GuardDog

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 gehostet werden
• PyPI: Quelldateien (tar.gz) von Paketen, die auf PyPI.org gehostet werden
• Go: GoLang-Quelldateien von Repositorys, die auf GitHub.com gehostet werden
• Rust: Crates, die auf crates.io gehostet werden
• RubyGems: Gem-Pakete, die auf rubygems.org gehostet werden
• GitHub Actions: JavaScript-Quelldateien von Repositorys, die auf GitHub.com gehostet werden
• VSCode-Erweiterungen: Erweiterungen (.vsix), die auf 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:

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 und das Cloud SIEM Content Pack für GuardDog an.

Erste Schritte

Installation

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.

Beispielverwendung

# 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). 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:

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:

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.

Hinweise zum Schreiben neuer Regeln finden Sie in 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-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:

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).

Benchmarking

Sie können GuardDog auf legitimen und bösartigen Paketen ausführen, um False Positives und False Negatives zu ermitteln. Siehe ./tests/samples

Codequalitätsprüfungen

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

Konfiguration über Umgebungsvariablen

Das Verhalten von GuardDog kann über Umgebungsvariablen angepasst werden:

Allgemeine Konfiguration

Konfiguration der Metadaten-Regeln

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:

Maintainer

• Sebastian Obregoso
• Ian Kretz
• Tesnim Hamdouni

Autoren

• Ellen Wang
• Christophe Tafani-Dereeper

Danksagungen

Inspiration:

• 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