GuardDog

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:

NPM: Paquetes alojados en npmjs.org
PyPI: Archivos fuente (tar.gz) de paquetes alojados en PyPI.org
Go: Archivos fuente de GoLang de repositorios alojados en GitHub.com
Rust: Crates alojados en crates.io
RubyGems: Paquetes Gem alojados en rubygems.org
GitHub Actions: Archivos fuente de JavaScript de repositorios alojados en GitHub.com
Extensiones de VSCode: Paquetes de extensiones (.vsix) alojados en marketplace.visualstudio.com

Uso de demostración de GuardDog

Cómo funciona GuardDog

GuardDog utiliza un modelo de detección basado en riesgos que correlaciona las capacidades del código con los indicadores de amenaza:

Detección: Las reglas identifican capacidades (lo que el código puede hacer) o amenazas (indicadores sospechosos)
Correlación: Las capacidades y amenazas encontradas en el mismo archivo forman riesgos (las coincidencias entre archivos también forman riesgos, con severidad reducida)
Puntuación: Los riesgos se puntúan (0-10) según la completitud y sofisticación de la cadena de ataque
Informe: Los paquetes reciben una calificación de severidad (baja/media/alta) con un desglose detallado de riesgos

¿Por qué este enfoque?

Las herramientas SAST tradicionales marcan cada patrón sospechoso de forma independiente, lo que provoca fatiga de alertas. GuardDog entiende que:

Solo la capacidad no es maliciosa (las bibliotecas de red deberían hacer solicitudes HTTP)
Solo los indicadores de amenaza podrían ser falsos positivos (fixtures de pruebas, documentación)
Capacidad + Amenaza juntas indican un riesgo real (código que puede y va a hacer algo malicioso)

Puntuación de riesgos

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:

0: Sin riesgos detectados
0.1-3: Riesgo bajo (amenazas de una sola etapa, baja especificidad)
3.1-7.5: Riesgo medio (cadena de ataque parcial, indicadores de metadatos o hallazgos de código de una sola etapa)
7.6-10: Riesgo alto (cadena de ataque de múltiples etapas con evidencia en el código fuente — casi certeza de compromiso)

Etapas de la cadena de ataque (basadas en MITRE ATT&CK):

Temprana: Acceso inicial, capacidades de ejecución
Media: Persistencia, evasión de defensas, acceso a credenciales
Tardía: Comando y control, exfiltración, impacto

Consulta la nueva integración del Datadog Agent y el content pack de Cloud SIEM para GuardDog.

Primeros pasos

Instalación

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.

Ejemplos de uso

# 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

Escaneo en entorno aislado (sandbox)

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.

guarddog v3.2.0