管理工作階段及匯出報表

CodeMender 會將每次掃描、驗證和修復嘗試，追蹤為由本機 SQLite 資料庫 (state.db) 支援的有狀態工作階段。您可以檢查進行中的工作階段、繼續執行暫停的工作，以及匯出詳細發現項目報表。

工作階段管理

CodeMender CLI 會在本機維護有狀態的執行工作階段，方便您追蹤進行中的工作、繼續執行中斷的工作流程，以及匯出安全性報告。

列出目前和過去的工作階段

執行下列指令，列出所有工作階段、其狀態 (RUNNING、WAITING_FOR_TOOL、COMPLETED、FAILED、CANCELLED) 和目標路徑：

cm session list

繼續中斷的工作階段

如果工作階段因網路中斷或步驟失敗而暫停，請從最新檢查點階段繼續執行：

cm session resume SESSION_ID

您可以將 --yes (-y)、--sandbox、--allow-all-paths、--allow-all-commands 和 --bypass-warning 傳遞至 cm session resume，控制恢復執行的確認提示、沙箱機制和政策邊界。

取消執行中的工作階段

如要終止進行中的工作階段，並停止後端代理運算執行作業，請按照下列步驟操作：

cm session cancel SESSION_ID

查看報表及匯出修補程式

使用 cm report 顯示工作階段發現項目、驗證狀態和修補程式詳細資料。

輸出格式

終端機資料表 (預設)

發現項目摘要清單。

cm report

HTML 報表

生成格式化的 HTML 報表。使用 --open (或 -o) 即可在預設瀏覽器中自動啟動。

cm report --format html --open

Markdown

產生 GitHub 樣式的 Markdown 報表。

cm report --format md

JSON

將所有工作階段發現項目詳細資料匯出為原始 JSON。

cm report --format json

SARIF

以標準 SARIF 格式 (v2.1.0) 匯出發現項目，以便與其他安全性工具整合。

cm report --format sarif

篩選及排序旗標

  • 顯示建議的程式碼修補程式 (--patches)：在報告中加入生成修正內容的完整統一差異。 bash cm report --patches
  • 依嚴重程度篩選 (--severity)：查看符合特定等級 (CRITICAL、HIGH、MEDIUM、LOW) 的發現項目。 bash cm report --severity HIGH
  • 依狀態篩選 (--status)：查看符合特定狀態 (OPEN、FIXED、DISMISSED、REOPENED) 的發現項目。 bash cm report --status OPEN
  • 依工作階段篩選 (--session)：查看特定工作階段 ID 前置字元的發現項目。
    cm report --session SESSION_ID_PREFIX
  • 顯示代理構件 (--artifacts)：包含代理產生的執行構件路徑 (例如記錄、漏洞利用指令碼)。 bash cm report --artifacts
  • 排序發現項目 (--sort)：依 severity (預設) 或 time 排序結果。bash cm report --sort time
  • 依發現項目 ID 篩選：傳遞特定發現項目 ID (或前置字元) 做為位置引數，即可查看單一發現項目的詳細資料。
    cm report FINDING_ID_PREFIX

安全漏洞發現項目狀態

CodeMender 會追蹤下列安全漏洞狀態的發現項目：

  • OPEN
    • 說明：掃描期間已成功偵測到安全漏洞 (或從第三方工具匯入)，但尚未驗證、修補或標示為無效。
    • 處理方式：這是新發現安全漏洞的初始狀態。處於 OPEN 狀態的安全漏洞會主動排入佇列，等待驗證 (cm verify) 或修補 (cm fix)。
  • FIXED
    • 意義：CodeMender 已生成安全漏洞修補程式、將差異套用至本機程式碼集，並成功編譯及執行驗證測試，證明安全漏洞已無法利用。
    • 處理方式：確認修補程式可解決問題，且不會破壞現有程式碼邏輯後，CodeMender 會將發現項目轉換為 FIXED。除非日後的掃描偵測到迴歸，否則會一直保持這個狀態。
  • DISMISSED
    • 說明：安全漏洞已標示為無效，原因可能是判定為誤判、已修正，或可信度不足，無法確認是否可遭利用 (包括在導入期間提供專案威脅模型的情況)。
    • 處理方式：將項目標示為 DISMISSED 後，系統就不會再發出快訊，並會使用 cm report --status OPEN 從有效的 CLI 輸出內容中排除發現項目。對已關閉的發現項目重新執行 cm verify，會重新檢查或還原已關閉的項目。
  • REOPENED
    • 意義：先前標示為 FIXED 或 DISMISSED 的安全漏洞，在後續的程式碼集掃描中再次偵測到。
    • 處理方式：這個狀態表示發生迴歸 (例如錯誤的 git 合併作業還原了修補程式)，或緩解策略失敗。系統會標記問題，要求立即重新評估，並要求開發人員審查修補程序。

安全漏洞嚴重性等級

CodeMender 會將發現項目分為下列嚴重性等級：

  • CRITICAL
    • 說明：安全漏洞會對應用程式或基礎架構造成立即且嚴重的風險，可能導致整個系統遭駭。
    • 為何歸類為「重大」：符合高後果影響門檻 (例如遠端執行程式碼或根層級寫入)，可直接從不受信任的邊界存取，不需任何先決條件，且有高信賴度的汙點流程分析或在 CodeMender 沙箱中執行的驗證概念驗證 (PoC) 做為依據。
  • HIGH
    • 說明：這個安全漏洞代表嚴重的安全缺陷，可能導致未經授權的系統控制、提權或重大資料暴露，但需要特定條件才能執行。
    • 為何歸類為「高」：雖然漏洞遭利用的影響很大 (例如任意讀取資料庫或管理員劫持)，但漏洞利用難度稍高。攻擊者可能需要具備標準使用者驗證、依賴特定系統設定，或需要高度精確的動作鏈。
  • MEDIUM
    • 說明：安全漏洞會帶來中等風險，通常會導致受限資料外洩或局部中斷，但對主機系統的風險較低。
    • 歸類為「中」的原因：這類漏洞利用行為受到可連線能力或複雜性的嚴格限制。通常需要使用者主動互動 (例如點選惡意連結)、高權限或複雜條件，才能繞過防禦層，且最終受影響的範圍有限。
  • LOW
    • 意義：發現項目代表輕微的安全風險，或一般缺乏縱深防禦衛生，本身不會造成立即威脅。
    • 歸類為「低」的原因：可利用性極低或影響極小。攻擊者通常會利用這項發現結果進行偵察或設定指紋，而非直接入侵，且無法用於執行任意程式碼或竊取機密應用程式資料。

追蹤權杖用量

CodeMender 會在本機的 ~/.codemender/logs/sessions/ 下方，寫入每次叫用的工作階段記錄。使用 cm stats 檢查離線權杖用量、快取命中率、輪詢次數，以及各指令或個別工作階段的執行時間長度，不必發出後端呼叫。

  • Summarize recent activity (--since)：查看最近一段時間 (預設為 168h，即 7 天) 內，依指令類型分組的權杖用量。bash cm stats cm stats --since 24h
  • 檢查特定工作階段 (--session)：查看工作階段 ID 或不重複工作階段 ID 前置字串的每輪權杖用量，包括多工作站 cm find --deep 和 cm find --diff 執行作業。
    cm stats --session SESSION_ID_PREFIX
  • 匯出 JSON (--json 和 --jsonl)：使用 --json 發出縮排 JSON，或使用 --jsonl 發出單行 JSON，以便擷取結構化記錄。JSON 輸出內容包含 model (或 models，如果有多個模型) 和 team_id (或 team_ids，如果匯總多個團隊)。
    cm stats --json
cm stats --jsonl
cm stats --session SESSION_ID_PREFIX --jsonl
  • 團隊屬性使用方式 (--team-id 或 CM_TEAM_ID)：使用 --team-id 旗標、CM_TEAM_ID 環境變數或 ~/.codemender/config.yaml 中的 team_id 執行掃描或修正時，請設定團隊 ID (1 到 63 個字元，符合 [A-Za-z0-9._-])。如果執行工作階段時未設定團隊，cm stats JSON 輸出內容中就不會歸因於任何團隊；如果查詢的時間範圍內沒有工作階段記錄，--team-id、CM_TEAM_ID 或 config.yaml 會提供頂層 team_id 標籤。
    CM_TEAM_ID=TEAM_ID cm find .
cm stats --jsonl

如果 Cloud Run 工作和 Cloud Build 步驟不會保留本機記錄檔，請參閱「將權杖遙測資料匯出至 Cloud Logging」。

收集診斷資料供支援團隊使用

如果 CodeMender 發生問題，請執行 cm support-bundle，將支援團隊所需的診斷資料收集到單一 .tar.gz 封存檔，再與支援團隊聯絡。這個指令會讀取本機檔案，並檢查憑證、設定和 CodeMender 連線。不會上傳任何內容。請檢查封存檔，並附加到客服案件。

如要收集特定工作階段的資料，請傳遞其 ID 或 ID 前置字元。如要找出工作階段 ID，請執行 cm session list。你可以重複--session：

cm support-bundle --session SESSION_ID

如果沒有 --session，指令會收集過去 72 小時內的活動。如要變更視窗，請使用 --since：

cm support-bundle --since 24h

這個指令會將 cm-support-bundle-TIMESTAMP.tar.gz 寫入目前的目錄，並輸出其路徑。如要選擇路徑，請使用 --output (或 -o)。

封存檔案內容

根據預設，封存檔會排除原始碼、差異、工具輸入和輸出內容。其中包含下列項目：

  • CLI 版本、作業系統，以及收集的資料清單。
  • CM_* 環境變數、專案和 Proxy 設定。
  • 憑證、設定和連線檢查的結果。
  • 設定檔和指令政策。
  • 各所選工作階段的狀態、模型和目標。
  • 每輪對話的時間、詞元用量，以及工具呼叫的名稱和時間長度。

工作階段資料仍可能包含檔案和目錄路徑、各 cm 指令的引數、發現項目標題和工具錯誤訊息。

如果支援團隊要求提供更多詳細資料，請新增 --include-content。這項作業也會收集發現項目、生成的修補程式和 CLI 偵錯記錄檔，其中記錄了每次工具呼叫的引數。這些檔案可能包含存放區的原始碼，因此請先檢查封存檔，再與他人分享。

cm support-bundle --session SESSION_ID --include-content

無論採用哪種模式，指令都會遮蓋存取權杖、API 金鑰、私密金鑰、授權標頭和密碼欄位。

如要略過憑證、設定和連線能力檢查 (例如在沒有網路存取權的情況下執行指令)，請使用 --skip-health。

Workspace 維護

如要重設本機狀態追蹤檔案，並清除暫時執行快取，請執行下列指令：

cm clean