보안 검토 스킬

Claude Code 하위 에이전트를 사용하여 코드 저장소에 대한 완전한 다단계 보안 검토를 오케스트레이션합니다. 각 단계는 좁은 책임을 가지며 그 출력을 다음 단계로 전달합니다.

전제 조건

실행 전에 다음 CLI 도구를 사용할 수 있는지 확인하십시오(누락된 경우 설치).

gitleaks — git 히스토리를 포함한 비밀 스캐닝. 권장.
osv-scanner — 기본 CVE 스캐너; lockfile의 모든 생태계를 포괄합니다. 권장.
semgrep — OWASP 스캐닝을 위한 정적 분석 시드. 권장.
jq — EPSS 보강(3단계) 및 런타임 Docker 경로(5단계). 권장.
pip-audit — 보조 Python CVE 패스(osv-scanner와 다른 DB 사용). 선택 사항(Python 저장소만 해당).
grype — 보조 Java/Maven CVE 패스. 선택 사항(Java 저장소만 해당).
poetry — pip-audit이 읽을 수 있도록 poetry.lock을 내보냅니다. 선택 사항(Poetry 프로젝트만 해당).
docker — 런타임 PoC 검증. 선택 사항(--runtime 플래그 사용 시에만).

npm audit은 목록에 없습니다. npm에 번들로 포함되어 있으며 모든 Node.js 프로젝트에서 자동으로 사용할 수 있습니다.

설치 및 확인:

bash scripts/setup.sh

입력

사용자는 다음을 제공합니다:

저장소 경로 (필수): 클론된 저장소의 경로
건너뛰기 플래그 (선택 사항): 쉼표로 구분된 건너뛸 단계 목록
보고서 출력 경로 (선택 사항): 최종 보고서를 작성할 위치
런타임 검증 (선택 사항): PoC 테스트를 위해 Docker를 시작할지 여부

$ARGUMENTS에서 다음 형식을 사용하여 파싱합니다:

/repo-security-review /path/to/repo [--skip phase1,phase3] [--output /path/to/report.md] [--runtime]

인수 파싱 규칙

인수	기본값	설명
(첫 번째 위치 인수)	필수 (단일 저장소 모드)	저장소 경로. `--repos`가 사용될 때는 생략합니다.
`--repos`	없음	다중 저장소 모드를 위한 쉼표로 구분된 저장소 경로 목록. 0단계와 7단계를 활성화합니다. 설정 시 첫 번째 위치 인수는 필요하지 않습니다.
`--skip`	없음	건너뛸 쉼표로 구분된 단계 이름: `secrets`, `architecture`, `dependencies`, `owasp`, `validation`
`--output`	없음 — 모든 산출물은 싱글 저장소의 경우 `{repo_path}/.security-review/`, 멀티 저장소의 경우 `./system-security-review/`에 유지됩니다.	실행 후 최종 보고서와 PoC 스크립트를 복사할 디렉터리. 존재하지 않으면 생성됩니다. 멀티 저장소 모드에서는 강력히 권장됩니다.
`--poc`	false	옵트인: 5단계에서 발견 사항을 검증한 후(CONFIRMED / CONFIRMED_LOW_CONFIDENCE), 이에 대한 PoC를 생성합니다. 이 플래그가 없으면 5단계는 모든 발견 사항을 검증하고 보고서에 전체 판정을 포함하지만 PoC 파일은 작성되지 않습니다. PR 모드(PoC를 생성하지 않음)나 벤더 모드(PoC 생성을 강제로 끔 — 벤더 모드 참조)에서는 효과가 없습니다.
`--runtime`	false	Docker 기반 런타임 PoC 검증을 활성화합니다. `--poc`를 암시합니다. 런타임 검증은 생성된 PoC 스크립트를 실행하므로 PoC 없이는 검증할 것이 없습니다.
`--vendor`	false	벤더/오픈소스 감사 모드. 회사가 채택을 고려 중인 타사 저장소를 감사합니다. 대상은 내부 보안 팀이며, 산출물은 채택 위험 판단(벤더를 위한 수정 목록이 아님)입니다. `secrets`, `dependencies`, `poc`를 강제로 건너뛰고, 모든 단계를 해결된 Standard 계층 모델(Opus는 절대 사용하지 않음)에 고정하며, 6단계를 벤더 보고서 형식으로 전환합니다. 아래 벤더 모드를 참조하십시오.
`--pr`	없음	PR 리뷰 모드. `--pr <base>...<head>` (또는 `--pr <base>` 단축형으로 `<base>...HEAD`)는 전체 저장소 대신 풀 리퀘스트의 diff만 검토합니다. 6/7단계 파이프라인을 `references/pr-review.md`로 대체하고, 해결된 Standard 계층 모델에 고정하며, `final-report.md` 대신 `pr-report.md`를 작성합니다. `--repos` 및 `--vendor`와 상호 배타적입니다. 아래 PR 리뷰 모드를 참조하십시오.
`--context`	없음	위협 모델을 보정하는 데 사용되는 인라인 `key=value,key=value`. 선택 사항 — 기본 동작을 위해 생략합니다. 아래 `--context`를 참조하십시오.
`--yes`	false	비대화형 모드. 모든 사용자 확인 프롬프트를 자동으로 승인합니다: `--output` 복사 확인, Docker 런타임 게이트(`--runtime`), 순수 스킬 저장소 자동 건너뛰기 계단식. 경로 유효성 검사(민감한 `--output` 대상 거부)는 절대 우회되지 않습니다. CI 또는 스크립트 실행 시 사용하십시오.
`--debug`	false	파일 읽기 단계가 실제로 어떻게 실행되었는지 기록하는 붙여넣기 친화적인 실행 로그를 `{repo_path}/.security-review/execution-log.md`에 작성합니다: 읽은 모든 파일과 줄 범위, 전체/부분 플래그, 보안 관련으로 분류되고 전체를 읽은 파일, 실행된 grep/도구, 실행되었거나 건너뛴 검사. 스킬 동작 검사를 위한 것으로 보고서 모드와 독립적입니다. 실행 로그를 참조하십시오.

저장소 경로가 제공되지 않고 --repos가 설정되지 않은 경우, 진행하기 전에 사용자에게 물어보십시오. 예외: --yes가 설정되었지만 저장소 경로가 제공되지 않은 경우, 프롬프트 대신 명확한 오류와 함께 중단하십시오 — 대화형 입력을 사용할 수 없습니다.

다중 저장소 모드는 --repos의 존재에 의해 활성화됩니다. 이 모드에서:

쉼표로 구분된 경로는 분석할 서비스 목록입니다.
--output은 제공되지 않으면 기본적으로 ./system-security-review/입니다.
0단계(서비스 토폴로지 매핑)는 저장소별 단계 전에 한 번 실행됩니다.
1~6단계는 각 저장소에 대해 순서대로 독립적으로 실행됩니다.
7단계(저장소 간 합성)는 모든 저장소별 단계가 완료된 후 한 번 실행됩니다.
출력 디렉터리에는 서비스별 하위 디렉터리와 시스템 수준 보고서가 모두 포함됩니다.

건너뛰기 단계 별칭:

secrets → 1단계
architecture → 2단계
dependencies → 3단계 + 3b단계
owasp → 4단계
validation → 5단계 전체(검증, 그리고 --poc가 설정된 경우 PoC도 모두 건너뜀)
skill-security → 4b단계

계단식 규칙:

--skip owasp → validation도 건너뜀(5단계가 작업할 내용이 없음). 검증이 건너뛰어지면 --poc는 효과가 없습니다.
--skip validation → --poc는 효과가 없음(PoC는 검증 판정이 필요하며, 판정이 없음)
--runtime without --poc → --poc가 암시됨; PoC 생성이 실행되어 런타임 검증이 검증할 대상을 갖게 됨

PR 모드(--pr)의 건너뛰기 별칭은 동일한 이름을 번호가 매겨진 단계가 아닌 references/pr-review.md의 단계에 대해 재해석합니다: secrets → 3단계, dependencies → 5단계, owasp → 4단계, validation → 6단계. architecture는 PR 모드에서 유효한 건너뛰기 대상이 아닙니다 — 1/2단계의 구조적 컨텍스트는 다른 모든 단계에 중요하며 건너뛸 수 없습니다. 전달 시 명확한 오류와 함께 중단됩니다. skill-security는 PR 모드에서 효과가 없습니다(4b단계가 실행되지 않음). --poc는 PR 모드에서 효과가 없습니다 — 이 모드는 PoC를 생성하지 않으며(아래 PR 리뷰 모드 참조), 플래그와 관계없습니다.

모델 구성

스킬은 항상 사용 가능한 최고 품질의 모델을 사용합니다. 모델 ID는 아래의 폴백 체인에서 런타임에 해결됩니다. 오케스트레이터는 1단계 전에 가용성을 프로브하고 해결된 ID를 run-metadata.json에 기록합니다.

모델 계층

모든 단계에서 두 계층이 사용됩니다:

계층	사용처	목적
Deep	2단계	확장된 추론: 아키텍처
Standard	0, 1, 3, 4, 4b, 5, 6, 7단계	집중 분석: 토폴로지 추출, 비밀, CVE, OWASP, LLM/AI 스킬 보안, 검증, 보고서, 저장소 간 합성

2단계만 Deep 계층을 사용합니다 — 이는 폴백이 아닌 명시적이고 의도적인 선택입니다. 0단계는 2026-07-30에 Standard로 이동되었습니다(토폴로지 매핑은 구조적 추출이지 보안 판단이 아닙니다). 4b단계와 7단계도 Standard로 이동되었으므로, 이제 Deep 계층은 아키텍처 분석만을 위해 예약되어 있습니다. LLM 보안 또는 저장소 간 합성 품질이 저하되면 재검토하십시오.

폴백 체인

각 계열을 순서대로 시도하십시오. 현재 API 키/계정 계층에서 사용 가능한 첫 번째 것을 사용하십시오. 해당 계열이 해석하는 구체적인 스냅샷을 그대로 수락하십시오. 특정 날짜가 있는 버전을 대상으로, 선호하거나 프로브하지 마십시오("claude-opus-4-8", "claude-sonnet-4-6" 없음) — 체인은 계열만 이름을 지정합니다.

Deep 계층:
  1. Opus 계열      ← 선호; 적응형 사고 지원
  2. Sonnet 계열     ← 폴백, Opus 계열을 완전히 사용할 수 없는 경우에만

Standard 계층:
  1. Sonnet 계열     ← 선호
  2. Haiku 계열      ← 폴백, Sonnet 계열을 완전히 사용할 수 없는 경우에만

claude-fable-5는 어느 계층의 어떤 위치에서도 선택할 수 없습니다. 출시 후 가드레일로 인해 2단계와 4b단계가 의존하는 공격 경로 및 주입 벡터 추론에 대해 지나치게 신중한 거부를 야기할 수 있습니다. 이것이 스킬이 여전히 적용하는 유일한 모델 수준 제외 사항입니다. 계열 내의 다른 모든 것은 계정이 현재 제공하는 스냅샷이라면 무엇이든 허용됩니다.

계층의 계열(및 그 하나의 폴백 계열)에 있는 어떤 것도 사용할 수 없으면 명확한 오류와 함께 중단하십시오. 다른 계층의 모델을 대체하지 마십시오(예: Standard에서 Deep으로 또는 그 반대로 절대 폴백하지 마십시오) — 유일한 예외는 Fable 5로, 사용 불가능 여부와 관계없이 절대 대체되어서는 안 됩니다.

설계상 계열만 — 버전 고정은 어디에도 없습니다. 스킬은 특정 날짜가 있는 스냅샷을 이름을 지정하거나, 대상으로 하거나, 선호하지 않습니다 — 오직 계층(Deep/Standard)과 계열(Opus/Sonnet/Haiku)만 사용합니다. 계정이 현재 해당 계열에 대해 제공하는 구체적인 모델이 무엇이든 그대로 수락합니다. 새 스냅샷이 해석되는 것은 예상된 동작이지 실패 조건이 아니며, 절대 게이트하거나 질문하거나 프롬프트로 처리할 사항이 아닙니다. 실제로 해석된 모든 것은 run-metadata.json에 기록됩니다. 이는 스킬이 목표로 한 대상이 아니라 결과에 대한 관찰입니다.

벤더 모드(--vendor)는 계층 해석을 재정의합니다. --vendor가 설정되면, 모든 단계는 해결된 Standard 계층 모델을 사용합니다 — Sonnet 계열, Sonnet을 완전히 사용할 수 없는 경우에만 Haiku 계열로 폴백 — Opus는 절대 사용하지 않습니다. 둘 다 사용할 수 없으면 명확한 오류와 함께 중단하십시오(모드의 계약은 "Standard 계층만, Deep은 절대"입니다 — Deep 계층 모델을 조용히 빌려오지 마십시오). 벤더 모드를 참조하십시오.

대화형 Claude Code 세션 내부의 디스패치 현실: 단계가 원시 Anthropic API 호출 대신 세션 자체의 하위 에이전트 디스패치 도구를 통해 생성될 때, 모델 선택은 소수의 일반 계열 별칭(예: opus / sonnet / haiku)과 추론 노력 계층으로만 노출됩니다 — 정확한 날짜가 있는 모델 ID나 명시적인 thinking 매개변수는 절대 없습니다. 이러한 일반 별칭은 활성 계정에 대해 현재 표준인 모델로 해석됩니다. 위의 계열 전용 참고 사항에 따라 그대로 수락하십시오. 어떤 경로가 사용되었든 실제로 해석되고 디스패치된 것을 run-metadata.json → fallback_notes에 기록하여 독자가 항상 특정 단계의 출력을 생성한 구체적인 모델을 알 수 있도록 하십시오. 여전히 중단되는 유일한 경우는 계열 자체를 완전히 사용할 수 없거나(예: opus-계열 모델이 전혀 없음) 해석 가능한 유일한 옵션이 claude-fable-5인 경우입니다.

사고 규칙(해결된 모델에 적용)

정확한 버전이 아니라 계열별로 키가 지정됩니다. 해석된 스냅샷이 4.x인지 5세대인지에 관계없이 동일한 계열/계층 행이 적용됩니다.

해결된 계열	계층	thinking 매개변수(원시 API 디스패치)	에이전트 도구 노력(별칭 디스패치)
Opus (모든 세대)	Deep	`thinking: {type: "adaptive"}`	`"high"`
Sonnet (모든 세대)	Deep (폴백) / Standard	해석된 스냅샷이 `adaptive`도 지원하는 Sonnet 5가 아닌 한 `thinking` 매개변수 생략	`"medium"`
Haiku (모든 세대)	Standard (폴백)	`thinking` 매개변수 생략	`"medium"`

절대 thinking: {type: "disabled"}를 전달하지 마십시오 — 적응형 사고 전용 Opus 스냅샷은 이에 대해 400을 반환합니다. 사고가 필요하지 않을 때는 매개변수를 완전히 생략하십시오.

모델 해석 단계

1단계를 생성하기 전(또는 다중 저장소 모드에서는 0단계 전):

1. 계열별로 시도별 프로브를 통해 각 계층을 해석합니다:
   - Deep 계층의 기본 계열(Opus)을 요청하는 최소 에이전트 호출을 시도합니다. 성공하면, 그것이 해석된 Deep 모델입니다. 반환된 구체적인 스냅샷을 그대로 수락하십시오. 특정 날짜 버전을 대상으로 하거나 선호하지 마십시오.
   - 모델을 찾을 수 없음/모델을 사용할 수 없음 오류와 함께 실패하면, Deep 계층의 한 폴백 계열(Sonnet)을 시도하십시오. 그것도 실패하면 명확한 오류와 함께 중단하십시오. 이 두 계열 외의 모델을 대체하지 마십시오.
   - Standard 계층(기본: Sonnet 계열; 폴백: Haiku 계열)에 대해 동일한 워크스루를 반복하십시오.
   - 대화형 Claude Code 세션 내부에서 이 "시도"는 문자 그대로의 날짜 ID가 아닌 하위 에이전트 디스패치 도구를 통해 계층의 계열 별칭(`opus` / `sonnet` / `haiku`)을 요청하는 것입니다. 위의 "디스패치 현실"을 참조하십시오. 해당 경로에는 정확한 ID로 프로빙하는 것이 없습니다. 별칭이 해석되는 것이 무엇이든 해석된 모델입니다.
   - 참고: Bash 명령으로 `claude models list`를 실행하지 마십시오. 대화형 Claude Code 세션 내부에서 해당 문자열은 대화형 인터페이스로 라우팅되어 CLI 바이너리가 아닌 설명 응답을 생성합니다.

2. 해결된 계열에 대한 thinking 매개변수/노력을 결정합니다(위 표 참조).

3. 해결된 ID와 fallback_notes 필드와 함께 run-metadata.json을 작성합니다.
   계층의 폴백 계열이 기본 계열 대신 사용될 때마다 fallback_notes를 포함시켜 실행의 모델 해석을 사후에 감사할 수 있도록 합니다.

run-metadata.json

단일 저장소: {repo_path}/.security-review/run-metadata.json에 작성합니다. 다중 저장소: 공유 복사본 하나를 {output_dir}/run-metadata.json에 작성합니다.

아래의 구체적인 ID는 설명용일 뿐입니다. 기록되는 내용의 형태를 보여주는 것이지, 스킬이 목표로 한 대상을 나타내는 것이 아닙니다. 실제 값은 각 계열이 실행 당일에 해석하는 스냅샷입니다(위의 계열 전용 참고 사항에 따라 다른 Opus 또는 Sonnet 스냅샷일 수도 있습니다).

{
  "resolvedModels": {
    "deep": "claude-opus-5-20250508",
    "standard": "claude-sonnet-5-20250508"
  },
  "fallbackNotes": {
    "deep": null,
    "standard": null
  },
  "modelSelectionMethod": "probe-by-attempt: agent-dispatch alias"
}

해당 단계가 실행되지 않으면(예: --skip architecture로 인해 2단계가 건너뛰어짐) "deep" 키가 없는 JSON입니다. 건너뛰어지지 않은 단계에 대해서만 기록하십시오.

단계

보안 검토는 아래 설명된 대로 순차적 단계로 구성됩니다. 마지막 단계가 완료되면 보고서가 이미 생성되어 있습니다. --output이 제공된 경우에만 최종 보고서도 해당 위치에 복사됩니다.

0단계: 서비스 토폴로지 매핑 (다중 저장소 모드 전용)

입력: 쉼표로 구분된 저장소 경로 목록 ($ARGUMENTS에서 --repos) 출력: {output_dir}/system-topology.json

각 저장소의 루트 README.md, package.json(또는 유사한 매니페스트) 및 기본 배포 구성(docker-compose.yml, Dockerfile, helm/ 등)을 읽습니다.
각 서비스가 시스템에 어떻게 기여하는지 식별합니다: 마이크로서비스, 라이브러리, 게이트웨이, 데이터베이스 등.
서비스 간 통신 흐름을 추론합니다(명시적인 HTTP/gRPC/REST 정의를 찾거나 파일 독점성에서 추론).
ESLint 구성, tsconfig 프로젝트 참조, 모노레포 도구, 애플리케이션 매니페스트와 같은 리포지토리 메타데이터를 활용하여 서비스 간의 관계를 정확하게 설명하는 시스템 토폴로지 맵을 구성합니다.
토폴로지를 {output_dir}/system-topology.json에 작성합니다.

1단계: 비밀 키 스캐닝

입력: 저장소 경로 출력: {repo_path}/.security-review/secrets-and-injection.json

git log -p에 대해 gitleaks를 실행합니다. Gitleaks 결과를 수집하고 각 발견에 대해:
- 파일 경로
- 비밀 유형 (예: AWS Secret Key, GitHub Token)
- 발견된 텍스트(첫 15자만: {REDACTED}가 아닌 실제 스니펫은 절대 기록하지 마십시오)
- 커밋 SHA
출력을 기계 판독 가능한 JSON 형식으로 저장합니다.
gitleaks를 사용할 수 없는 경우, 강력한 메시지와 함께 건너뛰십시오("gitleaks not found — scan skipped").
(선택 사항) 비밀 발견 위험이 낮거나 없음에도 불구하고 태그가 지정된 가양성 패턴을 자동으로 필터링합니다. 파일당 하나의 가양성 규칙 세트에 대해 보고하는 대신 단일 요약 메모로 압축하십시오. 예: ""dummy"

[...] 일부 콘텐츠가 잘렸지만 충분한 맥락을 제공합니다.

참고: 위 내용은 원본 SKILL.md의 일부로, 번역 요청 시 원본의 일부가 잘렸습니다. 전체 내용은 원본 SKILL.md를 참조하십시오.

Consensys/repo-security-review

repo-security-review란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서

보안 검토 스킬

전제 조건

입력

인수 파싱 규칙

모델 구성

모델 계층

폴백 체인

사고 규칙(해결된 모델에 적용)

모델 해석 단계

run-metadata.json

단계

0단계: 서비스 토폴로지 매핑 (다중 저장소 모드 전용)

1단계: 비밀 키 스캐닝

관련 스킬

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7