datadog/guarddog🐍 🔍 GuardDog ist ein CLI-Tool zur Identifizierung bösartiger PyPI- und npm-Pakete
# 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)
<p align="center">
<img src="https://raw.githubusercontent.com/DataDog/guarddog/v3/docs/images/logo.png?raw=true" alt="GuardDog" width="300" />
</p>
GuardDog ist ein CLI-Tool, das bösartige PyPI- und npm-Pakete, Go-Module, Rust-Crates, RubyGems, GitHub Actions oder VSCode-Erweiterungen identifiziert. Es führt statische Analysen des Paketquellcodes (mittels YARA-Regeln) durch und analysiert Paketmetadaten, um Lieferkettenangriffe zu erkennen.
**Was GuardDog besonders macht:** Anstatt nur verdächtige Muster aufzulisten, korreliert GuardDog die Funde, um tatsächliche **Risiken** auf Basis von Angriffsketten zu identifizieren. Ein Paket benötigt sowohl die **Fähigkeit** (Capability), eine Aktion auszuführen (z. B. Netzwerkzugriff), als auch einen **Bedrohungsindikator** (z. B. verdächtige Domain) in derselben Datei, um als hohes Risiko eingestuft zu werden.
Es lädt Code herunter und scannt ihn von:
* NPM: Pakete, die auf [npmjs.org](https://www.npmjs.com/) gehostet werden
* PyPI: Quelldateien (tar.gz) von Paketen, die auf [PyPI.org](https://pypi.org/) gehostet werden
* Go: GoLang-Quelldateien von Repositorys, die auf [GitHub.com](https://github.com) gehostet werden
* Rust: Crates, die auf [crates.io](https://crates.io/) gehostet werden
* RubyGems: Gem-Pakete, die auf [rubygems.org](https://rubygems.org/) gehostet werden
* GitHub Actions: JavaScript-Quelldateien von Repositorys, die auf [GitHub.com](https://github.com) gehostet werden
* VSCode-Erweiterungen: Erweiterungen (.vsix), die auf [marketplace.visualstudio.com](https://marketplace.visualstudio.com/) gehostet werden
## So funktioniert GuardDog
GuardDog verwendet ein **risikobasiertes Erkennungsmodell**, das Code-Fähigkeiten mit Bedrohungsindikatoren korreliert:
1. **Erkennung**: Regeln identifizieren entweder **Fähigkeiten** (was Code *kann*) oder **Bedrohungen** (verdächtige Indikatoren)
2. **Korrelation**: Fähigkeiten und Bedrohungen, die in derselben Datei gefunden werden, bilden **Risiken** (dateiübergreifende Treffer bilden ebenfalls Risiken, jedoch mit herabgestufter Schwere)
3. **Bewertung**: Risiken werden anhand der Vollständigkeit und Raffinesse der Angriffskette bewertet (0–10)
4. **Berichterstattung**: Pakete erhalten eine Schweregrad-Einstufung (niedrig/mittel/hoch) mit detaillierter Risikoaufschlüsselung
### Warum dieser Ansatz?
Traditionelle SAST-Tools kennzeichnen jedes verdächtige Muster unabhängig voneinander, was zu Alarmmüdigkeit führt. GuardDog versteht, dass:
- **Fähigkeiten allein** nicht bösartig sind (Netzwerkbibliotheken sollten HTTP-Anfragen stellen)
- **Bedrohungsindikatoren allein** Fehlalarme sein können (Test-Fixtures, Dokumentation)
- **Fähigkeit + Bedrohung zusammen** ein tatsächliches Risiko anzeigen (Code, der etwas Bösartiges *kann* *und* *wird*)
### Risikobewertung
Pakete erhalten eine Punktzahl von **0–10**, basierend auf vier Faktoren:
| Faktor | Gewichtung | Beschreibung |
|--------|--------|-------------|
| **Schweregrad** | 30% | Höchster Schweregrad-Fund (niedrig/mittel/hoch) |
| **Angriffskette** | 20% | Vorhandensein vollständiger Angriffsstufen (früh → mittel/spät) |
| **Spezifität** | 30% | Wie spezifisch Muster für Malware im Vergleich zu legitimem Code sind |
| **Raffinesse** | 20% | Fortschrittsgrad der Technik |
**Bewertungsetiketten:**
- **0**: Keine Risiken erkannt
- **0.1–3**: Geringes Risiko (einstufige Bedrohungen, geringe Spezifität)
- **3.1–7.5**: Mittleres Risiko (partielle Angriffskette, Metadatenindikatoren oder einstufige Code-Funde)
- **7.6–10**: Hohes Risiko (mehrstufige Angriffskette mit Quellcode-Beweisen — nahezu sichere Kompromittierung)
**Angriffsketten-Stufen** (basierend auf MITRE ATT&CK):
- **Früh**: Erster Zugriff, Ausführungsfähigkeiten
- **Mittel**: Persistenz, Umgehung der Verteidigung, Zugriff auf Anmeldeinformationen
- **Spät**: Command & Control, Exfiltration, Auswirkung
---
### Schauen Sie sich die neue Datadog Agent [Integration](https://docs.datadoghq.com/integrations/guarddog/) und das Cloud SIEM [Content Pack](https://app.datadoghq.com/security/siem/content-packs?query=guarddog) für GuardDog an.
---
## Erste Schritte
### Installation
Der einfachste Weg, GuardDog auszuführen, ist die Verwendung von [`uvx`](https://docs.astral.sh/uv/guides/tools/):
```sh
uvx guarddog pypi scan requests
```
Für die lokale Installation:
```sh
uv tool install guarddog
# oder
pip install guarddog
```
Oder verwenden Sie das Docker-Image:
```sh
docker pull ghcr.io/datadog/guarddog
alias guarddog='docker run --rm ghcr.io/datadog/guarddog'
```
*Hinweis: Unter Windows ist Docker die einzige unterstützte Installationsmethode.*
### Beispielverwendung
```sh
# Die neueste Version des Pakets 'requests' scannen
guarddog pypi scan requests
# Eine bestimmte Version des Pakets 'requests' scannen
guarddog pypi scan requests --version 2.28.1
# Das Paket 'requests' mit 2 bestimmten Heuristiken scannen
guarddog pypi scan requests --rules exec-base64 --rules code-execution
# Das Paket 'requests' mit allen Regeln außer einer scannen
guarddog pypi scan requests --exclude-rules exec-base64
# Ein lokales Paketarchiv scannen
guarddog pypi scan /tmp/triage.tar.gz
# Ein lokales Paketverzeichnis scannen
guarddog pypi scan /tmp/triage/
# Ein in S3 gespeichertes Paket scannen (einen Ordner/Präfix oder ein einzelnes Archivobjekt)
guarddog pypi scan s3://my-bucket/path/to/package/
guarddog pypi scan s3://my-bucket/path/to/package.tar.gz
# Jedes Paket scannen, das in einer requirements.txt-Datei eines lokalen Ordners referenziert wird
guarddog pypi verify workspace/guarddog/requirements.txt
# Jedes Paket scannen, das in einer requirements.txt-Datei referenziert wird, und eine SARIF-Datei ausgeben – funktioniert nur für verify
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt
# JSON auf der Standardausgabe ausgeben – funktioniert für jeden Befehl
guarddog pypi scan requests --output-format=json
# Alle Befehle funktionieren auch für npm, go, crates, rubygems
guarddog npm scan express
guarddog go scan github.com/DataDog/dd-trace-go
guarddog go verify /tmp/repo/go.mod
# Rust-Crates scannen
guarddog crates scan serde
guarddog crates verify /tmp/repo/Cargo.lock
# RubyGems-Pakete scannen
guarddog rubygems scan rails
guarddog rubygems verify /tmp/repo/Gemfile.lock
# Zusätzlich kann das Scannen von GitHub Actions unterstützt werden, die in JavaScript implementiert sind
guarddog github_action scan DataDog/synthetics-ci-github-action
guarddog github_action verify /tmp/repo/.github/workflows/main.yml
# VSCode-Erweiterungen aus dem Marketplace scannen
guarddog extension scan ms-python.python
# Eine bestimmte Version einer VSCode-Erweiterung scannen
guarddog extension scan ms-python.python --version 2023.20.0
# Ein lokales VSCode-Erweiterungsverzeichnis oder ein VSIX-Archiv scannen
guarddog extension scan /tmp/my-extension/
# Im Debug-Modus ausführen
guarddog --log-level debug npm scan express
```
## Sandbox-Scans
Beim Scannen von Paketen führt GuardDog die Quellcode-Analyse innerhalb einer **Kernel-Sandbox** aus (Linux über Landlock, macOS über Seatbelt, mittels [nono](https://github.com/always-further/nono-py)). Die Sandbox blockiert den gesamten Netzwerkzugriff und schränkt Dateisystemoperationen auf die für die Analyse benötigten Pfade ein. Dies schützt vor bösartigen Paketen, die versuchen, während der Archivextraktion oder des Scans Code auszuführen.
Standardmäßig ist die Sandbox erforderlich: Wenn sie auf der Plattform nicht verfügbar ist, schlägt der Scan fehl, anstatt ungeschützt ausgeführt zu werden. Für einen Scan ohne Sandbox müssen Sie explizit `--no-sandbox` übergeben:
```sh
# Standard: Sandbox erforderlich, bei Nichtverfügbarkeit mit Fehler beenden
guarddog pypi scan requests
# Sandbox explizit deaktivieren
guarddog pypi scan requests --no-sandbox
```
Bei Remote-Paketen laufen drei Phasen mit unterschiedlichen Berechtigungsstufen ab:
1. **Download** und **Metadatenanalyse** laufen ohne Sandbox (benötigen Netzwerkzugriff)
2. Die **Archivextraktion** läuft in einem sandboxed Subprozess (Netzwerk blockiert, Dateisystem eingeschränkt)
3. Die **Quellcode-Analyse** (YARA) läuft im Hauptprozess, nachdem eine Sandbox angewendet wurde (Netzwerk blockiert, Dateisystem auf extrahierte Dateien beschränkt)
Die Sandbox wurde eingeführt, um Path-Traversal- und Codeausführungs-Schwachstellen während der Archivextraktion zu entschärfen (CVE-2022-23530, CVE-2022-23531, CVE-2026-22870, CVE-2026-22871).
## Scannen von Paketen aus S3
GuardDog kann ein in S3 gespeichertes Paket scannen, entweder als Ordner/Präfix oder als einzelnes Archivobjekt:
```sh
guarddog npm scan s3://my-bucket/path/to/package/
guarddog npm scan s3://my-bucket/path/to/package.tar.gz
```
Dabei werden Ihre vorhandenen AWS-Anmeldeinformationen verwendet (Umgebungsvariablen, `~/.aws`, SSO oder eine IAM-Rolle). GuardDog verifiziert die Authentifizierung vorab über STS und beendet den Vorgang mit einem Fehler, wenn keine gültigen Anmeldeinformationen gefunden werden. Die Objekte werden in ein temporäres Verzeichnis synchronisiert, unter der Sandbox wie jeder andere nicht vertrauenswürdige Inhalt gescannt und anschließend von der Festplatte entfernt.
## Regeln
GuardDog verwendet zwei Arten von Erkennungsregeln, die beide in die risikobasierte Bewertungs-Engine einfließen:
* **Quellcode-Regeln** (YARA): Statische Analyse des Paketquellcodes zur Erkennung von Fähigkeiten und Bedrohungen
* **Metadaten-Regeln** (Python-Detektoren): Analyse der Paketregister-Metadaten zur Erkennung von Indikatoren für Lieferkettenangriffe
Die vollständige Liste der Regeln pro Ökosystem finden Sie in **[RULES.md](https://github.com/datadog/guarddog/blob/v3/RULES.md)**.
Hinweise zum Schreiben neuer Regeln finden Sie in **[WRITING_RULES.md](https://github.com/datadog/guarddog/blob/v3/WRITING_RULES.md)**.
## GuardDog in einer GitHub Action ausführen
Der einfachste Weg, GuardDog in Ihre CI-Pipeline zu integrieren, ist die Nutzung des SARIF-Ausgabeformats und dessen Upload in das [Code Scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning)-Feature von GitHub.
Damit erhalten Sie:
* Automatisierte Kommentare zu Ihren Pull Requests basierend auf der GuardDog-Scanausgabe
* Integriertes False-Positive-Management direkt in der GitHub-Oberfläche
Beispiel-GitHub Action mit GuardDog:
```yaml
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
```
## Entwicklung
### Eine lokale Version von GuardDog ausführen
* Stellen Sie sicher, dass Poetry eine Umgebung mit `python >=3.10` hat: `poetry env use 3.10.0`
* Abhängigkeiten installieren: `poetry install`
* GuardDog ausführen: `poetry run guarddog` oder `poetry shell` und dann `guarddog` ausführen
### Unit-Tests
Alle Unit-Tests ausführen: `make test`
Unit-Tests gegen Paketmetadaten-Heuristiken ausführen: `make test-metadata-rules` (Tests finden Sie [hier](https://github.com/DataDog/guarddog/tree/v3/tests/analyzer/metadata)).
### Benchmarking
Sie können GuardDog auf legitimen und bösartigen Paketen ausführen, um False Positives und False Negatives zu ermitteln. Siehe [./tests/samples](https://github.com/datadog/guarddog/blob/v3/tests/samples)
### Codequalitätsprüfungen
Führen Sie den Typprüfer aus mit
```shell
mypy --install-types --non-interactive guarddog
```
und den Linter mit
```shell
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
```
### Konfiguration über Umgebungsvariablen
Das Verhalten von GuardDog kann über Umgebungsvariablen angepasst werden:
#### Allgemeine Konfiguration
| Umgebungsvariable | Beschreibung | Standardwert |
|---------------------|-------------|---------------|
| `GUARDDOG_PARALLELISM` | Anzahl der Threads für die parallele Verarbeitung | Anzahl der verfügbaren CPUs |
| `GUARDDOG_VERIFY_EXHAUSTIVE_DEPENDENCIES` | Alle möglichen Versionen von Abhängigkeiten analysieren (`true`/`false`) | `false` |
| `GUARDDOG_NPM_INCLUDE_DEV_DEPENDENCIES` | `devDependencies` beim Scannen von npm-`package.json`-Dateien einbeziehen (`true`/`false`); kann auch pro Aufruf mit `guarddog npm verify --include-dev-dependencies` umgeschaltet werden | `false` |
| `GUARDDOG_TOP_PACKAGES_CACHE_LOCATION` | Speicherort des Cache-Verzeichnisses für Top-Pakete | `guarddog/analyzer/metadata/resources` |
| `GUARDDOG_YARA_EXT_EXCLUDE` | Kommagetrennte Liste von Dateierweiterungen, die vom YARA-Scan ausgeschlossen werden sollen | `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` |
#### Konfiguration der Metadaten-Regeln
| Umgebungsvariable | Beschreibung | Standardwert |
|---------------------|-------------|---------------|
| `GUARDDOG_NEW_DEPENDENCY_RISK_THRESHOLD` | Mindestrisikobewertung für eine neu eingeführte Abhängigkeit, um das übergeordnete Paket in der Regel `risky_new_dependency` zu kennzeichnen | `5.0` |
#### Sicherheitslimits für die Archivextraktion
GuardDog implementiert mehrere Sicherheitsprüfungen beim Extrahieren von Paketarchiven, um vor Compression Bombs und Angriffen zur Erschöpfung von Dateideskriptoren zu schützen:
| Umgebungsvariable | Beschreibung | Standardwert |
|---------------------|-------------|---------------|
| `GUARDDOG_MAX_UNCOMPRESSED_SIZE` | Maximal zulässige unkomprimierte Größe in Bytes (verhindert das Erschöpfen des Speicherplatzes) | 2147483648 (2 GB) |
| `GUARDDOG_MAX_COMPRESSION_RATIO` | Maximal zulässiges Kompressionsverhältnis (erkennt verdächtige Kompressionsmuster) | 100 (100:1) |
| `GUARDDOG_MAX_FILE_COUNT` | Maximale Anzahl von Dateien, die in einem Archiv zulässig sind (verhindert die Erschöpfung von Dateideskriptoren/Inodes) | 100000 |
## Maintainer
* [Sebastian Obregoso](https://www.linkedin.com/in/sebastianobregoso/)
* [Ian Kretz](https://github.com/ikretz)
* [Tesnim Hamdouni](https://github.com/tesnim5hamdouni)
## Autoren
* [Ellen Wang](https://www.linkedin.com/in/ellen-wang-4bb5961a0/)
* [Christophe Tafani-Dereeper](https://github.com/christophetd)
## Danksagungen
Inspiration:
* [Backstabber’s Knife Collection: A Review of Open Source Software Supply Chain Attacks](https://arxiv.org/pdf/2005.09535)
* [What are Weak Links in the npm Supply Chain?](https://arxiv.org/pdf/2112.10165.pdf)
* [A Survey on Common Threats in npm and PyPi Registries](https://arxiv.org/pdf/2108.09576.pdf)
* [A Benchmark Comparison of Python Malware Detection Approaches](https://arxiv.org/pdf/2209.13288.pdf)
* [Towards Measuring Supply Chain Attacks on Package Managers for Interpreted Languages](https://arxiv.org/pdf/2002.01139)