Add support for beacon guardrails

[yunzheng]

This adds support for dumping guardrails protected beacons.

fixes #72

[Copilot]

Pull Request Overview

This PR adds support for handling Beacon configurations protected with Guardrails by enhancing the parsing logic and adding new tests. Key changes include:

• Introducing a new Guardrails module for unmasking and parsing Guardrails configurations.
• Updating BeaconConfig to support guardrails extraction and modifying the CLI accordingly.
• Adding new test cases to verify guardrails-related functionality.

Reviewed Changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_guardrails.py	Adds tests to verify guardrails start bytes and metadata extraction.
tests/test_beacon.py	Adds tests for dumping beacons using multiple files and default xor keys.
dissect/cobaltstrike/guardrails.py	Introduces a new module for parsing Beacon Guardrails configuration.
dissect/cobaltstrike/utils.py	Adds a helper function for grouping items from an iterable.
dissect/cobaltstrike/beacon.py	Updates BeaconConfig to detect and process guardrails configurations and refines CLI arguments.
tests/conftest.py	Adds a fixture for a guardrails protected beacon.
dissect/cobaltstrike/version.py	Updates version mappings with additional keys for newer versions.

Files not reviewed (1)

• tests/beacons/README.rst: Language not supported

Comments suppressed due to low confidence (1)

dissect/cobaltstrike/guardrails.py:113

• [nitpick] Reassigning the variable 'fh'—which represents the input file handle—can be confusing; consider using a new variable name for the buffered reader to improve clarity.

fh = io.BufferedReader(io.BytesIO(unmasked_guard_config))

[codecov]

Codecov Report

Attention: Patch coverage is 97.60479% with 4 lines in your changes missing coverage. Please review.

Project coverage is 76.40%. Comparing base (a532957) to head (24508aa).
Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
dissect/cobaltstrike/guardrails.py	97.22%	3 Missing ⚠️
dissect/cobaltstrike/beacon.py	98.18%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #73      +/-   ##
==========================================
+ Coverage   75.08%   76.40%   +1.31%     
==========================================
  Files          11       12       +1     
  Lines        2597     2729     +132     
==========================================
+ Hits         1950     2085     +135     
+ Misses        647      644       -3     

Flag	Coverage Δ
unittests	76.40% <97.60%> (+1.31%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull Request Overview

This PR adds support for dumping Beacon configurations protected by Guardrails and enhances the beacon-dump functionality with additional test coverage and command‐line options. Key changes include:

• Addition of new tests for guardrails support and multiple-file dumping in tests.
• Implementation of Guardrails parsing logic in a new module and integration within BeaconConfig.
• Updates to argument parsing, version mapping, and utility functions to accommodate the new functionality.

Reviewed Changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/test_guardrails.py	New tests verifying guardrails start bytes and configuration recovery.
tests/test_beacon.py	New tests for multiple file dumps and default XOR keys handling.
dissect/cobaltstrike/guardrails.py	New module implementing guardrails config parsing and recovery.
dissect/cobaltstrike/beacon.py	Updated to integrate guardrails support into BeaconConfig and CLI.
dissect/cobaltstrike/utils.py	Added definition for grouper to support guardrails module usage.
tests/conftest.py	Added a new fixture for guardrails beacon data.
dissect/cobaltstrike/version.py	Extended version mapping with additional timestamp entries.

Files not reviewed (1)

• tests/beacons/README.rst: Language not supported

Comments suppressed due to low confidence (1)

tests/test_guardrails.py:25

• [nitpick] The parameter 'type' shadows a Python built-in which could lead to unintended issues; consider renaming it (e.g., to 'settings_type').

def test_guard_config_start_settings(guard_option, type, length) -> None:

[Copilot]

Pull Request Overview

This pull request adds support for dumping beacon configurations protected by guardrails, addressing issue #72. Key changes include:

• Addition of new unit tests for guardrails in tests/test_guardrails.py and tests/test_beacon.py.
• Introduction of a new module (dissect/cobaltstrike/guardrails.py) to handle guardrails metadata extraction and unmasking.
• Updates to the BeaconConfig file and argument parser in dissect/cobaltstrike/beacon.py to incorporate guardrails and related key options.

Reviewed Changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tests/test_guardrails.py	New tests validating guardrail configuration characteristics.
dissect/cobaltstrike/guardrails.py	New module defining guardrail structures and processing logic.
tests/test_beacon.py	Added tests to verify beacon dump behavior with multiple files and xor keys.
dissect/cobaltstrike/beacon.py	Adjusted BeaconConfig and CLI parsing to support guardrails.
dissect/cobaltstrike/utils.py	Moved the grouper utility to a common location for consistency.
tests/conftest.py	Extended fixtures to include a benchmark guardrails beacon.
dissect/cobaltstrike/version.py	Updated version mapping with additional entries.

Files not reviewed (1)

• tests/beacons/README.rst: Language not supported

Comments suppressed due to low confidence (2)

dissect/cobaltstrike/beacon.py:811

• [nitpick] The variable name 'fxor' is ambiguous; consider renaming it to something more descriptive (e.g. 'decoded_fobj') to improve code clarity.

fxor = XorEncodedFile.from_file(fobj)

dissect/cobaltstrike/utils.py:286

• [nitpick] The 'grouper' function is reintroduced here; verify that its implementation is consistent with its usage across the codebase to avoid unexpected behavior.

def grouper(iterable, n, fillvalue=None):