dissect.cobaltstrike.guardrails
===============================

.. py:module:: dissect.cobaltstrike.guardrails

.. autoapi-nested-parse::

   This module is responsible for finding and recovering Beacon Guardrails configuration from Cobalt Strike payloads.
   Guardrails is an additional layer of protection to the beacon config by using environmental keying (`T1480`_).

   .. note::
       Beacon Guardrails was introduced in Cobalt Strike 4.8:

       - https://www.cobaltstrike.com/blog/cobalt-strike-4-8-system-call-me-maybe

       Other research on Beacon Guardrails:

       - https://itea.org/journals/volume-45-3/cobalt-strike-cyber-assessment-challenge/

       .. _T1480: https://attack.mitre.org/techniques/T1480/



Attributes
----------

.. autoapisummary::

   dissect.cobaltstrike.guardrails.log
   dissect.cobaltstrike.guardrails.C_GUARDRAILS_DEF
   dissect.cobaltstrike.guardrails.BEACON_CONFIG_PATCH_SIZE
   dissect.cobaltstrike.guardrails.GUARD_PATCH_SIZE
   dissect.cobaltstrike.guardrails.GUARD_CONFIG_STARTS
   dissect.cobaltstrike.guardrails.c_guardrails
   dissect.cobaltstrike.guardrails.GuardrailSetting
   dissect.cobaltstrike.guardrails.GuardOption


Classes
-------

.. autoapisummary::

   dissect.cobaltstrike.guardrails.GuardrailMetadata


Functions
---------

.. autoapisummary::

   dissect.cobaltstrike.guardrails.iter_guardrail_configs
   dissect.cobaltstrike.guardrails.find_xor_key_candidates
   dissect.cobaltstrike.guardrails.payload_checksum
   dissect.cobaltstrike.guardrails.iter_guardrail_configs_with_beacon


Module Contents
---------------

.. py:data:: log

.. py:data:: C_GUARDRAILS_DEF
   :value: Multiline-String

   .. raw:: html

      <details><summary>Show Value</summary>

   .. code-block:: python

      """
      enum GuardOption: uint16 {
          GUARD_USER = 5,
          GUARD_COMPUTER = 6,
          GUARD_DOMAIN = 7,
          GUARD_LOCAL_IP = 8,
          GUARD_PAYLOAD_CHECKSUM = 9,
      };
      
      enum SettingsType: uint16 {
          TYPE_NONE = 0,
          TYPE_SHORT = 1,
          TYPE_INT = 2,
          TYPE_PTR = 3,
      };
      
      struct GuardrailSetting {
          GuardOption option;         // uint16
          SettingsType type;          // uint16
          uint16 length;              // uint16
          char value[length];
      };
      """

   .. raw:: html

      </details>



.. py:data:: BEACON_CONFIG_PATCH_SIZE
   :value: 6144


.. py:data:: GUARD_PATCH_SIZE
   :value: 2048


.. py:data:: GUARD_CONFIG_STARTS
   :value: [b'\x00\x05\x00\x01\x00\x02', b'\x00\x06\x00\x01\x00\x02', b'\x00\x07\x00\x01\x00\x02',...


.. py:data:: c_guardrails

.. py:data:: GuardrailSetting

.. py:data:: GuardOption

.. py:class:: GuardrailMetadata

   Class for holding Guardrail related data


   .. py:attribute:: beacon_config_offset
      :type:  int

      Offset of the beacon configuration in the payload


   .. py:attribute:: guard_config_offset
      :type:  int

      Offset of the guardrail configuration in the payload


   .. py:attribute:: masked_beacon_config
      :type:  bytes

      Masked raw beacon configuration


   .. py:attribute:: masked_guard_config
      :type:  bytes

      Masked raw guardrail configuration


   .. py:attribute:: beacon_xor_key
      :type:  bytes

      Single byte XOR key used to mask the beacon configuration. (0x2e by default unless modified beacon)


   .. py:attribute:: guardrail_xor_key
      :type:  bytes

      Single byte XOR key used to unmask the guardrail configuration (0x8a by default unless modified beacon)


   .. py:attribute:: unmasked_guard_config
      :type:  bytes

      Unmasked guardrail configuration


   .. py:attribute:: checksum
      :type:  int

      Extracted payload checksum from guardrail configuration. This is used to validate the beacon configuration


   .. py:attribute:: payload_xor_key
      :type:  bytes | None

      XOR key used to unmask the guarded beacon configuration. This is the environmental key


   .. py:attribute:: unmasked_beacon_config
      :type:  bytes

      Unmasked beacon configuration


   .. py:attribute:: settings
      :type:  list[GuardrailSetting]

      List of guardrail settings


.. py:function:: iter_guardrail_configs(fh: BinaryIO, xorkey: bytes = b'\x8a') -> collections.abc.Iterator[GuardrailMetadata]

.. py:function:: find_xor_key_candidates(fh: BinaryIO) -> collections.abc.Iterator[bytes]

.. py:function:: payload_checksum(data: bytes) -> int

.. py:function:: iter_guardrail_configs_with_beacon(fh: BinaryIO) -> collections.abc.Iterator[GuardrailMetadata]