Cycode MCP Server

官方

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

GitHub

文件

Cycode CLI 使用指南

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

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

先決條件

Cycode CLI 應用程式需要 Python 3.9 或更新版本。MCP 命令僅適用於 Python 3.10 及以上版本。如果您使用較早的 Python 版本，此命令將無法使用。
使用 cycode auth 命令向 Cycode 驗證 CLI
- 或者，您可以按照服務帳戶權杖和個人存取權杖頁面中詳述的步驟取得 Cycode 用戶端 ID 和用戶端密鑰，這些頁面包含了取得這些值的詳細資訊。

安裝

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

[!NOTE] 以下步驟假設 Python 相關命令使用 python3 和 pip3；但是，某些系統可能會根據您的 Python 環境設定而改用 python 和 pip 命令。

安裝 Cycode CLI

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

開啟您的命令列或終端機應用程式。
執行以下其中一個命令：
- 從 PyPI 安裝：
```
pip3 install cycode
```
- 從 Homebrew 安裝：
```
brew install cycode
```
- 從 GitHub Releases 安裝，請導航並下載適用於您作業系統和架構的可執行檔，然後執行以下命令：
```
cd /path/to/downloaded/cycode-cli
chmod +x cycode
./cycode
```
最後驗證 CLI。有三種方法可以設定 Cycode 用戶端 ID 和憑證（用戶端密鑰或 OIDC ID 權杖）：
- cycode auth (建議)
- cycode configure
- 將它們新增至您的環境變數

使用 Auth 命令

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

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

cycode auth
將會出現一個瀏覽器視窗，要求您登入 Cycode（如下所示）：
在此頁面上輸入您的登入憑證並登入。
您最終將被導向到以下頁面，系統會要求您選擇要授權 Cycode 的業務群組（如果適用）：

[!NOTE] 這將是向 Cycode CLI 驗證的預設方法。
點擊允許按鈕以授權 Cycode CLI 在所選的業務群組上使用。
完成後，如果成功選取，您將看到以下畫面：
在終端機/命令列畫面中，當您關閉瀏覽器視窗時，將會看到以下內容：

Successfully logged into cycode

使用 Configure 命令

[!NOTE] 如果您已經透過 Linux 或 Windows 環境變數設定了 Cycode 用戶端 ID 和用戶端密鑰，則這些憑證將優先於此方法。

在您的終端機/命令列視窗中輸入以下命令：
```
cycode configure
```
輸入您的 Cycode API URL 值（您可以保留空白以使用預設值）。

Cycode API URL [https://api.cycode.com]: https://api.onpremise.com
輸入您的 Cycode APP URL 值（您可以保留空白以使用預設值）。

Cycode APP URL [https://app.cycode.com]: https://app.onpremise.com
輸入您的 Cycode 用戶端 ID 值。

Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d
輸入您的 Cycode 用戶端密鑰值（如果您計劃使用 OIDC ID 權杖，請跳過）。

Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
輸入您的 Cycode OIDC ID 權杖值（選用）。

Cycode ID Token []: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
如果成功輸入值，您將看到以下訊息：

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 上

從控制台，導航至系統選單：
接著，點擊進階系統設定：
在開啟的系統內容視窗中，點擊環境變數按鈕：
建立 CYCODE_CLIENT_ID 和 CYCODE_CLIENT_SECRET 變數，其值分別對應您的 ID 和密鑰。如果您透過 OIDC 驗證，也請新增 CYCODE_ID_TOKEN 以及您的 OIDC ID 權杖值：
將 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

安裝 pre-commit 框架（必須安裝 Python 3.9 或更高版本）：
```
pip3 install pre-commit
```
導航至您要設定的本機 Git 儲存庫的頂層目錄。

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

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

根據您的特定需求修改建立的檔案。使用 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]
```
安裝 Cycode 的 hook：
```
pre-commit install
```
成功安裝 hook 將顯示訊息：Pre-commit installed at .git/hooks/pre-commit。
保持 pre-commit hook 為最新版本：
```
pre-commit autoupdate
```
它會自動將 .pre-commit-config.yaml 中的 rev 更新至 Cycode CLI 的最新可用版本。

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

安裝 Pre-Push Hook

若要額外安裝或取代 pre-commit hook 來安裝 pre-push hook：

將 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]

安裝 pre-push hook：

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

若要同時使用 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 應用程式可用的選項和命令：

選項	說明
`-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	啟動模型上下文協定 (MCP) 伺服器，以啟用 AI 整合 Cycode 掃描功能。
scan	掃描內容中的 Secrets/IaC/SCA/SAST 違規。您需要指定要執行的掃描類型：commit-history/path/repository/etc。
report	產生報告。您需要指定要執行的報告類型，例如 SBOM。
status	顯示 CLI 狀態並退出。

MCP 指令 [實驗性功能]

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

模型上下文協定 (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 環境變數。

啟動 MCP 伺服器

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

cycode mcp

預設情況下，這會使用 stdio 傳輸方式啟動伺服器，該方式適用於本機整合和可以生成子行程的 AI 應用程式。

可用選項

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

MCP 工具

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

工具名稱	說明
`cycode_secret_scan`	掃描硬編碼的機密
`cycode_sca_scan`	掃描軟體組成分析 (SCA) - 漏洞和授權問題
`cycode_iac_scan`	掃描基礎設施即程式碼 (IaC) 錯誤設定
`cycode_sast_scan`	掃描靜態應用程式安全測試 (SAST) - 程式碼品質和安全缺陷
`cycode_status`	取得 Cycode CLI 版本、驗證狀態和設定資訊

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

paths （首選） — 一個或多個存在於磁碟上的檔案或目錄路徑。目錄會被遞迴掃描。Cycode 引擎會處理檔案發現和過濾，就像 CLI 中的 cycode scan -t <type> path ./src 一樣。
files （備用） — 一個將檔案路徑對應到其完整內容（字串形式）的字典。僅在檔案無法在磁碟上使用時（例如尚未儲存的記憶體內編輯）才使用此模式。

[!TIP] 盡可能使用 paths。將大型檔案（如 package-lock.json）作為內聯內容傳遞可能會超出權杖限制並降低 AI 用戶端的速度。使用 paths，Cycode 引擎會直接從磁碟讀取檔案。

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

使用範例

基本指令範例

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

cycode mcp

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

cycode mcp -t stdio

使用伺服器傳送事件 (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] 對於 EU Cycode 環境，請確保在環境變數中設定適當的 CYCODE_API_URL 和 CYCODE_APP_URL 值（例如 https://api.eu.cycode.com 和 https://app.eu.cycode.com）。

按照本指南在您的 VS Code/GitHub Copilot 中設定 MCP 伺服器。請記住，在 settings.json 中，有一個包含巢狀 servers 子物件的 mcp 物件，而不是獨立的 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 傳輸（伺服器傳送事件）：

{
  "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"
    }
  }
}

進階設定

自訂憑證和逾時（代理環境）

如果您的組織使用企業代理或自訂 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_TIMEOUT`	MCP 用戶端（如 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 驗證才能運作。在啟動 MCP 伺服器之前，請確保您已使用 cycode auth 進行驗證或已設定您的憑證。

為子代理預先授權工具 (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 伺服器時遇到問題，可以啟用除錯記錄以獲取有關正在發生的事情的更詳細資訊。有兩種方法可以啟用除錯記錄：

使用 -v 或 --verbose 旗標：

cycode -v mcp

使用 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。

Scan 指令

執行掃描

Cycode CLI 應用程式提供多種類型的掃描，以便您可以選擇最適合您情況的選項。以下是目前可用的選項和指令：

選項	說明
`-t, --scan-type [secret\|iac\|sca\|sast]`	指定要執行的掃描類型（`secret`/`iac`/`sca`/`sast`），預設為 `secret`。
`--show-secret BOOLEAN`	以明文顯示密鑰。詳情請參閱顯示/隱藏密鑰章節。
`--soft-fail BOOLEAN`	執行掃描時不因違規而失敗，始終回傳非錯誤狀態碼。詳情請參閱軟性失敗章節。
`--severity-threshold [INFO\|LOW\|MEDIUM\|HIGH\|CRITICAL]`	僅顯示指定等級或更高級別的違規項目。
`--sca-scan`	指定要執行的 SCA 掃描類型（`package-vulnerabilities`/`license-compliance`）。預設為兩者皆執行。
`--monitor`	指定後，掃描結果將記錄於 Cycode 中。
`--cycode-report`	在主控台輸出中顯示 Cycode 平台上掃描報告的連結。
`--no-restore`	指定後，Cycode 將不會執行還原指令。這將僅掃描直接相依項目！
`--stop-on-error`	當任何檔案收集或相依項目還原失敗時中止掃描，而非跳過失敗的檔案並繼續。
`--gradle-all-sub-projects`	對所有子專案執行 Gradle 還原指令。此指令應從
`--maven-settings-file`	僅適用於 Maven，允許在掃描相依項目時使用自訂的 settings.xml 檔案
`--help`	顯示指定指令的選項。

指令	說明
commit-history	掃描提交歷史記錄，或在特定提交之間執行差異掃描
path	掃描指令中提供的路徑內的檔案
pre-commit	使用此指令掃描尚未提交的內容
repository	掃描 Git 儲存庫，包含其歷史記錄

選項

嚴重性選項

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

例如，以下指令將掃描儲存庫中嚴重性為「中」或更高的政策違規：

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

監控選項

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

若要將 SCA 類型掃描中發現的 SCA 政策相關掃描結果推送至 Cycode，請在掃描指令中加入引數 --monitor。

例如，以下指令將掃描儲存庫中的 SCA 政策違規，並將其推送至 Cycode 平台：

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

Cycode 報告選項

對於使用 Cycode CLI 執行的每次掃描，都會自動生成報告，並將其結果傳送至 Cycode。這些結果會與 Cycode 平台內的相關政策（例如，儲存庫掃描的 SCA 政策）關聯。

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

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

來自 CLI 的所有掃描結果都會顯示在 Cycode 的 CLI 日誌區段中。如果您在指令中包含了 --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

鎖定還原選項

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

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

以下生態系統支援自動鎖定檔還原：

生態系統	資訊清單檔案	生成的鎖定檔	調用的工具（當鎖定檔不存在時）
npm	`package.json`	`package-lock.json`	`npm install --package-lock-only --ignore-scripts --no-audit`
Yarn	`package.json`	`yarn.lock`	`yarn install --ignore-scripts`
pnpm	`package.json`	`pnpm-lock.yaml`	`pnpm install --ignore-scripts`
Deno	`deno.json` / `deno.jsonc`	`deno.lock`	（僅讀取現有鎖定檔）
Go	`go.mod`	`go.mod.graph`	`go list -m -json all` + `go mod graph`
Maven	`pom.xml`	`bcde.mvndeps`	`mvn dependency:tree`
Gradle	`build.gradle` / `build.gradle.kts`	`gradle-dependencies-generated.txt`	`gradle dependencies -q --console plain`
SBT	`build.sbt`	`build.sbt.lock`	`sbt dependencyLockWrite`
NuGet	`*.csproj`	`packages.lock.json`	`dotnet restore --use-lock-file`
Ruby	`Gemfile`	`Gemfile.lock`	`bundle --quiet`
Poetry	`pyproject.toml`	`poetry.lock`	`poetry lock`
Pipenv	`Pipfile`	`Pipfile.lock`	`pipenv lock`
PHP Composer	`composer.json`	`composer.lock`	`composer update --no-cache --no-install --no-scripts --ignore-platform-reqs`

如果鎖定檔已存在於資訊清單旁邊，Cycode 會直接讀取它，而不執行任何安裝指令。

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

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

錯誤時停止選項

預設情況下，即使檔案無法讀取（例如由於權限錯誤）或在 SCA 掃描期間無法生成相依鎖定檔，Cycode 仍會繼續掃描。失敗的項目會被跳過並發出警告，掃描會繼續處理其餘檔案。

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

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

這在 CI 管線中非常有用，因為靜默失敗會產生不完整的掃描結果。當觸發 --stop-on-error 時，您可以修復根本問題，或者（特別是針對 SCA 還原失敗）加入 --no-restore 來跳過鎖定檔生成，僅掃描直接相依項目。

使用 --stop-on-error 時，CLI 會透過退出碼區分掃描錯誤和政策違規：

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

儲存庫掃描

儲存庫掃描會檢查整個本機儲存庫中是否有任何暴露的密鑰或不安全的錯誤配置。這種更全面的掃描類型會檢查所有內容：儲存庫的當前狀態及其提交歷史記錄。它不僅會尋找儲存庫中當前暴露的密鑰，還會尋找先前已刪除的密鑰。

若要執行完整的儲存庫掃描，請執行以下指令：

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

路徑掃描

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

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

cycode scan path {{path}}

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

cycode scan path ~/home/git/codebase

Terraform 計劃掃描

Cycode CLI 支援 Terraform 計劃掃描（支援 Terraform 0.12 及更高版本）

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

如果您只有設定檔，可以透過以下步驟生成計劃：

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

terraform init
建立 Terraform 執行計劃並儲存二進位輸出：

terraform plan -out={tfplan_output}
將二進位輸出檔案轉換為可讀的 JSON：

terraform show -json {tfplan_output} > {tfplan}.json
使用 Cycode CLI 掃描您的 {tfplan}.json：

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

提交歷史掃描

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

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

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

密鑰掃描可以分析儲存庫歷史記錄中的所有提交，因為引入後又被移除的密鑰仍可能洩漏或暴露。對於 SCA 和 SAST 掃描，提交歷史指令專注於掃描提交之間的差異/變更，使其非常適合拉取請求審查和增量掃描。

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

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

cycode scan commit-history {{path}}

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

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

以下選項可與此指令搭配使用：

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

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

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

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

提交範圍語法

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

語法	說明	範例
`commit1..commit2`	從 commit1 到 commit2 的變更	`abc123..def456`
`commit1...commit2`	commit2 中有但 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 變更。

提交前掃描

提交前掃描會在您將變更提交至儲存庫之前自動識別任何問題。無需手動執行此掃描；請按照本指南的安裝章節中的詳細說明設定提交前掛鉤。

安裝提交前掛鉤後，您可能偶爾希望在特定提交期間跳過掃描。為此，請將以下內容新增至您的 git 命令中，以跳過單次提交的掃描：

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

推送前掃描

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

[!NOTE] 推送前掛鉤不適用於 IaC 掃描。

推送前掛鉤與 pre-commit 框架整合，可設定為在任何 git push 操作之前執行。

安裝推送前掛鉤

使用 pre-commit 框架設定推送前掛鉤：

安裝 pre-commit 框架（如果尚未安裝）：
```
pip3 install pre-commit
```

建立或更新您的 .pre-commit-config.yaml 檔案以包含推送前掛鉤：

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

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

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]

安裝推送前掛鉤：
```
pre-commit install --hook-type pre-push
```
成功安裝後將顯示訊息：Pre-push installed at .git/hooks/pre-push。
保持推送前掛鉤為最新版本：
```
pre-commit autoupdate
```

推送前掃描的運作方式

推送前掛鉤會：

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

智慧型預設分支偵測

推送前掛鉤會使用以下優先順序，智慧地偵測用於合併基底計算的預設分支：

環境變數：CYCODE_DEFAULT_BRANCH - 允許手動覆寫
Git 遠端 HEAD：使用 git symbolic-ref refs/remotes/origin/HEAD 來偵測實際的遠端預設分支
Git 遠端資訊：如果 symbolic-ref 失敗，則退回使用 git remote show origin
硬編碼的後備方案：使用常見的預設分支名稱（origin/main、origin/master、main、master）

設定自訂預設分支：

export CYCODE_DEFAULT_BRANCH=origin/develop

此智慧型偵測可確保推送前掛鉤能正確運作，無論您的儲存庫使用的是 main、master、develop 或任何其他預設分支名稱。

跳過推送前掃描

若要針對特定推送操作跳過推送前掃描，請使用：

SKIP=cycode-pre-push git push

或跳過所有推送前掛鉤：

git push --no-verify

[!TIP] 推送前掛鉤會在 git push 命令時觸發，且僅掃描即將推送的提交，這比掃描整個儲存庫更有效率。

從掃描中排除路徑

您可以使用 .cycodeignore 檔案來告訴 Cycode CLI 要從掃描中排除哪些檔案和目錄。它的運作方式就像 .gitignore 檔案一樣。這有助於您將掃描集中在相關程式碼上，並防止某些路徑在本機觸發違規。

運作方式

在您的工作資料夾中建立一個名為 .cycodeignore 的檔案。
使用與 .gitignore 相同的模式，列出您要排除的檔案和目錄。
將此檔案放置在您計劃執行 cycode scan 命令的目錄中。

[!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 [email protected]

在上述範例中，請將 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，其中 ~ 在 macOS 上表示使用者s home directory, for example, /Users/name`。

可以使用 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:
    - [email protected]
  secret:
    paths:
    - /Users/name/projects/build
    rules:
    - ce3a4de0-9dfc-448b-a004-c538cf8b4710
    shas:
    - a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
    values:
    - a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
    - 60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752

Report 指令

產生 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`	跳過鎖定檔還原，僅掃描直接相依項目。詳情請參閱鎖定還原選項。
`--gradle-all-sub-projects`	對所有子專案執行 Gradle 還原命令（從多專案 Gradle 建置的根目錄使用）。
`--maven-settings-file`	僅適用於 Maven，允許在建置相依樹時使用自訂的 settings.xml 檔案。

Import 指令

匯入 SBOM

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

此指令可使用下列選項：

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

例如：
cycode import sbom --name example-sbom --vendor cycode -label tag1 -label tag2 --owner [email protected] /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