security-analyst

Security Analyst

Repository: https://github.com/paixaop/security-analyst

Comprehensive security analysis suite that identifies vulnerabilities, assesses exploitability, and generates actionable remediation plans. Coordinates specialized agents through a multi-phase pipeline — built for developers and security researchers who want depth, not checkbox compliance.

When to Use

• Before deploying to production or after major feature work
• When a security audit or penetration test is requested
• After a vulnerability is reported, to find unpatched variants
• To generate a threat model for compliance or planning
• To create a fix plan from an existing security report
• To generate a Software Bill of Materials (SBOM) for compliance
• To map findings against SOC 2, ISO 27001, PCI DSS, HIPAA, or GDPR controls
• To compare security posture between two analysis runs (delta/regression tracking)
• To conduct a privacy and data protection assessment (PII flows, consent, data subject rights)

Available Commands

Command	Purpose	Agents	Output
/security-analyst	Interactive — choose scope and output mode	Varies	Varies
/security-analyst:full	All 9 phases, all attack surfaces	23+	Full run directory
/security-analyst:focused [component]	Target a specific area (e.g., authentication, data pipeline)	3-6	Inline findings
/security-analyst:recon	Phase 0 only — codebase security map	14 (parallel)	Recon index + step files
/security-analyst:threat-model	Recon + STRIDE analysis + attack trees	1+	Threat model doc
/security-analyst:variant-hunt [vuln]	Find all unpatched variants of a known vulnerability	2-6	Variant findings
/security-analyst:fix-plan [run-dir]	Generate implementation plan from existing report	1	Fix plan
/security-analyst:sbom	Software Bill of Materials — recon + dependency audit only	15	SBOM report
/security-analyst:diff [run-a] [run-b]	Compare two runs — new, resolved, persistent findings	1	Delta report
/security-analyst:compliance [framework]	Map findings to SOC 2 / ISO 27001 / PCI DSS / HIPAA / GDPR	1	Compliance report
/security-analyst:privacy	Privacy assessment — PII flows, consent, data subject rights	15+	Privacy report

How It Works

Group-Based Pipeline

Analysis runs in dependency-ordered execution groups. Each group's findings feed the next. Groups are execution-order groupings of phases. Finding IDs use category prefixes (HTTP, INJ, DEP, etc.).

Recon: Reconnaissance (14 agents, all parallel — 2 waves)
  └─ Wave A (12 agents, batch-spawned): metadata, docs, HTTP, boundaries, crown jewels, auth, integrations, secrets, security work, config, frontend, deps
  └─ Wave B (2 agents, batch-spawned): data flows, scope notes (depend on Wave A)
  └─ Assembly: orchestrator builds recon/index.md from LOD-0+1 returns

Surface: Attack Surface + Git History + Dependencies + Config (up to 16 agents, batch-spawned in parallel)
  ├─ HTTP entry points, authz rules, integrations, frontend
  ├─ LLM/AI security (OWASP Top 10 for LLM Applications)
  ├─ API schema validation (OpenAPI, GraphQL, gRPC)
  ├─ WebSocket / SSE real-time security
  ├─ File upload security
  ├─ Injection/auth/SSRF/data-exposure variant hunting via git history
  ├─ Dependency audit (npm audit, supply chain)
  ├─ Infrastructure config, secrets, KMS, IAM
  ├─ CI/CD pipeline security (GitHub Actions, GitLab CI)
  └─ Container security (Docker, Kubernetes)

┌─ SBOM Assembly (orchestrator, no agent — runs in parallel with logic stage)
│
Logic: Business Logic (4 agents batch-spawned, needs surface stage)
  ├─ Race conditions and TOCTOU
  ├─ Authorization escalation and IDOR
  ├─ Pipeline exploitation (input → AI → decision → action)
  └─ DoS and resource exhaustion

Tracing: Data Flow Tracing (up to 4 agents batch-spawned, needs surface + logic)
  └─ End-to-end trace of critical data flows with sanitization gap analysis

Exploits: Exploit Development (1 agent, needs all findings)
  └─ Develops complete exploits with PoCs, CVSS scores, CWE/ATT&CK IDs, chains

Validation: Finding Validation (1 critic agent)
  └─ Adversarial review — catches false positives, validates fixes, adjusts severity

Reporting: Final Report (1 agent)
  └─ Executive summary, risk dashboard, remediation roadmap

Remediation: Fix Plan (1 agent)
  └─ Actionable tasks with fix code, regression tests, effort estimates

Finding Format

Every Medium+ finding includes: CVSS 3.1 score, CWE ID, MITRE ATT&CK technique, exploit scoring (exploitability/blast radius/detectability/remediation ROI), attack steps, proof-of-concept, concrete fix code, and regression test.

Output Directory

Full runs write to docs/security/runs/{YYYY-MM-DD-HHMMSS}/:

File	Content
recon/index.md	Recon LOD-0 + LOD-1 index
recon/step-*.md	14 atomic LOD-2 recon section files
findings/	Atomic LOD-2 finding files + index
reports/surface.md	Attack surface, git history, deps, config
reports/sbom.md	Software Bill of Materials (deps, licenses, supply chain)
reports/logic.md	Business logic exploitation
reports/tracing.md	Data flow tracing
reports/exploits.md	Exploit catalog with PoCs
reports/validation.md	Validated findings
reports/final.md	Complete security report
reports/fix-plan.md	Implementation plan
reports/compliance.md	Compliance mapping (when requested)
reports/delta.md	Delta between two runs (when requested)
reports/privacy.md	Privacy & data protection assessment (when requested)

Command Details

Full Analysis

Runs all 9 phases with no prompts. Most thorough — spawns up to 28+ agents across 6 execution groups. Expect significant processing time.

/security-analyst:full

Focused Analysis

Analyzes a specific component with only relevant agents. Faster (3-6 agents) but still thorough within scope. Findings presented inline — no separate report.

/security-analyst:focused authentication
/security-analyst:focused data processing pipeline
/security-analyst:focused frontend
/security-analyst:focused database rules
/security-analyst:focused AI integration
/security-analyst:focused CI/CD
/security-analyst:focused containers
/security-analyst:focused API
/security-analyst:focused real-time
/security-analyst:focused file uploads

Reconnaissance Only

Quick security map without vulnerability analysis. Good for orientation before a full audit or for manual review planning.

/security-analyst:recon

Threat Model

Recon plus STRIDE analysis on each trust boundary, attack trees for each crown jewel, and a risk matrix. Useful for compliance (SOC 2, ISO 27001) and security planning.

/security-analyst:threat-model

Variant Hunt

Given a known vulnerability (commit hash, CVE, or description), systematically finds all unpatched variants using git history mining and pattern analysis.

/security-analyst:variant-hunt 6dc9bb7
/security-analyst:variant-hunt OData injection
/security-analyst:variant-hunt CVE-2024-XXXX

Software Bill of Materials

Generates a compliance-ready SBOM covering all languages, frameworks, direct and transitive dependencies, licenses, and supply chain health indicators. Runs recon plus the dependency audit agent only — no exploitation or attack surface analysis.

/security-analyst:sbom

Delta Report

Compares two security analysis runs to highlight new, resolved, and persistent findings. Tracks dependency changes, attack surface evolution, and fix plan progress. Auto-detects the two most recent runs or accepts specific run directories.

/security-analyst:diff
/security-analyst:diff docs/security/runs/2025-06-01-100000 docs/security/runs/2025-06-15-143022

Compliance Mapping

Maps findings from an existing security run to a compliance framework. Assesses each control as Pass/Partial/Fail/N/A and produces a compliance score with gap analysis.

/security-analyst:compliance soc2
/security-analyst:compliance iso27001
/security-analyst:compliance pci-dss
/security-analyst:compliance hipaa
/security-analyst:compliance gdpr

Privacy Assessment

Traces all PII data flows, evaluates consent mechanisms, checks data subject rights implementation (access, erasure, portability), reviews data retention and deletion, and assesses cross-border transfers. Can run standalone or enrich an existing security run.

/security-analyst:privacy

Fix Plan

Generates an implementation plan from an existing security report. Auto-detects the latest run or accepts a specific run directory. Tasks are prioritized: Quick Wins, Immediate, Short-term, Medium-term, Backlog.

/security-analyst:fix-plan
/security-analyst:fix-plan docs/security/runs/2025-06-15-143022

Architecture

For detailed architecture reference (directory structure, agent design, LOD architecture, customization), see references/architecture.md. For all constants (paths, filenames, agent registry, placeholders), see references/constants.md. For platform-specific tool mapping (Cursor vs Claude Code vs Codex) and hang prevention, see references/platform-tools.md.

Key concepts:

• LOD system: Three-tier Level of Detail (LOD-0/1/2) saves 80-96% of prompt tokens for downstream agents while preserving full detail on disk
• Group discipline: Later groups depend on earlier findings; never start a group early
• Dynamic scoping: Recon determines which agents to skip
• Framework plugins: 16 auto-detected plugins inject framework-specific checks into agent prompts. See references/plugins/README.md
• Critic validation: Adversarial review catches false positives before the final report

Before You Install

This skill performs comprehensive security analysis. It instructs agents to read large portions of your repository (including environment and secrets files), run dependency auditors, mine git history, and write proof-of-concept reproductions and reports to disk. Before installing or running it:

1. Only run on codebases you control — You must have explicit permission to perform security testing on the target project and environment.
2. Use an isolated workspace — Run inside a disposable environment, not a production system or a workspace containing real credentials. If you must analyze a production codebase, clone it into a sandboxed directory first.
3. Expect persistent artifacts — Generated PoCs, exploit chains, and fix code are written to docs/security/runs/ by default. Choose a safe output directory (configurable in references/constants.md), review artifacts promptly, and delete or secure them after triage.
4. Verify tooling availability — The skill requires git and benefits from npm audit, pip-audit, govulncheck, and other ecosystem tools. See Requirements for the full list and fallback behavior.
5. Run supervised first — If you are unsure about scope or safety, do not enable autonomous invocation. Run a manual, supervised test on a throwaway repository before trusting it on a real codebase. The /security-analyst:recon command is a good low-risk starting point — it maps the codebase without producing exploits.

Installation

Copy or symlink this skill folder to your skills directory:

# Claude Code
cp -r . ~/.claude/skills/security-analyst

# Cursor
cp -r . ~/.cursor/skills/security-analyst

# OpenAI Codex (if applicable)
cp -r . $CODEX_HOME/skills/security-analyst

Requirements

Workspace Access

The skill requires read access to the project codebase and write access to the project directory. Agents use Read, Grep, and Glob to analyze source files, and full runs write output to docs/security/runs/{YYYY-MM-DD-HHMMSS}/ inside the project workspace. The project being analyzed must be the current working directory.

Platform Tools

All agents are spawned as generalPurpose subagents via the Task tool and require:

Tool	Purpose
Task	Spawn and coordinate subagents (Claude Code, Cursor, Codex)
Bash / Shell	Run git commands, dependency auditors, and inline scripts
Read	Read source files, configs, lockfiles, and prior-stage outputs
Grep	Search for patterns across the codebase
Glob	Find files by name/extension patterns
Write	Write findings, reports, and recon step files to the run directory

See references/platform-tools.md for platform-specific availability (Cursor vs Claude Code vs Codex).

Required: git

Git is a hard dependency. Four agents mine git history (git log, git diff, git show, git blame) to find unpatched vulnerability variants. The dependency audit agent uses git ls-files to verify lockfile integrity. The variant-hunt command relies entirely on git history analysis. If the project is not a git repository, history-based agents will produce no findings and the variant-hunt command will not function.

Language-Specific Auditors (used when available)

The dependency audit agent attempts to run vulnerability scanners for detected package ecosystems. These tools are not required — if unavailable, the agent falls back to static analysis of manifest and lockfiles, but automated CVE detection will be less thorough.

Ecosystem	Tool	Invocation	Fallback
Node.js	npm	npm audit --json	Parse package.json + package-lock.json directly
Python	pip-audit	pip-audit --json	Parse requirements.txt / pyproject.toml directly
Go	govulncheck	govulncheck ./...	Parse go.mod / go.sum directly

The agent also runs inline Node.js scripts (via node -e) to extract license data from node_modules/ when present. No global npm packages are installed — only project-local tooling is used.

SBOM Export Tools (optional)

The SBOM report template references machine-readable export tools. These are documentation-only recommendations — the skill does not attempt to run them automatically. The SBOM report is always generated from the dependency audit agent's static analysis regardless of whether these tools are installed.

Format	Tool
CycloneDX	npx @cyclonedx/cyclonedx-npm, cyclonedx-py, cyclonedx-gomod
SPDX	spdx-sbom-generator, syft

Credentials

No credentials, API keys, or authentication tokens are required. All analysis is performed locally against the project source code and git history. The compliance and privacy commands assess implementation by reading code — they do not connect to external compliance platforms.

Security & Safety Considerations

This skill performs deep security analysis. By design, it reads broadly, looks for weaknesses, and produces proof-of-concept reproductions. The following sections describe the data and safety surfaces so users can make an informed decision before running it.

Instruction Scope — Broad Read Access

Agents are instructed to read all files in the project workspace, including source code, configuration, environment files, lockfiles, CI/CD pipelines, Dockerfiles, and infrastructure-as-code. This is inherent to security analysis — the skill cannot find vulnerabilities in code it cannot read. Specific high-sensitivity reads include:

• Secret scanning: Agents grep for patterns like API_KEY=, SECRET=, PASSWORD=, and read .env* files, credentials* files, and config files to identify hardcoded secrets. The config-infrastructure agent is explicitly instructed to redact the actual secret in findings — only file paths and pattern types are reported, not secret values.
• Git history mining: Four agents run git log, git diff, and git show to find previously-fixed vulnerabilities and check for incomplete remediation. This can surface deleted secrets that persist in git history.
• Absolute file paths with line numbers: Recon agents record exact file locations so downstream agents can Read specific code without re-scanning. This is an efficiency optimization, not a privilege escalation — agents already have workspace-wide read access via the platform's Read/Grep/Glob tools.

The scope is the project workspace only. Agents do not read files outside the current working directory, do not access the network, and do not read host system files.

Install Mechanism — Instruction Only

This skill contains no executable code, install scripts, or downloaded binaries. It consists entirely of markdown instruction files (prompts, templates, references) that are read by the orchestrator and injected into agent prompts. The risk surface is in what the instructions ask agents to do at runtime, not in installation.

Credential Discovery vs. Credential Use

The skill instructs agents to discover and report on credentials found in the codebase as part of the security audit. It does not use, exfiltrate, or test discovered credentials against external services. Specifically:

What agents do	What agents do NOT do
Grep for secret patterns in source and config files	Use discovered secrets to authenticate to any service
Read .env files to check if they are gitignored	Send secret values to external endpoints
Check git history for accidentally committed secrets	Store raw secret values in findings
Report the file path and pattern type of exposed secrets	Execute discovered credentials
Assess whether secret management (Vault, KMS, etc.) is used	Access cloud metadata endpoints or secret managers

The config-infrastructure agent prompt (line 115) explicitly mandates: "Plaintext secret findings are automatically High severity — include the file path (redact the actual secret)." However, since agents interpret these instructions at runtime, redaction is best-effort. Users handling highly sensitive codebases should review the findings/ directory after a run and before sharing reports.

Persistent Artifacts — Exploit PoCs on Disk

Full analysis runs write output to docs/security/runs/{YYYY-MM-DD-HHMMSS}/ containing:

• Exploit PoCs: The finding template requires Medium+ findings to include "concrete exploit code, curl command, or crafted payload" sufficient to reproduce the vulnerability.
• Exploit chains: The exploit developer agent produces multi-step attack chains combining individual findings.
• Fix code: Each finding includes concrete remediation code and regression tests.

These are text-based descriptions and code snippets in markdown files, not standalone executable scripts. They are no more executable than a security advisory with sample payloads. Nevertheless, they represent sensitive security knowledge about the analyzed project.

Recommendations for managing run artifacts:

1. Add to .gitignore — Consider adding docs/security/runs/ to .gitignore to prevent accidental commits of security findings to shared repositories.
2. Restrict access — Treat run directories with the same access controls as penetration test reports. Share on a need-to-know basis.
3. Clean up after review — Delete run directories after findings have been triaged, remediated, and verified. The /security-analyst:diff command can compare runs before cleanup to confirm resolution.
4. Custom output directory — The output path is defined in references/constants.md (RUN_DIR). Change it to write outside the project tree if preferred (e.g., to a directory not tracked by version control).

Activation

The skill sets always: false in its frontmatter. It only activates when the user explicitly requests a security audit, penetration test, threat model, vulnerability scan, SBOM, compliance mapping, or privacy assessment. It does not run automatically on every conversation.

Troubleshooting

Skill doesn't trigger on security-related requests

• Ensure the description includes your trigger phrase. Try: "run a security audit", "penetration test", "threat model", "vulnerability scan", "SBOM", "compliance mapping"

Analysis hangs / model waits forever

• On Cursor: the orchestrator may be trying to call TaskList or TaskCreate — these don't exist on Cursor. Read references/platform-tools.md for the correct flow.
• On Claude Code / Codex: each Task call should block until the agent returns. If it hangs, check that agent prompts include "Return your LOD-0 + LOD-1 summary in your final message."

MCP or subagent connection fails during analysis

• Verify the environment supports subagent spawning (Claude Code Task tool, Cursor Task tool)
• Check that the project being analyzed is the current workspace so recon agents can Read/Glob the codebase

Findings seem generic or lack concrete exploits

• The skill expects findings to include attack steps and PoC. If outputs are shallow, re-run with a focused scope (e.g., /security-analyst:focused authentication) for deeper analysis