🚀 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