Dissect.cobaltstrike

This v1.2.1 release mainly brings support for dumping beacons protected with [guardrails](https://www.cobaltstrike.com/blog/cobalt-strike-4-8-system-call-me-maybe). It can automatically deduce the environmental key and decrypt the protected beacon config. Example:

shell
$ 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](https://dissect-cobaltstrike.readthedocs.io/en/latest/beacon-version-identification.html) for reference.

What's Changed
* Fix BeaconSetting names with unknown values by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/64
* Speed up beacon file reading from zip files in tests by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/65
* Add version detection for Cobalt Strike 4.9 and 4.10 by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/66
* Output bof_reuse_memory and bof_allocator in c2profile by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/67
* Add support for SETTING_DATA_STORE_SIZE and SETTING_BEACON_GATE options by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/68
* Update pip install docs with quoting when installing extras by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/69
* More pip install quotations in the docs by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/70
* Add support for SETTING_HTTP_DATA_REQUIRED beacon setting by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/71
* Add support for beacon guardrails by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/73
* Fix failing readthedocs builds by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/74
* Add guardrails definitions to the docs by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/75
* Add Cobalt Strike 4.10.1 version detection by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/76
* Add beacon version table to documentation by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/77


**Full Changelog**: https://github.com/fox-it/dissect.cobaltstrike/compare/v1.2.0...v1.2.1

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:

shell
$ pip install --pre dissect.cobaltstrike


What's Changed
* Pin sphinx_rtd_theme>=2.0 to fix readthedocs by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/57
* Update minimal Python requirement to 3.9 by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/58
* Compatibility with cstruct v4 by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/56
* Update GitHub Actions to use latest versions by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/59
* Update pre-commit checks to latest versions by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/60
* Migrate setuptools to full pyproject.toml only by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/61
* Switch GitHub workflow to dissect-ci.yml by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/62


**Full Changelog**: https://github.com/fox-it/dissect.cobaltstrike/compare/v1.1.0...v1.2.0

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

New Contributors
* drb-ra made their first contribution in https://github.com/fox-it/dissect.cobaltstrike/pull/48

**Full Changelog**: https://github.com/fox-it/dissect.cobaltstrike/compare/v1.0.0...v1.1.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](https://dissect-cobaltstrike.readthedocs.io/en/latest/tutorials/minimal_beacon_client.html)
* [Decrypt Cobalt Strike PCAPs](https://dissect-cobaltstrike.readthedocs.io/en/latest/tutorials/decrypt_cobaltstrike_pcaps.html)

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 https://github.com/fox-it/dissect.cobaltstrike/pull/22 https://github.com/fox-it/dissect.cobaltstrike/pull/25
* Add `netbios_encode` and `netbios_decode` functions to utils.py https://github.com/fox-it/dissect.cobaltstrike/pull/23
* Add PE export stamps for Cobalt Strike 4.7 and 4.7.1 https://github.com/fox-it/dissect.cobaltstrike/pull/24
* Add support for beacon client and decrypting traffic from PCAP files https://github.com/fox-it/dissect.cobaltstrike/pull/25
* Move `scripts/artifact.py` to it's own `beacon-artifact` CLI tool https://github.com/fox-it/dissect.cobaltstrike/pull/37
* Removed support for Python 3.6 (mainly due to some dependencies not supporting it anymore) https://github.com/fox-it/dissect.cobaltstrike/pull/30
* Introduced new pip `extras` flavours to `setup.py` https://github.com/fox-it/dissect.cobaltstrike/pull/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 https://github.com/fox-it/dissect.cobaltstrike/pull/39
* Get rid of `docs/requirements.txt` and use pip method for building readthedocs https://github.com/fox-it/dissect.cobaltstrike/pull/28 https://github.com/fox-it/dissect.cobaltstrike/pull/29
* Added tutorials:
* [Minimal Beacon Client](https://dissect-cobaltstrike.readthedocs.io/en/latest/tutorials/minimal_beacon_client.html)
* [Decrypt Cobalt Strike PCAPs](https://dissect-cobaltstrike.readthedocs.io/en/latest/tutorials/decrypt_cobaltstrike_pcaps.html)
* Added `scripts/*.py` to it's own [scripts](https://dissect-cobaltstrike.readthedocs.io/en/latest/scripts/index.html) section in documentation.
* Added new CLI tool documentation:
* [`beacon-artifact`](https://dissect-cobaltstrike.readthedocs.io/en/latest/tools/beacon-artifact.html) for dumping beacons created with ArtifactKit
* [`beacon-client`](https://dissect-cobaltstrike.readthedocs.io/en/latest/tools/beacon-client.html) for connecting to a Cobalt Strike Team Server as a beacon client
* [`beacon-pcap`](https://dissect-cobaltstrike.readthedocs.io/en/latest/tools/beacon-pcap.html) for parsing and decrypting Cobalt Strike C2 traffic in PCAP files

**Full Changelog**: https://github.com/fox-it/dissect.cobaltstrike/compare/v0.2.2...v1.0.0

What's Changed
* Added pe_export_stamp for CS 4.6 DNS Beacon by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/16
* Fixed missing DNS beacon settings in c2profile output (17) by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/18
* Add task_* c2profile settings that were introduced in Cobalt Strike 4.6 by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/20
* Add Cobalt Strike 4.7 settings and version info by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/19
* Add retain_file_offset helper to utils.py by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/21


**Full Changelog**: https://github.com/fox-it/dissect.cobaltstrike/compare/v0.2.1...v0.2.2

What's Changed
* Add PE export timestamps for Cobalt Strike 4.6 by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/13
* Fix small typo in docs by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/14
* Add u64, p64, u64be and p64be packing aliases by yunzheng in https://github.com/fox-it/dissect.cobaltstrike/pull/15


**Full Changelog**: https://github.com/fox-it/dissect.cobaltstrike/compare/v0.2.0...v0.2.1