danoszz/penthera

Penthera Security Scanner

輕量級安全掃描器，用於 URL、本地儲存庫及（macOS）機器審計。執行任何掃描前，務必先通過授權閘門。

重要：授權閘門

在確認授權之前，請勿執行 Penthera。

在每次工作階段的第一次掃描前，要求使用者確認以下其中一項：

1. 使用者擁有該目標（應用程式、伺服器、專案）。
2. 使用者擁有來自系統擁有者的書面授權。
3. 目標是 localhost 或使用者控制的私人實驗環境。

如果使用者要求掃描第三方網域（例如 google.com、example.com），但未宣稱擁有權或授權，請停止並拒絕。如有疑慮，請勿掃描。

完整政策請參閱 references/authorization.md。

事前檢查

在第一次掃描前執行：

bash skills/penthera/scripts/preflight.sh [URL]

從儲存庫根目錄執行。傳入目標 URL 以針對非 localhost 目標發出警告。請先修正任何錯誤再繼續。

解析 CLI 命令

使用可用的指令：

penthera --version          # 執行 npm link 後
node bin/penthera.js --version   # 從儲存庫根目錄

以下範例均使用 penthera；必要時請替換為 node bin/penthera.js。

決策樹

使用者意圖	命令模式
初次使用 / 不確定	penthera（互動式精靈 — TTY）或 penthera-scan
掃描即時 URL	penthera <url> --profile standard -o reports/scan.json
僅掃描儲存庫（機密、路由）	penthera --repo . -o reports/repo-scan.json
URL + 原始碼合併掃描	penthera <url> --repo . -o reports/scan.json --sarif reports/scan.sarif
與前次掃描比較	penthera <url> -o reports/scan.json --baseline reports/previous.json
已認證端點	加入 --auth-cookie 或 --auth-bearer / PENTHERA_* 環境變數
macOS 機器審計	penthera --machine

預設安全行為

• 除非使用者明確要求更深入的測試，否則一律使用 --profile standard。
• 將報告寫入 reports/（已加入 .gitignore），絕不寫入 skills/penthera/ 內部。
• 掃描完成後，閱讀附帶的 .md 報告，並依嚴重性摘要發現結果，同時提出修復建議。

破壞性模式閘門

下列旗標會發送攻擊酬載。使用前需取得使用者明確確認：

• --deep — SQLi、SSTI、SSRF、XSS、CMDi 探測
• --fuzz — 基於屬性的 API 模糊測試
• --all — 啟用偵察 + deep + fuzz
• --profile deep — 最大涵蓋範圍

如果使用者要求「完整滲透測試」或「深度掃描」，請確認他們擁有該目標並接受基於酬載的測試。

工作流程 1：上線前審計

觸發條件：「掃描我的暫存應用程式」、「部署前安全審計」、「檢查我的應用程式漏洞」

1. 確認授權（請見上方閘門）。
2. 執行事前檢查。
3. 執行：

mkdir -p reports
penthera https://staging.example.com --profile standard -o reports/scan.json

4. 閱讀 reports/scan.md — 摘要嚴重/高/中風險發現。
5. 針對每個發現建議具體修復方式。
6. 注意退出碼：0 = 無嚴重/高風險；1 = 發現嚴重/高風險；2 = 掃描失敗。

工作流程 2：儲存庫 + 即時合併掃描

觸發條件：「掃描我的 Next.js 應用程式和暫存環境」、「黑箱和白箱掃描」

1. 確認 URL 的授權。
2. 使用 URL 執行事前檢查。
3. 執行：

mkdir -p reports
penthera https://staging.example.com --repo . --profile standard \
  -o reports/scan.json --sarif reports/scan.sarif

4. 摘要 URL 發現（標頭、TLS、CORS、認證）和儲存庫發現（機密、API 路由、信任邊界）。
5. 提供透過 GitHub Actions 上傳 SARIF 的選項（請參閱 references/output-and-ci.md）。

工作流程 3：CI / 基線回歸

觸發條件：「與上次掃描比較」、「僅顯示新發現」、「回歸檢查」

1. 確認授權，並確認 reports/previous.json 存在（或要求使用者提供基線路徑）。
2. 執行：

mkdir -p reports
penthera https://staging.example.com --profile standard \
  -o reports/scan.json --baseline reports/previous.json

3. 報告：新發現數量、已解決數量、未變更數量（掃描期間會輸出到 stderr）。
4. 摘要重點僅放在新發現上。

已認證掃描

只有在通過授權閘門後才能進行：

# Bearer token
PENTHERA_BEARER=eyJ... penthera https://myapp.com --profile standard -o reports/scan.json

# Session cookie
penthera https://myapp.com --auth-cookie "session=abc123" -o reports/scan.json

# 明確旗標
penthera https://myapp.com --auth-bearer "eyJ..." -o reports/scan.json

環境變數：PENTHERA_BEARER、PENTHERA_COOKIE。

僅儲存庫機密掃描

觸發條件：「尋找寫死的機密」、「掃描此儲存庫中的金鑰」

本地儲存庫分析無需 URL 授權：

penthera --repo . -o reports/repo-scan.json

摘要機密發現；提醒使用者輪換任何已暴露的憑證。

範例

範例 1：本地主機快速檢查

使用者：「掃描我 localhost 上 port 3000 的應用程式」

操作：

1. 確認 localhost — 授權已滿足。
2. bash skills/penthera/scripts/preflight.sh http://localhost:3000
3. penthera http://localhost:3000 --profile quick -o reports/scan.json
4. 摘要 reports/scan.md。

範例 2：部署前暫存環境檢查

使用者：「在我們部署前審計 staging.myapp.com」

操作：

1. 詢問：「你是否擁有 staging.myapp.com 或擁有其書面授權？」
2. 確認後，使用標準 profile 執行掃描，輸出 JSON 和 Markdown 報告。
3. 先列出嚴重/高風險項目，並附上補救步驟。

範例 3：未經授權的目標（必須拒絕）

使用者：「掃描 google.com 的漏洞」

操作：

1. 不要執行 Penthera。
2. 說明未經授權掃描第三方系統是不允許的。
3. 提議改為掃描他們自己的應用程式或 localhost。

請勿將此技能用於

• 一般的程式碼撰寫協助、天氣查詢或無關任務
• 掃描使用者不擁有或無權測試的系統
• 惡意利用或資料竊取

其他資源

• Profile 和旗標：references/profiles-and-flags.md
• 輸出格式和 CI：references/output-and-ci.md
• 疑難排解：references/troubleshooting.md
• 授權政策：references/authorization.md