GuardDog

GuardDog 是一个 CLI 工具，用于识别恶意的 PyPI 和 npm 包、Go 模块、Rust crates、RubyGems、GitHub Actions 或 VSCode 扩展。它通过对包源代码进行静态分析（通过 YARA 规则）并分析包元数据来检测供应链攻击。

GuardDog 的不同之处： GuardDog 不只是列出可疑模式，而是关联发现结果，基于攻击链来识别真正的风险。一个包需要同时具备执行某项操作的能力（capability，例如网络访问）和威胁指标（threat indicator，例如可疑域名），并且二者出现在同一文件中，才会被标记为高风险。

它会下载并扫描以下来源的代码：

NPM：npmjs.org 上托管的包
PyPI：PyPI.org 上托管的源文件（tar.gz）包
Go：GitHub.com 上托管的仓库的 GoLang 源文件
Rust：crates.io 上托管的 crates
RubyGems：rubygems.org 上托管的 Gem 包
GitHub Actions：GitHub.com 上托管的仓库的 JavaScript 源文件
VSCode 扩展：marketplace.visualstudio.com 上托管的扩展（.vsix）包

GuardDog demo usage

GuardDog 的工作原理

GuardDog 使用基于风险的检测模型（risk-based detection model），将代码能力与威胁指标关联起来：

检测（Detection）：规则识别能力（代码可以做什么）或威胁（可疑指标）
关联（Correlation）：在同一文件中发现的能力和威胁构成风险（跨文件匹配也会构成风险，但严重性会降级）
评分（Scoring）：根据攻击链的完整性和复杂程度对风险进行评分（0-10）
报告（Reporting）：包会获得严重性评级（低/中/高），并附有详细的风险明细

为什么采用这种方法？

传统的 SAST 工具会独立标记每一个可疑模式，导致告警疲劳。GuardDog 理解到：

仅有能力并不代表恶意（网络库本就应该发出 HTTP 请求）
仅有威胁指标可能是误报（测试夹具、文档）
能力 + 威胁同时出现才表示真正的风险（代码可以并且将会执行恶意操作）

风险评分

包会根据四个因素获得 0-10 的评分：

评分标签：

0：未检测到风险
0.1-3：低风险（单阶段威胁，特异性低）
3.1-7.5：中风险（部分攻击链、元数据指标或单阶段代码发现）
7.6-10：高风险（具有源代码证据的多阶段攻击链——几乎可以确定被入侵）

攻击链阶段（基于 MITRE ATT&CK）：

早期：初始访问、执行能力
中期：持久化、防御规避、凭据访问
后期：命令与控制、数据外泄、影响

查看适用于 GuardDog 的全新 Datadog Agent 集成和 Cloud SIEM 内容包。

快速开始

安装

运行 GuardDog 最简单的方法是使用 uvx：

uvx guarddog pypi scan requests

要在本地安装：

uv tool install guarddog
# or
pip install guarddog

或者使用 Docker 镜像：

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

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

示例用法

# Scan the most recent version of the 'requests' package
guarddog pypi scan requests

# Scan a specific version of the 'requests' package
guarddog pypi scan requests --version 2.28.1

# Scan the 'request' package using 2 specific heuristics
guarddog pypi scan requests --rules exec-base64 --rules code-execution

# Scan the 'requests' package using all rules but one
guarddog pypi scan requests --exclude-rules exec-base64

# Scan a local package archive
guarddog pypi scan /tmp/triage.tar.gz

# Scan a local package directory
guarddog pypi scan /tmp/triage/

# Scan a package stored in S3 (a folder/prefix or a single archive object)
guarddog pypi scan s3://my-bucket/path/to/package/
guarddog pypi scan s3://my-bucket/path/to/package.tar.gz

# Scan every package referenced in a requirements.txt file of a local folder
guarddog pypi verify workspace/guarddog/requirements.txt

# Scan every package referenced in a requirements.txt file and output a sarif file - works only for verify
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt

# Output JSON to standard output - works for every command
guarddog pypi scan requests --output-format=json

# All the commands also work on npm, go, crates, rubygems
guarddog npm scan express

guarddog go scan github.com/DataDog/dd-trace-go

guarddog go verify /tmp/repo/go.mod

# Scan Rust crates
guarddog crates scan serde

guarddog crates verify /tmp/repo/Cargo.lock

# Scan RubyGems packages
guarddog rubygems scan rails

guarddog rubygems verify /tmp/repo/Gemfile.lock

# Additionally can support scanning GitHub actions that are implemented in JavaScript
guarddog github_action scan DataDog/synthetics-ci-github-action

guarddog github_action verify /tmp/repo/.github/workflows/main.yml

# Scan VSCode extensions from the marketplace
guarddog extension scan ms-python.python

# Scan a specific version of a VSCode extension
guarddog extension scan ms-python.python --version 2023.20.0

# Scan a local VSCode extension directory or VSIX archive
guarddog extension scan /tmp/my-extension/

# Run in debug mode
guarddog --log-level debug npm scan express

沙箱扫描

扫描包时，GuardDog 会在内核级沙箱内运行源代码分析（Linux 上通过 Landlock，macOS 上通过 Seatbelt，使用 nono）。该沙箱会阻止所有网络访问，并将文件系统操作限制为仅分析所需的路径。这可以防止恶意包在归档解压或扫描期间尝试执行代码。

默认情况下，沙箱是必需的：如果平台不支持，扫描将失败，而不是在无保护状态下运行。要无沙箱扫描，必须显式传递 --no-sandbox 参数：

# Default: require the sandbox, exit with an error if it's unavailable
guarddog pypi scan requests

# Explicitly disable the sandbox
guarddog pypi scan requests --no-sandbox

对于远程包，以下三个阶段以不同的权限级别运行：

下载和元数据分析在无沙箱状态下运行（需要网络访问）
归档解压在沙箱子进程中运行（网络被阻止，文件系统受限）
源代码分析（YARA）在应用沙箱后的主进程中运行（网络被阻止，文件系统仅限于解压的文件）

引入沙箱是为了缓解归档解压期间的路径遍历和代码执行漏洞（CVE-2022-23530、CVE-2022-23531、CVE-2026-22870、CVE-2026-22871）。

从 S3 扫描包

GuardDog 可以扫描存储在 S3 中的包，可以是文件夹/前缀或单个归档对象：

guarddog npm scan s3://my-bucket/path/to/package/
guarddog npm scan s3://my-bucket/path/to/package.tar.gz

这会使用您现有的 AWS 凭据（环境变量、~/.aws、SSO 或 IAM 角色）。GuardDog 在开始任何操作之前通过 STS 验证身份验证，如果找不到有效的凭据，则退出并报错。这些对象会同步到临时目录，像其他任何不受信任的内容一样在沙箱下扫描，之后从磁盘上删除。

规则

GuardDog 使用两种类型的检测规则，它们都参与基于风险的评分引擎：

源代码规则（YARA）：对包源代码进行静态分析，检测能力和威胁
元数据规则（Python 检测器）：分析包注册表元数据，检测供应链攻击指标

有关每个生态系统的完整规则列表，请参阅 RULES.md。

有关编写新规则的指南，请参阅 WRITING_RULES.md。

在 GitHub Action 中运行 GuardDog

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

使用此功能，您可以获得：

基于 GuardDog 扫描输出自动评论您的拉取请求
直接在 GitHub UI 中内置误报管理

使用 GuardDog 的 GitHub Action 示例：

name: GuardDog

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

permissions:
  contents: read

jobs:
  guarddog:
    permissions:
      contents: read # for actions/checkout to fetch code
      security-events: write # for github/codeql-action/upload-sarif to upload SARIF results
    name: Scan dependencies
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: astral-sh/setup-uv@v7

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

      - name: Upload SARIF file to GitHub
        uses: github/codeql-action/upload-sarif@v3
        with:
          category: guarddog-builtin
          sarif_file: guarddog.sarif

开发

运行 GuardDog 的本地版本

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

单元测试

运行所有单元测试：make test

针对包元数据启发式规则运行单元测试：make test-metadata-rules（测试在此处）。

基准测试

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

代码质量检查

运行类型检查器：

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

以及运行 linter：

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

通过环境变量配置

可以使用环境变量自定义 GuardDog 的行为：

常规配置

元数据规则配置

环境变量	描述	默认值
`GUARDDOG_NEW_DEPENDENCY_RISK_THRESHOLD`	在 `risky_new_dependency` 规则中，新引入的依赖项触发父包标记的最低风险评分	`5.0`

归档解压安全限制

GuardDog 在解压包归档时实施多项安全检查，以防止压缩炸弹和文件描述符耗尽攻击：

环境变量	描述	默认值
`GUARDDOG_MAX_UNCOMPRESSED_SIZE`	允许的最大未压缩大小（字节），防止磁盘空间耗尽

维护者

作者

致谢

灵感来源：

严重性	30%	最高严重性的发现（低/中/高）
攻击链	20%	是否存在完整的攻击阶段（早期 → 中期/后期）
特异性	30%	模式对恶意软件与合法代码的特定程度
复杂程度	20%	技术的高级程度

`GUARDDOG_PARALLELISM`	用于并行处理的线程数	可用 CPU 数
`GUARDDOG_VERIFY_EXHAUSTIVE_DEPENDENCIES`	分析所有可能的依赖版本（`true`/`false`）	`false`
`GUARDDOG_NPM_INCLUDE_DEV_DEPENDENCIES`	在扫描 npm `package.json` 文件时包含 `devDependencies`（`true`/`false`）；也可以通过 `guarddog npm verify --include-dev-dependencies` 在每次调用时切换	`false`
`GUARDDOG_TOP_PACKAGES_CACHE_LOCATION`	热门包缓存目录的位置	`guarddog/analyzer/metadata/resources`
`GUARDDOG_YARA_EXT_EXCLUDE`	要以逗号分隔的文件扩展名列表，用于从 YARA 扫描中排除	`ini,md,rst,txt,lock,json,yaml,yml,toml,xml,html,csv,sql,pdf,doc,docx,ppt,pptx,xls,xlsx,odt,changelog,readme,makefile,dockerfile,pkg-info,d.ts`

guarddog

最受欢迎