Secure Agent Playbook

An open-source security playbook for AI agents. Structured, OWASP-grounded procedures that enable agents to perform security engineering tasks — from code review to AI agent security audits.

Table of Contents

• Why Use This?
• What This Is
• Quick Start
• Skills Catalog
• Agents
• Example Output
• Plays
• Architecture
• OWASP Foundation
• Related Projects
• Contributing

Why Use This?

Without a playbook, asking an AI agent to "review my code for security" gives you a surface-level checklist. With these plays, the agent follows a structured OWASP-grounded procedure — systematically testing every vulnerability class, producing findings with CWE mappings, OpenCRE cross-references, evidence snippets, and specific remediation code.

• Consistent methodology — Every assessment follows a documented procedure, not ad-hoc prompting. Results are reproducible across runs and reviewers.
• Structured, actionable output — Findings include severity, CWE, evidence, and remediation steps with code examples. No vague warnings.
• Cross-standard traceability — Findings link to CWE, ASVS, WSTG, and NIST 800-53 via OpenCRE for compliance mapping.
• 17 security skills — From dependency CVE scanning to prompt injection testing to multi-agent threat modeling. Install as a Claude Code plugin or use standalone.
• Works beyond Claude Code — Skills are Claude Code plugins; plays are standalone procedures any AI agent can follow.

What This Is

This is not a framework or a library. There is no code to import.

Each play is a step-by-step security procedure with checklists, decision criteria, and output templates. An AI agent follows the procedure to produce consistent, evidence-based findings. Think of it like a SOC analyst's playbook — but written for AI agents to execute.

Quick Start

With Claude Code (recommended):

Step 1 — Register the plugin marketplace:

/plugin marketplace add OWASP/secure-agent-playbook

Step 2 — Install a skill set:

/plugin install code-security-skills@agent-security-playbook
/plugin install ai-security-skills@agent-security-playbook

Step 3 — Use the skills by mentioning the task in conversation:

"Review this code for security issues"
"Scan my dependencies for CVEs"
"Audit this MCP server configuration"
"Test this chatbot for prompt injection"

Claude will automatically activate the relevant skill based on context. See Skills Catalog for all available skills and Example Output for what the results look like.

Organization plugin — For Claude organization admins installing via Organization Plugins:

1. Go to the latest release
2. Download secure-agent-playbook.zip from the release assets
3. Upload the zip at Organization settings > Plugins > Add plugin

Note: Do not use GitHub's "Download ZIP" button — it nests files in a subdirectory that the plugin validator rejects. Always use the release asset zip.

Local development — To test from a local clone instead of GitHub:

/plugin marketplace add /path/to/agent-security-playbook
/plugin install code-security-skills@agent-security-playbook
/plugin install ai-security-skills@agent-security-playbook

Without Claude Code:

Reference plays directly as procedures for any AI agent or manual use:

• Point your agent at a play: "Follow the procedure in plugins/ai-security-skills/plays/agent-security-audit.md"
• Or use the plays as checklists for manual security reviews

Skills Catalog

Code & Infrastructure Security (code-security-skills)

AI & Agent Security (ai-security-skills)

Agents

Agents are autonomous security specialists that invoke skills and produce structured reports. Each agent has a focused system prompt, scoped tool access, and preloaded skills. Use them individually or as a coordinated team.

Standalone usage — invoke any agent directly:

"Use code-security-reviewer to review src/"
"Use dependency-auditor to scan this project"

Team assessment — with agent teams enabled, the team lead dispatches specialists in parallel and consolidates findings into a single report:

"Run a full security assessment of this project"

The team lead scopes the target, dispatches relevant specialists (skipping those whose focus area isn't present), deduplicates findings, identifies cross-domain risk chains, and produces a unified report using templates/report.md.

Agent teams requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. See Claude Code docs for setup. Individual agents work without this flag.

Example Output

Running "Review src/auth/ for security issues" on a Node.js/Express codebase produces findings like this:

Security Code Review — src/auth/
Scope: Node.js/Express, server-side, processes user credentials
Findings: CRITICAL 1 | HIGH 2 | MEDIUM 1 | LOW 0

[CRITICAL] SQL Injection in User Lookup

• CWE: CWE-89
• OpenCRE: CRE-764-507 — Injection Prevention
• OWASP Ref: A03:2021 Injection
• Location: src/auth/login.js:42
• Impact: Attacker can extract the entire users table, bypass authentication, or execute arbitrary SQL via crafted id parameter
• Evidence:
  root@kitploit:~

  // src/auth/login.js:42
  const user = await db.query("SELECT * FROM users WHERE id=" + req.params.id);
  

• Remediation: Use parameterized queries:
  root@kitploit:~

  const user = await db.query("SELECT * FROM users WHERE id = $1", [req.params.id]);
  

• Confidence: HIGH

Every skill produces structured findings with severity, CWE, evidence, and remediation code. See examples/ for complete sample assessment reports.

Plays

AI/Agent Security plays

The differentiator — security procedures purpose-built for the AI agent era. Bundled inside the ai-security-skills plugin.

Code & Dependency Analysis plays

Immediate, practical value for any codebase. Bundled inside the code-security-skills plugin.

Planned

• Tier 2: Threat modeling, ASVS verification, infrastructure hardening
• Tier 3: WSTG testing checklist, DAST orchestration, attack surface mapping
• Tier 5: SAMM maturity assessment, compliance mapping, aggregate reporting

Architecture

Three-layer design — every layer lives inside the plugin source folder so the marketplace install bundles everything the skills need:

• plugins/<name>/agents/ — Autonomous security specialists with focused system prompts, co-located inside each plugin. Each agent invokes one or more skills, operates in an isolated context, and produces structured reports. Can work solo or as a coordinated team.
• plugins/<name>/skills/ — Self-contained SKILL.md files following the Agent Skills spec. Distributed through plugins/code-security-skills/ and plugins/ai-security-skills/, registered in the marketplace via .claude-plugin/marketplace.json. Each skill summarizes a procedure and references its corresponding play inside the same plugin.
• plugins/<name>/plays/ — Full reference procedures with detailed checklists, tables, decision criteria, and examples. Skills reference these for comprehensive coverage.
• plugins/<name>/templates/ and plugins/<name>/data/ — Output templates (finding.md, ) and OWASP reference datasets (FIASSE v1.0.4, ASVS v5.0, secure-code prompts) that skills load at runtime.

Agents orchestrate, skills execute, plays provide the full procedure. Contributors edit plays. This means the playbook works with any AI agent (just point it at a play), while Claude Code users get plugin-based installation with agents and skills.

OWASP Foundation

All plays reference OWASP standards and datasets:

• OWASP Top 10 — Web application risks
• OWASP API Security Top 10 — API-specific risks
• OWASP Top 10 for LLM Applications — AI/LLM risks
• OWASP Agentic Security Initiative — Autonomous-agent risks (Top 10 for Agentic Applications)
• OWASP ASVS — Security verification requirements
• OWASP MASVS — Mobile Application Security Verification Standard
• OWASP AISVS — AI Security Verification Standard
• OWASP WSTG — Testing methodology
• OWASP SAMM — Security program maturity model
• OWASP Cheat Sheet Series — Developer security guidance
• OWASP FIASSE — Framework for Inherently Adaptive and Securable Engineering (v1.0.4)

Related Projects

Contributing

See CONTRIBUTING.md for detailed guidelines.

New plays should:

• Solve one well-defined security task
• Include clear trigger conditions (when should this play run?)
• Follow a structured procedure with checkpoints
• Produce findings using the in-plugin templates/finding.md format
• Reference OWASP standards where applicable
• Prefer existing tools (semgrep, trivy, osv-scanner, trufflehog) over reimplementing detection
• Live inside the appropriate plugin's plays/ folder so they ship with the marketplace install

License

Licensed under Creative Commons Attribution 4.0 International (CC-BY-4.0). See THIRD_PARTY_NOTICES.md for attribution of upstream OWASP project content.