Cycode Cli

🚀 Cycode CLI 用戶指南

Cycode 命令行界面（CLI）是一款可在本地安裝的應用程序，用於掃描代碼倉庫，檢測其中是否存在密鑰信息、基礎設施即代碼（IaC）的錯誤配置、軟件成分分析（SCA）漏洞以及靜態應用安全測試（SAST）問題。本指南將帶領您瞭解該工具的安裝和使用方法。

🚀 快速開始

Cycode CLI 是一款強大的代碼掃描工具，能檢測代碼中多種安全問題。使用前需確保滿足相關前置條件，再按照安裝步驟完成安裝，之後就可以根據需求選擇合適的掃描命令進行代碼掃描。

✨ 主要特性

• 多類型掃描：支持對代碼倉庫進行密鑰信息、基礎設施即代碼（IaC）的錯誤配置、軟件成分分析（SCA）漏洞以及靜態應用安全測試（SAST）問題的掃描。
• 多種掃描方式：提供倉庫掃描、路徑掃描、提交歷史掃描、預提交掃描等多種掃描方式，滿足不同場景需求。
• 自定義配置：可以通過配置文件或命令行參數自定義掃描規則，如忽略特定的密鑰值、路徑、規則等。
• 詳細報告：掃描結果會生成詳細的報告，包括問題的嚴重程度、所在文件、代碼片段等信息，方便定位和解決問題。

📦 安裝指南

前置條件

• Cycode CLI 應用程序需要 Python 3.9 或更高版本。
• 使用 [cycode auth 命令](#using-the-auth-command) 來通過 CLI 對 Cycode 進行身份驗證。
  • 或者，您可以通過遵循 服務賬戶令牌 和 個人訪問令牌 頁面中詳細的步驟來獲取 Cycode 客戶端 ID 和客戶端密鑰，這些頁面包含了獲取這些值的詳細信息。

安裝 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 和客戶端密鑰：
   • cycode auth（推薦）
   • cycode configure
   • 將它們添加到 環境變量 中

使用 auth 命令

⚠️ 重要提示

這是在本地機器上設置與 Cycode CLI 進行身份驗證的 推薦 方法。

1. 在終端/命令行窗口中輸入以下命令： cycode auth
2. 會彈出一個瀏覽器窗口，要求您登錄 Cycode。
3. 在該頁面輸入您的登錄憑據並登錄。
4. 最終您將進入一個頁面，要求您選擇要授權 Cycode 使用的業務組（如果適用）。

   ⚠️ 重要提示

   這將是與 Cycode CLI 進行身份驗證的默認方法。

5. 點擊 允許 按鈕，以授權 Cycode CLI 在所選業務組上使用。
6. 完成後，如果選擇成功，您將看到相應的屏幕提示。
7. 在終端/命令行屏幕上，退出瀏覽器窗口時將看到以下內容： Successfully logged into cycode

使用 configure 命令

⚠️ 重要提示

如果您已經通過 Linux 或 Windows 環境變量設置了 Cycode 客戶端 ID 和客戶端密鑰，這些憑據將優先於此方法。

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 客戶端 ID 值。 Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d
5. 輸入您的 Cycode 客戶端密鑰值。 Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e
6. 如果值輸入成功，您將看到以下消息： 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}

在 Windows 上

1. 從控制面板中，導航到系統菜單。
2. 接下來，點擊“高級系統設置”。
3. 在打開的“系統屬性”窗口中，點擊“環境變量”按鈕。
4. 創建 CYCODE_CLIENT_ID 和 CYCODE_CLIENT_SECRET 變量，並分別將其值設置為您的 ID 和密鑰。
5. 將 cycode.exe 添加到路徑中以完成安裝。

安裝預提交鉤子

Cycode 的預提交鉤子可以在您的本地倉庫中設置，以便 Cycode CLI 應用程序在您將代碼提交到代碼庫之前自動識別代碼中的任何問題。

⚠️ 重要提示

預提交鉤子不適用於 IaC 掃描。

執行以下步驟安裝預提交鉤子：

1. 安裝預提交框架（必須安裝 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.2.0
       hooks:
         - id: cycode
           stages:
             - pre-commit
   

4. 根據您的具體需求修改創建的文件。使用鉤子 ID cycode 啟用密鑰掃描。使用鉤子 ID cycode-sca 啟用 SCA 掃描。使用鉤子 ID cycode-sast 啟用 SAST 掃描。如果您想啟用所有掃描類型，請使用以下配置：

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

5. 安裝 Cycode 的鉤子：

   pre-commit install
   

   鉤子安裝成功後將顯示消息：Pre-commit installed at .git/hooks/pre-commit。
6. 保持預提交鉤子為最新狀態：

   pre-commit autoupdate
   

   它將自動將 .pre-commit-config.yaml 中的 rev 更新到 Cycode CLI 的最新可用版本。

⚠️ 重要提示

觸發操作發生在 git commit 命令上。 鉤子僅對暫存提交的文件觸發。

💻 使用示例

基礎用法

以下是一些常見命令的基礎用法示例：

身份驗證

cycode auth

配置 CLI

cycode configure

掃描倉庫

cycode scan repository ~/home/git/codebase

高級用法

啟動 MCP 服務器

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

掃描指定類型並顯示詳細日誌

cycode scan -t sca --severity-threshold HIGH --verbose repository ~/home/git/codebase

📚 詳細文檔

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 客戶端密鑰。
--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	掃描內容中的密鑰、IaC、SCA、SAST 違規。您需要指定要執行的掃描類型：提交歷史、路徑、倉庫等。
report	生成報告。您需要指定要生成的報告類型，如 SBOM。
status	顯示 CLI 狀態並退出。

MCP 命令 [實驗性]

⚠️ 重要提示

MCP 命令僅適用於 Python 3.10 及以上版本。如果您使用的是較早的 Python 版本，此命令將不可用。

模型上下文協議（MCP）命令允許您啟動一個 MCP 服務器，該服務器將 Cycode 的掃描功能暴露給 AI 系統和應用程序，使 AI 模型能夠通過標準化協議與 Cycode CLI 工具進行交互。

💡 使用建議

為獲得最佳體驗，使用 pip install cycode 或 brew install cycode 在系統上全局安裝 Cycode CLI，然後使用 cycode auth 進行一次身份驗證。全局安裝和身份驗證後，您無需在 MCP 配置文件中配置 CYCODE_CLIENT_ID 和 CYCODE_CLIENT_SECRET 環境變量。

啟動 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 版本、身份驗證狀態和配置信息

使用示例

基本命令示例

• 使用默認設置（stdio 傳輸）啟動 MCP 服務器：

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 協議規範 - 傳輸。

配置示例

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

⚠️ 重要提示

對於歐盟 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"
      }
    }
  }
}

• 對於 stdio 傳輸 並使用 pipx 安裝：

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

• 對於 stdio 傳輸 並使用 uvx 安裝：

{
  "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 傳輸（先啟動服務器，然後配置客戶端）：

# 在後臺啟動 MCP 服務器
cycode mcp -t sse -p 8000 &

# 在 mcp.json 中配置
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.1:8000/sse"
    }
  }
}

• 對於 可流式 HTTP 傳輸：

# 在後臺啟動 MCP 服務器
cycode mcp -t streamable-http -H 127.0.0.2 -p 9000 &

# 在 mcp.json 中配置
{
  "mcpServers": {
    "cycode": {
      "url": "http://127.0.0.2:9000/mcp"
    }
  }
}

⚠️ 重要提示

MCP 服務器需要正確的 Cycode CLI 身份驗證才能正常工作。在啟動 MCP 服務器之前，請確保您已使用 cycode auth 進行身份驗證或配置了您的憑據。

MCP 故障排除

如果您在使用 MCP 服務器時遇到問題，可以啟用調試日誌以獲取更詳細的信息。有兩種方法可以啟用調試日誌：

1. 使用 -v 或 --verbose 標誌：

cycode -v mcp

2. 使用 CYCODE_CLI_VERBOSE 環境變量：

CYCODE_CLI_VERBOSE=1 cycode mcp

調試日誌將顯示以下詳細信息：

• 服務器啟動和配置
• 連接嘗試和狀態
• 工具執行和結果
• 發生的任何錯誤或警告

這些信息在以下情況下可能會有所幫助：

• 診斷連接問題
• 瞭解某些工具無法正常工作的原因
• 識別身份驗證問題
• 調試特定傳輸問題

掃描命令

運行掃描

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 將不運行恢復命令。這將僅掃描直接依賴項！
--gradle-all-sub-projects	為所有子項目運行 Gradle 恢復命令。此命令應從相應目錄運行。
--maven-settings-file	僅適用於 Maven，允許在掃描依賴項時使用自定義的 settings.xml 文件。
--help	顯示給定命令的選項。

命令	詳情
commit-history	掃描此 Git 倉庫中的所有提交歷史記錄
path	掃描命令中指定路徑下的文件
pre-commit	使用此命令掃描尚未提交的內容
repository	掃描 Git 倉庫，包括其歷史記錄

選項詳情

嚴重程度閾值選項

要將掃描結果限制在特定的嚴重程度閾值，可以在掃描命令中添加 --severity-threshold 參數。 例如，以下命令將掃描倉庫中嚴重程度為中等或更高的策略違規： cycode scan --severity-threshold MEDIUM repository ~/home/git/codebase

監控選項

⚠️ 重要提示

此選項僅適用於 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 標誌，掃描結果後將在終端中顯示特定報告的直接鏈接。

⚠️ 重要提示

您必須在 Cycode 中具有 owner 或 admin 角色才能查看此頁面。

報告頁面將類似於以下內容：

包漏洞選項

⚠️ 重要提示

此選項僅適用於 SCA 掃描。

要掃描本地倉庫中的特定包漏洞，可以在 -t sca 或 --scan-type sca 選項後添加 --sca-scan package-vulnerabilities 參數。 在前面的示例中，如果您只想對包漏洞執行 SCA 掃描，可以執行以下命令： cycode scan -t sca --sca-scan package-vulnerabilities repository ~/home/git/codebase

許可證合規選項

⚠️ 重要提示

此選項僅適用於 SCA 掃描。

要掃描本地倉庫的特定分支，可以在 --sca-scan license-compliance 參數後指定要掃描的分支名稱。 在前面的示例中，如果您只想掃描名為 dev 的分支，可以執行以下命令： cycode scan -t sca --sca-scan license-compliance repository ~/home/git/codebase -b dev

鎖定恢復選項

⚠️ 重要提示

此選項僅適用於 SCA 掃描。

我們使用 sbt-dependency-lock 插件為 SBT 項目恢復鎖定文件。要禁用鎖定恢復，請使用 --no-restore 選項。

前提條件：

• sbt-dependency-lock 插件：通過在 project/plugins.sbt 中添加以下行來安裝該插件：

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

倉庫掃描

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

要執行完整的倉庫掃描，請執行以下命令： 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 擴展名）。

如果您只有配置文件，可以通過以下步驟生成計劃：

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

提交歷史掃描

⚠️ 重要提示

密鑰掃描會分析倉庫歷史記錄中的所有提交，因為引入後又刪除的密鑰仍然可能會被洩露或暴露。SCA 和 SAST 掃描僅關注最新的代碼狀態以及分支或拉取請求之間的更改。SCA 和 SAST 不會執行完整的提交歷史掃描。

提交歷史掃描僅限於本地倉庫的先前提交，重點是在提交歷史記錄中查找任何密鑰，而不是檢查倉庫的當前狀態。

要執行提交歷史掃描，請執行以下命令： cycode scan commit-history {{path}}

例如，假設您要掃描存儲在 ~/home/git/codebase 中的倉庫的提交歷史記錄。您可以執行以下命令： cycode scan commit-history ~/home/git/codebase

此命令可用的選項如下：

選項	詳情
-r, --commit-range TEXT	掃描此 Git 倉庫中的提交範圍，默認情況下，cycode 會掃描所有提交歷史記錄（例如：HEAD~1）

提交範圍選項

默認情況下，提交歷史掃描會檢查倉庫的整個提交歷史記錄，一直追溯到初始提交。您可以通過添加 --commit-range（-r）參數，後跟您指定的名稱，將掃描限制在特定的提交範圍。

在前面的示例中，如果您只想掃描倉庫中的特定提交，可以執行以下命令： cycode scan commit-history -r {{from-commit-id}}...{{to-commit-id}} ~/home/git/codebase

預提交掃描

預提交掃描會在您將更改提交到倉庫之前自動識別任何問題。無需手動執行此掃描；按照本指南的安裝部分詳細說明配置預提交鉤子即可。

安裝預提交鉤子後，您可能偶爾希望在特定提交期間跳過掃描。要做到這一點，請在 git 命令中添加以下內容，以跳過單次提交的掃描：

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

掃描結果

每次掃描完成後，會顯示一條消息，說明是否發現任何問題。

如果未發現問題，掃描將以以下成功消息結束： 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 門戶在相關策略中設置了自定義修復指南，您將看到一個“公司指南”字段，其中包含您添加的修復指南。請注意，如果您沒有添加任何公司指南，此工具將不會顯示該字段。

忽略掃描結果

可以添加忽略規則來忽略特定的密鑰值、特定的 SHA512 值、特定的路徑以及特定的 Cycode 密鑰和 IaC 規則 ID。這樣，掃描將不會對這些值發出警報。忽略規則會以本地方式寫入並保存在 ./.cycode/config.yaml 文件中。

⚠️ 重要提示

在添加要忽略的值時，應仔細考慮這些值、路徑和策略，以確保掃描能夠檢測到真正的問題。

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。

忽略包

⚠️ 重要提示

此選項僅適用於 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，其中 ~ 表示用戶的主目錄，例如，在 macOS 上為 /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。

⚠️ 重要提示

“按值忽略”的值不會以明文形式存儲！ 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

掃描日誌

所有 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