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

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:

1. Detección: Las reglas identifican capacidades (lo que el código puede hacer) o amenazas (indicadores sospechosos)
2. Correlación: Las capacidades y amenazas encontradas en el mismo archivo forman riesgos (las coincidencias entre archivos también forman riesgos, con severidad reducida)
3. Puntuación: Los riesgos se puntúan (0-10) según la completitud y sofisticación de la cadena de ataque
4. 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:

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.

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:

1. La descarga y el análisis de metadatos se ejecutan sin sandbox (necesitan acceso a la red)
2. La extracción del archivo se ejecuta en un subproceso aislado (red bloqueada, sistema de archivos restringido)
3. El análisis del código fuente (YARA) se ejecuta en el proceso principal después de aplicar un sandbox (red bloqueada, sistema de archivos restringido a los archivos extraídos)

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

Escaneo de paquetes desde S3

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.

Reglas

GuardDog utiliza dos tipos de reglas de detección, ambas participan en el motor de puntuación basado en riesgos:

• Reglas de código fuente (YARA): Análisis estático del código fuente del paquete que detecta capacidades y amenazas
• Reglas de metadatos (detectores de Python): Análisis de los metadatos del registro de paquetes que detecta indicadores de ataques a la cadena de suministro

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.

Ejecutar GuardDog en una GitHub Action

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:

• Comentarios automáticos en tus pull requests basados en la salida del escaneo de GuardDog
• Gestión de falsos positivos integrada directamente en la interfaz de GitHub

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

Desarrollo

Ejecutar una versión local de GuardDog

• Asegúrate de que poetry tenga un entorno con python >=3.10 poetry env use 3.10.0
• Instala las dependencias poetry install
• Ejecuta guarddog poetry run guarddog o poetry shell y luego ejecuta guarddog

Pruebas unitarias

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

Evaluación comparativa (benchmarking)

Puedes ejecutar GuardDog en paquetes legítimos y maliciosos para determinar falsos positivos y falsos negativos. Consulta ./tests/samples

Controles de calidad del código

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

Configuración mediante variables de entorno

El comportamiento de GuardDog se puede personalizar mediante variables de entorno:

Configuración general

Configuración de reglas de metadatos

Límites de seguridad en la extracción de archivos

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:

Mantenedores

• Sebastian Obregoso
• Ian Kretz
• Tesnim Hamdouni

Autores

• Ellen Wang
• Christophe Tafani-Dereeper

Agradecimientos

Inspiración:

• 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