보안 스캔 스킬
AgentShield를 사용하여 Claude Code 구성을 보안 문제에 대해 감사합니다.
활성화 시점
- 새 Claude Code 프로젝트 설정 시
.claude/settings.json,CLAUDE.md또는 MCP 구성을 수정한 후- 구성 변경 사항을 커밋하기 전
- 기존 Claude Code 구성이 있는 새 리포지토리에 온보딩할 때
- 정기적인 보안 위생 점검
검사 항목
| 파일 | 검사 내용 |
|---|---|
CLAUDE.md | 하드코딩된 시크릿, 자동 실행 명령어, 프롬프트 인젝션 패턴 |
settings.json | 과도하게 허용적인 허용 목록, 누락된 차단 목록, 위험한 우회 플래그 |
mcp.json | 위험한 MCP 서버, 하드코딩된 환경 시크릿, npx 공급망 위험 |
hooks/ | 보간법을 통한 명령 주입, 데이터 유출, 무음 오류 억제 |
agents/*.md | 제한 없는 도구 접근, 프롬프트 인젝션 표면, 누락된 모델 사양 |
전제 조건
AgentShield가 설치되어 있어야 합니다. 필요한 경우 확인 및 설치:
# 설치 여부 확인
npx ecc-agentshield --version
# 전역 설치 (권장)
npm install -g ecc-agentshield
# 또는 npx를 통해 직접 실행 (설치 불필요)
npx ecc-agentshield scan .
사용법
기본 검사
현재 프로젝트의 .claude/ 디렉터리에서 실행:
# 현재 프로젝트 검사
npx ecc-agentshield scan
# 특정 경로 검사
npx ecc-agentshield scan --path /path/to/.claude
# 최소 심각도 필터로 검사
npx ecc-agentshield scan --min-severity medium
출력 형식
# 터미널 출력 (기본값) — 등급이 포함된 컬러 보고서
npx ecc-agentshield scan
# JSON — CI/CD 통합용
npx ecc-agentshield scan --format json
# Markdown — 문서화용
npx ecc-agentshield scan --format markdown
# HTML — 독립형 다크 테마 보고서
npx ecc-agentshield scan --format html > security-report.html
자동 수정
안전한 수정 사항을 자동으로 적용합니다 (자동 수정 가능으로 표시된 것만):
npx ecc-agentshield scan --fix
이 작업은 다음을 수행합니다:
- 하드코딩된 시크릿을 환경 변수 참조로 대체
- 와일드카드 권한을 범위가 지정된 대안으로 강화
- 수동 전용 제안은 절대 수정하지 않음
Opus 4.6 심층 분석
적대적 3-에이전트 파이프라인을 실행하여 더 심층적인 분석:
# ANTHROPIC_API_KEY 필요
export ANTHROPIC_API_KEY=your-key
npx ecc-agentshield scan --opus --stream
다음을 실행합니다:
- 공격자 (레드 팀) — 공격 벡터 탐색
- 방어자 (블루 팀) — 강화 조치 권장
- 감사자 (최종 판결) — 두 관점 종합
보안 구성 초기화
처음부터 새 보안 .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
심각도 수준
| 등급 | 점수 | 의미 |
|---|---|---|
| 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 서버에 대한 설명 누락
- 금지 명령어가 모범 사례로 올바르게 플래그 지정됨