Cycode
官方透過 SAST、SCA、機密與 IaC 掃描，使用 Cycode 提升開發生命週期中的安全性。
你可以用 Cycode MCP 做什麼？
- 掃描機密資訊 — 請助理使用
cycode_secret_scan掃描檔案或目錄中的硬編碼機密資訊。 - 掃描 SCA 問題 — 使用
cycode_sca_scan執行軟體組成分析掃描，檢查漏洞與授權問題。 - 掃描 IaC 設定錯誤 — 請助理使用
cycode_iac_scan檢查基礎架構即程式碼中的設定錯誤。 - 掃描 SAST 問題 — 使用
cycode_sast_scan執行靜態應用程式安全測試掃描，檢查程式碼品質與安全漏洞。 - 檢查 CLI 狀態 — 使用
cycode_status查詢 Cycode CLI 版本、驗證狀態與設定詳細資訊。
文件
Cycode CLI 使用者指南
Cycode 命令列介面 (CLI) 是一款可在本機安裝的應用程式，可掃描您的儲存庫，找出機密資訊、基礎架構即程式碼設定錯誤、軟體組成分析漏洞，以及靜態應用程式安全測試問題。
本指南將帶您了解安裝與使用方式。
目錄
- 必要條件
- 安裝
- Cycode CLI 命令
- 憑證與 Proxy
- MCP 命令
- Platform 命令
- AI Guardrails
- Scan 命令
- Report 命令
- Import 命令
- 掃描記錄
- 語法說明
必要條件
- Cycode CLI 應用程式需要 Python 3.10 或更新版本。
- 使用
cycode auth命令，透過 CLI 向 Cycode 驗證- 或者，您可以依照 Service Account Token 和 Personal Access Token 頁面中的步驟取得 Cycode Client ID 和 Client Secret Key；這些頁面詳細說明如何取得這些值。
安裝
以下安裝步驟適用於 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 client ID 和憑證（client secret 或 OIDC ID token）有三種方式：
- cycode auth（建議）
- cycode configure
- 將其新增至環境變數
使用 Auth 命令
[!NOTE] 這是設定本機電腦以透過 Cycode CLI 進行驗證的建議方式。
-
在終端機/命令列視窗中輸入以下命令：
cycode auth -
瀏覽器視窗會開啟，提示您登入 Cycode（如下所示）：
-
在此頁面輸入登入憑證並登入。
-
接著會前往下方頁面，要求您選擇要授權 Cycode 使用的業務群組（如適用）：
[!NOTE] 這會成為 Cycode CLI 的預設驗證方式。
-
按一下 Allow 按鈕，授權 Cycode CLI 使用所選的業務群組。
-
完成後，若選取成功，您會看到以下畫面：
-
關閉瀏覽器視窗後，終端機/命令列視窗會顯示以下內容：
Successfully logged into cycode
使用 Configure 命令
[!NOTE] 如果您已透過 Linux 或 Windows 環境變數設定 Cycode Client ID 和 Client Secret，這些憑證的優先順序會高於此方法。
-
在終端機/命令列視窗中輸入以下命令：
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 Client ID 值。
Cycode Client ID []: 7fe5346b-xxxx-xxxx-xxxx-55157625c72d -
輸入 Cycode Client Secret 值（若打算使用 OIDC ID token，請略過）。
Cycode Client Secret []: c1e24929-xxxx-xxxx-xxxx-8b08c1839a2e -
輸入 Cycode OIDC ID Token 值（選填）。
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 token（或另外提供）：
export CYCODE_ID_TOKEN={your Cycode OIDC ID token}
在 Windows 上
-
在控制台中，前往 System 功能表：
-
接著，按一下 Advanced system settings：
-
在開啟的 System Properties 視窗中，按一下 Environment Variables 按鈕：
-
建立
CYCODE_CLIENT_ID和CYCODE_CLIENT_SECRET變數，並分別填入您的 ID 和 Secret Key 值。如果您透過 OIDC 驗證，也請新增CYCODE_ID_TOKEN，並填入 OIDC ID token 值：
-
將
cycode.exe加入路徑，以完成安裝。
安裝 Pre-Commit Hook
您可以在本機儲存庫中設定 Cycode 的 pre-commit 和 pre-push hook，讓 Cycode CLI 應用程式在您提交或推送程式碼至程式碼庫之前，自動找出程式碼中的問題。
[!NOTE] IaC 掃描不支援 pre-commit 和 pre-push hook。
請執行以下步驟安裝 pre-commit hook：
安裝 Pre-Commit Hook
-
安裝 pre-commit 架構（必須安裝 Python 3.10 或更新版本）：
pip3 install pre-commit -
前往您要設定的本機 Git 儲存庫頂層目錄。
-
在儲存庫頂層目錄中建立名為
.pre-commit-config.yaml的新 YAML 檔案（包含開頭的.），並加入以下內容：repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode stages: [pre-commit] -
依照您的需求修改建立的檔案。使用 hook ID
cycode啟用 Secrets 掃描。使用 hook IDcycode-sca啟用 SCA 掃描。使用 hook IDcycode-sast啟用 SAST 掃描。若要啟用所有掃描類型，請使用以下設定：repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.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 hook 加入您的
.pre-commit-config.yaml檔案：repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.0 hooks: - id: cycode-pre-push stages: [pre-push] -
安裝 pre-push hook：
pre-commit install --hook-type pre-push -
若要同時使用 pre-commit 和 pre-push hook，請使用：
pre-commit install pre-commit install --hook-type pre-push
[!NOTE] Pre-push hook 會在
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 client ID。 |
--client-secret TEXT | 為此特定掃描執行指定 Cycode client secret。 |
--id-token TEXT | 為此特定掃描執行指定 Cycode OIDC ID token。 |
--install-completion | 為目前的 shell 安裝補全功能。 |
--show-completion [bash|zsh|fish|powershell|pwsh] | 顯示指定 shell 的補全設定，以便複製或自訂安裝方式。 |
-h, --help | 顯示指定命令的選項。 |
| Command | Description |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| auth | 驗證您的機器，以將 CLI 與您的 Cycode 帳戶關聯。 |
| configure | 用於設定 CLI 用戶端驗證的初始命令。 |
| ignore | 忽略特定值、路徑或規則 ID。 |
| mcp | 啟動 Model Context Protocol (MCP) 伺服器，讓 AI 整合 Cycode 掃描功能。 |
| scan | 掃描內容中的 Secrets/IaC/SCA/SAST 違規。您`ll 需要指定要執行的掃描類型：commit-history/path/repository 等。 |
| report | 產生報告。您需要指定要產生的報告類型，例如 SBOM。 |
| status | 顯示 CLI 狀態並結束。 |
憑證與 Proxy
依預設，Cycode CLI 會使用隨附於 CLI 的 CA 套件組驗證 HTTPS 連線。
如果您的組織使用會檢查 HTTPS 流量的 Proxy，或使用具有自有 CA 的內部部署安裝，您有兩種選擇。
選項 1 — 使用已安裝在機器上的憑證。 如果您的 CA 位於機器憑證存放區中（受管理裝置通常如此），請選擇啟用：
export CYCODE_CLI_ENABLE_TRUSTSTORE=1
接著，CLI 會使用 Windows 憑證存放區、macOS Keychain 或 Linux 上的系統 CA 目錄進行驗證，且不需要設定憑證路徑。
[!IMPORTANT] 此功能刻意設為選擇啟用。信任機器存放區代表信任該機器上的所有根憑證，包括管理員或惡意軟體安裝的憑證。只有在確定信任機器的憑證存放區時才啟用。
選項 2 — 指定 CLI 使用 CA 套件組檔案。 不必選擇啟用即可使用：
| Environment Variable | Description |
|---|---|
REQUESTS_CA_BUNDLE | 要信任的 CA 套件組檔案路徑（.pem 或 .crt）。 |
CURL_CA_BUNDLE | REQUESTS_CA_BUNDLE 的別名，僅在後者未設定時採用。 |
兩種選項可以搭配使用：使用 CYCODE_CLI_ENABLE_TRUSTSTORE=1 時，會信任來自
REQUESTS_CA_BUNDLE 的憑證，並且是額外信任，而非取代機器存放區。
[!TIP] 使用
-v執行任何命令，即可查看目前使用的信任來源，例如cycode -v status。
注意事項：
- 在 Windows 上，若未設定
REQUESTS_CA_BUNDLE或CURL_CA_BUNDLE，CLI 一直會回退使用系統憑證存放區。此行為維持不變。 - Proxy 本身使用標準的
HTTP_PROXY、HTTPS_PROXY和NO_PROXY環境變數設定。
MCP 命令 [EXPERIMENT]
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環境變數。
啟動 MCP 伺服器
若要啟動 MCP 伺服器，請使用以下命令：
cycode mcp
依預設，伺服器會使用 stdio 傳輸方式啟動，適用於本機整合，以及能夠啟動子程序的 AI 應用程式。
可用選項
| Option | Description |
|---|---|
-t, --transport | MCP 伺服器的傳輸類型：stdio、sse 或 streamable-http（預設：stdio） |
-H, --host | 要繫結伺服器的主機位址（僅用於非 stdio 傳輸）（預設：127.0.0.1） |
-p, --port | 要繫結伺服器的連接埠號碼（僅用於非 stdio 傳輸）（預設：8000） |
--help | 顯示說明訊息和可用選項 |
MCP 工具
MCP 伺服器提供下列 AI 系統可使用的工具：
| Tool Name | Description |
|---|---|
cycode_secret_scan | 掃描硬編碼的密鑰 |
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 引擎會處理檔案探索和篩選，與 CLI 中的cycode scan -t <type> path ./src相同。files（備用） — 將檔案路徑對應至完整字串內容的字典。僅在檔案無法於磁碟上取得時使用（例如尚未儲存的記憶體內編輯）。
[!TIP] 請盡可能使用
paths。將大型檔案（例如package-lock.json）作為內嵌內容傳遞，可能會超出 token 限制並拖慢 AI 用戶端。使用paths時，Cycode 引擎會直接從磁碟讀取檔案。
所有掃描工具都會傳回 JSON 物件，其中包含 "summary" 欄位，提供易讀的違規數量（例如 "Cycode found 3 violations: 1 CRITICAL, 2 HIGH."），以及完整的 "detections" 陣列。
使用範例
基本命令範例
使用預設設定啟動 MCP 伺服器（stdio 傳輸）：
cycode mcp
明確指定 stdio 傳輸以啟動 MCP 伺服器：
cycode mcp -t stdio
使用 Server-Sent Events (SSE) 傳輸啟動 MCP 伺服器：
cycode mcp -t sse -p 8080
在自訂主機和連接埠上使用 streamable HTTP 傳輸啟動 MCP 伺服器：
cycode mcp -t streamable-http -H 0.0.0.0 -p 9000
如需 MCP 傳輸類型的詳細資訊，請參閱 MCP Protocol Specification – Transports。
設定範例
在 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 傳輸（Server-Sent Events）：
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8000/sse"
}
}
}
在自訂連接埠上使用 SSE 傳輸：
{
"mcpServers": {
"cycode": {
"url": "http://127.0.0.1:8080/sse"
}
}
}
streamable 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"
}
}
}
streamable 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 環境）
如果 MCP 用戶端中斷長時間執行的掃描，請增加工具呼叫逾時時間。
| Environment Variable | Description |
|---|---|
MCP_TOOL_TIMEOUT | MCP 用戶端（例如 Claude 和 GitHub Copilot）等待工具呼叫完成的逾時時間（秒）。如果長時間執行的掃描在完成前遭到中斷，請增加此值。 |
在企業 Proxy 後方時，請在 MCP 伺服器的 env 區塊中設定憑證變數。如需選項，請參閱
憑證與 Proxy：使用 CYCODE_CLI_ENABLE_TRUSTSTORE=1 採用機器上已有的憑證，或使用
REQUESTS_CA_BUNDLE 指向 CA 套件組檔案。
使用自訂 CA 套件組和較長逾時時間的 mcp.json 設定範例：
{
"mcpServers": {
"cycode": {
"command": "cycode",
"args": ["mcp"],
"env": {
"REQUESTS_CA_BUNDLE": "/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 伺服器發生問題，您可以啟用偵錯記錄，以取得更詳細的執行資訊。啟用偵錯記錄有兩種方式：
- 使用
-v或--verbose旗標：
cycode -v mcp
- 使用
CYCODE_CLI_VERBOSE環境變數：
CYCODE_CLI_VERBOSE=1 cycode mcp
偵錯記錄會顯示以下詳細資訊：
- 伺服器啟動和設定
- 連線嘗試和狀態
- 工具執行和結果
- 發生的任何錯誤或警告
這些資訊有助於：
- 診斷連線問題
- 了解特定工具無法運作的原因
- 找出驗證問題
- 偵錯傳輸方式相關問題
MCP 設定
Platform 命令 [BETA]
[!WARNING]
platform命令目前處於測試版。命令、引數和輸出格式會根據 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>
首次使用時，系統會從 Cycode API 擷取 OpenAPI 規格，並快取於 ~/.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
平台範例
# 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'
平台注意事項與限制
- 目前為唯讀。 此 Beta 版僅公開
GET端點。 - 由規格驅動。 在 API 中新增端點後，下次重新整理快取時便會自動顯示。
- 不隨附規格。 安裝後（或 24 小時快取到期後）首次呼叫
cycode platform時會透過網路擷取資料。若連線速度較慢，首次呼叫可能需要幾秒；之後的呼叫在快取到期前幾乎會立即完成。 - 使用
CYCODE_SPEC_CACHE_TTL=<seconds>覆寫快取 TTL。
AI 防護措施 [BETA]
AI 防護措施會在支援的 AI 程式碼代理（Claude Code、Cursor、Copilot、Codex）中安裝掛鉤，以便在提示、代理讀取的檔案及 MCP 工具引數送達模型之前，掃描其中是否含有機密資訊。
AI 防護措施收集的資料
掃描在伺服器端進行，因此掃描內容會離開本機：提示文字、代理讀取的檔案內容，以及 MCP 工具引數都會傳送至您的 Cycode 租用戶，以檢查是否含有機密資訊。
每個事件也會附上開發人員與機器的相關資訊，以便將發現項目歸屬至來源裝置與使用者。其中部分資訊屬於個人資料：
- 裝置識別資訊 — 機器的主機名稱與硬體序號。
- 使用者識別資訊 — 登入 AI 程式碼代理之使用者的電子郵件地址，以及本機作業系統使用者名稱。
- 環境詳細資料 — 作業系統及版本、AI 代理、其版本與使用中的模型、代理 MCP 設定檔的內容，以及已啟用的外掛程式。
硬體序號會快取在本機暫存檔案中，且只有執行命令的使用者可以讀取，因此重複呼叫掛鉤時不會再次查詢硬體。
如果您的環境不允許收集這些資料，請勿安裝防護措施掛鉤（cycode ai-guardrails uninstall 可移除已安裝的掛鉤）。
掃描命令
執行掃描
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/unmaintained-packages/malicious-packages）。預設為全部。 |
--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 | 掃描尚未提交的內容；也支援透過旗標進行本機差異掃描（適合 IDE） |
| 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 Logs 區段中。如果您在命令中加入 --cycode-report 旗標，掃描結果之後便會在終端機中顯示特定報告的直接連結。
[!WARNING] 您必須在 Cycode 中具有
owner或admin角色，才能檢視此頁面。
報告頁面看起來會像以下範例：
套件弱點選項
[!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 掃描。
若只要掃描未維護的套件（其 OpenSSF Scorecard Maintained 檢查分數偏低，表示近期提交與問題活動很少或完全沒有），請在 -t sca 或 --scan-type sca 選項後加入引數 --sca-scan unmaintained-packages。
[!NOTE] 是否回報未維護的套件由您組織的原則控制。此選項會縮小掃描回報的範圍；無法啟用租用戶中已關閉的原則。
在前一個範例中，若只想對未維護的套件執行 SCA 掃描，可以執行以下命令：
cycode scan -t sca --sca-scan unmaintained-packages repository ~/home/git/codebase
惡意套件選項
[!NOTE] 此選項僅適用於 SCA 掃描。
若只要掃描惡意套件（安全公告已將其識別為惡意軟體，而非僅有弱點的相依性），請在 -t sca 或 --scan-type sca 選項後加入引數 --sca-scan malicious-packages。
惡意套件違規一律會回報為 Critical，且不會附帶 CVSS 分數或修正版本：唯一的補救方式是移除該相依性。
[!NOTE] 是否回報惡意套件由您組織的原則控制。此選項會縮小掃描回報的範圍；無法啟用租用戶中已關閉的原則。
在前一個範例中，若只想對惡意套件執行 SCA 掃描，可以執行以下命令：
cycode scan -t sca --sca-scan malicious-packages repository ~/home/git/codebase
鎖定檔還原選項
[!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 |
| pip | pyproject.toml / requirements.txt | pylock.toml | pip lock . / pip lock -r requirements.txt -o pylock.toml |
| 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>`
此命令可使用以下選項：
| 選項 | 說明 |
|---|---|
-b, --base-ref TEXT | 要比較差異的 Git ref（提交、分支或標籤）；預設為 HEAD，與提交前掛鉤的行為一致 |
--include-unstaged | 也掃描已追蹤檔案中尚未暫存的變更，而不只掃描已暫存的內容；預設為關閉 |
--path PATH | 用於限定差異掃描範圍的選用路徑；可重複指定；預設為整個工作目錄 |
本機差異掃描（IDE 整合）
--base-ref 和 --include-unstaged 會將 pre-commit 轉變為通用的本機差異掃描：比較任意提交（預設為 HEAD）與您目前的工作目錄，包括尚未暫存的編輯內容。此功能適用於 IDE 外掛程式及其他需要在您工作時持續提供即時回饋的工具，而非 Git 掛鉤流程。搭配 --include-unstaged 使用時，--path 可讓 IDE 將掃描範圍限定為編輯器中目前開啟的檔案。
[!NOTE] IaC 掃描不支援本機差異掃描（透過這些旗標）。
掃描目前所有變更（已暫存 + 未暫存），並與上一次提交比較：
cycode scan pre-commit --include-unstaged
掃描與特定提交或分支之間的變更：
cycode scan pre-commit --include-unstaged --base-ref main
只掃描特定檔案（例如 IDE 中目前開啟的檔案）：
cycode scan pre-commit --include-unstaged --path src/app.py
推送前掃描
推送前掃描會在您將變更推送至遠端儲存庫之前，自動找出任何問題。此掛鉤會在用戶端執行，且只掃描即將推送的提交，因此能有效率地在問題抵達遠端儲存庫之前將其找出。
[!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.25.0 hooks: - id: cycode-pre-push stages: [pre-push] -
若要使用多種掃描類型，請使用以下設定：
repos: - repo: https://github.com/cycodehq/cycode-cli rev: v3.25.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
推送前掃描的運作方式
此掛鉤會逐一掃描每個即將推送的提交，因此即使某個密鑰在一個提交中新增、並在後續提交中移除，仍會被偵測到。透過 pre-commit 架構安裝時，推送範圍會由該架構提供：對於現有分支，範圍是遠端分支之後的新提交；對於新分支，則是尚未推送至遠端的提交（推送至空的遠端時則為所有提交）。若從手寫的 .git/hooks/pre-push 執行，範圍會從 git 的掛鉤輸入讀取；新分支則會從其與預設分支的合併基底開始掃描（請參閱下文）。
沒有可掃描內容的推送，例如標籤、分支刪除和已是最新狀態的推送，會直接通過而不執行掃描。如果掛鉤無法判斷推送內容，則會失敗並阻止推送，而不是無聲地放行。
Cycode 推送前掛鉤會設定 always_run: true 和 pass_filenames: false，因為掃描範圍是即將推送的提交，而非檔案清單。若未設定 always_run，當即將推送的提交合計沒有變更檔案時（例如某個密鑰在一個提交中新增，並在下一個提交中刪除），pre-commit 架構會略過此掛鉤。若未設定 pass_filenames: false，架構會將掃描不使用的變更檔案名稱傳入；大型推送時，還會將檔案分批，並針對每一批執行一次完整掃描。如果您自行定義掛鉤（例如定義為 repo: local 掛鉤），請設定這兩個選項。
智慧型預設分支偵測
從手寫的掛鉤執行時，推送前掃描會依照以下優先順序偵測用於計算合併基底的預設分支：
- 環境變數：
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 或任何其他預設分支名稱，pre-push hook 都能正常運作。
略過 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 檔案相同。這有助於您專注掃描相關程式碼，並避免特定路徑在本機觸發違規。
運作方式
- 在工作資料夾中建立名為
.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。
掃描結果範例
Secrets 結果範例
╭─────────────────────────────────────────────────────────────── 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 掃描中忽略特定路徑，您需要搭配 -t, --scan-type 旗標使用 --by-path 旗標（必須指定掃描類型）。這會在該掃描類型的所有後續掃描中忽略指定路徑。使用以下命令新增要忽略的路徑：
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 規則，您需要搭配 -t, --scan-type 旗標使用 --by-rule 旗標（必須指定掃描類型）。這會在所有後續掃描中忽略指定的規則 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 掃描中忽略特定套件，您需要搭配 -t, --scan-type 旗標使用 --by-package 旗標（必須指定 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 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:
- pyyaml@5.3.1
secret:
paths:
- /Users/name/projects/build
rules:
- ce3a4de0-9dfc-448b-a004-c538cf8b4710
shas:
- a44081db3296c84b82d12a35c446a3cba19411dddfa0380134c75f7b3973bff0
values:
- a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
- 60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752
Report Command
產生 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 Command
匯入 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 example@cycode.com /path/to/local/project
掃描記錄
所有 CLI 掃描都會記錄在 Cycode 中。您可以在 Settings > CLI Logs 下找到這些記錄。
語法說明
您可以隨時將 --help 引數新增至任何命令，以查看顯示可用選項及其語法的說明訊息。
若要查看一般說明，只需輸入命令：
cycode --help
若要查看掃描選項，請輸入：
cycode scan --help
若要查看特定掃描類型的可用選項，請輸入：
cycode scan {{option}} --help
例如，若要查看路徑掃描的可用選項，請輸入：
cycode scan path --help
若要查看忽略掃描功能的可用選項，請使用此命令：
cycode ignore --help
若要查看報告的可用選項，請使用此命令：
cycode report --help
若要查看特定報告類型的可用選項，請輸入：
cycode scan {{option}} --help