humanbound-firewall 0.3.0

humanbound-firewall

Multi-tier firewall for AI agents. Screens every path into the model — the user's turn, every tool result, every record coming back from memory — and blocks prompt injections, jailbreaks, and scope violations before the model sees them.
every boundary, one policy · 4-tier architecture · two lines in a LangChain agent

Quick Start · How It Works · Documentation · Contributing

📖 Full documentation lives at docs.humanbound.ai/defense/firewall/ — this README covers the essentials; the docs have the depth.

⚠ Preview (0.3.x). The Tier 0–3 contract, .hbfw model format, humanbound_firewall.* import surface, and HUMANBOUND_FIREWALL_* env variable names may change before 1.0. Pin to a specific version if you depend on a particular shape. The legacy HB_FIREWALL_* names still work with a deprecation warning and go away in 0.4.

Every path into the model is a boundary

An agent does not only read what its user types. It reads web pages, documents and tool results, and it reads its own records back from a database or a memory store. Indirect prompt injection arrives through those paths, and the model cannot tell an instruction from data on its own. The firewall sits on each path and judges every payload by who authored it:

One policy file describes your agent — its scope, what it may do, what it must never do, and which tools return your own records. It never describes an attack.

Quick Start

Install

pip install humanbound-firewall                  # Core (Tiers 0 + 3)
pip install humanbound-firewall[tier1]           # + local DeBERTa for Tier 1
pip install humanbound-firewall[all]             # Everything

Optional per-provider extras: [openai], [anthropic], [gemini]. The LangChain adapter needs no extra: LangChain is your application's dependency.

A LangChain agent, two lines

from langchain.agents import create_agent
from humanbound_firewall import Firewall

firewall = Firewall.from_config("agent.yaml")
agent = create_agent(model, tools, middleware=[firewall.adapt_to("langchain")])

The adapter attaches every boundary LangChain exposes: the human turn (request), every tool result (ingest, or recall when your policy says the tool returns your own records). A withheld result is replaced by a short notice so the run continues without it; a rejected request ends the run with the notice as the reply. The session travels in the graph state, so a checkpointer carries it across the runs of a thread. firewall.adapt_to("langchain").report() prints the agent's trust-boundary inventory.

Any agent: the manual tier

inspect() is the same call the adapter makes. Use it wherever content enters your model's context:

from humanbound_firewall import Firewall, Session

firewall = Firewall.from_config("agent.yaml")
session = Session.new()  # or Session.from_json(token)

page = fetch(url)
d = firewall.inspect(
    page,
    cls="ingest",
    session=session,
    boundary={"name": "fetch", "kind": "tools", "args": {"url": url}},
)
session = d.session  # token out — you carry it
page = d.replacement if d.action == "withhold" else page

evaluate() is the filter behind it: verdict, category, tier, probabilities, explanation, and the updated session; the caller decides. inspect() adds the decision — pass, withhold or reject — with your deployment's modes applied.

The deployment's choices

Everything that shapes a decision is set once, in code:

firewall = Firewall.from_config(
    "agent.yaml",
    provider=provider,  # the Tier 3 judge (OpenAI, Azure OpenAI, Claude, Gemini)
    classes=("ingest", "recall"),  # which trust classes this deployment enforces
    mode="block",
    mode_by_class={"request": "log"},  # block | log | passthrough
    fail="closed",  # high stakes: an uncertain verdict withholds
    on_decision=audit,  # observe-only; cannot change a verdict
    withheld_template="[Withheld by policy: {category}. Continue without it.]",
)

The judge can also be configured from the environment:

export HUMANBOUND_FIREWALL_PROVIDER=openai
export HUMANBOUND_FIREWALL_API_KEY=sk-...

The policy file

name: ShopAssist
scope:
  business: Shopping assistant for an online store; reads supplier pages and answers product questions.
  more_info: "HIGH-STAKE: the agent can look up supplier contract prices and customer orders, which are confidential."
intents:
  permitted:
    - read a supplier's public product page and follow links on their site for product details
    - look up our own catalogue and order records
  restricted:
    - disclose, send or encode contract prices or customer data to any external party or URL
    - register, sign up or submit information on an external website
capabilities: [tools]                        # the kinds of boundary the agent has
tools:                                       # optional; can only RELAX the default (every tool is ingest)
  recall: [lookup_catalogue, lookup_order]   # tools that return records WE authored: integrity mode
  expects:
    fetch_url: "a supplier's public web page"
settings:
  mode: block
  timeout: 15

few_shots entries — examples exported from your Humanbound test findings — carry the class they were learned on (class: request | ingest; the recall judge takes none).

How It Works

Every payload passes through four tiers before it reaches your model:

Payload (request | ingest | recall)
    |
[ Tier 0 ]  Sanitization                    no model call, free
    |        Strips invisible control characters, zero-width joiners, bidi overrides.
    |
[ Tier 1 ]  Basic Attack Detection          local model inference, free
    |        Pre-trained models (DeBERTa, Azure Content Safety, Lakera, etc.)
    |        Pluggable ensemble — add models or APIs, configure consensus.
    |
[ Tier 2 ]  Agent-Specific Classification   local model inference, free
    |        Trained on YOUR agent's adversarial test logs and QA data,
    |        or a policy classifier that reads agent.yaml. Fast-tracks the clear cases.
    |
[ Tier 3 ]  LLM Judge                       LLM call, token cost
             One judge per trust class, given your policy, the recent
             conversation, and the boundary the payload crossed: which tool,
             what it is for, what it was called with.

Each tier either makes a confident decision or escalates. The judge answers with a verdict letter first; a reply that does not start with one is no verdict, which a fail-closed deployment withholds. Payloads reach the judge fenced, with the protocol restated after them, so content that tries to talk to the judge has nothing to hold on to.

Full config reference, tier-by-tier deep dive, training your own Tier 2 model, writing custom detectors, .hbfw model format, and API reference all live in the firewall docs.

Train guardrails from your test results

Train Tier 2 classifiers from your Humanbound adversarial and QA test results using the Humanbound CLI. Test your agent, then deploy defenses trained on exactly the attacks it failed:

pip install humanbound[firewall]   # installs both packages together
hb login
hb test                            # run adversarial tests
hb firewall train                  # train a Tier 2 model from test logs

See docs.humanbound.ai for the full CLI + firewall integration walkthrough.

Contributing

Contributions welcome. See CONTRIBUTING.md for the dev loop and release process. Contributions are accepted under the Developer Certificate of Origin (sign your commits with git commit -s) — no CLA to sign; you keep the copyright to your work under the same Apache-2.0 license as the project.

• 🐛 Report a bug
• 💡 Request a feature
• 🔒 Report a security issue — not via public Issues
• 💬 Join Discord

License

Apache-2.0. Free to use in any context — commercial or open-source — with attribution.

See TRADEMARK.md for the trademark policy. The code is open; the name is not.