Claude Code 보안 가이던스 플러그인 완벽 정리 — 설치부터 실전 활용까지

이 도구가 뭔가요?

Claude Code 보안 가이던스 플러그인(Security Guidance plugin)은 Claude가 작성한 코드를 작업 중에 스스로 보안 검토하고, 발견한 취약점을 같은 세션 안에서 바로 고치는 플러그인입니다. injection, 안전하지 않은 역직렬화(deserialization), 위험한 DOM API 같은 문제를 코드가 PR(Pull Request)에 도달하기 전에 잡아내, 사람 리뷰어에게 넘어가는 보안 검토 부담을 앞단에서 줄여줍니다.

핵심은 "설치하면 알아서 돈다"는 점입니다. 따로 호출할 명령어도, 기억해야 할 슬래시 커맨드도 없습니다. 설치 후에는 백그라운드에서 자동으로 작동하며, PR 단계에서 도는 Code Review의 세션 내 짝꿍 역할을 합니다.

핵심 기능

이 플러그인은 Claude의 작업을 세 지점에서, 각기 다른 깊이로 검토합니다.

1. 파일 편집마다(무비용 패턴 검사): Claude가 파일에 쓸 때마다 알려진 위험 패턴을 스캔합니다. 모델 호출 없는 단순 문자열 매칭이라 사용 비용이 들지 않습니다. eval(, new Function, os.system 같은 동적 코드 실행, pickle 같은 역직렬화, .innerHTML =이나 dangerouslySetInnerHTML 같은 DOM 주입, .github/workflows/ 아래의 워크플로 파일 수정 등을 잡습니다.
2. 턴 종료마다(diff 보안 검토): 한 번의 응답이 끝날 때, 그 턴 동안 작업 트리에서 바뀐 전부를 git diff로 계산해 별도의 Claude에게 보안 관점으로 검토를 맡깁니다. 인가 우회(authorization bypass), 안전하지 않은 직접 객체 참조(IDOR), injection, 서버 측 요청 위조(SSRF), 약한 암호화처럼 단순 문자열 매칭으로는 못 잡는 문제를 찾아냅니다. 검토는 백그라운드에서 돌아 Claude의 답변을 늦추지 않고, 문제가 나오면 그 결과를 다시 Claude에게 던져 후속으로 수정하게 합니다.
3. 커밋·푸시마다(에이전트형 심층 검토): Claude가 Bash 도구로 git commit이나 git push를 실행하면, 더 깊은 에이전트형 검토가 백그라운드에서 돕니다. 이 검토는 호출부, 새니타이저(sanitizer), 관련 파일까지 주변 코드를 읽어 발견 사항이 진짜인지 판단한 뒤 보고합니다. 그래서 떼어놓고 보면 위험해 보이지만 실제 코드베이스에서는 안전한 패턴의 오탐(false positive)을 낮춰줍니다.

여기서 중요한 설계가 하나 있습니다. 코드를 쓴 그 Claude에게 자기 채점을 시키지 않는다는 점입니다. 턴 종료·커밋 검토는 새로운 컨텍스트와 보안 전용 프롬프트를 가진 별도의 Claude 호출로 돕니다. 검토자는 원래 접근 방식에 미련이 없고, 오직 문제를 찾으라는 지시만 받은 상태에서 diff부터 출발합니다.

시작하기 — 설치 방법

먼저 준비물부터 확인합니다.

• Claude Code CLI 2.1.144 버전 이상
• PATH에 등록된 Python 3.8 이상 (플러그인이 python3 → python → py -3 순으로 시도)
• 작업 디렉터리가 git 저장소일 것 (턴 종료·커밋 검토는 git 상태를 diff하므로, 저장소가 아니면 조용히 건너뜀. 파일 편집 패턴 검사는 어디서든 작동)

설치는 공식 Anthropic 마켓플레이스에서 합니다. Claude Code 세션 안에서 아래를 실행하세요.

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

설치 중 스코프를 물으면 user 스코프를 고르면 이 머신에서 새로 시작하는 모든 로컬 세션에 적용됩니다. 마켓플레이스를 못 찾는다고 나오면 /plugin marketplace add anthropics/claude-plugins-official를 먼저 실행한 뒤 재시도합니다. 설치 후에는 재시작 없이 현재 세션에 적용하는 /reload-plugins로 활성화합니다.

처음 실행할 때 플러그인이 ~/.claude/security/ 아래에 가상환경을 만들고 Claude Agent SDK를 설치합니다(pip와 네트워크 필요). 이 설치가 실패하면 커밋 검토는 에이전트형 대신 단발성(single-shot) 검토로 대체됩니다.

이렇게 써보세요 — 실전 활용법

활용 1: 팀·클라우드 세션에 한 번에 켜기

user 스코프 플러그인은 Claude Code 웹 세션으로는 따라가지 않습니다. 웹 세션이 Anthropic 인프라에서 돌기 때문입니다. 저장소를 클론하는 모든 사람에게 켜거나 웹에서도 쓰려면, 프로젝트의 체크인되는 설정에 선언하세요.

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

관리자라면 관리형 설정(managed settings)의 enabledPlugins로 조직 전체에 일괄 적용할 수 있습니다. 팀 단위로 보안 검토의 바닥을 깔아두는 가장 깔끔한 방법입니다.

활용 2: 우리 저장소만의 보안 규칙 추가하기

내장 검사 위에 우리 팀의 위협 모델을 얹을 수 있습니다. 프로젝트에 .claude/claude-security-guidance.md를 만들고 검토 체크리스트를 평문으로 적으면, 모델 기반 검토가 내장 체크리스트와 함께 이 파일을 추가 컨텍스트로 읽습니다.

# Security guidance for this repo

- customer_id, account_number를 INFO 레벨 이상으로 로깅하지 말 것.
- /admin 아래 모든 라우트는 DB 읽기 전에 require_role("admin")을 호출할 것.
- 토큰 비교는 ===가 아니라 crypto.timingSafeEqual을 쓸 것.

단, 이건 검토자를 위한 가이드이지 강제 가드레일이 아닙니다. 위반을 발견 사항으로 띄워주지만 쓰기를 막아주지는 않습니다. 또 "이 취약점 클래스는 무시하라"는 규칙으로 내장 검사를 끌 수는 없습니다(추가만 가능). 하드한 차단이 필요하면 편집을 막는 hook이나 CI 검사와 함께 쓰세요.

활용 3: 결정론적 패턴 룰로 비밀키·멀티테넌트 누수 막기

무비용 패턴 검사 층에는 정규식이나 부분 문자열 룰을 직접 추가할 수 있습니다. .claude/security-patterns.yaml을 만들면 내장 패턴과 나란히 결정론적 문자열 매칭으로 돕니다.

patterns:
  - rule_name: internal_api_key
    substrings: ["sk_live_", "AKIA"]
    reminder: "하드코딩된 API 키 접두사. 시크릿 매니저에서 자격증명을 불러오세요."
  - rule_name: tenant_unfiltered_query
    regex: "\\.objects\\.all\\(\\)"
    paths: ["**/src/tenants/**"]
    reminder: "멀티테넌트 코드는 org_id로 필터링해야 합니다."

paths 글롭은 전체 파일 경로에 매칭되므로 프로젝트 상대 패턴은 **/를 앞에 붙이세요. YAML은 PyYAML이 임포트 가능해야 동작하는데, 플러그인이 PyYAML을 깔아주지는 않습니다. 환경이 불확실하면 어떤 Python에서도 도는 security-patterns.json을 쓰면 됩니다. 룰은 최대 50개까지 로드됩니다.

활용 4: 레이어별로 켜고 끄기

세 층을 통째로 쓸 필요는 없습니다. 환경변수로 각 층을 개별 제어합니다.

예를 들어 비용이 걱정되면 무비용 패턴 검사만 남기고 모델 검토 두 층을 끄는 식으로 운영할 수 있습니다.

비용은 얼마나 드나요?

파일 편집 패턴 검사는 모델 호출이 없어 비용이 0입니다. 턴 종료·커밋 검토는 일반 Claude 요청과 똑같이 사용량(usage)에 잡힙니다. 대략 파일을 바꾼 턴마다 검토 1회, 커밋마다 더 깊은 검토 1회가 든다고 보면 됩니다. 커밋 검토는 에이전트형이라 커밋당 모델 턴이 여러 번 돌 수 있고, 롤링 1시간당 최대 20회로 제한됩니다. 턴 종료 검토는 턴당 최대 3회 연속까지만 발동한 뒤 사용자에게 제어를 돌려줍니다.

두 모델 기반 검토는 기본으로 Claude Opus 4.7을 씁니다. SECURITY_REVIEW_MODEL로 턴 종료 검토 모델을, SG_AGENTIC_MODEL로 커밋 검토 모델을 바꿀 수 있습니다. 플러그인은 모든 요금제에서 사용할 수 있습니다.

다른 보안 도구와 어떻게 맞물리나요?

이 플러그인은 한 겹의 방어선일 뿐, 그 자체로 완결된 보안 솔루션이 아닙니다. 어느 층도 쓰기나 커밋을 막지 않고, 검토 모델도 문제를 놓칠 수 있습니다. 전형적인 다단계 구성은 이렇습니다.

플러그인의 가치는 뒤 단계로 넘어가는 양을 줄이는 것이지, 뒤 단계를 없애는 게 아닙니다. 가장 이른 시점(코드가 아직 에디터에 있을 때)에 잡는다는 게 강점입니다.

자주 묻는 질문

Claude Code 보안 가이던스 플러그인은 무료인가요?

플러그인 자체는 모든 요금제에서 쓸 수 있습니다. 다만 모델 기반 검토(턴 종료·커밋)는 일반 Claude 요청처럼 사용량에 잡힙니다. 비용 없이 쓰려면 모델 검토 층을 끄고 무비용 패턴 검사만 남기면 됩니다.

플러그인을 켰는데 검토가 안 보일 때는요?

먼저 ~/.claude/security/log.txt의 진단 로그를 확인하세요. 메시지 없이 검토 층이 건너뛰는 흔한 이유는 ① 디렉터리가 git 저장소가 아닐 때(턴 종료·커밋 검토 스킵), ② 세션에 Anthropic 인증이 없을 때(모델 검토 스킵, 패턴 검사만 작동), ③ security-patterns.yaml은 있는데 PyYAML이 임포트 안 될 때(파일 무시 — .json을 쓰세요)입니다.

/security-review 명령과 뭐가 다른가요?

/security-review는 요청할 때 현재 브랜치를 한 번 점검하는 온디맨드 명령입니다. 이 플러그인은 호출 없이 편집·턴 종료·커밋 시점에 자동으로 돌며, 발견 사항을 같은 세션에서 바로 수정하게 합니다. 즉 더 이른 시점에서 상시 작동한다는 점이 다릅니다.

내가 직접 친 git commit도 검토되나요?

아니요. 커밋·푸시 검토는 Claude가 Bash 도구로 실행한 커밋·푸시에만 발동합니다. 본인 셸에서 직접 한 커밋이나 세션 안의 ! 셸 이스케이프로 한 커밋은 검토되지 않습니다.

한 발 더 — 나의 생각

이 플러그인에서 가장 눈여겨볼 지점은 기능 목록이 아니라 "검토자를 분리했다"는 설계 판단입니다. 코드를 쓴 Claude에게 자기 코드를 채점시키면 자기 접근 방식을 방어하려는 편향이 끼기 쉽습니다. 그래서 fresh context의 별도 Claude가 diff부터 보고 "문제를 찾아라"는 지시만 받는 구조로 짠 겁니다. AI 에이전트에게 검증을 맡길 때 흔히 빠지는 함정 — 만든 주체가 검증까지 하는 것 — 을 정면으로 피한 사례라, 보안을 떠나 에이전트 워크플로 설계 일반에 시사점이 큽니다.

한국 팀 관점에서 실전 적용 순서를 제안하면, 처음부터 세 층을 다 켜기보다 무비용 패턴 검사(security-patterns.yaml)부터 시작하는 걸 추천합니다. 우리 코드베이스에서 반복적으로 새던 패턴 — 하드코딩된 키, 멀티테넌트 필터 누락, 사내 금지 함수 — 을 5~10개 규칙으로 먼저 박아두면, 모델 호출 비용 0으로 가장 흔한 사고를 막을 수 있습니다. 모델 기반 검토는 그다음에, 비용 한도(시간당 20회 커밋 검토)를 감안해 핵심 저장소에만 켜는 게 합리적입니다.

다만 한 가지는 분명히 짚어야 합니다. 어떤 층도 쓰기·커밋을 막지 않습니다. "AI가 보안 검토를 해준다"는 안도감이 오히려 사람 리뷰를 느슨하게 만든다면 그게 더 큰 리스크입니다. 이 플러그인은 PR로 넘어가는 문제의 양을 줄이는 도구이지, 사람 리뷰나 CI의 SAST를 대체하는 도구가 아닙니다. 방어선의 가장 앞 한 겹으로 정확히 그만큼만 기대하는 게 맞습니다.

원문: Security guidance plugin — Claude Code Docs