Claude Security 설치부터 패치 적용까지, AI 코드 취약점 스캔 가이드

Claude Security가 뭔가요?

Claude Security는 여러 Claude 에이전트가 팀을 이뤄 코드베이스의 보안 취약점을 스캔하고, 검증을 거친 발견 사항을 패치 파일로까지 만들어주는 AI 보안 도구입니다. Anthropic이 2026년 7월 베타로 공개했고, 두 가지 형태로 제공됩니다.

• Claude Code 플러그인: 내 터미널의 Claude Code 세션 안에서 스캔이 돌아갑니다. 유료 플랜이면 누구나 베타로 사용할 수 있습니다.
• 매니지드 서비스: Anthropic이 호스팅하는 방식으로, 연결된 저장소를 상시 모니터링하고 Slack·Jira 연동과 예약 스캔을 지원합니다. Enterprise 플랜 전용 공개 베타입니다.

이 글은 대부분의 사용자가 바로 써볼 수 있는 플러그인 기준으로 설치부터 패치 적용까지 다룹니다.

스캔이 시작되면 에이전트 팀이 4단계로 움직입니다. 먼저 코드베이스의 아키텍처를 맵핑하고, 위협 모델을 세우고, 취약점을 사냥한 뒤, 별도의 검증 에이전트가 모든 발견 사항을 독립적으로 재검토합니다. 검증을 통과한 항목만 리포트에 실리기 때문에 규칙 기반 스캐너 대비 오탐이 줄어드는 구조입니다. 초점은 메모리 손상, 인젝션, 인증 우회, 복잡한 로직 오류 같은 고심각도 취약점입니다.

준비물

• Claude Code v2.1.154 이상, 유료 플랜 (스캔은 플랜 사용량에서 차감됩니다)
• 다이내믹 워크플로우 활성화 (Pro 플랜은 /config의 Dynamic workflows 항목에서 켜야 합니다)
• Python 3.9.6 이상이 python3로 PATH에 잡혀 있을 것 (표준 라이브러리만 쓰므로 별도 패키지 설치는 없습니다)
• Git (변경분 스캔과 패치 생성에 필요. 전체 스캔은 버전 관리 없는 디렉터리에서도 동작합니다)
• Linux, macOS, Windows 모두 지원

Step 1: 플러그인 설치

Claude Code 세션에서 공식 마켓플레이스로 설치합니다.

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

마켓플레이스를 찾을 수 없다는 메시지가 나오면 마켓플레이스를 먼저 등록한 뒤 다시 설치합니다.

/plugin marketplace add anthropics/claude-plugins-official

설치 후 재시작 없이 현재 세션에 적용하려면 리로드 명령을 실행합니다.

/reload-plugins

Step 2: 코드베이스 스캔 실행

플러그인이 추가하는 명령은 /claude-security 하나입니다. 실행하면 세 가지 작업 메뉴가 열립니다.

1. Scan codebase: 저장소 전체 또는 특정 영역 스캔
2. Scan changes: 브랜치 diff, PR diff, 단일 커밋 스캔
3. Suggest patches: 리포트의 발견 사항을 패치 파일로 변환

메뉴에서 Scan codebase를 고르면 플러그인이 저장소를 먼저 읽고, 전체 스캔과 영역별 스캔 옵션을 파일 수·상대 비용과 함께 제시합니다. 어디를 스캔할지 모르겠다면 "I don't know"라고 답하면 저장소 크기에 맞는 기본값을 골라줍니다. 스캔은 토큰을 상당히 소모할 수 있고 완료까지 Claude Code를 열어둬야 하므로, 사용자가 확인하기 전에는 아무것도 실행되지 않습니다.

메뉴를 거치지 않고 자연어로 바로 요청할 수도 있습니다. /claude-security scan my branch처럼 인자를 붙이거나, "scan commit abc1234"라고 말하면 됩니다. 머지 전 브랜치 점검이라면 변경분 스캔이 시간과 토큰을 아껴줍니다. 단, 커밋된 변경만 스캔 대상이므로 작업 중인 수정은 먼저 커밋하거나 스태시해야 합니다.

대형 저장소라면 전체를 한 번에 돌리기보다 API 레이어, 인증 코드처럼 영역을 하나씩 나눠 스캔하는 방식을 권장합니다. 리포트의 커버리지 섹션에 어디를 검사했고 어디를 안 했는지 명시되므로, 다른 영역은 다음 스캔에서 이어가면 됩니다.

Photo by Markus Spiske on Unsplash

Step 3: 스캔 리포트 읽기

스캔이 끝나면 저장소 안에 타임스탬프가 붙은 CLAUDE-SECURITY-<timestamp>/ 디렉터리가 생기고, 세 개의 파일이 담깁니다.

이 디렉터리에는 자체 .gitignore가 들어 있어 실수로 git add를 해도 리포트가 커밋에 딸려 가지 않습니다. 감사 기록용으로 리포트를 남기고 싶다면 그 .gitignore 파일만 지우고 커밋하면 됩니다.

한 가지 알아둘 점은 스캔이 비결정적이라는 것입니다. 같은 코드를 두 번 스캔하면 다른 발견 사항이 나올 수 있습니다. 공식 문서도 정기적으로 스캔을 반복하고, 리비전 스탬프로 각 리포트가 어느 코드를 다뤘는지 추적하라고 안내합니다.

Step 4: 패치 제안 받고 적용하기

/claude-security 메뉴에서 Suggest patches를 고르거나 "fix finding F3"처럼 요청하면, 선택한 발견 사항에 대한 패치가 만들어집니다. 패치는 저장소의 스크래치 복사본에서 작성되므로 원본 파일은 건드리지 않습니다.

여기서 이 도구의 설계 철학이 드러납니다. 패치를 작성한 에이전트와 별개의 리뷰 에이전트가 diff를 독립적으로 읽고, 프로젝트에 테스트가 있으면 실제로 돌려봅니다. 이 리뷰가 "해당 취약점을 해결했고, 새 취약점을 만들지 않았고, 다른 동작은 바꾸지 않았다" 세 가지를 보증할 수 있을 때만 패치가 산출됩니다. 보증할 수 없으면 패치 대신 이유를 설명하는 짧은 노트가 남습니다.

패치는 절대 자동으로 적용되지 않습니다. patches/ 폴더에 발견 사항별로 F1.patch 형태로 떨어지고, 적용은 항상 사용자의 몫입니다.

git apply CLAUDE-SECURITY-<timestamp>/patches/F1.patch

패치마다 별도 PR로 올려 각각 리뷰·테스트받는 방식을 공식 문서가 권장합니다. 패치 대상 코드에 테스트가 없었다면 노트에 그 사실이 적히므로, 그런 패치는 더 꼼꼼히 검토해야 합니다.

기존 보안 도구와 어떻게 다른가요?

Claude Security 플러그인은 Claude 생태계 보안 도구 스택에서 "온디맨드 딥 스캔" 층을 담당합니다. 층별로 역할이 다릅니다.

플러그인과 매니지드 서비스의 관계도 대체가 아니라 분담입니다. 매니지드는 저장소를 연결해두면 알아서 모니터링하지만, 플러그인은 매니지드가 닿지 못하는 곳에 닿습니다. GitLab이나 Bitbucket에 있는 저장소, 인바운드 연결을 막아둔 사내망 코드는 로컬에서 도는 플러그인만 스캔할 수 있습니다.

기존 SAST, 의존성 스캐너와의 관계도 마찬가지입니다. 공식 문서는 이 플러그인이 기존 도구를 대체하지 않는다고 명시합니다. 결정론적 규칙 검사는 기존 도구가, 사람 보안 연구원처럼 맥락을 읽는 추론은 Claude가 맡는 상호 보완 구조입니다.

세션 내 실시간 검토 층이 궁금하다면 Claude Code 보안 가이던스 플러그인 정리 글을 함께 참고하시면 됩니다.

자주 묻는 질문

Claude Security는 무료인가요?

플러그인은 Claude Code 유료 플랜(Pro 이상)에서 베타로 사용할 수 있고, 스캔마다 플랜 사용량이 차감됩니다. 상시 모니터링형 매니지드 서비스는 Enterprise 플랜 전용입니다.

패치가 코드에 자동으로 적용되나요?

아닙니다. 패치는 patches/ 폴더에 파일로만 생성되고, 적용은 항상 사용자가 git apply로 직접 합니다. 독립 리뷰 에이전트의 검증을 통과한 패치만 산출되지만, 공식 문서도 적용 전 직접 검토를 권장합니다.

security-guidance 플러그인과 뭐가 다른가요?

security-guidance는 Claude가 코드를 작성하는 동안 같은 세션에서 자동으로 검토하는 실시간 층이고, Claude Security 플러그인은 원할 때 저장소 전체나 diff를 멀티 에이전트로 깊게 스캔하는 온디맨드 층입니다. 둘은 대체 관계가 아니라 방어선의 서로 다른 겹입니다.

GitLab이나 사내망 코드도 스캔할 수 있나요?

가능합니다. 플러그인은 내 머신의 Claude Code 세션에서 로컬로 실행되므로, GitLab·Bitbucket 저장소나 인바운드 연결이 막힌 네트워크의 코드처럼 매니지드 서비스가 접근할 수 없는 코드도 스캔할 수 있습니다.

기존 SAST 도구를 걷어내도 되나요?

권장하지 않습니다. 공식 문서는 정적 분석, 의존성 스캐닝, 코드 리뷰와 나란히 운영하라고 안내합니다. 언어별 규칙과 공급망 검사는 기존 도구의 결정론적 검사가, 파일을 넘나드는 데이터 흐름 추적과 로직 오류는 Claude의 맥락 추론이 각각 강한 영역입니다.

인사이트

이번 출시에서 눈여겨볼 지점은 기능보다 설계 패턴입니다. Anthropic 보안 제품 세 가지가 전부 같은 원리 위에 서 있습니다. security-guidance는 코드를 쓴 Claude가 아닌 별도 컨텍스트의 Claude가 diff를 검토하고, Claude Security는 취약점을 찾은 에이전트와 다른 에이전트가 발견을 검증하며, 패치 역시 작성자가 아닌 리뷰어 에이전트가 보증해야만 산출됩니다. "만든 주체와 검증하는 주체를 분리한다"는 원칙이 제품군 전체의 뼈대가 된 셈입니다. 이 패턴은 보안이 아닌 일반 업무 에이전트를 설계할 때도 그대로 가져다 쓸 수 있습니다. 콘텐츠 생성과 품질 검수, 데이터 추출과 대조 검증처럼 생산자·검증자를 나누는 것만으로 결과물 신뢰도가 달라집니다.

또 하나, 스캔의 비결정성을 공식 문서가 숨기지 않고 명시한 점이 흥미롭습니다. 같은 코드에서 매번 같은 결과가 나오는 기존 SAST와 정반대 특성인데, Anthropic은 이를 결함이 아니라 "정기적으로 반복 스캔하라"는 운영 모델의 근거로 삼았습니다. 결정론적 도구는 한 번 통과하면 끝이지만, 비결정적 스캐너는 돌릴 때마다 다른 각도에서 코드를 봅니다. 리비전 스탬프로 각 리포트를 특정 커밋에 묶어두는 장치도 이 운영 모델을 전제로 한 설계입니다.

한국 기업 환경에서는 플러그인의 로컬 실행이라는 특성이 생각보다 중요할 수 있습니다. 국내 조직 상당수가 GitLab 자체 호스팅이나 폐쇄망에서 코드를 관리하는데, 외부 SaaS 보안 스캐너는 이런 환경에 넣기 어렵습니다. 터미널에서 도는 플러그인은 인바운드 연결 없이 동작하므로, 보안 정책이 엄격한 조직이 AI 취약점 스캔을 처음 시도해보는 진입로가 될 수 있습니다.

원문: https://claude.com/product/claude-security
플러그인 문서: https://code.claude.com/docs/en/claude-security