Manual

InfernoFirewall is an inline gateway between agents and LLMs. The ML layer proposes facts; Cedar policy decides the verdict. A tenant with no active bundle has no access, so the default posture is deny-by-default. This manual covers what operators need to run, audit, and trust the system.

Operator workflow

  1. Start from migrations and tenant setup. Run fw migrate as the database owner, then seed a tenant, provider route, model catalog entry, and gateway API key.
  2. Define tool capabilities. Import tools or sync MCP tool lists. A tool must be approved in the active bundle before a policy can allow it.
  3. Build and activate Cedar bundles. fw bundle build validates, checks invariants, diffs against the active bundle, and stores the candidate bundle.
  4. Activate deliberately. Activating a bundle that loosens access requires an explicit accept. Tightenings can be activated without loosening.
  5. Run in shadow mode first. The console records what the firewall would have blocked, held, redacted, or approved before enforcing.
  6. Verify the audit chain after upgrades or restores. fw audit verify checks hash chains, checkpoints, gaps, edits, forged records, and pinned public keys.

Policy and decision model

Policies are Cedar rules stored per tenant. The baseline guard rails are included in every bundle: secrets do not reach external sinks, unreviewed tools cannot run, irreversible actions need approval, and high injection scores block tool calls.

Deny by default

A tool call is allowed only when a matching permit exists and no forbid rule blocks it. If evaluation errors, the result is deny.

ML only tightens

Classifier facts appear in forbid conditions. The policy ceiling can shrink, but it cannot widen.

Verdicts are recorded

Allow, deny, step-up, redact, sandbox, and fail-closed outcomes each carry reason codes, rules fired, scores, thresholds, and stage latency.

Approvals are exact

An approval is bound to tenant, session, principal, tool pin, and canonical arguments hash. A changed amount is a different call.

Sessions, taint and MCP tools

A session is where provenance matters. Anything returned by a tool is untrusted for the rest of that session, and policy decides what untrusted content means for later calls.

Taint grows forward

Reads, fetches, tool results, and child agents inherit taint and data classes. Declassification is an audited, append-only action.

Tool lists are pinned

MCP tool lists are approved only when the tool description, schema, and annotations match the recorded pin. If they change upstream, the tool disappears until re-review.

Tool results are recorded before the model sees them

The result is scanned and recorded first. If the session state cannot be saved, the result is withheld.

Consequential calls need durable evidence

A consequential allowed or redacted call waits for its audit record. If the commit fails or times out, the call is refused before any approval is spent.

Audit, replay and exports

The audit log is not a side channel. It is part of enforcement: consequential actions are recorded before they run, and every decision can be replayed against the bundle that produced it.

fw audit keygen
fw audit verify --tenant demo --public-key <pinned-public-key>
fw replay --tenant demo --limit 1000
fw replay --tenant demo --bundle <candidate-bundle-hash>

Replay compares stored Cedar inputs and recorded verdicts. Detection scores can be stored without raw text, so detection replay depends on payload retention and is not assumed.

Hash chains

Records are chained by SHA-256 over the previous hash and canonical record, one chain per tenant and gateway node.

Signed checkpoints

Ed25519 checkpoints anchor the chain. Verification can be pinned to a public key kept outside the database.

Sinks are cursor-based

Export sinks move cursors only after acknowledgement, so outage causes lag but not skipped records.

Deployment notes

Self-hosted today: one Rust binary and Postgres. Docker Compose is available for quick start, while production upgrades should back up first, run migrations, roll gateways, then verify the chain.

AreaDefault posture
Decision pipelineHard deadline; tool calls fail closed on timeout, stage error, panic, malformed JSON, or lost session state.
Plain textCan fail open only if FW_FAIL_OPEN_TEXT is explicitly enabled.
Private provider addressesNormal model traffic follows FW_UPSTREAM_DENY_PRIVATE; console probes use FW_PROBE_DENY_PRIVATE.
Console accessRole-gated. Payload views write access records before content is shown.
Provider keysStored encrypted under FW_MASTER_KEY, bound to tenant, provider, and base URL.