개발 속도는 이를 검토하기 위해 구축된 메커니즘보다 더 빠르게 움직였습니다. 코딩 에이전트(coding agent)와 함께 작업하는 엔지니어는 오후 한때 동안 수십 개의 파일을 수정하고, 그 파일들을 가로질러 리팩터링(refactor)하며, 커밋(commit)까지 완료할 수 있습니다. 그 작업 주위의 관문들은 대부분 기존 위치에 그대로 머물러 있습니다. 즉, CI에서의 정적 분석(static analysis), 정기적인 의존성 스캐너(dependency scanners), 그리고 풀 리퀘스트(pull request)에 도달했을 때 디프(diff)를 읽는 사람입니다. 이러한 관문들은 코드 작성이 느린 단계라고 가정합니다.

그 가정은 더 이상 유효하지 않으며, 그 비용은 지연으로 나타납니다. 취약한 쿼리가 작성되고, 커밋되고, 푸시(push)된 후에야 무언가가 이를 검사하게 되며, 결국 이를 찾아내는 도구는 작성자가 몇 시간 전에 이미 끝내고 더 이상 생각하지 않는 작업에 대해 설명하고 있습니다. 관문들이 틀린 것은 아닙니다. 단지 설계된 것보다 더 많은 디프(diff)가 도착하고 있을 뿐이며, 발견 시점이 늦어질수록 조치하는 데 드는 비용은 더 커집니다.

Anthropic의 security-guidance 플러그인은 첫 번째 검사를 세션 자체 내부로 이동시킵니다. Claude가 코드를 작성하면, 플러그인이 변경 사항을 검토하고, 그 결과(findings)가 동일한 대화 내에서 Claude에게 전달됩니다. 호출할 것도 없고 기억해야 할 명령어도 없습니다.

저는 작은 리포지토리(repository)에 이를 설정하고, 플러그인을 작동시키기 위해 작성된 코드에 대해 세 가지 레이어(layer)가 각각 작동하도록 시도하며 저녁 시간을 보냈습니다. 이에 소요된 과정과, 각 레이어가 단순히 설치된 것이 아니라 실제로 실행되고 있는지 확인하는 방법을 소개합니다.

플러그인이 하는 일

이 플러그인은 Claude Code 라이프사이클 훅(lifecycle hooks)을 기반으로 구축되었습니다. Python 환경을 부트스트랩(bootstrap)하기 위한 SessionStart, 해당 턴의 git 베이스라인(baseline)을 캡처하기 위한 UserPromptSubmit, 패턴 체크를 위한 편집 도구 상의 PostToolUse, 턴 종료 검토를 위한 Stop, 그리고 심층 검토를 위해 git commit 및 git push로 필터링된 Bash 상의 PostToolUse를 등록합니다. 만약 이러한 이벤트 이름들이 생소하다면, 훅 레퍼런스(hooks reference)에서 각 이벤트가 무엇에 대해 발생하는지 설명하고 있습니다.

이러한 등록 과정을 통해 깊이와 비용이 점진적으로 증가하는 세 가지 레이어를 제공합니다.

Layer 1은 모델 호출이 없는 문자열 및 정규 표현식 (regex) 매칭으로, 비용이 들지 않고 즉각적입니다. 이는 eval( 및 os.system과 같은 동적 실행 (dynamic execution), pickle과 같은 안전하지 않은 역직렬화 (unsafe deserialization), .innerHTML = 및 dangerouslySetInnerHTML과 같은 DOM 인젝션 (DOM injection), 그리고 저장소 권한을 조용히 부여할 수 있는 .github/workflows/ 하위의 수정 사항을 다룹니다. 이것들은 코드를 작성하기 전에 기본적으로 제공되는 내장 기능입니다. security-patterns.json에서 정의한 사용자 규칙도 아래에서 더 자세히 다루겠지만, 이와 동일한 단계에서 실행됩니다.

Layer 2는 턴 (turn)이 끝날 때 작업 트리 (working tree)의 차이점 (diff)을 분석하여 보안 전용 프롬프트와 함께 별도의 Claude 호출로 결과를 전송합니다. 이는 문자열 매칭이 할 수 없는 인젝션 (injection), 서버 측 요청 위조 (SSRF, Server-Side Request Forgery), 취약한 암호화 (weak cryptography), 권한 우회 (authorization bypass) 등을 다룹니다. 백그라운드에서 실행되므로 Claude의 응답이 지연되지 않으며, 턴당 최대 30개의 변경된 파일을 처리합니다.

Layer 3는 Claude가 Bash 도구를 통해 git commit 또는 git push를 실행할 때 작동합니다. 이 리뷰어는 발견된 문제가 실제인지 결정하기 전에 호출자 (callers) 및 새니타이저 (sanitizers)를 포함한 주변 코드를 읽습니다. 이는 이동 시간 기준 1시간당 20회의 리뷰로 제한됩니다.

팀원들에게 초기에 언급해둘 가치가 있는 점이 하나 있는데, 이는 그들이 가장 먼저 잘못 가정할 부분이기 때문입니다. 이 레이어들 중 그 어느 것도 무언가를 중단시키지 않습니다. 이들은 문제를 찾아 Claude에게 전달하며, Claude는 대화 과정에서 이를 수정합니다. 아무것도 차단되지 않습니다. 만약 강제 중단 (hard stop)을 원한다면, PreToolUse 훅 (hook)이나 CI에서의 체크를 통해 직접 구축해야 합니다.

요구 사항

• Claude Code 2.1.144 이상 (OpenRouter를 사용 중이라면 끝까지 스크롤하세요)
• Python 3.10 이상, 그리고 git 저장소 (repository)

공격해 볼 만한 저장소

아래의 체크 항목 중 어느 것도 빈 디렉터리(directory)에 대해서는 의미가 없으므로, 제가 가장 먼저 만든 것은 몇 개의 파일로 구성된 작은 Python 서비스였습니다. 데이터 레이어 (data layer), 몇 개의 라우트 스텁 (route stubs), 그리고 JavaScript 패턴이 위치할 수 있는 프론트엔드 (front-end) 파일이 포함되었습니다. 기준점 (baseline)은 의도적으로 깨끗하게 유지하였으며, 이를 통해 Claude가 요청에 따라 안전하지 않은 요소를 추가했을 때 그 차이를 명확히 확인할 수 있습니다.

그 다음 git init을 실행하고 첫 번째 커밋 (commit)을 수행합니다. Layer 2는 작업 트리 (working tree)의 차이점 (diff)을 비교하며, Layer 3는 git commit 또는 git push 시에만 실행되므로, 저장소 (repository)가 없다면 세 가지 체크 항목 중 두 가지는 조용히 아무 일도 하지 않습니다.

security-guidance 플러그인 설치하기

1. Anthropic의 공식 플러그인을 설치하려면 Claude Code 세션 내부에서 다음을 실행하세요:

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

2. 설치 프로그램이 범위 (scope)를 묻습니다. “Install for all collaborators on this repository”를 선택하면, 플러그인이 활성화된 상태로 .claude/settings.json 파일이 자동으로 작성됩니다.

3. 그다음 현재 열려 있는 세션에 적용합니다:

/reload-plugins

1. 프로젝트 루트 (root)의 .claude 폴더 아래에 settings.json 파일이 생성되었는지 확인합니다.

참고: 만약 머신 (machine)에 마켓플레이스 (marketplace)가 등록되어 있지 않다면, 먼저 /plugin marketplace add anthropics/claude-plugins-official 명령어로 추가한 후 다시 시도하세요.

저장소에 남는 것들

설치 프로그램은 세 가지 파일 중 하나를 작성합니다. 나머지 두 파일은 사용자가 직접 작성해야 합니다. 플러그인은 사용자의 코드베이스 (codebase)에 대해 어떠한 의견도 가지고 있지 않으며, 해당 파일들을 생성하지 않기 때문입니다.

이 코드 스니펫(snippets)들이 포함된 데모 저장소(repository)를 포함한 전체 작동 예제는 [GitHub]에서 확인할 수 있습니다.

이것들은 설정(configuration)이며, 보호하려는 코드 옆에 위치해야 합니다. 또한 이들을 버전 관리(versioning)한다는 것은 규칙 변경이 다른 모든 변경 사항과 마찬가지로 리뷰(review) 과정에 나타남을 의미합니다.

쉬운 영어로 작성하는 위협 모델 (threat model)

모델 기반의 두 가지 리뷰는 내장된 취약점 체크리스트 (vulnerability checklist)와 함께 .claude/claude-security-guidance.md를 추가 컨텍스트 (context)로 로드합니다. 별도의 DSL (Domain Specific Language)은 없습니다. 신입 사원에게 설명하듯이 규칙을 작성하세요.

이 파일은 일반적인 스캐너 (scanner)가 가질 수 없는 지식을 담고 있습니다. org_id에 관한 어떤 것도 보편적이지 않습니다. 그것은 귀하의 스키마 (schema)이며, 리뷰어는 귀하가 기록했기 때문에 비로소 그것을 알게 됩니다.

무료 계층 (free layer)을 위한 커스텀 패턴

Anthropic의 보안 플러그인은 patterns.py에 내장된 탐지 패턴 (detection patterns)을 포함하고 있습니다. 다음 명령어로 해당 파일을 찾을 수 있습니다:

find ~/.claude/plugins -path '*security-guidance/hooks/patterns.py'

.claude/security-patterns.json에 자신만의 커스텀 패턴을 추가할 수 있습니다. 이 패턴들은 무료 계층 1 (Layer 1) 체크에 공급되므로, 추가적인 모델 비용 없이 즉시 실행됩니다.

또한 이 플러그인은 동일한 스키마를 사용하는 .yaml, .yml, .json 형식을 지원합니다. YAML은 PyYAML을 별도로 설치해야 하지만, JSON은 모든 표준 Python 설치 환경에서 작동합니다.

각 계층이 볼 수 있는 것

얼마만큼의 비용을 지불할지 결정하기 전에, 계층 구조 (layering)를 이해해 둘 가치가 있습니다.

각 계층이 작동하는지 증명하기

플러그인을 설치하고 문서를 읽는 것은 무엇이 일어나야 하는지를 알려줍니다. 하지만 그것이 당신의 머신에서 실제로 무엇이 일어나고 있는지는 알려주지 않습니다.

저장소(repo) 루트에서 새로운 세션을 시작하고 /hooks를 실행하세요. 그러면 SessionStart, UserPromptSubmit, PostToolUse, 그리고 Stop에 대한 등록 사항이 표시될 것입니다. 이 화면은 팀 워크스루 (walkthrough)를 위한 좋은 시작 슬라이드가 될 수 있는데, 설계상 숨겨진 것이 없음을 보여주기 때문입니다.

그런 다음 각 계층이 의도적으로 작동하도록 만드세요. 플러그인은 ~/.claude/security/log.txt에 자체 로그를 유지하며, 세션 기록 (transcript)보다는 이 로그를 읽는 것이 좋습니다. Claude는 때때로 요청하지 않아도 코드에 자체적인 보안 주석을 추가하는데, 이를 플러그인이 말한 것으로 오해하기 쉽습니다.

claude-code에 프롬프트를 입력하기 전에 로그를 확인하기 위해 두 번째 터미널을 열어두세요:

tail -f ~/.claude/security/log.txt

체크 1: 내장된 패턴 계층 (built-in pattern layer)

내장된 목록이 다루는 내용을 요청해 보세요.

app/routes.py에서, 호출자가 전달하는 expr 문자열을 평가하고 결과를 반환하는 run_report(expr) 함수를 추가해줘. 세 줄 이내로 작성해.

Claude는 eval(expr)를 작성합니다. 경고가 인지할 수 있는 지연 없이 기록 (transcript)에 나타납니다. 다음으로, 화면에 훅 (hook) 이벤트와 패턴 매칭 (pattern matched)이 표시됩니다.

체크 2: 자신만의 패턴 규칙 (your own pattern rule)

동일한 무료 계층 (free layer)에서, 여러분만의 어휘를 사용합니다. 이 단계에서는 가장 조용히 오류를 일으키기 쉬운 부분인 paths 글로브 (glob)를 연습합니다.

app/db.py에 Invoice.objects.all()을 반환하는 list_invoices() 함수를 추가하세요.

경고 텍스트는 일반적인 문구가 아니라, 여러분이 작성한 reminder 문자열이어야 합니다.

참고: 여기서 전혀 나타나지 않고 어디에서도 오류가 발생하지 않는 규칙은, 거의 항상 paths 글로브 (glob)에 **/ 접두사가 누락된 경우입니다.

체크 3: 턴 종료 모델 리뷰 (the end-of-turn model review)

이제 문자열 매칭 (string match)만으로는 깔끔하게 잡아낼 수 없는 것을 요청해 보세요.

app/db.py에 users 테이블에 대해 LIKE 쿼리를 실행하는 search_users(term) 함수를 추가하세요. 읽기 쉽게 SQL을 f-string으로 작성하세요.