Skip to content

[Draft]: Add windows_pe keyword#14840

Draft
jlucovsky wants to merge 5 commits intoOISF:mainfrom
jlucovsky:executable/1
Draft

[Draft]: Add windows_pe keyword#14840
jlucovsky wants to merge 5 commits intoOISF:mainfrom
jlucovsky:executable/1

Conversation

@jlucovsky
Copy link
Contributor

@jlucovsky jlucovsky commented Feb 18, 2026

[Draft] Add a windows_pe keyword for detecting Windows Portable Executable (PE) files with metadata matching capabilities.

Rule keyword:

windows_pe: [architecture <arch>][, size <uint32>][, sections <uint16>][, entry_point <uint32>][, subsystem <uint16>][, characteristics <hex>][, dll_characteristics <hex>];

where

  • architecture -- CPU architecture: x86, x86_64, arm, arm64
  • size -- image size
  • sections -- sections count
  • entry_point -- PE entry point (RVA, relative virtual address)
  • subsystem -- PE subsystem (1=native, 2=gui, 3=console, ...) All defined subsystems are handled
  • characteristics -- COFF flags (0x0002=executable, ...) These are handled: EXECUTABLE_IMAGE, DLL, LARGE_ADDRESS_AWARE, 32BIT_MACHINE
  • dll_characteristics -- security flags (0x0040=ASLR, 0x0100=DEP/NX) Handle HIGH_ENTROPY_VA, DYNAMIC_BASE, NX_COMPAT, NO_SEH, GUARD_CF.

See https://learn.microsoft.com/en-us/windows/win32/debug/pe-format for values.

Here are some examples

windows_pe;                                         # any PE
windows_pe: architecture x86_64;                    # 64-bit only
windows_pe: size >1000000;                          # large files
windows_pe: sections <4;                            # few sections (possibly packed)
windows_pe: dll_characteristic <0x0040;            # no ASLR
windows_pe: architecture x86_64, size >100000, sections <4;  # combined

Link to ticket: https://redmine.openinfosecfoundation.org/issues/

Describe changes:

Provide values to any of the below to override the defaults.

  • To use a Suricata-Verify or Suricata-Update pull request,
    link to the pull request in the respective _BRANCH variable.
  • Leave unused overrides blank or remove.

SV_REPO=
SV_BRANCH=
SU_REPO=
SU_BRANCH=

Add a method that accepts an integer value and logs a hex value along
with unittests
This module adds the windows_pe detection keyword and metadata logging
with unittests that exercise its functionality.

These changes provide functions for a C-shim that registers and uses the
detection/logging.
@victorjulien
Copy link
Member

If we parse the PE in detection, we parse it again in logging, right? Can we store the parsed result in the File structure?

alert http any any -> any any (msg:"Windows PE file detected"; \
flow:established,to_client; \
file.data; content:"MZ"; startswith; \
windows_pe:; \
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

strange syntax?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oops. will fix.

alert http any any -> any any (msg:"x86_64 PE detected"; \
flow:established,to_client; \
file.data; content:"MZ"; startswith; \
windows_pe: architecture: x86_64; \
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we use this syntax else where, in other places it would be windows_pe: arch x86_64; (so no : inside the keyword arguments)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will fix.

alert http any any -> any any (msg:"Packed x64 PE"; \
flow:established,to_client; \
file.data; content:"MZ"; startswith; \
windows_pe: architecture: x86_64, size: >100000, sections: <4, entry_point: <4096; \
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we should break this out into per sub option keywords, so they can be simpler and well as easier to optimize with things like prefiltering/fast_pattern

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Meaning having keywords like "windows_pe_arch", "windows_pe_size", etc?

C-shim for integrating windows_pe keyword into the detection engine.
Log windows_pe metadata for alerts and fileinfo objects.
Add documentation for the windows_pe keyword including example rules.
@suricata-qa
Copy link

Information: QA ran without warnings.

Pipeline = 29808

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants