GuardDog

GuardDog est un outil en ligne de commande qui identifie les paquets PyPI et npm malveillants, les modules Go, les crates Rust, les gems RubyGems, les actions GitHub ou les extensions VSCode. Il exécute une analyse statique sur le code source des paquets (via des règles YARA) et analyse les métadonnées des paquets pour détecter les attaques de la chaîne d'approvisionnement.

Ce qui rend GuardDog différent : au lieu de simplement lister des motifs suspects, GuardDog corrèle les résultats pour identifier les risques réels basés sur les chaînes d'attaque. Un paquet doit posséder à la fois la capacité d'effectuer une action (par exemple, l'accès réseau) et un indicateur de menace (par exemple, un domaine suspect) dans le même fichier pour être signalé comme à haut risque.

Il télécharge et analyse le code de :

• NPM : Paquets hébergés sur npmjs.org
• PyPI : Paquets de fichiers source (tar.gz) hébergés sur PyPI.org
• Go : Fichiers source GoLang des dépôts hébergés sur GitHub.com
• Rust : Crates hébergés sur crates.io
• RubyGems : Paquets Gem hébergés sur rubygems.org
• GitHub Actions : Fichiers source JavaScript des dépôts hébergés sur GitHub.com
• Extensions VSCode : Paquets d'extensions (.vsix) hébergés sur marketplace.visualstudio.com

Comment fonctionne GuardDog

GuardDog utilise un modèle de détection basé sur les risques qui corrèle les capacités du code avec les indicateurs de menace :

1. Détection : Les règles identifient soit des capacités (ce que le code peut faire) soit des menaces (indicateurs suspects)
2. Corrélation : Les capacités et les menaces trouvées dans le même fichier forment des risques (les correspondances entre fichiers forment également des risques, avec une sévérité réduite)
3. Score : Les risques sont notés (0-10) en fonction de la complétude et de la sophistication de la chaîne d'attaque
4. Rapport : Les paquets reçoivent un niveau de sévérité (faible/moyen/élevé) avec un détail des risques

Pourquoi cette approche ?

Les outils SAST traditionnels signalent chaque motif suspect indépendamment, ce qui entraîne une fatigue d'alerte. GuardDog comprend que :

• La capacité seule n'est pas malveillante (les bibliothèques réseau doivent faire des requêtes HTTP)
• Les indicateurs de menace seuls peuvent être des faux positifs (fixtures de test, documentation)
• Capacité + Menace ensemble indique un risque réel (du code qui peut et va faire quelque chose de malveillant)

Score de risque

Les paquets reçoivent un score de 0-10 basé sur quatre facteurs :

Facteur	Pondération	Description
Sévérité	30 %	Résultat le plus sévère (faible/moyen/élevé)
Chaîne d'attaque	20 %	Présence d'étapes d'attaque complètes (précoce → intermédiaire/tardive)
Spécificité	30 %	Degré de spécificité des motifs aux logiciels malveillants par rapport au code légitime
Sophistication	20 %	Niveau d'avancement des techniques

Étiquettes de score :

• 0 : Aucun risque détecté
• 0,1-3 : Risque faible (menaces à une seule étape, faible spécificité)
• 3,1-7,5 : Risque moyen (chaîne d'attaque partielle, indicateurs de métadonnées ou résultats de code à une seule étape)
• 7,6-10 : Risque élevé (chaîne d'attaque en plusieurs étapes avec preuves dans le code source — quasi-certitude de compromission)

Étapes de la chaîne d'attaque (basées sur MITRE ATT&CK) :

• Précoce : Accès initial, capacités d'exécution
• Intermédiaire : Persistance, évasion de la défense, accès aux identifiants
• Tardive : Commande et contrôle, exfiltration, impact

---

Découvrez la nouvelle intégration Datadog Agent et le content pack Cloud SIEM pour GuardDog.

---

Pour commencer

Installation

Le moyen le plus simple d'exécuter GuardDog est d'utiliser uvx :

uvx guarddog pypi scan requests

Pour l'installer localement :

uv tool install guarddog
# ou
pip install guarddog

Ou utilisez l'image Docker :

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

Remarque : Sous Windows, la seule méthode d'installation prise en charge est Docker.

Exemples d'utilisation

# Analyse la version la plus récente du paquet 'requests'
guarddog pypi scan requests

# Analyse une version spécifique du paquet 'requests'
guarddog pypi scan requests --version 2.28.1

# Analyse le paquet 'request' en utilisant 2 heuristiques spécifiques
guarddog pypi scan requests --rules exec-base64 --rules code-execution

# Analyse le paquet 'requests' en utilisant toutes les règles sauf une
guarddog pypi scan requests --exclude-rules exec-base64

# Analyse une archive locale de paquet
guarddog pypi scan /tmp/triage.tar.gz

# Analyse un répertoire local de paquet
guarddog pypi scan /tmp/triage/

# Analyse un paquet stocké dans S3 (un dossier/préfixe ou un objet archive unique)
guarddog pypi scan s3://my-bucket/path/to/package/
guarddog pypi scan s3://my-bucket/path/to/package.tar.gz

# Analyse chaque paquet référencé dans un fichier requirements.txt d'un dossier local
guarddog pypi verify workspace/guarddog/requirements.txt

# Analyse chaque paquet référencé dans un fichier requirements.txt et génère un fichier sarif - fonctionne uniquement pour verify
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt

# Sortie JSON sur la sortie standard - fonctionne pour chaque commande
guarddog pypi scan requests --output-format=json

# Toutes les commandes fonctionnent également sur npm, go, crates, rubygems
guarddog npm scan express

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

guarddog go verify /tmp/repo/go.mod

# Analyse les crates Rust
guarddog crates scan serde

guarddog crates verify /tmp/repo/Cargo.lock

# Analyse les paquets RubyGems
guarddog rubygems scan rails

guarddog rubygems verify /tmp/repo/Gemfile.lock

# Peut également prendre en charge l'analyse des actions GitHub implémentées en JavaScript
guarddog github_action scan DataDog/synthetics-ci-github-action

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

# Analyse les extensions VSCode du marketplace
guarddog extension scan ms-python.python

# Analyse une version spécifique d'une extension VSCode
guarddog extension scan ms-python.python --version 2023.20.0

# Analyse un répertoire local d'extension VSCode ou une archive VSIX
guarddog extension scan /tmp/my-extension/

# Exécute en mode débogage
guarddog --log-level debug npm scan express

Analyse en sandbox