Security Audit Skill 초보자용 튜토리얼: Claude Code를 AI 보안 감사자로 바꾸는 코드 스캔부터 취약점 보고서까지 완전 실전

점검 결과는 길게 나오는데, 실제 취약점인지 판단할 근거가 부족한가요?
Security Audit Skill로 Claude Code를 단계별 보안 감사 보조자로 설정할 수 있습니다. 다만 점검 범위와 승인된 도구를 제한하고, 중요한 발견은 사람이 검증해야 합니다.

이 글은 Claude Code의 반복적인 코드 검토 절차를 표준화하려는 개발자와 보안 엔지니어를 위한 안내입니다.
AI 에이전트 기반 감사 흐름을 평가하는 기술 책임자도 대상입니다.

Security Audit Skill이 맡을 일과 맡기면 안 될 일을 나눕니다

Security Audit Skill은 Claude Code가 따를 재사용 가능한 지침과 작업 흐름을 제공합니다. 코드 전체의 안전성을 보장하거나 전문 보안 감사를 대신하는 인증 도구는 아닙니다. 결과의 신뢰도는 저장소에 제공된 맥락, 허용된 도구, 담당자의 검토에 따라 달라집니다.

역할을 분리하면 기대치를 관리하기 쉽습니다.

• Skill: 점검 범위, 확인 순서, 근거 기록 형식과 보고서 구성을 안내합니다.
• Claude Code: 저장소의 코드와 제공된 설명을 검토하고, 설정된 권한 안에서 분석 도구를 사용할 수 있습니다.
• 분석 도구: 지원하는 언어와 규칙에 따라 후보 문제를 찾습니다. 도구가 다루지 않는 유형이나 경로까지 검사했다고 간주할 수는 없습니다.
• 사람: 코드 맥락과 데이터 흐름을 대조하고, 위험도와 수정 우선순위를 확정합니다.

정적 분석 경고는 검토할 후보입니다. 실제 취약점인지 확인하려면 코드 위치가 맞는지, 입력이 해당 처리 지점에 도달하는지, 방어 로직이 적용되는지를 확인해야 합니다. 약점 분류는 약점과 취약점의 차이를 설명하는 자료를 참고해 용어를 정리하되, 분류 이름만으로 영향도를 결정하지 않습니다.

점검 대상을 작게 정하고 필요한 맥락을 제공합니다

처음부터 저장소 전체를 대상으로 하면 불필요한 파일이 섞이고, 점검 목표가 모호해질 수 있습니다. 반대로 중요한 경로를 범위에서 빼면 발견을 놓칠 수 있습니다. 허가된 저장소, 대상 디렉터리, 언어, 우선 위험을 함께 적어야 합니다.

다음처럼 구체적으로 지정할 수 있습니다.

허가된 예시 저장소의 src/auth와 src/api만 검토합니다. 외부 입력에서 인증·권한 확인과 데이터베이스 처리까지 이어지는 흐름을 살핍니다. 비밀 값은 출력하거나 보고서에 복사하지 않습니다. 근거 코드와 확인 상태가 없는 항목은 확정 취약점으로 쓰지 않습니다.

이 안내가 “저장소의 보안 문제를 모두 찾으세요”로 줄어들면, 점검 대상과 성공 기준이 불명확해집니다. 프로젝트 구조 설명 없이 파일만 전달해도 인증 흐름이나 입력의 출처를 잘못 추정할 수 있습니다. 보안 검토에 관련된 구조와 실행 방법을 필요한 만큼 제공하고, 비밀 값이나 운영 환경의 실제 인증 정보를 넣지 않습니다.

위험의 이름을 정리할 때는 웹 애플리케이션 위험 분류를 참고 자료로 삼을 수 있습니다. 이 분류가 모든 프로젝트의 취약점을 빠짐없이 다룬다고 해석하지 말고, 실제 코드와 위협 모델을 함께 확인해야 합니다.

Skill 파일에 실행 순서와 증거 기준을 씁니다

공식 안내에서는 스킬을 SKILL.md 파일로 구성하고, 프로젝트 범위의 스킬은 .claude/skills/ 아래에 둘 수 있다고 설명합니다. 디렉터리와 호출 방식은 설정에 따라 달라질 수 있으므로 적용 시점의 공식 스킬 구성 안내를 확인합니다. 호출은 이름을 지정해 요청하거나, 환경에서 지원하는 스킬 호출 방식을 사용합니다.

다음은 구조를 보여 주는 예시입니다. 특정 도구의 지원 범위나 취약점 탐지 성능을 보장하는 설정은 아닙니다.

---
name: security-audit
description: 허가된 저장소의 코드 보안 검토를 보조합니다.
---

# 점검 범위
- 요청에 명시된 디렉터리만 검토합니다.
- 비밀 값이나 실제 사용자 데이터를 출력하지 않습니다.
- 범위가 불명확하면 스캔 전에 확인을 요청합니다.

# 점검 순서
- 프로젝트 구조와 입력 경로를 파악합니다.
- 인증, 권한 확인, 민감 정보 처리, 위험한 데이터 흐름을 검토합니다.
- 이미 승인된 분석 도구가 있으면 허가된 범위에서 실행합니다.
- 경고의 코드 위치와 주변 맥락을 확인합니다.
- 근거가 충분하지 않은 항목은 미확인 상태로 분리합니다.

# 결과 형식
- 파일과 코드 위치
- 관찰한 근거와 가능한 영향
- 확인에 필요한 조건
- 수정 권고
- 검증 상태

설정 파일이나 대화에서 어떤 작업을 허용할지는 별도로 관리합니다. 스킬 지침이 권한을 자동으로 부여한다고 생각해서는 안 됩니다. 파일 수정이나 도구 실행 권한은 공식 권한 규칙과 설정 파일 안내를 확인하고, 필요한 범위만 승인합니다. 보안상 주의할 동작과 데이터 취급은 공식 보안 안내도 함께 검토합니다.

허가된 저장소에서 스캔하고 결과를 대조합니다

설정을 만든 뒤에는 운영 코드가 아닌 허가된 저장소나 검토용 복제본으로 흐름을 먼저 확인합니다. 아래 순서는 실제 프로젝트에 적용할 때도 그대로 따라갈 수 있습니다.

• [ ] 저장소 소유자와 점검 권한을 확인하고, 허가된 작업 범위를 문서로 남깁니다.
• [ ] 점검할 디렉터리와 언어, 중점 위험, 제외 대상이 서로 모순되지 않는지 확인합니다.
• [ ] 민감 정보가 제거된 코드와 프로젝트 구조 설명을 준비합니다.
• [ ] 스킬을 호출해 점검 범위와 확인 순서를 먼저 요약하게 하고, 범위가 맞지 않으면 실행 전에 바로잡습니다.
• [ ] 이미 설치되고 승인된 분석 도구가 있다면 허가된 대상에만 실행한 뒤, 출력과 코드 근거를 서로 대조합니다.
• [ ] 후보마다 입력 출처, 처리 경로, 방어 로직, 영향 조건을 확인하고 확정·추가 확인·오탐 가능성으로 나눕니다.
• [ ] 수정한 항목은 같은 범위에서 다시 점검하고 보고서 상태를 갱신합니다.

Claude Code에 결과를 전달할 때는 “경고를 취약점으로 단정하지 말고, 파일 위치와 주변 코드에서 확인할 근거를 제시하라”고 요청합니다. 스캐너에 경고가 있어도 실제 실행 경로에서 도달할 수 없다면 그 사유를 기록합니다. 반대로 자동 도구가 경고하지 않았다는 이유만으로 안전하다고 결론 내리지 않습니다.

도구 출력에는 비밀 값이나 내부 경로가 포함될 수 있습니다. 보고서에 원문을 붙여 넣기 전에 민감 정보를 제거하고, 저장 위치와 열람 권한도 점검합니다.

자주 확인하는 설정과 검증 문제를 해결합니다

저장소 전체를 한 번에 점검해도 되나요?
허가가 명확하고 프로젝트 구조와 점검 목표가 충분히 제공된 경우에도, 처음에는 중요한 디렉터리부터 검토하는 편이 결과를 확인하기 쉽습니다. 제외 경로나 생성 파일이 섞이면 보고서가 불필요하게 커질 수 있습니다. 점검 범위를 넓힐 때마다 빠진 경로가 없는지 다시 확인하고, 범위 변경을 기록합니다.

심각도는 어떤 기준으로 정하나요?
경고의 표현만으로 정하지 않습니다. 접근 가능성, 필요한 전제, 영향받는 데이터나 기능, 기존 방어 조치를 함께 검토합니다. 안전한 소프트웨어 개발 프레임워크는 개발 과정에 보안 활동을 반영하는 참고 기준으로 활용할 수 있지만, 특정 발견의 심각도를 자동으로 결정하지는 않습니다.

후보 경고를 검토 가능한 취약점 보고서로 바꿉니다

스캔 기록과 최종 결론을 구별해야 합니다. 예를 들어 “사용자 입력이 위험한 처리 지점에 전달될 수 있음”은 확인이 필요한 관찰입니다. 코드에서 입력 경로와 방어 여부를 확인하기 전에는 이를 확정 취약점으로 표현하지 않습니다.

보고서에는 다음 항목을 넣습니다.

• 유형과 위치: 약점 유형을 적고, 저장소 안의 파일과 코드 위치를 명시합니다.
• 근거: 관련 코드와 도구 결과를 연결합니다. 민감 정보는 제거합니다.
• 영향과 전제: 어떤 조건에서 문제가 발생하고, 무엇이 영향을 받는지 구분합니다.
• 수정 권고: 변경할 동작이나 검증 방법을 제안합니다. 확인되지 않은 구현을 가정하지 않습니다.
• 상태: 확정, 추가 확인 필요, 오탐 가능성, 수정 후 재검증 필요처럼 근거에 맞는 상태를 표시합니다.

초기 기록: “입력 검증 부족. 위험 가능성 있음.”
검토 후 기록: “src/api의 입력 처리 경로에서 사용자 제공 값이 후속 처리로 전달되는 것을 확인했습니다. 권한 검사와 실제 영향 조건은 아직 검증하지 못했습니다. 추가 확인 전까지 확정 취약점으로 분류하지 않습니다. 입력 검증과 권한 경계를 검토하고, 수정 후 해당 경로를 다시 확인해야 합니다.”

코드 위치가 존재하지 않거나 재현 조건이 설명되지 않는 보고서는 담당자가 검토하기 어렵습니다. 반대로 근거가 있는 항목도 영향 범위가 불분명하면 심각도를 단정하지 말고, 어떤 확인이 남았는지 명시합니다.

사람의 재검토와 원격 실행 환경을 마지막으로 점검합니다

아래 항목 중 하나라도 충족되지 않으면 보고서를 확정하기 전에 멈추고 보완합니다.

• [ ] 저장소와 디렉터리가 명시된 허가 범위 안에 있습니다.
• [ ] 점검에 필요한 맥락만 제공했고 비밀 값과 실제 사용자 데이터는 제거했습니다.
• [ ] 핵심 발견의 코드 위치와 데이터 흐름을 사람이 확인했습니다.
• [ ] 분석 도구가 다루지 않는 언어, 경로, 위험이 무엇인지 기록했습니다.
• [ ] 확정 항목과 추정 또는 추가 확인 항목이 구분되어 있습니다.
• [ ] 수정 후 같은 근거를 기준으로 재점검하고 보고서 상태를 갱신했습니다.

인증·권한 우회, 민감 정보 노출, 중요한 데이터 처리처럼 영향이 큰 발견은 보안 담당자의 추가 평가가 필요합니다. 코드만으로 실행 조건이나 사용자 영향을 판단하기 어렵거나, 도구 결과와 실제 경로가 일치하지 않는 경우도 마찬가지입니다. 자동 점검 결과를 안전성 인증으로 간주하지 말고, 개발 과정의 검토 기록으로 사용합니다. 이런 경계를 두는 접근은 안전한 소프트웨어 개발 기준의 개발 과정 중심 관점과도 맞닿아 있습니다.

개발자 개인의 장비에서 모든 분석 도구와 프로젝트 환경을 유지하면 환경 차이와 작업 전환이 생길 수 있고, 팀원이 같은 조건으로 재현하기 어려울 수도 있습니다. 다만 지속적인 고부하 작업이나 물리 장치 연결이 필수라면 임대 환경이 적합하지 않을 수 있으며, 사내 보안 정책과 데이터 처리 요건도 먼저 확인해야 합니다. 원격 개발 환경의 이용 조건이나 자주 묻는 운영 관련 내용을 확인하려면 Zutcloud 도움말 센터를 참고할 수 있습니다. 허가된 저장소를 분리된 원격 개발 환경에서 검토할 필요가 있다면, Zutcloud의 맥 미니 대여 안내에서 현재 제공 조건을 확인한 뒤 이 글의 재검토 기준을 적용해 비교할 수 있습니다.