datadog/guarddog🐍 🔍 GuardDog ist ein CLI-Tool zur Identifizierung bösartiger PyPI- und npm-Pakete
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:
GuardDog verwendet ein risikobasiertes Erkennungsmodell, das Code-Fähigkeiten mit Bedrohungsindikatoren korreliert:
Traditionelle SAST-Tools kennzeichnen jedes verdächtige Muster unabhängig voneinander, was zu Alarmmüdigkeit führt. GuardDog versteht, dass:
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:
Angriffsketten-Stufen (basierend auf MITRE ATT&CK):
Der einfachste Weg, GuardDog auszuführen, ist die Verwendung von uvx:
uvx guarddog pypi scan requests
Für die lokale Installation:
uv tool install guarddog
# oder
pip install guarddog
Oder verwenden Sie das Docker-Image:
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.
# 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
Beim Scannen von Paketen führt GuardDog die Quellcode-Analyse innerhalb einer Kernel-Sandbox aus (Linux über Landlock, macOS über Seatbelt, mittels nono). 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:
# 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:
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).
GuardDog kann ein in S3 gespeichertes Paket scannen, entweder als Ordner/Präfix oder als einzelnes Archivobjekt:
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.
GuardDog verwendet zwei Arten von Erkennungsregeln, die beide in die risikobasierte Bewertungs-Engine einfließen:
Die vollständige Liste der Regeln pro Ökosystem finden Sie in RULES.md.
Hinweise zum Schreiben neuer Regeln finden Sie in WRITING_RULES.md.
Der einfachste Weg, GuardDog in Ihre CI-Pipeline zu integrieren, ist die Nutzung des SARIF-Ausgabeformats und dessen Upload in das Code Scanning-Feature von GitHub.
Damit erhalten Sie:
Beispiel-GitHub Action mit GuardDog:
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
python >=3.10 hat: poetry env use 3.10.0poetry installpoetry run guarddog oder poetry shell und dann guarddog ausführenAlle Unit-Tests ausführen: make test
Unit-Tests gegen Paketmetadaten-Heuristiken ausführen: make test-metadata-rules (Tests finden Sie hier).
Sie können GuardDog auf legitimen und bösartigen Paketen ausführen, um False Positives und False Negatives zu ermitteln. Siehe ./tests/samples
Führen Sie den Typprüfer aus mit
mypy --install-types --non-interactive guarddog
und den Linter mit
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
Das Verhalten von GuardDog kann über Umgebungsvariablen angepasst werden:
| 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 |
| 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 |
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 |
Inspiration: