dissect.cobaltstrike.pe

This module contains helper functions for parsing PE files, mainly for extracting Beacon specific PE artifacts.

Module Contents

Functions

find_mz_offset(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Optional[int]

Find and return the start offset of a valid IMAGE_DOS_HEADER or None if it cannot be found.

find_compile_stamps(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Tuple[Optional[int], Optional[int]]

Find and return a tuple with the PE compile and PE export timestamps.

find_magic_mz(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Optional[bytes]

Find and returns the MZ header bytes or None if cannot be found

find_magic_pe(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Optional[bytes]

Find and returns the PE header (magic_pe) bytes or None if cannot be found

find_stage_prepend_append(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Tuple[Optional[bytes], Optional[bytes]]

Find and return the stage prepend and append bytes as a tuple.

find_architecture(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Optional[str]

Find and return the PE image architecture, either "x86" or "x64" or None if not found.

Attributes

logger

PE_DEF

pestruct

DOSHEADER_X64

DOSHEADER_X86

dissect.cobaltstrike.pe.logger[source]
dissect.cobaltstrike.pe.PE_DEF = Multiline-String[source]
Show Value
  1#define IMAGE_FILE_MACHINE_AMD64    0x8664
  2#define IMAGE_FILE_MACHINE_I386     0x014c
  3#define IMAGE_FILE_MACHINE_IA64     0x0200
  4
  5#define IMAGE_NUMBEROF_DIRECTORY_ENTRIES 16
  6#define IMAGE_SIZEOF_SHORT_NAME          8
  7
  8#define IMAGE_DIRECTORY_ENTRY_EXPORT    0
  9#define IMAGE_DIRECTORY_ENTRY_IMPORT    1
 10#define IMAGE_DIRECTORY_ENTRY_RESOURCE  2
 11
 12typedef struct _IMAGE_DOS_HEADER
 13{
 14    WORD e_magic;
 15    WORD e_cblp;
 16    WORD e_cp;
 17    WORD e_crlc;
 18    WORD e_cparhdr;
 19    WORD e_minalloc;
 20    WORD e_maxalloc;
 21    WORD e_ss;
 22    WORD e_sp;
 23    WORD e_csum;
 24    WORD e_ip;
 25    WORD e_cs;
 26    WORD e_lfarlc;
 27    WORD e_ovno;
 28    WORD e_res[4];
 29    WORD e_oemid;
 30    WORD e_oeminfo;
 31    WORD e_res2[10];
 32    LONG e_lfanew;
 33} IMAGE_DOS_HEADER;
 34
 35typedef struct _IMAGE_FILE_HEADER {
 36    WORD  Machine;
 37    WORD  NumberOfSections;
 38    DWORD TimeDateStamp;
 39    DWORD PointerToSymbolTable;
 40    DWORD NumberOfSymbols;
 41    WORD  SizeOfOptionalHeader;
 42    WORD  Characteristics;
 43} IMAGE_FILE_HEADER;
 44
 45typedef struct _IMAGE_DATA_DIRECTORY {
 46    ULONG   VirtualAddress;
 47    ULONG   Size;
 48} IMAGE_DATA_DIRECTORY;
 49
 50typedef struct _IMAGE_OPTIONAL_HEADER {
 51    WORD                 Magic;
 52    BYTE                 MajorLinkerVersion;
 53    BYTE                 MinorLinkerVersion;
 54    DWORD                SizeOfCode;
 55    DWORD                SizeOfInitializedData;
 56    DWORD                SizeOfUninitializedData;
 57    DWORD                AddressOfEntryPoint;
 58    DWORD                BaseOfCode;
 59    DWORD                BaseOfData;
 60    DWORD                ImageBase;
 61    DWORD                SectionAlignment;
 62    DWORD                FileAlignment;
 63    WORD                 MajorOperatingSystemVersion;
 64    WORD                 MinorOperatingSystemVersion;
 65    WORD                 MajorImageVersion;
 66    WORD                 MinorImageVersion;
 67    WORD                 MajorSubsystemVersion;
 68    WORD                 MinorSubsystemVersion;
 69    DWORD                Win32VersionValue;
 70    DWORD                SizeOfImage;
 71    DWORD                SizeOfHeaders;
 72    DWORD                CheckSum;
 73    WORD                 Subsystem;
 74    WORD                 DllCharacteristics;
 75    DWORD                SizeOfStackReserve;
 76    DWORD                SizeOfStackCommit;
 77    DWORD                SizeOfHeapReserve;
 78    DWORD                SizeOfHeapCommit;
 79    DWORD                LoaderFlags;
 80    DWORD                NumberOfRvaAndSizes;
 81    IMAGE_DATA_DIRECTORY DataDirectory[IMAGE_NUMBEROF_DIRECTORY_ENTRIES];
 82} IMAGE_OPTIONAL_HEADER;
 83
 84typedef struct _IMAGE_OPTIONAL_HEADER64 {
 85    WORD        Magic;
 86    BYTE        MajorLinkerVersion;
 87    BYTE        MinorLinkerVersion;
 88    DWORD       SizeOfCode;
 89    DWORD       SizeOfInitializedData;
 90    DWORD       SizeOfUninitializedData;
 91    DWORD       AddressOfEntryPoint;
 92    DWORD       BaseOfCode;
 93    ULONGLONG   ImageBase;
 94    DWORD       SectionAlignment;
 95    DWORD       FileAlignment;
 96    WORD        MajorOperatingSystemVersion;
 97    WORD        MinorOperatingSystemVersion;
 98    WORD        MajorImageVersion;
 99    WORD        MinorImageVersion;
100    WORD        MajorSubsystemVersion;
101    WORD        MinorSubsystemVersion;
102    DWORD       Win32VersionValue;
103    DWORD       SizeOfImage;
104    DWORD       SizeOfHeaders;
105    DWORD       CheckSum;
106    WORD        Subsystem;
107    WORD        DllCharacteristics;
108    ULONGLONG   SizeOfStackReserve;
109    ULONGLONG   SizeOfStackCommit;
110    ULONGLONG   SizeOfHeapReserve;
111    ULONGLONG   SizeOfHeapCommit;
112    DWORD       LoaderFlags;
113    DWORD       NumberOfRvaAndSizes;
114    IMAGE_DATA_DIRECTORY DataDirectory[IMAGE_NUMBEROF_DIRECTORY_ENTRIES];
115} IMAGE_OPTIONAL_HEADER64;
116
117typedef struct _IMAGE_SECTION_HEADER {
118    char    Name[IMAGE_SIZEOF_SHORT_NAME];
119    ULONG   VirtualSize;
120    ULONG   VirtualAddress;
121    ULONG   SizeOfRawData;
122    ULONG   PointerToRawData;
123    ULONG   PointerToRelocations;
124    ULONG   PointerToLinenumbers;
125    USHORT  NumberOfRelocations;
126    USHORT  NumberOfLinenumbers;
127    ULONG   Characteristics;
128} IMAGE_SECTION_HEADER;
129
130typedef struct _IMAGE_IMPORT_DESCRIPTOR {
131    union {
132        ULONG   Characteristics;
133        ULONG   OriginalFirstThunk;
134    } u;
135    ULONG   TimeDateStamp;
136    ULONG   ForwarderChain;
137    ULONG   Name;
138    ULONG   FirstThunk;
139} IMAGE_IMPORT_DESCRIPTOR;
140
141typedef struct _IMAGE_EXPORT_DIRECTORY {
142    ULONG   Characteristics;
143    ULONG   TimeDateStamp;
144    USHORT  MajorVersion;
145    USHORT  MinorVersion;
146    ULONG   Name;
147    ULONG   Base;
148    ULONG   NumberOfFunctions;
149    ULONG   NumberOfNames;
150    ULONG   AddressOfFunctions;     // RVA from base of image
151    ULONG   AddressOfNames;         // RVA from base of image
152    ULONG   AddressOfNameOrdinals;  // RVA from base of image
153} IMAGE_EXPORT_DIRECTORY;
dissect.cobaltstrike.pe.pestruct[source]
dissect.cobaltstrike.pe.DOSHEADER_X64[source]
dissect.cobaltstrike.pe.DOSHEADER_X86[source]
dissect.cobaltstrike.pe.find_mz_offset(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Optional[int][source]

Find and return the start offset of a valid IMAGE_DOS_HEADER or None if it cannot be found.

It uses IMAGE_DOS_HEADER.e_lfanew and IMAGE_FILE_HEADER.Machine as a constraint.

Side effects: file handle position due to seeking

Parameters

  • fh – file like object

  • start_offset – offset to start searching from, None indicates from current file position

  • maxrange – how far to search for into the file object

Returns

offset of the start of IMAGE_DOS_HEADER in the file object or None if it’s not found

dissect.cobaltstrike.pe.find_compile_stamps(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Tuple[Optional[int], Optional[int]][source]

Find and return a tuple with the PE compile and PE export timestamps.

If one or more TimeDateStamps are not found it will be returned as None in the tuple.

Side effects: file handle position due to seeking

Parameters

  • fh – file like object

  • start_offset – offset to start searching from, None indicates from current file position

  • maxrange – how far to search for into the file object

Returns

Tuple with (IMAGE_FILE_HEADER.TimeDateStamp, IMAGE_EXPORT_DIRECTORY.TimeDateStamp). Either tuple values can be None if it’s not found.

dissect.cobaltstrike.pe.find_magic_mz(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Optional[bytes][source]

Find and returns the MZ header bytes or None if cannot be found

Cobalt Strike allows changing the MZ magic header using magic_mz_x86 or magic_mz_x64 in the c2 profile. This function recovers these bytes.

Side effects: file handle position due to seeking

Parameters

  • fh – file like object

  • start_offset – offset to start searching from, None indicates from current file position

  • maxrange – how far to search for into the file object

Returns

MZ header bytes or None if not found.

dissect.cobaltstrike.pe.find_magic_pe(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Optional[bytes][source]

Find and returns the PE header (magic_pe) bytes or None if cannot be found

Cobalt Strike allows changing the PE magic header using the magic_pe in the malleable c2 profile. This function tries to recovers these bytes.

Side effects: file handle position due to seeking

Parameters

  • fh – file like object

  • start_offset – offset to start searching from, None indicates from current file position

  • maxrange – how far to search for into the file object

Returns

PE header bytes or None if not found.

dissect.cobaltstrike.pe.find_stage_prepend_append(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Tuple[Optional[bytes], Optional[bytes]][source]

Find and return the stage prepend and append bytes as a tuple.

Cobalt Strike allows prepending and appending extra bytes to the beacon using malleable c2 profile settings. This function tries to recover these bytes.

Side effects: file handle position due to seeking

Parameters

  • fh – file like object

  • start_offset – offset to start searching from, None indicates from current file position

  • maxrange – how far to search for into the file object

Returns

Tuple containing (prepend_bytes, append_bytes). Either tuple values can be None if it’s not found.

dissect.cobaltstrike.pe.find_architecture(fh: BinaryIO, start_offset: int = 0, maxrange: int = 1024) → Optional[str][source]

Find and return the PE image architecture, either "x86" or "x64" or None if not found.

It uses IMAGE_DOS_HEADER.e_lfanew and IMAGE_FILE_HEADER.Machine as a constraint.

Only x86 and x64 are considered, other machine architectures are ignored.

Side effects: file handle position due to seeking

Parameters

  • fh – file like object

  • start_offset – offset to start searching from, None indicates from current file position

  • maxrange – how far to search for into the file object

Returns

"x86" or "x64", None if not found.