GuardDog

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:

• NPM: Pacchetti ospitati su npmjs.org
• PyPI: File sorgente (tar.gz) di pacchetti ospitati su PyPI.org
• Go: File sorgente GoLang di repository ospitate su GitHub.com
• Rust: Crate ospitati su crates.io
• RubyGems: Pacchetti Gem ospitati su rubygems.org
• GitHub Actions: File sorgente JavaScript di repository ospitate su GitHub.com
• Estensioni VSCode: Pacchetti di estensioni (.vsix) ospitati su marketplace.visualstudio.com

Come funziona GuardDog

GuardDog utilizza un modello di rilevamento basato sul rischio che correla le capacità del codice con gli indicatori di minaccia:

1. Rilevamento: Le regole identificano capacità (cosa il codice può fare) o minacce (indicatori sospetti)
2. Correlazione: Le capacità e le minacce trovate nello stesso file formano rischi (anche le corrispondenze tra file diversi formano rischi, con gravità ridotta)
3. Punteggio: I rischi vengono valutati (0-10) in base alla completezza e alla sofisticatezza della catena di attacco
4. Report: I pacchetti ricevono una valutazione di gravità (bassa/media/alta) con una ripartizione dettagliata dei rischi

Perché questo approccio?

Gli strumenti SAST tradizionali segnalano ogni pattern sospetto in modo indipendente, causando stanchezza da allarmi. GuardDog comprende che:

• La sola capacità non è dannosa (le librerie di rete devono effettuare richieste HTTP)
• I soli indicatori di minaccia potrebbero essere falsi positivi (fixture di test, documentazione)
• Capacità + minaccia insieme indicano un rischio reale (codice che può e farà qualcosa di dannoso)

Punteggio del rischio

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:

• 0: Nessun rischio rilevato
• 0.1-3: Rischio basso (minacce a fase singola, bassa specificità)
• 3.1-7.5: Rischio medio (catena di attacco parziale, indicatori nei metadati o risultati di codice a fase singola)
• 7.6-10: Rischio alto (catena di attacco a più fasi con prove nel codice sorgente — quasi certezza di compromissione)

Fasi della catena di attacco (basate su MITRE ATT&CK):

• Iniziale: Accesso iniziale, capacità di esecuzione
• Intermedia: Persistenza, evasione della difesa, accesso alle credenziali
• Finale: Comando e controllo, esfiltrazione, impatto

---

Scopri la nuova integrazione Datadog Agent e il content pack Cloud SIEM per GuardDog.

---

Per iniziare

Installazione

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.

Esempi di utilizzo

# 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

Scansione in sandbox

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: