CLI overview

The CLI handles everything: interactive setup, attack generation, firing attacks, judging responses, and producing reports. It’s the primary surface for engineers and CI.

Install

npm install -g @keyvaluesystems/agent-opfor-cli

From source (contributors):

git clone https://github.com/KeyValueSoftwareSystems/agent-opfor.git
cd opfor
npm install
npm run install:cli   # builds + installs `opfor` globally

Two testing modes

Opfor decides which pipeline to run from target.kind. Pick one per config.

Mode	Target	How attacks are delivered	How responses are judged
`agent`	HTTP endpoint or local script speaking LLM chat	Attacker LLM writes free-text adversarial prompts; opfor sends them	Judge LLM reads the target’s text reply
`mcp`	MCP server (stdio process or remote URL)	Opfor lists tools; attacker LLM crafts tool name + JSON args; opfor fires `tools/call`	Judge LLM reads the JSON-RPC response, plus a resource + rug-pull scan

This is different from running opfor itself as an MCP server so AI assistants can invoke it.

Create a config

Interactive wizard (recommended):

opfor setup           # prompts: agent vs mcp, provider, target, suite, effort, turns, telemetry
opfor setup --agent   # skip the mode prompt, go straight to the agent wizard
opfor setup --mcp     # skip the mode prompt, go straight to the MCP wizard

Blank config to hand-edit:

opfor setup --agent --empty   # minimal agent config, no prompts
opfor setup --mcp --empty     # minimal MCP config, no prompts

Configs land in .opfor/configs/opfor-config-<timestamp>-<id>.json unless you pass --config <path>.

Add .opfor/ to .gitignore — it holds configs and reports with embedded target metadata.

Config shape

Agent
MCP (stdio)

{
  "target": {
    "kind": "agent",
    "name": "My Support Bot",
    "description": "A customer support chatbot with access to booking data and PII. Can issue partial refunds.",
    "type": "http-endpoint",
    "endpoint": "http://localhost:4000/chat",
    "requestFormat": "openai"
  },
  "selection": { "mode": "suite", "suite": "owasp-llm-top10" },
  "attackerLlm": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "apiKeyEnv": "OPENAI_API_KEY"
  },
  "effort": "adaptive",
  "turnMode": "multi",
  "turns": 3
}

{
  "target": {
    "kind": "mcp",
    "name": "My MCP Server",
    "transport": "stdio",
    "command": "node",
    "args": ["dist/index.js"]
  },
  "selection": { "mode": "suite", "suite": "owasp-mcp-top10" },
  "attackerLlm": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "apiKeyEnv": "OPENAI_API_KEY"
  },
  "effort": "adaptive",
  "turnMode": "single",
  "turns": 1
}

For a remote MCP server, use { "transport": "url", "url": "https://...", "urlHeaders": { "Authorization": "Bearer ..." } }.

apiKeyEnv is the env var name holding the key — never the key itself. Don’t put raw keys in a config file.

API keys

The attacker/judge LLM key is read at run time. Set it in your shell or a .env file in the working directory:

export OPENAI_API_KEY=sk-...

Load a non-default path with --env:

opfor run --config <path> --env .env.prod

Running scans

Execute, runtime overrides, and reports.

Config reference

Every config field for agent and MCP targets.

Get Started

CLI

Browser Extension

MCP Server

Skills

SDK

Evaluators & Suites

Trace-aware Testing

Reference

CLI overview

Install

Two testing modes

Create a config

Config shape

API keys

Next

Running scans

Config reference

​Install

​Two testing modes

​Create a config

​Config shape

​API keys

​Next

Running scans

Config reference

Install

Two testing modes

Create a config

Config shape

API keys

Next