---
name: security-scan
description: 使用 AgentShield 掃描您的 Claude Code 檔案配置（claude/ 目錄）是否存在安全性漏洞、配置錯誤及程式碼注入風險。檢查對象包含 CLAUDE.md、settings.json、MCP 伺服器、Hooks 以及 Agent 定義。
---

# 安全性掃描技能 (Security Scan Skill)

使用 [AgentShield](https://github.com/affaan-m/agentshield) 稽核您的 Claude Code 配置檔案，確保環境安全性。

## 何時啟用

- 設定新的 Claude Code 專案時。
- 修改 `.claude/settings.json`、`CLAUDE.md` 或 MCP 配置後。
- 在提交（Commit）配置更改之前。
- 接手具有現成 Claude Code 配置的新儲存庫時。
- 定期進行安全性健康檢查。

## 掃描對象與項目

| 檔案名稱 | 檢查重點 |
|------|--------|
| `CLAUDE.md` | 硬編碼的秘密資訊、自動執行指令、提示詞注入 (Prompt Injection) 模式 |
| `settings.json` | 過度寬鬆的允許清單 (Allow lists)、缺失的拒絕清單 (Deny lists)、危險的繞過標記 |
| `mcp.json` | 具備風險的 MCP 伺服器、硬編碼的環境變數秘密、npx 供應鏈風險 |
| `hooks/` | 指令注入風險、資料外送 (Data Exfiltration)、靜默錯誤抑制 |
| `agents/*.md` | 未受限制的工具存取權、提示詞注入攻擊面、缺失的模型規格 |

## 前置作業

確保已安裝 AgentShield。您可以視需求檢查或進行安裝：

```bash
# 檢查是否已安裝
npx ecc-agentshield --version

# 全域安裝（建議方式）
npm install -g ecc-agentshield

# 或直接透過 npx 執行（免安裝）
npx ecc-agentshield scan .
```

## 使用方式

### 基礎掃描

針對當前專案的 `.claude/` 目錄執行掃描：

```bash
# 掃描當前專案
npx ecc-agentshield scan

# 掃描指定路徑
npx ecc-agentshield scan --path /專案/路徑/claude

# 設定最低嚴重性過濾器
npx ecc-agentshield scan --min-severity medium
```

### 輸出格式

- **終端機輸出 (預設)**：附帶評等色彩的報告。
- **JSON**：適用於 CI/CD 整合。
- **Markdown**：適用於產出技術文件。
- **HTML**：產出自帶深色主題的單一報表檔案。

### 自動修復 (Auto-Fix)

自動套用安全的修復方案（僅限標記為可自動修復的項目）：

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

此操作將會：
- 將硬編碼的秘密資訊替換為環境變數引用。
- 將萬用字元 (*) 權限縮減至具體範圍。
- **絕不會** 修改標註為須手動處理的建議。

### 嚴重性評等說明

- **A (90-100)**：安全的配置。
- **B (75-89)**：存在細微問題。
- **C (60-74)**：需要留意。
- **D (40-59)**：存在顯著風險。
- **F (0-39)**：存在嚴重漏洞。

## 結果解讀

### 致命發現 (Critical - 請立即修正)
- 配置檔案中存在硬編碼的 API 金鑰或權杖。
- 允許清單中出現 `Bash(*)` (代表無限制的 Shell 存取權)。
- Hooks 中存在指令注入風險。

### 高風險發現 (High - 部署至生產環境前修正)
- `CLAUDE.md` 中包含自動執行指令 (可能成為提示詞注入媒介)。
- 權限設定中缺失拒絕清單 (Deny List)。

### 中度風險發現 (Medium - 建議修正)
- Hooks 中存在靜默錯誤抑制 (如 `2>/dev/null`)。
- MCP 伺服器配置中使用了 `npx -y` 自動安裝。

## 相關連結

- **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)
