v1.2.1

This v1.2.1 release mainly brings support for dumping beacons protected with guardrails. It can automatically deduce the environmental key and decrypt the protected beacon config. Example:

$ beacon-dump -v 124552cf674b362e0c916ab79b9e7a56.bin
2025-03-25 15:17:14,318 INFO root: Processing: '124552cf674b362e0c916ab79b9e7a56.bin'
2025-03-25 15:17:14,869 INFO dissect.cobaltstrike.guardrails: Found guardrail config at offset: 320138 in <_io.BufferedReader name='124552cf674b362e0c916ab79b9e7a56.bin'>
2025-03-25 15:17:14,893 INFO dissect.cobaltstrike.guardrails: Found guardrail payload xorkey: b'desktop-r4vgq8o'
...
--------------------------------------------------
pe_export_stamp = 1720799264, 0x66915020, Fri Jul 12 17:47:44 2024 - Cobalt Strike 4.10 (Jul 16, 2024)
pe_compile_stamp = 1720799264, 0x66915020, Fri Jul 12 17:47:44 2024
max_setting_enum = 78 - BeaconSetting.SETTING_BEACON_GATE
beacon_version = Cobalt Strike 4.10 (Jul 16, 2024)
guardrail payload xor key = b'desktop-r4vgq8o'
guardrail options = [<GuardOption.GUARD_COMPUTER: 6>, <GuardOption.GUARD_PAYLOAD_CHECKSUM: 9>]

Also, some small quality of life changes were made to beacon-dump:

• You can now specify more than one beacon file to dump, useful for shell globbing, e.g.: beacon-dump -v beacons/*.bin
• It will now try all single byte XOR keys by default, this deprecates the --all flag and introduces --default-xor-keys-only.

Furthermore, the beacon version identification support is now up to Cobalt Strike v4.10.1 and the identification table can now also be found in the documentation for reference.

What's Changed

• Fix BeaconSetting names with unknown values by @yunzheng in #64
• Speed up beacon file reading from zip files in tests by @yunzheng in #65
• Add version detection for Cobalt Strike 4.9 and 4.10 by @yunzheng in #66
• Output bof_reuse_memory and bof_allocator in c2profile by @yunzheng in #67
• Add support for SETTING_DATA_STORE_SIZE and SETTING_BEACON_GATE options by @yunzheng in #68
• Update pip install docs with quoting when installing extras by @yunzheng in #69
• More pip install quotations in the docs by @yunzheng in #70
• Add support for SETTING_HTTP_DATA_REQUIRED beacon setting by @yunzheng in #71
• Add support for beacon guardrails by @yunzheng in #73
• Fix failing readthedocs builds by @yunzheng in #74
• Add guardrails definitions to the docs by @yunzheng in #75
• Add Cobalt Strike 4.10.1 version detection by @yunzheng in #76
• Add beacon version table to documentation by @yunzheng in #77

Full Changelog: v1.2.0...v1.2.1

v1.2.0

This release mainly fixes the compatibility with dissect.cstruct v4 and drops support for EOL Python versions going forward, the minimal requirement is now Python 3.9.

Python packages are now also automatically uploaded to pypi.org, including the dev packages from the main branch.
This means you can now install the latest development version using the --pre flag:

$ pip install --pre dissect.cobaltstrike

What's Changed

• Pin sphinx_rtd_theme>=2.0 to fix readthedocs by @yunzheng in #57
• Update minimal Python requirement to 3.9 by @yunzheng in #58
• Compatibility with cstruct v4 by @yunzheng in #56
• Update GitHub Actions to use latest versions by @yunzheng in #59
• Update pre-commit checks to latest versions by @yunzheng in #60
• Migrate setuptools to full pyproject.toml only by @yunzheng in #61
• Switch GitHub workflow to dissect-ci.yml by @yunzheng in #62

Full Changelog: v1.1.0...v1.2.0

v1.1.0

What's Changed

• Add codespell to .pre-commit-config.yaml and fixed typos by @yunzheng in #41
• Update git repo for flake8 by @yunzheng in #43
• Add Cobalt Strike 4.8 version detection by @yunzheng in #44
• Decode SETTING_DOMAINS using latin-1 instead of ascii codec by @yunzheng in #45
• Print beacon version information when running beacon-dump -v by @yunzheng in #46
• Improve support for Cobalt Strike v4.7 and v4.8 by @yunzheng in #47
• Updates to C2 and Client Code to better handle certain beacon configs by @drb-ra in #48
• Speed up finding non standard beacon XOR keys by @yunzheng in #49
• Switch to ruff linter by @yunzheng in #50
• Fix tox -e build by pinning Python version by @yunzheng in #51
• Pin dissect.cstruct < 4.0 for now by @yunzheng in #54

New Contributors

• @drb-ra made their first contribution in #48

Full Changelog: v1.0.0...v1.1.0

v1.0.0

This release mainly introduces support for parsing and decrypting Cobalt Strike C2 traffic from PCAP files and also adds Beacon Client support which allows you to connect to a Cobalt Strike Team Server and receive tasks and send back data like a real Beacon.

See also these new tutorials on how to use it:

• Minimal Beacon Client
• Decrypt Cobalt Strike PCAPs

Many thanks to @sud0woodo for laying the groundwork for these features!

What's Changed

• Add new properties to BeaconConfig: public_key, port, jitter, sleeptime, submit_uri #22 #25
• Add netbios_encode and netbios_decode functions to utils.py #23
• Add PE export stamps for Cobalt Strike 4.7 and 4.7.1 #24
• Add support for beacon client and decrypting traffic from PCAP files #25
• Move scripts/artifact.py to it's own beacon-artifact CLI tool #37
• Removed support for Python 3.6 (mainly due to some dependencies not supporting it anymore) #30
• Introduced new pip extras flavours to setup.py #25
  • dissect.cobaltstrike[c2] - for if you want to communicate with Cobalt Strike Team Servers
  • dissect.cobaltstrike[pcap] - for if you want to parse and decrypt PCAPs containing Beacon traffic
  • dissect.cobaltstrike[full] - all of the above but also installs rich for prettier log output

Documentation

• Updated README.rst with screenshots and text for C2 and PCAP support #39
• Get rid of docs/requirements.txt and use pip method for building readthedocs #28 #29
• Added tutorials:
  • Minimal Beacon Client
  • Decrypt Cobalt Strike PCAPs
• Added scripts/*.py to it's own scripts section in documentation.
• Added new CLI tool documentation:
  • beacon-artifact for dumping beacons created with ArtifactKit
  • beacon-client for connecting to a Cobalt Strike Team Server as a beacon client
  • beacon-pcap for parsing and decrypting Cobalt Strike C2 traffic in PCAP files

Full Changelog: v0.2.2...v1.0.0

v0.2.2

What's Changed

• Added pe_export_stamp for CS 4.6 DNS Beacon by @yunzheng in #16
• Fixed missing DNS beacon settings in c2profile output (#17) by @yunzheng in #18
• Add task_* c2profile settings that were introduced in Cobalt Strike 4.6 by @yunzheng in #20
• Add Cobalt Strike 4.7 settings and version info by @yunzheng in #19
• Add retain_file_offset helper to utils.py by @yunzheng in #21

Full Changelog: v0.2.1...v0.2.2

v0.2.1

What's Changed

• Add PE export timestamps for Cobalt Strike 4.6 by @yunzheng in #13
• Fix small typo in docs by @yunzheng in #14
• Add u64, p64, u64be and p64be packing aliases by @yunzheng in #15

Full Changelog: v0.2.0...v0.2.1

v0.2.0

What's Changed

• Also run unit tests on pypy3 by @yunzheng in #1
• Unbreak black by updating it to 22.3.0 by @yunzheng in #3
• Fixed exception handling in @catch_sigpipe by @yunzheng in #2
• Add support for reading from stdin to beacon-dump by @yunzheng in #4
• Improved handling for empty or all zero xorkey buffer in utils.xor by @yunzheng in #5
• Refactor OSError exception handling in @catch_sigpipe decorator by @yunzheng in #7
• Apply black --check and --diff options via .pre-commit-config.yaml only by @yunzheng in #8
• Determine Sphinx docs version from dissect.cobaltstrike._version by @yunzheng in #6
• Add process exit code to beacon-dump by @yunzheng in #9
• Refactor pytest.raises statements to use match keyword by @yunzheng in #10
• Add tests for dissect.cobaltstrike.beacon main function by @yunzheng in #11
• Update README.rst by @yunzheng in #12

New Contributors

• @yunzheng made their first contribution in #1

Full Changelog: v0.1.0...v0.2.0

v0.1.0

Initial Release