CodeMender 尋找模式

CodeMender 透過 cm find 指令提供三種不同的掃描模式。每種模式都專為軟體開發生命週期的特定階段設計，可平衡速度、範圍和深度。

比較尋找模式

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

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

深度掃描 (預設)

執行 cm find 時，如未提供其他掃描旗標，預設模式為深度掃描 (為提供回溯相容性，系統也支援 --deep 旗標)。這項模式會進行詳盡掃描，專為全面安全性稽核而設計。它會使用平行工作站 (以 --deep-workers 設定，預設為 8，支援 1 到 16 的範圍)，同時稽核目標目錄或存放區中的來源檔案。發現候選結果時，會根據周圍的程式碼背景資訊進行驗證和佐證，在回報結果前篩除偽陽性。

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

# Run an exhaustive deep scan across the repository (default mode)
cm find .

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

優勢

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

缺點和限制

請勿將深度掃描做為同步檢查，以免提取要求遭到封鎖。深度掃描會逐一徹底分析檔案，因此，與快速或差異掃描相比，這類掃描需要更長的執行時間和更高的權杖費用。

使用時機

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

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

差異掃描

差異掃描會檢查修改和新增的檔案，並著重於確切變更的行範圍 (差異區塊)，對提取要求工作流程和 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 存放區。

使用時機

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

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

快速掃描

快速掃描 (cm find --quick) 會對指定目標目錄執行單一工作階段自主掃描，而非預設的並行逐一檔案深度掃描。掃描期間，CodeMender 會找出來源檔案，並根據安全漏洞模式排定優先順序、執行初步安全性分析，以及回報潛在安全漏洞 (依嚴重程度和類型分組)。

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

# Run a single-session quick scan on a directory using the default model
cm find ./src --quick

# Run a quick scan with a specific Gemini model
cm find ./src --quick --model gemini-3.8-flash

優勢

快速掃描可兼顧速度和涵蓋範圍，執行時間適中，且使用的權杖和運算資源比完整深度掃描少，因此在日常開發過程中，可快速進行探索式檢查，符合成本效益。

缺點和限制

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

使用時機

在下列情況下，請使用快速掃描：

  • 在本機電腦上執行快速掃描，在本機開發期間快速取得意見回饋。
  • 檢查新複製的存放區或小型專案，快速初步評估其資安態勢。
  • 快速檢查時，請檢查特定子目錄或模組。

選擇尋找模式

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

工作流程或環境 用途和目標 建議模式 範例指令
本機終端機 快速探索或確認特定模組 快速掃描 cm find ./src --quick
本機終端機 推送前，對暫存變更進行預先提交檢查 差異掃描 cm find . --diff --staged
CI/CD 管道 自動對變更的程式碼和呼叫端進行提取要求閘控 差異掃描 cm find . --diff=origin/main --fail-on=CRITICAL,HIGH
排定的管道或稽核作業 夜間稽核、預先發布版閘道、SOC 2 法規遵循 深度掃描 cm find . --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 略過互動式確認提示和自動更新檢查。 如果啟用 OS 層級沙箱，並採用預設網路隔離 (permissive-closed)，cm find 會以唯讀方式掛接工作區，並自動略過指令確認提示。
--sandbox true 在 OS 層級沙箱中執行指令 (例如 --sandbox=false 可停用)。在 cm find 中，沙箱會以唯讀方式掛接工作區。
--allow-all-paths false 停用工作區路徑邊界檢查 (與 --sandbox=false 搭配使用，可存取未掛接在沙箱內的主機路徑)。
--allow-all-commands false 停用這項執行的 command_policy.yaml 封鎖清單強制執行功能。
--include-hidden false 在檔案探索期間，納入隱藏的目錄和檔案 (開頭為 .)。

深度掃描旗標

下列旗標會設定預設 cm find (或 cm find --deep) 掃描作業：

標記 預設 說明
--deep true 執行詳盡的檔案深度掃描 (未傳遞模式旗標時的預設模式)。無法與 --diff 或 --quick 搭配使用。
--deep-workers COUNT 8 每項檔案深度掃描作業的並行 worker 數量 (1 到 16)。
--enable-bash false 在每個檔案的 --deep worker 中啟用殼層指令執行 (run_command) (或設定 CMOC_FIND_ENABLE_BASH=true)。快速掃描 (--quick) 和差異掃描 (--diff) 預設會啟用 run_command。

差異掃描旗標

下列旗標可用於設定 cm find --diff 掃描作業：

標記 預設 說明
--diff[=REF] 關閉 啟用目標參照的差異模式，例如 origin/main 或 HEAD~1。如果沒有 REF，則會與 HEAD 比較。無法與 --deep 或 --quick 搭配使用。
--staged 關閉 僅將差異範圍設為暫存索引 (git diff --cached)。 需要 --diff。
--diff-workers COUNT 4 提取要求稽核工作的並行 worker 數量 (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 --quick 掃描作業：

標記 預設 說明
--quick false 執行單一工作階段快速掃描，而非預設的並行逐一檔案深度掃描。無法與 --deep 或 --diff 搭配使用。