Security Harness

Claude Code(그리고 추후 다른 AI 에이전트)를 위한 멀티 에이전트 애플리케이션 보안 검토 하네스입니다. 하나의 라우터 스킬이 코드베이스를 매핑하고, 클래스별 지식 베이스로 취약점을 사냥하며, 발견 사항을 연쇄시켜 에스컬레이션으로 연결하고, 실제 영향을 검증한 뒤, README / JSON / SARIF / doc / PDF로 보고하는 완전한 공격 보안 파이프라인으로 디스패치합니다.

범위: 이 하네스는 자신이 소유하거나 테스트 권한이 있는 코드에 대해 정적 분석(소스 검토, 데이터 흐름 추적, PoC/페이로드 구성)을 수행합니다. 실제 제3자 시스템을 공격하지 않습니다.

포함 내용```

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. 의존성 CVE/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

/plugin marketplace add는 다음 중 하나를 허용합니다: GitHub owner/repo(위와 같음), 전체 git URL (https://github.com/dmdhrumilmistry/security-harness.git), 또는 클론의 로컬 경로 (예: 체크아웃이 있는 디렉터리에서 /plugin marketplace add ./security-harness). 그런 다음 /plugin install security-harness를 실행하고, 프롬프트가 표시되면 다시 로드하세요.

Gemini CLI - 네이티브 확장, 저장소 루트에 매니페스트가 있음:```bash gemini extensions install https://github.com/dmdhrumilmistry/security-harness

**opencode, Codex 또는 모든 [agentskills.io](https://agentskills.io) 에이전트** - 스킬을
검색 디렉터리에 복사하세요. Codex는 추가적으로 `AGENTS.md`를 자체적으로 인식합니다:```bash
git clone https://github.com/dmdhrumilmistry/security-harness
cd security-harness
python3 scripts/sync-agent-skills.py --install agents     # ~/.agents/skills
python3 scripts/sync-agent-skills.py --install opencode   # ~/.config/opencode/skills

Graft는 파이프라인에 의해 자동으로 설치되고 설정됩니다. Stage 0은 Graft가 없으면 npm install -g @nanonets/graft를 실행하고(Node/npm 필요), 그다음 graft init <target> --no-agents --no-global을 실행하여 대상 저장소에 대한 Graft MCP 서버와 freshness 훅을 등록합니다. 그래프 자체(<target>/graft/, 자동 gitignore됨)는 recon 중에 빌드됩니다. 수동으로 미리 설치하려면: npm install -g @nanonets/graft. Graft의 구조적 빌드는 무료이며 API 키가 필요 없습니다. 선택적 --deep LLM 패스는 설정된 경우 GRAFT_API_KEY / GRAFT_PROVIDER / GRAFT_MODEL을 사용합니다.

다른 도구들도 Stage 0에 의해 없으면 자동 설치됩니다 (머신에 있는 패키지 관리자를 통해 - winget/choco/scoop, brew, apt, npm/pip/go - references/tooling-setup.md 참조). 설치는 알림이 표시되고, 권한 상승이 필요 없는 방법을 선호하며, 실행을 절대 차단하지 않습니다. 설치할 수 없는 것은 단순히 사용 불가로 표시되고 파이프라인은 폴백합니다. Stage 0은 누락된 기능 그룹을 채우는 것만 설치합니다:

• SBOM: syft · CVE: grype (선호), trivy, 또는 osv-scanner 중 하나
• 보고서: wkhtmltopdf 또는 pandoc (PDF/DOCX용); 그렇지 않으면 report.html(또는 헤드리스 Chrome PDF)을 받습니다.

이들 모두는 선택 사항입니다 - 아무것도 설치되지 않으면 파이프라인은 네이티브 검색 + 매니페스트 파싱으로 우아하게 성능이 저하됩니다.

사용법

자연어 요청으로 라우터를 호출합니다:``` /sh-router full security review of ./api /sh-router find SQLi and IDOR in src/ /sh-router just map this codebase # recon only

또는 파이프라인을 직접 호출하세요:```
/sh-security-review . classes:sqli,access-control,ssrf depth:deep
/sh-security-review . stage:report       # regenerate reports for the latest run

모델 및 비용 제어

각 단계는 인지 부하에 맞춰진 모델에서 실행되므로, 토큰은 발견 품질이 실제로 좌우되는 곳에 사용되고 기계적인 작업에서는 절약됩니다. 이것이 기본값이며, 인수가 필요하지 않습니다.

단계	기본 모델
recon	sonnet
hunt (클래스별)	패턴 클래스(secrets, crypto, open-redirect, csrf)에는 haiku · 소스→싱크 추적(sqli, xss, ssrf, injection, path-traversal, xxe, file-upload, auth)에는 sonnet · 심층 로직 클래스(access-control, race-conditions, deserialization)에는 opus
chain	opus
verify	opus (정밀도 게이트 - 강하게 유지됨)
report	haiku

models: 인수로 재정의할 수 있습니다(라우터를 통해서도 전달됨):``` /sh-security-review . # default tiered map above /sh-security-review . models:max # every stage + hunter on opus (max quality, max cost) /sh-security-review . models:cheap # aggressive downshift (trades some verify precision) /sh-security-review . models:verify=opus,hunt=sonnet # per-stage overrides /sh-security-review . models:report=sonnet,hunt.pattern=sonnet # per-hunter-tier override

단계: `setup, recon, hunt, chain, verify, report`. 모델: `opus, sonnet, haiku, inherit`. `hunt`의 경우,
모델을 그대로 지정하면 모든 헌터가 해당 모델로 통일되며, `hunt.pattern` / `hunt.trace` / `hunt.logic`은 특정 계층을 대상으로 합니다.
다른 토큰 절약 기능도 내장되어 있습니다. recon은 실제 공격 표면이 있는 클래스에 대해서만 헌터를 생성하고, 헌터는
전체 파일을 읽는 대신 Graft 그래프를 조회하며, `findings.json`/SARIF는 모델이 아닌
결정적 스크립트에 의해 생성됩니다.

### 출력

모든 결과는 `<target>/.security-harness/<run-id>/` 아래에 저장됩니다:

- `recon.md`, `codebase-map.json` - 맵 (스택, SBOM, CVE, 공격 표면).
- `findings.jsonl` → `chains.md` → `verified.jsonl` - 작업 상태 (`references/state-files.md` 참조).
- `reports/` - `README.md`, `findings.json`, `results.sarif`, `report.html`, `report.pdf` (+ `report.docx`).

게시된 각 발견 사항에는 페이로드, PoC, 검증 판정, CWE/OWASP ID, CVSS, 그리고
코드 수준의 완화책이 포함됩니다.

## 풀 리퀘스트 리뷰

`sh-pr-review`는 전체 코드베이스가 아닌 단일 풀 리퀘스트를 리뷰하고, 결과를
**PR 자체에** 인라인 코멘트로 게시하며, 브랜치 보호가 적용할 수 있는
`security/pr-review` 커밋 상태를 설정합니다.

**읽을 수 있는 모든 PR에 대해 자신의 머신에서 실행하세요.** 플러그인을 설치하고 요청하세요:```
review https://github.com/acme/api/pull/128
review PR 42
security review this PR

PR 링크를 붙여넣으면 해당 저장소의 PR을 리뷰하며, 먼저 임시 디렉터리로 클론합니다. 헌터들은 패치뿐 아니라 파일도 읽기 때문입니다. 작업 중인 저장소에는 아무것도 기록되지 않습니다.

숫자만 넘기면 현재 있는 저장소, 즉 git remote가 가리키는 저장소를 기준으로 해석합니다. 아무것도 넘기지 않으면 현재 브랜치의 열린 PR을 가져옵니다.

Phase 7은 발견 사항과 판정을 출력하고 무엇이든 게시하기 전에 물어봅니다 - 거절은 정상적인 결과이며, 페이로드는 나중에 게시할 수 있도록 디스크에 남아 있습니다.

분석에 비용을 쓰기 전에 대상 저장소에 실제로 쓸 수 있는지 확인하므로, 다른 사람의 프로젝트를 리뷰할 때 게시가 403이 될 것임을 10분 뒤에 발견하는 대신 미리 알려줍니다.

노이즈가 아니라 머지 게이트로 쓸 수 있게 하는 세 가지 속성이 있습니다:

• PR이 책임지는 것만 실패시킵니다. 모든 발견 사항은 introduced, aggravated, pre_existing 중 하나의 pr_impact를 가집니다. 처음 두 개는 차단하고, pre_existing은 보고되지만 절대 차단하지 않습니다. 작성자가 쓰지도 않은 코드 때문에 머지를 차단하면 필수 검사가 삭제되므로, 헌터가 aggravated와 pre_existing 사이에서 확신이 없을 때는 pre_existing을 골라야 합니다.
• 깊이는 위험을 따릅니다. 트리아지는 서브에이전트 없이 오케스트레이터에서 먼저 실행됩니다. 변경된 경로와 추가된 줄의 싱크 토큰을 sh-kb-* 베이스가 사용하는 것과 동일한 클래스 슬러그에 매핑한 다음 티어를 고릅니다. Tier 0(보안 관련 변경 없음)은 아무것도 실행하지 않고도 상태를 설정합니다. Tier 3은 전체 파이프라인을 실행합니다.
• 재푸시는 스팸이 되지 않습니다. 각 코멘트는 줄 번호 없이 계산된 숨겨진 지문을 가지므로, 재리뷰는 새로운 것만 추가하고 수정된 것은 "Resolved since the last review"로 나열합니다.

판정	상태	조건
fail	failure	--fail-on(기본 medium) 이상의 introduced 또는 aggravated 발견 사항, 신뢰도 >= 80
warn	success	introduced 또는 aggravated 없음; pre-existing 발견 사항 보고됨
pass	success	발견 사항 없음, 또는 트리아지가 Tier 0에서 중단됨
error	error	리뷰를 완료할 수 없음

warn이 의도적으로 success를 보고하는 이유: 머지를 차단하는 경고는 단계만 늘어난 실패이며, 팀은 검사를 제거하는 것으로 대응합니다. error는 failure와 구분되게 유지되어, 망가진 실행이 찾지 못한 취약점처럼 보이는 일이 없습니다.

리뷰 이벤트는 항상 COMMENT이며, REQUEST_CHANGES나 APPROVE가 아닙니다. 커밋 상태가 강제 메커니즘이며, 브랜치 보호가 읽는 것이 바로 이것입니다.

범위: 이 스킬은 풀 리퀘스트와 커밋 상태에만 쓰고, 다른 곳에는 쓰지 않습니다. 이슈를 열지 않고 어떤 외부 트래커에도 아무것도 생성하지 않습니다.

재리뷰는 증분식입니다

PR은 푸시마다 한 번 리뷰되므로, 두 번째 리뷰는 첫 번째보다 저렴해야 합니다. 그렇지 않으면 이 도구는 사람들이 꺼버리는 것이 됩니다.