Cycode

官方

透過 SAST、SCA、機密與 IaC 掃描，使用 Cycode 提升開發生命週期中的安全性。

GitHub
99

你可以用 Cycode MCP 做什麼？

  • 掃描儲存庫路徑以尋找硬編碼密碼 — 要求助理在本地目錄上執行 cycode_secret_scan，以偵測暴露的憑證。
  • 檢查相依性是否有已知漏洞 — 針對專案路徑觸發 cycode_sca_scan，以識別有漏洞或不合規的開源套件。
  • 稽核基礎設施即程式碼檔案中的錯誤設定 — 在 Terraform 或 CloudFormation 目錄上使用 cycode_iac_scan，以揭露風險設定。
  • 審查原始碼中的安全缺陷 — 在程式碼庫上執行 cycode_sast_scan，以找出程式碼層級的弱點與品質問題。
  • 驗證 CLI 驗證與版本狀態 — 呼叫 cycode_status，以確認與 Cycode 的連線以及目前啟用的版本。

文件

Cycode CLI 使用者指南

MCP Toplist

Cycode 命令列介面（CLI）是一個可安裝在本機的應用程式，用於掃描您的儲存庫，以找出機密、基礎架構即程式碼（IaC）設定錯誤、軟體組成分析（SCA）漏洞，以及靜態應用程式安全測試（SAST）問題。

本指南將引導您完成安裝和使用。

目錄

  1. 先決條件
  2. 安裝
    1. 安裝 Cycode CLI
      1. 使用 Auth 命令
      2. 使用 Configure 命令
      3. 新增至環境變數
        1. 在 Unix/Linux 上
        2. 在 Windows 上
    2. 安裝 Pre-Commit Hook
  3. Cycode CLI 命令
  4. MCP 命令
    1. 啟動 MCP 伺服器
    2. 可用選項
    3. MCP 工具
    4. 使用範例
    5. 進階設定
  5. Platform 命令
    1. 探索命令
    2. 範例
    3. 注意事項與限制
  6. AI 防護措施
    1. AI 防護措施收集的資料
  7. Scan 命令
    1. 執行掃描
      1. 選項
        1. 嚴重性門檻
        2. 監控
        3. Cycode 報告
        4. 套件漏洞
        5. 授權合規
        6. 鎖定還原
        7. 錯誤時停止
      2. 儲存庫掃描
        1. 分支選項
      3. 路徑掃描
        1. Terraform Plan 掃描
      4. 提交歷史掃描
        1. 提交範圍選項（差異掃描）
      5. Pre-Commit 掃描
      6. Pre-Push 掃描
    2. 掃描結果
      1. 顯示/隱藏機密
      2. 軟失敗
      3. 掃描結果範例
        1. 機密結果範例
        2. IaC 結果範例
        3. SCA 結果範例
        4. SAST 結果範例
      4. 公司自訂修補指引
    3. 忽略掃描結果
      1. 忽略機密值
      2. 忽略機密 SHA 值
      3. 忽略路徑
      4. 忽略機密、IaC 或 SCA 規則
      5. 忽略套件
      6. 透過設定檔忽略
  8. Report 命令
    1. 產生 SBOM 報告
  9. Import 命令
  10. 掃描日誌
  11. 語法說明

先決條件

  • Cycode CLI 應用程式需要 Python 3.9 或更新版本。MCP 命令僅適用於 Python 3.10 及以上版本。如果您使用較舊的 Python 版本，此命令將不可用。
  • 使用 cycode auth 命令 透過 CLI 向 Cycode 進行驗證
    • 或者，您可以按照 服務帳戶權杖 和 個人存取權杖 頁面中詳細說明的步驟取得 Cycode Client ID 和 Client Secret Key，這些頁面包含取得這些值的詳細資訊。

安裝

以下安裝步驟適用於 Windows 和 UNIX / Linux 作業系統。

[!NOTE] 以下步驟假設使用 python3 和 pip3 來執行 Python 相關命令；但是，某些系統可能會改用 python 和 pip 命令，具體取決於您的 Python 環境設定。

安裝 Cycode CLI

若要在本機安裝 Cycode CLI 應用程式，請執行以下步驟：

  1. 開啟您的命令列或終端機應用程式。

  2. 執行下列其中一個命令：

    • 若要從 PyPI 安裝：

      pip3 install cycode

    • 若要從 Homebrew 安裝：

      brew install cycode

    • 若要從 GitHub Releases 安裝，請瀏覽並下載適用於您的作業系統和架構的可執行檔，然後執行以下命令：

    cd /path/to/downloaded/cycode-cli
chmod +x cycode
./cycode

  3. 最後驗證 CLI。有三種方法可以設定 Cycode 用戶端 ID 和憑證（用戶端密碼或 OIDC ID 權杖）：

使用 Auth 命令

[!NOTE] 這是設定本機與 Cycode CLI 驗證的建議方法。

  1. 在您的終端機/命令列視窗中輸入以下命令：

    cycode auth

  2. 將出現一個瀏覽器視窗，要求您登入 Cycode（如下所示）：

    Cycode login

  3. 在此頁面輸入您的登入憑證並登入。

  4. 您最終將被帶到以下頁面，系統會要求您選擇要授權 Cycode 的業務群組（如果適用）：

    authorize CLI

    [!NOTE] 這將是使用 Cycode CLI 驗證的預設方法。

  5. 按一下允許按鈕，以在選取的業務群組上授權 Cycode CLI。

    allow CLI

  6. 完成後，如果成功選取，您將看到以下畫面：

    successfully auth

  7. 在終端機/命令列畫面中，當您離開瀏覽器視窗時，您將看到以下內容：

    Successfully logged into cycode

使用 Configure 命令

[!NOTE] 如果您已透過 Linux 或 Windows 環境變數設定 Cycode Client ID 和 Client Secret，這些憑證將優先於此方法。

  1. 在您的終端機/命令列視窗中輸入以下命令：

    cycode configure

  2. 輸入您的 Cycode API URL 值（您可以留空以使用預設值）。

    Cycode API URL [https://api.cycode.com]: https://api.onpremise.com

  3. 輸入您的 Cycode APP URL 值（您可以留空以使用預設值）。

    Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com

  4. 輸入您的 Cycode Client ID 值。

    Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d

  5. 輸入您的 Cycode Client Secret 值（如果您打算使用 OIDC ID 權杖，請略過）。

    Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e

  6. 輸入您的 Cycode OIDC ID 權杖值（選用）。

    Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

  7. 如果值輸入成功，您將看到以下訊息：

    Successfully configured CLI credentials!

    或/和

    Successfully configured Cycode URLs!

如果您進入使用者資料夾下的 .cycode 資料夾，您會發現這些憑證已建立並放置在該資料夾中的 credentials.yaml 檔案中。 URL 已放置在該資料夾中的 config.yaml 檔案中。

新增至環境變數

在 Unix/Linux 上：

export CYCODE_CLIENT_ID={your Cycode ID}

和

export CYCODE_CLIENT_SECRET={your Cycode Secret Key}

如果您的組織使用 OIDC 驗證，您可以改為提供 ID 權杖（或額外提供）：

export CYCODE_ID_TOKEN={your Cycode OIDC ID token}

在 Windows 上

  1. 從控制台瀏覽至系統選單：

    system menu

  2. 接著，按一下進階系統設定：

    advanced system setting

  3. 在開啟的系統內容視窗中，按一下環境變數按鈕：

    environments variables button

  4. 建立 CYCODE_CLIENT_ID 和 CYCODE_CLIENT_SECRET 變數，其值分別對應您的 ID 和 Secret Key。如果您透過 OIDC 驗證，也請新增 CYCODE_ID_TOKEN 並填入您的 OIDC ID 權杖值：

    environment variables window

  5. 將 cycode.exe 插入路徑以完成安裝。

安裝 Pre-Commit Hook

Cycode 的 pre-commit 和 pre-push hooks 可以在您的本機儲存庫中設定，以便 Cycode CLI 應用程式在您提交或推送程式碼至程式碼庫之前，自動識別程式碼中的任何問題。

[!NOTE] pre-commit 和 pre-push hooks 不適用於 IaC 掃描。

執行以下步驟以安裝 pre-commit hook：

安裝 Pre-Commit Hook

  1. 安裝 pre-commit 框架（必須安裝 Python 3.9 或更高版本）：

    pip3 install pre-commit

  2. 瀏覽至您要設定的本機 Git 儲存庫的頂層目錄。

  3. 在儲存庫的頂層目錄中建立一個名為 .pre-commit-config.yaml 的新 YAML 檔案（包含開頭的 .），內容如下：

    repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode
        stages: [pre-commit]

  4. 根據您的特定需求修改建立的檔案。使用 hook ID cycode 啟用機密掃描。使用 hook ID cycode-sca 啟用 SCA 掃描。使用 hook ID cycode-sast 啟用 SAST 掃描。如果您想要啟用所有掃描類型，請使用此設定：

    repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode
        stages: [pre-commit]
      - id: cycode-sca
        stages: [pre-commit]
      - id: cycode-sast
        stages: [pre-commit]

  5. 安裝 Cycode 的 hook：

    pre-commit install

    成功的 hook 安裝將產生訊息：Pre-commit installed at .git/hooks/pre-commit。

  6. 保持 pre-commit hook 為最新狀態：

    pre-commit autoupdate

    它會自動將 .pre-commit-config.yaml 中的 rev 升級至 Cycode CLI 的最新可用版本。

[!NOTE] 觸發發生在 git commit 命令時。 Hook 僅在暫存以供提交的檔案上觸發。

安裝 Pre-Push Hook

若要安裝 pre-push hook（除了 pre-commit hook 之外或取代它）：

  1. 將 pre-push hooks 新增至您的 .pre-commit-config.yaml 檔案：

    repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode-pre-push
        stages: [pre-push]

  2. 安裝 pre-push hook：

    pre-commit install --hook-type pre-push

  3. 對於 pre-commit 和 pre-push hooks，請使用：

    pre-commit install
pre-commit install --hook-type pre-push

[!NOTE] Pre-push hooks 在 git push 命令時觸發，且僅掃描即將推送的提交。

Cycode CLI 命令

以下是 Cycode CLI 應用程式可用的選項和命令：

OptionDescription
-v, --verbose顯示詳細日誌。
--no-progress-meter不顯示進度計。
--no-update-notifier不檢查 CLI 更新。
-o, --output [rich|text|json|table]指定輸出類型。預設為 rich。
--client-id TEXT為此特定掃描執行指定 Cycode 用戶端 ID。
--client-secret TEXT為此特定掃描執行指定 Cycode 用戶端密碼。
--id-token TEXT為此特定掃描執行指定 Cycode OIDC ID 權杖。
--install-completion為目前 shell 安裝完成功能。
--show-completion [bash|zsh|fish|powershell|pwsh]顯示指定 shell 的完成功能，以複製或自訂安裝。
-h, --help顯示指定命令的選項。
指令說明
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
auth驗證您的機器，將 CLI 與您的 Cycode 帳戶建立關聯。
configure初始化指令，用於設定您的 CLI 用戶端驗證。
ignore忽略特定的值、路徑或規則 ID。
mcp啟動 Model Context Protocol (MCP) 伺服器，以啟用 AI 與 Cycode 掃描功能的整合。
scan掃描內容中的 Secrets/IaC/SCA/SAST 違規。您需要指定要執行的掃描類型：commit-history/path/repository 等。
report產生報告。您需要指定要執行的報告類型，例如 SBOM。
status顯示 CLI 狀態並結束。

MCP 指令 [實驗性]

[!WARNING] MCP 指令僅適用於 Python 3.10 及以上版本。如果您使用的是較舊的 Python 版本，此指令將無法使用。

Model Context Protocol (MCP) 指令可讓您啟動一個 MCP 伺服器，將 Cycode 的掃描功能暴露給 AI 系統和應用程式。這使得 AI 模型可以透過標準化協定與 Cycode CLI 工具互動。

[!TIP] 為獲得最佳體驗，請使用 pip install cycode 或 brew install cycode 在您的系統上全域安裝 Cycode CLI，然後使用 cycode auth 驗證一次。全域安裝並完成驗證後，您就不需要在 MCP 設定檔中設定 CYCODE_CLIENT_ID 和 CYCODE_CLIENT_SECRET 環境變數。

Add MCP Server to Cursor using UV

啟動 MCP 伺服器

若要啟動 MCP 伺服器，請使用以下指令：

cycode mcp

預設情況下，這會使用 stdio 傳輸方式啟動伺服器，此方式適用於本機整合以及可以產生子處理程序的 AI 應用程式。

可用選項

選項說明
-t, --transportMCP 伺服器的傳輸類型：stdio、sse 或 streamable-http（預設：stdio）
-H, --host伺服器要綁定的主機位址（僅用於非 stdio 傳輸）（預設：127.0.0.1）
-p, --port伺服器要綁定的連接埠號碼（僅用於非 stdio 傳輸）（預設：8000）
--help顯示說明訊息和可用選項

MCP 工具

MCP 伺服器提供以下可供 AI 系統使用的工具：

工具名稱說明
cycode_secret_scan掃描硬編碼的 secrets
cycode_sca_scan掃描 Software Composition Analysis (SCA) - 漏洞和授權問題
cycode_iac_scan掃描 Infrastructure as Code (IaC) 錯誤設定
cycode_sast_scan掃描 Static Application Security Testing (SAST) - 程式碼品質和安全性缺陷
cycode_status取得 Cycode CLI 版本、驗證狀態和設定資訊

每個掃描工具接受兩種互斥的輸入模式：

  • paths （建議） — 磁碟上存在的一個或多個檔案或目錄路徑。目錄會以遞迴方式掃描。Cycode 引擎會處理檔案探索和篩選，就像 cycode scan -t <type> path ./src 從 CLI 執行時一樣。
  • files （備用） — 一個將檔案路徑對應到其完整內容（以字串表示）的字典。僅在檔案無法從磁碟取得時使用（例如尚未儲存的記憶體中編輯）。

[!TIP] 盡可能使用 paths。將大型檔案（例如 package-lock.json）作為內嵌內容傳遞可能會超過 token 限制並拖慢 AI 用戶端。使用 paths 時，Cycode 引擎會直接從磁碟讀取檔案。

所有掃描工具都會傳回一個 JSON 物件，其中包含一個 "summary" 欄位，內含人類可讀的違規計數（例如 "Cycode found 3 violations: 1 CRITICAL, 2 HIGH."），以及完整的 "detections" 陣列。

使用範例

基本指令範例

使用預設設定（stdio 傳輸）啟動 MCP 伺服器：

cycode mcp

使用明確的 stdio 傳輸啟動 MCP 伺服器：

cycode mcp -t stdio

使用 Server-Sent Events (SSE) 傳輸啟動 MCP 伺服器：

cycode mcp -t sse -p 8080

在自訂主機和連接埠上使用可串流 HTTP 傳輸啟動 MCP 伺服器：

cycode mcp -t streamable-http -H 0.0.0.0 -p 9000

在 MCP 協定規格 – 傳輸 中深入了解 MCP 傳輸類型。

設定範例

搭配 Cursor/VS Code/Claude Desktop 等使用 MCP（mcp.json）

[!NOTE] 對於歐盟 Cycode 環境，請務必在環境變數中設定適當的 CYCODE_API_URL 和 CYCODE_APP_URL 值（例如 https://api.eu.cycode.com 和 https://app.eu.cycode.com）。

請依照此指南在您的 VS Code/GitHub Copilot 中設定 MCP 伺服器。請記住，在 settings.json 中，有一個 mcp 物件包含巢狀的 servers 子物件，而不是獨立的 mcpServers 物件。

stdio 傳輸（直接執行）：

{
  "mcpServers": {
    "cycode": {
      "command": "cycode",
      "args": ["mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

搭配 pipx 安裝的 stdio 傳輸：

{
  "mcpServers": {
    "cycode": {
      "command": "pipx",
      "args": ["run", "cycode", "mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

搭配 uvx 安裝的 stdio 傳輸：

{
  "mcpServers": {
    "cycode": {
      "command": "uvx",
      "args": ["cycode", "mcp"],
      "env": {
        "CYCODE_CLIENT_ID": "your-cycode-id",
        "CYCODE_CLIENT_SECRET": "your-cycode-secret-key",
        "CYCODE_API_URL": "https://api.cycode.com",
        "CYCODE_APP_URL": "https://app.cycode.com"
      }
    }
  }
}

SSE 傳輸（Server-Sent Events）：

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

自訂連接埠上的 SSE 傳輸：

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8080/sse"
    }
  }
}

可串流 HTTP 傳輸：

{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
在背景執行 MCP 伺服器

SSE 傳輸（先啟動伺服器，再設定用戶端）：

# Start the MCP server in the background
cycode mcp -t sse -p 8000 &

# Configure in mcp.json
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

可串流 HTTP 傳輸：

# Start the MCP server in the background
cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &

# Configure in mcp.json
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.2:9000/mcp"
    }
  }
}

進階設定

自訂憑證和逾時（Proxy 環境）

如果您的組織使用企業 proxy 或自訂 CA 憑證套件進行 HTTPS 檢查，您需要告訴 Cycode CLI（以及底層的 Python TLS 堆疊）要在哪裡找到受信任的憑證套件。您也可以增加 MCP 工具呼叫逾時時間，以防掃描被過早中斷。

環境變數說明
REQUESTS_CA_BUNDLE自訂 CA 憑證套件檔案的路徑（.pem 或 .crt）。由 requests 程式庫用於 Cycode CLI 進行的所有 HTTPS 呼叫。
SSL_CERT_FILE自訂 CA 憑證套件檔案的路徑。由 Python 的低階 ssl 模組使用。請與 REQUESTS_CA_BUNDLE 一起設定以獲得完整涵蓋範圍。
MCP_TOOL_TIMEOUTMCP 用戶端（例如 Claude 和 GitHub Copilot）等待工具呼叫完成的逾時時間（以秒為單位）。如果長時間執行的掃描在完成前被中斷，請增加此值。

[!TIP] 將 REQUESTS_CA_BUNDLE 和 SSL_CERT_FILE 都設定為相同的 CA 憑證套件路徑。REQUESTS_CA_BUNDLE 涵蓋 HTTP 層；SSL_CERT_FILE 涵蓋較低層級的 TLS 層。在某些環境中，只使用其中一個可能仍會導致憑證錯誤。

使用自訂憑證和較長逾時時間的 mcp.json 設定範例：

{
  "mcpServers": {
    "cycode": {
      "command": "cycode",
      "args": ["mcp"],
      "env": {
        "REQUESTS_CA_BUNDLE": "/path/to/your/corporate-ca-bundle.pem",
        "SSL_CERT_FILE": "/path/to/your/corporate-ca-bundle.pem",
        "MCP_TOOL_TIMEOUT": "1800"
      }
    }
  }
}

[!NOTE] MCP 伺服器需要正確的 Cycode CLI 驗證才能運作。請確保您已使用 cycode auth 完成驗證，或在啟動 MCP 伺服器之前設定好您的憑證。

為子代理程式預先授權工具（Claude Code）

當 Claude Code 將工作委派給背景子代理程式（例如並行執行掃描）時，這些子代理程式無法顯示互動式權限提示。如果 Cycode 工具尚未預先核准，掃描將在子代理程式環境中靜默失敗。

若要預先授權 Cycode MCP 工具，使其在所有環境（包括子代理程式）中都能運作，請將它們新增到 Claude Code 設定（~/.claude/settings.json）中的 allowedTools 清單：

{
  "allowedTools": [
    "mcp__cycode__cycode_secret_scan",
    "mcp__cycode__cycode_sca_scan",
    "mcp__cycode__cycode_iac_scan",
    "mcp__cycode__cycode_sast_scan",
    "mcp__cycode__cycode_status"
  ]
}

新增後，Claude Code 在呼叫這些工具時將不會提示核准，而且它們將能在子代理程式內部正常運作。

MCP 疑難排解

如果您遇到 MCP 伺服器的問題，可以啟用除錯記錄以取得更詳細的資訊。有兩種方式可以啟用除錯記錄：

  1. 使用 -v 或 --verbose 旗標：
cycode -v mcp
  1. 使用 CYCODE_CLI_VERBOSE 環境變數：
CYCODE_CLI_VERBOSE=1 cycode mcp

除錯記錄會顯示以下詳細資訊：

  • 伺服器啟動和設定
  • 連線嘗試和狀態
  • 工具執行和結果
  • 發生的任何錯誤或警告

以下情況時，此資訊會很有幫助：

  • 診斷連線問題
  • 了解某些工具為何無法運作
  • 識別驗證問題
  • 除錯特定傳輸的問題

MCP 設定

Platform 指令 [BETA]

[!WARNING] platform 指令目前處於 beta 階段。指令、引數和輸出格式會根據 Cycode API 規格動態產生，並可能在各版本之間變更而不另行通知。請勿在正式環境自動化中依賴它們。

cycode platform 指令將 Cycode 平台的唯讀 API 公開為 CLI 指令。它會依資源（例如 projects、violations、workflows）將端點分組，並將每個端點的參數轉換為型別化的 CLI 引數和 --option 旗標。

cycode platform projects list --page-size 50
cycode platform violations count
cycode platform workflows view <workflow-id>

OpenAPI 規格會在首次使用時從 Cycode API 取得，並在 ~/.cycode/openapi-spec.json 快取 24 小時。不相關的指令（cycode scan、cycode status 等）不會觸發取得動作。

[!NOTE] 您必須完成驗證（cycode auth 或 CYCODE_CLIENT_ID / CYCODE_CLIENT_SECRET 環境變數），cycode platform 才能探索和執行指令。其他 Cycode CLI 指令則不需要驗證即可運作。

探索指令

由於指令是從規格產生的，因此可用指令的權威來源是 --help：

cycode platform --help                  # list all resource groups
cycode platform projects --help         # list actions on a resource
cycode platform projects list --help    # list options/arguments for an action

Platform 範例

# List projects with pagination
cycode platform projects list --page-size 25

# View a single project by ID
cycode platform projects view <project-id>

# Count violations across the tenant
cycode platform violations count

# Filter using query parameters (see `--help` for what each endpoint supports)
cycode platform violations list --severity CRITICAL

所有輸出預設皆為 JSON — 可透過 jq 進行臨時篩選：

cycode platform projects list --page-size 100 | jq '.items[].name'

Platform 注意事項與限制

  • 目前僅供唯讀。 此 beta 版本僅暴露 GET 端點。
  • 由規格驅動。 在 API 中新增端點時，會在下次快取重新整理時自動顯示。
  • 不包含隨附規格。 安裝後（或 24 小時快取過期後）的第一次 cycode platform 呼叫會執行網路取得。在慢速連線上，第一次呼叫可能需要幾秒鐘；後續呼叫則近乎即時，直到快取過期為止。
  • 使用 CYCODE_SPEC_CACHE_TTL=<seconds> 覆寫快取 TTL。

AI Guardrails [BETA]

AI Guardrails 會將掛鉤（hooks）安裝到受支援的 AI 編碼代理程式（Claude Code、Cursor、Copilot、Codex）中，以便在提示詞、代理程式讀取的檔案以及 MCP 工具引數送達模型之前，先對其進行密碼掃描。

AI Guardrails 收集的資料

掃描在伺服器端進行，因此被掃描的內容會離開本機：提示詞文字、代理程式讀取的檔案內容，以及 MCP 工具引數都會被傳送到您的 Cycode 租戶進行密碼檢查。

每個事件也會附帶開發人員與機器的相關背景資訊回報，因此可以將發現結果歸因於來源裝置與使用者。其中部分屬於個人資料：

  • 裝置識別碼 — 機器的主機名稱與硬體序號。
  • 使用者識別碼 — 登入 AI 編碼代理程式的使用者電子郵件地址，以及本機作業系統使用者名稱。
  • 環境詳細資料 — 作業系統與版本、AI 代理程式、其版本與使用中的模型、代理程式的 MCP 設定檔內容，以及其已啟用的外掛程式。

硬體序號會快取在本機暫存檔中，僅供執行該命令的使用者讀取，因此重複呼叫掛鉤時不會重新查詢硬體。

如果您的環境無法接受收集這些資料，請勿安裝 guardrails 掛鉤（cycode ai-guardrails uninstall 會移除已安裝的掛鉤）。

掃描命令

執行掃描

Cycode CLI 應用程式提供多種掃描類型，讓您可以選擇最符合需求的選項。以下是目前可用的選項與命令：

選項說明
-t, --scan-type [secret|iac|sca|sast]指定您要執行的掃描類型（secret/iac/sca/sast），預設為 secret。
--show-secret BOOLEAN以純文字顯示密碼。詳見 顯示/隱藏密碼 一節。
--soft-fail BOOLEAN執行掃描但不因違規而失敗，一律回傳非錯誤狀態碼。詳見 Soft Fail 一節。
--severity-threshold [INFO|LOW|MEDIUM|HIGH|CRITICAL]僅顯示指定層級或更高層級的違規。
--sca-scan指定您要執行的 SCA 掃描類型（package-vulnerabilities/license-compliance）。預設為兩者皆執行。
--monitor指定時，掃描結果會記錄在 Cycode 中。
--cycode-report在主控台輸出中顯示 Cycode 平台掃描報告的連結。
--no-restore指定時，Cycode 不會執行 restore 命令。這將僅掃描直接相依套件！
--stop-on-error若任何檔案收集或相依套件還原失敗，則中止掃描，而不是略過失敗的檔案並繼續。
--gradle-all-sub-projects對所有子專案執行 gradle restore 命令。應從以下位置執行
--maven-settings-file僅適用於 Maven，允許在掃描相依套件時使用自訂的 settings.xml 檔案
--help顯示指定命令的選項。
命令說明
commit-history掃描提交歷史，或在特定提交之間執行差異掃描
path掃描命令中指定路徑內的檔案
pre-commit使用此命令掃描尚未提交的內容
repository掃描 git 儲存庫，包括其歷史記錄

選項

嚴重性選項

若要將掃描結果限制在特定的嚴重性門檻，可以在掃描命令中加入 --severity-threshold 引數。

例如，以下命令會掃描儲存庫中嚴重性為 Medium 或更高的原則違規：

cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase

Monitor 選項

[!NOTE] 此選項僅適用於 SCA 掃描。

若要將 SCA 類型掃描中找到的 SCA 原則 相關掃描結果推送到 Cycode，請在掃描命令中加入 --monitor 引數。

例如，以下命令會掃描儲存庫中的 SCA 原則違規，並將其推送到 Cycode 平台：

cycode scan -t sca --monitor repository ~/home/git/codebase

Cycode 報告選項

每次使用 Cycode CLI 執行掃描時，系統會自動產生報告，並將結果傳送至 Cycode。這些結果會與 Cycode 平台中的相關原則（例如 Repository 掃描的 SCA 原則）關聯。

若要在掃描完成後於 CLI 輸出中列印此 Cycode 報告的直接 URL，請在掃描命令中加入 --cycode-report 引數。

cycode scan --cycode-report repository ~/home/git/codebase

CLI 的所有掃描結果都會顯示在 Cycode 的 CLI Logs 區段中。如果您在命令中包含 --cycode-report 旗標，終端機將在掃描結果之後顯示特定報告的直接連結。

[!WARNING] 您必須在 Cycode 中具備 owner 或 admin 角色才能檢視此頁面。

cli-report

報告頁面看起來會類似以下內容：

套件漏洞選項

[!NOTE] 此選項僅適用於 SCA 掃描。

若要掃描本機儲存庫的特定套件漏洞，請在 -t sca 或 --scan-type sca 選項之後加入 --sca-scan package-vulnerabilities 引數。

在先前的範例中，如果您只想對套件漏洞執行 SCA 掃描，可以執行以下命令：

cycode scan -t sca --sca-scan package-vulnerabilities repository ~/home/git/codebase

授權合規選項

[!NOTE] 此選項僅適用於 SCA 掃描。

若要掃描本機儲存庫的特定分支，請加入 --sca-scan license-compliance 引數，後面接著您要掃描的分支名稱。

在先前的範例中，如果您只想掃描名為 dev 的分支，可以執行以下命令：

cycode scan -t sca --sca-scan license-compliance repository ~/home/git/codebase -b dev

Lock 還原選項

[!NOTE] 此選項僅適用於 SCA 掃描。

執行 SCA 掃描時，Cycode CLI 會自動嘗試為其找到的每個受支援的 manifest 檔案還原（產生）相依套件 lockfile。這允許掃描傳遞相依套件，而不僅僅是 manifest 中直接列出的套件。若要跳過此步驟並僅掃描直接相依套件，請使用 --no-restore 旗標。

以下生態系統支援自動 lockfile 還原：

生態系統Manifest 檔案產生的 Lockfile呼叫的工具（當 lockfile 不存在時）
npmpackage.jsonpackage-lock.jsonnpm install --package-lock-only --ignore-scripts --no-audit
Yarnpackage.jsonyarn.lockyarn install --ignore-scripts
pnpmpackage.jsonpnpm-lock.yamlpnpm install --ignore-scripts
Denodeno.json / deno.jsoncdeno.lock（僅讀取現有 lockfile）
Gogo.modgo.mod.graphgo list -m -json all + go mod graph
Mavenpom.xmlbcde.mvndepsmvn dependency:tree
Gradlebuild.gradle / build.gradle.ktsgradle-dependencies-generated.txtgradle dependencies -q --console plain
SBTbuild.sbtbuild.sbt.locksbt dependencyLockWrite
NuGet*.csprojpackages.lock.jsondotnet restore --use-lock-file
RubyGemfileGemfile.lockbundle --quiet
Poetrypyproject.tomlpoetry.lockpoetry lock
pippyproject.toml / requirements.txtpylock.tomlpip lock . / pip lock -r requirements.txt -o pylock.toml
PipenvPipfilePipfile.lockpipenv lock
PHP Composercomposer.jsoncomposer.lockcomposer update --no-cache --no-install --no-scripts --ignore-platform-reqs

如果 lockfile 已存在於 manifest 旁邊，Cycode 會直接讀取它，而不執行任何安裝命令。

SBT 先決條件： 必須安裝 sbt-dependency-lock 外掛程式。請將以下行加入 project/plugins.sbt：

addSbtPlugin("software.purpledragon" % "sbt-dependency-lock" % "1.5.1")

錯誤時停止選項

預設情況下，即使檔案無法讀取（例如因權限錯誤）或 SCA 掃描期間無法產生相依套件 lockfile，Cycode 仍會繼續掃描。失敗的項目會以警告方式略過，掃描會繼續處理其餘檔案。

使用 --stop-on-error 來變更此行為：掃描會在第一次此類失敗時立即中止，並回報錯誤。

cycode scan -t sca --stop-on-error path ~/home/git/codebase

這在 CI 管線中很有用，因為靜默失敗會產生不完整的掃描結果。當觸發 --stop-on-error 時，您可以修正根本問題，或者針對 SCA 還原失敗，加入 --no-restore 以跳過 lockfile 產生並僅掃描直接相依套件。

使用 --stop-on-error 時，CLI 會透過結束碼區分掃描錯誤與原則違規：

結束碼意義
0掃描完成，無違規
1掃描完成，發現違規
2掃描因錯誤而中止（僅在設定 --stop-on-error 時）

Repository 掃描

Repository 掃描會檢查整個本機儲存庫，尋找任何暴露的密碼或不安全的錯誤設定。這種更全面的掃描類型會檢視所有內容：儲存庫的目前狀態及其提交歷史。它不僅會尋找目前暴露在儲存庫中的密碼，也會尋找先前已刪除的密碼。

若要執行完整的 repository 掃描，請執行以下命令：

cycode scan repository {{path}}

例如，如果您想掃描儲存在 ~/home/git/codebase 中的儲存庫，可以執行以下命令：

cycode scan repository ~/home/git/codebase

此命令可使用以下選項：

選項說明
-b, --branch TEXT要掃描的分支，若未設定則掃描預設分支

分支選項

若要掃描本機儲存庫的特定分支，請加入 -b 引數（或 --branch），後面接著您要掃描的分支名稱。

承接先前的範例，如果您只想掃描名為 dev 的分支，可以執行以下命令：

cycode scan repository ~/home/git/codebase -b dev

Path 掃描

Path 掃描會檢查特定的本機目錄及其中的所有內容，而不是僅專注於 GIT 儲存庫。

若要執行目錄掃描，請執行以下命令：

cycode scan path {{path}}

例如，假設您想要掃描位於 ~/home/git/codebase 的目錄。您可以執行以下命令：

cycode scan path ~/home/git/codebase

Terraform Plan 掃描

Cycode CLI 支援 Terraform plan 掃描（支援 Terraform 0.12 及更新版本）

Terraform plan 檔案必須為 JSON 格式（具有 .json 副檔名）

如果您只有設定檔，可以依照下列步驟產生 plan：

  1. 初始化包含 Terraform 設定檔的工作目錄：

    terraform init

  2. 建立 Terraform 執行計畫並儲存二進位輸出：

    terraform plan -out={tfplan_output}

  3. 將二進位輸出檔轉換為可讀的 JSON：

    terraform show -json {tfplan_output} > {tfplan}.json

  4. 使用 Cycode CLI 掃描您的 {tfplan}.json：

    cycode scan -t iac path ~/PATH/TO/YOUR/{tfplan}.json

提交歷史掃描

[!NOTE] 提交歷史掃描不適用於 IaC 掃描。

提交歷史掃描指令提供兩項主要功能：

  1. 完整歷史掃描：分析儲存庫歷史中的所有提交
  2. 差異掃描：僅掃描特定提交之間的變更

機密掃描可以分析儲存庫歷史中的所有提交，因為已引入但後來移除的機密仍可能遭到洩漏或暴露。對於 SCA 和 SAST 掃描，提交歷史指令專注於掃描提交之間的差異/變更，非常適合用於 Pull Request 審查和增量掃描。

提交歷史掃描會檢查您的 Git 儲存庫的提交歷史，既可用於全面的歷史分析，也可用於針對特定變更的差異掃描。

若要執行提交歷史掃描，請執行以下指令：

cycode scan commit-history {{path}}

例如，假設您想要掃描儲存在 ~/home/git/codebase 中的儲存庫的提交歷史。您可以接著執行以下指令：

cycode scan commit-history ~/home/git/codebase

此指令可使用下列選項：

選項說明
-r, --commit-range TEXT掃描此 git 儲存庫中的提交範圍，預設情況下 cycode 會掃描所有提交歷史（範例：HEAD~1）

提交範圍選項（差異掃描）

提交範圍選項啟用差異掃描 – 僅掃描特定提交之間的變更，而非整個儲存庫歷史。 這對於以下情況特別有用：

  • Pull Request 驗證：僅掃描 PR 中引入的變更
  • 增量 CI/CD 掃描：專注於最近的變更，而非整個程式碼庫
  • 功能分支審查：與 main/master 分支進行比較
  • 效能最佳化：透過限制範圍至相關變更來加快掃描速度

提交範圍語法

--commit-range（-r）選項支援標準 Git 修訂語法：

語法說明範例
commit1..commit2從 commit1 到 commit2 的變更abc123..def456
commit1...commit2commit2 中但不在 commit1 中的變更main...feature-branch
commit從 commit 到 HEAD 的變更HEAD~1
branch1..branch2從 branch1 到 branch2 的變更main..feature-branch

差異掃描範例

掃描最後一次提交的變更：

cycode scan commit-history -r HEAD~1 ~/home/git/codebase

掃描兩個特定提交之間的變更：

cycode scan commit-history -r abc123..def456 ~/home/git/codebase

掃描您的功能分支相對於 main 的變更：

cycode scan commit-history -r main..HEAD ~/home/git/codebase

掃描 main 與功能分支之間的變更：

cycode scan commit-history -r main..feature-branch ~/home/git/codebase

掃描最近 3 次提交中的所有變更：

cycode scan commit-history -r HEAD~3..HEAD ~/home/git/codebase

[!TIP] 對於 CI/CD 管線，您可以使用環境變數，例如 ${{ github.event.pull_request.base.sha }}..${{ github.sha }}（GitHub Actions）或 $CI_MERGE_REQUEST_TARGET_BRANCH_SHA..$CI_COMMIT_SHA（GitLab CI），僅掃描 PR/MR 的變更。

提交前掃描

提交前掃描會在您將變更提交到儲存庫之前自動識別任何問題。無需手動執行此掃描；請依照本指南的安裝章節所述設定 pre-commit hook。

安裝 pre-commit hook 後，您可能偶爾希望在特定提交期間略過掃描。若要這樣做，請在您的 git 指令中加入以下內容，以略過單一提交的掃描：

SKIP=cycode git commit -m <your commit message>`

推送前掃描

推送前掃描會在您將變更推送到遠端儲存庫之前自動識別任何問題。此 hook 在用戶端執行，僅掃描即將推送的提交，使其能有效率地在問題到達遠端儲存庫之前將其攔截。

[!NOTE] Pre-push hook 不適用於 IaC 掃描。

Pre-push hook 與 pre-commit 框架整合，可設定在任何 git push 操作之前執行。

安裝 Pre-Push Hook

若要使用 pre-commit 框架設定 pre-push hook：

  1. 安裝 pre-commit 框架（如果尚未安裝）：

    pip3 install pre-commit

  2. 建立或更新您的 .pre-commit-config.yaml 檔案以包含 pre-push hooks：

    repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode-pre-push
        stages: [pre-push]

  3. 對於多種掃描類型，請使用此設定：

    repos:
  - repo: https://github.com/cycodehq/cycode-cli
    rev: v3.5.0
    hooks:
      - id: cycode-pre-push          # Secrets scan
        stages: [pre-push]
      - id: cycode-sca-pre-push      # SCA scan
        stages: [pre-push]
      - id: cycode-sast-pre-push     # SAST scan
        stages: [pre-push]

  4. 安裝 pre-push hook：

    pre-commit install --hook-type pre-push

    成功安裝將產生訊息：Pre-push installed at .git/hooks/pre-push。

  5. 保持 pre-push hook 為最新狀態：

    pre-commit autoupdate

Pre-Push 掃描的運作方式

Pre-push hook：

  • 接收有關正在推送的提交的資訊
  • 計算要掃描的適當提交範圍
  • 對於新分支：掃描從與預設分支的合併基礎開始的所有提交
  • 對於現有分支：僅掃描自上次推送以來的新提交
  • 執行與其他 Cycode 掃描模式相同的全面掃描

智慧預設分支偵測

Pre-push hook 會使用下列優先順序智慧偵測預設分支以進行合併基礎計算：

  1. 環境變數：CYCODE_DEFAULT_BRANCH - 允許手動覆寫
  2. Git Remote HEAD：使用 git symbolic-ref refs/remotes/origin/HEAD 偵測實際的遠端預設分支
  3. Git Remote Info：如果 symbolic-ref 失敗，則回退至 git remote show origin
  4. 硬編碼回退：使用常見的預設分支名稱（origin/main、origin/master、main、master）

設定自訂預設分支：

export CYCODE_DEFAULT_BRANCH=origin/develop

此智慧偵測可確保 pre-push hook 無論您的儲存庫使用 main、master、develop 或任何其他預設分支名稱，都能正確運作。

略過 Pre-Push 掃描

若要略過特定推送操作的 pre-push 掃描，請使用：

SKIP=cycode-pre-push git push

或略過所有 pre-push hooks：

git push --no-verify

[!TIP] Pre-push hook 會在 git push 指令時觸發，且僅掃描即將推送的提交，比掃描整個儲存庫更有效率。

從掃描中排除路徑

您可以使用 .cycodeignore 檔案告訴 Cycode CLI 要從掃描中排除哪些檔案和目錄。 其運作方式類似於 .gitignore 檔案。這有助於將掃描專注於您的相關程式碼，並防止特定路徑在本機觸發違規。

運作方式

  1. 在您的工作資料夾中建立名為 .cycodeignore 的檔案。
  2. 使用與 .gitignore 相同的模式，列出您要排除的檔案和目錄。
  3. 將此檔案放在您計畫執行 cycode 掃描指令的目錄中。

[!WARNING]

  • 無效檔案：如果 .cycodeignore 檔案包含語法錯誤，CLI 掃描將失敗並傳回錯誤。
  • 忽略路徑與違規：此檔案用於排除路徑。這與 CLI 忽略特定違規的能力不同（例如，使用 --ignore-violation 旗標）。

支援的掃描器

  • SAST
  • IaC（即將推出）
  • SCA（即將推出）

掃描結果

每次掃描都會以訊息完成，說明是否找到任何問題。

如果未找到問題，掃描會以下列成功訊息結束：

Good job! No issues were found!!! 👏👏👏

如果找到問題，完成時會改為顯示違規卡片。在此情況下，您應檢視結果訊息所標示的特定行所在的檔案。實作解決問題所需的任何變更，然後再次執行掃描。

顯示/隱藏機密

在下面的範例中，在位於子資料夾 cli 的檔案 secret_test 中發現了一個機密。訊息的第二部分顯示機密出現的特定行，在此案例中是指派給 googleApiKey 的值。

請注意範例如何模糊化實際的機密值，將機密的大部分替換為星號。掃描預設會模糊化機密，但您可以選擇停用此功能以檢視完整機密（假設您檢視掃描結果的機器對於窺探者來說足夠安全）。

若要停用機密模糊化，請在任何類型的掃描中加入 --show-secret 引數。

在下列範例中，針對 cli 子目錄執行路徑掃描，並啟用選項以完整顯示找到的任何機密：

cycode scan --show-secret path ./cli

結果將不會被模糊化。

軟失敗

在正常操作中，當掃描結果中發現問題時，CLI 會傳回退出碼 1。根據您的 CI/CD 設定，這通常會導致整體失敗。如果您不希望發生這種情況，可以使用軟失敗功能。

在任何類型的掃描中加入 --soft-fail 選項，無論是否找到任何結果，退出碼都會強制為 0。

範例掃描結果

機密結果範例

╭─────────────────────────────────────────────────────────────── Hardcoded generic-password is used ───────────────────────────────────────────────────────────────╮
│                                                                                                                                               Violation 12 of 12 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity    🟠 MEDIUM                             │ │   34 };                                                                                               │ │
│ │  In file     /Users/cycodemacuser/NodeGoat/test/s  │ │   35                                                                                                  │ │
│ │              ecurity/profile-test.js               │ │   36 var sutUserName = "user1";                                                                       │ │
│ │  Secret SHA  b4ea3116d868b7c982ee6812cce61727856b  │ │ ❱ 37 var sutUserPassword = "Us*****23";                                                               │ │
│ │              802b3063cd5aebe7d796988552e0          │ │   38                                                                                                  │ │
│ │  Rule ID     68b6a876-4890-4e62-9531-0e687223579f  │ │   39 chrome.setDefaultService(service);                                                               │ │
│ ╰────────────────────────────────────────────────────╯ │   40                                                                                                  │ │
│                                                        ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ A generic secret or password is an authentication token used to access a computer or application and is assigned to a password variable.                     │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

IaC 結果範例

╭──────────── Enable Content Encoding through the attribute 'MinimumCompressionSize'. This value should be greater than -1 and smaller than 10485760. ─────────────╮
│                                                                                                                                              Violation 45 of 110 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity      🟠 MEDIUM                           │ │   20 BinaryMediaTypes:                                                                                │ │
│ │  In file       ...ads-copy/iac/cft/api-gateway/ap  │ │   21   - !Ref binaryMediaType1                                                                        │ │
│ │                i-gateway-rest-api/deploy.yml       │ │   22   - !Ref binaryMediaType2                                                                        │ │
│ │  IaC Provider  CloudFormation                      │ │ ❱ 23 MinimumCompressionSize: -1                                                                       │ │
│ │  Rule ID       33c4b90c-3270-4337-a075-d3109c141b  │ │   24 EndpointConfiguration:                                                                           │ │
│ │                53                                  │ │   25   Types:                                                                                         │ │
│ ╰────────────────────────────────────────────────────╯ │   26     - EDGE                                                                                       │ │
│                                                        ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ This policy validates the proper configuration of content encoding in AWS API Gateway. Specifically, the policy checks for the attribute                     │ │
│ │ 'minimum_compression_size' in API Gateway REST APIs. Correct configuration of this attribute is important for enabling content encoding of API responses for │ │
│ │ improved API performance and reduced payload sizes.                                                                                                          │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

SCA 結果範例

╭─────────────────────────────────────────────────────── [CVE-2019-10795] Prototype Pollution in undefsafe ────────────────────────────────────────────────────────╮
│                                                                                                                                             Violation 172 of 195 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity               🟠 MEDIUM                  │ │   26758   "integrity": "sha1-5z3T17DXxe2G+6xrCufYxqadUPo=",                                           │ │
│ │  In file                /Users/cycodemacuser/Node  │ │   26759   "dev": true                                                                                 │ │
│ │                         Goat/package-lock.json     │ │   26760 },                                                                                            │ │
│ │  CVEs                   CVE-2019-10795             │ │ ❱ 26761 "undefsafe": {                                                                                │ │
│ │  Package                undefsafe                  │ │   26762   "version": "2.0.2",                                                                         │ │
│ │  Version                2.0.2                      │ │   26763   "resolved": "https://registry.npmjs.org/undefsafe/-/undefsafe-2.0.2.tgz",                   │ │
│ │  First patched version  Not fixed                  │ │   26764   "integrity": "sha1-Il9rngM3Zj4Njnz9aG/Cg2zKznY=",                                           │ │
│ │  Dependency path        nodemon 1.19.1 ->          │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │                         undefsafe 2.0.2            │                                                                                                           │
│ │  Rule ID                9c6a8911-e071-4616-86db-4  │                                                                                                           │
│ │                         943f2e1df81                │                                                                                                           │
│ ╰────────────────────────────────────────────────────╯                                                                                                           │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ undefsafe before 2.0.3 is vulnerable to Prototype Pollution. The 'a' function could be tricked into adding or modifying properties of Object.prototype using │ │
│ │ a __proto__ payload.                                                                                                                                         │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

SAST 結果範例

╭───────────────────────────────────────────── [CWE-208: Observable Timing Discrepancy] Observable Timing Discrepancy ─────────────────────────────────────────────╮
│                                                                                                                                               Violation 24 of 49 │
│ ╭─ 🔍 Details ───────────────────────────────────────╮ ╭─ 💻 Code Snippet ─────────────────────────────────────────────────────────────────────────────────────╮ │
│ │  Severity       🟠 MEDIUM                          │ │   173         " including numbers, lowercase and uppercase letters.";                                 │ │
│ │  In file        /Users/cycodemacuser/NodeGoat/app  │ │   174     return false;                                                                               │ │
│ │                 /routes/session.js                 │ │   175 }                                                                                               │ │
│ │  CWE            CWE-208                            │ │ ❱ 176 if (password !== verify) {                                                                      │ │
│ │  Subcategory    Security                           │ │   177     errors.verifyError = "Password must match";                                                 │ │
│ │  Language       js                                 │ │   178     return false;                                                                               │ │
│ │  Security Tool  Bearer (Powered by Cycode)         │ │   179 }                                                                                               │ │
│ │  Rule ID        19fbca07-a8e7-4fa6-92ac-a36d15509  │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
│ │                 fa9                                │                                                                                                           │
│ ╰────────────────────────────────────────────────────╯                                                                                                           │
│ ╭─ 📝 Summary ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │
│ │ Observable Timing Discrepancy occurs when the time it takes for certain operations to complete can be measured and observed by attackers. This vulnerability │ │
│ │ is particularly concerning when operations involve sensitive information, such as password checks or secret comparisons. If attackers can analyze how long   │ │
│ │ these operations take, they might be able to deduce confidential details, putting your data at risk.                                                         │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

公司自訂補救指南

如果您的公司已透過 Cycode 入口網站為相關政策設定了自訂補救指南，您會看到一個「公司指南」欄位，其中包含您新增的補救指南。請注意，如果您尚未新增任何公司指南，此欄位將不會出現在 CLI 工具中。

忽略掃描結果

可以新增忽略規則，以忽略特定的機密值、特定的 SHA512 值、特定的路徑，以及特定的 Cycode 機密和 IaC 規則 ID。這將使掃描不會對這些值發出警示。忽略規則會寫入並儲存在本機的 ./.cycode/config.yaml 檔案中。

[!WARNING] 新增要忽略的值時，應仔細考量值、路徑和政策，以確保掃描能偵測到真正的陽性結果。

以下是 cycode ignore 指令可用的選項：

選項說明
--by-value TEXT掃描機密時忽略特定值。詳情請參閱忽略機密值。
--by-sha TEXT掃描機密時忽略字串的特定 SHA512 表示。詳情請參閱忽略機密 SHA 值。
--by-path TEXT避免掃描特定路徑。需要指定掃描類型。詳情請參閱忽略路徑。
--by-rule TEXT忽略掃描特定的機密規則 ID/IaC 規則 ID/SCA 規則 ID。詳情請參閱忽略機密或 IaC 規則。
--by-package TEXT執行 SCA 掃描時忽略掃描特定套件版本。預期模式 - name@version。詳情請參閱忽略套件。
--by-cve TEXT執行 SCA 掃描時忽略掃描特定 CVE。預期模式：CVE-YYYY-NNN。
-t, --scan-type [secret|iac|sca|sast]指定您要執行的掃描（secret/iac/sca/sast）。預設值為 secret。
-g, --global新增忽略規則並更新至全域 .cycode 設定檔。

忽略機密值

若要忽略特定的機密值，您需要使用 --by-value 旗標。這會從所有未來的掃描中忽略指定的機密值。使用以下命令新增要忽略的機密值：

cycode ignore --by-value {{secret-value}}

在本節開頭的範例中，忽略特定機密值的命令如下：

cycode ignore --by-value h3110w0r1d!@#$350

在上述範例中，將 h3110w0r1d!@#$350 值替換為您未遮罩的機密值。有關如何在掃描結果中查看機密值的詳細資訊，請參閱 Cycode 掃描選項。

忽略機密 SHA 值

若要忽略特定的機密 SHA 值，您需要使用 --by-sha 旗標。這會從所有未來的掃描中忽略指定的機密 SHA 值。使用以下命令新增要忽略的機密 SHA 值：

cycode ignore --by-sha {{secret-sha-value}}

在本節開頭的範例中，忽略特定機密 SHA 值的命令如下：

cycode ignore --by-sha a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0

在上述範例中，將 a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0 值替換為您的機密 SHA 值。

忽略路徑

若要忽略機密、IaC 或 SCA 掃描的特定路徑，您需要使用 --by-path 旗標搭配 -t, --scan-type 旗標（您必須指定掃描類型）。這會從指定掃描類型的所有未來掃描中忽略給定的路徑。使用以下命令新增要忽略的路徑：

cycode ignore -t {{scan-type}} --by-path {{path}}

在本節開頭的範例中，忽略機密特定路徑的命令如下：

cycode ignore -t secret --by-path ~/home/my-repo/config

在上述範例中，將 ~/home/my-repo/config 值替換為您的路徑值。

在本節開頭的範例中，從 IaC 掃描中忽略特定路徑的命令如下：

cycode ignore -t iac --by-path ~/home/my-repo/config

在上述範例中，將 ~/home/my-repo/config 值替換為您的路徑值。

在本節開頭的範例中，從 SCA 掃描中忽略特定路徑的命令如下：

cycode ignore -t sca --by-path ~/home/my-repo/config

在上述範例中，將 ~/home/my-repo/config 值替換為您的路徑值。

忽略機密、IaC、SCA 或 SAST 規則

若要忽略特定的機密、IaC、SCA 或 SAST 規則，您需要使用 --by-rule 旗標搭配 -t, --scan-type 旗標（您必須指定掃描類型）。這會從所有未來的掃描中忽略給定的規則 ID 值。使用以下命令新增要忽略的規則 ID 值：

cycode ignore -t {{scan-type}} --by-rule {{rule-ID}}

在本節開頭的範例中，忽略特定機密規則 ID 的命令如下：

cycode ignore -t secret --by-rule ce3a4de0-9dfc-448b-a004-c538cf8b4710

在上述範例中，將 ce3a4de0-9dfc-448b-a004-c538cf8b4710 值替換為您要忽略的規則 ID。

在本節開頭的範例中，忽略特定 IaC 規則 ID 的命令如下：

cycode ignore -t iac --by-rule bdaa88e2-5e7c-46ff-ac2a-29721418c59c

在上述範例中，將 bdaa88e2-5e7c-46ff-ac2a-29721418c59c 值替換為您要忽略的規則 ID。

在本節開頭的範例中，忽略特定 SCA 規則 ID 的命令如下：

cycode ignore -t sca --by-rule dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b

在上述範例中，將 dc21bc6b-9f4f-46fb-9f92-e4327ea03f6b 值替換為您要忽略的規則 ID。

忽略套件

[!NOTE] 此選項僅適用於 SCA 掃描。

若要忽略 SCA 掃描中的特定套件，您需要使用 --by-package 旗標搭配 -t, --scan-type 旗標（您必須指定 sca 掃描類型）。這會使用 {{package_name}}@{{package_version}} 格式，從所有未來的掃描中忽略給定的套件。使用以下命令新增要忽略的套件和版本：

cycode ignore --scan-type sca --by-package {{package_name}}@{{package_version}}

或

cycode ignore -t sca --by-package {{package_name}}@{{package_version}}

在下面的範例中，忽略特定 SCA 套件的命令如下：

cycode ignore --scan-type sca --by-package pyyaml@5.3.1

在上述範例中，將 pyyaml 替換為套件名稱，並將 5.3.1 替換為您要忽略的套件版本。

透過設定檔忽略

套用的忽略規則儲存在名為 config.yaml 的設定檔中。 此檔案可以輕鬆地在開發人員之間共享，甚至可以提交到遠端 Git。 這些檔案始終位於 .cycode 資料夾中。 該資料夾以點 (.) 開頭，您應該啟用顯示隱藏檔案才能看到它。

設定檔的路徑

預設情況下，所有 cycode ignore 命令都會將忽略規則儲存到執行 CLI 的目前目錄。

範例：從 /Users/name/projects/backend 執行忽略 CLI 命令將在 /Users/name/projects/backend/.cycode 中建立 config.yaml

➜  backend  pwd
/Users/name/projects/backend
➜  backend  cycode ignore --by-value test-value
➜  backend  tree -a
.
└── .cycode
    └── config.yaml

2 directories, 1 file

第二個選項是將忽略規則儲存到全域設定檔。 全域設定的路徑是 ~/.cycode/config.yaml， 其中 ~ 表示 users home directory, for example, /Users/name`（在 macOS 上）。

可以使用 cycode ignore 命令的 -g 旗標來儲存到全域空間。 例如：cycode ignore -g --by-value test-value。

正確的工作目錄

將 .cycode 資料夾放置並從相同位置執行 CLI 非常重要。 在使用不同環境（例如 CI/CD（GitHub Actions、Jenkins 等））時，您應該仔細檢查。

您可以將 .cycode 資料夾提交到儲存庫的根目錄。在這種情況下，您必須從儲存庫根目錄執行 CLI 掃描。如果這不符合您的需求，您可以暫時將 .cycode 資料夾複製到任何您想要的位置，並從該資料夾執行 CLI 掃描。

設定檔中的忽略規則結構

了解 CLI 如何儲存忽略規則非常重要，這樣才能讀取這些設定檔，甚至無需 CLI 即可修改它們。

抽象的 YAML 結構：

exclusions:
  {scanTypeName}:
    {ignoringType}:
    - someIgnoringValue1
    - someIgnoringValue2

scanTypeName 的可能值：iac、sca、sast、secret。

ignoringType 的可能值：paths、values、rules、packages、shas、cves。

[!WARNING] 「依值忽略」的值不會以純文字儲存！ CLI 改為儲存值的 sha256 雜湊。 手動修改設定檔時，您應該放入字串的雜湊。

真實 config.yaml 的範例：

exclusions:
  iac:
    rules:
    - bdaa88e2-5e7c-46ff-ac2a-29721418c59c
  sca:
    packages:
    - pyyaml@5.3.1
  secret:
    paths:
    - /Users/name/projects/build
    rules:
    - ce3a4de0-9dfc-448b-a004-c538cf8b4710
    shas:
    - a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
    values:
    - a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
    - 60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752

報告命令

產生 SBOM 報告

軟體物料清單（SBOM）是應用程式開發和交付過程中所有組成元件和軟體相依項的清單。 使用此命令，您可以為本機專案或儲存庫 URI 建立 SBOM 報告。

此命令可使用以下選項：

選項說明必要預設
-f, --format [spdx-2.2|spdx-2.3|cyclonedx-1.4]SBOM 格式是
-o, --output-format [JSON]指定輸出檔案格式否json
--output-file PATH輸出檔案否自動產生的檔案名稱，儲存於目前目錄
--include-vulnerabilities包含漏洞否False
--include-dev-dependencies包含開發相依項否False

此命令可使用以下子命令：

命令說明
path為命令中提供的路徑產生 SBOM 報告
repository-url為命令中提供的儲存庫 URI 產生 SBOM 報告

儲存庫

若要為儲存庫 URI 建立 SBOM 報告：
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> repository_url <repository url>

例如：
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies repository_url https://github.com/cycodehq/cycode-cli.git

本機專案

若要為路徑建立 SBOM 報告：
cycode report sbom --format <sbom format> --include-vulnerabilities --include-dev-dependencies --output-file </path/to/file> path </path/to/project>

例如：
cycode report sbom --format spdx-2.3 --include-vulnerabilities --include-dev-dependencies path /path/to/local/project

path 子命令支援以下其他選項：

選項說明
--no-restore跳過 lockfile 還原，僅掃描直接相依項。詳情請參閱鎖定檔還原選項。
--gradle-all-sub-projects為所有子專案執行 Gradle 還原命令（從多專案 Gradle 建置的根目錄使用）。
--maven-settings-file僅適用於 Maven，允許在建置相依性樹狀結構時使用自訂的 settings.xml 檔案。

匯入命令

匯入 SBOM

軟體物料清單（SBOM）是應用程式開發和交付過程中所有組成元件和軟體相依項的清單。 使用此命令，您可以將 SBOM 檔案從您的檔案系統匯入 Cycode。

此命令可使用以下選項：

選項描述必填預設值
-n, --name TEXTSBOM 的顯示名稱是
-v, --vendor TEXT提供 SBOM 的實體名稱是
-l, --label TEXT為 SBOM 附加標籤否
-o, --owner TEXT作為此 SBOM 聯絡窗口的 Cycode 使用者電子郵件地址否
-b, --business-impact [High | Medium | Low]業務影響否中等

例如：
cycode import sbom --name example-sbom --vendor cycode -label tag1 -label tag2 --owner example@cycode.com /path/to/local/project

掃描日誌

所有 CLI 掃描都會記錄在 Cycode 中。日誌可在「設定 > CLI 日誌」下找到。

語法說明

您可以隨時在任何命令中加入 --help 引數，以查看顯示可用選項及其語法的說明訊息。

若要查看一般說明，只需輸入命令：

cycode --help

若要查看掃描選項，請輸入：

cycode scan --help

若要查看特定類型掃描的可用選項，請輸入：

cycode scan {{option}} --help

例如，若要查看路徑掃描的可用選項，您應輸入：

cycode scan path --help

若要查看忽略掃描功能的可用選項，請使用此命令：

cycode ignore --help

若要查看報告的可用選項，請使用此命令：

cycode report --help

若要查看特定類型報告的可用選項，請輸入：

cycode scan {{option}} --help