repo-security-scan

repo-security-scan 是做什麼的？

掃描目標儲存庫以找出高信號安全問題，並產生報告。

功能範圍（MVP）

• 機密掃描：使用 gitleaks（本地掃描；日誌中的機密會被遮罩）
• 相依性漏洞掃描：使用 osv-scanner（比對相依性與 OSV 資料庫）

輸出內容：

• report.md — 人類可讀的摘要
• summary.json — 機器可讀的摘要
• 原始工具輸出（gitleaks.json、osv.json）+ 日誌

為何選擇此技術組合（信號/雜訊比）

• gitleaks：預設值強大、速度快、容易透過 .gitleaks.toml / .gitleaksignore 抑制誤報。
• osv-scanner：透過 OSV 進行準確的相依性漏洞比對（生態系統支援廣泛，通常比各生態系統專屬的「audit」指令雜訊更低）。

（其他掃描器如 Semgrep/SAST 及語言專屬稽核工具可於日後透過明確的 --deep 模式加入，避免造成 CI 失敗的雜訊。）

安全性

• 唯讀掃描檔案。
• 不會上傳原始碼。
• gitleaks 輸出已遮罩（--redact），且報告會避免印出機密。
• osv-scanner 預設會使用網路查詢 OSV（也可能查詢 deps.dev 以取得套件中繼資料）。它傳送的是相依性中繼資料，而非原始碼。

使用方式

本機執行

從此儲存庫執行：

# 掃描當前儲存庫，輸出寫入 .repo-security-scan/out
bash scripts/repo-security-scan/scan.sh --repo .

# 掃描另一個儲存庫
bash scripts/repo-security-scan/scan.sh --repo /path/to/target --out /tmp/repo-security-scan-out

# 檢視報告
cat .repo-security-scan/out/report.md

示範

bash scripts/demo.sh            # 掃描此儲存庫
bash scripts/demo.sh /path/repo # 掃描目標儲存庫

輸出內容

在輸出目錄（預設：<skill-suite>/.repo-security-scan/out）中：

• report.md
• summary.json
• gitleaks.json、gitleaks.log
• osv.json、osv.log

退出碼：

• 0 無發現結果
• 1 偵測到發現結果
• 2 掃描器錯誤（缺少工具、執行失敗）

設定 / 允許清單

掃描特定專案時，建議使用儲存庫本機的設定：

• gitleaks：
  • <repo>/.gitleaks.toml
  • <repo>/.gitleaksignore
• osv-scanner：
  • <repo>/osv-scanner.toml（僅套用至該目錄）

此技能套件亦包含保守的預設值，位於：

• .repo-security-scan/gitleaks.toml
• .repo-security-scan/.gitleaksignore
• .repo-security-scan/osv-scanner.toml

若要強制指定某個 osv-scanner 設定檔：

bash scripts/repo-security-scan/scan.sh --repo /path/repo --osv-config /path/to/osv-scanner.toml

安裝必要條件

• macOS：
  • brew install gitleaks osv-scanner jq
• Ubuntu：
  • sudo apt-get update && sudo apt-get install -y jq
  • 從 releases 安裝 gitleaks 與 osv-scanner，或透過 go install 編譯。