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

두 개의 append-only JSONL 파일 - `runs.jsonl`(repo, PR, tier, verdict, totals, 전달한 플래그)과 `events.jsonl`(각 phase 또는 agent당 한 줄: model, tokens, duration, outcome, 캐시에서 재사용되었는지 여부). JSONL이므로 크래시가 발생한 실행도 크래시 위쪽에 유효한 줄을 남긴다. | Platform | Metrics | Cache | |---|---|---| | **Linux / BSD** | `$XDG_DATA_HOME/security-harness/metrics`<br>기본값 `~/.local/share/security-harness/metrics` | `$XDG_CACHE_HOME/security-harness`<br>기본값 `~/.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 명세를 따르므로, 둘 다 설정된 경우 `XDG_DATA_HOME`과 `XDG_CACHE_HOME`을 존중하고 설정되지 않은 경우 `~/.local/share`와 `~/.cache`로 폴백한다. `SH_METRICS_DIR`과 `SH_REVIEW_CACHE_DIR`로 둘 중 하나를 직접 재정의할 수 있다. **`python` vs `python3`에 관하여:** 대부분의 Linux 배포판은 `python3`를 제공하며 `python`은 전혀 없다. 따라서 여기의 예제는 `python3`를 사용한다. 번들된 스크립트는 `#!/usr/bin/env python3` shebang을 가지며 실행 가능하므로, `./scripts/sh-metrics.py report`는 Linux와 macOS에서 직접 작동한다. 스킬은 실행당 한 번 `PY="$(command -v python3 || command -v python)"`를 해석하며, 이는 Windows의 Git Bash를 포함한 세 플랫폼 모두를 커버한다. **철저히 로컬.** 어느 스크립트에도 네트워크 코드나 리포팅 엔드포인트가 없다. 토큰 형태의 모든 것은 기록되기 전에 리댁션된다. 로컬 파일은 이슈에 붙여넣어지기 때문이다. ### 무인 실행 선택 사항이며, 스킬 사용과는 별개의 결정이다. 먼저 한동안 자신의 PR에서 수동으로 실행하여, 팀 앞에서 말하기 전에 자신의 코드베이스에 대해 무엇을 말하는지 파악하라. 준비가 되면, [`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를 위한 복사-붙여넣기 워크플로가 있으며, 죽은 작업이 필수 체크를 `pending` 상태로 남기는 것을 막는 fail-safe도 포함되어 있다. 임계값은 기본값인 `medium`으로 유지된다. 기존 발견 사항은 절대 머지를 차단하지 않으므로, 스캔되지 않은 코드베이스가 첫날부터 빨간 벽을 만들어내지 않는다 - PR이 실제로 도입하거나 악화시킨 것만 실패시킬 수 있다. ## 작동 방식 1. **Setup** - 사용 가능한 도구를 탐색하고, 범위를 정의하고, 실행 디렉터리를 생성한다. 2. **Recon** (`sh-recon`) - Graft 그래프를 구축하고, 스택/버전을 감지하고, SBOM + CVE를 수집하고, 진입점, 신뢰 경계, 위험한 싱크를 열거한다. 3. **Hunt** (`sh-hunter` ×N, 병렬) - 관련 클래스당 하나의 hunter가 자신의 `sh-kb-*` 지식 베이스를 로드하고, 공격자 입력을 소스에서 싱크까지 추적하고, 후보를 기록한다. 공유 **attempts ledger**는 에이전트들이 서로의 프로브를 반복하는 것을 막는다. 4. **Chain** (`sh-chainer`) - 발견 사항을 더 높은 심각도의 공격 경로로 구성한다. 5. **Verify** (`sh-verifier`) - 먼저 반박하고, 그다음 증거로부터 익스플로잇 가능성을 확인하고, PoC를 구축하고, CVSS를 할당하고, 오탐을 제거한다. 6. **Report** (`sh-reporter`) - 산출물을 생성한다. 서브에이전트는 파일 외에는 아무것도 공유하지 않는다. 계약은 `plugins/security-harness/references/state-files.md`에 있다. ## 확장 공유 템플릿(When to hunt · Sources & sinks · Detection recipe · Payloads/PoC · False-positive filters · CWE/OWASP · Chaining hints · Mitigation)을 따라 `skills/sh-kb-<class>/SKILL.md`를 생성하여 새로운 취약점 클래스를 추가한 다음, 그 slug를 `references/finding-schema.json`의 `class` enum과 `skills/sh-router/SKILL.md`의 라우팅 테이블에 추가한다. ## 자동화된 지식 베이스 업데이트 예약된 GitHub Action(`.github/workflows/update-knowledge-base.yml`)이 `sh-kb-*` 지식 베이스를 최신 상태로 유지한다. **격일로**(그리고 수동 `workflow_dispatch` 시), 에이전트를 실행하여 새롭고 신뢰할 수 있는 공개 보안 연구 - OWASP, PortSwigger Research, CWE/CAPEC, NIST, MDN, 큐레이션된 GitHub repo, 공개 HackerOne 공개 정보 - 를 작고 출처가 명확한 개선 사항으로 정제한다. 그런 다음 **두 번째, 적대적 리뷰어 에이전트**가 결과 diff에서 악성/주입된 콘텐츠를 스캔하고, PR은 **그 리뷰어가 승인한 경우에만 자동 머지된다**. ### 두 개의 워크플로, 세 개의 작업 PR 생성은 리뷰 및 머지와 의도적으로 분리되어 있어, diff를 작성하는 것이 그것을 배포하기로 결정하는 것이 결코 아니다. **Stage 1 - [`update-knowledge-base.yml`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/workflows/update-knowledge-base.yml)** (예약 또는 수동). 하나의 작업, `create-pr`: 1. **Generate** - 에이전트가 허용 목록 소스에서 KB를 편집한다. 커밋도, 푸시도 없다. 2. **Open PR** - 결정적 단계가 `automated/kb-update` 브랜치에 PR을 열고(또는 업데이트하고), `awaiting-review` 라벨을 붙인다. 3. **Hand off** - PR 생성이 성공하면 PR 번호와 함께 stage 2를 디스패치한다. **Stage 2 - [`kb-review-and-merge.yml`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/workflows/kb-review-and-merge.yml)** (stage 1에 의해 디스패치되거나, 임의의 자동화 PR에 대해 수동으로 실행). 두 개의 작업: - **`review`** - *별도의* 에이전트 실행이 diff를 **적대적으로** 검사하여 prompt-injection 흔적, 범위 밖 편집, 시크릿/유출, PII, 무기화된 익스플로잇, 허용 목록 외 소싱, 또는 하우스 스타일 위반을 찾는다. **웹도 셸도 없으며**, **fail closed**한다: 의심스러운 것, 불확실성, 또는 누락된 verdict 파일 → REJECT. verdict는 PR 코멘트로 게시되고 라벨을 결정한다. - **`merge`** - `APPROVE`에서**만** 실행되며, PR을 머지한다. `REJECT`는 이를 건너뛰고 `blocked` 작업이 이유를 보고한다. > **`pull_request` 트리거 대신 dispatch를 쓰는 이유:** `GITHUB_TOKEN`으로 열린 PR은 `pull_request` 워크플로를 트리거하지 않는다. `workflow_dispatch`는 그 재귀 가드에서 면제되는 두 이벤트 중 하나이므로, stage 1이 안정적으로 핸드오프할 수 있다. **자동 머지는 승인하는 에이전트가 `main`에 코드를 배포한다는 뜻이다.** 이에 대한 통제: - 머지 작업은 닫혔거나, 포크에서 온, 또는 head 브랜치가 `automated/*` 밖에 있는 PR을 거부한다(워크플로의 `ALLOWED_HEAD_PREFIX`). - GitHub 자체의 auto-merge를 선호하므로 **브랜치 보호가 여전히 적용된다**. `main`에 승인 리뷰를 요구하는 규칙이 있으면, PR은 머지되는 대신 대기열에 들어가 사람을 기다린다. auto-merge가 꺼져 있는 repo에서만 즉시 머지로 폴백한다. - 수동 실행 시 `auto_merge` 입력을 `false`로 설정하여 머지 없이 리뷰할 수 있다. - 리뷰어 프롬프트는 에이전트에게 그 verdict가 권고가 아니라 구속력이 있음을 알린다. > 워크플로가 PR을 열 수 있도록 repo 설정 **"Allow GitHub Actions to create and approve pull requests"**(Settings → Actions → General → Workflow permissions)가 필요하다. auto-merge에도 불구하고 사람을 루프에 두고 싶다면, PR과 최소 하나의 승인 리뷰를 요구하는 브랜치 보호 규칙으로 `main`을 보호하라 - auto-merge 경로가 이를 존중한다. ### 플러그 가능한 에이전트 두 stage 모두 [`.github/actions/ai-agent`](https://github.com/dmdhrumilmistry/security-harness/blob/main/.github/actions/ai-agent/action.yml)를 통해 실행되며, 이는 구성한 에이전트로 디스패치하는 composite action이다. Claude Code, OpenAI Codex, Gemini CLI, 그리고 그 외 모든 것을 위한 탈출구: | `agent` | 실행 | 자격 증명 | |---|---|---| | `claude` (기본값) | `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` | 필요한 것 | `workflow_dispatch` 입력에서 실행별로 선택하거나, repo 변수를 설정하여 기본값을 변경한다: 생성기용 `KB_AGENT`와 `KB_MODEL`, 리뷰어용 `KB_REVIEW_AGENT`와 `KB_REVIEW_MODEL`. 생성기와 리뷰어를 **서로 다른 에이전트**에서 실행하는 것은 의미 있는 강화 단계이다: 한 모델에 맞춰진 주입이 두 번째, 독립적인 모델에 적중할 가능성은 낮다. `agent: custom`의 경우, `KB_AGENT_COMMAND`를 셸 명령으로 설정한다. 프롬프트는 `$AGENT_PROMPT_FILE`로 명명된 파일에 작성되고, `$AGENT_MODEL`이 모델 입력을 전달한다. 생성기가 열린 웹을 읽으므로 prompt-injection 방어: - **도메인 허용 목록.** `WebFetch`는 `.github/kb-update/trusted-sources.md`의 신뢰할 수 있는 도메인으로 제한된다(워크플로의 `--allowedTools`에 미러링됨). `WebSearch`는 URL을 발견할 수 있지만, 허용 목록에 있는 도메인만 실제로 fetch될 수 있다. - **콘텐츠는 데이터이지 명령이 아니다.** 작업 프롬프트(`.github/kb-update/prompt.md`)는 Claude에게 fetch된 모든 바이트를 신뢰할 수 없는 참조 자료로 취급하고 페이지에 내장된 모든 지시를 무시하도록 지시한다 - HackerOne 리포트 본문(사용자 생성)은 최고 위험 등급으로 표시된다. - **생성기에는 셸도, 푸시도 없다; 리뷰어가 게이트다.** 생성기는 파일만 편집할 수 있다. 독립적인 리뷰어(`.github/kb-update/review-prompt.md`)가 fetch된 콘텐츠와 `main` 사이에 서는 것이다 - 명시적 승인 없이는 아무것도 머지되지 않는다. - **생성기와 리뷰어에 서로 다른 에이전트.** 선택 사항이며, 게이트의 가장 강력한 형태이다: `KB_AGENT`와 `KB_REVIEW_AGENT`를 두 개의 서로 다른 엔진으로 설정하라. **설정:** - 사용하는 에이전트의 자격 증명을 추가한다(Settings → Secrets and variables → Actions): **`CLAUDE_CODE_OAUTH_TOKEN`**(기본값), `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, 또는 `GEMINI_API_KEY`. OAuth 토큰은 종량제 API 키가 아니라 **당신의 Claude 구독 사용 한도**에 대해 인증한다 - 로컬에서 `claude setup-token`으로 생성하고(활성 Claude Pro/Max 구독 필요) 결과를 붙여넣어라. - 워크플로가 PR을 열 수 있도록 **"Allow GitHub Actions to create and approve pull requests"**(Settings → Actions → General → Workflow permissions)를 활성화한다. 권장: `main`에 PR과 승인 리뷰를 요구하는 브랜치 보호 규칙을 추가하여, auto-merge가 켜져 있어도 사람 없이는 어떤 자동화 변경도 배포될 수 없게 하라. - 허용되는 소스를 변경하려면 `trusted-sources.md`의 허용 목록**과** 워크플로의 일치하는 `WebFetch(domain:...)` 항목을 편집하라 - 둘을 동기화 상태로 유지하라. 각 실행은 수행한 작업을 `.github/kb-update/last-run-summary.md`에 기록한다. ## 로드맵 - ~~Codex / Cursor 미러 배선.~~ ✅ 출시됨: `AGENTS.md`, Gemini CLI 확장, 그리고 `.agents/skills`와 opencode를 위한 `scripts/sync-agent-skills.py`. [`docs/DISTRIBUTION.md`](https://github.com/dmdhrumilmistry/security-harness/blob/main/docs/DISTRIBUTION.md) 참조. - ~~큐레이션된 참조 위에 지식 베이스의 선택적 라이브 fetch 증강(PortSwigger/OWASP/CWE).~~ ✅ 위의 예약된 지식 베이스 업데이터로 출시됨. - `needs-runtime` 발견 사항의 런타임 확인을 위한 선택적 DAST 브리지. ## 라이선스 MIT

단계	기본 모델
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`

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

security-harness

인기

사용법

모델 및 비용 제어

재리뷰는 증분식입니다

게시, 그리고 어디에 기록되는가

로컬 실행 지표