Claude Code security-guidance 플러그인 입문 — 실시간 취약점 탐지의 메커니즘 - Insights | Molayo

Anthropic은 2026년 5월 27일, Claude Code에 보안 취약성을 실시간으로 탐지 및 수정하는 공식 플러그인 「security-guidance」를 출시했습니다.

이 플러그인은 AI가 작성한 코드를 다른 AI가 독립적으로 리뷰하는 메커니즘으로, SQL 인젝션(SQL Injection)・XSS・커맨드 인젝션(Command Injection) 등 약 25종류의 취약점 패턴을 세션 내에서 탐지 및 수정합니다. 코드 리뷰나 CI/CD 스캔의 전 단계로서 기능하며, PR(Pull Request)에 도달하는 보안 문제의 양을 줄이는 것을 목적으로 합니다.

security-guidance 플러그인 설치 방법
3층 리뷰 메커니즘 (패턴 체크・턴 종료 시 리뷰・커밋 시 리뷰)
커스텀 규칙(Custom Rules) 설정 방법
다른 보안 도구와의 조합 방법
Claude Code CLI v2.1.144 이후
Python 3.8 이상 (PATH에 등록되어 있을 것)
Git 리포지토리(Repository) 내에서 작업 중일 것
/plugin install security-guidance@claude-plugins-official로 즉시 도입
파일 편집・턴 종료・커밋 시의 3단계로 AI가 자동 보안 리뷰
커스텀 규칙으로 자사의 위협 모델을 추가할 수 있으며, 팀 전체에 전개 가능

security-guidance는 Claude Code가 생성한 코드를 실시간으로 심사하고, 취약점이 있으면 동일 세션 내에서 수정하는 공식 플러그인입니다. 코드 리뷰나 CI/CD 스캔의 전 단계로서, AI가 코드를 작성하는 단계에서 보안 문제를 잡아내는 「첫 번째 방어선」 역할을 수행합니다.

플러그인은 Claude Code hooks 메커니즘을 활용하여 구현되어 있으며, Claude Code 라이프사이클의 각 포인트에 개입합니다.

중요한 설계 사상으로서, 코드를 작성한 Claude와 심사하는 Claude는 별개의 인스턴스입니다. 엔드 오브 턴(End-of-turn) 리뷰와 커밋 리뷰에서는 새로운 컨텍스트로 심사용 프롬프트(Prompt)를 부여한 독립된 모델 호출이 이루어지기 때문에, 자기 평가 편향(Self-evaluation bias)을 배제합니다.

이 플러그인은 모든 취약성을 보장하는 완전한 솔루션이 아니라, 다층 방어(Defense in depth)의 한 계층으로 위치한다는 점에 주의가 필요합니다.

Claude Code의 세션 내에서 다음을 실행합니다:

/plugin install security-guidance@claude-plugins-official

마켓플레이스(Marketplace)를 찾을 수 없는 경우, 먼저 등록합니다:

/plugin marketplace add anthropics/claude-plugins-official

설치 후, 현재 세션에 즉시 적용합니다:

/reload-plugins

스코프(Scope)는 user 스코프를 선택하면 동일한 머신의 모든 세션에서 자동으로 로드됩니다.

리포지토리에 .claude/settings.json을 추가함으로써, 해당 리포지토리를 클론(Clone)한 모든 사람에게 자동 적용됩니다:

{
"enabledPlugins": {
"security-guidance@claude-plugins-official": true
...

Claude Code on the Web(클라우드 세션)에서는 유저 스코프의 플러그인이 승계되지 않으므로, 프로젝트 설정에 기술이 필요합니다. 조직 전체에 전개할 경우에는 관리자가 매니지드 설정(Managed settings)으로 enabledPlugins를 설정합니다.

security-guidance는 다음 3단계로 코드를 심사합니다:

계층	타이밍	깊이	비용
패턴 체크	파일 편집 시	고속・결정론적	무료
...	`git commit` / `git push` 시	에이전트형 심층 리뷰	통상적인 사용료 (시간당 상한 20회)

Claude가 파일을 편집할 때마다 모델 호출 없이 고속 패턴 매칭(Pattern matching)을 실행합니다. 탐지하는 패턴 예시:

동적 코드 실행(Dynamic code execution): eval(), new Function, os.system, child_process.exec
안전하지 않은 역직렬화(Unsafe deserialization): pickle
DOM 인젝션 (DOM Injection): dangerouslySetInnerHTML, .innerHTML =, document.write
워크플로우 파일 (Workflow files): .github/workflows/ 하위의 편집 (리포지토리 권한에 영향을 미치므로 모니터링 대상)

경고는 한 세션 동안 동일 파일의 동일 패턴에 대해 한 번만 표시되므로, 대화가 넘쳐나는 일은 없습니다. 패턴 체크는 모델 호출을 수행하지 않으므로 비용이 발생하지 않습니다.

한 턴(사용자의 메시지 전송부터 Claude의 응답 완료까지)이 끝날 때마다, 해당 턴에서 변경된 파일의 git diff를 보안에 특화된 별도의 모델로 보냅니다. 리뷰는 백그라운드에서 실행되므로 Claude의 응답이 지연되지 않습니다.

패턴 매칭으로는 포착할 수 없는 다음과 같은 문제를 탐지합니다:

인가 우회 (Authorization Bypass)
안전하지 않은 직접 객체 참조 (IDOR)
인젝션 (Injection, SQL 인젝션 등)
서버 사이드 요청 위조 (SSRF)
취약한 암호화 (Weak Encryption)

한 턴에 최대 30개 파일을 대상으로, 연속해서 최대 3회까지 재프롬프트(Re-prompt)합니다.

Claude가 Bash 도구로 git commit이나 git push를 실행하면, 변경된 코드 주변(호출부, 새니타이저(Sanitizer), 관련 파일)까지 읽어들이는 심층 에이전트 리뷰(Deep Agent Review)가 가동됩니다. 컨텍스트를 넓게 읽음으로써, 고립된 상태로 보면 위험해 보이지만 실제로는 안전한 패턴을 오탐지하지 않습니다.

이 계층은 Claude가 자신의 Bash 도구로 실행한 커밋 및 푸시만을 대상으로 합니다. 사용자가 직접 터미널에서 실행한 커밋은 대상에서 제외됩니다.

.claude/claude-security-guidance.md 파일을 생성하여 자사의 위협 모델(Threat Model)이나 심사 체크리스트를 기술합니다:

# Security guidance for this repo
- `customer_id`나 `account_number`를 INFO 레벨 이상으로 로그에 출력하지 말 것
- `/admin` 하위의 모든 루트는 DB 액세스 전에 `require_role("admin")`을 호출할 것
...

이 파일은 모델 리뷰의 추가 컨텍스트로 읽힙니다. 가이던스는 가산적(Additive)이므로, 특정 취약점 클래스를 무시하는 기술을 하더라도 내장된 탐지 기능이 억제되지는 않습니다.

가이던스 파일의 스코프별 경로:

스코프	경로	용도
사용자 (User)	`~/.claude/claude-security-guidance.md`	해당 머신의 모든 프로젝트에 적용
프로젝트 (Project)	`.claude/claude-security-guidance.md`	리포지토리에 커밋
프로젝트 로컬 (Project Local)	`.claude/claude-security-guidance.local.md`	gitignore된 개인 설정

여러 파일이 존재하는 경우 연결됩니다 (합계 8KB 상한).

.claude/security-patterns.yaml을 통해 독자적인 패턴을 추가할 수 있습니다:

patterns:
- rule_name: internal_api_key
  substrings: ["sk_live_", "AKIA"]
...

필드	타입	설명
`rule_name`	string	경고에 표시될 식별자
`reminder`	string	Claude의 컨텍스트에 추가될 경고 문구 (최대 1KB)
`regex`	string	Python 정규 표현식
`substrings`	list	리터럴 문자열 리스트 (`regex` 또는 `substrings` 중 하나를 지정)
`paths`	list	적용 대상 glob 패턴 (옵션)
`exclude_paths`	list	제외할 glob 패턴 (옵션)

최대 50개의 커스텀 규칙을 설정할 수 있습니다. PyYAML을 사용할 수 없는 경우 security-patterns.json (동일 스키마)을 사용하십시오.

각 계층을 개별적으로 제어하는 환경 변수:

환경 변수	효과
`ENABLE_PATTERN_RULES=0`	패턴 체크 (Pattern Check) 비활성화
`ENABLE_STOP_REVIEW=0`	턴 종료 리뷰 (Turn-end Review) 비활성화
`ENABLE_COMMIT_REVIEW=0`	커밋/푸시 리뷰 (Commit/Push Review) 비활성화
`ENABLE_CODE_SECURITY_REVIEW=0`	모든 모델 리뷰 (Model Review) 비활성화
`SECURITY_GUIDANCE_DISABLE=1`	플러그인 전체 비활성화 (삭제 불필요)
`SECURITY_REVIEW_MODEL`	턴 종료 리뷰에서 사용할 모델 변경
`SG_AGENTIC_MODEL`	커밋 리뷰에서 사용할 모델 변경

일시적으로 비활성화하려면 세션 내에서:

/plugin disable security-guidance@claude-plugins-official

완전히 삭제하려면:

/plugin uninstall security-guidance@claude-plugins-official

프로젝트의 settings.json에서 활성화되어 있는 경우, 비활성화 설정은 settings.local.json에 작성되므로 팀원들에게 영향을 주지 않습니다.

공식 문서에 따르면, 리뷰가 표시되지 않는 주요 원인은 다음과 같습니다:

git 리포지토리 외부에서 작업 중: 턴 종료 및 커밋 리뷰는 git 상태가 필요하므로 스킵됨
Anthropic 인증 없음: 모델 리뷰가 스킵되고 패턴 체크 (Pattern Check)만 동작함
PyYAML 사용 불가: security-patterns.yaml이 무시됨 (security-patterns.json을 사용)

런타임 진단 로그는 ~/.claude/security/log.txt에 출력됩니다.

security-guidance는 다층 방어 (Defense in Depth)의 최전선에 위치합니다:

스테이지	도구	커버 범위
세션 내	security-guidance	Claude가 작성한 코드의 일반적인 취약점
온디맨드 (On-demand)	`/security-review` 명령	현재 브랜치에 대한 일회성 보안 패스
풀 리퀘스트 (PR) 시	Code Review (Team/Enterprise 플랜)	코드베이스 전체의 컨텍스트를 가진 멀티 에이전트 (Multi-agent) 리뷰
CI/CD	SAST · 의존성 스캐너	언어 특화 규칙 · 공급망 (Supply Chain) 체크

각 스테이지는 이전 단계에서 놓친 것을 보완합니다. security-guidance의 가치는 후속 단계로 도달하는 코드의 양을 줄이는 데 있습니다.

Claude Code security-guidance 플러그인의 핵심 포인트:

제로 컨피그 (Zero-config)로 즉시 도입: /plugin install 명령어 하나로 활성화, 추가 설정 불필요
3단계 자동 심사: 편집 시 (무료) · 턴 종료 시 · 커밋 시의 다층 체크
독립된 리뷰어: 코드를 작성한 Claude와 심사하는 Claude가 별도의 인스턴스
커스터마이징 가능: YAML 패턴과 Markdown 가이던스로 사내 고유 규칙 추가 가능
팀 배포 용이: .claude/settings.json을 커밋하는 것만으로 모두에게 적용

공식 문서에 따르면 모든 플랜에서 무료로 이용할 수 있습니다. AI 코딩 세션 내에서 보안 문제를 조기에 발견하여, PR 리뷰나 CI/CD 스캔의 부하를 줄이는 다층 방어의 최전선으로서 기능합니다.

Claude Code security-guidance 플러그인 입문 — 실시간 취약점 탐지의 메커니즘

요약

핵심 포인트

댓글