Metadata-Version: 2.4
Name: firegex
Version: 5.0.0
Summary: Firegex client
Author-email: Pwnzer0tt1 <pwnzer0tt1@poliba.it>
Project-URL: Homepage, https://github.com/pwnzer0tt1/firegex
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: typer
Requires-Dist: rich
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.7.1
Requires-Dist: pycryptodome
Requires-Dist: watchfiles
Requires-Dist: websockets
Requires-Dist: brotli>=1.2.0
Requires-Dist: zstandard; python_version < "3.14"

# Firegex Python Library and CLI

This is the Python library for [Firegex](https://github.com/Pwnzer0tt1/firegex), a firewall built for CTF Attack-Defense competitions. It provides `firegex.pyfilters` — the package you write [Python filters](../docs/pyfilter.md) against — `firegex.regex` for pattern rulesets, the `fgex` CLI, and local simulators for both, so a filter can be tried before it ever reaches a running Firegex.

## Installation

```bash
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:

```bash
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](../docs/pyfilter.md)** — 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.

## The rest of Firegex

This package is the part you write filters *with*. What runs them is a Firegex instance,
started from a clone with `python3 run.py` — there is deliberately no deploy command here,
because any second description of that script's arguments would drift from it.

Two guides cover everything an instance does:

- **[Services](../docs/services.md)** — a service is a **network layer** (NFQUEUE, the
  terminating proxy, or a hand-off to a proxy you wrote) plus an ordered chain of
  **filters** (hyperscan patterns, or the Python you write with this library). TLS, QUIC
  and every version of HTTP are protocols a service can speak rather than separate things
  to set up.
- **[Firewall Rules](../docs/firewall.md)** — plain nftables allow/drop/reject rules.

The modules this library used to list — `nfregex`, `nfproxy`, `porthijack` and `tls` —
were folded into services as choices rather than modules in 5.0.0, which is also when
`firegex.nfproxy` became `firegex.pyfilters`.
