에이전트에게 보안 감사를 맡기되 스스로 채점은 못 하게: cloudflare/security-audit-skill의 6단계 워크플로·커버리지 원장·3판정 findings 계약 심층 해부

코딩 에이전트에게 “이 저장소 보안 감사 좀 해 줘”라고 맡기면 보통 두 가지 문제가 생긴다. 하나는 컨텍스트가 금방 차서 저장소의 일부만 보고 끝난다는 것, 다른 하나는 자기가 찾은 버그를 자기가 채점한다는 것이다. 그러면 “exec()가 실행된다, 고로 치명적 취약점” 같은 동어반복 보고서가 쌓인다. cloudflare/security-audit-skill은 Cloudflare 보안팀이 사내 취약점 탐지 하네스를 만들기 전에 실제로 쓰던 단일 저장소용 감사 스킬을 MIT로 공개한 것이다. 오늘(2026-10-21) GitHub Trending 전체 일간 2위(오늘 +1,712 stars)에 올라 있다.

핵심 아이디어는 단순하다. 탐지(헌터)와 판정(검증자)을 서로 다른 새 에이전트로 쪼개고, 진행 상태는 대화가 아니라 coverage-ledger.json·findings.json 같은 파일에 남기며, 그 파일의 형식은 의존성 없는 Node 검증기 두 개가 기계적으로 막는다. 이 글은 ① 저장소 구조와 6단계 워크플로, ② 커버리지 원장과 세 판정(confirmed/needs_validation/rejected) 계약, ③ 샌드박스·쓰기 격리라는 신뢰 경계, ④ 비용 예산 규칙, ⑤ 비슷한 도구와의 차이를 실무자 눈높이에서 뜯어본다. 그리고 박스(리눅스 VM)에서 API 키 없이 공식 테스트와 직접 만든 정상·비정상 입력 20여 개로 검증기를 돌려, 무엇을 막고 무엇을 그냥 통과시키는지 확인했다. 수치는 모두 2026-10-21 11:51~11:56 KST에 실측했거나 저장소·GitHub API·Cloudflare 블로그에서 확인한 값이다.

한눈에 보기: 오늘 기준 스냅숏

왜 지금 주목받나: ‘하네스’의 씨앗을 그대로 꺼내 놓았다

저장소 자체는 4개월 전에 만들어졌고 마지막 커밋도 9월 중순이다. 그런데도 오늘 트렌딩 상위에 오른 건, 에이전트에게 보안 리뷰를 맡기는 흐름이 실무로 내려오면서 “그럼 결과를 어떻게 믿느냐”는 질문의 답으로 이 스킬이 다시 회자되고 있기 때문으로 보인다. 실제로 열린 이슈·PR은 10월 들어 계속 늘고 있다(10-20 하루에만 PR #82~#85, 이슈 #80·#81). 내용도 대부분 원장 상태 전이, 완료 조건, Windows 검증기 같은 계약의 빈틈을 메우자는 것이다.

저장소 구조: 코드가 아니라 ‘프롬프트 + 계약 + 검증기’

이 저장소에는 실행 엔진이 없다. 오케스트레이션은 사용자의 코딩 에이전트(Claude Code, Codex, OpenCode 등)가 맡고, 저장소는 그 에이전트가 따라야 할 절차서와 결과물이 지켜야 할 형식 계약, 그 계약을 확인하는 결정적 코드만 제공한다. SKILL.md가 진입점이고, 나머지 문서는 필요한 단계·도메인에서만 읽히는 동반 문서다.

두 가지 모드: 불러오는 것과 감사를 시작하는 것은 다르다

9월 15일 커밋의 요점은 “스킬을 불러왔다고 전체 감사를 시작하는 건 아니다”라는 구분이다. 보안 질문이나 특정 버그 조사는 guidance 모드로 필요한 부분만 쓰고, 파일을 만들지 않는다. “이 코드베이스를 감사해 줘”, “침투 테스트 해 줘”, “보고서 파일로 줘”처럼 명시적으로 요청할 때만 full audit 모드로 6단계를 모두 돈다. 어느 쪽인지 애매하면 파일을 만들기 전에 한 번 묻도록 돼 있다.

6단계 워크플로와 산출물

눈여겨볼 점은 Cloudflare가 블로그에서 말한 세 가지 벽(컨텍스트 고갈, 중간 실패 시 처음부터 다시, 저장소 간 추론 불가) 중 앞의 두 개를 파일 기반 상태로 부분적으로 완화한다는 것이다. 원장과 이전 findings를 다음 실행이 읽고 이어 가므로 “여러 번 돌리면 누적된다”. 반면 저장소 간 추적은 이 스킬의 범위 밖이고, 블로그도 그건 하네스(데이터베이스 + 오케스트레이터)의 몫이라고 선을 긋는다.

커버리지 원장: ‘봤다’를 셀 수 있게 만드는 장치

원장의 한 단위는 canonical_refs의 네 값(surface, boundary, subsystem, attack_class)으로 정의되고, coverage_id는 이 네 값을 퍼센트 인코딩해 ::로 이은 결정적 문자열이다. 박스에서 실제로 계산해 보니 src/router.ts#POST /users/:id 같은 입력은 src%2Frouter.ts%23POST%20%2Fusers%2F%3Aid::src%2Fauthz.ts%23requireOwner::…가 됐고, 임의 값을 넣으면 검증기가 기대값을 보여 주며 거부했다. 같은 단위는 실행이 바뀌어도 같은 ID를 가지므로 이전 실행과 대조할 수 있다.

이전 실행과의 관계는 prior_status 11개 값(prior_confirmed_same_source, prior_covered_changed_source, prior_rejected_claim_changed 등)으로 표현한다. 원칙은 “이전 소스 ref가 같다는 것만으로는 바뀌지 않았다는 증거가 아니다”이다. 이전에 확인된 취약점도 현재 소스가 그대로일 때만 이어받고, 그래도 현재 검증 경로를 다시 통과해야 한다. 이전 quick 실행이나 범위 지정 실행은 “나머지는 괜찮다”는 뜻이 절대 아니다.

세 판정 계약: 심각도는 confirmed에만

스키마 외의 의미 검사도 꽤 촘촘하다. 배열은 fingerprint 사전순 정렬·중복 금지, trace는 entrypoint로 시작해 sink로 끝나고 중간은 모두 propagation, 파일 경로는 저장소 상대 경로만(../·절대 경로·제어 문자·Windows 예약 이름 거부), 문자열은 “보이는 글자”가 하나는 있어야 한다(공백·제로폭 문자만 있으면 거부). 심각도 기준점도 문서에 명시돼 있다. critical은 “인증 없는 공격자의 코드 실행·전체 데이터 접근·임의 계정 탈취”, high는 “명시적 통제를 완전히 무력화”, medium은 “영향 범위가 제한된 실제 경계 위반”이다. 판별 질문은 하나다. “통제를 완전히 무너뜨렸나, 약하게 만들었을 뿐인가?”

후보 게이트: 프롬프트 인젝션만으로는 발견이 아니다

헌터는 후보를 내기 전에 7조짜리 게이트를 통과해야 한다. 핵심은 “낮은 신뢰 주체, 받아들여진 입력, 의도된 통제, 넘어간 경계, 영향받은 주체·자원, 관측 결과”를 모두 이름 붙이라는 요구다. LLM 기반 대상을 위한 AI-AND-LLM.md는 이 원칙을 더 날카롭게 적용한다.

신뢰 경계: 대상 코드는 적대적이라고 가정한다

감사 대상 저장소는 공격자가 쓴 코드일 수도 있다. 그래서 스킬은 소스 읽기는 읽기 전용으로 하고, 대상이 통제하는 빌드·테스트·프로세스는 아래 통제를 전부 갖춘 OS 수준 샌드박스에서만 돌리라고 요구한다. 하나라도 못 갖추면 대상 코드를 실행하지 말고 그 후보를 needs_validation으로 남기라는 것이 기본값이다.

이 승격 절차는 꽤 편집증적으로 보이지만 이유가 있다. 헌터가 샌드박스 안에서 만든 “증거 파일”이 사실은 호스트의 다른 파일을 가리키는 심볼릭 링크이거나 하드 링크, FIFO일 수 있다. 검증기 CLI도 같은 철학으로 입력 파일을 연다. 박스에서 심볼릭 링크와 FIFO를 넘기자 각각 “input must not be a symlink”, “input must be a regular file”로 바로 거부했다. 다만 이 규칙들은 문서화된 절차이고, 실제로 지키는 건 사용자의 에이전트와 사용자가 준비한 샌드박스다. 스킬 저장소는 샌드박스를 제공하지 않는다. Cloudflare 블로그에 따르면 사내 하네스는 unshare 기반 샌드박스를 썼고, Docker 안에서 돌릴 때는 seccomp·AppArmor 설정이 필요했다고 한다.

프로필과 비용 예산: 에이전트 호출 수로 센다

예산은 “전체 단계의 최대 에이전트 호출 수”로 run-metadata.json에 기록한다. 정찰 전에 엄격한 게이트를 먼저 적용한다. 기본 정찰 4회, 비평가(quick은 1회, standard·deep은 2회), 검증자 최소 1회를 예약하지 못하면 에이전트를 하나도 띄우지 않고 budget_cannot_fund_reconnaissance_and_reserves로 끝낸다. 헌터는 비평가·검증 예약분에 절대 손대지 않는다(애매하면 남은 예산의 30%를 검증에 예약). 검증 예산이 바닥나면 미검증 후보를 needs_validation으로 둔갑시키지 말고 validation_budget_exhausted로 미완료를 선언하라고 못 박는다. 사용자가 정한 예산을 조용히 넘기지 말라는 규칙도 있다.

설치와 실행

설치는 Vercel의 Skills CLI(npx skills)로 한다. 박스에서는 격리된 HOME과 빈 git 저장소를 만들어 Claude Code 대상으로 설치해 봤다.

# 프로젝트 단위 설치 (Claude Code 대상, 비대화형)
mkdir proj && cd proj && git init -q .
npx -y skills add https://github.com/cloudflare/security-audit-skill \
  --skill security-audit -a claude-code -y
#  → ./.claude/skills/security-audit (copied)
#  → skills-lock.json 에 source·skillPath·computedHash 기록

# 사용자 전역 설치
npx skills add https://github.com/cloudflare/security-audit-skill \
  --skill security-audit --global

# 에이전트 안에서의 호출 예 (README)
security audit this codebase                      # full audit 모드
find security vulnerabilities in ./src            # 범위 지정
do a security review, output to ~/audits/my-project

# 검증기는 단독으로도 쓸 수 있다 (Node만 필요, 의존성 0)
node .claude/skills/security-audit/validate-coverage-ledger.cjs <out>/coverage-ledger.json
node .claude/skills/security-audit/validate-findings.cjs <out>/findings.json
node --test .claude/skills/security-audit/*.test.cjs

박스 스모크 테스트: 검증기는 무엇을 막고 무엇을 놓쳤나

전체 감사는 돌리지 않았다. 그러려면 도구 호출과 병렬 서브에이전트를 지원하는 코딩 에이전트와 모델 API가 필요한데, 이번 테스트는 비밀 값 없이 하는 것이 원칙이었다. 대신 이 스킬에서 결정적으로 동작하는 유일한 부분인 두 검증기를 집중적으로 두드렸다. 환경은 박스 리눅스 VM, Node v20.19.2, 커밋 c1c8a8c, 네트워크는 설치 단계에서만 사용했다.

정리하면, 형식 계약 위반과 적대적 파일 입력에는 매우 단단하다. 대신 아래 세 가지는 그냥 통과했다. ① 추가 CLI 인자를 조용히 무시한다. CI에서 validate-findings.cjs a.json b.json처럼 쓰면 b가 틀려도 초록불이 뜬다. 열린 PR #63(“Reject extra CLI arguments”)이 바로 이 문제다. ② 빈 원장이 통과한다. 원장 검증기는 단위 하나하나가 올바른지 보지 정찰이 충분한 단위를 만들었는지는 보지 않는다. 이슈 #79(“complete가 in_progress/blocked 없는 원장을 요구하지 않는다”)와 PR #84도 같은 맥락이다. ③ 당연하지만 내용의 참·거짓은 모른다. 파일·줄 번호가 실제로 존재하는지도 이 두 검증기는 확인하지 않는다. Cloudflare 블로그의 사내 하네스는 이걸 별도 결정적 코드로 검사한다고 했다.

비슷한 도구와 비교

Cloudflare 블로그에는 흥미로운 관찰이 하나 있다. Semgrep을 파이프라인 끝까지 연결해 뒀는데 헌터들이 한 달 동안 한 번도 부르지 않았다는 것이다. 에이전트는 규칙 엔진보다 코드를 직접 읽고 돌려 보는 쪽을 택했다. 그렇다고 SAST가 필요 없다는 뜻은 아니다. 결정적 도구는 매 PR마다 싸게 돌고, 이 스킬은 주기적으로 깊게 도는 감사에 가깝다. 둘은 대체 관계보다 보완 관계로 보는 편이 맞다.

주의할 점과 한계

누가 도입하면 좋은가

정리하자면 cloudflare/security-audit-skill은 “AI가 보안 감사를 해 준다”는 마법 상자가 아니다. AI가 낸 보안 결과를 어떤 형식으로 남기고, 누가 반박하며, 무엇을 아직 모른다고 말해야 하는지를 정한 운영 규약에 가깝다. 그 규약의 기계적 부분은 박스에서 확인한 대로 단단하지만 몇 군데 빈틈이 있고, 나머지는 쓰는 사람의 에이전트와 샌드박스에 달려 있다. 에이전트 보안 리뷰를 이미 실험하고 있다면 프롬프트보다 이 계약과 원장 구조를 먼저 가져다 쓰는 것을 권한다.