affaan-m/agentshield

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 출력으로 시작하세요.