DataDog/datadog-static-analyzer

# Datadog 静态分析器 datadog-static-analyzer 是 Datadog [静态分析](https://www.datadoghq.com/code-analysis/)的静态分析引擎。 ## 如何使用 Datadog 静态分析工具 ### 快速开始 #### 在 macOS 上安装 在 macOS 上，你可以使用 Homebrew 安装静态分析器： ``` brew install datadog-static-analyzer ``` #### 在其他平台上安装 1. 从 [releases](https://github.com/DataDog/datadog-static-analyzer/releases) 下载二进制文件 2. 解压并在你的代码仓库上运行分析器（如下所示） #### 运行分析器 安装完成后，使用默认规则运行分析器： ``` datadog-static-analyzer --directory /path/to/directory --output report.csv --format csv ``` #### 使用 Docker ``` docker run -it --rm -v /path/to/directory:/data ghcr.io/datadog/datadog-static-analyzer:latest --directory /data --output /data/report.csv --format csv ``` 关于 Docker 容器的更多信息，请参阅[此处的文档](./doc/docker-container.md)。 如果你遇到问题，请先阅读[常见问题解答](FAQ.md)，其中可能包含你问题的解决方案。 ### 高级用法 你可以通过创建 `static-analysis.datadog.yml` 文件来选择用于扫描代码仓库的规则。 首先，请确保遵循[文档](https://docs.datadoghq.com/code_analysis/static_analysis)并在项目根目录下创建一个包含你想要使用的规则集的 `static-analysis.datadog.yml` 文件。 所有规则都可以在 [Datadog 文档](https://docs.datadoghq.com/security/code_security/static_analysis/static_analysis_rules/)中找到。你的 `static-analysis.datadog.yml` 应仅包含 [Datadog 文档](https://docs.datadoghq.com/security/code_security/static_analysis/static_analysis_rules/)中可用的规则集。 YAML 文件示例 ``` schema-version: v1 rulesets: - python-code-style - python-best-practices - python-inclusive ignore: - tests ``` ### CI/CD 集成 你可以使用我们的集成将其用于 CI/CD 流水线中： - [GitHub Action](https://github.com/DataDog/datadog-static-analyzer-github-action) - [CircleCI ORB](https://circleci.com/developer/orbs/orb/datadog/datadog-static-analyzer-circleci-orb) 如果你在自己的 CI/CD 流水线中使用它，可以直接集成该工具：请参阅 [Datadog 文档了解更多信息](https://docs.datadoghq.com/security/code_security/static_analysis/setup)。 ### IntelliJ JetBrains 产品 [Datadog IntelliJ 扩展](https://plugins.jetbrains.com/plugin/19495-datadog) 允许你直接在所有 JetBrains 产品中使用静态分析器。 创建一个 `static-analysis.datadog.yml` 文件，下载扩展程序，即可开始使用。你可以在下面看到一个示例，展示了在使用 Python 的 requests 模块获取数据时添加 timeout 的建议。  ### VS Code [Datadog VS Code 扩展](https://marketplace.visualstudio.com/items?itemName=Datadog.datadog-vscode) 允许你直接从 VS Code 中使用静态分析器。 创建一个 `static-analysis.datadog.yml` 文件，下载扩展程序，即可开始使用。  ## 规则集列表 当你在 Datadog 产品上进行入门设置时，你可以选择你想要/需要的规则集。如果你不直接使用 Datadog，这里是 Datadog 静态分析产品中按语言分类的常用规则集列表。 完整列表可在[我们的文档](https://docs.datadoghq.com/security/code_security/static_analysis/static_analysis_rules/)中找到。 规则集列表可在 [RULESETS.md](RULESETS.md) 中找到。 ## 下载 从 [发布页面](https://github.com/DataDog/datadog-static-analyzer/releases/latest) 下载适用于你的系统和架构的最新版本。 要通过 shell 获取静态分析器： ``` curl -L -O https://www.github.com/DataDog/datadog-static-analyzer/releases/latest/download/datadog-static-analyzer-.zip ``` 获取 Linux x86_64 二进制文件的示例： ``` curl -L -O https://www.github.com/DataDog/datadog-static-analyzer/releases/latest/download/datadog-static-analyzer-x86_64-unknown-linux-gnu.zip ``` ## 用法 ``` datadog-static-analyzer -i -o ``` 为了使工具正常工作，你必须有一个 `/static-analysis.datadog.yml` 文件来定义分析器的配置。该文件将指示你用于项目的规则。 你可以在 [Datadog 文档](https://docs.datadoghq.com/security/code_security/static_analysis/setup) 中获取有关配置的更多信息。 ### Mac OS X 用户 如果你是通过 Homebrew (`brew install datadog-static-analyzer`) 安装的，可以跳过此部分。 如果你是手动下载的二进制文件，则无法直接执行。你需要使用以下命令将二进制文件标记为可安全执行： ``` xattr -dr com.apple.quarantine datadog-static-analyzer ``` ## 选项 - `-f` 或 `--format`：输出文件的格式。`-f sarif` 生成一个 [符合 SARIF 标准的文件](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sarif) - `-r` 或 `--rules`：提供包含所有规则的文件（可以使用 `datadog-export-rulesets` 将规则放入文件中） - `-c` 或 `--cpus`：用于分析的核心数（每个核心大约占用 1GB 内存） - `-o` 或 `--output`：输出文件 - `-p` 或 `--ignore-path`：要忽略的路径（模式/glob）；支持多个 - `-x` 或 `--performance-statistics`：显示分析器的性能统计信息 - `-g` 或 `--add-git-info`：在使用 -f sarif 时，将 Git 相关信息（sha 等）添加到 SARIF 报告中 - `--fail-on-any-violation`：如果存在给定严重级别的违规，则使程序以非零退出代码退出。 - `-w` 或 `--diff-aware`：启用差异感知扫描（请参阅下面的专门说明） ## 配置 设置以下变量以配置分析： - `DD_SITE`：用于获取规则的 Datadog 站点参数（[查看列表](https://docs.datadoghq.com/getting_started/site/)）（默认值：`datadoghq.com`） ## 配置文件 可以使用代码仓库根目录下的 `static-analysis.datadog.yml` 文件配置静态分析器。这是一个包含以下条目的 YAML 文件： - `rulesets`：（必需）包含此代码仓库要使用的所有规则集的列表（完整列表请参阅 [Datadog 文档](https://docs.datadoghq.com/security/code_security/static_analysis/static_analysis_rules/)）。此列表中的元素必须是字符串或包含规则集配置的映射（如下所述）。 - `ignore`：（可选）要忽略的路径前缀和 glob 模式列表。与其条目之一匹配的文件将不会被分析。 - `only`：（可选）要分析的路径前缀和 glob 模式列表。如果指定了 `only`，则仅分析与其中一个条目匹配的文件。 - `ignore-gitignore`：（可选）默认情况下，`.gitignore` 文件中的任何条目都会添加到 `ignore` 列表中。如果 `ignore-gitignore` 选项为 true，则不会读取 `.gitignore` 文件。 - `max-file-size-kb`：（可选）大于此大小（以千字节为单位）的文件将被忽略。默认值为 200 kB。 - `schema-version`：（可选）此配置文件遵循的 schema 版本。如果指定，则必须为 `v1`。 `rulesets` 列表的条目必须是包含要启用的规则集名称的字符串，或者是包含规则集配置的映射。此映射包含以下字段： - 第一个字段（必需）以其键的形式给出规则集名称，值为空。 - `ignore`：（可选）_针对此规则集_ 要忽略的路径前缀和 glob 模式列表。对于与 `ignore` 列表中任何条目匹配的任何文件，将不会评估此规则集中的规则。 - `only`：（可选）_针对此规则集_ 要分析的路径前缀和 glob 模式列表。如果指定了 `only`，则此规则集中的规则将仅针对与其中一个条目匹配的文件进行评估。 - `rules`：（可选）规则配置的映射。此映射中未指定的规则仍将被评估，但使用其默认配置。 `rules` 字段中的映射使用规则名称作为其键，值是包含以下字段的映射： - `ignore`（可选）_针对此规则_ 要忽略的路径前缀和 glob 模式列表。对于与 `ignore` 列表中任何条目匹配的任何文件，将不会评估此规则。 - `only`：（可选）_针对此规则_ 要分析的路径前缀和 glob 模式列表。如果指定了 `only`，则此规则将仅针对与其中一个条目匹配的文件进行评估。 - `severity`：（可选）如果提供，则覆盖此规则产生的违规的严重级别。有效的严重级别为 `ERROR`、`WARNING`、`NOTICE` 和 `NONE`。 - `category`：（可选）如果提供，则覆盖此规则的类别。有效的类别为 `BEST_PRACTICES`、`CODE_STYLE`、`ERROR_PRONE`、`PERFORMANCE` 和 `SECURITY`。 - `arguments`：（可选）规则参数的值映射。 `arguments` 字段中的映射使用参数名称作为其键，值可以是字符串或映射： - 如果要为整个代码仓库设置一个值，可以将其指定为字符串； - 如果要为代码仓库中的不同子树设置不同的值，可以将它们指定为从子树前缀到该子树内参数值的映射。有关更多详细信息，请参阅示例。 带有注释的配置文件示例： ``` # 这是一个旧版 "v1" 配置文件。 schema-version: v1 # 为此 repository 启用的 rulesets 列表。 rulesets: # Enable the `python-inclusive` ruleset with the default configuration. - python-inclusive # Enable the `python-best-practices` ruleset with a custom configuration. - python-best-practices: # Do not apply any of the rules in this ruleset to files that match `src/**/*.generated.py`. ignore: - src/**/*.generated.py rules: # Special configuration for the `python-best-practices/no-generic-exception` rule. no-generic-exception: # Treat violations of this rule as errors (normally "notice"). severity: ERROR # Classify violations of this rule under the "code style" category. category: CODE_STYLE # Only apply this rule to files under the `src/new-code` subtree. only: - src/new-code # Enable the `python-code-style ruleset` with a custom configuration. - python-code-style: rules: max-function-lines: # Set arguments for the `python-code-style/max-function-lines` rule. arguments: # Set the `max-lines` argument to 150 in the whole repository. max-lines: 150 max-class-lines: # Set arguments for the `python-code-style/max-class-lines` rule. arguments: # Set different values for the `max-lines` argument in different subtrees. max-lines: # Set the `max-lines` argument to 100 by default /: 100 # Set the `max-lines` argument to 75 under the `src/new-code` subtree. src/new-code: 75 # 仅分析 `src` 和 `imported` subtrees 中的文件。 only: - src - imported # 不要分析 `src/tests` subtree 中的任何文件。 ignore: - src/tests # 不要将 `.gitignore` 文件的内容添加到 `ignore` 列表中。 ignore-gitignore: true # 不要分析大于 100 kB 的文件。 max-file-size-kb: 100 ``` 另一个展示了使用每个选项的示例： ``` schema-version: v1 rulesets: - python-best-practices - python-code-style: ignore: - src/generated - src/**/*_test.py only: - src - imported/**/new/** rules: max-function-lines: severity: WARNING category: PERFORMANCE ignore: - src/new-code - src/new/*.gen.py only: - src/new - src/**/new-code/** arguments: max-lines: 150 min-lines: /: 10 src/new-code: 0 ignore: - dist - lib/**/*.py only: - src - imported/**/*.py ignore-gitignore: true max-file-size-kb: 256 ``` ## 配置文件 Schema 在 `schema/legacy` 子目录中有一个用于 `static-analysis.datadog.yml` 的 JSON Schema 定义。 你可以使用它来检查配置文件的语法： 1. 执行 `npx --yes ajv-cli@5.0.0 validate -s schema/legacy/schema.json -r 'schema/legacy/examples/*/*.json' -d path/to/your/static-analysis.datadog.yml` 在 [`schema/legacy/examples/valid`](schema/legacy/examples/valid) 和 [`schema/legacy/examples/invalid`](schema/legacy/examples/invalid) 子目录中分别有一些有效和无效配置文件的示例。如果你对 JSON Schema 进行了更改，可以针对我们的示例进行测试： 1. 执行 `make -C schema` ## 差异感知扫描 差异感知扫描是静态分析器的一项功能，旨在仅扫描最近发生更改的文件。差异感知扫描使用以前的结果，并仅添加来自已更改文件的违规。 为了使用差异感知扫描，你必须是 Datadog 客户。 要使用差异感知扫描： 1. 根据你使用的 Datadog 数据中心设置 `DD_SITE` 环境变量 2. 使用你的 Datadog 应用程序密钥和 API 密钥设置 `DD_APP_KEY` 和 `DD_API_KEY` 环境变量 3. 使用 `--diff-aware` 选项运行静态分析器 在使用差异感知时，静态分析器将连接到 Datadog 并尝试使用以前的分析结果。如果发生任何问题导致无法使用差异感知，分析器将输出如下所示的错误并继续进行全面扫描。 如果需要，你可以使用 `--debug true` 选项进行进一步的故障排除。 ``` $ datadog-static-analyzer --directory /path/to/code --output output.sarif --format sarif --diff-aware ... diff aware not enabled (error when receiving diff-aware data from Datadog with config hash 16163d87d4a1922ab89ec891159446d1ce0fb47f9c1469448bb331b72d19f55c, sha 5509900dc490cedbe2bb64afaf43478e24ad144b), proceeding with full scan. ... ``` ## 其他工具 ### datadog-export-rulesets 将规则集从 API 导出到文件中 ``` cargo run --locked --bin datadog-export-rulesets -- -r -o ``` ## 更多 - [差异感知扫描的工作原理](doc/diff-aware.md) - [报告问题](doc/report-issue.md) - [OWASP Benchmark](doc/owasp-benchmark.md) ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 文件以获取更多信息，以及 [DEVELOPMENT.md](DEVELOPMENT.md) 了解有关测试和编码指南的所有详细信息。 ## 更多信息 - [Datadog 静态分析](https://docs.datadoghq.com/security/code_security/static_analysis/)

标签：Datadog, DevSecOps, Docker, Python, SAST, SSH爆破, TLS抓取, 上游代理, 二进制发布, 云计算, 代码安全, 代码审查, 代码规范, 可视化界面, 安全专业人员, 安全扫描, 安全防御评估, 开源工具, 无后门, 时序注入, 漏洞枚举, 盲注攻击, 规则引擎, 请求拦截, 软件安全, 通知系统, 错误基检测, 静态代码分析