datadog/guarddog🐍 🔍 GuardDog es una herramienta CLI para identificar paquetes maliciosos de PyPI y npm
GuardDog es una herramienta CLI que identifica paquetes maliciosos de PyPI y npm, módulos de Go, crates de Rust, RubyGems, acciones de GitHub o extensiones de VSCode. Ejecuta análisis estático sobre el código fuente de los paquetes (mediante reglas YARA) y analiza los metadatos de los paquetes para detectar ataques a la cadena de suministro.
Qué hace diferente a GuardDog: En lugar de simplemente listar patrones sospechosos, GuardDog correlaciona los hallazgos para identificar riesgos reales basados en cadenas de ataque. Un paquete necesita tanto la capacidad de realizar una acción (p. ej., acceso a red) como un indicador de amenaza (p. ej., dominio sospechoso) en el mismo archivo para ser marcado como de alto riesgo.
Descarga y escanea código de:
GuardDog utiliza un modelo de detección basado en riesgos que correlaciona las capacidades del código con los indicadores de amenaza:
Las herramientas SAST tradicionales marcan cada patrón sospechoso de forma independiente, lo que provoca fatiga de alertas. GuardDog entiende que:
Los paquetes reciben una puntuación de 0-10 basada en cuatro factores:
| Factor | Peso | Descripción |
|---|---|---|
| Severidad | 30% | Hallazgo de mayor severidad (baja/media/alta) |
| Cadena de ataque | 20% | Presencia de etapas de ataque completas (temprana → media/tardía) |
| Especificidad | 30% | Qué tan específicos son los patrones del malware frente al código legítimo |
| Sofisticación | 20% | Nivel de avance de la técnica |
Etiquetas de puntuación:
Etapas de la cadena de ataque (basadas en MITRE ATT&CK):
La forma más sencilla de ejecutar GuardDog es usar uvx:
uvx guarddog pypi scan requests
Para instalarlo localmente:
uv tool install guarddog
# o
pip install guarddog
O usa la imagen de Docker:
docker pull ghcr.io/datadog/guarddog
alias guarddog='docker run --rm ghcr.io/datadog/guarddog'
Nota: En Windows, el único método de instalación compatible es Docker.
# Escanea la versión más reciente del paquete 'requests'
guarddog pypi scan requests
# Escanea una versión específica del paquete 'requests'
guarddog pypi scan requests --version 2.28.1
# Escanea el paquete 'requests' usando 2 heurísticas específicas
guarddog pypi scan requests --rules exec-base64 --rules code-execution
# Escanea el paquete 'requests' usando todas las reglas excepto una
guarddog pypi scan requests --exclude-rules exec-base64
# Escanea un archivo de paquete local
guarddog pypi scan /tmp/triage.tar.gz
# Escanea un directorio de paquete local
guarddog pypi scan /tmp/triage/
# Escanea un paquete almacenado en S3 (una carpeta/prefijo o un único objeto de archivo)
guarddog pypi scan s3://my-bucket/path/to/package/
guarddog pypi scan s3://my-bucket/path/to/package.tar.gz
# Escanea cada paquete referenciado en un archivo requirements.txt de una carpeta local
guarddog pypi verify workspace/guarddog/requirements.txt
# Escanea cada paquete referenciado en un archivo requirements.txt y genera un archivo sarif - solo funciona con verify
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt
# Genera JSON en la salida estándar - funciona para todos los comandos
guarddog pypi scan requests --output-format=json
# Todos los comandos también funcionan con npm, go, crates, rubygems
guarddog npm scan express
guarddog go scan github.com/DataDog/dd-trace-go
guarddog go verify /tmp/repo/go.mod
# Escanea crates de Rust
guarddog crates scan serde
guarddog crates verify /tmp/repo/Cargo.lock
# Escanea paquetes RubyGems
guarddog rubygems scan rails
guarddog rubygems verify /tmp/repo/Gemfile.lock
# También puede escanear acciones de GitHub implementadas en JavaScript
guarddog github_action scan DataDog/synthetics-ci-github-action
guarddog github_action verify /tmp/repo/.github/workflows/main.yml
# Escanea extensiones de VSCode desde el marketplace
guarddog extension scan ms-python.python
# Escanea una versión específica de una extensión de VSCode
guarddog extension scan ms-python.python --version 2023.20.0
# Escanea un directorio de extensión de VSCode local o un archivo VSIX
guarddog extension scan /tmp/my-extension/
# Ejecuta en modo de depuración
guarddog --log-level debug npm scan express
Al escanear paquetes, GuardDog ejecuta el análisis del código fuente dentro de un sandbox a nivel de kernel (Linux mediante Landlock, macOS mediante Seatbelt, usando nono). El sandbox bloquea todo el acceso a la red y restringe las operaciones del sistema de archivos solo a las rutas necesarias para el análisis. Esto protege contra paquetes maliciosos que intentan ejecutar código durante la extracción del archivo o el escaneo.
De forma predeterminada, el sandbox es obligatorio: si no está disponible en la plataforma, el escaneo falla en lugar de ejecutarse sin protección. Para escanear sin él, debes pasar explícitamente --no-sandbox:
# Predeterminado: requiere el sandbox, sale con un error si no está disponible
guarddog pypi scan requests
# Desactiva explícitamente el sandbox
guarddog pypi scan requests --no-sandbox
Para paquetes remotos, se ejecutan tres fases con diferentes niveles de privilegio:
El sandbox se introdujo para mitigar las vulnerabilidades de path traversal y ejecución de código durante la extracción de archivos (CVE-2022-23530, CVE-2022-23531, CVE-2026-22870, CVE-2026-22871).
GuardDog puede escanear un paquete almacenado en S3, ya sea como carpeta/prefijo o como un único objeto de archivo:
guarddog npm scan s3://my-bucket/path/to/package/
guarddog npm scan s3://my-bucket/path/to/package.tar.gz
Esto utiliza tus credenciales AWS existentes (variables de entorno, ~/.aws, SSO o un rol de IAM). GuardDog verifica la autenticación mediante STS antes de hacer nada y sale con un error si no se encuentran credenciales válidas. Los objetos se sincronizan a un directorio temporal, se escanean bajo el sandbox como cualquier otro contenido no confiable y se eliminan del disco después.
GuardDog utiliza dos tipos de reglas de detección, ambas participan en el motor de puntuación basado en riesgos:
Para la lista completa de reglas por ecosistema, consulta RULES.md.
Para obtener orientación sobre cómo escribir nuevas reglas, consulta WRITING_RULES.md.
La forma más sencilla de integrar GuardDog en tu pipeline de CI es aprovechar el formato de salida SARIF y subirlo a la función de code scanning de GitHub.
Con esto, obtienes:
Ejemplo de GitHub Action usando 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 o poetry shell y luego ejecuta guarddogEjecutar todas las pruebas unitarias: make test
Ejecutar pruebas unitarias contra las heurísticas de metadatos de paquetes: make test-metadata-rules (las pruebas están aquí).
Puedes ejecutar GuardDog en paquetes legítimos y maliciosos para determinar falsos positivos y falsos negativos. Consulta ./tests/samples
Ejecuta el verificador de tipos con
mypy --install-types --non-interactive guarddog
y el 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
El comportamiento de GuardDog se puede personalizar mediante variables de entorno:
| Variable de entorno | Descripción | Valor predeterminado |
|---|---|---|
GUARDDOG_PARALLELISM | Número de hilos a usar para el procesamiento en paralelo | Número de CPUs disponibles |
GUARDDOG_VERIFY_EXHAUSTIVE_DEPENDENCIES | Analizar todas las versiones posibles de dependencias (true/false) | false |
GUARDDOG_NPM_INCLUDE_DEV_DEPENDENCIES | Incluir devDependencies al escanear archivos package.json de npm (true/false); también se puede alternar por invocación con guarddog npm verify --include-dev-dependencies | false |
GUARDDOG_TOP_PACKAGES_CACHE_LOCATION | Ubicación del directorio de caché de paquetes principales | guarddog/analyzer/metadata/resources |
GUARDDOG_YARA_EXT_EXCLUDE | Lista separada por comas de extensiones de archivo a excluir del escaneo 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 |
| Variable de entorno | Descripción | Valor predeterminado |
|---|---|---|
GUARDDOG_NEW_DEPENDENCY_RISK_THRESHOLD | Puntuación de riesgo mínima para que una dependencia recién introducida marque el paquete principal en la regla risky_new_dependency | 5.0 |
GuardDog implementa múltiples controles de seguridad al extraer archivos de paquetes para proteger contra bombas de compresión y ataques de agotamiento de descriptores de archivo:
| Variable de entorno | Descripción | Valor predeterminado |
|---|---|---|
GUARDDOG_MAX_UNCOMPRESSED_SIZE | Tamaño máximo permitido sin comprimir en bytes (evita el agotamiento del espacio en disco) | 2147483648 (2 GB) |
GUARDDOG_MAX_COMPRESSION_RATIO | Relación de compresión máxima permitida (detecta patrones de compresión sospechosos) | 100 (100:1) |
GUARDDOG_MAX_FILE_COUNT | Número máximo de archivos permitidos en un archivo (evita el agotamiento de descriptores de archivo/inodos) | 100000 |
Inspiración: