GeezerVison

Humanbound attacks your agent the way real attackers will, scores every conversation,
and turns each failure into a firewall rule. Open source, runs locally, no login needed.

AI agents hold conversations, call tools and keep state, so many security failures appear only as a conversation unfolds, never in a single prompt.

Humanbound tests the agent, not just the prompt: it holds multi-turn conversations with your real endpoint, tries to make the agent misuse its tools or step outside its role, and an AI judge scores every reply against your security policy.

Key capabilities:

• Realistic attacks — multi-turn conversations that try prompt injection, jailbreaks, tool abuse and data leaks, the way a real attacker would
• Standards-mapped — every finding maps to the OWASP LLM and Agentic AI Top 10
• Behavior checks — does the agent stay on task and answer correctly
• A security score — 0–100 with an A–F grade, plus every conversation that failed
• Findings into defenses — failures become rules for humanbound-firewall
• Fits your workflow — CLI, Python SDK, GitHub Action and an MCP server for coding agents

_{Security score and failed conversations after attacking the hello-world practice agent, with each conversation's severity (0–100) and the judge's reason.}

• Before launch — red-team a new agent before real users reach it
• On every pull request — fail the build when a prompt, tool or model change opens a hole
• In production — monitor the agent continuously and catch regressions (Platform)
• At runtime — block the attacks it failed with firewall rules generated from the findings

Prerequisites: Python 3.10+, and an LLM API key (OpenAI, Anthropic, Gemini) or a local Ollama. The practice agents below also need Docker and an OpenAI key, or an OpenAI-compatible server such as Ollama.

pip install 'humanbound[engine]'
export HB_PROVIDER=openai HB_API_KEY=sk-...   # the model that attacks and judges

No agent of your own yet? hello-world is a deliberately vulnerable shop chatbot that runs in Docker. Start it, attack it and see how it broke:

hb arena config set OPENAI_API_KEY=sk-...             # the practice agent's model
hb arena run hello-world
hb test --target arena://hello-world --quick --wait   # about 20 minutes
hb posture                                            # security score, 0–100 and A–F
hb logs --verdict fail                                # the conversations where it broke
hb arena stop hello-world

Building with tools? Try pricewatch (tool use, indirect injection). hb arena ls lists every practice agent (Arena docs).

Humanbound calls your agent's API over REST, WebSocket or SSE. Tell it how in bot-config.json; $PROMPT is replaced with each attack message:

{
  "chat_completion": {
    "endpoint": "https://your-bot.com/chat",
    "headers": {"Authorization": "Bearer <token>"},
    "payload": {"message": "$PROMPT"}
  }
}

The agent should reply with JSON that has the answer in a field such as content, text, reply or message; nested fields are fine.

hb test --endpoint ./bot-config.json --wait   # about 20 minutes with a cloud model
hb report -o report.html                      # shareable HTML report

No API key, or your model refuses to write attacks? Test your agent on the Platform with hosted attack models.

Next steps

Log in and the same CLI sends its runs to the Humanbound Platform. Your findings and score are kept across runs, and the Platform can keep testing your agent on a schedule (hb monitor). The free plan needs no card.

hb login
hb connect --endpoint ./bot-config.json    # creates a project and runs a first test
hb posture --trends                        # score over time
hb findings                                # open, fixed and regressed findings

Everything in open source, plus:

• Findings tracked across runs, and score history
• Continuous monitoring
• Cross-session leaks: does one user's data reach another
• Hosted attack models, no API key needed
• Team collaboration

Many models refuse to write attacks because of their safety rules, which makes them poor attackers. Hosted attack models don't have that problem: if an attack doesn't work with one model, it's retried with another, and a separate model grades the results, so the model that wrote an attack never judges it.

Sign up, run hb login and hb connect, and hb test runs on the Platform with hosted attack models, unless you add your own provider with hb providers create. Practice agents and hb test --local always use your own model.

Start free on app.humanbound.ai →

On-premises installation, SAML/OIDC single sign-on, SIEM integration, bring-your-own-key models and a named engineer with an SLA. Contact sales →

Test → find → defend → test again.

1. Export the findings as a firewall policy:

   hb guardrails -f yaml -o agent.yaml

2. Load agent.yaml into humanbound-firewall (pip install humanbound-firewall). It blocks the attacks your agent just failed.

3. Run hb test again to confirm.

Optional: train a dedicated classifier from your test logs with 'humanbound[firewall]' (Firewall docs).

humanbound/actions tests your agent on every pull request and fails the build on findings at or above a severity:

# .github/workflows/agent-security.yml
name: Agent security
on: [pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker compose up -d agent # start your agent, reachable on localhost

      - uses: humanbound/actions@v1
        with:
          endpoint: ./bot-config.json   # same format as in the Quick start, pointing at localhost
          provider-api-key: ${{ secrets.OPENAI_API_KEY }}
          model: gpt-4.1
          fail-on: high

With a Humanbound account, pass api-key, org-id and project-id instead of provider-api-key and model, and the run uses hosted attack models (or your own provider, if you added one).

Findings can also appear in GitHub's Security tab (SARIF). GitLab and other systems: CI/CD docs.

Ask about your results (MCP server). Claude Code, Cursor, Windsurf or Copilot can answer questions about your score, findings and runs on the Platform. It needs a Humanbound account:

pip install 'humanbound[mcp]'
hb login
claude mcp add humanbound -- hb mcp

Setup for other editors is in the MCP docs.

Let the agent run the test (plugin, preview). The humanbound-test plugin lets Claude Code or Cursor find your local FastAPI agent and test it for you. It needs a Humanbound account.

The CLI and the SDK share one implementation:

import json
import time

from humanbound import LocalRunner, TestConfig

config = TestConfig(
    endpoint=json.load(open("bot-config.json")),
    test_category="humanbound/adversarial/owasp_agentic",
    testing_level="unit",
    lang="english",
)

runner = LocalRunner()
experiment_id = runner.start(config)
while runner.get_status(experiment_id).status not in ("Finished", "Failed", "Terminated"):
    time.sleep(5)

posture = runner.get_posture(experiment_id)
print(f"Security posture: {posture.overall_score} ({posture.grade})")

More in the docs, including how the engine works.

Everything else is at docs.humanbound.ai: configuration, attack methodology, CI/CD, the Platform and the full command reference.

Code, docs and bug reports are welcome. See CONTRIBUTING.md for the dev setup and the DCO sign-off.

• 🐛 Report a bug
• 💡 Request a feature
• 🔒 Report a security issue — not via public issues
• 💬 Join Discord
• 📋 Release notes

If Humanbound finds something in your agent, a ⭐ helps other builders find it too.

The hb CLI sends anonymous usage data to help improve the project. To turn it off:

hb telemetry disable           # or: export HB_TELEMETRY_DISABLED=1, or: export DO_NOT_TRACK=1

Turning it off sends one final anonymous telemetry_disabled event per machine, so we can count opt-outs. Details in PRIVACY.md.

Humanbound is licensed under the Apache License 2.0. See TRADEMARK.md for the trademark policy.