# framedrag

> Curated IP reputation feeds, dragged into the null route. A single static Go binary that consumes curated IP-reputation feeds (the pfBlockerNG catalog) and turns them into live firewall policy for pfSense and OPNsense, with silent-failure detection as the core feature. It is the IP-blocking half of pfBlockerNG, decoupled from pfSense.

framedrag is a pre-release, open-source project licensed under Apache-2.0. The module is `framedrag.dev/framedrag`, the binary is `framedrag`. It runs one-shot from cron or a systemd timer, configured by a single YAML file. Its core promise: it never fails open. A FAILED feed falls back to its last-good cached copy; after 14 days it is dropped loudly; the run exits non-zero if any feed is FAILED or SUSPECT. Both pfSense and OPNsense consume its output today via URL Table aliases, with zero API integration. It credits pfBlockerNG (BBcan177 / Rubicon Communications) for the feed catalog and a decade of curation, and traces its lineage to Vixie & Rand's 1997 RBL (RTBH filtering). It is not affiliated with Netgate/pfSense, Deciso/OPNsense, or Spamhaus.

## Docs

- [Full site content](https://framedrag.dev/llms-full.txt): The complete plain-text description of framedrag, including the health checks, the pipeline, the command list, configuration, and install steps.
- [Homepage](https://framedrag.dev): The framedrag website.
- [Source and spec](https://github.com/framedrag/framedrag): The project source code on GitHub; the full product spec is at docs/SPEC.md.

## Key facts

- [Health checks](https://framedrag.dev/llms-full.txt): Six per-feed checks on every run: HTTP failure, zero entries after a 200, count delta, rejected-line ratio, staleness, and a sanity floor (0.0.0.0/0, ::/0, RFC1918, your own networks). Statuses are OK, SUSPECT, STALE, FAILED.
- [Commands](https://framedrag.dev/llms-full.txt): `framedrag update`, `framedrag update --dry-run`, `framedrag health`, `framedrag catalog sync`, `framedrag catalog list`, `framedrag version`. Global flags: `--config`, `--verbose`, `--json`.
- [Install](https://framedrag.dev/llms-full.txt): `go install framedrag.dev/framedrag/cmd/framedrag@latest`, or clone https://github.com/framedrag/framedrag and `make build`.

## Optional

- [pfBlockerNG](https://github.com/pfBlockerNG/pfBlockerNG): The upstream feed catalog framedrag tracks (Apache-2.0), credited as prior art.
- [Author](https://akeemjenkins.com): Akeem Jenkins, who designed and built framedrag.
- [Sibling tools](https://higgscli.com): Other tools by the same author: higgscli.com, ouracli.com, useokf.com.