Cloudflare의 무료 Skill을 사용하여, AI가 작성한 코드의 취약점을 공개 전에 Claude Code/Codex로 탐지하는 절차

AI Contents Bank를 운영하고 있는 슈우지입니다. Claude Code나 Codex로 코드를 작성하는 양이 늘어날수록, '작동은 하지만 안전한지는 알 수 없는' 코드의 양도 증가합니다. 본 기사에서는 Cloudflare가 MIT 라이선스로 공개한 보안 감사(security audit) Skill을 Claude Code/Codex에 적용하여, 직접 가진 코드의 허점을 공개 전에 찾아내는 과정과, 도출된 결과를 어떻게 읽어내야 하는지를 설명합니다.

절차와 프롬프트의 완전판은 Kit에 정리했습니다. 등록 없이 모두 읽으실 수 있습니다.

먼저 세 가지 전제 조건을 말씀드립니다.

사용하는 것은 본인(자사)이 관리하는 코드만입니다. 타인의 시스템을 무단으로 조사하는 행위는 부정접근금지법 등에 저촉될 수 있습니다.
운영 환경이나 외부 서비스에는 접근하지 않습니다. 코드는 읽기만 하고 실행하지 않습니다.
.env와 같은 비밀 정보도 열람하지 않습니다. 감사 보고서는 공개되지 않는 것입니다. 수정하기 전의 약점을 외부에 노출할 이유는 없습니다.

왜 필요한가: AI가 작성한 코드는 '작동'까지가 빠르다

AI에게 코드를 작성하게 하면, 작동하는 결과물이 나올 때까지는 매우 빠릅니다. 반면 리뷰는 사람의 속도를 따릅니다. 모든 차이점(diff)을 읽기 전에 다음 기능이 완성되어 있고, 어느새 '작동 확인은 했지만, 읽지 않은 코드'가 쌓이게 됩니다.

작동 확인으로 발견되는 것은, 작동하지 않았을 때 알 수 있는 버그입니다. 보안 허점은 아무 일도 일어나지 않기 때문에 알아차리기 어렵습니다. 로그인하지 않은 사람에게 보이는 화면, 원래는 본인 것만 보여야 할 목록, 자리를 잘못 둔 열쇠 등 모두 화면 자체는 정상적으로 작동합니다. 이를 발견하는 것은 자신 외의 누군가가 먼저 찾아냈을 때입니다.

그래서 '읽지 않은 코드'를 읽어내는 역할을, 작성한 AI와 별도로 세웁니다. 사람이 전부 읽는 것은 불가능하지만, 읽기 전문 에이전트라면 돌릴 수 있습니다.

Skill의 구조: 찾는 역할과 의심하는 역할을 분리하기

사용하는 것은 Cloudflare의 security-audit-skill입니다. 이 Skill은 Cloudflare 사내 취약점 발견 하네스(vulnerability discovery harness)에서 유래했으며, 1개의 리포지토리를 위한 출발점으로 공개되었습니다.

README에 적힌 과정은 총 6단계입니다. 내용을 부드럽게 풀어서 설명합니다.

정찰 (偵察): 구성, 신뢰 경계(trust boundary), 입력의 진입점을 지도화합니다.
탐색 (探索): 지도의 단위별로 여러 개의 에이전트(헌터)가 약점 후보를 찾습니다.
후보 검증 (候補の検証): 후보를 한 건씩, 깨끗한 검증 역할에 넘겨 '반증'을 시킵니다.
구조화 출력 (構造化出力): confirmed(확정)/needs_validation(요확인)/rejected(기각) 중 하나로 기록합니다.
독립 재검증 (独立した再検証): 최종적인 주장을 또 다른 에이전트가 확인합니다.
보고 (報告): REPORT.md, FINDINGS-DETAIL.md, NEEDS-VALIDATION.md를 출력합니다.

핵심은 3단계와 5단계입니다. 발견한 에이전트는 자신이 찾은 것을 검증하지 않습니다. README의 설계 원칙에도 '발견하는 쪽과 확인하는 쪽은 항상 별개'라고 쓰여 있습니다. AI 감사에서 가장 문제가 되는 것은 '그럴듯하지만 과도하게 많은 지적'이 나오는 것이므로, 의심하는 역할을 따로 세우는 이 구조는 실용적으로 매우 효과적입니다.

또 하나, 심각도의 부여 방식입니다. 심각도는 '확정(confirmed)'된 경우에만 붙으며, '발생 가능성 × 영향도'로 결정하고 체크리스트의 일탈로는 결정하지 않는다고 README에 명시되어 있습니다. 예를 들어, 'A 계층에서 방어되고 있다면, B 계층이 없는 것은 취약점이 아니라 보강 메모'라는 식으로 다룹니다. 이러한 경계 설정 덕분에 보고서가 단순히 '気になる点の羅列(신경 쓰이는 점의 나열)'이 되는 것을 막아줍니다.

실행하지 않는다는 전제

README의 요구사항에는 대상 코드를 빌드하거나 실행하려면 OS 레벨의 샌드박스(sandbox)가 필요하다고 적혀 있습니다. 이것이 없는 경우, 이 Skill은 실행되지 않고 해당 후보는 '요확인' 상태로 남게 됩니다.

Kit에서는 샌드박스를 준비시키는 대신, 처음부터 '코드는 읽기만 하고 실행하지 않는다'를 전제로 합니다. 그만큼 '요확인'이 많이 나오지만, 이는 설계대로입니다. 공개 전의 코드를 운영 환경이나 외부에 건드리지 않고 읽게 하는 것. 이 안전 쪽에서의 양보가 개인이나 작은 팀에서 돌릴 때 적절하다고 생각합니다.

안전하게 실행하기 위한 조건

Skill을 도입하는 것은 단 하나의 명령어만 필요합니다 (Skills CLI는 Node.js 22.20 이상이 필요합니다).

npx skills add https://github.com/cloudflare/security-audit-skill --skill security-audit -g -a claude-code -a codex -y

-g는 사용자 전체에 적용되므로, 애플리케이션 폴더에는 파일이 추가되지 않습니다. Claude Code와 Codex 모두에 적용됩니다.

실행 조건은 Kit의 프롬프트에 모두 작성되어 있습니다. 여기서는 무엇을 제한하는지만 나열합니다.

프로파일은 가벼운 것부터: 첫 번째는 quick으로 시작하며, 에이전트 호출은 총 40회까지로 제한합니다. 갑자기 깊게 실행하지 않습니다.

읽기 전용(Read only): 코드를 실행하지 않습니다. 빌드나 테스트도 이 단계에서는 돌리지 않습니다.
접근 금지(Do not touch): 프로덕션 환경, 외부 서비스, .env와 같은 비밀 정보 파일에 접근하지 않습니다.
수정 금지(Do not change): 소스 코드는 일절 수정하지 않습니다. 수정은 나중 단계에서 사람이 보면서 진행합니다.
보고서 위치: Skill의 기본 설정으로는 리포지토리 외부(~/security-audit-skill/<repo-name>/run-<N>)에 출력됩니다. 리포지토리 내부에 출력하는 것은 버전 관리 대상이 아닌 폴더를 명시했을 때만 가능합니다.
용어: REPORT.md는 엔지니어가 아닌 사람도 이해할 수 있는 일본어로 작성하도록 합니다.

마지막 하나는 사소하지만 중요합니다. 보고서를 읽는 사람이 본인 혼자라면 영어여도 문제가 없지만, 수정 우선순위를 누군가와 상의하는 상황에서는 한국어로 '무엇이, 어디서, 어떻게 문제인지'가 적혀 있는 것이 훨씬 빠릅니다.

결과 해석: 확정・요확인・기각

첫 번째 스캔이 끝나면, 보고서를 '읽는(Reading)' 과정을 별도로 거칩니다. Kit의 Step 3이 이 역할을 하며, AI에게 두 개의 표를 만들도록 지시합니다.

확정(confirmed) 표: 소스 추적과 영향 범위가 일치하는 항목입니다. 심각도가 표시되므로 위험한 순서로 정렬됩니다. Kit에서는 시급성을 '오늘', '이번 주', '이번 달', '나중에 해도 됨'의 4단계로 나누도록 합니다. '오늘'은 예를 들어 비밀 정보가 노출되는 곳에 놓여 있어 방치할 이유가 없는 경우입니다.

요확인(needs_validation) 표: '이 부분이 미확인'이라는 사실이 하나 남아있는 항목입니다. 심각도는 표시되지 않습니다. 표에는 '무엇을 확인해야 확정인지 기각인지 결정되는지'를 함께 작성하도록 합니다. 사람이 설정 화면만 보면 되는 경우도 있고, 샌드박스를 준비하지 않으면 결론을 내릴 수 없는 경우도 있습니다.

기각(rejected): 검증 담당자가 반증한 항목입니다. 보고서에는 남지만 수정 대상은 아닙니다. 남겨두는 이유는 다음 회차에서 같은 후보를 다시 꺼내지 않기 위함입니다.

여기서 기대치에 대해 한 가지 말씀드리겠습니다. README에는 '테스트에서는 1회 실행으로 발견된 것이 반복 실행했을 때의 총합의 약 절반이었다'고 쓰여 있습니다. 즉, 한 번만 돌렸다고 해서 절반은 남아있다고 생각하는 편이 좋습니다. 첫 번째는 '모든 것을 찾는 회차'가 아니라, '당장 고칠 것을 찾는 회차'입니다.

개별 수정: 브랜치・테스트・승인

수정도 AI에게 맡기지만, 한 번에 몰아서 주지 않습니다. 하나씩입니다. Kit의 Step 4 프롬프트가 제한하는 것은 다음 5가지입니다.

main에서 해당 항목을 위한 수정 브랜치를 분기(branch)합니다. 수정은 지정된 부분만 합니다. '덤으로'를 금지합니다.
재발 방지 테스트를 하나 추가합니다. 기존 테스트는 모두 통과해야 합니다.
변경 내용을 3줄로 설명하도록 합니다.
push하기 전에 멈추고, 사람의 승인을 기다립니다.

개별적으로 처리하는 이유는 차이점(diff)을 읽을 수 있는 양에 맞추기 위함입니다. AI는 '수정한다'고 하면 주변까지 깔끔하게 정리하려는 경향이 있어, 차이점이 부풀려지면 사람이 무엇을 수정했는지 추적할 수 없게 됩니다. 보안 수정에서 그렇게 할 경우, 고쳤다고 생각했지만 다른 구멍을 만들게 됩니다.

3줄 설명은 PR(Pull Request)의 설명문에 그대로 사용할 수 있습니다. 무엇을 고쳤는지를 사람의 언어로 남겨두면, 다음 회차 보고서에서 '고쳐졌다'고 나왔을 때 대조할 수 있습니다.

지속적인 실행: 월 1회 및 차이점

Kit의 Step 5는 '계속하기(Continue)'입니다. 할 일은 두 가지가 있습니다.

월 1회 재감사. 먼저, 지난 회차의 '확정' 항목들이 수정되었는지 확인시킨 후, 한 단계 깊은 standard

프로파일(Profile)로 (최대 호출 60회까지) 실행합니다. 나온 결과를 '수정됨', '남음', '새롭게 발견됨'의 세 가지로 분류하도록 합니다. README에 나와 있듯이, 이 Skill은 과거 기록과 결과물을 사용하여 다음 회차에서 허점을 노리기 때문에, 반복할수록 그물망이 촘촘해집니다.

main에 큰 변경 사항을 넣기 전의 차분 검사. 차분만 대상으로 quick으로 실행합니다(최대 호출 20회까지). 새로 늘어난 위험 지점이 있다면 3줄 이내로, 없다면 '없음'이라고 답변하도록 합니다. 이것은 월 1회와는 별개로, 머지(merge) 전 습관으로 만듭니다. '이것으로 안전해졌다'라고 어느 단계에서도 말할 수 없습니다. 말할 수 있는 것은 '미리 발견하여 구멍을 줄였다'까지만입니다. 그래도 자신 외의 누군가에게 먼저 발견당하는 것보다는 훨씬 낫습니다.

완전한 절차는 Kit에

Kit은 '준비 → 가벼운 스캔 → 읽기 → 항목별 수정 → 지속'의 5단계로 구성되어 있습니다. 준비 시간이 10분, 첫 번째 스캔이 30분부터 시작하며, 수정 작업은 항목당 15~30분이 소요되는 것이 기준입니다.

본 기사에서는 구조와 읽는 방법만 작성했습니다. AI에 붙여 넣을 프롬프트 전문, 도입 확인 절차, 결과를 표로 만들도록 지시하는 내용, 수정 브랜치(branch)에 대한 지시는 Kit에 있습니다. 등록 없이 모두 읽을 수 있습니다.

직접 실행하기 어려운 경우

코드를 직접 만지지 않거나, 개발을 외주 맡기는 경우에는 외부 진단 서비스에 의존하는 흐름을 별도의 Kit으로 만들었습니다. AgenticSec이라는 외부 유료 서비스(요금은 해당 서비스 측에서 확인해주세요)를 요청할 때 필요한 진단 메모, 상담문, 테스트 환경 요청, 진단 의뢰서, 결과 해석, 개발자에게 수정 요청, 재진단까지 총 7단계로 구성했습니다. AI 자체에 스캔을 시키지 않고 문서 작성만 하도록 설계되었습니다.

AI Contents Bank는 재현 가능한(reproducible) AI 워크플로우를 Goal・Step・Block의 3개 계층으로 공유하는 플랫폼입니다. 이 Kit처럼 절차를 프롬프트나 링크별로 배치하고 있습니다.