공식 SKILL.md는 보안 감사를 정찰부터 보고서 작성까지 6단계로 나눕니다. 공식 보안 감사 스킬 문서에 근거하면, security-audit-skill은 코드 저장소의 초기 감사와 반복적인 취약점 후보 점검에 적합하지만 사람이 최종 검토해야 합니다.
증상 → 가장 빠른 해결책
설치는 됐는데 감사가 시작되지 않거나 결과가 믿기 어렵다면, 먼저 스킬 경로와 대상 저장소 권한을 확인한 뒤 격리 샌드박스에서 다시 실행해야 합니다. 고위험 저장소는 로컬 장비보다 원격 클라우드 맥 또는 독립 개발 환경에서 실행하고, 모든 결과를 구조화된 파일로 남기는 편이 안전합니다.
이 글은 보안 감사 절차를 통일하려는 기술 책임자, DevSecOps 담당자, 백엔드 개발자를 위한 안내서입니다. 단순한 코드 질문보다 저장소 전체의 입력 지점과 신뢰 경계를 추적해야 하는 작업에 적합합니다.
마지막 업데이트: 2026년 9월 21일. 설치 방식, 감사 단계, 출력 파일, 샌드박스 요구 사항은 공식 저장소를 기준으로 확인했습니다. 저장소가 변경되면 게시 전에 다시 검증해야 합니다.
security-audit-skill은 어떤 감사에 적합한가요?
security-audit-skill을 자동 침투 테스트 도구로 보면 안 됩니다. 이 도구의 역할은 코드 저장소를 읽고, 위험한 입력 흐름과 권한 경계를 찾고, 재현 가능한 후보를 정리하는 데 있습니다. 실제 서비스에 공격을 시도하거나 배포 승인에 자동으로 서명하는 도구는 아닙니다.
다음 세 가지 작업을 구분하면 도입 판단이 쉬워집니다.
- 전체 저장소 감사: 디렉터리 구조, 실행 경로, 인증 흐름, 데이터 처리 지점을 폭넓게 조사합니다.
- 대상 지정 감사: 파일 업로드, 웹훅, 인증 토큰, 외부 API 연결처럼 위험도가 높은 부분만 집중합니다.
- 보안 질의 응답: 특정 함수나 변경 사항에 대해 위험 가능성과 추가 확인 방법을 묻습니다.
전체 감사는 누락을 줄이는 대신 실행 시간이 길어지고 검토할 결과가 많아집니다. 반대로 지정 감사는 빠르지만 감사 범위를 문서로 남기지 않으면 중요한 디렉터리가 빠질 수 있습니다. 따라서 반복 실행이 목적이면 먼저 전체 범위를 기록하고, 이후 변경된 영역을 지정 감사로 좁히는 방식이 적절합니다.
설치 실패와 에이전트 인식 문제
설치 전 확인 항목
먼저 다음 조건을 확인합니다.
- Node.js를 설치합니다. 버전 조건은 저장소의 현재 설치 안내를 기준으로 판단하고, 필요한 파일은 Node.js 공식 다운로드 페이지에서 받습니다.
- AI Coding Agent가 읽을 수 있는 스킬 경로에 security-audit-skill을 추가합니다.
- 감사 대상 저장소를 에이전트의 작업 디렉터리 안에 둡니다.
- 에이전트가 소스 파일을 읽고 분석 결과를 별도 출력 디렉터리에 쓸 수 있는지 확인합니다.
- 병렬 하위 에이전트를 사용하는 경우, 각 프로세스가 같은 저장소를 동시에 변경하지 않도록 읽기 전용 작업과 검증 작업을 분리합니다.
- 빌드나 테스트가 필요한 저장소라면 실행 명령, 의존성, 네트워크 접근 범위를 사전에 정합니다.
구체적인 설치 구문은 저장소의 README와 현재 스킬 정의를 기준으로 입력해야 합니다. 예전 게시물의 skills add 예시를 그대로 복사하면 스킬 경로나 명령이 바뀐 경우 설치는 성공해도 에이전트가 기능을 호출하지 못할 수 있습니다.
security-audit-skill이 호출되지 않을 때
설치 성공과 실행 성공은 다릅니다. 다음 순서로 점검합니다.
- 스킬 디렉터리에 실제
SKILL.md가 존재하는지 확인합니다. - AI Coding Agent가 해당 디렉터리를 검색하는 설정인지 확인합니다.
- 프롬프트에 저장소 전체 보안 감사, 입력면 조사, 결과 파일 생성처럼 작업 범위를 명시합니다.
- 에이전트가 현재 디렉터리를 대상 저장소로 인식하는지 확인합니다.
- 도구 호출 권한이 읽기 전용으로 제한되어 있거나 필요한 실행 도구가 차단되어 있지 않은지 봅니다.
- 지원 여부가 공식적으로 확인되지 않은 에이전트에서는 동일한 작업을 작은 테스트 저장소로 먼저 실행합니다.
Claude Code는 공식 시작 문서를 참고해 작업 디렉터리와 도구 권한을 확인할 수 있습니다. Codex와 다른 에이전트의 호환 범위는 공식 저장소가 명시한 보장 범위와 현재 실측을 분리해서 판단해야 합니다. 커뮤니티에서 작동했다는 사례만으로 호환성을 확정하면 안 됩니다.
감사 범위와 오탐을 줄이는 기록 방식
정찰과 coverage ledger
첫 실행에서 바로 취약점 후보를 찾으라고 하면 에이전트가 이름이 익숙한 디렉터리만 집중할 수 있습니다. 먼저 정찰 단계에서 다음 내용을 기록해야 합니다.
- 애플리케이션의 주요 실행 경로
- 외부 요청과 파일 입력이 들어오는 지점
- 인증과 권한 확인 위치
- 데이터가 저장되거나 외부로 나가는 경계
- 빌드 스크립트와 배포 설정
- 테스트가 존재하지 않는 영역
- 아직 읽지 않은 디렉터리와 파일
이 목록이 coverage ledger입니다. 감사자는 후보의 개수보다 어느 범위를 읽었고 어느 범위를 읽지 않았는지를 먼저 확인해야 합니다.
예를 들어 탈취된 파일 이름을 처리하는 모듈을 조사한다고 가정해 보겠습니다. 정찰 결과 웹 요청 처리기와 백그라운드 작업 큐는 확인했지만, 관리자용 가져오기 명령은 아직 읽지 않았습니다. 이때 웹 처리기에서 문제 후보가 나오더라도 바로 확정하지 않고, 관리자 명령과 공통 파일 처리 함수까지 같은 입력이 전달되는지 확인해야 합니다. coverage ledger가 없으면 첫 발견 지점만 검증하고 다른 입력 경로를 놓칠 수 있습니다.
발견자와 검증자 분리
AI Coding Agent가 취약점 후보를 찾은 뒤 같은 판단을 스스로 확정하면 오탐이 늘어날 수 있습니다. 발견 단계와 검증 단계를 분리하면 다음과 같은 장점이 있습니다.
- 발견자는 넓은 범위를 읽고 후보와 근거를 기록합니다.
- 검증자는 후보가 실제 실행 경로에 연결되는지 확인합니다.
- 검증자는 입력 조건, 권한 조건, 설정 조건을 다시 확인합니다.
- 발견 결과를 검증자가 반박할 수 있어 자기 확증을 줄입니다.
보고서 상태는 최소한 다음처럼 구분해야 합니다.
- confirmed: 코드 흐름과 실행 조건을 근거로 문제가 확인된 상태입니다.
- needs_validation: 위험한 흐름은 보였지만 실행 조건이나 영향 범위를 더 확인해야 하는 상태입니다.
- rejected: 추가 검토 결과 문제가 성립하지 않거나 근거가 부족한 상태입니다.
공식 보고서 스키마를 기준으로 필드 이름과 상태 표현을 확인하십시오. 상태를 모두 “confirmed”로 바꾸면 보고서가 더 강해지는 것이 아니라 검토자의 신뢰를 잃게 됩니다.
샌드박스와 최소 권한 구성
실행 전 권한 분리
대상 저장소를 분석하는 것과 대상 저장소의 코드를 실행하는 것은 다른 위험입니다. 빌드, 테스트, 브라우저 자동화, 퍼징을 수행해야 한다면 운영체제 수준의 격리 환경에 넣어야 합니다.
다음 항목을 실행 전에 점검합니다.
- 네트워크는 기본 차단하고 필요한 주소만 일시적으로 허용합니다.
- 개인 키, 접근 토큰, 셸 이력, 클라우드 자격 증명을 환경에서 제거합니다.
- 소스 저장소와 결과 디렉터리를 분리합니다.
- 결과 디렉터리 외의 쓰기 권한을 차단합니다.
- 프로세스, 메모리, 디스크와 실행 시간을 제한합니다.
- 호스트 운영체제의 소켓과 장치 파일을 불필요하게 노출하지 않습니다.
- 브라우저 프로필과 실제 계정 세션을 공유하지 않습니다.
- 감사 로그와 에이전트 대화 기록의 보존 위치를 정합니다.
특히 “테스트를 실행해 취약점을 확인하라”는 지시는 위험할 수 있습니다. 실제 공격용 페이로드를 만들기보다, 비밀 정보가 없는 탈취 방지용 샘플 저장소에서 입력 흐름과 실패 조건을 검증하는 방식으로 제한해야 합니다.
로컬 실행과 원격 실행의 판단
로컬 장비는 작은 저장소를 빠르게 확인하기 좋습니다. 그러나 다음 조건이면 원격 환경이 유리합니다.
- 개발 장비에 비밀 정보와 업무 계정이 함께 있습니다.
- 저장소의 빌드 과정이 외부 도구나 브라우저를 실행합니다.
- 장시간 감사 중 세션이 끊기면 결과를 잃을 수 있습니다.
- 팀원이 동일한 로그와 findings 파일을 검토해야 합니다.
- 감사 대상이 외부 공개 프로젝트이거나 공급망 위험을 포함합니다.
Kvmzen의 맥 지원 안내를 먼저 확인한 뒤, 실제 장비와 원격 환경의 권한 분리 수준을 비교하십시오. 중요한 것은 맥이라는 이름 자체가 아니라 샌드박스, 세션 유지, 로그 보존과 접근 권한을 함께 관리할 수 있는가입니다.
findings.json에서 검토 가능한 보고서로
구조화된 결과는 사람이 읽는 보고서의 원본입니다. 각 결과에는 적어도 다음 관계가 유지되어야 합니다.
- 위치: 파일, 함수, 관련 코드 범위를 적습니다.
- 입력 경로: 외부 입력이 어디에서 들어오는지 설명합니다.
- 신뢰 경계: 검증 전 데이터가 어떤 권한이나 시스템으로 이동하는지 기록합니다.
- 증거: 코드 흐름, 설정, 테스트 결과를 연결합니다.
- 재현 절차: 실제 공격 코드를 제공하지 않고 안전한 샘플 입력과 관찰 결과를 씁니다.
- 영향 범위: 영향을 받는 조건과 영향을 받지 않는 조건을 구분합니다.
- 수정 제안: 검증, 권한 축소, 출력 인코딩, 설정 변경처럼 실행 가능한 조치를 적습니다.
- 상태: confirmed, needs_validation, rejected 중 현재 근거에 맞는 값을 사용합니다.
파일 형식이 유효한지 확인할 때는 공식 결과 검증 스크립트를 사용합니다. 공식 테스트 파일도 함께 살펴보면 예상되는 출력 구조와 검증 흐름을 파악할 수 있습니다.
Markdown 보고서는 다음 순서가 읽기 쉽습니다.
- 감사 범위와 제외 범위
- 환경과 권한
- 요약된 결과
- confirmed 결과
- needs_validation 결과
- rejected 결과와 판단 근거
- 영향 경계
- 수정 우선순위
- 사람이 추가로 확인해야 할 항목
이 구조를 사용하면 보안 문제, 단순한 강화 제안, 증명되지 않은 후보가 섞이지 않습니다. 자동화 결과를 배포 승인 문서로 바로 사용하지 말고, 담당자가 코드 위치와 증거를 다시 확인한 뒤 승인하도록 절차를 고정해야 합니다.
실행 방식별 선택표
| 선택지 | 적합한 작업 | 장점 | 주의할 점 | 선택 기준 |
|---|---|---|---|---|
| 로컬 개발 장비 | 작은 저장소의 초기 확인 | 설정이 빠르고 즉시 수정 가능 | 개인 키와 계정이 노출될 수 있음 | 코드 실행이 없고 저장소 위험도가 낮을 때 |
| 격리된 로컬 환경 | 반복 감사와 테스트 | 네트워크와 파일 권한을 직접 통제 가능 | 직접 샌드박스를 유지해야 함 | 팀 내부에서 환경을 관리할 역량이 있을 때 |
| 원격 클라우드 맥 | 장시간 감사, 병렬 작업, 세션 유지 | 업무 장비와 분리하고 로그를 모으기 쉬움 | 접근 정책과 결과 회수 절차를 먼저 정해야 함 | 로컬 장비에 비밀 정보가 있거나 고위험 저장소일 때 |
| 독립 개발 환경 | 여러 담당자가 같은 감사 결과를 검토할 때 | 권한과 작업 공간을 분리하기 쉬움 | 초기 구성과 비용을 검토해야 함 | 반복 가능한 DevSecOps 절차가 필요할 때 |
로컬 장비가 부족하거나 실행 도구를 분리하기 어렵다면 Kvmzen의 맥 미니 대여 안내에서 원격 환경의 접근 방식과 제공 조건을 확인할 수 있습니다. 다만 대여 환경을 선택해도 저장소 권한, 비밀 정보 제거, 로그 보존 정책은 사용자가 직접 검토해야 합니다.
현재 로컬 장비만으로 실행하면 개인 계정과 감사 대상 코드가 같은 환경에 남고, 장시간 작업에서 세션이 끊기며, 팀 단위 로그 검토를 별도로 구축해야 하는 단점이 있습니다. 반면 Kvmzen의 원격 맥 환경을 사용하면 개발 장비와 감사 작업을 분리하는 선택지가 생기고, 격리된 실행 공간을 기준으로 세션과 결과 파일을 관리하기가 수월합니다. 먼저 작은 저장소로 로컬 시험을 끝낸 뒤, 실제 코드가 샌드박스와 장시간 세션을 요구할 때 원격 환경으로 옮기는 순서가 합리적입니다.