security-scan

安全掃描技能

使用 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 深度分析

執行對抗式三代理管線進行更深層分析：

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

這會依序執行：

1. 攻擊者（紅隊） — 尋找攻擊向量
2. 防禦者（藍隊） — 建議強化措施
3. 稽核者（最終裁決） — 綜合雙方觀點

初始化安全設定

從頭建立新的安全 .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 存取）
• hooks 中透過 ${file} 插值進行的命令注入
• 執行 shell 的 MCP 伺服器

高度發現（上線前修復）

• CLAUDE.md 中的自動執行指令（提示注入向量）
• 權限中缺少拒絕清單
• 具有不必要 Bash 存取的代理

中度發現（建議修復）

• hooks 中的靜默錯誤抑制（2>/dev/null、|| true）
• 缺少 PreToolUse 安全 hooks
• MCP 伺服器設定中的 npx -y 自動安裝

資訊發現（僅供參考）

• MCP 伺服器缺少說明
• 正確標記為良好實務的禁止性指令

連結

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