TL;DR

AgentShield는 Claude Code 생태계에서 .claude/ 설정, Hook, MCP 서버, Agent 권한의 보안 취약점을 찾는 독립 실행형 CLI 보안 도구입니다. 102개 규칙이 Secrets·Permissions·Hooks·MCP Servers·Agents를 검사하고, 하드코딩된 키와 과도한 도구 권한부터 명령 주입·원격 실행·Prompt Injection·공급망 위험까지 심각도와 A–F 점수로 정리합니다. npx CLI, GitHub Action, SARIF·JSON·HTML 출력, 기준선·조직 Policy·Evidence pack을 지원해 개인 점검과 CI 게이트에 모두 연결할 수 있습니다. Claude Code 설정을 저장소에서 운영한다면 사용 가치가 높지만, 템플릿과 문서 예시의 탐지 결과가 실제 활성 런타임 노출을 뜻하지 않을 수 있고 안정적인 라이브러리 import API도 아직 제공되지 않습니다.

핵심 포인트

• AgentShield는 Claude Code의 .claude/ 설정과 MCP 서버, Hook, Agent 권한을 검사하는 TypeScript 기반 보안 스캐너입니다. npx로 즉시 실행하거나 npm 전역 설치 후 CLI로 사용할 수 있어 도입 장벽이 낮습니다. Claude Code 설정을 운영하는 개인 개발자와 팀의 사전 점검 도구로 적합합니다.
• Secrets, Permissions, Hooks, MCP Servers, Agents의 5개 범주에 걸쳐 102개 규칙을 적용합니다. 하드코딩된 API 키, Bash(*) 권한, 파일명 보간을 이용한 명령 주입, npx -y 기반 공급망 위험, Prompt Injection 패턴까지 탐지합니다. JSON·SARIF·HTML·Evidence pack 출력으로 CI와 보안 검토 흐름에 연결할 수 있습니다.
• --fix는 환경 변수 참조 전환과 일부 와일드카드 권한 축소처럼 안전하다고 표시된 항목만 자동 수정합니다. GitHub Action은 최소 심각도, 기준선 대비 Drift, 조직 Policy, 공급망 검증을 기준으로 작업을 통과시키거나 실패시킬 수 있습니다. 다만 템플릿·문서·Plugin cache와 실제 활성 설정을 runtimeConfidence로 구분해 결과를 사람이 최종 판정해야 합니다.
• 핵심 사용 대상은 Claude Code 설정을 GitHub 저장소와 CI에서 관리하는 프로젝트입니다. npm 패키지 루트는 안정적인 Scanner library API가 아니라 CLI 진입점을 가리키므로 내부 TypeScript 모듈을 직접 import하는 용도에는 적합하지 않습니다. 프로그래밍 방식 연동이 필요하면 내부 모듈보다 --format json 결과를 소비하는 편이 안전합니다.