安全掃描技能
使用 AgentShield 稽核你的 Claude Code 設定，找出安全問題。
啟用時機
- 設定新的 Claude Code 專案時
- 修改
.claude/settings.json、CLAUDE.md或 MCP 設定後 - 在提交設定變更之前
- 加入一個已有 Claude Code 設定的新儲存庫時
- 定期安全衛生檢查
掃描項目
| 檔案 | 檢查內容 |
|---|---|
CLAUDE.md | 硬編碼機密、自動執行指令、提示注入模式 |
settings.json | 過於寬鬆的允許清單、遺漏的拒絕清單、危險的繞過旗標 |
mcp.json | 有風險的 MCP 伺服器、硬編碼環境變數機密、npx 供應鏈風險 |
hooks/ | 透過插入（interpolation）進行的命令注入、資料外洩、靜默錯誤抑制 |
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 深度分析
執行對抗式三代理管線以進行更深層分析：
# 需要 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(*)（無限制的 shell 存取） - 鉤子中透過
${file}插入進行的命令注入 - 執行 shell 的 MCP 伺服器
高度發現（上線前修復）
- CLAUDE.md 中的自動執行指令（提示注入向量）
- 權限中遺漏的拒絕清單
- 具有不必要 Bash 存取的代理
中度發現（建議修復）
- 鉤子中的靜默錯誤抑制（
2>/dev/null、|| true） - 遺漏 PreToolUse 安全鉤子
- MCP 伺服器設定中的
npx -y自動安裝
資訊發現（僅供參考）
- MCP 伺服器遺漏描述
- 正確標記為良好做法的禁止性指令