Nick2bad4u/Github-Security-CodeScanning-Alerts-Skill

GitHub 安全警示管理

總覽

當使用者要求檢視或管理 GitHub 儲存庫安全警示時使用此技能，包括：

• 程式碼掃描警示 (code scanning alerts)
• Dependabot 警示 (Dependabot alerts)
• Dependabot 惡意軟體警示 (Dependabot malware alerts)
• 密碼掃描警示 (secret scanning alerts)
• 密碼掃描警示位置 (secret scanning alert locations)
• 密碼掃描掃描歷史 (secret scanning scan history)
• 儲存庫安全設定總覽 (repository security settings overview)
• 跨儲存庫的原始 GitHub 安全 API 檢查 (raw GitHub security API inspection across repositories)
• 大規模警示匯出以供離線分級或報告工作流程 (bulk alert export for offline triage or reporting workflows)
• 大規模警示更新以利大量清理工作流程 (bulk alert mutation for high-volume cleanup workflows)

內建的輔助工具與儲存庫無關：

• 使用 --repo 指向任何本地檢出目錄 (local checkout)
• 讓它從 git remote 自動偵測 owner/repo 與 GitHub 主機 (GitHub host)
• 或明確傳入 --repository owner/repo
• 透過環境變數進行驗證，而非在指令列上放置 token
• 可選擇性地覆寫 API 或 Web 基礎 URL 以支援自訂環境

相容性

需要 Python 3。 直接使用 GitHub REST API，並透過環境變數（例如 GITHUB_TOKEN 或 GH_TOKEN）提供 token。 支援 GitHub.com 與標準的 GHES API 基礎 URL（從 git remote 推導），並提供原始 API 後備方案以處理尚未包裝的請求。

調用提示

當目標是本地檢出目錄時使用 repo，預設值為 .。 當自動偵測不足時，可使用選用的 repository、api_base_url、web_base_url 與 token_env 值。 常用指令包括：summary、export-alerts、bulk-update-alerts、repo-security-overview、list-code-scanning、show-code-scanning、update-code-scanning、list-dependabot、show-dependabot、update-dependabot、list-malware、show-malware、update-malware、list-secret-scanning、show-secret-scanning、update-secret-scanning、list-secret-locations、secret-scan-history 與 api-call。

安全模型

請勿將 GitHub token 貼入指令參數中。 除非使用者明確要求未遮罩的密碼值並確認暴露風險，否則不要使用 --show-secret-values。請優先使用已遮罩的警示中繼資料、密碼位置、有效性與解決狀態。如果需要未遮罩的輸出進行修復，請勿將密碼素材貼入聊天、議題評論、PR、提交、日誌或已儲存的報告中。

較佳模式：

$env:GITHUB_TOKEN = Get-Secret GITHUB_TOKEN -AsPlainText

如果儲存庫使用不同的環境變數名稱，請先匯出該變數，或透過 --token-env 傳遞變數名稱。

範例：

python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "."
python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --token-env GITHUB_TOKEN

共用的 CLI 選項

• repo：目標儲存庫檢出目錄內的路徑（預設 .）
• repository：可選的明確 owner/repo 覆蓋
• api_base_url：可選的明確 API 基礎 URL 覆蓋
• web_base_url：可選的明確 Web 基礎 URL 覆蓋（用於產生連結）
• token_env：可選的環境變數名稱（內含 token）；可重複以提供後備方案
• json：可選的機器可讀輸出旗標

關於惡意軟體警示的重要說明

GitHub 將惡意軟體發現結果顯示為 Dependabot 惡意軟體警示。

GitHub 並未提供獨立的儲存庫警示系列及其專屬的 REST 介面。因此，內建的輔助工具將惡意軟體視為 Dependabot 警示的已篩選子集，並將每個警示的諮詢 GHSA 與 GitHub Advisory Database 進行交叉比對，以識別類型為 malware 的諮詢。

這表示：

• list-malware、show-malware 與 update-malware 是基於 Dependabot 警示 API
• 惡意軟體分類在 GitHub.com 上最為強大，因為該處提供 Advisory Database 端點
• 如果目標主機上無法進行諮詢類型查詢，輔助工具會回報該狀態，而非默默猜測

快速入門

1. 檢查目前安全狀態

python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "."

2. 檢視儲存庫安全設定總覽

python "<path-to-skill>/scripts/manage_github_security_alerts.py" repo-security-overview --repo "."

2.5 匯出完整警示集以進行大量分級

python "<path-to-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json

3. 程式碼掃描清單範例

使用共用輸入 repo、repository、api_base_url、web_base_url、token_env 與 json，以及程式碼掃描篩選條件，例如 state、severity、tool_name、tool_guid、ref 與 pr。 輸出 code_scanning_alerts，格式為渲染文字或機器可讀的 JSON。

python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --severity high,error

3.5 大量關閉或重新開啟警示

python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface code-scanning --select-state open --target-state dismissed --dismissed-reason "false positive" --comment "Reviewed and intentionally dismissed." --limit 10 --dry-run --json

python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface dependabot --select-state open --target-state dismissed --dismissed-reason tolerable_risk --comment "Accepted until the next dependency refresh." --limit 25 --dry-run --json

python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface secret-scanning --select-state open --target-state resolved --resolution used_in_tests --limit 25 --dry-run --json

4. 關閉或重新開啟程式碼掃描警示

python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "False positive after manual review." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state open

5. Dependabot 清單範例

使用共用輸入 repo、repository、api_base_url、web_base_url、token_env 與 json，以及 Dependabot 篩選條件，例如 state、severity、ecosystem、package、manifest、has、assignee 與 scope。 輸出 dependabot_alerts，格式為渲染文字或機器可讀的 JSON。

python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --has patch

6. 關閉或重新開啟 Dependabot 警示

python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Accepted until next quarterly upgrade." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state open

7. 惡意軟體清單範例

使用共用輸入 repo、repository、api_base_url、web_base_url、token_env 與 json，以及基於 Dependabot 的惡意軟體篩選條件，例如 state、severity、ecosystem、package、manifest 與 has。 輸出 malware_alerts 以及任何來自諮詢類型分類的 lookup_failures。

python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --state open

8. 密碼掃描清單範例

使用共用輸入 repo、repository、api_base_url、web_base_url、token_env 與 json，以及密碼掃描篩選條件，例如 state、secret_type、resolution、assignee、validity 以及洩漏或多儲存庫旗標。 輸出 secret_scanning_alerts，密碼值預設為遮罩狀態。

python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open

密碼值預設為隱藏。除非使用者明確確認需要未遮罩的密碼輸出，否則請保持此設定。

9. 解決或重新開啟密碼掃描警示

python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Token revoked and rotated." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state open

10. 顯示密碼位置與掃描歷史

python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11
python "<path-to-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "."

11. 使用原始 API 後備方案處理尚未包裝的請求

python "<path-to-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/code-scanning/default-setup

工作流程

1. 安全地解決驗證問題。
   • 優先使用環境變數（例如 GITHUB_TOKEN）。
   • 如有需要，先從密碼管理器載入至環境變數。
   • 切勿在日誌或聊天輸出中列印 token。
2. 解析目標儲存庫。
   • 優先使用 --repo 並從 git remote 自動偵測。
   • 當本地檢出目錄不可用或非標準時，改為使用 --repository owner/repo。
3. 檢查目前的發現結果。
   • 先執行 summary。
   • 當需要更完整的多面向 JSON 快照以進行大量分級或外部報告時，請使用 export-alerts。
   • 針對您關心的警示系列，使用 list/show 指令。
   • 當問題涉及啟用狀態或可用的安全設定時，使用 repo-security-overview。
4. 分類發現結果。
   • 在適當情況下修復程式碼或依賴設定中的實際缺陷。
   • 僅在您有明確理由時才關閉警示。
   • 當先前的關閉或解決不再有效時，重新開啟警示。
   • 當儲存庫有數十或數百個已審查但誤分類且需要相同處理的警示時，請使用 bulk-update-alerts。
5. 謹慎套用變更。
   • 對於有風險的變更，優先使用 --dry-run。
   • 加入簡短且可操作的關閉或解決說明。
   • 請記住，寫入操作需要對應的 GitHub 權限。
6. 驗證變更後的狀態。
   • 重新執行相關的 list/show 指令。
   • 對於程式碼或依賴修復，如果您預期警示會自然消失，請等待下一次 GitHub 分析週期。

隨附資源

輔助腳本

scripts/manage_github_security_alerts.py 是一個與儲存庫無關的 GitHub 儲存庫安全警示輔助工具。

支援的指令：

• summary
• export-alerts
• bulk-update-alerts
• repo-security-overview
• list-code-scanning
• show-code-scanning
• update-code-scanning
• list-dependabot
• show-dependabot
• update-dependabot
• list-malware
• show-malware
• update-malware
• list-secret-scanning
• show-secret-scanning
• update-secret-scanning
• list-secret-locations
• secret-scan-history
• api-call

實作模組：

• github_security_api.py
• github_security_cli.py
• github_security_common.py
• github_security_operations.py
• github_security_render.py

範例：

python "<path-to-skill>/scripts/manage_github_security_alerts.py" summary --repo "." --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" export-alerts --repo "." --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" bulk-update-alerts --repo "." --surface code-scanning --select-state open --target-state dismissed --dismissed-reason "false positive" --comment "Reviewed and intentionally dismissed." --limit 10 --dry-run --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-code-scanning --repo "." --state open --per-page 100 --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-code-scanning --repo "." --alert 42 --state dismissed --dismissed-reason false_positive --comment "False positive after review." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-dependabot --repo "." --state open --ecosystem npm --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-malware --repo "." --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-dependabot --repo "." --alert 7 --state dismissed --dismissed-reason tolerable_risk --comment "Accepted temporarily." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-scanning --repo "." --state open --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" update-secret-scanning --repo "." --alert 11 --state resolved --resolution revoked --comment "Revoked and rotated." --dry-run
python "<path-to-skill>/scripts/manage_github_security_alerts.py" list-secret-locations --repo "." --alert 11 --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" secret-scan-history --repo "." --json
python "<path-to-skill>/scripts/manage_github_security_alerts.py" api-call --repo "." --endpoint /repos/OWNER/REPO/dependabot/alerts --query-param state=open --json