firegex/fgex-lib/README.md

Firegex Python Library and CLI

This is the Python library for Firegex, a firewall built for CTF Attack-Defense competitions. It provides the firegex.pyfilters package used to write Python filter Python packet filters, the fgex CLI, and a local proxy simulator (proxysim) for testing filters without a running Firegex instance.

Installation

pip install -U firegex

fgex is an alias package for firegex: installing either one gives you the same firegex module and the fgex/firegex CLI commands.

Documentation

It carries firegex.regex, which binds the same hyperscan firegex matches with, so a pattern ruleset can be checked and tried without a running instance:

fgex regex check rules.json                    # does it compile? what is in it?
fgex regex test  rules.json --sample req.txt   # what would it do to this?
fgex regex proxy rules.json 10.60.3.1 8080     # a local proxy applying it

The ruleset file is the same shape firegex uses. Matching needs libhs (vectorscan) installed; without it the tools say so and stop rather than answering with a different engine, because a tester that disagrees with production is worse than none.

➡️ Writing and testing @pyfilter scripts — the pyfilter decorator, every data structure (RawPacket, TCPInputStream/TCPOutputStream, HttpRequest/HttpResponse and their variants, HttpHistory), packet statements, stream limits, the fgex pyfilters CLI simulator, and a full worked example.

That page is also what's shown in the Firegex web UI itself (the docs button on the service pages) — both are generated from that single file, so they can never drift out of sync.

Firegex's other filtering modules

This library only covers Netfilter Proxy. Firegex ships several other independent modules, each with its own guide:

• Services — fast, PCRE2/hyperscan-based regex matching against raw traffic.
• Hijack Port to Proxy — redirect traffic to your own external proxy without touching the target service.
• Firewall Rules — plain nftables allow/drop/reject rules.
• Services — decrypt-and-reinspect bridge for services that speak TLS natively.