datadog/guarddog🐍 🔍 GuardDog è uno strumento CLI per identificare pacchetti PyPI e npm malevoli
GuardDog è uno strumento CLI che identifica pacchetti PyPI e npm dannosi, moduli Go, crate Rust, gemme RubyGems, azioni GitHub o estensioni VSCode. Esegue analisi statica sul codice sorgente dei pacchetti (attraverso regole YARA) e analizza i metadati dei pacchetti per rilevare attacchi alla supply chain.
Cosa rende GuardDog diverso: invece di limitarsi a elencare pattern sospetti, GuardDog correla i risultati per identificare veri rischi basati su catene di attacco. Un pacchetto deve avere sia la capacità di eseguire un'azione (ad es. accesso alla rete) sia un indicatore di minaccia (ad es. dominio sospetto) nello stesso file per essere segnalato come ad alto rischio.
Scarica e analizza il codice da:
GuardDog utilizza un modello di rilevamento basato sul rischio che correla le capacità del codice con gli indicatori di minaccia:
Gli strumenti SAST tradizionali segnalano ogni pattern sospetto in modo indipendente, causando stanchezza da allarmi. GuardDog comprende che:
I pacchetti ricevono un punteggio da 0-10 basato su quattro fattori:
| Fattore | Peso | Descrizione |
|---|---|---|
| Gravità | 30% | Il risultato con gravità più alta (bassa/media/alta) |
| Catena di attacco | 20% | Presenza di fasi di attacco complete (iniziale → intermedia/finale) |
| Specificità | 30% | Quanto i pattern sono specifici del malware rispetto al codice legittimo |
| Sofisticatezza | 20% | Livello di avanzamento delle tecniche |
Etichette dei punteggi:
Fasi della catena di attacco (basate su MITRE ATT&CK):
Il modo più semplice per eseguire GuardDog è usare uvx:
uvx guarddog pypi scan requests
Per installarlo localmente:
uv tool install guarddog
# or
pip install guarddog
Oppure usa l'immagine Docker:
docker pull ghcr.io/datadog/guarddog
alias guarddog='docker run --rm ghcr.io/datadog/guarddog'
Nota: su Windows, l'unico metodo di installazione supportato è Docker.
# Scan the most recent version of the 'requests' package
guarddog pypi scan requests
# Scan a specific version of the 'requests' package
guarddog pypi scan requests --version 2.28.1
# Scan the 'request' package using 2 specific heuristics
guarddog pypi scan requests --rules exec-base64 --rules code-execution
# Scan the 'requests' package using all rules but one
guarddog pypi scan requests --exclude-rules exec-base64
# Scan a local package archive
guarddog pypi scan /tmp/triage.tar.gz
# Scan a local package directory
guarddog pypi scan /tmp/triage/
# Scan a package stored in S3 (a folder/prefix or a single archive object)
guarddog pypi scan s3://my-bucket/path/to/package/
guarddog pypi scan s3://my-bucket/path/to/package.tar.gz
# Scan every package referenced in a requirements.txt file of a local folder
guarddog pypi verify workspace/guarddog/requirements.txt
# Scan every package referenced in a requirements.txt file and output a sarif file - works only for verify
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt
# Output JSON to standard output - works for every command
guarddog pypi scan requests --output-format=json
# All the commands also work on npm, go, crates, rubygems
guarddog npm scan express
guarddog go scan github.com/DataDog/dd-trace-go
guarddog go verify /tmp/repo/go.mod
# Scan Rust crates
guarddog crates scan serde
guarddog crates verify /tmp/repo/Cargo.lock
# Scan RubyGems packages
guarddog rubygems scan rails
guarddog rubygems verify /tmp/repo/Gemfile.lock
# Additionally can support scanning GitHub actions that are implemented in JavaScript
guarddog github_action scan DataDog/synthetics-ci-github-action
guarddog github_action verify /tmp/repo/.github/workflows/main.yml
# Scan VSCode extensions from the marketplace
guarddog extension scan ms-python.python
# Scan a specific version of a VSCode extension
guarddog extension scan ms-python.python --version 2023.20.0
# Scan a local VSCode extension directory or VSIX archive
guarddog extension scan /tmp/my-extension/
# Run in debug mode
guarddog --log-level debug npm scan express
Quando analizza i pacchetti, GuardDog esegue l'analisi del codice sorgente all'interno di una sandbox a livello di kernel (Linux tramite Landlock, macOS tramite Seatbelt, usando nono). La sandbox blocca tutto l'accesso alla rete e limita le operazioni sul filesystem ai soli percorsi necessari per l'analisi. Questo protegge da pacchetti dannosi che tentano di eseguire codice durante l'estrazione dell'archivio o la scansione.
Per impostazione predefinita, la sandbox è obbligatoria: se non è disponibile sulla piattaforma, la scansione fallisce invece di essere eseguita senza protezione. Per analizzare senza di essa, devi passare esplicitamente --no-sandbox:
# Default: require the sandbox, exit with an error if it's unavailable
guarddog pypi scan requests
# Explicitly disable the sandbox
guarddog pypi scan requests --no-sandbox
Per i pacchetti remoti, tre fasi vengono eseguite con diversi livelli di privilegio:
La sandbox è stata introdotta per mitigare le vulnerabilità di path traversal ed esecuzione di codice durante l'estrazione degli archivi (CVE-2022-23530, CVE-2022-23531, CVE-2026-22870, CVE-2026-22871).
GuardDog può analizzare un pacchetto archiviato in S3, sia come cartella/prefisso sia come singolo oggetto archivio:
guarddog npm scan s3://my-bucket/path/to/package/
guarddog npm scan s3://my-bucket/path/to/package.tar.gz
Questo utilizza le tue credenziali AWS esistenti (variabili d'ambiente, ~/.aws, SSO o un ruolo IAM). GuardDog verifica l'autenticazione tramite STS prima di fare qualsiasi cosa ed esce con un errore se non vengono trovate credenziali valide. Gli oggetti vengono sincronizzati in una directory temporanea, analizzati sotto la sandbox come qualsiasi altro contenuto non fidato e rimossi dal disco in seguito.
GuardDog utilizza due tipi di regole di rilevamento, entrambe partecipano al motore di punteggio basato sul rischio:
Per l'elenco completo delle regole per ogni ecosistema, vedere RULES.md.
Per indicazioni su come scrivere nuove regole, vedere WRITING_RULES.md.
Il modo più semplice per integrare GuardDog nella tua pipeline CI è sfruttare il formato di output SARIF e caricarlo nella funzionalità code scanning di GitHub.
In questo modo ottieni:
Esempio di GitHub Action che usa 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 poetry env use 3.10.0poetry installpoetry run guarddog oppure poetry shell e poi esegui guarddogPer eseguire tutti i test unitari: make test
Per eseguire i test unitari sulle euristiche dei metadati dei pacchetti: make test-metadata-rules (i test sono qui).
Puoi eseguire GuardDog su pacchetti legittimi e dannosi per determinare falsi positivi e falsi negativi. Vedi ./tests/samples
Esegui il type checker con
mypy --install-types --non-interactive guarddog
e il linter con
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
Il comportamento di GuardDog può essere personalizzato tramite variabili d'ambiente:
| Variabile d'ambiente | Descrizione | Valore predefinito |
|---|---|---|
GUARDDOG_PARALLELISM | Numero di thread da usare per l'elaborazione parallela | Numero di CPU disponibili |
GUARDDOG_VERIFY_EXHAUSTIVE_DEPENDENCIES | Analizza tutte le possibili versioni delle dipendenze (true/false) | false |
GUARDDOG_NPM_INCLUDE_DEV_DEPENDENCIES | Include devDependencies durante la scansione dei file npm package.json (true/false); può anche essere attivato per singola invocazione con guarddog npm verify --include-dev-dependencies | false |
GUARDDOG_TOP_PACKAGES_CACHE_LOCATION | Posizione della directory della cache dei pacchetti principali | guarddog/analyzer/metadata/resources |
GUARDDOG_YARA_EXT_EXCLUDE | Elenco separato da virgole di estensioni di file da escludere dalla scansione YARA | 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 |
| Variabile d'ambiente | Descrizione | Valore predefinito |
|---|---|---|
GUARDDOG_NEW_DEPENDENCY_RISK_THRESHOLD | Punteggio di rischio minimo per una dipendenza appena introdotta per segnalare il pacchetto padre nella regola risky_new_dependency | 5.0 |
GuardDog implementa molti controlli di sicurezza durante l'estrazione degli archivi dei pacchetti per proteggersi dalle compression bombs e dagli attacchi di esaurimento dei descrittori di file:
| Variabile d'ambiente | Descrizione | Valore predefinito |
|---|---|---|
GUARDDOG_MAX_UNCOMPRESSED_SIZE | Dimensione massima non compressa consentita in byte (previene l'esaurimento dello spazio su disco) | 2147483648 (2 GB) |
GUARDDOG_MAX_COMPRESSION_RATIO | Rapporto di compressione massimo consentito (rileva pattern di compressione sospetti) | 100 (100:1) |
GUARDDOG_MAX_FILE_COUNT | Numero massimo di file consentiti in un archivio (previene l'esaurimento dei descrittori di file/inode) | 100000 |
Ispirazione: