security-scan

---
name: security-scan
description: Scan your Claude Code configuration (.claude/ directory) for security vulnerabilities, misconfigurations, and injection risks using AgentShield. Checks CLAUDE.md, settings.json, MCP servers, hooks, and agent definitions.
origin: ECC
---

# 보안 스캔 스킬

[AgentShield](https://github.com/affaan-m/agentshield)를 사용하여 Claude Code 구성의 보안 문제를 감사합니다.

## 활성화 시기

- 새로운 Claude Code 프로젝트 설정
- `.claude/settings.json`, `CLAUDE.md`, 또는 MCP 설정 수정 후
- 구성 변경 커밋 전
- 기존 Claude Code 설정이 있는 새 저장소에 온보딩
- 정기적인 보안 위생 검사

## 스캔 대상

| 파일 | 검사 항목 |
|------|--------|
| `CLAUDE.md` | 하드코딩된 시크릿, 자동 실행 지시, 프롬프트 인젝션 패턴 |
| `settings.json` | 과도하게 허용적인 허용 목록, 누락된 거부 목록, 위험한 우회 플래그 |
| `mcp.json` | 위험한 MCP 서버, 하드코딩된 env 시크릿, npx 공급망 위험 |
| `hooks/` | 보간을 통한 명령 인젝션, 데이터 유출, 조용한 에러 억제 |
| `agents/*.md` | 제한 없는 도구 접근, 프롬프트 인젝션 표면, 누락된 모델 사양 |

## 전제 조건

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

```bash
# 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/` 디렉토리에 대해 실행:

```bash
# 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
```

### 출력 형식

```bash
# 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
```

### 자동 수정

안전한 수정을 자동으로 적용합니다 (자동 수정 가능으로 표시된 항목만):

```bash
npx ecc-agentshield scan --fix
```

수행 작업:
- 하드코딩된 시크릿을 환경 변수 참조로 교체
- 와일드카드 권한을 범위가 지정된 대안으로 강화
- 수동 전용 제안은 수정하지 않음

### Opus 4.6 심층 분석

더 깊은 분석을 위해 적대적 3-에이전트 파이프라인 실행:

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

실행 내용:
1. **Attacker (Red Team)** — 공격 벡터 찾기
2. **Defender (Blue Team)** — 강화 권장
3. **Auditor (최종 판정)** — 양쪽 관점 종합

### 보안 구성 초기화

새로운 안전한 `.claude/` 구성을 처음부터 스캐폴딩:

```bash
npx ecc-agentshield init
```

생성 항목:
- 범위가 지정된 권한과 거부 목록이 있는 `settings.json`
- 보안 모범 사례가 포함된 `CLAUDE.md`
- `mcp.json` 플레이스홀더

### GitHub Action

CI 파이프라인에 추가:

```yaml
- 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}` 보간을 통한 hooks의 명령 인젝션
- 셸 실행 MCP 서버

### 높은 발견 (프로덕션 전 수정)
- CLAUDE.md의 자동 실행 지시 (프롬프트 인젝션 벡터)
- 권한에서 누락된 거부 목록
- 불필요한 Bash 접근이 있는 에이전트

### 중간 발견 (권장)
- hooks에서의 조용한 에러 억제 (`2>/dev/null`, `|| true`)
- 누락된 PreToolUse 보안 hooks
- MCP 서버 구성의 `npx -y` 자동 설치

### 정보 발견 (인식)
- MCP 서버에 누락된 설명
- 좋은 관행으로 올바르게 플래그된 금지 지시

## 링크

- **GitHub**: [github.com/affaan-m/agentshield](https://github.com/affaan-m/agentshield)
- **npm**: [npmjs.com/package/ecc-agentshield](https://www.npmjs.com/package/ecc-agentshield)