Purple Team: an authorized offensive-security framework driven by your AI coding agent

Purple Team is a local, multi-agent offensive-security framework for authorized testing, designed to run recon, exploit, and report through an AI agent the operator already uses. Exploit operators are still in progress. It is for practitioners who test systems they own or are explicitly authorized to test.

At a glance

• Runs recon, exploit, and report as one mission, from a browser War Room or the command line.
• Works with a local AI agent the operator is already signed into, or with a model the operator runs.
• Refuses networked actions against hosts outside the written scope.
• Records evidence and findings, and requires a retest before a finding is treated as confirmed.
• Labels each component as stable, experimental, in development, or planned.

Offensive security work sits behind years of practice and expensive tooling. The project's README says its bet is that a coordinated set of agents can put authorized bug-hunting within reach of more practitioners. The areas it names are web apps, capture-the-flag challenges, smart contracts, source code, and embedded or robotics open-source projects. The README also says its status sections separate what already works from what is still a bet.

An AI agent that can run commands and send network traffic creates a second problem. The operator has to show what was in scope, what ran, what evidence came back, and whether a fix held. The project's scope model says a mission may be aggressive, but the system must still keep scope, evidence, and operator accountability intact.

This page does not compare other products. It describes the gaps that Purple Team's own documents address.

• Broad execution with no scope record. The scope model rules out a generic execution surface for broad exploitation or credential tooling.
• Findings that cannot be traced. The same model says findings need evidence and retests before they become confident claims.
• A second bill for every run. The README presents its keyless path as needing no new API keys, no cloud tenant, and no second bill.
• Reach beyond the target. Once a mission target is set, the arsenal checks each networked call against the authorized scope before the tool runs.

Purple Team starts with a plain-language mission contract and records each step under it. The scope model lists seven layers in order: human intent, scope receipt, tool gate, evidence ledger, finding ledger, retest, and memory proposal. Each layer answers a reviewer's question: which target is in scope, which action class is approved, and which output supports each claim.

Each tool or adapter runs in one of four execution modes. Safe command covers local-read or lab-safe work. Receipt required covers active, networked, or credential-adjacent work. Catalog only covers known capabilities that should not run through generic command execution. Import only covers evidence brought in from outside.

The framework uses eight operators in one agent cell: Recon, Scanner, Exploiter, Infiltrator, Exfiltrator, Ghost, Coordinator, and Analyst. The README maps each to a MITRE ATT&CK tactic. Recon is the live stage. The README describes the later operators as scaffolded or experimental, and it says the coordinated swarm is not yet proven.

Team archetypes add a defensive view of the same work. Black, blue, and white teams each have their own arsenal grant table. A purple orchestrator correlates their outputs into one posture ledger. Blue views show coverage gaps and a severity-tiered hardening plan, both read from the stored findings.

The README gives the kill chain as recon, exploit, and report. The steps below follow the code that enforces each stage. Each step is a control or a record.

1. Set the scope. When a target is added, the server rebuilds the arsenal's egress scope from the mission's targets. The scope admits those target hosts and their subdomains, plus loopback and private addresses.
2. Request approval for an action. An approval request names an action class and a target. Wildcard targets are refused for active actions, and a whole-subdomain wildcard needs explicit opt-in.
3. Approve for a set time. An approval records who approved it and when it expires. The default window is 30 minutes.
4. Gate risky tools. A tool in a gated risk tier cannot run until it is approved, either interactively or from a pre-authorized list. Built-in probes are ungated by default and rely on the egress gate.
5. Refuse out-of-scope hosts. Before any tool handler runs, the arsenal checks the run's tool allowlist and then the egress scope. An out-of-scope target returns a SCOPE DENIED result.
6. Run recon. The recon engine performs network discovery, DNS lookups, and HTTP fingerprinting. The README says each finding traces to real tool output.
7. Save evidence. Evidence entries link to a mission, an operation, or a finding. Reads of the evidence list pass through a redaction step.
8. Mirror findings without duplicates. Each mission finding is mirrored into the findings ledger. Matching uses title and target, so a finding that appears again on a later pass updates the existing record.
9. Retest before confirming. A retest record starts as queued and can end as passed, failed, or blocked.
10. Report in draft. Coordinated-disclosure output and bounty-platform connectors prepare drafts only. A human must review and confirm before anything is submitted.

Example workflow (illustrative scenario)

This scenario is invented to show how the steps connect. It does not describe a real engagement.

A practitioner has written permission to test a staging web application at staging.example.com. She opens the War Room, describes the application to Op Admiral in plain English, and adds the host as the mission target. The server rebuilds the egress scope from that target (step 1).

During a run, an agent proposes a networked action against a host the owner did not list. The arsenal refuses it before the handler runs and returns SCOPE DENIED (step 5). She then requests approval for a networked action against the staging host and approves it for 30 minutes (steps 2 and 3). Recon output is saved as evidence linked to the mission (step 7). One finding is mirrored into the findings ledger (step 8).

After the owner ships a fix, she opens a retest on that finding. The retest starts as queued. She saves fresh evidence and records whether the retest passed or failed (step 9). The report is a draft, and she reviews it before anything is sent (step 10).

Agents and models

Purple Team connects to five local agents: Claude Code, Codex, Hermes, OpenCode, and Oh My Pi. Connecting one in Settings needs no API key.

Slow local agents can be given more time. Three settings, in milliseconds, control the time allowed for each agent call (T3MP3ST_LOCAL_AGENT_TIMEOUT_MS), each mission task (T3MP3ST_TASK_TIMEOUT_MS), and each planning request (T3MP3ST_GENERAL_TIMEOUT_MS).

Session reuse for Claude Code is off by default. A resumed session may keep provider-side context and tool authority outside the Arsenal's receipt boundary. An operator who trusts the local Claude Code configuration can set T3MP3ST_TRUST_CLAUDE_SESSION=1. The README says that choice must not be treated as an Arsenal-enforced sandbox.

Hosted providers use API keys. The README names OPENROUTER_API_KEY, VENICE_API_KEY, ANTHROPIC_API_KEY, and OPENAI_API_KEY. It also names XAI_API_KEY for Grok Build and NOVITA_API_KEY for Novita AI.

Novita is an opt-in third-party provider. Its requests send the selected model id, prompts and context, generated output, and request metadata to Novita. The README advises reviewing Novita's privacy policy and terms before sending sensitive target data. Purple Team does not claim independent assurance for sensitive workloads.

For a fully offline run, the operator points Purple Team at a local model. The default is Ollama at a local address, and any OpenAI-compatible server works, such as LM Studio, vLLM, or llama.cpp. Tool calls are driven over text, so the built-in tools work on models without native function calling.

This section states what is signed, which operations use keys the operator holds, and what runs off-chain. Purple Team's package manifest lists no web3 or blockchain library. The README places smart-contract work in reproduction only, and it marks that area experimental.

Responsibility. The software is licensed under MIT and provided as-is, with no warranty. The README says the operator alone is responsible for lawful use and for staying inside their rules of engagement. The security policy also asks operators to use test or dummy data for demonstrations, not to exfiltrate real sensitive data, and to keep records of all testing.

What is signed. No approval, scope receipt, evidence entry, or finding is cryptographically signed in the reviewed server paths. The approval handler sets a status, approver, and expiry in server-side records. The server state file is plain JSON. No signing step appears in those paths. [VERIFIED: no signing calls found in src/server.ts, src/arsenal/approval.ts, or src/arsenal/index.ts]

What uses keys the operator holds. Hosted model calls use provider keys that the operator sets as environment variables. Subscription sign-ins keep their credentials on the server. A server that listens beyond loopback will not start until the operator sets a bearer secret.

What runs off-chain. Purple Team's operations are off-chain. Approvals, scope checks, evidence, findings, and retests are held by the local server. A model call goes to the provider the operator selected, and that provider receives the prompt and context. The code reviewed records no operation on a public ledger.

Controls in code. The egress scope gate refuses out-of-scope networked calls before they run. Gated tools stay inert until approved. Evidence list responses pass through a redaction step. Bounty-platform connectors submit only after a human confirms.

Integrations. The command line starts missions through the local HTTP API. An MCP server exposes a recon tool to MCP-aware agents. The Docker setup binds the API to 127.0.0.1, so it is reachable only from the local machine.

Implemented

• Mission engine, War Room, and Op Admiral, keyless through a connected local agent. Cited in src/server.ts at the mission start route.
• Recon engine. Cited in src/recon/index.ts.
• Egress scope gate, on by default. Cited in src/arsenal/index.ts.
• Approval gate for gated tools. Cited in src/arsenal/approval.ts.
• Arsenal, MCP server, and HTTP API. Cited in src/mcp-server.ts and src/server.ts.
• Evidence, findings, and retest records. Cited in src/server.ts.
• Blue gap and hardening views. Cited in src/server.ts.
• Coordinated-disclosure drafts. Cited in src/integrations/bounty.ts and package.json.
• Local agent connections. Cited in src/agent/local-agents.ts.
• Hosted and local model providers. Cited in src/config/index.ts.

In progress (the README marks these as experimental or in development)

• White-box source analysis. Cited in src/recon/whitebox.ts.
• Smart-contract reproduction of known exploit classes. Cited in the README status table.
• Exploiter, Infiltrator, Exfiltrator, and Ghost operators. Cited in the README status table. The swarm is not yet proven.
• Network-domain stages beyond recon. Cited in the README coverage table.
• Cloud, mobile, identity, and binary domains. Cited in the README coverage table.

Planned

• Advanced modules for cloud, persistence, swarm, and cognition. Interface-only in src/stubs/.
• Self-improvement loop. It records lessons and proposals today. Feeding them back into planning is on the roadmap. Cited in the README status table.

Maturity signals: the 20 most recent commits in the repository are dated from 2026-10-10 to 2026-10-19. The repository has 579 files whose names match test patterns, counted outside node_modules.

• Projected: Authorized engagements keep scope, approvals, evidence, and findings in records a reviewer can read. Basis: the server records and checks described above, and the reviewer checklist in the scope model.
• Projected: Findings get a retest before anyone treats them as confirmed. Basis: the retest states and the rule that findings need retests first in the scope model.
• Projected: Owners of tested systems receive a fix plan and a retest record they can check. Basis: the scope model's example of a fix plan, and the blue hardening view.
• Projected: Teams that run offense, detection, and oversight archetypes get one correlated posture view. Basis: the purple synthesis route and the team description in the getting started guide.

Does Purple Team need its own API key?

No, not for the quick start. The README describes a keyless path: after the operator connects a local agent in Settings, such as Claude Code, Codex, Hermes, OpenCode, or Oh My Pi, the mission engine runs without a key. The operator can instead set a provider key and skip the connect step.

Can Purple Team run without a hosted model?

Yes. The README describes a fully offline run on the operator's own model. It defaults to Ollama and can point at any OpenAI-compatible server, such as LM Studio, vLLM, or llama.cpp. Tool calls are driven over text, so the built-in tools work even on local models without native function calling.

Can Purple Team be pointed at any target?

No. The README says to point it only at systems the operator owns or has explicit, written permission to test. SECURITY.md asks for written authorization from the system owner, a defined scope, and rules of engagement before use. Once a mission target is set, networked tools refuse hosts outside that scope.

Does a hosted model provider receive target data?

It can. Hosted providers receive the model id, prompts, context, generated output, and request metadata needed to serve a request. Novita is opt-in, and the README advises reviewing its privacy policy and terms before sending sensitive target data. A local model endpoint keeps requests on the host the operator configures.

Request a technical briefing or early access through the site's contact page. Ask for the scope model, the approval flow, and the current status list in writing. This page does not cover commercial terms. Early access is not currently offered; the contact route (app/contact/page.tsx) exists but no early access program is active.

Paths are relative to the purpleteam repository (swcstudiospace/purple-team) unless noted.

• README.md
• SECURITY.md
• docs/SCOPE_AND_AUTHORIZATION.md
• docs/GETTING_STARTED.md
• package.json
• src/server.ts
• src/cli.ts
• src/index.ts
• src/arsenal/index.ts
• src/arsenal/approval.ts
• src/llm/index.ts
• src/config/index.ts
• src/agent/local-agents.ts
• src/integrations/bounty.ts
• src/mcp-server.ts
• src/recon/index.ts
• src/recon/whitebox.ts
• src/stubs/
• Git history: last 20 commits, read with git log -n 20 --date=short.
• Test file count: find for *.test.* and *.spec.* outside node_modules.