AI 에이전트 설정을 위한 보안 감사 도구 (Security auditor for AI agent configurations)
Claude Code 설정을 스캔하여 하드코딩된 비밀 정보(secrets), 권한 설정 오류(permission misconfigs), 훅 주입(hook injection), MCP 서버 리스크, 그리고 에이전트 프롬프트 주입(prompt injection) 벡터를 탐지합니다.
CLI, GitHub Action, 그리고 GitHub App 통합 방식으로 사용할 수 있습니다.
빠른 시작(Quick Start) · 탐지 항목(What It Catches) · API 참조(API Reference) · Opus 파이프라인(Opus Pipeline) · GitHub Action · 배포(Distribution) · MiniClaw · 변경 이력(Changelog)
AI 에이전트 생태계는 보안 도구의 발전 속도보다 빠르게 성장하고 있습니다. 2026년 1월 한 달 동안에만:
- 주요 에이전트 스킬 마켓플레이스의 **12%**가 악성임 (커뮤니티 스킬 2,857개 중 341개)
- CVSS 8.8 등급의 CVE로 인해 17,500개 이상의 인터넷 노출 인스턴스가 원클릭 RCE(원격 코드 실행) 위험에 노출됨 - Moltbook 침해 사고 관련
- 770,000개의 에이전트에 걸쳐 150만 개의 API 토큰이 유출됨
개발자들은 커뮤니티 스킬을 설치하고, MCP 서버를 연결하며, 훅(hooks)을 설정하지만, 자신의 설정 보안을 감사할 수 있는 자동화된 방법이 없습니다. AgentShield는 .claude/ 디렉토리를 스캔하여 취약점이 공격(exploits)으로 이어지기 전에 경고를 보냅니다.
Claude Code 해커톤(Cerebral Valley x Anthropic, 2026년 2월)에서 제작되었습니다. Everything Claude Code 생태계(42K+ stars)의 일부입니다.
# Claude Code 설정을 스캔합니다 (설치 불필요)
npx ecc-agentshield scan
# 또는 전역 설치
...
끝입니다. AgentShield는 ~/.claude/ 디렉토리를 자동으로 탐색하고, 모든 설정 파일을 스캔하며, 등급이 매겨진 보안 보고서를 출력합니다.
탐색 과정에서는 node_modules, 빌드 출력물, .dmux 워크트리 미러와 같은 일반적인 생성 디렉토리를 의도적으로 건너뛰어, 일시적인 복사본이 탐지 결과를 중복시키지 않도록 합니다.
AgentShield 보안 보고서 (Security Report)
등급: F (0/100)
점수 세부 내역 (Score Breakdown)
...
# 특정 디렉토리 스캔
agentshield scan --path /path/to/.claude
# 안전한 문제 자동 수정 (하드코딩된 비밀 정보를 환경 변수(env var) 참조로 교체)
...
이제 JSON 보고서에서 findings[].runtimeConfidence를 확인할 수 있습니다.
AgentShield가 활성 런타임 설정 (active runtime config)을 프로젝트 로컬 설정 (project-local settings), 템플릿/예시 인벤토리 (template/example inventories), 설치된 Claude 플러그인 캐시 (installed Claude plugin caches), 선언적 플러그인 매니페스트 (declarative plugin manifests), 그리고 매니페스트로 해결된 비-셸 훅 구현체 (manifest-resolved non-shell hook implementations)와 구분할 수 있을 때, 이제 JSON 보고서에서 findings[].runtimeConfidence를 확인할 수 있습니다. 보고서에는 일치하는 마커가 있는 경우 Claude Code, OpenCode, Codex, Gemini, Zed, VS Code, dmux, 터미널-에이전트 래퍼 (terminal-agent wrappers), 그리고 프로젝트 로컬 템플릿에 대한 로컬 하네스 어댑터 (local harness adapter) 증거도 포함됩니다.
5개 카테고리에 걸친 102개의 규칙이 있으며, 0–100점 사이의 수치 점수와 함께 A–F 등급이 매겨집니다.
| 항목 | 예시 |
|---|
| API 키 | Anthropic (sk-ant- ), OpenAI (sk-proj- /sk- ), xAI (xai- ), AWS (AKIA ), Google/Gemini (AIza ), Stripe (sk_test_ /sk_live_ ) |
| ... | |
| 항목 | 예시 |
| --- | --- |
| 와일드카드 액세스 (Wildcard access) | Bash(*) , Write(*) , Edit(*) — 제한 없는 도구 권한 |
| ... | |
| 항목 | 예시 |
| --- | --- |
| 커맨드 인젝션 (Command injection) | 셸 명령 내 ${file} 보간 (interpolation) — 공격자가 제어하는 파일명이 코드가 됨 |
| ... | |
| 항목 | 예시 |
| --- | --- |
| 고위험 서버 | 셸/커맨드 MCP, 루트 권한이 있는 파일 시스템, 데이터베이스 MCP, 브라우저 자동화 |
| ... | |
공급망 검증 (agentshield scan --supply-chain)은 MCP 패키지 참조와 루트 package.json 및 package-lock.json 의존성 증거를 추출한 다음, npm 대 git, 고정(pinned) 대 비고정(unpinned), 알려진 양호한 패키지, 그리고 npm 레지스트리 기반 메타데이터에 대한 출처(provenance) 수를 보고합니다. 다운로드 수, 유지 관리자, postinstall 스크립트, 지원 중단(deprecation), 패키지 연령을 확인하기 위해 npm에 쿼리하려면 --supply-chain-online을 추가하십시오.
패키지 관리자 강화 (Package-manager hardening) 점검은 또한 .npmrc, .yarnrc.yml, pnpm-workspace.yaml을 스캔하여 평문 레지스트리 자격 증명, 명시적인 의존성 라이프사이클 스크립트 (lifecycle-script) 활성화 여부, 그리고 패키지 관리자가 지원하는 경우 누락되었거나 취약한 릴리스 연령 쿨다운 (release-age cooldowns)을 확인합니다. npm 설정은 라이프사이클 스크립트 차단 여부와 잘못된 신뢰를 유발할 수 있는 지원되지 않는 릴리스 연령 키를 점검합니다. pnpm의 minimumReleaseAge / minimum-release-age를 사용하십시오.
, Yarn npmMinimalAgeGate,
또는 냉각 기간 (cooldown) 강제를 위한 외부 패키지 관리자 정책 래퍼 (policy wrapper)를 사용하십시오.
AgentShield는 최근 npm 및 PyPI 캠페인 페이로드에서 사용되는 AI 개발 도구의 지속성 표면 (persistence surfaces)을 스캔합니다. 여기에는 Claude Code 훅 (hook) 설정, .claude/router_runtime.js, VS Code tasks.json 폴더 열기 자동화, Zed 프로젝트 tasks.json, .vscode/setup.mjs, .zed/setup.mjs, GitHub 워크플로 드롭인 (workflow drop-ins), LaunchAgent/systemd 데드맨 스위치 (dead-man switch) 아티팩트, gh-token-monitor 토큰 저장소 파일, 메타데이터 서비스 자격 증명 대상, 그리고 보고된 데이터 유출 또는 2단계 네트워크 지표 (indicators)가 포함됩니다. 이러한 지표들은 심각한 훅 탐지 결과 (critical hook findings)로 방출되어, 악성 패키지가 이미 삭제된 후라도 CI가 즉시 실패 (fail fast)할 수 있도록 합니다.
AgentShield는 활성화된 MCP 설정과 저장소에 포함된 MCP 템플릿을 모두 스캔합니다.
mcp.json, .claude/mcp.json, .claude.json 및 활성화된 settings.json에서 발견된 사항은 가장 신뢰도가 높은 런타임 노출 (runtime exposure)로 취급해야 합니다.settings.local.json에서 발견된 사항은 runtimeConfidence: project-local-optional로 방출됩니다.mcp-configs/, config/mcp/ 또는 configs/mcp/와 같은 위치에서 발견된 사항은 저장소 템플릿에 존재하는 위험한 MCP 정의를 나타내며, 활성화된 런타임 사용이 보장된 것은 아닙니다.- JSON, 마크다운 (markdown), 터미널 (terminal) 및 HTML 출력은 이제
runtimeConfidence: active-runtime | project-local-optional | template-example | docs-example | plugin-cache | plugin-manifest | hook-code를 통해 소스 컨텍스트를 노출합니다.
- 기밀이 아닌
template-example MCP 탐지 결과는 0.25x의 가중 점수가 적용되며, 단일 템플릿 파일은 점수 카테고리당 최대 10점의 차감 점수로 제한되므로, 단일 MCP 카탈로그가 수십 개의 활성화된 서버처럼 점수를 깎지 않도록 합니다.
- 템플릿 파일 내에서 위험한 서버 유형, 원격 URL 전송 (remote URL transport),
npx -y와 같은 탐지 결과는
, 고정되지 않은 패키지 (unpinned packages), 그리고 환경 상속 (environment inheritance)은 여전히 가치가 있지만, 이를 "이 MCP가 현재 확실히 활성화되어 있다"라기보다는 "이 저장소가 위험한 MCP 템플릿을 포함하고 있다"로 해석해야 합니다. - 소스 파일이 템플릿 카탈로그인 경우, 대규모 MCP 서버 수와 같은 집계된 결과는 런타임 노출 (runtime exposure)을 과장할 가능성이 특히 높습니다.
| 항목 | 예시 |
|---|
| 제한되지 않은 도구 (Unrestricted tools) | Bash 접근 권한이 있는 에이전트, allowedTools 제한 없음 |
| ... | |
.claude/subagents/ 및 .claude/slash-commands/ 아래의 구조화된 JSON은 allowedTools 또는 유사한 도구 메타데이터를 선언할 때 에이전트 설정 (agent config)과 같이 분석됩니다. 자유 형식의 skill-md 프롬프트 텍스트는 여전히 agent-md 및 CLAUDE.md보다 보안 범위가 좁습니다. | |
- 실시간 감사 노트와 후속 조치 항목은
false-positive-audit.md에서 추적됩니다. - 가장 유용한 운영자 가이드는 감사의 Triage Rules For Current Reports 섹션에 있습니다. - 감사 문서에는 재사용 가능한 False-Positive Taxonomy, Repo Audit Worksheet, 그리고 Release Gate For Accuracy Changes가 포함되어 있습니다. - 파일 간 훅 매니페스트 (hook-manifest) 인지 기능이 추가되어, 동반되는 hooks/hooks.json 매니페스트가 PreToolUse 훅을 정의하는 경우 설정 전용인 hooks-no-pretooluse를 억제합니다. - 매니페스트 참조 훅 구현은 이제 hooks/hooks.json 스타일의 간접 참조를 통해 발견됩니다; 셸 타겟 (shell targets)은 훅 규칙을 통해 계속 탐지되며, 비셸 hook-code 타겟은 이제 명시적인 output(...) 컨텍스트 주입, 트랜스크립트 입력 접근, 그리고 자식 프로세스 래퍼 (child-process wrappers)를 통해 실행되는 원격 셸 페이로드 (remote shell payloads)에 대해 타겟팅된 결과(findings)를 생성합니다. - 현재 알려진 고신호 (high-signal) 주의 사항으로는, 현재의 hook-code 신호를 넘어 언어 인식 분석 (language-aware analysis)이 여전히 필요한 광범위한 비셸 훅 실행과, 대부분의 에이전트/인젝션 규칙을 여전히 우회하는 skill-md 프롬프트 텍스트가 있습니다. runtimeConfidence는 이제 MCP 결과 및 settings.local.json에 표시됩니다.
, docs/examples, 설치된 Claude 플러그인 캐시 (plugin caches), 플러그인 매니페스트 (plugin manifests), 그리고 매니페스트로 확인된 non-shell 훅 코드 (manifest-resolved non-shell hook code). 점수 산정 시 non-secret template-example 및 docs-example 탐지 결과는 0.25x로 감점하고, non-secret project-local-optional 탐지 결과는 0.75x로 감점하며, non-secret plugin-cache / plugin-manifest 탐지 결과는 0.5x로 감점합니다. Non-secret template-example 탐지 결과는 파일 및 점수 카테고리당 최대 10점의 감점 제한이 적용되어, 하나의 카탈로그 파일이 전체 등급을 좌우할 수 없도록 합니다. hook-code 탐지 결과는 현재 전체 가중치를 유지하지만
탐지 결과; 와일드카드(wildcard) 및 동적 네트워크 권한은 여전히 탐지됩니다. - Exact
Bash(node scripts/foo.js ...)
및 Bash(python3 ./tools/audit.py ...)
래퍼(wrapper) 명령은 더 이상 일반적인 인터프리터 액세스(interpreter-access) 탐지를 트리거하지 않지만, node -e 및 python -c와 같은 인라인 eval 형태는 여전히 트리거됩니다. - Exact
Bash(docker ps) 및 Bash(docker image ls)와 같은 읽기 전용 Docker 인벤토리 명령은 더 이상 일반적인 Docker 액세스(Docker-access) 탐지를 트리거하지 않지만, docker run 및 docker exec와 같은 실행 중심 형태는 여전히 트리거됩니다. - Exact
settings.local.json 허용 목록(allowlists)은 모든 허용 항목이 완전히 명시된 경우 permissions-no-deny-list의 심각도를 높음(high)에서 중간(medium)으로 낮춥니다. 와일드카드 또는 동적 프로젝트 로컬 권한은 여전히 더 높은 심각도를 유지합니다. - Exact local-only
settings.local.json 허용 목록은 이제 hooks-no-pretooluse 또한 중간(medium)에서 낮음(low)으로 낮춥니다. 더 광범위하거나 네트워크 기능이 있는 프로젝트 로컬 설정은 여전히 더 높은 심각도를 유지합니다. - Comment-only
주석 처리된 셸 훅(shell-hook) 라인은 이제 훅 유출(hook exfiltration), 민감한 경로(sensitive-path), 및 silent-fail 정규식 규칙에서 무시되므로, 인라인 수정 사항(remediation notes) 및 주석 처리된 예제는 더 이상 실제 훅 동작처럼 보이지 않습니다.
-
좁은 범위의 전문 에이전트(specialist agents), 하위 에이전트(subagents), 그리고 슬래시 명령(slash commands)은 이제 일반적인 Bash 액세스 및 권한 상승 체인(escalation-chain) 탐지 결과를 높음(high)에서 중간(medium)으로 낮춥니다. 더 광범위한 일반 에이전트(generalist) 워크플로우는 여전히 더 높은 심각도를 유지합니다.
-
./와 같은 상대 경로를 사용하는 리포지토리 범위(Repo-scoped) 파일 시스템 MCP 서버는 이제 제한 없는 루트/홈(root/home) 파일 시스템 액세스보다 낮은 등급을 받습니다. 루트 레벨의 파일 시스템 노출은 여전히 높음(high) 상태를 유지합니다. - Defensive agent-review
fetch(userProvidedUrl)와 같은 패턴을 언급하는 방어적 에이전트 검토 콘텐츠는 더 이상 agents-injection-surface를 트리거하지 않습니다. 외부 콘텐츠를 가져오거나 처리하라는 직접적인 지침은 여전히 트리거됩니다. agents-explorer-write는 이제 이후의 워크플로우/예제 텍스트 대신 역할 메타데이터(role metadata)와 리드 에이전트 소개(lead agent intro)를 사용하므로, 일반 작업자 프롬프트의 절차적인 search for ... 단계는 더 이상 탐색형(explorer-style) 에이전트로 잘못 분류되지 않습니다. 예시: chief-of-staff.md
gog gmail search ...를 포함하고 있다는 이유만으로 더 이상 해당 규칙에 걸리지 않습니다.
.agents-oversized-prompt
이제는 단순한 파일 길이가 아닌, 코드 블록 (fenced code blocks)과 마크다운 표 (Markdown tables)를 제외한 실제 유효한 프롬프트 크기 (effective prompt size)를 측정합니다. chief-of-staff.md 및 planner.md와 같이 예시가 많은 에이전트들은 더 이상 해당 규칙에 걸리지 않는 반면, 산문 (prose) 비중이 높은 에이전트들은 여전히 걸리게 됩니다.
docs/, commands/, examples/, tutorials/, demos/와 같이 예시와 유사한 경로에 있는 마크다운 예시/테스트 비밀번호들은 주변 문맥이 명확하게 교육적(instructional)인 경우 이제 억제(suppressed)됩니다. 이러한 억제 기능은 일반적인 에이전트/설정 (agent/config) 마크다운에는 적용되지 않습니다.
리포지토리 스캔 결과가 너무 소란스럽게(noisy) 보이거나 AgentShield 규칙을 조정할 때는 이 워크플로우를 사용하세요.
- 파일 경로와
runtimeConfidence를 검사할 수 있도록 JSON 출력으로 시작하세요.