Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/strozfriedberg/cobaltstrike-config-extractor

Cobalt Strike Beacon configuration extractor and parser.
https://github.com/strozfriedberg/cobaltstrike-config-extractor

Last synced: about 2 months ago
JSON representation

Cobalt Strike Beacon configuration extractor and parser.

Awesome Lists containing this project

README 

        
#################################################

Cobalt Strike Configuration Extractor and Parser

#################################################



Overview

=========



Pure Python library and set of scripts to extract and parse configurations (configs) from `Cobalt Strike Beacons `_.

The library, ``libcsce``, contains classes for building tools to work with Beacon configs.

There are also two CLI scripts included that use the library to parse Beacon config data:



1. ``csce``: Parses all known Beacon config settings to JSON,

   mimicing the `Malleable C2 profile `_ structure.

2. ``list-cs-settings``: Attempts to find by brute-force the associated Cobalt Strike version, and all settings/their types, of a Beacon config.

   This script is useful for conducting research on Beacon samples.



Installation

=============



Install from Pypi (preferred method)

-------------------------------------



.. code-block:: bash



   > pip install libcsce



Install from GitHub with Pip

-----------------------------



.. code-block:: bash



    > pip install git+ssh://[email protected]/strozfriedberg/cobaltstrike-config-extractor.git#egg=libcsce



Install from Cloned Repo

-------------------------



.. code-block:: bash



    > git clone ssh://[email protected]/strozfriedberg/cobaltstrike-config-extractor.git

    > cd libcsce

    > pip install .



Dependencies

=============



The only external non-development dependency is `pefile `_,

which is required to decrypt Beacon configs from the ``.data`` section of PE files.

Requires **Python 3.6+**.



Development dependencies include those specified in ``pyproject.toml`` as well as:



- `Poetry `_

- `Make `_



Getting Started

================



csce

-----



Both of the CLI scripts support extracting Beacon configs from PE files (DLLs/EXEs) and memory dumps where a Beacon was running.

To parse a Beacon PE file to JSON, use ``csce``:



.. code-block:: bash



    > csce --pretty 



By default, the script will try to parse the Beacon as version ``3`` and, if that fails, try version ``4``.

You can specify a version manually via the ``-v`` flag to save cycles if you know the Beacon is version ``4``

(using ``-v 3`` doesn't technically save cycles because the script tries that version first by default).



list-cs-settings

-----------------



To discover new settings and while conducting research, sometimes it's useful to extract all possible settings and their types from a Beacon sample.

Use ``list-cs-settings`` to detect by brute-force the Cobalt Strike version and all settings/types:



.. code-block:: bash



    > list-cs-settings 



This script produces JSON where the top-level key is the Cobalt Strike version number,

which points to a mapping from setting number to information about that setting, including:



1. length (in bytes)

2. offset from the beginning of the config section

3. fundamental type (short, int, str)



Contributing

==============



Stroz Friedberg wants to work with the security community to make these open source tools the most comprehensive

available for working with Cobalt Strike Beacons. If you encounter a bug, have research to share on Beacons,

spot a typo in the documentation, want to request new functionality, etc. please submit an issue! If you want to contribute code

or documentation to the project, please submit a PR and we will review it!

Note that all contributions will be subject to the `Apache-2.0 license `_ included in the repo.