# DC3-Kordesii
[Changelog](CHANGELOG.md) | [Releases](https://github.com/Defense-Cyber-Crime-Center/kordesii/releases)
DC3-Kordesii is a framework for decoding encoded strings and files in malware via IDA Pro IDAPython scripting.
One parser module is usually created per malware family.
It is designed to ease the burden of encoded string extraction by doing it in an automated,
static way as well as to provide a standard set of functionality and methodologies.
It supports both an analyst directed analysis and large-scale automated executing,
utilizing either the REST API, the CLI or by manually running decoders in IDA.
DC3-Kordesii is authored by the Department of Defense Cyber Crime Center (DC3).
- [Install](#install)
- [Usage](#usage)
- [CLI Tool](#cli-tool)
- [REST API](#rest-api)
- [Logging](#logging)
- [CPU Emulation](#cpu-emulation)
- [IDA Proxy](#ida-proxy)
### Guides
- [CPU Emulation](docs/CPUEmulation.md)
- [Decoder Development](docs/DecoderDevelopment.md)
- [Decoder Installation](docs/DecoderInstallation.md)
- [Decoder Testing](docs/DecoderTesting.md)
## Dependencies
DC3-Kordesii requires the following:
- Python 3.7+ (64 bit)
- IDA Pro 7.* (tested and developed with 7.4)
- *(optional)* Hex Ray's Decompiler for x86/x64 architectures
- (Used to improve accuracy of getting function arguments in `function_tracing`)
## Install
```console
> pip install kordesii
```
Alternatively you can clone this repo and install locally.
```console
> git clone https://github.com/Defense-Cyber-Crime-Center/kordesii.git
> pip install ./kordesii
```
For a development mode use the `-e` flag to install in editable mode:
```console
> git clone https://github.com/Defense-Cyber-Crime-Center/kordesii.git
> pip install -e ./kordesii
```
### Setup IDA location
By default kordesii assumes you are on Windows and have installed IDA under the default location `C:/Program Files/IDA Pro *`.
If you have installed IDA at a different location or running on another operating system, please set the `IDA_DIR` environment
to point to where IDA has been installed.
## Usage
DC3-Kordesii is designed to standardize automation of a task typically done by one-off scripts.
Most automated processing systems will use a condition, such as a YARA signature match,
to trigger execution of a particular DC3-Kordesii decoder.
There are 2 options for integration of DC3-Kordesii:
- CLI: `kordesii`
- REST API: ```kordesii serve```
### CLI tool
The `kordesii` tool provides functionality to run and test decoders on files:
```console
> kordesii parse Sample ./kordesii/decoders/tests/strings.exe
[+] (kordesii): Parsing: ./kordesii/decoders/tests/strings.exe
[+] (kordesii.core): IDA return code = 0
----Decoded Strings----
Hello World!
Test string with key 0x02
The quick brown fox jumps over the lazy dog.
Oak is strong and also gives shade.
Acid burns holes in wool cloth.
Cats and dogs each hate the other.
Open the crate but don't break the glass.
There the flood mark is ten inches.
1234567890
CreateProcessA
StrCat
ASP.NET
kdjsfjf0j24r0j240r2j09j222
32897412389471982470
The past will look brighter tomorrow.
Cars and busses stalled in sand drifts.
The jacket hung on the back of the wide chair.
32908741328907498134712304814879837483274809123748913251236598123056231895712
----Debug----
[+] IDA return code = 0
> kordesii test Sample
Running test cases. May take a while...
1/1 - kordesii:Sample strings.exe 8.9183s
Test stats:
Top 10 Slowest Test Cases:
1. kordesii:Sample strings.exe 8.9183s
Top 10 Fastest Test Cases:
1. kordesii:Sample strings.exe 8.9183s
Mean Running Time: 8.9183s
Median Running Time: 8.9183s
Cumulative Running Time: 0:00:08.918259
Total Running Time: 0:00:09.480942
All Passed = True
```
see ```kordesii -h``` for full set of options
### REST API
The REST API provides two commonly used functions:
* ```/run_decoder/<decoder>``` -- executes a decoder on uploaded file
* ```/descriptions``` -- provides list of available parsers
To use, first start the server by running:
```console
> kordesii serve
```
The following curl commands demonstrate how to use this web service:
```console
> curl --form data=@README.md http://localhost:8080/run_decoder/foo
> curl http://localhost:8080/descriptions
```
A simple HTML interface is also available at the same address.
Individual samples can be submitted and results
saved as JSON, plain text, or ZIP archives.
## Logging
DC3-Kordesii uses Python's builtin in `logging` module to log all messages.
By default, logging is configured using the [log_config.yml](kordesii/config/log_config.yml) configuration
file. Which is currently set to log all messages to the console and error messages to `%LOCALAPPDATA%/kordesii/errors.log`.
You can provide your own custom log configuration file by adding the path
to the environment variable `KORDESII_LOG_CFG`. (Please see [Python's documentation](http://docs.python.org/dev/library/logging.config.html) for more information on how to write your own configuration file.)
You may also use the `--verbose` or `--debug` flags to adjust the logging level when using the `kordesii` tool.
## CPU Emulation
DC3-Kordesii includes an experimental tracing utility called `function_tracing` that can be used to statically emulate
and trace instructions within a function.
Please see the [CPU Emulation](docs/CPUEmulation.md) documentation for more information.
Raw data
{
"_id": null,
"home_page": "https://github.com/Defense-Cyber-Crime-Center/kordesii",
"name": "kordesii",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "malware,ida,idapro",
"author": "DC3",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/fa/38/7ce388fc3e9ebe5fcb01dafc21ff41f540bc25f640ef73158ca9349049cf/kordesii-2.5.2.tar.gz",
"platform": null,
"description": "# DC3-Kordesii\n[Changelog](CHANGELOG.md) | [Releases](https://github.com/Defense-Cyber-Crime-Center/kordesii/releases)\n\nDC3-Kordesii is a framework for decoding encoded strings and files in malware via IDA Pro IDAPython scripting. \nOne parser module is usually created per malware family. \nIt is designed to ease the burden of encoded string extraction by doing it in an automated, \nstatic way as well as to provide a standard set of functionality and methodologies. \nIt supports both an analyst directed analysis and large-scale automated executing, \nutilizing either the REST API, the CLI or by manually running decoders in IDA. \n\nDC3-Kordesii is authored by the Department of Defense Cyber Crime Center (DC3).\n\n- [Install](#install)\n- [Usage](#usage)\n - [CLI Tool](#cli-tool)\n - [REST API](#rest-api)\n- [Logging](#logging)\n- [CPU Emulation](#cpu-emulation)\n- [IDA Proxy](#ida-proxy)\n\n### Guides\n- [CPU Emulation](docs/CPUEmulation.md)\n- [Decoder Development](docs/DecoderDevelopment.md)\n- [Decoder Installation](docs/DecoderInstallation.md)\n- [Decoder Testing](docs/DecoderTesting.md)\n\n## Dependencies\nDC3-Kordesii requires the following:\n- Python 3.7+ (64 bit)\n- IDA Pro 7.* (tested and developed with 7.4)\n- *(optional)* Hex Ray's Decompiler for x86/x64 architectures\n - (Used to improve accuracy of getting function arguments in `function_tracing`)\n\n## Install\n```console\n> pip install kordesii\n```\n\nAlternatively you can clone this repo and install locally.\n```console\n> git clone https://github.com/Defense-Cyber-Crime-Center/kordesii.git\n> pip install ./kordesii\n```\n\nFor a development mode use the `-e` flag to install in editable mode:\n\n```console\n> git clone https://github.com/Defense-Cyber-Crime-Center/kordesii.git\n> pip install -e ./kordesii\n```\n\n### Setup IDA location\n\nBy default kordesii assumes you are on Windows and have installed IDA under the default location `C:/Program Files/IDA Pro *`.\nIf you have installed IDA at a different location or running on another operating system, please set the `IDA_DIR` environment\nto point to where IDA has been installed.\n\n## Usage\n\nDC3-Kordesii is designed to standardize automation of a task typically done by one-off scripts.\nMost automated processing systems will use a condition, such as a YARA signature match, \nto trigger execution of a particular DC3-Kordesii decoder.\n\nThere are 2 options for integration of DC3-Kordesii:\n- CLI: `kordesii`\n- REST API: ```kordesii serve```\n\n### CLI tool\n\nThe `kordesii` tool provides functionality to run and test decoders on files:\n\n```console\n> kordesii parse Sample ./kordesii/decoders/tests/strings.exe\n[+] (kordesii): Parsing: ./kordesii/decoders/tests/strings.exe\n[+] (kordesii.core): IDA return code = 0\n----Decoded Strings----\n\nHello World!\nTest string with key 0x02\nThe quick brown fox jumps over the lazy dog.\nOak is strong and also gives shade.\nAcid burns holes in wool cloth.\nCats and dogs each hate the other.\nOpen the crate but don't break the glass.\nThere the flood mark is ten inches.\n1234567890\nCreateProcessA\nStrCat\nASP.NET\nkdjsfjf0j24r0j240r2j09j222\n32897412389471982470\nThe past will look brighter tomorrow.\nCars and busses stalled in sand drifts.\nThe jacket hung on the back of the wide chair.\n32908741328907498134712304814879837483274809123748913251236598123056231895712\n\n----Debug----\n\n[+] IDA return code = 0\n\n> kordesii test Sample\nRunning test cases. May take a while...\n 1/1 - kordesii:Sample strings.exe 8.9183s\n\nTest stats:\n\nTop 10 Slowest Test Cases:\n 1. kordesii:Sample strings.exe 8.9183s\n\nTop 10 Fastest Test Cases:\n 1. kordesii:Sample strings.exe 8.9183s\n\nMean Running Time: 8.9183s\nMedian Running Time: 8.9183s\nCumulative Running Time: 0:00:08.918259\n\nTotal Running Time: 0:00:09.480942\nAll Passed = True\n```\n\nsee ```kordesii -h``` for full set of options\n\n### REST API\n\nThe REST API provides two commonly used functions:\n\n* ```/run_decoder/<decoder>``` -- executes a decoder on uploaded file\n* ```/descriptions``` -- provides list of available parsers\n\nTo use, first start the server by running:\n```console\n> kordesii serve\n```\n\nThe following curl commands demonstrate how to use this web service:\n```console\n> curl --form data=@README.md http://localhost:8080/run_decoder/foo\n> curl http://localhost:8080/descriptions\n```\n\nA simple HTML interface is also available at the same address.\nIndividual samples can be submitted and results\nsaved as JSON, plain text, or ZIP archives.\n\n## Logging\nDC3-Kordesii uses Python's builtin in `logging` module to log all messages.\nBy default, logging is configured using the [log_config.yml](kordesii/config/log_config.yml) configuration\nfile. Which is currently set to log all messages to the console and error messages to `%LOCALAPPDATA%/kordesii/errors.log`. \nYou can provide your own custom log configuration file by adding the path\nto the environment variable `KORDESII_LOG_CFG`. (Please see [Python's documentation](http://docs.python.org/dev/library/logging.config.html) for more information on how to write your own configuration file.)\n\nYou may also use the `--verbose` or `--debug` flags to adjust the logging level when using the `kordesii` tool.\n\n\n## CPU Emulation\nDC3-Kordesii includes an experimental tracing utility called `function_tracing` that can be used to statically emulate\nand trace instructions within a function.\n\nPlease see the [CPU Emulation](docs/CPUEmulation.md) documentation for more information.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A framework for decoding encoded strings and files in malware via IDA Pro IDAPython scripting.",
"version": "2.5.2",
"split_keywords": [
"malware",
"ida",
"idapro"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e149b5d3d8ecd991be07110fa3943536d2a0b711b50c80a2b2a9faafdc1b6534",
"md5": "3d25e6a5c43a45e65f9c861116ddbc3e",
"sha256": "4f3eb55a7e27d30a304629b5af245ee8e31b99f61abb98f3f7aebac322f371aa"
},
"downloads": -1,
"filename": "kordesii-2.5.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3d25e6a5c43a45e65f9c861116ddbc3e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 261444,
"upload_time": "2023-02-03T02:28:36",
"upload_time_iso_8601": "2023-02-03T02:28:36.771836Z",
"url": "https://files.pythonhosted.org/packages/e1/49/b5d3d8ecd991be07110fa3943536d2a0b711b50c80a2b2a9faafdc1b6534/kordesii-2.5.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fa387ce388fc3e9ebe5fcb01dafc21ff41f540bc25f640ef73158ca9349049cf",
"md5": "b7f6956146ccb60bf419de9c253dcdb8",
"sha256": "801b878f35cecb34db2df2c6f18d2e7732ee838933ad2c3e1fb58133c6c6bff8"
},
"downloads": -1,
"filename": "kordesii-2.5.2.tar.gz",
"has_sig": false,
"md5_digest": "b7f6956146ccb60bf419de9c253dcdb8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 240366,
"upload_time": "2023-02-03T02:28:38",
"upload_time_iso_8601": "2023-02-03T02:28:38.157963Z",
"url": "https://files.pythonhosted.org/packages/fa/38/7ce388fc3e9ebe5fcb01dafc21ff41f540bc25f640ef73158ca9349049cf/kordesii-2.5.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-03 02:28:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "Defense-Cyber-Crime-Center",
"github_project": "kordesii",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "kordesii"
}
JSON
