Humanbound CLI
Humanbound attacks your AI agent in multi-turn chats, scores replies against policy and turns failures into firewall rules
- 238 ★ on the repository
- Last commit
- Apache-2.0
Broad access
Why this level
- The engine sends hostile prompts to the given agent endpoint and triggers its tools, so aim it only at systems you own.
- The provider key and conversation contents go to the model that attacks and judges.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/humanboundDetects the agents on your machine, shows the access level and pins the version.
What it sends to the author: what it sends to the author: the hb CLI sends anonymous usage data to help improve the project. disabling data sending requires explicit user action. To turn it off: HB_TELEMETRY_DISABLED=1 in the server environment.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The engine sends hostile prompts to the given agent endpoint and triggers its tools, so aim it only at systems you own.
- The provider key and conversation contents go to the model that attacks and judges.
This is third-party code. Review the repository files before installing.
What it does
Humanbound is an engine and command-line tool `hb` for security testing of AI agents. It holds multi-turn conversations with your real endpoint: it tries to make the agent misuse its tools, step out of its role, fall for prompt injection or leak data. An AI judge scores each reply against your security policy. After a run `hb posture` shows a 0 to 100 security score with an A to F grade, and `hb logs --verdict fail` lists conversations where the agent broke. Findings map to the OWASP LLM and Agentic AI Top 10. Failures become rules for the separate humanbound-firewall project, then the run is repeated to confirm. The endpoint is described in a config file and a run starts with `hb test --endpoint ./bot-config.json --wait`. Practice agents `hello-world` and `pricewatch` run in Docker and are vulnerable on purpose. Integrations: a GitHub Action with a `fail-on` threshold and SARIF, and an MCP server for questions about results.
Who it is for. Developers and security teams shipping an AI agent with tools who want to find weak spots before production.
Good fit when
- A tool-using chatbot is heading to release and needs a check for injections and leaks.
- CI should fail the build when the agent fails a high-severity check.
- You need a report mapping findings to OWASP LLM and Agentic AI Top 10.
- A team needs a safe sandbox to learn attacking an agent: the practice agents in Docker fit.
Not a fit when
- You want to test systems you do not own: the tool is meant for your own agents and endpoints.
- You have no LLM provider key or local Ollama: the attacking model and the judge are required.
- You need a ready production traffic shield: the separate humanbound-firewall handles that.
Example request
Install humanbound, describe my endpoint in `bot-config.json`, run `hb test --endpoint ./bot-config.json --wait` and show the conversations where the agent failed.Limitations
Python 3.10 or newer is required, plus a model provider key (OpenAI, Anthropic, Gemini) or a local Ollama: that model attacks and scores. The practice agents need Docker and an OpenAI key or a compatible server. Practice agents are vulnerable by design, so never run them near sensitive data. A quick run takes about 20 minutes. Hosted attack models and the MCP server work through a Humanbound Platform account, while local `hb test --local` uses your own model. The outcome depends on the judge, so disputed verdicts are worth reviewing by hand.
How to disable. Remove the package with `pip uninstall humanbound`, stop practice agents with `hb arena stop hello-world` and delete the config files from your project.
FAQ
How do I install Humanbound?
Run `pip install 'humanbound[engine]'` and set `HB_PROVIDER` and `HB_API_KEY` for the model that attacks and judges.
Can I try it without my own agent?
Yes, the practice agent `hello-world` starts with `hb arena run hello-world`, and `hb test --target arena://hello-world --quick --wait` attacks it.
How do I connect it to CI?
Through the GitHub Action with `endpoint`, `provider-api-key`, `model` and a `fail-on` threshold. Findings show up as SARIF in the Security tab.
Is a Humanbound account needed?
Not for local runs, no sign-up is required. An account is needed for hosted attack models and the MCP server.
How do I use it from Claude Code or Cursor?
Install `pip install 'humanbound[mcp]'`: the MCP server answers questions about score, findings and runs on the platform.
Discussion
No questions or reviews yet.
Related
CLI toolsHackAgent tests your AI model or agent for jailbreaks, prompt injection and tool misuse and reports a measured attack success rate
ai-engineering installs hooks that deny risky agent calls and write a receipt for every verdict into your repository
Open-source adversary emulation for AI agents, LLM apps and MCP servers, checked against OWASP catalogs
HOL Guard checks an AI agent's shell commands, secret reads, MCP calls and package installs before they run and holds risky actions until you decide
An AI security verification CLI: scans models and code, probes live endpoints and MCP servers, and analyzes recorded agent runs
A CLI with policies that intercepts dangerous AI agent commands like rm -rf, force push or reading .env before they run
README in short
The Humanbound loop is: attack, policy scoring, firewall rules and a repeat run. The project is open source, runs locally without login and is Apache-2.0, with a platform for team work.