Anthropic의 Claude를 활용한 코드 보안 검토 GitHub Action

Claude를 사용하여 코드 변경 사항을 분석하고 보안 취약점을 점검하는 AI 기반 보안 검토 GitHub Action입니다. 이 액션은 Anthropic의 Claude Code 도구를 이용해 풀 리퀘스트(PR)에 대한 지능적이고 문맥을 이해하는 보안 분석을 제공합니다. 자세한 내용은 블로그 게시물을 참고하세요.

AI 기반 분석: Claude의 고급 추론 능력을 활용하여 깊은 의미론적 이해를 바탕으로 보안 취약점을 감지합니다.
Diff 기반 스캐닝: PR의 경우 변경된 파일만 분석합니다.
PR 댓글 작성: 발견된 보안 문제에 대해 PR에 자동으로 댓글을 작성합니다.
문맥 이해: 단순한 패턴 매칭을 넘어 코드 의미론(semantics)을 이해합니다.
언어 독립적: 모든 프로그래밍 언어에서 작동합니다.
오탐지 필터링: 노이즈를 줄이고 실제 취약점에 집중하기 위한 고급 필터링 기능을 제공합니다.

이를 리포지토리의 .github/workflows/security.yml에 추가하세요.

:

name: Security Review
permissions:
pull-requests: write # PR 댓글 작성을 위해 필요
...

주의: 이 액션은 프롬프트 주입 공격(prompt injection attacks)에 대해 강화되지 않았으므로, 신뢰할 수 있는 PR을 검토하는 용도로만 사용해야 합니다. 워크플로우가 메인테이너가 PR을 검토한 후에만 실행되도록 리포지토리를 구성하려면 '모든 외부 기여자 승인 요구(Require approval for all external contributors)' 옵션을 사용하는 것을 권장합니다.

Input	설명	기본값	필수 여부
claude-api-key	보안 분석을 위한 Anthropic Claude API 키. 참고: 이 API 키는 Claude API와 Claude Code 사용 모두에 활성화되어야 합니다.	없음	예
comment-pr	발견된 내용을 PR에 댓글로 남길지 여부	true	아니오
upload-results	결과를 아티팩트로 업로드할지 여부	true	아니오
exclude-directories	스캔에서 제외할 디렉터리의 쉼표 구분 목록	없음	아니오
claude-model	사용할 Claude 모델 이름. 기본값은 Opus 4.1입니다.	claude-opus-4-1-20250805	아니오
claudecode-timeout	분 단위로 한 ClaudeCode 분석 시간 초과 설정	20	아니오
run-every-commit	모든 커밋마다 ClaudeCode 실행 (캐시 확인 건너뜀). 경고: 커밋이 많은 PR의 경우 오탐(false positive)을 증가시킬 수 있습니다.	false	아니오
false-positive-filtering-instructions	사용자 지정 오탐 필터링 지침 텍스트 파일 경로	없음	아니오
custom-security-scan-instructions	감사 프롬프트에 추가할 사용자 지정 보안 스캔 지침 텍스트 파일 경로	없음	아니오

Output	설명
findings-count	발견된 보안 문제의 총 개수
results-file	결과 JSON 파일 경로

claudecode/
├── github_action_audit.py # GitHub Actions용 메인 감사 스크립트
├── prompts.py # 보안 감사 프롬프트 템플릿
...

PR 분석: 풀 리퀘스트(pull request)가 열릴 때, Claude는 변경된 내용을 분석하여 무엇이 바뀌었는지 이해합니다.문맥적 검토 (Contextual Review): Claude는 코드 변경 사항을 문맥 속에서 검토하며, 목적과 잠재적인 보안 영향을 파악합니다.문제점 도출 (Finding Generation): 상세한 설명, 심각도 등급, 그리고 해결 지침과 함께 보안 문제가 식별됩니다.오탐 필터링 (False Positive Filtering): 고급 필터링을 통해 영향도가 낮거나 오탐 가능성이 높은 발견 사항을 제거하여 노이즈를 줄입니다.PR 댓글: 발견된 내용은 특정 코드 라인에 검토 댓글로 게시됩니다.

주입 공격 (Injection Attacks): SQL 주입(SQL injection), 명령어 주입(command injection), LDAP 주입(LDAP injection), XPath 주입(XPath injection), NoSQL 주입(NoSQL injection), XXE**
인증 및 권한 부여 (Authentication & Authorization): 인증 오류(Broken authentication), 권한 상승(privilege escalation), 안전하지 않은 직접 객체 참조(insecure direct object references), 우회 로직(bypass logic), 세션 결함(session flaws)**
데이터 노출 (Data Exposure): 하드코딩된 비밀 정보(Hardcoded secrets), 민감 데이터 로깅(sensitive data logging), 정보 공개(information disclosure), PII 처리 위반(PII handling violations)**
암호화 문제 (Cryptographic Issues): 취약한 알고리즘(Weak algorithms), 부적절한 키 관리(improper key management), 안전하지 않은 난수 생성(insecure random number generation)**
입력 유효성 검사 (Input Validation): 누락된 유효성 검사(Missing validation), 부적절한 정제(improper sanitization), 버퍼 오버플로우(buffer overflows)**
비즈니스 로직 결함 (Business Logic Flaws): 경쟁 조건(Race conditions), 시간 확인-시간 사용 문제(time-of-check-time-of-use, TOCTOU) 문제**
설정 보안 (Configuration Security): 안전하지 않은 기본값(Insecure defaults), 누락된 보안 헤더(missing security headers), 허용적인 CORS(permissive CORS)**
공급망 (Supply Chain): 취약한 의존성(Vulnerable dependencies), 오타 스쿼팅 위험(typosquatting risks)**
코드 실행 (Code Execution): 역직렬화(deserialization)를 통한 RCE, pickle 주입(pickle injection), eval 주입(eval injection)**
크로스 사이트 스크립팅 (Cross-Site Scripting, XSS): 반사형(Reflected), 저장형(stored), DOM 기반 XSS**

이 도구는 다양한 저영향 및 오탐 가능성이 높은 발견 사항을 자동으로 제외하여 고영향 취약점에 집중합니다:

• 서비스 거부(Denial of Service) 취약점
• 속도 제한 우려(Rate limiting concerns)
• 메모리/CPU 고갈 문제(Memory/CPU exhaustion issues)
• 입증된 영향이 없는 일반적인 입력 유효성 검사
• 오픈 리디렉트 취약점(Open redirect vulnerabilities)

오탐 필터링은 프로젝트의 보안 목표에 따라 필요에 맞게 조정할 수도 있습니다.

맥락 이해 (Contextual Understanding): 단순히 패턴이 아닌 코드 의미론 및 의도를 이해합니다
낮은 오탐률 (Lower False Positives): AI 기반 분석을 통해 코드가 실제로 취약한지 여부를 파악하여 노이즈를 줄입니다
상세 설명 (Detailed Explanations): 무엇이 왜 취약점인지, 그리고 어떻게 수정해야 하는지에 대한 명확한 설명을 제공합니다
적응형 학습 (Adaptive Learning): 조직별 특정 보안 요구 사항으로 맞춤 설정할 수 있습니다.

위의 빠른 시작 가이드(Quick Start guide)를 따르십시오. 이 액션은 모든 의존성을 자동으로 처리합니다.

특정 PR에 대해 로컬에서 보안 스캐너를 실행하려면 평가 프레임워크 문서(evaluation framework documentation)를 참조하십시오.

기본적으로, Claude Code는 /security-review를 배포합니다.

슬래시 명령어(/slash command)가 GitHub Action 워크플로우와 동일한 보안 분석 기능을 제공하지만, Claude Code 개발 환경에 직접 통합됩니다. 이를 사용하려면 단순히 /security-review를 실행하여 모든 보류 중인 변경 사항에 대한 포괄적인 보안 검토를 수행하십시오.

기본 /security-review 명령어는 대부분의 경우 잘 작동하도록 설계되었지만, 특정 보안 요구 사항에 따라 사용자 정의할 수도 있습니다. 그렇게 하려면:

• 이 저장소에서 security-review.md 파일을 프로젝트의 .claude/commands/ 폴더로 복사하십시오.
• security-review.md를 편집하여 보안 분석을 사용자 정의하십시오. 예를 들어, 오탐(false positive) 필터링 지침에 조직별 추가 지침을 추가할 수 있습니다.

또한 커스텀 스캐닝 및 오탐 필터링 지침을 구성하는 것도 가능하며, 자세한 내용은 docs/ 폴더를 참조하십시오.

기능 검증을 위해 테스트 스위트를 실행하십시오:

cd claude-code-security-review
# 모든 테스트 실행
pytest claudecode -v

문제나 질문이 있는 경우:

• 이 저장소에 이슈를 생성하십시오.
• 디버깅 정보는 GitHub Actions 로그를 확인하십시오.

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하십시오.