shannon

Shannon：網頁應用程式與 API 的自動化 AI 滲透測試工具

權限概覽： 此技能會編排 Shannon——一個基於 Docker 的滲透測試工具，會主動對目標應用程式發動攻擊。它會在本機複製/更新 Shannon 儲存庫、執行 Docker 容器，並讀取滲透測試報告。Shannon 會執行真實的漏洞利用——僅限於對你擁有或已取得明確書面授權的應用程式進行測試。 切勿對正式環境執行。

Shannon 會分析你的原始碼、識別攻擊向量，並實際執行漏洞利用，在弱點進入正式環境前加以證明。在 XBOW 安全基準測試中達到 96.15% 的漏洞利用成功率。涵蓋 OWASP Top 10：注入、XSS、SSRF、認證缺陷、授權缺陷等。

---

關鍵：安全檢查（務必優先執行）

在執行任何操作之前，你必須確認：

1. 授權：詢問使用者——「您是否擁有對此目標進行滲透測試的明確授權？」如果他們回答「否」或不確定，請立即停止，並說明需要系統擁有者的書面許可。
2. 環境：確認目標是本機、測試或沙箱環境——絕對不能是正式環境。
3. 範圍：釐清他們想要測試的範圍（完整滲透測試或特定類別）。

⚠️  Shannon 會執行具有變更效應的真實攻擊。
├─ 僅限於對你擁有或已取得書面授權的系統執行
├─ 切勿以正式環境為目標
├─ 結果需要人工審查——LLM 輸出可能包含幻覺
└─ 你必須遵守所有適用的法律

每次滲透測試執行前都顯示此警告。如果使用者已在本次對話中確認過授權，簡短提醒即可。

---

解析使用者意圖

從使用者的輸入中提取：

1. TARGET_URL：要滲透測試的 URL（例如 http://localhost:3000、http://staging.example.com）
2. REPO_NAME：原始碼資料夾名稱（放置在 Shannon 內的 ./repos/ 中）
3. SCOPE：完整滲透測試（預設）或特定類別（injection、xss、ssrf、auth、authz）
4. WORKSPACE：具名工作區，用於恢復功能（選用）
5. CONFIG：自訂 YAML 設定檔路徑（選用，用於認證流程、焦點/避免規則）

常見呼叫模式：

• /shannon http://localhost:3000 myapp → 對本機應用程式進行完整滲透測試
• /shannon --workspace=audit1 http://staging.example.com backend-api → 具名工作區以便恢復
• /shannon --scope=xss,injection http://localhost:8080 frontend → 針對特定類別
• /shannon status → 檢查執行中的滲透測試
• /shannon results → 顯示最新報告
• /shannon stop → 停止執行中的滲透測試

顯示解析後的意圖：

🔐 Shannon 滲透測試
├─ 目標：{TARGET_URL}
├─ 原始碼：repos/{REPO_NAME}
├─ 範圍：{SCOPE 或「完整（全部 5 個 OWASP 類別）」}
├─ 工作區：{WORKSPACE 或「自動產生」}
└─ 設定檔：{CONFIG 或「預設」}

預估執行時間：1–1.5 小時 │ 預估成本：約 $50（Claude Sonnet）

---

步驟 0：確認 Shannon 已安裝

檢查 Shannon 是否已在本機複製：

SHANNON_HOME="${SHANNON_HOME:-$HOME/shannon}"

if [ -d "$SHANNON_HOME" ] && [ -f "$SHANNON_HOME/shannon" ]; then
  echo "Shannon 已安裝於 $SHANNON_HOME"
  cd "$SHANNON_HOME" && git pull --ff-only 2>/dev/null || true
else
  echo "Shannon 未安裝。正在複製..."
  git clone https://github.com/KeygraphHQ/shannon.git "$SHANNON_HOME"
fi

# 確認 Docker 可用
if command -v docker &>/dev/null; then
  echo "Docker：$(docker --version)"
else
  echo "錯誤：需要 Docker。請安裝 Docker Desktop：https://docker.com/products/docker-desktop"
  exit 1
fi

如果 Shannon 未安裝，請複製並通知使用者。如果缺少 Docker，請停止並告知他們安裝。

SHANNON_HOME 預設為 ~/shannon。使用者可透過 SHANNON_HOME 環境變數覆蓋。

---

步驟 1：準備原始碼

Shannon 需要目標的原始碼位於 $SHANNON_HOME/repos/{REPO_NAME}/。

詢問使用者原始碼的位置：

# 如果使用者提供本機路徑
REPO_PATH="/path/to/their/source"
REPO_NAME="myapp"

# 建立符號連結或複製到 Shannon 的 repos 目錄
mkdir -p "$SHANNON_HOME/repos"
if [ ! -d "$SHANNON_HOME/repos/$REPO_NAME" ]; then
  ln -s "$(realpath "$REPO_PATH")" "$SHANNON_HOME/repos/$REPO_NAME"
  echo "已連結 $REPO_PATH → repos/$REPO_NAME"
fi

如果使用者提供 GitHub URL：

cd "$SHANNON_HOME/repos"
git clone "$GITHUB_URL" "$REPO_NAME"

---

步驟 2：設定認證（如有需要）

如果目標需要登入，協助使用者建立 YAML 設定檔：

# $SHANNON_HOME/configs/target-config.yaml
authentication:
  type: form            # "form" 或 "sso"
  login_url: "http://localhost:3000/login"
  credentials:
    username: "admin"
    password: "password123"
  flow: "導航至登入頁面，輸入使用者名稱和密碼，點擊登入"
  success_condition:
    url_contains: "/dashboard"

rules:
  avoid:
    - "/logout"
    - "/admin/delete"
  focus:
    - "/api/"
    - "/auth/"

pipeline:
  max_concurrent_pipelines: 5  # 1-5，預設 5

僅在目標需要認證或有特定範圍規則時才建立設定檔。 對於開放/無需認證的目標，不需要設定檔。

---

步驟 3：驗證 API 憑證

檢查 AI 提供者的憑證是否可用：

cd "$SHANNON_HOME"

# 檢查 Anthropic API 金鑰（主要）
if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
  echo "✅ ANTHROPIC_API_KEY 已設定"
elif [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]; then
  echo "✅ CLAUDE_CODE_OAUTH_TOKEN 已設定"
elif [ "${CLAUDE_CODE_USE_BEDROCK:-}" = "1" ]; then
  echo "✅ AWS Bedrock 模式已啟用"
elif [ "${CLAUDE_CODE_USE_VERTEX:-}" = "1" ]; then
  echo "✅ Google Vertex AI 模式已啟用"
else
  echo "❌ 找不到 AI 憑證。"
  echo "請設定以下其中一項：ANTHROPIC_API_KEY、CLAUDE_CODE_OAUTH_TOKEN，或啟用 Bedrock/Vertex"
  exit 1
fi

如果找不到憑證，說明選項：

• 直接 API（建議）：export ANTHROPIC_API_KEY=sk-ant-...
• OAuth：export CLAUDE_CODE_OAUTH_TOKEN=...
• AWS Bedrock：export CLAUDE_CODE_USE_BEDROCK=1 + AWS 憑證
• Google Vertex：export CLAUDE_CODE_USE_VERTEX=1 + 服務帳戶置於 ./credentials/

也建議：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000

---

步驟 4：啟動滲透測試

關鍵：啟動前務必與使用者確認。 顯示完整指令並等待核准。

cd "$SHANNON_HOME"

# 建立指令
CMD="./shannon start URL={TARGET_URL} REPO={REPO_NAME}"

# 加入選用旗標
# CONFIG=configs/target-config.yaml  （如果存在認證設定檔）
# WORKSPACE={WORKSPACE}              （如果使用者指定）
# OUTPUT=./audit-logs/               （預設）

echo "準備啟動："
echo "  $CMD"
echo ""
echo "這將啟動 Docker 容器並開始滲透測試。"
echo "執行時間：約 1-1.5 小時 │ 成本：約 $50（Claude Sonnet）"

使用者確認後，在背景執行：

cd "$SHANNON_HOME" && ./shannon start URL={TARGET_URL} REPO={REPO_NAME} {EXTRA_FLAGS}

使用 run_in_background: true 並設定逾時為 600000 毫秒（初始設定 10 分鐘）。滲透測試本身在 Docker 中執行，會獨立繼續。

---

步驟 5：監控進度

滲透測試執行期間，使用者可以檢查狀態：

cd "$SHANNON_HOME"

# 列出作用中的工作區
./shannon workspaces

# 檢視特定工作流程的日誌
./shannon logs ID={workflow-id}

說明 5 階段管線：

Shannon 管線（5 階段，盡可能平行）：
├─ 階段 1：前期偵察——原始碼分析 + 外部掃描（Nmap、Subfinder、WhatWeb）
├─ 階段 2：偵察——透過瀏覽器自動化進行即時攻擊面繪製
├─ 階段 3：弱點分析——5 個平行代理程式（注入、XSS、SSRF、認證、授權）
├─ 階段 4：漏洞利用——專用代理程式執行真實攻擊以驗證發現
└─ 階段 5：報告——附可重現 PoC 的執行摘要

---

步驟 6：讀取與解讀結果

報告儲存於 $SHANNON_HOME/audit-logs/{hostname}_{sessionId}/。

cd "$SHANNON_HOME"

# 尋找最新報告
LATEST=$(ls -td audit-logs/*/ 2>/dev/null | head -1)
if [ -n "$LATEST" ]; then
  echo "最新報告：$LATEST"
  # 尋找主要報告檔案
  find "$LATEST" -name "*.md" -type f | head -5
fi

讀取報告並呈現摘要：

🔐 Shannon 滲透測試報告：{TARGET}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 嚴重：{N} 個弱點
🟠 高：   {N} 個弱點
🟡 中：   {N} 個弱點
🔵 低：   {N} 個弱點

主要發現：
1. [嚴重] {弱點類型} — {位置} — PoC：{簡短說明}
2. [高] {弱點類型} — {位置} — PoC：{簡短說明}
3. ...

每個發現都包含可重現的概念驗證漏洞利用。

重要：Shannon 的「無漏洞利用，無報告」政策意味著每個發現都有可運作的 PoC。 但提醒使用者 LLM 生成的內容需要人工審查。

---

實用指令

檢查狀態

cd "$SHANNON_HOME" && ./shannon workspaces

檢視日誌

cd "$SHANNON_HOME" && ./shannon logs ID={workflow-id}

停止滲透測試

cd "$SHANNON_HOME" && ./shannon stop

停止並清除所有資料

# 破壞性操作——先與使用者確認
cd "$SHANNON_HOME" && ./shannon stop CLEAN=true

恢復先前的工作區

cd "$SHANNON_HOME" && ./shannon start URL={URL} REPO={REPO} WORKSPACE={name}

---

針對本機應用程式

如果使用者的應用程式在本機主機上執行，說明：

Shannon 在 Docker 內部執行。要連線到你的本機應用程式：
├─ 使用 http://host.docker.internal:{PORT} 而非 http://localhost:{PORT}
├─ macOS/Windows：Docker Desktop 會自動處理
└─ Linux：在 docker run 中加入 --add-host=host.docker.internal:host-gateway

在指令中自動將 localhost URL 轉換為 host.docker.internal。

---

設定參考

環境變數

變數	必要	說明
ANTHROPIC_API_KEY	其中之一	直接 Anthropic API 金鑰
CLAUDE_CODE_OAUTH_TOKEN	必要	Anthropic OAuth 權杖
CLAUDE_CODE_USE_BEDROCK		設為 1 以使用 AWS Bedrock
CLAUDE_CODE_USE_VERTEX		設為 1 以使用 Google Vertex AI
CLAUDE_CODE_MAX_OUTPUT_TOKENS	建議	設為 64000
SHANNON_HOME	選用	Shannon 安裝目錄（預設：~/shannon）

YAML 設定選項

區段	欄位	說明
authentication.type	form / sso	登入方式
authentication.login_url	URL	登入頁面
authentication.credentials	物件	username、password、totp_secret
authentication.flow	字串	自然語言的登入說明
authentication.success_condition	物件	url_contains 或 element_present
rules.avoid	清單	要跳過的路徑/子網域
rules.focus	清單	要優先處理的路徑/子網域
pipeline.retry_preset	subscription	針對速率限制方案的延長退避
pipeline.max_concurrent_pipelines	1-5	平行代理程式數量（預設：5）

---

弱點涵蓋範圍

Shannon 測試 5 個 OWASP 類別中的 50 多種特定案例：

類別	範例
注入	SQL 注入、命令注入、SSTI、NoSQL 注入
XSS	反射型、儲存型、DOM 型、透過檔案上傳
SSRF	內部服務存取、雲端中繼資料、協定走私
認證缺陷	預設憑證、JWT 缺陷、Session 固定、MFA 繞過、CSRF
授權缺陷	IDOR、權限提升、路徑遍歷、強制瀏覽

---

整合的安全工具（隨 Docker 捆綁）

• Nmap — 連接埠掃描與服務偵測
• Subfinder — 子網域列舉
• WhatWeb — 網頁技術指紋辨識
• Schemathesis — 基於 API 綱要的模糊測試
• Chromium — 用於自動化漏洞利用的無頭瀏覽器（Playwright）

---

對話記憶

在本次對話的後續部分，記住：

• SHANNON_HOME：Shannon 安裝路徑
• TARGET_URL：正在測試的 URL
• REPO_NAME：原始碼資料夾名稱
• WORKSPACE：工作區名稱（如有）
• PENTEST_STATUS：執行中 / 已完成 / 已停止

當使用者提出後續問題時：

• 檢查滲透測試狀態並回報進度
• 從 audit-logs 讀取和解讀新的發現
• 協助修復發現的弱點，提供程式碼修正
• 說明 PoC 漏洞利用及其影響

---

安全性與權限

此技能的功能：

• 從 GitHub 將 Shannon 儲存庫複製/更新至 ~/shannon（或 $SHANNON_HOME）
• 從使用者的原始碼建立符號連結至 ~/shannon/repos/
• 透過 ./shannon CLI 啟動 Docker 容器（Temporal 伺服器、工作者、選用路由器）
• 從 ~/shannon/audit-logs/ 讀取滲透測試報告
• 選擇性地在 ~/shannon/configs/ 中建立 YAML 設定檔

Shannon 的功能（在 Docker 內部）：

• 對目標 URL 執行真實漏洞利用（SQL 注入、XSS、SSRF 等）
• 使用 Nmap、Subfinder、WhatWeb、Schemathesis 進行掃描
• 透過無頭 Chromium 自動化瀏覽器互動
• 將提示傳送至 Anthropic API（或 Bedrock/Vertex）進行推理
• 將報告寫入 audit-logs/ 目錄

此技能不會做的事：

• 未經使用者確認不會針對任何系統
• 不會儲存或傳輸 API 金鑰至設定的提供者之外
• 不會修改使用者的原始碼
• 除非明確指示（且會發出警告），否則不會存取正式系統
• 不會在沒有 Docker 的情況下執行——所有攻擊工具皆容器化

首次使用前請檢閱 Shannon 原始碼： https://github.com/KeygraphHQ/shannon