agent-opfor - Open-source adversary emulation for AI agents and

项目说明

<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/Opfor_white%20text.svg" />
<source media="(prefers-color-scheme: light)" srcset="assets/Opfor_black%20text.svg" />
<img src="assets/Opfor_black%20text.svg" alt="OPFOR" width="250" />
</picture>
</p>

<p align="center">
<strong>Open-source ad emulation for AI agents, LLM apps, and MCP servers.</strong><br/>
Test your AI like a real attacker would — from your CLI, your IDE, or a browser extension that anyone on your team can use.
</p>

<p align="center">
<a href="LICENSE"><img src=" alt="License: Apache 2.0"></a>
<a href=" src=" alt="GitHub stars"></a>
<a href=" src=" alt="Discord"></a>
<a href="#e"><img src=" alt="OWASP co"></a>
</p>

<p align="center">
<a href=" target="_blank" rel="noopener noreferrer"><img src=" alt="Key%2Fagent-opfor | Trendshift" width="250" height="55"/></a>
</p>

<p align="center">
<a href=" ·
<a href=" ·
<a href=" ·
<a href=" Extension</a> ·
<a href="
</p>

OPFOR is short for _Opposition Force_ — a military term for the unit that plays the enemy in training, so the rest of the army learns what real attacks feel like before they come. We named the tool after that idea: to defend AI agents better, you have to attack them first.

<p align="center">
<img src="assets/opfor-high-level.svg" alt="How OPFOR works" width="860" />
</p>

Why KeyValue built this

We' 130 products for 90 startups over the last ten years. In the last 18 months, almost every one of them had an AI agent in it — and every one of those teams hit the same wall when it came to testing.

So we built OPFOR. For oursel. Now open source.

Apache 2.0. Built from India.

Quick Start

One-shot — runs the setup wizard and immediately starts the scan:

Two-step — save a config you can reuse or commit to CI:

What opfor does

Opfor red-teams the full AI agent surface — prompts, tools, MCP servers, memory, and multi-turn reasoning. It generates targeted attacks for OWASP LLM Top 10, OWASP Agentic AI Top 10, OWASP MCP Top 10, OWASP API Security, and EU AI Act bias suites, fires them at your target, and judges each response with an LLM.

Most red-team tooling in this space is excellent at one thing — a probe library, a de e, a programmatic framework. Opfor covers more ground in one tool:

Five ways to run opfor

Different people on your team need different entry points. Opfor ships five.

| Mode | How | Best for |
| ------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 🖥️ CLI | opfor setup → opfor run | Engineers, CI/CD, terminal-first workflows |
| 🌐 Browser extension | Install the extension, click the icon on any chat interface | Product managers, designers, QA, security analysts — anyone who can't or won't write code |
| 🤖 MCP server | Register opfor in Cursor or Claude Desktop, then ask in chat | AI coding agents that test your other agents |
| ⚡ Skills | /opfor-setup · /opfor-run · /opfor-mcp-setup · /opfor-mcp-run | De who want one-command testing inside their IDE |
| 📦 SDK | npm install @key/agent-opfor-sdk, then call run / hunt from your code | Programmatic red-teaming and custom workflows |

All fi the same e, attack templates, and judge logic.

→ CLI reference · Browser extension setup · MCP setup · Skills setup · SDK reference · Session handling

How it works

<p align="center">
<img src="assets/opfor-execution-flow.svg" alt="What happens during opfor run" width="860" />
</p>

When you run a scan, opfor:

1. Fetches target info — connects to your agent, detects a tools, MCP endpoints, capabilities
2. Plans attacks per category — generates targeted prompts for each e in your selected suite
3. Emulates the attack — runs multi-turn ad con (real requests, real responses)
4. E with a judge — an LLM judge classifies each response with pass/fail + reasoning
5. Generates a report — HTML for browsing, JSON for CI/CD, all artifacts logged for reproducibility

Each run lands in its own subfolder under .opfor/reports/run-report-<compactTs>-<slug>-<shortId>/ containing <slug>-report.html and <slug>-report.json. Autonomous opfor hunt runs use the same layout under hunt-report-<compactTs>-<slug>-<shortId>/.

Testing cost

Every run reports what its instrumented LLM calls cost, broken down by model:

This is opfor's own spend — the attacker and judge LLMs. It excludes your target's inference cost, which opfor cannot see from the outside. The per-model split is the useful part: the judge is often the bigger share, and pointing it at a cheaper model is usually the easiest saving.

Prices come from a snapshot of LiteLLM's public price map that ships with the package, so runs work offline and a report re-rendered later produces the same figure. Cached input is billed at the provider's cache rate — multi-turn attacks re-send the con each turn, and that repeated prefix is often ~100× cheaper than fresh text, so the figure tracks the real bill rather than a worst case. Caveats worth knowing:

→ Token usage and testing cost

E co

Opfor ships with curated suites that map to industry standards. Pick a suite or run indi e.

| Suite ID | Standard | Focus |
| ------------------ | ------------------------- | ------------------------------------------------------------------------- |
| owasp-llm-top10 | OWASP LLM Top 10 (2025) | Prompt injection, jailbreaks, sensiti, system prompt leakage |
| owasp-agentic-ai | OWASP Agentic AI Top 10 | Excessi, tool misuse, agent goal hijack, memory poisoning |
| owasp-mcp-top10 | OWASP MCP Top 10 (2025) | Secret exposure, scope escalation, tool description injection, SSRF |
| owasp-api | OWASP API Security Top 10 | BOLA, BFLA, SQL injection |
| eu-ai-act-bias | EU AI Act — Bias | Age, gender, race, disability |

→ Full e reference and OWASP mapping

Trace-aware testing

Plug opfor into your obser stack and the LLM judge sees not just the final response — but every tool call, retrieval, and intermediate reasoning step. Out of the box, opfor integrates with Langfuse and Netra.

This catches what input/output testing misses — PII that leaks into a tool call but ne the user, scope escalations in MCP that don't change the response text, agents that retrie data but render a clean reply.

→ Trace-aware testing guide

Autonomous Red-Teaming

opfor hunt skips the config file entirely. Give it an endpoint and an objective, and a multi-agent system — commander, operators, scout — runs an adapti campaign on its own: recon, strategy, multi-turn probing, report. Unlike opfor run, the agents run on Claude only (via a Claude API key, claude setup-token, or your local claude login session) — your target can be anything.

Add --ui to watch the attack tree unfold in a li.

→ Full reference

Browser extension — red-team a chatbot

The browser extension is opfor's no-code path. Install from the Chrome Web Store, open any chat interface, click the opfor icon, pick a suite, and watch it run.

It auto-detects the chat interface, sends attack prompts as if you were typing them, watches the responses, and downloads an HTML report when done. No CLI, no target setup, no YAML.

This is the path for the half of every product team that doesn't open a terminal.

→ Install from the Chrome Web Store · Setup guide

SDK — embed red-teaming in your code

The SDK is opfor's programmatic path. Install @key/agent-opfor-sdk, call run or hunt, and get structured results back — no CLI, no config files, no subprocess.

Use it in CI, in test suites, or anywhere you need red-teaming without leaving TypeScript.

→ SDK reference

Examples

| Example | Description |
| ----------------------------------------------------- | --------------------------------------------------------------- |
| | Plain customer support chatbot — test LLM-le |
| customer-support | Tool-calling agent with PostgreSQL — test BOLA, BFLA, RBAC, PII |
| | Sample MCP server with intentional |

Supported LLM pro

| Provider | Env var | Default model |
| ----------------- | ------------------------------ | ---------------------------------- |
| Groq | GROQ_API_KEY | llama-3.3-70b- |
| OpenAI | OPENAI_API_KEY | gpt-4o-mini |
| Anthropic | ANTHROPIC_API_KEY | claude-3-5-haiku-20241022 |
| Google | GOOGLE_GENERATI | gemini-2.0-flash |
| OpenAI-compatible | OPFOR_API_KEY + baseURL | LiteLLM, OpenRouter, Azure, Ollama |

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

&nbsp;

Authors

Built by the team at KeyValue Software Systems. Contact for all enquiries.

&nbsp;

Security

Use opfor only on systems you own or are authorized to test. To report a in opfor itself, see SECURITY.md — do not open a public issue.

&nbsp;

License

Opfor is licensed under Apache 2.0 — see the LICENSE file for details.

---

<p align="center">
Built with ❤️ by <a href="
</p>

项目信息

开发语言：TypeScript

Star 数：582

技术要点

该项目属于红蓝攻防方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Open-source adversary emulation for AI agents and MCP servers. 展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。