GuardDog

GuardDog 是一个命令行工具，用于识别恶意的 PyPI 和 npm 包或 Go 模块。它通过 Semgrep 规则对包的源代码和元数据运行一系列启发式检查。

GuardDog 可以使用任何可用的启发式方法来扫描本地或远程的 PyPI 和 npm 包或 Go 模块。

GuardDog 演示使用

入门

安装

pip install guarddog

或使用 Docker 镜像：

docker pull ghcr.io/datadog/guarddog
alias guarddog='docker run --rm ghcr.io/datadog/guarddog'

注意：在 Windows 上，唯一支持的安装方法是 Docker。

示例用法

# 扫描 'requests' 包的最新版本
guarddog pypi scan requests

# 扫描 'requests' 包的特定版本
guarddog pypi scan requests --version 2.28.1

# 使用 2 个特定的启发式方法扫描 'request' 包
guarddog pypi scan requests --rules exec-base64 --rules code-execution

# 使用除一个规则外的所有规则扫描 'requests' 包
guarddog pypi scan requests --exclude-rules exec-base64

# 扫描本地包归档
guarddog pypi scan /tmp/triage.tar.gz

# 扫描本地包目录
guarddog pypi scan /tmp/triage/

# 扫描本地文件夹中 requirements.txt 文件引用的每个包
guarddog pypi verify workspace/guarddog/requirements.txt

# 扫描 requirements.txt 文件引用的每个包并输出 sarif 文件 - 仅适用于 verify 命令
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt

# 将 JSON 输出到标准输出 - 适用于每个命令
guarddog pypi scan requests --output-format=json

# 所有命令也适用于 npm 或 go
guarddog npm scan express

# 以调试模式运行
guarddog --log-level debug npm scan express

启发式方法

GuardDog 包含两种类型的启发式方法：

源代码启发式方法：针对包源代码运行的 Semgrep 规则。
包元数据启发式方法：针对 PyPI 或 npm 上的包元数据运行的 Python 或 Javascript 启发式方法。

PyPI

源代码启发式方法：

启发式方法	描述
shady-links	识别包中是否包含指向可疑域名扩展的 URL
obfuscation	识别包是否使用恶意软件常用的混淆方法
clipboard-access	识别包是否读取或写入剪贴板数据
exfiltrate-sensitive-data	识别包是否从本地系统读取并泄露敏感数据
download-executable	识别包是否下载并执行远程二进制文件
exec-base64	识别包是否动态执行 base64 编码的代码
silent-process-execution	识别包是否静默执行可执行文件
dll-hijacking	识别恶意包是否操纵受信任的应用程序加载恶意 DLL
bidirectional-characters	识别包是否包含双向字符，这可能被用来显示与实际执行不同的源代码。更多信息请参见 https://trojansource.codes/
steganography	识别包是否从图像中检索隐藏数据并执行
code-execution	识别 setup.py 文件中是否执行操作系统命令
cmd-overwrite	识别 setup.py 中的 'install' 命令是否被覆盖，表明在安装包时自动运行的代码

元数据启发式方法：

启发式方法	描述
empty_information	识别描述字段为空的包
release_zero	识别发布版本为 0.0 或 0.0.0 的包
typosquatting	识别与高度流行的包名称相近的包
potentially_compromised_email_domain	识别包维护者的电子邮件域名（因此包管理器账户）可能已被入侵
unclaimed_maintainer_email_domain	识别包维护者的电子邮件域名（因此 npm 账户）未被认领且可被攻击者注册
repository_integrity_mismatch	识别链接的 GitHub 仓库中包含额外意外文件的包
single_python_file	识别只有单个 Python 文件的包
bundled_binary	识别捆绑二进制文件的包
deceptive_author	此启发式方法检测作者是否使用一次性电子邮件

npm

源代码启发式方法：

启发式方法	描述
npm-serialize-environment	识别包是否序列化 'process.env' 以泄露环境变量
npm-obfuscation	识别包是否使用恶意软件常用的混淆方法
npm-silent-process-execution	识别包是否静默执行可执行文件
shady-links	识别包中是否包含指向可疑域名扩展的 URL
npm-exec-base64	识别包是否通过 'eval' 动态执行代码
npm-install-script	识别包是否有自动运行命令的预安装或后安装脚本
npm-steganography	识别包是否从图像中检索隐藏数据并执行
bidirectional-characters	识别包是否包含双向字符，这可能被用来显示与实际执行不同的源代码。更多信息请参见 https://trojansource.codes/
npm-dll-hijacking	识别恶意包是否操纵受信任的应用程序加载恶意 DLL
npm-exfiltrate-sensitive-data	识别包是否从本地系统读取并泄露敏感数据

元数据启发式方法：

启发式方法	描述
empty_information	识别描述字段为空的包
release_zero	识别发布版本为 0.0 或 0.0.0 的包
potentially_compromised_email_domain	识别包维护者的电子邮件域名（因此包管理器账户）可能已被入侵；注意，NPM 的 API 可能不提供关于维护者电子邮件的准确信息，因此这个检测器可能会对 NPM 包造成误报。参见 https://www.theregister.com/2022/05/10/security_npm_email/
unclaimed_maintainer_email_domain	识别包维护者的电子邮件域名（因此 npm 账户）未被认领且可被攻击者注册；注意，NPM 的 API 可能不提供关于维护者电子邮件的准确信息，因此这个检测器可能会对 NPM 包造成误报。参见 https://www.theregister.com/2022/05/10/security_npm_email/
typosquatting	识别与高度流行的包名称相近的包
direct_url_dependency	识别具有直接 URL 依赖的包。通过这种方式获取的依赖项不是不可变的，可能被用来注入不可信的代码或降低可重现安装的可能性。
npm_metadata_mismatch	识别 npm 包清单和包信息在某些关键字段上存在不匹配的包
bundled_binary	识别捆绑二进制文件的包
deceptive_author	此启发式方法检测作者是否使用一次性电子邮件

go

源代码启发式方法：

启发式方法	描述
shady-links	识别包中是否包含指向可疑域名扩展的 URL

自定义规则

Guarddog 允许实现自定义源代码规则。源代码规则位于 guarddog/analyzer/sourcecode 目录下，支持的格式是 Semgrep 或 Yara。

Semgrep 规则是与语言相关的，Guarddog 将导入所有与用户在 CLI 中选择的生态系统语言匹配的 .yml 规则。
另一方面，Yara 规则与语言无关，因此所有匹配的 .yar 规则都会被导入。

您可以编写自己的规则并将其放入该目录，Guarddog 将允许您像选择或排除任何内置规则一样选择或排除它，并将结果附加到输出中。例如，您可以创建以下 semgrep 规则：

rules:
  - id: sample-rule 
    languages:
      - python
    message: 规则匹配时的输出信息
    metadata:
      description: CLI 帮助中使用的描述
    patterns:
        在此处添加您的规则启发式  
    severity: WARNING

然后您需要将其保存为 sample-rule.yml，并注意 id 必须与文件名匹配。

对于 Yara，您可以创建以下规则：

rule sample-rule
{
  meta:
    description = "输出信息中使用的描述"
    target_entity = "file"
  strings:
    $exec = "exec"
  condition:
    1 of them
}

然后您需要将其保存为 sample-rule.yar。

请注意，在这两种情况下，规则 id 都必须与文件名匹配。

在 GitHub Action 中运行 GuardDog

将 GuardDog 集成到您的 CI 流程中最简单的方法是利用 SARIF 输出格式，并将其上传到 GitHub 的代码扫描功能。

使用这种方法，您可以获得：

基于 GuardDog 扫描输出的自动 pull request 评论
直接在 GitHub UI 中内置的误报管理

使用 GuardDog 的示例 GitHub Action：

name: GuardDog

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  guarddog:
    permissions:
      contents: read # 用于 actions/checkout 获取代码
      security-events: write # 用于 github/codeql-action/upload-sarif 上传 SARIF 结果
    name: 扫描依赖项
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: 设置 Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      - name: 安装 GuardDog
        run: pip install guarddog

      - run: guarddog pypi verify requirements.txt --output-format sarif --exclude-rules repository_integrity_mismatch > guarddog.sarif

      - name: 将 SARIF 文件上传到 GitHub
        uses: github/codeql-action/upload-sarif@v3
        with:
          category: guarddog-builtin
          sarif_file: guarddog.sarif

开发

运行 GuardDog 的本地版本

使用 pip

确保已安装 >=python3.10
克隆仓库
创建虚拟环境：python3 -m venv venv && source venv/bin/activate
安装依赖：pip install -r requirements.txt
使用 python -m guarddog 运行 GuardDog

使用 poetry

确保 poetry 有一个 python >=3.10 的环境 poetry env use 3.10.0
安装依赖 poetry install
运行 guarddog poetry run guarddog 或 poetry shell 然后运行 guarddog

单元测试

运行所有单元测试：make test

运行针对 Semgrep 规则的单元测试：make test-semgrep-rules（测试在这里）。这些测试使用测试 Semgrep 规则的标准方法。

运行针对包元数据启发式的单元测试：make test-metadata-rules（测试在这里）。

基准测试

您可以在合法和恶意包上运行 GuardDog 来确定误报和漏报。请参见 ./tests/samples

代码质量检查

运行类型检查器：

mypy --install-types --non-interactive guarddog

运行代码风格检查器：

flake8 guarddog --count --select=E9,F63,F7,F82 --show-source --statistics --exclude tests/analyzer/sourcecode,tests/analyzer/metadata/resources,evaluator/data
flake8 guarddog --count --max-line-length=120 --statistics --exclude tests/analyzer/sourcecode,tests/analyzer/metadata/resources,evaluator/data --ignore=E203,W503