GuardDog

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

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

入门

安装

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

源代码启发式方法：

元数据启发式方法：

npm

源代码启发式方法：

元数据启发式方法：

go

源代码启发式方法：

自定义规则

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

维护者

作者：

• Ellen Wang
• Christophe Tafani-Dereeper
• Vladimir de Turckheim
• Sebastian Obregoso

致谢

灵感来源：

• Backstabber's Knife Collection: A Review of Open Source Software Supply Chain Attacks
• What are Weak Links in the npm Supply Chain?
• A Survey on Common Threats in npm and PyPi Registries
• A Benchmark Comparison of Python Malware Detection Approaches
• Towards Measuring Supply Chain Attacks on Package Managers for Interpreted Languages