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:

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:

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

1. Il download e l'analisi dei metadati vengono eseguiti senza sandbox (necessitano di accesso alla rete)
2. L'estrazione dell'archivio viene eseguita in un sottoprocesso in sandbox (rete bloccata, filesystem limitato)
3. L'analisi del codice sorgente (YARA) viene eseguita nel processo principale dopo l'applicazione di una sandbox (rete bloccata, filesystem limitato ai file estratti)

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

Scansione di pacchetti da S3

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.

Regole

GuardDog utilizza due tipi di regole di rilevamento, entrambe partecipano al motore di punteggio basato sul rischio:

• Regole sul codice sorgente (YARA): Analisi statica del codice sorgente del pacchetto per rilevare capacità e minacce
• Regole sui metadati (rilevatori Python): Analisi dei metadati del registro pacchetti per rilevare indicatori di attacchi alla supply chain

Per l'elenco completo delle regole per ogni ecosistema, vedere RULES.md.

Per indicazioni su come scrivere nuove regole, vedere WRITING_RULES.md.

Eseguire GuardDog in una GitHub Action

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:

• Commenti automatici sulle tue pull request basati sull'output della scansione di GuardDog
• Gestione integrata dei falsi positivi direttamente nell'interfaccia di GitHub

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

Sviluppo

Eseguire una versione locale di GuardDog

• Assicurati che poetry abbia un ambiente con python >=3.10 poetry env use 3.10.0
• Installa le dipendenze poetry install
• Esegui guarddog poetry run guarddog oppure poetry shell e poi esegui guarddog

Test unitari

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

Benchmark

Puoi eseguire GuardDog su pacchetti legittimi e dannosi per determinare falsi positivi e falsi negativi. Vedi ./tests/samples

Controlli di qualità del codice

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

Configurazione tramite variabili d'ambiente

Il comportamento di GuardDog può essere personalizzato tramite variabili d'ambiente:

Configurazione generale

Configurazione delle regole sui metadati

Limiti di sicurezza per l'estrazione degli archivi

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:

Maintainer

• Sebastian Obregoso
• Ian Kretz
• Tesnim Hamdouni

Autori

• Ellen Wang
• Christophe Tafani-Dereeper

Riconoscimenti

Ispirazione:

• 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