GuardDog 是一款 CLI 工具，通过源代码和元数据启发式规则识别 PyPI、npm、Go、RubyGems、GitHub Actions 和 VSCode 扩展中的恶意软件包。
# GuardDog
[](https://github.com/DataDog/guarddog/actions/workflows/checks.yml)
[](https://securityscorecards.dev/viewer/?uri=github.com/DataDog/guarddog)
[](https://www.bestpractices.dev/projects/12273)
GuardDog 是一个 CLI 工具，用于识别恶意的 PyPI 和 npm 包、Go modules、RubyGems、GitHub actions 或 VSCode 扩展。它通过对包的源代码（通过 Semgrep 规则）和包的元数据运行一系列启发式规则来进行识别。
GuardDog 可以使用任何可用的[启发式规则](#heuristics)来扫描本地或远程的 PyPI 和 npm 包、Go modules、RubyGems、GitHub actions 或 VSCode 扩展。
它会从以下位置下载并扫描代码：
* NPM：托管在 [npmjs.org](https://www.npmjs.com/) 上的包
* PyPI：托管在 [PyPI.org](https://pypi.org/) 上的源文件 (tar.gz) 包
* Go：托管在 [GitHub.com](https://github.com) 上的仓库的 GoLang 源文件
* RubyGems：托管在 [rubygems.org](https://rubygems.org/) 上的 Gem 包
* GitHub Actions：托管在 [GitHub.com](https://github.com) 上的仓库的 Javascript 源文件
* VSCode Extensions：托管在 [marketplace.visualstudio.com](https://marketplace.visualstudio.com/) 上的扩展 (.vsix) 包
### 查看全新的 Datadog Agent [集成](https://docs.datadoghq.com/integrations/guarddog/)和针对 GuardDog 的 Cloud SIEM [内容包](https://app.datadoghq.com/security/siem/content-packs?query=guarddog)。
## 快速开始
### 安装说明
运行 GuardDog 最简单的方法是使用 [`uvx`](https://docs.astral.sh/uv/guides/tools/)：
```
uvx guarddog pypi scan requests
```
要在本地安装：
```
uv tool install guarddog
# 或
pip install guarddog
```
或者使用 Docker 镜像：
```
docker pull ghcr.io/datadog/guarddog
alias guarddog='docker run --rm ghcr.io/datadog/guarddog'
```
*注意：在 Windows 上，唯一受支持的安装方式是 Docker。*
### 示例用法
```
# 扫描 'requests' package 的最新版本
guarddog pypi scan requests
# 扫描 'requests' package 的特定版本
guarddog pypi scan requests --version 2.28.1
# 使用 2 个特定启发式规则扫描 'request' package
guarddog pypi scan requests --rules exec-base64 --rules code-execution
# 使用除一个之外的所有规则扫描 'requests' package
guarddog pypi scan requests --exclude-rules exec-base64
# 扫描本地 package 归档
guarddog pypi scan /tmp/triage.tar.gz
# 扫描本地 package 目录
guarddog pypi scan /tmp/triage/
# 扫描本地文件夹中 requirements.txt 文件引用的所有 package
guarddog pypi verify workspace/guarddog/requirements.txt
# 扫描 requirements.txt 文件引用的所有 package 并输出 sarif 文件 - 仅适用于 verify
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt
# 输出 JSON 到标准输出 - 适用于所有命令
guarddog pypi scan requests --output-format=json
# 所有命令也适用于 npm, go, rubygems
guarddog npm scan express
guarddog go scan github.com/DataDog/dd-trace-go
guarddog go verify /tmp/repo/go.mod
# 扫描 RubyGems packages
guarddog rubygems scan rails
guarddog rubygems verify /tmp/repo/Gemfile.lock
# 此外，还可以支持扫描使用 JavaScript 实现的 GitHub actions
guarddog github_action scan DataDog/synthetics-ci-github-action
guarddog github_action verify /tmp/repo/.github/workflows/main.yml
# 从 marketplace 扫描 VSCode extensions
guarddog extension scan ms-python.python
# 扫描 VSCode extension 的特定版本
guarddog extension scan ms-python.python --version 2023.20.0
# 扫描本地 VSCode extension 目录或 VSIX 归档
guarddog extension scan /tmp/my-extension/
# 以 debug 模式运行
guarddog --log-level debug npm scan express
```
## 启发式规则
GuardDog 自带 2 种类型的启发式规则：
* [**源代码启发式规则**](https://github.com/DataDog/guarddog/tree/main/guarddog/analyzer/sourcecode)：针对包源代码运行的 Semgrep 规则。
* [**包元数据启发式规则**](https://github.com/DataDog/guarddog/tree/main/guarddog/analyzer/metadata)：针对 PyPI 或 npm 上的包元数据运行的 Python 或 Javascript 启发式规则。
### PyPI
源代码启发式规则：
| **启发式规则** | **描述** |
|:-------------:|:---------------:|
| api-obfuscation | 识别使用替代 Python 语法模式混淆的 API 调用 |
| shady-links | 识别包中何时包含带有可疑扩展名的域名的 URL |
| obfuscation | 识别包何时使用了恶意软件常用的混淆方法 |
| clipboard-access | 识别包何时读取或写入剪贴板数据 |
| exfiltrate-sensitive-data | 识别包何时读取并外渗本地系统上的敏感数据 |
| download-executable | 识别包何时下载并执行远程二进制文件 |
| exec-base64 | 识别包何时动态执行 base64 编码的代码 |
| silent-process-execution | 识别包何时静默执行可执行文件 |
| dll-hijacking | 识别恶意包何时操纵受信任的应用程序加载恶意 DLL |
| steganography | 识别包何时从图像中检索隐藏数据并执行它 |
| code-execution | 识别在 setup.py 文件中何时执行了 OS 命令 |
| unicode | 识别可疑的 unicode 字符 |
| cmd-overwrite | 识别 setup.py 中的 'install' 命令何时被覆盖，表明存在一段在安装包时自动运行的代码 |
| suspicious_passwd_access_linux | 检测对 /etc/passwd 文件的可疑读取访问，恶意软件通常以此为目标以收集凭据 |
元数据启发式规则：
| **启发式规则** | **描述** |
|:-------------:|:---------------:|
| 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 | 识别包何时从图像中检索隐藏数据并执行它 |
| npm-dll-hijacking | 识别恶意包何时操纵受信任的应用程序加载恶意 DLL |
| npm-exfiltrate-sensitive-data | 识别包何时读取并外渗本地系统上的敏感数据 |
| suspicious_passwd_access_linux | 检测对 /etc/passwd 文件的可疑读取访问，恶意软件通常以此为目标以收集凭据 |
元数据启发式规则：
| **启发式规则** | **描述** |
|:-------------:|:---------------:|
| 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 |
| go-exec-base64 | 识别在 Go 中传递给执行函数的 Base64 解码内容 |
| go-exfiltrate-sensitive-data | 此规则识别包何时读取并外渗本地系统上的敏感数据。 |
| go-exec-download | 此规则在设置可执行权限后下载并执行远程二进制文件。 |
| suspicious_passwd_access_linux | 检测对 /etc/passwd 文件的可疑读取访问，恶意软件通常以此为目标以收集凭据 |
元数据启发式规则：
| **启发式规则** | **描述** |
|:-------------:|:---------------:|
| typosquatting | 识别名称与非常受欢迎的包极其相似的包 |
### GitHub Action
源代码启发式规则：
| **启发式规则** | **描述** |
|:-------------:|:---------------:|
| npm-serialize-environment | 识别包何时序列化 'process.env' 以外渗环境变量 |
| npm-obfuscation | 识别包何时使用了恶意软件常用的混淆方法 |
| npm-silent-process-execution | 识别包何时静默执行可执行文件 |
| shady-links | 识别包中何时包含带有可疑扩展名的域名的 URL |
| npm-exec-base64 | 识别包何时通过 'eval' 动态执行代码 |
| npm-install-script | 识别包何时具有自动运行命令的预安装或安装后脚本 |
| npm-steganography | 识别包何时从图像中检索隐藏数据并执行它 |
| npm-dll-hijacking | 识别恶意包何时操纵受信任的应用程序加载恶意 DLL |
| npm-exfiltrate-sensitive-data | 识别包何时读取并外渗本地系统上的敏感数据 |
| suspicious_passwd_access_linux | 检测对 /etc/passwd 文件的可疑读取访问，恶意软件通常以此为目标以收集凭据 |
### Extension
源代码启发式规则：
| **启发式规则** | **描述** |
|:-------------:|:---------------:|
| npm-serialize-environment | 识别包何时序列化 'process.env' 以外渗环境变量 |
| npm-obfuscation | 识别包何时使用了恶意软件常用的混淆方法 |
| npm-silent-process-execution | 识别包何时静默执行可执行文件 |
| shady-links | 识别包中何时包含带有可疑扩展名的域名的 URL |
| npm-exec-base64 | 识别包何时通过 'eval' 动态执行代码 |
| npm-install-script | 识别包何时具有自动运行命令的预安装或安装后脚本 |
| npm-steganography | 识别包何时从图像中检索隐藏数据并执行它 |
| npm-dll-hijacking | 识别恶意包何时操纵受信任的应用程序加载恶意 DLL |
| npm-exfiltrate-sensitive-data | 识别包何时读取并外渗本地系统上的敏感数据 |
| suspicious_passwd_access_linux | 检测对 /etc/passwd 文件的可疑读取访问，恶意软件通常以此为目标以收集凭据 |
### RubyGems
源代码启发式规则：
| **启发式规则** | **描述** |
|:-------------:|:---------------:|
| rubygems-code-execution | 识别 gem 何时执行 OS 命令 |
| rubygems-exfiltrate-sensitive-data | 识别包何时读取并外渗本地系统上的敏感数据 |
| rubygems-serialize-environment | 识别包何时序列化 ENV 以外渗环境变量 |
| rubygems-network-on-require | 识别 gem 何时在 require 时发出网络请求 |
| rubygems-install-hook | 识别 gem 何时注册安装钩子 |
| rubygems-exec-base64 | 识别包何时动态执行 base64 编码的代码 |
| suspicious_passwd_access_linux | 检测对 /etc/passwd 文件的可疑读取访问，恶意软件通常以此为目标以收集凭据 |
元数据启发式规则：
| **启发式规则** | **描述** |
|:-------------:|:---------------:|
| typosquatting | 识别名称与非常受欢迎的包极其相似的包 |
| empty_information | 识别描述字段为空的包 |
| release_zero | 识别发布版本为 0.0 或 0.0.0 的包 |
| bundled_binary | 识别捆绑了二进制文件的包 |
| repository_integrity_mismatch | 识别具有关联的 GitHub 仓库且该包包含额外意外文件的包 |
## 自定义规则
Guarddog 允许实现自定义源代码规则。
源代码规则位于 [guarddog/analyzer/sourcecode](guarddog/analyzer/sourcecode) 目录下，支持的格式为 [Semgrep](https://github.com/semgrep/semgrep) 或 [Yara](https://github.com/VirusTotal/yara)。
* Semgrep 规则依赖于特定语言，Guarddog 将导入所有语言与用户在 CLI 中选择的生态系统相匹配的 `.yml` 规则。
* 另一方面，Yara 规则独立于语言，因此将导入存在的所有匹配的 `.yar` 规则。
接下来，你可以编写自己的规则并将其放入该目录中，Guarddog 将允许你像选择或排除任何内置规则一样选择或排除它，并将发现结果附加到其输出中。
例如，你可以创建以下 semgrep 规则：
```
rules:
- id: sample-rule
languages:
- python
message: Output message when rule matches
metadata:
description: Description used in the CLI help
patterns:
YOUR RULE HEURISTICS GO HERE
severity: WARNING
```
然后你需要将其保存为 `sample-rule.yml`，并注意 id 必须与文件名
对于 Yara，你可以创建以下规则：
```
rule sample-rule
{
meta:
description = "Description used in the output message"
target_entity = "file"
strings:
$exec = "exec"
condition:
1 of them
}
```
然后你需要将其保存为 `sample-rule.yar`。
请注意，在这两种情况下，规则 id 必须与文件名匹配
## 在 GitHub Action 中运行 GuardDog
将 GuardDog 集成到你的 CI pipeline 中最简单的方法是利用 SARIF 输出格式，并将其上传到 GitHub 的 [代码扫描](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning)功能。
使用此方法，你将获得：
* 基于 GuardDog 扫描输出在你的 pull requests 中自动评论
* 直接在 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`
针对 Semgrep 规则运行单元测试：`make test-semgrep-rules`（测试位于[此处](
标签：云安全监控, 域名收集, 网络信息收集, 请求拦截, 逆向工具, 配置审计, 静态分析