security-audit-skill 쓰는 법
Cloudflare의 오픈소스 코딩 에이전트 스킬 security-audit-skill을 Skills CLI로 설치하고 보안 감사를 돌리는 방법을 정리한 가이드다. 여섯 단계 감사와 findings 판정·리포트 산출물까지 공식 README 기준으로 따라간다.
security-audit-skill(cloudflare/security-audit-skill)은 Cloudflare가 공개한 오픈소스 코딩 에이전트 스킬이다. 한 줄로 말하면, 코딩 에이전트를 다단계 보안 감사관으로 바꿔 주는 프롬프트·워크플로 묶음이다. 라이선스 MIT, GitHub 스타 약 22,700(작성 시점 API 기준). 이 스킬이 나중에 Cloudflare의 취약점 발견 하네스(harness)로 자란 출발점이고, 배경은 공식 블로그 Build your own vulnerability harness에 정리돼 있다.
이 글은 “security-audit-skill 쓰는 법”만 다룬다. Skills CLI로 설치하고, 감사 문구로 실행하고, findings.json·리포트가 어디에 쌓이는지까지 공식 README 기준으로 따라간다.
핵심 요약 (TL;DR)
- 무엇인가: 코딩 에이전트용
security-audit스킬. 정찰 → 커버리지 기반 사냥 → 후보 검증 → 구조화 출력 → 독립 재검증 → 타깃 중립 리포트, 여섯 단계로 감사를 돌린다. - 설치:
npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit(전역은--global). - 호출 예: “security audit this codebase”, “find security vulnerabilities in ./src”처럼 보안 감사·취약점 탐색 요청이면 스킬이 걸린다.
- 판정 세 가지:
confirmed/needs_validation/rejected. 확인된 것만 심각도를 붙이고, 미해결 사실은needs_validation으로 남긴다. - 산출물:
findings.json,REPORT.md,FINDINGS-DETAIL.md,NEEDS-VALIDATION.md,coverage-ledger.json등. - 필수 조건: 도구 사용 + 병렬 서브에이전트를 지원하는 코딩 에이전트, Node.js(검증 스크립트), OS 강제 샌드박스(없으면 타깃 코드 실행 대신
needs_validation으로 남김).
할 수 있는 일
먼저 용어만 짧게 풀어 둔다.
- 코딩 에이전트: 파일을 읽고, 명령을 돌리고, 수정을 제안하는 AI 개발 도우미(Claude Code, Codex, Cursor 계열 등).
- 스킬(skill): 에이전트에게 “이 작업은 이렇게 하라”는 절차·프롬프트·보조 파일을 묶어 넣는 패키지. 여기서는 Skills CLI(skills.sh)로 설치한다.
- 하네스(harness): 여러 에이전트·단계를 오케스트레이션하는 실행 껍데기. Cloudflare는 이 스킬로 시작해 함대(fleet) 규모 파이프라인으로 키웠다. (한글로는 하네스라고 쓴다.)
- findings 판정: 후보 취약점을
confirmed(출처·관찰 결과가 닫힘),needs_validation(정확한 미해결 사실 남음, 심각도 없음),rejected(반증됨)로 나눈다.
공식 README 기준으로 바로 할 수 있는 일은 대략 이렇다.
- 단일 레포 보안 감사: 에이전트에게 코드베이스 감사를 시키면 여섯 단계 워크플로가 돈다.
- 커버리지 장부 기반 사냥:
coverage-ledger.json에 영역을 잡고, 빈칸을 메우는 식으로 헌터를 돌린다. 여러 번 돌리면 이전 장부·findings를 이어받아 빈 곳을 더 채운다(문서: 한 번 실행은 반복 실행 합의 대략 절반 정도를 찾는 경향). - 적대적 검증: 찾은 에이전트와 다른(fresh) 검증 에이전트가 후보를 뒤집으려 한다.
- 기계 검증 스크립트: 부모가
validate-coverage-ledger.cjs,validate-findings.cjs를 돌려 스키마·장부를 맞춘다(Node, 외부 의존성 없음). - 사람·도구가 읽기 쉬운 산출물: JSON + 마크다운 리포트로 triage·상세·미검증 목록을 남긴다.
- 공격 클래스 확장 문서: 웹·메모리 안전·AI/LLM·공급망·클라우드 등 클래스별 프롬프트 파일이 스킬 안에 들어 있다.
필요한 것
| 항목 | 공식 근거 | 메모 |
|---|---|---|
| 코딩 에이전트 | README Requirements | 도구 사용(tool use) + 병렬 서브에이전트를 지원하는 모델/에이전트 |
| Skills CLI | README Installation · skills.sh | npx skills add …로 설치. 에이전트 선택·비대화형 옵션은 npx skills --help |
| 스킬 이름 | README | --skill security-audit (레포 경로와 스킬 이름을 헷갈리지 말 것) |
| Node.js | README Requirements | validate-findings.cjs / validate-coverage-ledger.cjs 실행용 |
| OS 강제 샌드박스 | README Requirements | 외부망 차단, 허용된 env, 리소스 한도, 지정 scratch에만 쓰기. 없으면 타깃 코드 실행 대신 lead를 needs_validation으로 유지 |
| 라이선스 | README / LICENSE | MIT |
| 스타(참고) | GitHub API (작성 시점) | 약 22,733 |
| 관련 블로그 | Cloudflare Engineering | Build your own vulnerability harness (2026-06-18) |
링크: GitHub · skills.sh 페이지 · Cloudflare 블로그.
단계
1) Skills CLI로 스킬 설치
프로젝트(또는 에이전트가 읽는 스킬 디렉터리)에 설치한다. README와 동일하다.
npx skills add https://github.com/cloudflare/security-audit-skill \
--skill security-audit
모든 프로젝트에서 쓰려면 사용자 전역 설치:
npx skills add https://github.com/cloudflare/security-audit-skill \
--skill security-audit \
--global
에이전트 선택·비대화형 플래그는 npx skills --help를 본다. skills.sh 설명에는 짧은 형태 npx skills add cloudflare/security-audit-skill도 안내돼 있으니, 환경에 맞게 쓰면 된다. 중요한 건 스킬 id가 security-audit이라는 점이다.
2) 감사할 코드베이스에서 에이전트 실행
감사 대상 레포 안에서(또는 그 경로를 가리킨 채) 코딩 에이전트를 켠 뒤, 보안 감사 요청을 한다. README 예시:
security audit this codebase
find security vulnerabilities in ./src
do a security review, output to ~/audits/my-project
보안 감사·취약점 탐색·펜테스트류 요청이면 스킬이 자동으로 걸린다. 전체 감사 모드에서는 출력 디렉터리를 안 정하면 기본이 ~/security-audit-skill/<repo-name>/run-<N>이다. 대상 레포 안에 쓰려면, 버전 관리가 무시하는 디렉터리를 직접 지정해야 한다(README 안내).
3) 여섯 단계가 도는 방식 (읽을 때만)
- Reconnaissance — 아키텍처·신뢰 경계·입력면·기존 증거를
architecture.md와coverage-ledger.json에 정리. - Coverage-led hunting — 장부 단위로 격리된 헌터를 돌리고, 커버리지 크리틱으로 빈칸을 찾음.
- Candidate validation — 후보마다 fresh verifier가 반증을 시도.
- Structured output —
confirmed/needs_validation/rejected를findings.json에 쓰고report-schema.json으로 검증. - Independent record verification — 또 다른 fresh 에이전트가 최종 출처 주장을 재확인. 교체된 기록은 다시 검증.
- Target-neutral reporting — 검증된 기록과 장부에서
REPORT.md,FINDINGS-DETAIL.md,NEEDS-VALIDATION.md를 생성.
부모 에이전트는 장부를 만든 뒤·갱신할 때마다 validate-coverage-ledger.cjs를, Phase 4와 Phase 5 교체 후에는 validate-findings.cjs를 돌린다.
4) 산출물 확인
실행이 끝나면 출력 디렉터리에서 최소한 아래를 본다.
findings.json— 기계가 읽는 판정 기록REPORT.md— 사람용 요약 리포트FINDINGS-DETAIL.md— 상세NEEDS-VALIDATION.md— 아직 닫히지 않은 리드coverage-ledger.json— 어디를 훑었는지 장부
confirmed만 “경계 실패가 출처와 관찰로 닫힌” 항목이다. 샌드박스 없이 타깃 코드를 못 돌렸거나 사실이 하나라도 비면 needs_validation으로 남는 게 정상 동작이다.
막히는 지점
| 증상 | 원인 후보 | 확인 / 해결 |
|---|---|---|
거의 모든 lead가 needs_validation | OS 강제 샌드박스 없음·미충족 | README Requirements: 외부망 차단, 허용 env, 리소스 한도, scratch 전용 쓰기. 조건이 안 되면 워크플로가 타깃 코드 실행 대신 미검증으로 남김 |
| 정찰·사냥이 얇거나 단계가 스킵되는 느낌 | 에이전트가 병렬 서브에이전트/도구 사용을 못 함 | tool use + parallel sub-agents를 지원하는 코딩 에이전트·모델인지 확인 |
validate-*.cjs 실패·미실행 | Node.js 없음·경로 오류 | Node 설치 후 스킬 디렉터리의 검증 스크립트를 부모가 돌리는지 확인 |
| 스킬이 안 걸림 | 잘못된 스킬 이름·미설치 | --skill security-audit인지, 프로젝트/글로벌 설치 경로를 에이전트가 읽는지 확인. 요청 문구에 security audit / vulnerabilities / pen-test 등이 들어가게 |
| 레포 안에 감사 산출물이 섞임 | 출력 경로를 VCS 추적 디렉터리로 지정 | 기본 ~/security-audit-skill/…를 쓰거나, ignore되는 디렉터리만 명시 |
| 한 번 돌렸는데 구멍이 많아 보임 | 단일 실행 한계 | 문서 설계상 여러 번 돌리며 장부·findings를 이어가는 전제. 한 번 ≈ 반복 합의 절반 수준이라는 설명 참고 |
| 가짜 양성처럼 보이는 confirmed | 검증 단계 스킵·자기 채점 | 스킬은 “찾은 에이전트 ≠ 검증 에이전트”, 출처 추적·관찰 결과가 닫혀야 confirmed. 의심되면 NEEDS-VALIDATION·상세 리포트와 원본 코드를 대조 |
마치며
security-audit-skill은 “AI야 보안 리뷰 해줘” 한 줄을 여섯 단계 감사 파이프라인으로 바꿔 주는 코딩 에이전트 스킬이다. Skills CLI로 security-audit을 깔고, 대상 레포에서 감사 문구를 던진 뒤, findings.json과 마크다운 리포트·커버리지 장부를 확인하면 된다. 샌드박스와 병렬 서브에이전트가 없으면 결과가 약해지거나 needs_validation으로 남는 게 설계이니, 그 조건을 먼저 맞추자. 설치 명령·요구사항은 시간이 지나면 바뀔 수 있으니, 실행 직전 GitHub README와 Cloudflare 블로그를 한 번 더 보면 안전하다.
이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.