{
  "markdown": "# oh-my-secuaudit\n\nSecurity skill collection for Claude Code and Codex workflows.\n\n## Install (Claude Code)\n\nThis repo is packaged as a Claude Code plugin marketplace named `windshock`. The plugin name is `oh-my-secuaudit`.\n\n```\n/plugin marketplace add windshock/oh-my-secuaudit\n/plugin install oh-my-secuaudit@windshock\n```\n\nTo develop locally against this checkout:\n\n```\n/plugin marketplace add /Users/<you>/path/to/oh-my-secuaudit\n/plugin install oh-my-secuaudit@windshock\n```\n\nAfter install, the six SKILL.md files become discoverable to Claude Code by their frontmatter `description` and trigger automatically when relevant work appears.\n\n## Layout\n\nSkills live under `plugins/oh-my-secuaudit/skills/` (Claude Code plugin convention: `<plugin-root>/skills/<skill-name>/SKILL.md`). Category groupings (architect / runtime / static / external / methodology) live in this README, not in directory paths.\n\n- `plugins/oh-my-secuaudit/skills/sec-audit-static` *(static)*: SAST/SCA/secret/reporting workflow\n- `plugins/oh-my-secuaudit/skills/sec-cluster` *(static)*: security code clustering workflow (v4 dataflow-based)\n- `plugins/oh-my-secuaudit/skills/sec-audit-dast` *(runtime)*: runtime/API assessment workflow (DAST/ASM)\n- `plugins/oh-my-secuaudit/skills/external-software-analysis` *(external)*: third-party software/binary analysis workflow\n- `plugins/oh-my-secuaudit/skills/security-architecture-review` *(architect)*: security architecture review workflow\n- `plugins/oh-my-secuaudit/skills/security-testing-as-code` *(methodology)*: assessment-as-project workflow (PoC, evidence, handoff)\n\n## Capability Matrix\n\n| Skill | Primary Question | Typical Input | Primary Output | Consumed By |\n|---|---|---|---|---|\n| `sec-audit-static` | What is vulnerable in source code and dependencies? | source repo | finding JSON, task/final report JSON, markdown report, `reporting_summary` | `security-architecture-review` |\n| `sec-cluster` | Which code paths share the same security review strategy? | source repo + static findings | CLUSTERS.md, semgrep rules, REVIEW_CHECKLIST.md | `sec-audit-static`, `security-architecture-review` |\n| `sec-audit-dast` | What is exposed or exploitable at runtime? | domains/IPs/endpoints/ASM exports | SARIF/CSV findings, finding JSON, `reporting_summary` | `security-architecture-review` |\n| `external-software-analysis` | What risks exist in third-party binaries/packages? | jar/aar/so/external package | markdown report, finding JSON, architecture handoff markdown, `reporting_summary` | `security-architecture-review` |\n| `security-architecture-review` | How do all findings affect trust boundaries and critical flows? | static/dast/external outputs + repo evidence | `security-architecture-review.md` + `security-product-requirements.md` (tracked backlog and lifecycle delta) | final artifact |\n| `security-testing-as-code` | How to make assessment results reproducible and inheritable? | assessment findings + PoC code | project structure (artifacts/poc/, artifacts/runtime/, handoff-plan.md) | any producer skill |\n\n## End-to-End Relationship Map\n\n```mermaid\nflowchart LR\n    subgraph L0[\"Layer 0: Threat Context (Manual, Non-Automated)\"]\n        T[\"External threat research (advisories, KEV/CVE trends, abuse intel)\"]\n    end\n\n    subgraph L1[\"Layer 1: Producer Runs\"]\n        S[\"sec-audit-static\"]\n        CL[\"sec-cluster\"]\n        D[\"sec-audit-dast\"]\n        E[\"external-software-analysis\"]\n    end\n\n    subgraph LM[\"Layer M: Methodology\"]\n        STAC[\"security-testing-as-code\"]\n    end\n\n    subgraph L2[\"Layer 2: Contract Normalization\"]\n        N[\"Normalize findings: finding_id, severity, provenance, impacted_flow\"]\n    end\n\n    subgraph L3[\"Layer 3: Architecture Synthesis\"]\n        R[\"security-architecture-review\"]\n    end\n\n    subgraph L4[\"Layer 4: Outputs and Lifecycle\"]\n        O[\"security-architecture-review.md\"]\n        P[\"security-product-requirements.md (SPR backlog + delta)\"]\n        FB[\"Feedback scope: missing evidence, boundary gaps, flow-specific follow-up\"]\n    end\n\n    S -->|required| N\n    CL -.->|clustering context| S\n    CL -.->|cluster-to-scenario mapping| R\n    D -->|required| N\n    E -->|required| N\n    E -.->|optional enrichment| EH[\"external-analysis-architecture-handoff.md\"]\n    T -.->|manual threat context| R\n    STAC -.->|project structure & PoC packaging| S\n    STAC -.->|project structure & evidence packaging| D\n\n    N -->|required| R\n    EH -.->|optional enrichment| R\n\n    R -->|required| O\n    R <--> |continuous requirement lifecycle| P\n\n    O -->|gap-based follow-up| FB\n    P -->|SPR-driven priorities| FB\n\n    FB -.->|targeted re-scan| S\n    FB -.->|targeted re-scan| D\n    FB -.->|targeted re-analysis| E\n    FB -.->|new threat questions| T\n\n    classDef static fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;\n    classDef runtime fill:#fff3e0,stroke:#ef6c00,color:#e65100;\n    classDef external fill:#e3f2fd,stroke:#1565c0,color:#0d47a1;\n    classDef threat fill:#ffebee,stroke:#c62828,color:#b71c1c;\n    classDef review fill:#fff8e1,stroke:#f9a825,color:#e65100;\n    classDef contract fill:#eceff1,stroke:#455a64,color:#263238;\n    classDef artifact fill:#f5f5f5,stroke:#616161,color:#212121;\n    classDef feedback fill:#e0f2f1,stroke:#00695c,color:#004d40;\n\n    classDef cluster fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c;\n    classDef methodology fill:#e8eaf6,stroke:#283593,color:#1a237e;\n\n    class T threat;\n    class S static;\n    class CL cluster;\n    class D runtime;\n    class E,EH external;\n    class N contract;\n    class R review;\n    class O,P artifact;\n    class FB feedback;\n    class STAC methodology;\n```\n\nLegend:\n- Green: static producer flow\n- Purple: clustering (code pattern grouping)\n- Orange: runtime producer flow\n- Blue: external producer flow\n- Red: external threat context (manual/non-automated input)\n- Indigo: methodology (assessment-as-code)\n- Yellow: architecture synthesis\n- Gray: contract normalization and artifacts\n- Teal: feedback loop to producers\n- Solid arrow: required handoff\n- Dashed arrow: optional enrichment or iterative feedback\n- Double arrow: continuous lifecycle synchronization\n\n## Handoff Contract (Why It Matters)\n\n- `security-architecture-review` is not another scanner.\n- It is the synthesis layer that merges heterogeneous evidence and decides:\n  - which risks are architecture-confirmed\n  - which are external/runtime-only\n  - which remain `not-confirmed`\n- Cross-skill normalization relies on these fields:\n  - `finding_id` (or `id`)\n  - `severity`\n  - `provenance` (`binary-confirmed|source-confirmed|runtime-confirmed|not-confirmed`)\n  - `impacted_flow` (e.g. `F1`, `F2`)\n\n## Minimal Artifact Set For Architecture Review\n\n| Source Skill | Required For Synthesis | Recommended |\n|---|---|---|\n| `sec-audit-static` | finding JSON with required fields, `reporting_summary` | markdown report and taint/source-sink notes |\n| `sec-audit-dast` | finding JSON or normalized runtime findings with required fields, `reporting_summary` | SARIF and reproducible probe metadata |\n| `external-software-analysis` | finding JSON with required fields | `external-analysis-architecture-handoff.md` |\n| external threat research (manual) | not required for run completion | threat themes from advisories/intel mapped to attack scenarios |\n\n## Architecture-to-Product Bridge\n\n- `security-architecture-review` converts High/Critical risks and unresolved gaps into `SPR-*` requirements.\n- Each `SPR-*` must include owner, target milestone, status, and testable acceptance criteria.\n- Requirement status is updated on every architecture run with a delta:\n  - `added`, `updated`, `closed`, `deferred`, `accepted-risk`\n\n## Which Skills To Run\n\n| Situation | Run |\n|---|---|\n| Source repository audit | `sec-audit-static` -> `security-architecture-review` |\n| External endpoint/runtime assessment | `sec-audit-dast` -> `security-architecture-review` |\n| Third-party binary/package risk | `external-software-analysis` -> `security-architecture-review` |\n| Full blended assessment | `sec-audit-static` + `sec-audit-dast` + `external-software-analysis` -> `security-architecture-review` |\n\n## Recommended Orchestration\n\n1. Run producer skills (`static`, `runtime`, `external`) in parallel where possible.\n2. Normalize findings with the common contract (`finding_id`, `severity`, `provenance`, `impacted_flow`).\n3. Add manual external threat research themes and map them to candidate attack scenarios.\n4. Run `security-architecture-review` to map findings into DFD nodes, trust boundaries, and attack scenarios.\n5. Generate a feedback plan from architecture gaps (missing evidence, unresolved boundaries, uncertain flows, new threat questions).\n6. Re-run producers with focused scope from the feedback plan, then re-run architecture review.\n7. Upgrade `provenance` only when new direct evidence exists.\n\n## Closed-Loop Model (Producer <-> Architecture)\n\n1. Producers find candidates and initial confirmations.\n2. Architecture review synthesizes system-level risk and identifies confirmation gaps.\n3. Gaps are translated into targeted producer actions (new rules, new probes, deeper binary/source tracing).\n4. Producers return refined evidence.\n5. Architecture review updates DFD/Attack Flow and confidence.\n6. Repeat until major gaps are closed.\n\n## Quality Gates Before Final Report\n\n1. Every imported finding has `provenance` and `impacted_flow`.\n2. External runtime-hop components (e.g. RP relay, mobile SDK) appear explicitly in DFD node/edge/boundary mapping.\n3. Attack Flow scenarios map back to scenario IDs and imported finding IDs.\n4. `Confidence & Gaps` clearly lists unresolved confirmation items.\n\n## Developer Workflow\n\n- Run local validation: `just check` (or `python3 scripts/validate_skills_repo.py`)\n- CI runs the same contract validation on `push`/`pull_request` to `main`.\n- Quick working tree check: `just status`\n\nRelease process:\n- See [`.github/RELEASE_GUIDE.md`](.github/RELEASE_GUIDE.md) for versioning/tagging steps.\n\n## Project Docs\n\n- Release notes: `RELEASE_NOTES.md`\n- Future plan: `ROADMAP.md`\n\n## Setup\n\n### Claude Code\n\nPreferred path — install as a plugin (see [Install](#install-claude-code) above). After install, skills auto-trigger from their frontmatter descriptions; no per-skill setup needed.\n\nAlternative paths (without the plugin):\n\n1. **Direct reference**: Ask Claude Code to read and follow a specific `SKILL.md`:\n   ```\n   Read plugins/oh-my-secuaudit/skills/sec-audit-static/SKILL.md and run the static audit playbook for this codebase.\n   ```\n\n2. **Project commands**: Symlink skill directories into your project's `.claude/commands/`:\n   ```bash\n   mkdir -p .claude/commands\n   ln -s \"$(pwd)/plugins/oh-my-secuaudit/skills/sec-audit-static/SKILL.md\" .claude/commands/sec-audit-static.md\n   ```\n\n3. **CLAUDE.md integration**: Reference skills from your project's `CLAUDE.md`:\n   ```markdown\n   For security audits, follow the workflow in /path/to/oh-my-secuaudit/plugins/oh-my-secuaudit/skills/sec-audit-static/SKILL.md\n   ```\n\n### Codex\n\nEach skill directory includes `agents/openai.yaml` for Codex-native discovery. Copy or symlink skill directories into `~/.codex/skills/local/`.\n\n## Related Reading\n\nBlog posts from [Code Before Breach](https://windshock.github.io/en/):\n\n| Skill | Post | Relevance |\n|---|---|---|\n| `security-testing-as-code` | [Security Diagnostics Reports Die Upon Publication](https://windshock.github.io/en/post/2026-03-17-security-testing-as-code/) | Direct source — assessment-as-project thesis |\n| `sec-cluster` | [Structure Builders Will Outlast Vulnerability Finders](https://windshock.github.io/en/post/2026-04-02-security-from-sense-to-structure/) | Systematic structure over ad-hoc finding |\n\n## Notes\n\n- Each skill directory contains its own `SKILL.md`, references, schemas, and scripts.\n- Skills are flat under `plugins/oh-my-secuaudit/skills/`; the architect / runtime / static / external / methodology grouping is documented in the [Layout](#layout) section above.\n",
  "bytes": 11971,
  "sha": "9234e413f770f0fd1eb3613e41ff2862510214cf94dcbb260bcd068deb4197bb",
  "repo_slug": "windshock/oh-my-secuaudit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_windshock_oh_my_secuaudit_oh_my_secuaudi_e36aabf0/readme"
}