USAP — Open-Source AI Cybersecurity Agent Skills

Signal Architecture · agents reason · humans approve · MCP executes

Website Skills Agents Domains Contract Frameworks License Python Last Commit usap-skills MCP server

Open-source cybersecurity skills library that turns any LLM into an auditable, portable security workflow runtime for SOC and AppSec teams.

Each SKILL.md is a complete LLM system prompt — paste into Claude, ChatGPT, Gemini, Ollama, or AnythingLLM with no install. Apache 2.0, typed 11-field output contract, framework-mapped (MITRE ATT&CK, NIST CSF 2.0, OWASP Top 10, ATLAS, D3FEND, NIST AI RMF), L1–L4 autonomy with explicit human-approval gates.

If this is useful, star the repo — it's the cheapest signal to send and the only one that drives discovery. Want to contribute? The open invitations in ROADMAP.md are picked tasks, not vague areas.

▶ See every pillar run with real, reproducible output → examples/ · Install on your platform → INSTALLATION.md

Try it in 60 seconds

Option 1 — Claude Code plugin (one command, no clone)

If you have Claude Code installed, type these two slash commands in any project:

/plugin marketplace add jaskaranhundal/usap-skills
/plugin install usap@usap

That activates 7 slash commands (/usap:run, /usap:fortigate, /usap:orchestrate, /usap:challenge, /usap:compare, /usap:test, /usap:README) and 6 user-invocable orchestrator skills (@usap-alex, @usap-ciso, @usap-devsecops, @usap-incident-responder, @usap-program-manager, @usap-red-teamer).

Smoke test it:

/usap:fortigate

Alex runs the AT + CA workflows against the bundled Fintech FortiGate zero-day scenario and produces a 7-task scorecard.

Option 2 — paste-into-any-LLM bundle (Claude.ai, ChatGPT, Gemini, Ollama)

git clone https://github.com/jaskaranhundal/usap-skills.git
cd usap-skills
python3 shared/scripts/bundle_usap.py bundle --mode lite   # → dist/USAP_LITE.md  (32 KB)
# python3 shared/scripts/bundle_usap.py bundle --mode pro  # → dist/USAP_PRO.md   (185 KB — Gemini 1.5 Pro / 2.0 Flash)
# python3 shared/scripts/bundle_usap.py bundle --mode full # → dist/USAP_BUNDLE.md (744 KB — Claude Opus / GPT-5 / Gemini 2.5 Pro)

Paste dist/USAP_LITE.md as the system prompt in any LLM. No npm, no Docker, no API key, no signup. The bundled file is one markdown blob that becomes Alex (cs-security-analyst) on any model.

Option 3 — interactive web demo (no install)

Open docs/design-system/ui_kits/platform/index.html in any browser for the 3-screen click-through (Landing → Agent Console → Findings).

Option 4 — MCP server (Cursor, Codex CLI, Gemini CLI, Goose, any MCP client)

USAP also runs as a stdlib-only Model Context Protocol server. Add to your client's MCP config:

{
  "mcpServers": {
    "usap": {
      "command": "python3",
      "args": ["/absolute/path/to/usap-skills/tools/mcp_server.py"]
    }
  }
}

Connect, then ask plain-English security questions — your client discovers and loads USAP skills and cs-* agents on demand. Read-only Phase 1 today; Phase 2 turns USAP into the master MCP routing security intents to downstream vendor MCPs (SIEM, EDR, firewall) with the contract's human_approval_required gate enforcing the human approval step. Full docs at docs/mcp-server.md.

Architecture

The diagram above is the architecture diagram — a Signal-Architecture-styled hex constellation with all 12 cs-* agents around the central USAP hub. Domain colour-coding on the border: security/ cyan · appsec/ violet · devsecops/ orange · executive/ blue · governance/ green. Regenerate with python3 tools/gen_architecture_svg.py.

flowchart LR
    SK["79 skills across<br/>12 domains<br/>(SKILL.md + scripts/)"]:::skill --> A
    subgraph A ["12 cs-* orchestrator agents"]
        direction TB
        subgraph S ["agents/security/"]
            S1[cs-security-analyst]
            S2[cs-incident-responder]
            S3[cs-red-teamer]
            S4[cs-blue-team-analyst]
            S5[cs-cloud-investigator]
            S6[cs-supply-chain-defender]
            S7[cs-threat-intel-lead]
            S8[cs-purple-team-lead]
        end
        subgraph P ["agents/appsec/"]
            P1[cs-appsec-engineer]
        end
        subgraph D ["agents/devsecops/"]
            D1[cs-devsecops-engineer]
        end
        subgraph E ["agents/executive/"]
            E1[cs-ciso-advisor]
        end
        subgraph G ["agents/governance/"]
            G1[cs-security-program-manager]
        end
    end
    A --> OUT["11-field JSON output contract<br/>agent_slug · intent_type · action<br/>rationale · confidence · severity<br/>key_findings · evidence_references<br/>next_agents · human_approval_required<br/>timestamp_utc"]:::out

    classDef skill fill:#06222b,stroke:#29d3f0,stroke-width:1px,color:#e6edf3
    classDef out fill:#1c2230,stroke:#d2a8ff,stroke-width:1px,color:#e6edf3

Skills are stateless prompt + tool packages (SKILL.md + stdlib scripts/). Orchestrator agents compose them via the v2 agent contract (standards/agent-contract.md). Every output validates against the typed 11-field contract (standards/output-contract.md).

Interactive UI kit: for the same flow as a clickable web demo (Landing → Agent Console → Findings), open docs/design-system/ui_kits/platform/index.html — built on the USAP Design System: Signal Architecture visual language, 10 React components, 160+ CSS tokens.

What a real payload looks like

Every skill emits the same shape. Below is a fully-populated payload from one run of vuln-scan against the in-repo SimpleStoreAPI fixture — all 11 required fields plus the optional tail (mitre_ttps, affected_assets, artifact_path). Byte-identical to appsec-devsecops/vuln-scan/expected_outputs/sample_output.json, validated against tools/output_contract.py in CI on every push.

{
  "agent_slug": "vuln-scan",
  "intent_type": "detect",
  "action": "Hand off to finding-triage — 4 mapped findings, 1 unmapped, top severity high.",
  "rationale": "Scanned SimpleStoreAPI against TM-001..TM-005. Found 5 distinct findings after dedup: hardcoded credential (TM-001 proximity 9), SQL string concat (TM-002 proximity 8), public S3 ACL (TM-002 proximity 7), permissive CORS (unmapped), missing input validation on /api/v1/profile (TM-001 proximity 9). Confidence dampened 0.05 per merge.",
  "confidence": 0.82,
  "severity": "high",
  "key_findings": [
    "VF-001 hardcoded-credential at src/config.py:14 — mapped to TM-001, proximity 9",
    "VF-002 sql-string-concat at src/db/profile.js:42 — mapped to TM-002, proximity 8",
    "VF-003 public-iac at infra/storage.tf:21 — mapped to TM-002, proximity 7",
    "VF-004 missing-input-validation at src/routes/profile.js:11 — mapped to TM-001, proximity 9",
    "VF-005 permissive-cors at src/middleware/cors.js:6 — UNMAPPED (no top-5 threat covers this)"
  ],
  "evidence_references": [
    {"source": "scanner", "ref": "src/config.py:14", "quote": "PASSWORD = \"changeme-prod\""},
    {"source": "scanner", "ref": "src/db/profile.js:42", "quote": "db.query('SELECT * FROM users WHERE id = ' + req.params.id)"},
    {"source": "scanner", "ref": "infra/storage.tf:21", "quote": "acl = \"public-read\""}
  ],
  "next_agents": ["finding-triage"],
  "human_approval_required": false,
  "timestamp_utc": "2026-06-20T10:30:00Z",
  "mitre_ttps": ["T1552.001", "T1190"],
  "affected_assets": ["SimpleStoreAPI"],
  "artifact_path": "/tmp/simple-store-api/VULN-FINDINGS.json"
}

The 11 required fields are: agent_slug, intent_type, action, rationale, confidence, severity, key_findings, evidence_references, next_agents, human_approval_required, timestamp_utc. Optional extras after that. The CI gate fails any committed sample that drops a required field.

Why USAP

New here? Read: USAP vs Prompt Libraries — why a SKILL.md is more than a folder of prompts.

• Open source, no SaaS, no waitlist. Apache 2.0. Drop the skills into Claude, ChatGPT, Gemini, Ollama, or AnythingLLM with no platform install. No vendor cloud, no per-seat pricing, no telemetry leaving your environment.
• Standardized 11-field output contract. Every skill emits CVSS, MITRE ATT&CK technique IDs, evidence references, and an explicit human_approval_required flag (standards/output-contract.md). Safe to embed in production agent stacks where competitor copilots remain black boxes.
• cs-* orchestrator agents. 12 named agents (cs-security-analyst, cs-incident-responder, cs-blue-team-analyst, cs-red-teamer, cs-cloud-investigator, cs-supply-chain-defender, cs-threat-intel-lead, cs-purple-team-lead, cs-appsec-engineer, cs-devsecops-engineer, cs-ciso-advisor, cs-security-program-manager) compose the skills into reproducible workflows.
• Framework-mapped at the metadata layer. metadata.frameworks.{mitre_attack, nist_csf, mitre_atlas, owasp_top10, d3fend, nist_ai_rmf} arrays drive auto-generated ATT&CK Navigator and NIST CSF coverage docs in mappings/ — never hand-maintained.
• L1–L4 autonomy model. Mutating intents (key rotation, isolation, account disablement) carry explicit human_approval_required: true gates. Predictable behaviour at every level.
• agentskills.io spec-conformant. Every USAP SKILL.md validates against the open standard (verified on 2026-06-20). Drop USAP into any agentskills.io-compatible client — Claude Code, Cursor, Goose, OpenCode, GitHub Copilot, Gemini CLI, OpenAI Codex CLI, and 30+ others.

Who is this for

USAP is built for three teams that already own LLM access and don't want to rent another SaaS:

• SOC and detection engineering teams (50–500-person security orgs) running Splunk / Sentinel + EDR who want a vetted, MITRE-mapped skills library to amplify analyst output. Activate cs-security-analyst for any alert; cascade to cs-blue-team-analyst, cs-threat-intel-lead, or cs-incident-responder.
• DevSecOps and platform-security engineers at engineering-led orgs who use Claude Code or similar. Embed cs-devsecops-engineer and cs-appsec-engineer in CI; route runtime findings into webapp-security/.
• MSSPs, security consultancies, and red teamers who need client-ready CVSS / MITRE / evidence-tagged deliverables. White-label the skills, embed in your own delivery stack, ship.

Demo: an end-to-end run

A real run of cs-appsec-engineer against the in-repo SimpleStoreAPI fixture. The animation above and the transcript below show the same data — every line of JSON is byte-identical to appsec-devsecops/vuln-scan/expected_outputs/sample_output.json. Regenerate the animation with python3 tools/gen_demo_svg.py.

You: Scan examples/SimpleStoreAPI for vulnerabilities and route any high findings to triage.

cs-appsec-engineer: Running vuln-scan against threat model TM-001..TM-005.

$ python3 appsec-devsecops/vuln-scan/scripts/vuln-scan_tool.py \
    --input examples/SimpleStoreAPI/scan-context.json --output json

{
  "agent_slug": "vuln-scan",
  "intent_type": "detect",
  "action": "Hand off to finding-triage — 4 mapped findings, 1 unmapped, top severity high.",
  "rationale": "Scanned SimpleStoreAPI against TM-001..TM-005. Found 5 distinct findings after dedup: hardcoded credential (TM-001 proximity 9), SQL string concat (TM-002 proximity 8), public S3 ACL (TM-002 proximity 7), permissive CORS (unmapped), missing input validation on /api/v1/profile (TM-001 proximity 9). Confidence dampened 0.05 per merge.",
  "confidence": 0.82,
  "severity": "high",
  "key_findings": [
    "VF-001 hardcoded-credential at src/config.py:14 — mapped to TM-001, proximity 9",
    "VF-002 sql-string-concat at src/db/profile.js:42 — mapped to TM-002, proximity 8",
    "VF-003 public-iac at infra/storage.tf:21 — mapped to TM-002, proximity 7",
    "VF-004 missing-input-validation at src/routes/profile.js:11 — mapped to TM-001, proximity 9",
    "VF-005 permissive-cors at src/middleware/cors.js:6 — UNMAPPED (no top-5 threat covers this)"
  ],
  "evidence_references": [
    {"source": "scanner", "ref": "src/config.py:14", "quote": "PASSWORD = \"changeme-prod\""},
    {"source": "scanner", "ref": "src/db/profile.js:42", "quote": "db.query('SELECT * FROM users WHERE id = ' + req.params.id)"},
    {"source": "scanner", "ref": "infra/storage.tf:21", "quote": "acl = \"public-read\""}
  ],
  "next_agents": ["finding-triage"],
  "human_approval_required": false,
  "timestamp_utc": "2026-06-20T10:30:00Z"
}

cs-appsec-engineer: Severity is high, next_agents points at finding-triage. Handing off.

Synthesis (operator-facing):

Five findings, four mapped to your threat model. The hardcoded production credential (src/config.py:14) and the SQL string concatenation on the profile route are both proximity-9 hits against TM-001 — patch first. The public S3 bucket ACL is a separate proximity-7 TM-002 hit. The permissive CORS rule is unmapped, which usually means your threat model is incomplete — recommend revisiting TM coverage. No mutating actions taken; human_approval_required was false because this was a read-only detect.

Try it yourself:

python3 appsec-devsecops/vuln-scan/scripts/vuln-scan_tool.py --output json | jq .
python3 tools/output_contract.py appsec-devsecops/vuln-scan/expected_outputs/sample_output.json

Proof: every claim is a file in this repo

ATT&CK Navigator layer (excerpt)

The full layer at mappings/mitre-attack/attack-navigator-layer.json opens directly in MITRE's Navigator. Excerpt of the first two techniques:

{
  "name": "USAP MITRE ATT&CK Coverage",
  "versions": {
    "attack": "16",
    "navigator": "4.9.5",
    "layer": "4.5"
  },
  "domain": "enterprise-attack",
  "techniques": [
    {
      "techniqueID": "T1041",
      "score": 1,
      "color": "",
      "comment": "USAP skills covering: detection/threat-intelligence",
      "enabled": true,
      "metadata": [],
      "links": [],
      "showSubtechniques": true
    },
    {
      "techniqueID": "T1046",
      "score": 1,
      "color": "",
      "comment": "USAP skills covering: detection/threat-hunting",
      "enabled": true,
      "metadata": [],
      "links": [],
      "showSubtechniques": true
    }
  ]
}

NIST CSF 2.0 coverage (excerpt)

From mappings/nist-csf/csf-alignment.md:

These tables are not hand-maintained. They are emitted by tools/framework_extractor.py from each skill's metadata.frameworks.* arrays. The CI pipeline fails any PR that ships a drift between the source frontmatter and the generated docs.

Quick Start

One agent. Any security question. Paste and go.

Generate your kit:

python3 shared/scripts/bundle_usap.py bundle --mode lite   # → dist/USAP_LITE.md
python3 shared/scripts/bundle_usap.py bundle --mode pro    # → dist/USAP_PRO.md
python3 shared/scripts/bundle_usap.py bundle --mode full   # → dist/USAP_BUNDLE.md

How Alex works

Alex (cs-security-analyst) is the single entry point for all three kits. You do not need to know which agent or skill to use — Alex figures that out.

• Lite: Alex answers directly from knowledge of all 79 USAP skills. Plain English by default; goes fully technical when you ask.
• Pro / Full: Alex detects multi-domain problems, activates party mode (OR), delegates to specialist agents (cs-incident-responder, cs-ciso-advisor, etc.), and synthesizes one unified answer.
• Any LLM: Paste the file as your system prompt. No install required.
• Future: MCP connectors will let Alex pull live cloud inventory, SIEM, and EDR data automatically. Until then, paste logs or describe your environment.

Use with Gemini

Three ways — pick the one that fits your setup:

Option 1: Google AI Studio (free, no code)

1. Go to aistudio.google.com
2. Click Create new prompt → set type to Chat
3. Paste the contents of dist/USAP_LITE.md into the System instructions field
4. Start chatting with Alex

Option 2: Gemini Gems (Gemini Advanced)

1. Go to gemini.google.com → Gems → Create a Gem
2. Name: USAP Security Advisor
3. Instructions: paste the contents of dist/USAP_LITE.md
4. Save and chat

Option 3: Python script (Gemini API)

# Install the SDK
pip install google-generativeai

# Set your API key (get one free at aistudio.google.com)
export GEMINI_API_KEY="your-key-here"

# Start a chat session with Alex
python3 shared/scripts/gemini_chat.py --kit lite

# Use the pro kit (Alex + all 6 specialist agents)
python3 shared/scripts/gemini_chat.py --kit pro

# Use a different model
python3 shared/scripts/gemini_chat.py --kit lite --model gemini-1.5-pro

Kit size guide:

Use as CLI commands

USAP agents are registered as native slash commands in both Gemini CLI and Claude Code.

Gemini CLI

npm install -g @google/gemini-cli
cd usap-skills
gemini          # GEMINI.md auto-loaded
/usap-alex      # Activate cs-security-analyst

Claude Code

cd usap-skills
claude          # CLAUDE.md auto-loaded
/usap-alex      # Activate cs-security-analyst

Available commands

Which agent for which problem?

Active incident in progress

Credentials and identity

Threats and hunting

Vulnerabilities and patching

Cloud and infrastructure

Detection and engineering

Architecture and design

Compliance and governance

Supply chain and third parties

Red team and adversary simulation

Operations and reporting

Orchestrator Agents

7 cs-* agents that coordinate multiple skills into role-specific workflows:

See agents/CLAUDE.md for the agent development guide.

Domain Index

All 79 skills

Standalone use (no USAP required)

Paste any SKILL.md into your LLM as the system prompt, then send a security event as the user message.

# View a SKILL.md
cat secrets-exposure/SKILL.md

# Minimal user message structure
{
  "event_type": "secret_exposure",
  "severity": "critical",
  "raw_payload": {
    "file_path": "config/prod.env",
    "matched_pattern": "aws_access_key",
    "branch": "main"
  }
}

The LLM returns a structured JSON recommendation with action, rationale, intent_type, confidence, key_findings, evidence_references, and timestamp_utc.

Use with USAP

This repo is the default skills/ submodule in the USAP platform.

# Clone USAP with all public skills
git clone --recurse-submodules https://github.com/jaskaranhundal/usap.git

# To add private bug bounty skills alongside:
git submodule add https://github.com/jaskaranhundal/usap-bugbounty skills-bb
echo "USAP_SKILLS_PATHS=./skills,./skills-bb" >> .env
python3 -m usap.cli validate-agents   # 79 skills + 12 cs-* agents valid

Skill package structure

<slug>/
  SKILL.md                              # LLM system prompt + YAML frontmatter
  README.md                             # This file — what the agent does
  references/
    workflow.md                         # Step-by-step analyst workflow
    *.md                                # Domain-specific reference documents
  assets/
    templates/
      output-template.json              # Output schema template
  expected_outputs/
    sample_output.json                  # Representative output example
  scripts/
    <slug>_tool.py                      # CLI tool
    pre_analysis.py                     # Optional: deterministic pre-analysis

Shared utilities

shared/scripts/ contains tools used across multiple skill packages:

See shared/README.md for usage.

Contributing

To add a new agent, open a PR against this repo. See CONTRIBUTING.md for the full authoring guide including frontmatter requirements, SKILL.md body structure, and quality bar.

License

Apache 2.0 — see LICENSE.

Privacy

This plugin does not collect, store, or transmit any user data. All processing happens locally within your Claude Code session. No telemetry, no analytics, no external API calls are made by the plugin itself.

Contact: [email protected]