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)。