CodeMender 尋找模式

CodeMender 透過 cm find 指令提供三種不同的掃描模式。每個模式都適用於軟體開發生命週期的特定階段，並兼顧速度、範圍和深度。

比較尋找模式

下表比較三種 cm find 掃描模式：

模式 指令 目標範圍 一般執行時間 適用情境
標準掃描 cm find PATH 指定目錄 中等執行階段 本機開發人員探索、快速檢查、探索性審查
差異掃描 cm find PATH --diff[=REF] 修改過的檔案和依附元件檔案 (例如呼叫者和被呼叫者) 執行階段速度快 提取要求 CI/CD 管道 (GitHub Actions、Cloud Build)、 預先提交勾點
深度掃描 cm find PATH --deep 整個存放區 執行時間較長 定期稽核、發布準備、法規遵循認證 (SOC 2、ISO)

標準掃描 (預設)

執行 cm find 時，如果沒有提供其他掃描標記，系統會預設使用標準掃描模式。這項工具會對指定目標目錄執行單一工作階段的自主掃描。掃描期間，CodeMender 會找出來源檔案、根據安全漏洞模式排定優先順序、執行初步安全性分析，並回報依嚴重程度和類型分組的潛在安全漏洞。

以下範例說明如何對目標目錄執行標準掃描：

# Scan a directory using the default model
cm find ./src

# Scan with a specific Gemini model
cm find ./src --model gemini-3.8-flash

優勢

標準掃描功能無須設定，也不需要額外標記或參數。這項模型兼顧速度和涵蓋範圍，執行時間適中，且使用的權杖和運算資源最少，因此適合日常開發工作，經濟實惠。

缺點和限制

標準掃描對大型程式碼集的召回率較低，而且可能不會探索大型多套件企業存放區中的每個檔案，因為這類掃描是在單一工作階段環境中運作。此外，這類工具主要著重於個別檔案中的本機模式，因此跨套件分析能力有限，可能會遺漏跨遠端套件的漏洞。

使用時機

在下列情況下使用標準掃描：

  • 在修訂變更前，先在本機執行掃描，即可在本地開發期間快速取得意見回饋。
  • 檢查新複製的存放區或小型專案，初步評估其資安態勢。
  • 調查潛在問題時，請檢查特定子目錄或模組。

差異掃描

差異掃描會檢查修改和新增的檔案，並著重於變更的確切行範圍 (差異區塊)，對提取要求工作流程和 CI/CD 管道執行 Git 差異分析。除了檢查變更的程式碼行，還會執行影響分析，找出存放區中未經修改，但會呼叫、匯入或依附於修改後函式和符號的檔案。這有助於確保在一個檔案中變更合約或函式簽章時，不會在依附檔案中引入安全漏洞。

掃描期間，CodeMender 會自動隔離未修改程式碼中先前存在的安全漏洞，避免舊版問題導致掃描失敗或封鎖提取要求。接著，系統會根據 --fail-on 政策評估發現項目，並以表格、JSON 或 SARIF v2.1.0 格式輸出結果。

以下範例示範如何針對工作副本變更、暫存變更或目標分支執行差異掃描：

# Scan working copy changes versus HEAD
cm find . --diff

# Scan staged changes only (pre-commit)
cm find . --diff --staged

# Scan a pull request branch against the main branch in CI/CD
cm find . --diff=origin/main --format=sarif --output=results.sarif \
    --fail-on=CRITICAL,HIGH

如需端對端管道設定，請參閱「整合 CI/CD」。

優勢

差異掃描快速且具決定性，通常會在 2 分鐘內完成，以縮短 CI/CD 管道的執行時間。與只檢查變更行的差異掃描器不同，--diff 會檢查呼叫端和被呼叫端的關係，以偵測跨檔案的安全回歸和合約違規。由於這項功能會隱藏未變更程式碼中的發現項目，因此掃描作業只會封鎖因變更而導入或受影響的問題，避免產生大量報告和不必要的建構失敗。差異掃描也會發出 SARIF v2.1.0，直接整合至 GitHub 程式碼掃描註解和 Cloud Build 資訊主頁。

缺點和限制

差異掃描只會分析提取要求受影響區域內的程式碼，不會在存放區未觸及的部分中尋找先前存在的安全漏洞。此外，您也需要具備可存取目標基礎參照的 Git 存放區。

使用時機

在下列情況下，請使用差異掃描：

  • 在 CI/CD 管道 (例如 GitHub Actions、Cloud Build、GitLab CI 或 Jenkins) 中，對每項提取要求執行自動檢查。
  • 將程式碼推送至遠端存放區之前，請先確認預先提交或預先推送掛鉤中的本機變更是否乾淨。
  • 確認發布分支之間的合併不會導致回歸。

深度掃描

深度掃描是一種詳盡的掃描模式，專為整個存放區的全面安全性稽核而設計。這項工具會使用平行工作站 (透過 --deep-workers 設定，預設為 8，並支援 1 到 16 範圍) 同時稽核整個存放區的來源檔案。發現候選發現項目後，工具會根據周圍的程式碼環境驗證並佐證這些結果，以濾除偽陽性情形，再回報結果。

以下範例說明如何對存放區執行深度掃描：

# Run an exhaustive deep scan across the entire repository
cm find . --deep

# Tune concurrency and use the cyber-specialized security model
cm find . --deep --deep-workers=8 --model=gemini-3.8-flash-cyber

優勢

深度掃描可在大規模企業程式碼集中，提供高檢索率和全面的安全漏洞偵測功能，成效優於單一工作階段掃描，並使用自動驗證功能維持高精確度。這項工具支援多種語言，且不受平台限制，可在 Gemini 支援的所有語言中運作，不需要特定語言的編譯器、建構設定或文法檔案。此外，這項功能會著重分析正式環境程式碼，並盡量減少非正式環境檔案的運算和權杖消耗量，藉此最佳化資源用量。

缺點和限制

請勿使用深度掃描做為會阻斷提取要求的同步檢查。深層掃描會對整個存放區進行全面分析。因此，與標準或差異掃描相比，這類掃描需要更長的執行時間和更高的權杖費用。

使用時機

在下列情況下，請使用深度掃描：

  • 每晚或每週對所有正式環境存放區執行排定的安全性稽核。
  • 在發布主要版本或部署至正式環境前，請先進行全面的預先發布安全性稽核。
  • 為 SOC 2、ISO 27001、FedRAMP 或 PCI-DSS 法規遵循和認證審查產生稽核證據。
  • 將新程式碼集加入 CodeMender 時，請建立初始安全性基準。

選擇尋找模式

請參閱下表，為工作流程選擇合適的掃描模式：

工作流程或環境 用途和目標 建議模式 範例指令
本機終端機 快速探索或確認特定模組 標準掃描 cm find ./src
本機終端機 推送前，對暫存變更進行預先提交檢查 差異掃描 cm find . --diff --staged
CI/CD 管道 針對變更的程式碼和呼叫端，自動執行提取要求閘道 差異掃描 cm find . --diff=origin/main --fail-on=CRITICAL,HIGH
排定的管道或稽核作業 每晚稽核、預先發布閘道、SOC 2 法規遵循 深度掃描 cm find . --deep --deep-workers=8

依模式分類的指令旗標參考資料

下表說明各掃描模式支援的指令列旗標。

常見旗標 (所有模式)

下列旗標適用於所有 cm find 掃描模式：

標記 預設 說明
-c, --context TEXT "" 引導掃描代理程式的其他背景資訊，例如架構附註。
--model MODEL_NAME gemini-3.8-flash 要使用的 Gemini 模型 (gemini-3.8-flash、 gemini-3.8-flash-cyber)。
-y, --yes false 略過所有互動式確認提示。
--unrestricted false 關閉檔案系統沙箱。

差異掃描旗標

下列標記可設定 cm find --diff 掃描：

標記 預設 說明
--diff[=REF] 關閉 針對目標參照啟用差異模式，例如 origin/main 或 HEAD~1。如果沒有 REF，則會與 HEAD 比較。無法與 --deep 搭配使用。
--staged 關閉 僅將差異範圍設為暫存索引 (git diff --cached)。 必須使用 --diff。
--diff-depth DEPTH 1 影響分析的遍歷深度 (1 到 3，預設為 1 個躍點)。
--diff-workers COUNT 4 提取要求稽核工作的並行工作站數量 (1 到 16)。
--diff-max-neighbors COUNT 10 要檢查的依附呼叫端或被呼叫端檔案數量上限。
--fail-on SEVERITIES CRITICAL,HIGH 以半形逗號分隔的嚴重程度，導致 cm find 以代碼 1 結束。
--fail-on-truncation 關閉 如果鄰居探索超出上限，請以代碼 1 結束。
--format FORMAT table 輸出格式：table、json 或 sarif。
--output FILE 標準輸出內容 將報表寫入檔案，而非標準輸出。

深度掃描旗標

下列標記可設定 cm find --deep 掃描：

標記 預設 說明
--deep false 啟用整個存放區的詳盡深度掃描。無法與 --diff 搭配使用。
--deep-workers COUNT 8 深度掃描的並行工作站數量 (1 到 16)。