security-scan

보안 스캔 스킬

AgentShield를 사용해 Claude Code 설정의 보안 문제를 감사합니다.

사용 시점

• 새 Claude Code 프로젝트를 설정할 때
• .claude/settings.json, CLAUDE.md, MCP 설정을 수정한 뒤
• 설정 변경을 커밋하기 전
• 기존 Claude Code 설정이 있는 새 저장소에 온보딩할 때
• 주기적으로 보안 위생 점검을 할 때

검사 대상

File	Checks
CLAUDE.md	하드코딩된 시크릿, 자동 실행 지시, 프롬프트 인젝션 패턴
settings.json	지나치게 넓은 허용 목록, 누락된 차단 목록, 위험한 우회 플래그
mcp.json	위험한 MCP 서버, 하드코딩된 환경 변수 시크릿, npx 공급망 위험
hooks/	문자열 보간 기반 명령 인젝션, 데이터 유출, 조용한 오류 억제
agents/*.md	무제한 도구 접근, 프롬프트 인젝션 표면, 누락된 모델 명세

사전 준비

AgentShield가 설치되어 있어야 합니다. 필요하면 확인 후 설치합니다.

# Check if installed
npx ecc-agentshield --version

# Install globally (recommended)
npm install -g ecc-agentshield

# Or run directly via npx (no install needed)
npx ecc-agentshield scan .

사용 방법

기본 스캔

현재 프로젝트의 .claude/ 디렉터리를 대상으로 실행합니다.

# Scan current project
npx ecc-agentshield scan

# Scan a specific path
npx ecc-agentshield scan --path /path/to/.claude

# Scan with minimum severity filter
npx ecc-agentshield scan --min-severity medium

출력 형식

# Terminal output (default) — colored report with grade
npx ecc-agentshield scan

# JSON — for CI/CD integration
npx ecc-agentshield scan --format json

# Markdown — for documentation
npx ecc-agentshield scan --format markdown

# HTML — self-contained dark-theme report
npx ecc-agentshield scan --format html > security-report.html

자동 수정

안전한 수정만 자동 적용합니다. 자동 수정 가능으로 표시된 항목만 처리합니다.

npx ecc-agentshield scan --fix

이 작업은 다음을 수행합니다.

• 하드코딩된 시크릿을 환경 변수 참조로 교체
• 와일드카드 권한을 더 좁은 범위의 대안으로 축소
• 수동 조치 전용 제안은 수정하지 않음

Opus 4.6 심층 분석

더 깊은 분석이 필요하면 대립형 3에이전트 파이프라인을 실행합니다.

# Requires ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY=your-key
npx ecc-agentshield scan --opus --stream

이 흐름은 다음 순서로 동작합니다.

1. 공격자(Red Team) — 공격 벡터 탐색
2. 방어자(Blue Team) — 강화 방안 제안
3. 감사자(Final Verdict) — 두 관점을 종합

안전한 설정 초기화

새로운 안전한 .claude/ 설정을 처음부터 생성합니다.

npx ecc-agentshield init

생성 항목:

• 범위가 제한된 권한과 차단 목록이 포함된 settings.json
• 보안 모범 사례가 반영된 CLAUDE.md
• mcp.json 플레이스홀더

GitHub Action

CI 파이프라인에 다음처럼 추가합니다.

- uses: affaan-m/agentshield@v1
  with:
    path: '.'
    min-severity: 'medium'
    fail-on-findings: true

심각도 등급

Grade	Score	Meaning
A	90-100	안전한 설정
B	75-89	경미한 문제
C	60-74	주의 필요
D	40-59	중대한 위험
F	0-39	치명적 취약점

결과 해석

치명적 항목 즉시 수정

• 설정 파일에 하드코딩된 API 키 또는 토큰
• 허용 목록의 Bash(*) 같은 무제한 셸 접근
• ${file} 보간을 이용한 훅 명령 인젝션
• 셸 실행형 MCP 서버

높음 운영 반영 전 수정

• CLAUDE.md의 자동 실행 지시문(프롬프트 인젝션 벡터)
• 권한 설정에서 차단 목록 누락
• 불필요한 Bash 접근 권한을 가진 에이전트

중간 수정 권장

• 훅에서의 조용한 오류 억제(2>/dev/null, || true)
• 누락된 PreToolUse 보안 훅
• MCP 서버 설정에서의 npx -y 자동 설치

정보 참고용

• MCP 서버 설명 누락
• 금지 지시문이 좋은 관행으로 올바르게 감지된 경우

링크

• GitHub: github.com/affaan-m/agentshield
• npm: npmjs.com/package/ecc-agentshield