코딩 에이전트를 활용한 소프트웨어 개발이 일상화되면서, 소스 코드의 보안 취약점을 자동으로 점검하려는 시도가 활발해지고 있습니다. Skills CLI는 개발자가 사용하는 코딩 에이전트에 특정 작업 능력을 주입해 주는 도구이며, cloudflare/security-audit-skill은 코드베이스의 아키텍처와 신뢰 경계를 분석해 잠재적 보안 취약점을 체계적으로 발굴하는 감사 전용 스킬입니다.
두 도구의 관계는 단순합니다. Skills CLI를 매개체로 보안 감사 스킬을 에이전트 환경에 등록하면, 에이전트는 사전에 정의된 보안 감사 규칙과 6단계 파이프라인에 따라 자율적이면서도 통제된 방식으로 코드베이스 조사를 수행합니다. 이를 통해 단순한 텍스트 질문을 넘어 프로젝트 구조를 이해하는 체계적인 보안 검토가 가능해집니다.
이 글에서는 Skills CLI를 이용해 cloudflare/security-audit-skill을 설치하는 공식 명령부터, 대상 코드베이스에서 감사를 실행하는 올바른 프롬프트 구문, 그리고 감사 완료 후 생성되는 산출물을 공식 Node.js 스크립트로 정합성 검증하는 전 과정을 공식 문서에 근거하여 명확하게 안내합니다.
보안 감사 스킬과 코딩 에이전트의 역할 이해하기
보안 감사를 시작하기에 앞서 에이전트가 동작하는 기본 원리를 이해하는 것이 중요합니다. cloudflare/security-audit-skill은 Cloudflare의 자체 취약점 발굴 시스템에서 파생된 단일 저장소 기반의 스킬로, 고립된 다중 에이전트를 조율해 엄격한 파이프라인을 실행합니다.
이 스킬의 핵심은 정찰(Reconnaissance), 커버리지 기반 사냥(Coverage-led hunting), 후보 검증(Candidate validation), 구조화 출력(Structured output), 독립 기록 검증(Independent record verification), 그리고 타깃 중립 보고(Target-neutral reporting)의 6단계 파이프라인으로 구성되어 있다는 점입니다. 에이전트가 단독으로 취약점을 추정해 확정 짓지 않고, 모든 취약점 후보는 최초 발견 에이전트와 분리된 별도의 검증 에이전트(fresh verifier)에게 전달되어 소스 기반의 반증(Refutation) 과정을 거치도록 설계되어 있습니다.
또한 이 스킬은 기본적으로 안내(guidance) 모드로 로드됩니다. 단순히 스킬을 등록했다고 해서 전체 감사 파일이 생성되거나 임의의 디렉터리가 만들어지지 않으며, 사용자가 명시적으로 감사를 요청할 때만 전체 파이프라인과 산출물 작성 과정이 활성화됩니다.
Skills CLI를 통한 cloudflare/security-audit-skill 설치 방법
스킬 설치는 npm 패키지 실행 도구인 npx를 활용한 Skills CLI 명령어로 간단히 완료할 수 있습니다. 설치 위치에 따라 특정 프로젝트 환경에만 종속시킬 수도 있고, 전체 사용자 환경에 글로벌로 구성할 수도 있습니다.
# 현재 프로젝트 환경에 스킬 설치
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- 터미널을 열고 코딩 에이전트가 연동된 작업 디렉터리로 이동합니다.
- 위의 코드 블록 중 사용 환경에 맞는 명령어를 입력해 실행합니다. 단일 프로젝트에서만 사용할 경우 첫 번째 명령을, 여러 프로젝트에서 공통으로 호출하려면
--global옵션이 포함된 두 번째 명령을 사용합니다. - 에이전트 선택이나 비대화형(non-interactive) 옵션 설정이 필요한 경우
npx skills --help명령어를 입력하여 추가 파라미터를 점검합니다.
정상적으로 실행되면 Skills CLI가 저장소 메타데이터를 다운로드하고 security-audit 스킬을 에이전트의 도구 목록에 등록합니다. 만약 설치 과정에서 네트워크 오류나 권한 문제가 발생한다면 터미널의 오류 로그를 확인하고 Node.js 실행 환경 및 npm 네트워크 접근 권한을 점검해야 합니다.
대상 코드베이스에서 보안 감사 트리거하기
스킬 등록이 완료되었다면 코딩 에이전트에게 감사를 시작하도록 지시할 수 있습니다. 감사를 수행할 때 에이전트는 점검 대상이 되는 코드베이스 디렉터리 내부에서 실행되거나, 해당 소스 경로를 명확히 가리키고 있어야 합니다.
# 코드베이스 전체 감사 지시
security audit this codebase
# 특정 소스 디렉터리 대상 취약점 탐색
find security vulnerabilities in ./src
# 결과 산출물 출력 디렉터리를 지정하여 감사 수행
do a security review, output to ~/audits/my-project감사 지시문이 입력되면 스킬의 트리거 조건이 일치하면서 본격적인 6단계 감사 작업이 진행됩니다.
- 정찰 및 원장 작성: 대상 코드의 신뢰 경계와 입력 지점을 파악하여
architecture.md와 커버리지 원장인coverage-ledger.json을 구성합니다. - 산출물 기록: 검증을 통과한 데이터는 구조화된 형식인
findings.json에 기록되며, 최종적으로REPORT.md,FINDINGS-DETAIL.md,NEEDS-VALIDATION.md등의 보고서가 도출됩니다.
에이전트가 전체 감사를 시작하지 않고 단순 조언만 출력한다면, 입력 구문이 일반 질문 형태로 해석되었을 가능성이 높습니다. 이 경우 전체 감사 모드를 명시적으로 트리거하기 위해 위 예시처럼 security audit 또는 security review 키워드를 포함하여 명확히 지시해야 합니다.
공식 Node.js 검증 스크립트로 감사 산출물 확인하기
감사 파이프라인이 종료된 후 생성된 산출물은 스키마와 원장 정합성이 유지되었는지 공식 검증 스크립트를 통해 검사해야 합니다. cloudflare/security-audit-skill 저장소 내부에는 외부 의존성 없이 실행 가능한 전용 Node.js 검증 스크립트가 포함되어 있습니다.
# findings.json 구조 및 스키마 검증
node <skill-dir>/validate-findings.cjs <output-dir>/findings.json
# coverage-ledger.json 원장 정합성 검증
node <skill-dir>/validate-coverage-ledger.cjs <output-dir>/coverage-ledger.json- 감사 산출물이 저장된 디렉터리 경로(
<output-dir>)와 스킬이 위치한 경로(<skill-dir>)를 확인합니다. - 터미널에서
validate-findings.cjs를 실행하여findings.json이 공식report-schema.json규격에 맞게 작성되었는지 점검합니다. - 이어서
validate-coverage-ledger.cjs를 실행하여coverage-ledger.json의 추적 원장이 단계별 상태 전이 규칙을 준수하는지 확인합니다.
검증 스크립트를 실행할 때 염두에 두어야 할 기술 사양과 판정 기준은 다음과 같습니다.
- 세 가지 판정 상태: 산출물에 기록되는 검증 판정은 확정(
confirmed), 검증필요(needs_validation), 기각(rejected)의 세 가지로 명확히 분리됩니다.confirmed는 완결된 소스 추적과 확인된 관측 결과를 포함하며,needs_validation은 미해결된 사실이 남아 있는 상태로 심각도(severity)가 부여되지 않습니다.rejected는 반증 과정을 통해 기각된 후보를 기록합니다. - 타깃 코드 격리 원칙: 타깃 코드를 직접 실행하여 검증하는 작업은 외부 네트워크가 차단되고 읽기 전용 타깃 및 임시 환경(scratch)만 허용되는 승인된 OS 수준 샌드박스 내부에서만 수행되어야 합니다. 격리 제어가 불가한 경우 실행을 중단하고 미해결 상태로 보존해야 합니다.
- 결과의 해석과 누적 감사: 검증 스크립트 통과 성공은 출력 포맷과 커버리지 원장의 구조적 정합성을 입증하는 것이며, 코드베이스에 취약점이 완전히 없다는 절대적 무결성을 보장하지는 않습니다. 단일 실행으로는 전체 커버리지를 모두 다루기 어려우므로, 이전 원장과 findings 기록을 유지한 상태에서 추가 감사를 실행하여 누적 방식으로 탐색 범위를 넓히는 것이 권장됩니다.
