Security Harness

Claude Code (और, बाद में, अन्य AI एजेंट्स) के लिए एक मल्टी-एजेंट एप्लिकेशन-सुरक्षा समीक्षा हार्नेस। एक राउटर स्किल एक पूर्ण आक्रामक-सुरक्षा पाइपलाइन को डिस्पैच करता है जो एक कोडबेस को मैप करता है, प्रति-श्रेणी ज्ञान आधार के साथ कमज़ोरियों का शिकार करता है, निष्कर्षों को एस्केलेशन में श्रृंखलाबद्ध करता है, वास्तविक प्रभाव को सत्यापित करता है, और README / JSON / SARIF / doc / PDF में रिपोर्ट करता है।

दायरा: यह हार्नेस उस कोड पर स्टैटिक विश्लेषण (स्रोत समीक्षा, डेटा-फ़्लो ट्रेसिंग, PoC/पेलोड निर्माण) करता है जिसका आप स्वामी हैं या जिसका परीक्षण करने के लिए आप अधिकृत हैं। यह लाइव तृतीय-पक्ष सिस्टम पर हमला नहीं करता।

अंदर क्या है```

security-harness/ # a plugin marketplace └── plugins/security-harness/ ├── skills/ │ ├── sh-router # single entry point - routes any appsec request │ ├── sh-security-review # the pipeline orchestrator (Stages 0-5) │ └── sh-kb-* (15) # per-vuln-class knowledge bases ├── agents/ │ ├── sh-recon # map: Graft graph + stack/SBOM/CVE + attack surface │ ├── sh-hunter # find: source→sink hunting, one per class (parallel) │ ├── sh-chainer # escalate: combine findings into attack chains │ ├── sh-verifier # confirm: offensive + seceng + dev verification + PoC │ └── sh-reporter # deliver: README/JSON/SARIF/HTML/PDF/doc └── references/ # shared contracts (finding schema, SARIF map, state files, rubrics)

### कवर की गई भेद्यता श्रेणियाँ (`sh-kb-*` कौशल)

access-control (IDOR/BOLA/priv-esc) · sqli · xss · ssrf · injection (cmd/code/SSTI/LDAP) · auth (session/JWT)
· deserialization · path-traversal (LFI/RFI) · secrets · csrf · xxe · open-redirect · crypto · race-conditions
· file-upload. Dependency CVEs/SBOM को recon चरण द्वारा संभाला जाता है।

## इंस्टॉल

यह हार्नेस कई एजेंट्स के लिए उपलब्ध है। पूर्ण पैकेजिंग विवरण और रिलीज़
चेकलिस्ट [`docs/DISTRIBUTION.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/docs/DISTRIBUTION.md) में हैं।

**Claude Code** - इस रेपो को प्लगइन मार्केटप्लेस के रूप में जोड़ें और प्लगइन इंस्टॉल करें:```
/plugin marketplace add dmdhrumilmistry/security-harness
/plugin install security-harness

Stages: `setup, recon, hunt, chain, verify, report`. Models: `opus, sonnet, haiku, inherit`. `hunt` के लिए, एक bare model सभी hunters को उसी पर flatten कर देता है; `hunt.pattern` / `hunt.trace` / `hunt.logic` एक tier को target करते हैं। अन्य token savers built in हैं: recon केवल उन classes के लिए hunters spawn करता है जिनमें real attack surface हो, hunters whole files पढ़ने के बजाय Graft graph query करते हैं, और `findings.json`/SARIF model के बजाय एक deterministic script द्वारा generate होते हैं। ### Output सब कुछ `<target>/.security-harness/<run-id>/` के अंतर्गत आता है: - `recon.md`, `codebase-map.json` - the map (stack, SBOM, CVEs, attack surface). - `findings.jsonl` → `chains.md` → `verified.jsonl` - the working state (देखें `references/state-files.md`). - `reports/` - `README.md`, `findings.json`, `results.sarif`, `report.html`, `report.pdf` (+ `report.docx`). प्रत्येक published finding में एक payload, एक PoC, verification verdict, CWE/OWASP ids, CVSS, और एक code-level mitigation होता है। ## Pull request review `sh-pr-review` पूरे codebase के बजाय एक single pull request review करता है, परिणाम को inline comments के रूप में **PR पर ही** post करता है, और एक `security/pr-review` commit status set करता है जिसे branch protection enforce कर सकता है। **इसे अपनी मशीन से, किसी भी PR पर जिसे आप पढ़ सकते हैं, चलाएँ।** Plugin install करें और पूछें:``` review https://github.com/acme/api/pull/128 review PR 42 security review this PR

दो append-only JSONL फ़ाइलें - `runs.jsonl` (repo, PR, tier, verdict, totals, आपके द्वारा पास किए गए flags) और `events.jsonl` (प्रत्येक phase या agent के लिए एक पंक्ति: model, tokens, duration, outcome, क्या इसे cache से पुनः उपयोग किया गया था)। JSONL इसलिए ताकि crash होने पर भी crash के ऊपर valid पंक्तियाँ बनी रहें। | Platform | Metrics | Cache | |---|---|---| | **Linux / BSD** | `$XDG_DATA_HOME/security-harness/metrics`<br>default `~/.local/share/security-harness/metrics` | `$XDG_CACHE_HOME/security-harness`<br>default `~/.cache/security-harness` | | macOS | `~/Library/Application Support/security-harness/metrics` | `~/Library/Caches/security-harness` | | Windows | `%LOCALAPPDATA%\security-harness\metrics` | `%LOCALAPPDATA%\security-harness\cache` | Linux XDG Base Directory spec का पालन करता है, इसलिए दोनों सेट होने पर `XDG_DATA_HOME` और `XDG_CACHE_HOME` का सम्मान करते हैं और सेट न होने पर `~/.local/share` और `~/.cache` पर वापस चले जाते हैं। `SH_METRICS_DIR` और `SH_REVIEW_CACHE_DIR` के साथ किसी भी एक को सीधे override करें। **`python` बनाम `python3` पर:** अधिकांश Linux distributions `python3` के साथ आते हैं और उनमें `python` बिल्कुल नहीं होता, इसलिए यहाँ के उदाहरण `python3` का उपयोग करते हैं। bundled scripts में `#!/usr/bin/env python3` shebang होता है और वे executable हैं, इसलिए `./scripts/sh-metrics.py report` Linux और macOS पर सीधे काम करता है। skill प्रति run एक बार `PY="$(command -v python3 || command -v python)"` resolve करता है, जो Windows पर Git Bash सहित तीनों platforms को cover करता है। **पूरी तरह local।** दोनों scripts में कोई network code या reporting endpoint नहीं है। token-जैसा कुछ भी लिखे जाने से पहले redact कर दिया जाता है, क्योंकि local files issues में paste हो जाती हैं। ### इसे unattended चलाना वैकल्पिक, और skill का उपयोग करने से एक अलग निर्णय। पहले कुछ समय अपने PRs पर इसे हाथ से चलाएँ, ताकि आपकी team के सामने कहने से पहले आप जान लें कि यह आपके codebase के बारे में क्या कहता है। जब आप तैयार हों, [`references/pr-review-mapping.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/plugins/security-harness/references/pr-review-mapping.md) में "Enforcing the check on a repository" में **आपके** repo के लिए एक copy-paste workflow है, साथ ही वह fail-safe भी जो एक मृत job को required check को `pending` पर अटके रहने से रोकता है। threshold default `medium` पर ही रहता है। पहले से मौजूद findings कभी merge को block नहीं करते, इसलिए एक unscanned codebase पहले दिन लाल रंग की दीवार नहीं बनाता - केवल वही जो कोई PR वास्तव में पेश करता है या बिगाड़ता है, उसे fail करा सकता है। ## यह कैसे काम करता है 1. **Setup** - उपलब्ध tools की जाँच करें, scope परिभाषित करें, run directory बनाएँ। 2. **Recon** (`sh-recon`) - Graft graph बनाएँ; stack/versions detect करें; SBOM + CVEs; entry points, trust boundaries, और dangerous sinks की गणना करें। 3. **Hunt** (`sh-hunter` ×N, parallel) - प्रत्येक relevant class के लिए एक hunter अपना `sh-kb-*` knowledge base load करता है, attacker input को source से sink तक trace करता है, और candidates record करता है। एक साझा **attempts ledger** agents को एक-दूसरे की probes दोहराने से रोकता है। 4. **Chain** (`sh-chainer`) - findings को उच्च-गंभीरता वाले attack paths में compose करें। 5. **Verify** (`sh-verifier`) - पहले खंडन करें, फिर evidence से exploitability की पुष्टि करें, PoCs बनाएँ, CVSS assign करें, और false positives काटें। 6. **Report** (`sh-reporter`) - deliverables तैयार करें। Subagents files के अलावा कुछ साझा नहीं करते; contract `plugins/security-harness/references/state-files.md` में है। ## विस्तार करना साझा template का पालन करते हुए `skills/sh-kb-<class>/SKILL.md` बनाकर एक नई vulnerability class जोड़ें (When to hunt · Sources & sinks · Detection recipe · Payloads/PoC · False-positive filters · CWE/OWASP · Chaining hints · Mitigation), फिर उसका slug `references/finding-schema.json` में `class` enum और `skills/sh-router/SKILL.md` में routing table में जोड़ें। ## स्वचालित knowledge-base अपडेट एक scheduled GitHub Action (`.github/workflows/update-knowledge-base.yml`) `sh-kb-*` knowledge bases को ताज़ा रखता है। **हर दूसरे दिन** (और manual `workflow_dispatch` पर), यह एक agent चलाता है जो नई, प्रतिष्ठित सार्वजनिक security research - OWASP, PortSwigger Research, CWE/CAPEC, NIST, MDN, curated GitHub repos, और सार्वजनिक HackerOne disclosures - को छोटे, अच्छी तरह sourced सुधारों में distill करता है। फिर एक **दूसरा, adversarial reviewer agent** परिणामी diff को दुर्भावनापूर्ण/injected content के लिए scan करता है, और PR **केवल तभी auto-merged होता है जब वह reviewer approve करता है**। ### दो workflows, तीन jobs PR creation को जानबूझकर review और merge से अलग रखा गया है, ताकि जो diff लिखता है वह कभी वह न हो जो इसे ship करने का निर्णय लेता है। **Stage 1 - [`update-knowledge-base.yml`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/workflows/update-knowledge-base.yml)** (scheduled या manual)। एक job, `create-pr`: 1. **Generate** - agent allowlisted sources से KB को edit करता है। कोई commit नहीं, कोई push नहीं। 2. **Open PR** - एक deterministic step `automated/kb-update` branch पर एक PR खोलता है (या update करता है), जिस पर `awaiting-review` label लगा होता है। 3. **Hand off** - सफल PR creation पर यह PR number के साथ stage 2 को dispatch करता है। **Stage 2 - [`kb-review-and-merge.yml`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/workflows/kb-review-and-merge.yml)** (stage 1 द्वारा dispatched, या किसी भी automated PR के विरुद्ध हाथ से चलाया गया)। दो jobs: - **`review`** - एक *अलग* agent run diff को **adversarially** जाँचता है prompt-injection artifacts, out-of-scope edits, secrets/exfil, PII, weaponized exploits, off-allowlist sourcing, या house-style violations के लिए। इसमें **कोई web नहीं और कोई shell नहीं** है, और यह **fail closed** करता है: कुछ भी संदिग्ध, कोई भी अनिश्चितता, या एक गायब verdict file → REJECT। verdict एक PR comment के रूप में पोस्ट किया जाता है और label को नियंत्रित करता है। - **`merge`** - **केवल** `APPROVE` पर चलता है, और PR को merge करता है। एक `REJECT` इसे skip कर देता है और `blocked` job बताता है कि क्यों। > **`pull_request` trigger के बजाय dispatch क्यों:** `GITHUB_TOKEN` द्वारा खोला गया PR > `pull_request` workflows को trigger नहीं करता। `workflow_dispatch` उन दो events में से एक है > जो उस recursion guard से मुक्त हैं, इसलिए stage 1 विश्वसनीय रूप से hand off कर सकता है। **Auto-merge का अर्थ है कि एक approving agent `main` में code land करता है।** उस पर नियंत्रण: - merge job किसी भी ऐसे PR को अस्वीकार करता है जो closed है, किसी fork से है, या जिसकी head branch `automated/*` के बाहर है (workflow में `ALLOWED_HEAD_PREFIX`)। - यह GitHub के अपने auto-merge को प्राथमिकता देता है, इसलिए **branch protection अभी भी लागू रहता है**। `main` पर एक rule के साथ जो approving review की माँग करता है, PR queue में लग जाता है और merge होने के बजाय एक इंसान का इंतज़ार करता है। यह केवल उन repos पर तत्काल merge पर वापस जाता है जहाँ auto-merge बंद है। - merge किए बिना review करने के लिए manual run पर `auto_merge` input को `false` पर सेट करें। - reviewer prompt agent को बताता है कि उसका verdict binding है, advisory नहीं। > इसके लिए repo setting **"Allow GitHub Actions to create and approve pull requests"** (Settings → > Actions → General → Workflow permissions) चाहिए ताकि workflow PR खोल सके। यदि आप auto-merge के बावजूद एक इंसान को > loop में चाहते हैं, तो `main` को एक branch-protection rule से सुरक्षित करें जो एक pull request और कम से कम > एक approving review की माँग करता है - auto-merge path इसका सम्मान करता है। ### Pluggable agents दोनों stages [`.github/actions/ai-agent`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/actions/ai-agent/action.yml) के माध्यम से चलते हैं, एक composite action जो उस agent को dispatch करता है जिसे आप configure करते हैं। Claude Code, OpenAI Codex, Gemini CLI, और बाकी किसी भी चीज़ के लिए एक escape hatch: | `agent` | Runs | Credential | |---|---|---| | `claude` (default) | `anthropics/claude-code-action@v1` | `CLAUDE_CODE_OAUTH_TOKEN` या `ANTHROPIC_API_KEY` | | `codex` | `codex exec --full-auto` | `OPENAI_API_KEY` | | `gemini` | `gemini --yolo --prompt` | `GEMINI_API_KEY` | | `custom` | आपका `KB_AGENT_INSTALL` / `KB_AGENT_COMMAND` | जो भी इसे चाहिए | प्रति run `workflow_dispatch` inputs से चुनें, या default बदलने के लिए repo variables सेट करें: generator के लिए `KB_AGENT` और `KB_MODEL`, reviewer के लिए `KB_REVIEW_AGENT` और `KB_REVIEW_MODEL`। generator और reviewer को **अलग-अलग agents** पर चलाना एक सार्थक hardening step है: एक model के लिए tuned injection के दूसरे, स्वतंत्र model पर लगने की संभावना कम होती है। `agent: custom` के लिए, `KB_AGENT_COMMAND` को एक shell command पर सेट करें। prompt उस file में लिखा जाता है जिसका नाम `$AGENT_PROMPT_FILE` है, और `$AGENT_MODEL` model input ले जाता है। Prompt-injection defenses, क्योंकि generator खुले web को पढ़ता है: - **Domain allowlist.** `WebFetch` `.github/kb-update/trusted-sources.md` में भरोसेमंद domains तक सीमित है (workflow के `--allowedTools` में mirrored)। `WebSearch` URLs खोज सकता है, लेकिन केवल allowlisted domains ही वास्तव में fetch किए जा सकते हैं। - **Content data है, commands नहीं।** task prompt (`.github/kb-update/prompt.md`) Claude को निर्देश देता है कि हर fetched byte को अविश्वसनीय reference material माने और किसी page में embedded किसी भी instruction को अनदेखा करे - HackerOne report bodies (user-generated) को उच्चतम-जोखिम tier के रूप में flag किया जाता है। - **generator पर कोई shell नहीं, कोई push नहीं; reviewer ही gate है।** generator केवल files edit कर सकता है। स्वतंत्र reviewer (`.github/kb-update/review-prompt.md`) वही है जो fetched content और `main` के बीच खड़ा है - इसकी स्पष्ट approval के बिना कुछ merge नहीं होता। - **generator और reviewer के लिए अलग agents।** वैकल्पिक, और gate का सबसे मजबूत संस्करण: `KB_AGENT` और `KB_REVIEW_AGENT` को दो अलग engines पर सेट करें। **Setup:** - जो भी agent आप उपयोग करते हैं उसके लिए credential जोड़ें (Settings → Secrets and variables → Actions): **`CLAUDE_CODE_OAUTH_TOKEN`** (default), `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, या `GEMINI_API_KEY`। OAuth token metered API key के बजाय **आपकी Claude subscription की usage limits** के विरुद्ध authenticate करता है - इसे locally `claude setup-token` से generate करें (एक सक्रिय Claude Pro/Max subscription आवश्यक है) और परिणाम paste करें। - **"Allow GitHub Actions to create and approve pull requests"** enable करें (Settings → Actions → General → Workflow permissions) ताकि workflow अपना PR खोल सके। अनुशंसित: `main` पर एक branch-protection rule जोड़ें जो एक PR और एक approving review की माँग करता है, ताकि auto-merge चालू होने पर भी कोई automated change किसी इंसान के बिना land न कर सके। - यह बदलने के लिए कि कौन से sources allowed हैं, `trusted-sources.md` में allowlist **और** workflow में मेल खाती `WebFetch(domain:...)` entries edit करें - दोनों को sync में रखें। प्रत्येक run ने क्या किया, यह `.github/kb-update/last-run-summary.md` में record करता है। ## Roadmap - ~~Codex / Cursor mirror wiring.~~ ✅ Shipped: `AGENTS.md`, एक Gemini CLI extension, और `.agents/skills` तथा opencode के लिए `scripts/sync-agent-skills.py`। देखें [`docs/DISTRIBUTION.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/docs/DISTRIBUTION.md)। - ~~curated references के ऊपर knowledge bases का optional live-fetch augmentation (PortSwigger/OWASP/CWE)।~~ ✅ ऊपर दिए गए scheduled knowledge-base updater के रूप में Shipped। - `needs-runtime` findings की runtime confirmation के लिए optional DAST bridge। ## License MIT

चरण	डिफ़ॉल्ट मॉडल
recon	`sonnet`
hunt (प्रति वर्ग)	पैटर्न वर्गों के लिए `haiku` (secrets, crypto, open-redirect, csrf) · source→sink ट्रेसिंग के लिए `sonnet` (sqli, xss, ssrf, injection, path-traversal, xxe, file-upload, auth) · deep-logic वर्गों के लिए `opus` (access-control, race-conditions, deserialization)
chain	`opus`
verify	`opus` (सटीकता गेट - मजबूत रखा गया)
report	`haiku`

Verdict	Status	When
fail	`failure`	`--fail-on` (डिफ़ॉल्ट `medium`) पर या उससे ऊपर introduced या aggravated निष्कर्ष, confidence >= 80
warn	`success`	कुछ भी introduced या aggravated नहीं; pre-existing निष्कर्ष रिपोर्ट किए गए
pass	`success`	कोई निष्कर्ष नहीं, या triage Tier 0 पर रुक गया
error	`error`	समीक्षा पूरी नहीं हो सकी

security-harness

सबसे लोकप्रिय

Usage

मॉडल और लागत नियंत्रण

री-रिव्यू इंक्रीमेंटल होते हैं

पोस्टिंग, और चीज़ें कहाँ लिखी जाती हैं

स्थानीय रन मेट्रिक्स