dissect.cobaltstrike 1.2.1.dev5__tar.gz → 1.2.1.dev7__tar.gz

{dissect_cobaltstrike-1.2.1.dev5 → dissect_cobaltstrike-1.2.1.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: dissect.cobaltstrike
-Version: 1.2.1.dev5
+Version: 1.2.1.dev7
 Summary: a Python library for dissecting Cobalt Strike related data
 Project-URL: Homepage, https://github.com/fox-it/dissect.cobaltstrike
 Project-URL: Documentation, https://dissect-cobaltstrike.readthedocs.io/
@@ -93,7 +93,11 @@ The library is available on `PyPI <https://pypi.org/project/dissect.cobaltstrike
 
 Or install using the ``full`` extra to automatically install dependencies for C2 and PCAP support::
 
-   $ pip install dissect.cobaltstrike[full]
+   $ pip install 'dissect.cobaltstrike[full]'
+
+If you want to install the latest pre-release version, use the ``--pre`` flag::
+
+   $ pip install --pre dissect.cobaltstrike
 
 **dissect.cobaltstrike** requires Python 3.9 or later.
 

{dissect_cobaltstrike-1.2.1.dev5 → dissect_cobaltstrike-1.2.1.dev7}/README.rst

@@ -21,7 +21,11 @@ The library is available on `PyPI <https://pypi.org/project/dissect.cobaltstrike
 
 Or install using the ``full`` extra to automatically install dependencies for C2 and PCAP support::
 
-   $ pip install dissect.cobaltstrike[full]
+   $ pip install 'dissect.cobaltstrike[full]'
+
+If you want to install the latest pre-release version, use the ``--pre`` flag::
+
+   $ pip install --pre dissect.cobaltstrike
 
 **dissect.cobaltstrike** requires Python 3.9 or later.
 

{dissect_cobaltstrike-1.2.1.dev5 → dissect_cobaltstrike-1.2.1.dev7}/dissect/cobaltstrike/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.2.1.dev5'
-__version_tuple__ = version_tuple = (1, 2, 1, 'dev5')
+__version__ = version = '1.2.1.dev7'
+__version_tuple__ = version_tuple = (1, 2, 1, 'dev7')

{dissect_cobaltstrike-1.2.1.dev5 → dissect_cobaltstrike-1.2.1.dev7}/dissect/cobaltstrike/beacon.py

@@ -170,6 +170,12 @@ enum BeaconSetting: uint16 {
 
     // CobaltStrike version >= 4.7 (Aug 17, 2022)
     SETTING_MASKED_WATERMARK = 74,
+
+    // CobaltStrike version >= 4.9 (Sep 19, 2023)
+    SETTING_DATA_STORE_SIZE = 76,
+
+    // CobaltStrike version >= 4.10 (Jul 16, 2024)
+    SETTING_BEACON_GATE = 78,
 };
 
 enum DeprecatedBeaconSetting: uint16 {
@@ -253,6 +259,33 @@ enum BofAllocator: uint16 {
     MapViewOfFile = 1,
     HeapAlloc = 2,
 };
+
+// https://hstechdocs.helpsystems.com/manuals/cobaltstrike/current/userguide/content/topics/beacon-gate.htm
+struct BeaconGateOptions {
+    uint8 InternetOpenA;        // commms
+    uint8 InternetConnectA;
+    uint8 VirtualAlloc;         // core
+    uint8 VirtualAllocEx;
+    uint8 VirtualProtect;
+    uint8 VirtualProtectEx;
+    uint8 VirtualFree;
+    uint8 GetThreadContext;
+    uint8 SetThreadContext;
+    uint8 ResumeThread;
+    uint8 CreateThread;
+    uint8 CreateRemoteThread;
+    uint8 OpenProcess;
+    uint8 OpenThread;
+    uint8 CloseHandle;
+    uint8 CreateFileMappingA;
+    uint8 MapViewOfFile;
+    uint8 UnmapViewOfFile;
+    uint8 VirtualQuery;
+    uint8 DuplicateHandle;
+    uint8 ReadProcessMemory;
+    uint8 WriteProcessMemory;
+    uint8 ExitThread;           // cleanup
+};
 """
 
 cs_struct = cstruct.cstruct(endian=">")
@@ -269,6 +302,7 @@ ProxyServer = cs_struct.ProxyServer
 InjectAllocator = cs_struct.InjectAllocator
 InjectExecutor = cs_struct.InjectExecutor
 BofAllocator = cs_struct.BofAllocator
+BeaconGateOptions = cs_struct.BeaconGateOptions
 
 DEFAULT_XOR_KEYS: List[bytes] = [b"\x69", b"\x2e", b"\x00"]
 """ Default XOR keys used by Cobalt Strike for obfuscating Beacon config bytes """
@@ -581,6 +615,61 @@ def parse_pivot_frame(data: bytes) -> bytes:
     return p.read(length - 4)
 
 
+def parse_beacon_gate(data: bytes) -> BeaconGateOptions:
+    """Parse ``SETTING_BEACON_GATE`` (`.stage.beacon_gate`) data"""
+    return BeaconGateOptions(data)
+
+
+def beacon_gate_options_string(bgo: BeaconGateOptions) -> list[str]:
+    """Return the enabled BeaconGate WinAPI's as a list of strings"""
+    options = {k for k, v in bgo._values.items() if v}
+
+    comms = {"InternetOpenA", "InternetConnectA"}
+    core = {
+        "VirtualAlloc",
+        "VirtualAllocEx",
+        "VirtualProtect",
+        "VirtualProtectEx",
+        "VirtualFree",
+        "GetThreadContext",
+        "SetThreadContext",
+        "ResumeThread",
+        "CreateThread",
+        "CreateRemoteThread",
+        "OpenProcess",
+        "OpenThread",
+        "CloseHandle",
+        "CreateFileMappingA",
+        "MapViewOfFile",
+        "UnmapViewOfFile",
+        "VirtualQuery",
+        "DuplicateHandle",
+        "ReadProcessMemory",
+        "WriteProcessMemory",
+    }
+    cleanup = {"ExitThread"}
+
+    ret = []
+    if options.issuperset(comms | core | cleanup):
+        ret.append("All")
+        options -= comms | core | cleanup
+
+    if options.issuperset(comms):
+        ret.append("Comms")
+        options -= comms
+
+    if options.issuperset(core):
+        ret.append("Core")
+        options -= core
+
+    if options.issuperset(cleanup):
+        ret.append("Cleanup")
+        options -= cleanup
+
+    ret.extend(options)
+    return ret
+
+
 def sha256sum_pubkey(der_data: bytes) -> str:
     """Return the SHA-256 digest of `der_data`"""
     return hashlib.sha256(der_data.rstrip(b"\x00")).hexdigest()
@@ -643,6 +732,7 @@ SETTING_TO_PRETTYFUNC: Dict[BeaconSetting, Callable] = {
     BeaconSetting.SETTING_WATERMARKHASH: lambda x: null_terminated_bytes(x) if isinstance(x, bytes) else x,
     BeaconSetting.SETTING_MASKED_WATERMARK: lambda x: x.hex(),
     BeaconSetting.SETTING_BOF_ALLOCATOR: lambda x: BofAllocator(x).name,
+    BeaconSetting.SETTING_BEACON_GATE: lambda x: beacon_gate_options_string(parse_beacon_gate(x)),
     # BeaconSetting.SETTING_PROTOCOL: lambda x: BeaconProtocol(x).name,
     # BeaconSetting.SETTING_CRYPTO_SCHEME: lambda x: CryptoScheme(x).name,
     # BeaconSetting.SETTING_PROXY_BEHAVIOR: lambda x: ProxyServer(x).name,

{dissect_cobaltstrike-1.2.1.dev5 → dissect_cobaltstrike-1.2.1.dev7}/dissect/cobaltstrike/c2profile.lark

@@ -137,6 +137,8 @@ stage_options: "string" string ";"                  -> string
     | "set" "rich_header" string ";"                -> rich_header
     | "set" "checksum" string ";"                   -> checksum
     | "set" "syscall_method" string ";"             -> syscall_method           // introduced in Cobalt Strike 4.8
+    | "set" "data_store_size" string ";"            -> data_store_size          // introduced in Cobalt Strike 4.9
+    | "beacon_gate" "{" beacon_gate_options* "}"    -> beacon_gate              // introduced in Cobalt Strike 4.10
 
 process_inject_options: "set" "allocator" string ";"    -> allocator
     | "set" "min_alloc" string ";"                      -> min_alloc
@@ -158,6 +160,35 @@ execute_options: "CreateThread" string ";"  -> createthread_special
     | "RtlCreateUserThread" ";"             -> rtlcreateuserthread
     | "SetThreadContext" ";"                -> setthreadcontext
 
+beacon_gate_options: "None" ";"             -> none
+    | "Comms" ";"                           -> comms
+    | "Core" ";"                            -> core
+    | "Cleanup" ";"                         -> cleanup
+    | "All" ";"                             -> all
+    | "InternetOpenA" ";"                   -> internetopena
+    | "InternetConnectA" ";"                -> internetconnecta
+    | "VirtualAlloc" ";"                    -> virtualalloc
+    | "VirtualAllocEx" ";"                  -> virtualallocex
+    | "VirtualProtect" ";"                  -> virtualprotect
+    | "VirtualProtectEx" ";"                -> virtualprotextex
+    | "VirtualFree" ";"                     -> virtualfree
+    | "GetThreadContext" ";"                -> getthreadcontext
+    | "SetThreadContext" ";"                -> setthreadcontext
+    | "ResumeThread" ";"                    -> resumethread
+    | "CreateThread" ";"                    -> createthread
+    | "CreateRemoteThread" ";"              -> createremotethread
+    | "OpenProcess" ";"                     -> openprocess
+    | "OpenThread" ";"                      -> openthread
+    | "CloseHandle" ";"                     -> closehandle
+    | "CreateFileMappingA" ";"              -> createfilemappinga
+    | "MapViewOfFile" ";"                   -> mapviewoffile
+    | "UnmapViewOfFile" ";"                 -> unmapviewoffile
+    | "VirtualQuery" ";"                    -> virtualquery
+    | "DuplicateHandle" ";"                 -> duplicatehandle
+    | "ReadProcessMemory" ";"               -> readprocessmemory
+    | "WriteProcessMemory" ";"              -> writeprocessmemory
+    | "ExitThread" ";"                      -> exitthread
+
 postex_options: "set" "spawnto_x86" string ";"  -> spawnto_x86
     | "set" "spawnto_x64" string ";"            -> spawnto_x64
     | "set" "obfuscate" string ";"              -> obfuscate

{dissect_cobaltstrike-1.2.1.dev5 → dissect_cobaltstrike-1.2.1.dev7}/dissect/cobaltstrike/c2profile.py

@@ -350,6 +350,50 @@ class ExecuteOptionsBlock(ConfigBlock):
         return block
 
 
+class BeaconGateBlock(ConfigBlock):
+    """`.stage.beacon_gate` block"""
+
+    __name__ = "BeaconGateBlock"
+
+    none = ConfigBlock._enable
+    comms = ConfigBlock._enable
+    core = ConfigBlock._enable
+    cleanup = ConfigBlock._enable
+    all = ConfigBlock._enable
+    internetopena = ConfigBlock._enable
+    internetconnecta = ConfigBlock._enable
+    virtualalloc = ConfigBlock._enable
+    virtualallocex = ConfigBlock._enable
+    virtualprotect = ConfigBlock._enable
+    virtualprotextex = ConfigBlock._enable
+    virtualfree = ConfigBlock._enable
+    getthreadcontext = ConfigBlock._enable
+    setthreadcontext = ConfigBlock._enable
+    resumethread = ConfigBlock._enable
+    createthread = ConfigBlock._enable
+    createremotethread = ConfigBlock._enable
+    openprocess = ConfigBlock._enable
+    openthread = ConfigBlock._enable
+    closehandle = ConfigBlock._enable
+    createfilemappinga = ConfigBlock._enable
+    mapviewoffile = ConfigBlock._enable
+    unmapviewoffile = ConfigBlock._enable
+    virtualquery = ConfigBlock._enable
+    duplicatehandle = ConfigBlock._enable
+    readprocessmemory = ConfigBlock._enable
+    writeprocessmemory = ConfigBlock._enable
+    exitthread = ConfigBlock._enable
+
+    @classmethod
+    def from_beacon_gate_option_strings(cls, options: list[str]):
+        block = cls()
+
+        for option in options:
+            block._enable(option.lower(), True)
+
+        return block
+
+
 class C2Profile(ConfigBlock):
     """A :class:`C2Profile` object represents a parsed Malleable C2 Profile
 
@@ -622,6 +666,11 @@ class C2Profile(ConfigBlock):
                 proc_inj.set_option("bof_reuse_memory", "true")
             elif setting == BeaconSetting.SETTING_BOF_ALLOCATOR:
                 proc_inj.set_option("bof_allocator", value)
+            elif setting == BeaconSetting.SETTING_DATA_STORE_SIZE:
+                stage.set_option("data_store_size", value)
+            elif setting == BeaconSetting.SETTING_BEACON_GATE and value:
+                block = BeaconGateBlock.from_beacon_gate_option_strings(value)
+                stage.set_config_block("beacon_gate", block)
 
         if c2_recover:
             http_get.set_non_empty_config_block("server", HttpOptionsBlock(output=DataTransformBlock(steps=c2_recover)))

{dissect_cobaltstrike-1.2.1.dev5 → dissect_cobaltstrike-1.2.1.dev7}/docs/installation.rst

@@ -19,14 +19,23 @@ The following pip `extras` flavours are provided as well:
 
 .. code-block:: bash
 
-    $ pip install dissect.cobaltstrike[c2]
-    $ pip install dissect.cobaltstrike[pcap]
-    $ pip install dissect.cobaltstrike[full]
+    $ pip install 'dissect.cobaltstrike[c2]'
+    $ pip install 'dissect.cobaltstrike[pcap]'
+    $ pip install 'dissect.cobaltstrike[full]'
 
 * ``[c2]`` for if you want to communicate with Cobalt Strike Team Servers, eg: :doc:`tools/beacon-client`.
 * ``[pcap]`` for if you want to parse and decrypt PCAPS containing Beacon traffic, eg: :doc:`tools/beacon-pcap`.
 * ``[full]`` provides the above but also installs ``rich`` for prettier console logging.
 
+Install the latest pre-release version
+--------------------------------------
+
+Every change to the main branch is packaged and uploaded to PyPi as a pre-release version, to install the latest pre-release version use the ``--pre`` flag:
+
+.. code-block:: bash
+
+    $ pip install --pre dissect.cobaltstrike
+
 Installing from source
 ----------------------
 
@@ -36,7 +45,7 @@ If you want to install ``dissect.cobaltstrike`` from source, you can use the fol
 
      $ git clone https://github.com/fox-it/dissect.cobaltstrike.git
      $ cd dissect.cobaltstrike
-     $ pip install --editable .[full]
+     $ pip install --editable '.[full]'
 
 Using a virtual environment is recommended. Using the ``--editable`` flag ensures that any changes you make to the source code directly affects the installed package.
 

{dissect_cobaltstrike-1.2.1.dev5 → dissect_cobaltstrike-1.2.1.dev7}/docs/tutorials/decrypt_cobaltstrike_pcaps.rst

@@ -26,7 +26,7 @@ First we ensure that we have ``dissect.cobaltstrike`` installed with PCAP suppor
 
 .. code-block:: bash
 
-   $ pip install dissect.cobaltstrike[pcap]
+   $ pip install 'dissect.cobaltstrike[pcap]'
 
 This also installs the ``pyshark`` Python package but it still requires the ``tshark`` binary from Wireshark_ to work.
 Ensure that you have Wireshark_ installed or install the ``tshark`` binary, for example on Ubuntu or Debian systems you can install it with:

{dissect_cobaltstrike-1.2.1.dev5 → dissect_cobaltstrike-1.2.1.dev7}/docs/tutorials/minimal_beacon_client.rst

@@ -26,7 +26,7 @@ First we install ``dissect.cobaltstrike`` with the ``[c2]`` extra, as we are goi
 
 .. code-block:: bash
 
-    $ pip install dissect.cobaltstrike[c2]
+    $ pip install 'dissect.cobaltstrike[c2]'
 
 This installs the necessary dependencies such as `PyCryptodome` and `httpx`.
 

{dissect_cobaltstrike-1.2.1.dev5 → dissect_cobaltstrike-1.2.1.dev7}/tests/test_c2profile.py

@@ -298,6 +298,39 @@ def test_c2profile_v48():
     assert profile.properties["stage.syscall_method"] == ["direct"]
 
 
+def test_c2profile_v49():
+    c2profile_fragment = """
+    stage {
+        set data_store_size "1024";
+    }
+    """
+    profile = c2profile.C2Profile.from_text(c2profile_fragment)
+    assert profile.properties["stage.data_store_size"] == ["1024"]
+
+
+def test_c2profile_v410():
+    c2profile_fragment = """
+    stage {
+        beacon_gate {
+            All;
+        }
+    }
+    """
+    profile = c2profile.C2Profile.from_text(c2profile_fragment)
+    assert profile.properties["stage.beacon_gate"] == ["All"]
+
+    c2profile_fragment = """
+    stage {
+        beacon_gate {
+            VirtualAlloc;
+            WriteProcessMemory;
+        }
+    }
+    """
+    profile = c2profile.C2Profile.from_text(c2profile_fragment)
+    assert profile.properties["stage.beacon_gate"] == ["VirtualAlloc", "WriteProcessMemory"]
+
+
 @pytest.mark.parametrize(
     ("allocator_enum", "bof_allocator"),
     [
@@ -338,3 +371,27 @@ def test_c2profile_bof_reuse_memory(bof_reuse_memory):
         assert profile.properties["process-inject.bof_reuse_memory"] == ["true"]
     else:
         assert "project.inject.bof_reuse_memory" not in profile.properties
+
+
+def test_c2profile_beacon_gate():
+    # beacon gate with all options
+    data = beacon.Setting(
+        index=beacon.BeaconSetting.SETTING_BEACON_GATE,
+        type=beacon.SettingsType.TYPE_PTR,
+        length=0x40,
+        value=b"\x01" * 0x40,
+    ).dumps()
+    bconfig = beacon.BeaconConfig(data)
+    profile = c2profile.C2Profile.from_beacon_config(bconfig)
+    assert profile.properties["stage.beacon_gate"] == ["All"]
+
+    # empty beacon gate should not result into any profile setting
+    data = beacon.Setting(
+        index=beacon.BeaconSetting.SETTING_BEACON_GATE,
+        type=beacon.SettingsType.TYPE_PTR,
+        length=0x40,
+        value=b"\x00" * 0x40,
+    ).dumps()
+    bconfig = beacon.BeaconConfig(data)
+    profile = c2profile.C2Profile.from_beacon_config(bconfig)
+    assert "stage.beacon_gate" not in profile.properties