https://github.com/humanbound/humanbound
Open-source AI agent red-team engine, SDK, and CLI. Run offline or against the Humanbound Platform.
https://github.com/humanbound/humanbound
adversarial-testing agentic-ai ai-agents ai-red-teaming ai-safety ai-security aisecops cli cybersecurity guardrails humanbound llm llm-security multimodal-ai multimodal-security owasp pentesting prompt-injection security-testing security-tools
Last synced: 17 days ago
JSON representation
Open-source AI agent red-team engine, SDK, and CLI. Run offline or against the Humanbound Platform.
- Host: GitHub
- URL: https://github.com/humanbound/humanbound
- Owner: humanbound
- License: other
- Created: 2026-02-08T08:47:43.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-05T18:50:32.000Z (22 days ago)
- Last Synced: 2026-05-05T20:32:16.475Z (22 days ago)
- Topics: adversarial-testing, agentic-ai, ai-agents, ai-red-teaming, ai-safety, ai-security, aisecops, cli, cybersecurity, guardrails, humanbound, llm, llm-security, multimodal-ai, multimodal-security, owasp, pentesting, prompt-injection, security-testing, security-tools
- Language: Python
- Homepage: https://docs.humanbound.ai/
- Size: 2.79 MB
- Stars: 18
- Watchers: 0
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Roadmap: ROADMAP.md
- Cla: CLA.md
Awesome Lists containing this project
README
humanbound
Open-source AI agent red-team engine, SDK, and CLI.
Runs locally or against the Humanbound Platform. No login required to start.
Quick Start ·
CLI ·
SDK ·
Documentation ·
Contributing
---
> 📖 **Full documentation** lives at [**docs.humanbound.ai**](https://docs.humanbound.ai/) —
> this README covers the essentials; the docs have the depth.
## Quick Start
### Install
```bash
pip install humanbound # CLI + SDK, core deps
pip install humanbound[engine] # + OpenAI / Anthropic / Gemini providers
pip install humanbound[firewall] # + humanbound-firewall runtime
pip install humanbound[engine,firewall] # everything
```
### CLI usage
```bash
# Configure your LLM provider
export HB_PROVIDER=openai
export HB_API_KEY=sk-...
# Run a security test
hb test --endpoint ./bot-config.json --repo . --wait
# View results
hb posture # security score (0-100, A-F)
hb logs # conversation logs
hb report -o report.html # HTML report
hb guardrails -o rules.yaml # firewall rules
```
Full air-gap with [Ollama](https://ollama.com) — zero external API calls:
```bash
export HB_PROVIDER=ollama
export HB_MODEL=llama3.1:8b
hb test --endpoint ./bot-config.json --scope ./scope.yaml --wait
```
### Python SDK
```python
from humanbound import Bot, LocalRunner, OwaspAgentic, TestingLevel, EngineCallbacks
# Compose your own test pipeline
bot = Bot(endpoint="https://my-agent/chat", api_key="...")
class Callbacks(EngineCallbacks):
def on_finding(self, insight): ...
def on_progress(self, pct): ...
runner = LocalRunner()
# See docs.humanbound.ai for the full example
```
## Stability contract
| Import path | Stability |
|---|---|
| `from humanbound import X` | **Stable** — semver-protected |
| `from humanbound. import Y` | **Stable** — semver-protected |
| `from humanbound_cli.* import Z` | **Internal** — may change any release, do not import from user code |
The full Tier-by-Tier walkthrough, orchestrator authoring guide, Platform
integration, and API reference all live on
[docs.humanbound.ai](https://docs.humanbound.ai/).
## What's shipping in 2.0
- **Clean name**: `humanbound` is the new PyPI install. The old
`humanbound-cli` package is a discontinued transitional stub (final
release 1.2.2 depends on `humanbound>=2.0.2`); please install
`humanbound` directly.
- **Public SDK namespace** alongside the CLI — use the CLI or drive the
engine from Python. Both share the same implementation, so they can't
drift.
- **Firewall integration**: `pip install humanbound[firewall]` pulls the
renamed [`humanbound-firewall`](https://github.com/humanbound/humanbound-firewall)
(formerly `hb-firewall`) alongside the CLI.
See [CHANGELOG.md](./CHANGELOG.md) for the full 2.0.0 release notes.
## Contributing
Contributions welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the dev
loop, release process, and CLA requirement (see [CLA.md](./CLA.md)).
- 🐛 [Report a bug](https://github.com/humanbound/humanbound/issues/new/choose)
- 💡 [Request a feature](https://github.com/humanbound/humanbound/issues/new/choose)
- 🔒 [Report a security issue](./SECURITY.md) — **not via public Issues**
- 💬 [Join Discord](https://discord.gg/gQyXjVBF)
## License
[Apache-2.0](./LICENSE). Free to use in any context — commercial or
open-source — with attribution. See [TRADEMARK.md](./TRADEMARK.md) for the
trademark policy. The code is open; the name is not.
The sibling project [`humanbound-firewall`](https://github.com/humanbound/humanbound-firewall)
is also Apache-2.0 — same license, different product.