Claude Security 플러그인으로 취약점 스캔
기준일: 2026-07-26
공식 기준: Scan your codebase for vulnerabilities
개요
Claude Security 플러그인은 Claude Code 세션 안에서 멀티 에이전트 취약점 스캔을 돌립니다. 에이전트 팀이 아키텍처를 매핑하고, 위협 모델을 만들고, 취약점을 찾고, 모든 발견을 독립 검토한 뒤 보고서를 씁니다. 전체 저장소 또는 브랜치/PR/커밋 변경 집합만 스캔한 다음, 선택한 발견을 패치로 바꾸고 직접 검토·적용합니다.
플러그인은 세션 로컬에서 실행되며 스캔마다 플랜 사용량 한도에 포함됩니다. 저장소를 계속 모니터링하는 관리형 서비스가 필요하면 Enterprise 플랜 Claude Security 제품을 보세요. 플러그인은 GitLab·Bitbucket 호스팅, 인바운드 연결이 막힌 네트워크 등 관리형 제품이 닿기 어려운 코드에도 도달할 수 있습니다.
다른 Claude Code 보안 도구와 구분:
- security guidance plugin — Claude가 쓰는 코드를 세션 중 검토
/security-review— 브랜치 단일 패스- Code Review — PR 리뷰
계층 비교는 아래 “다른 보안 도구와의 관계” 표.
핵심 개념
| 항목 | 내용 |
|---|---|
| 최소 버전 | Claude Code v2.1.154+, 유료 플랜 (dynamic workflows 필요; Pro는 /config Dynamic workflows 행에서 활성화) |
| Python | python3 3.9.6+ on PATH (표준 라이브러리만 사용, 추가 설치 없음) |
| OS | Linux, macOS, Windows |
| Git | 변경 스캔·패치에 필요. 전체 스캔은 VCS 없이도 가능 |
| 명령 | /claude-security 메뉴: Scan codebase / 변경 스캔 / Suggest patches |
| 패치 적용 | 절대 자동 적용 없음. git apply 등 사용자가 적용 |
상세
설치
공식 Anthropic 마켓플레이스:
/plugin install claude-security@claude-plugins-official
marketplace not found면 먼저:
/plugin marketplace add anthropics/claude-plugins-official
세션 활성:
/reload-plugins
제거: /plugin 메뉴 또는 claude plugin uninstall claude-security.
스캔 및 수정 흐름
/claude-security→ Scan codebase- 저장소 읽은 뒤 전체 또는 집중 영역 선택 (파일 수·상대 비용 표시). “I don't know”면 크기 기반 기본값
- 확인 — 오래 걸릴 수 있고 토큰을 많이 쓰며 완료까지 Claude Code를 열어 둬야 함. 확인 전 실행 안 함
- 단계별 진행은
/workflows에서 상세 확인. 결과는 타임스탬프 디렉터리 /claude-security→ Suggest patches → 처리할 발견 선택 →patches/- 수락한 패치만 셸에서
git apply, PR당 하나 권장
메뉴 없이 /claude-security scan my branch 또는 “scan commit abc1234” 같은 자연어도 가능. auto mode가 에이전트 진행에 가장 잘 맞으며, 작업 시작 시 활성화 방법을 안내합니다.
변경만 스캔
베이스에 없는 커밋이 있는 브랜치면 메뉴가 해당 diff만 스캔을 제안합니다. 열린 PR 하나 또는 “scan commit abc1234”도 가능. 커밋된 변경만 스캔: 진행 중 편집은 commit/stash 하거나 워킹 트리를 읽는 전체 스캔.
변경 스캔은 git 저장소 필요. 미버전 디렉터리 전체 스캔은 가능. 열린 PR 찾기는 네트워크를 쓰는 유일한 단계이며, 세션이 GitHub CLI 실행 권한이 있고 gh 로그인된 경우만 제공됩니다.
대형 저장소 범위
한 번에 한 영역(API 레이어, 인증 코드 등)을 고르면 실행 규모가 그에 맞춰집니다. 보고서 coverage 섹션이 검사·미검사 범위를 명시합니다.
결과 읽기
타임스탬프 CLAUDE-SECURITY-<timestamp>/ 디렉터리:
CLAUDE-SECURITY-RESULTS.md— finding ID(예:F1), impact, exploit scenario, severity, confidence, recommendationCLAUDE-SECURITY-RESULTS.jsonl— 줄당 JSONCLAUDE-SECURITY-REVISION-<commit>.json— 스캔 커밋, effort, uncommitted 포함 여부, 검증 깊이. VCS 밖은UNVERSIONED
이 디렉터리가 스캔이 checkout에 만드는 유일한 변경이며 자체 .gitignore가 있어 실수로 git add되지 않습니다. 감사 추적용으로 이력에 남기려면 그 .gitignore만 지우고 커밋합니다.
발견은 독립 verifier 에이전트 분석 후에만 보고서에 올라 짧게 유지됩니다. 스캔은 비결정적입니다. 같은 코드 두 번 스캔해도 발견이 다를 수 있습니다. 정기 실행과 revision stamp로 코드·설정에 보고서를 귀속시키세요.
발견 수정 (Suggest patches)
메뉴 Suggest patches 또는 “fix finding F3”. 패치는 커밋된 코드 기준. 코드가 바뀐 발견은 건너뛰고 새 스캔을 제안합니다. 패치는 저장소 스크래치 복사본에서 작성되어 적용 전 원본 파일을 건드리지 않습니다.
전달 전 작성자와 독립된 에이전트가 프로젝트 테스트(있으면)를 돌리고 diff를 검토합니다. “해당 finding 해결 + 새 취약점 없음 + 그 외 동작 유지”를 보증할 때만 패치를 씁니다. 아니면 짧은 설명 노트만 반환합니다.
패치는 절대 자동 적용되지 않음
patches/F<n>.patch + 설명 노트. 적용 예:
git apply CLAUDE-SECURITY-<timestamp>/patches/F1.patch
테스트 없으면 노트에 표시됩니다. 패치마다 별도 PR로 리뷰·테스트하세요.
다른 보안 도구와의 관계
| 단계 | 도구 | 범위 |
|---|---|---|
| 세션 중 | Security guidance plugin | Claude가 쓰는 코드의 흔한 취약점 |
| 온디맨드 단일 패스 | /security-review |
현재 브랜치 1회 |
| 온디맨드 deep scan | Claude Security plugin | 저장소/diff 멀티 에이전트 + 독립 검토 + 패치 |
| PR | Code Review (Team/Enterprise) | 코드베이스 컨텍스트 멀티 에이전트 정확성·보안 |
| 관리형 | Claude Security 제품 (Enterprise) | 연결된 저장소 모니터링 |
| CI | 기존 SAST·의존성 스캐너 | 언어 규칙, 공급망, 정책 |
기존 소스 보안 도구를 대체하지 않습니다. 정적 분석·의존성 스캔·코드 리뷰와 병행하세요.
트러블슈팅
- Python 경고:
python33.9.6+ PATH. 없거나 오래되면 메뉴 경고. 설치·PATH 조정 후 새 세션. - Fable 5 safeguards 메시지: 사이버보안 분류기 때문에 일부 활동이 차단되고 Opus로 자동 다운그레이드될 수 있음. 예상 동작이며 스캔은 완료되는 것이 정상.
체크리스트
- v2.1.154+, 유료 플랜, Pro면 Dynamic workflows 활성
-
python33.9.6+ 확인 -
claude-security@claude-plugins-official설치 후/reload-plugins - 범위(전체/영역/diff)를 확인하고 실행 확인했다
- 보고서를 읽고 Suggest patches 후
git apply로 선택 적용했다 - 패치 자동 적용을 기대하지 않는다
다음 단계
기준일
- 문서 작성·동기화 기준일: 2026-07-26
- 원문: https://code.claude.com/docs/en/claude-security