GuardDog

O GuardDog é uma ferramenta de CLI que identifica pacotes PyPI e npm maliciosos, módulos Go, crates Rust, RubyGems, GitHub Actions ou extensões do VSCode. Ela executa análise estática no código-fonte dos pacotes (por meio de regras YARA) e analisa os metadados dos pacotes para detectar ataques à cadeia de suprimentos.

O que torna o GuardDog diferente: Em vez de apenas listar padrões suspeitos, o GuardDog correlaciona descobertas para identificar riscos reais com base em cadeias de ataque. Um pacote precisa ter tanto a capacidade de executar uma ação (por exemplo, acesso à rede) quanto um indicador de ameaça (por exemplo, domínio suspeito) no mesmo arquivo para ser sinalizado como de alto risco.

Ele baixa e analisa código de:

• NPM: Pacotes hospedados em npmjs.org
• PyPI: Arquivos-fonte (tar.gz) de pacotes hospedados em PyPI.org
• Go: Arquivos-fonte GoLang de repositórios hospedados em GitHub.com
• Rust: Crates hospedados em crates.io
• RubyGems: Pacotes Gem hospedados em rubygems.org
• GitHub Actions: Arquivos-fonte Javascript de repositórios hospedados em GitHub.com
• Extensões do VSCode: extensões (pacotes .vsix) hospedadas em marketplace.visualstudio.com

Como o GuardDog Funciona

O GuardDog usa um modelo de detecção baseado em riscos que correlaciona capacidades de código com indicadores de ameaça:

1. Detecção: As regras identificam capacidades (o que o código pode fazer) ou ameaças (indicadores suspeitos)
2. Correlação: Capacidades e ameaças encontradas no mesmo arquivo formam riscos (correspondências entre arquivos também formam riscos, com severidade reduzida)
3. Pontuação: Os riscos são pontuados (0-10) com base na completude e sofisticação da cadeia de ataque
4. Relatório: Os pacotes recebem uma classificação de severidade (baixa/média/alta) com detalhamento dos riscos

Por que essa abordagem?

Ferramentas SAST tradicionais sinalizam cada padrão suspeito de forma independente, levando à fadiga de alertas. O GuardDog entende que:

• Capacidade isolada não é maliciosa (bibliotecas de rede devem fazer requisições HTTP)
• Indicadores de ameaça isolados podem ser falsos positivos (fixtures de teste, documentação)
• Capacidade + Ameaça juntas indicam risco real (código que pode e irá fazer algo malicioso)

Pontuação de Riscos

Os pacotes recebem uma pontuação de 0 a 10 com base em quatro fatores:

Rótulos de Pontuação:

• 0: Nenhum risco detectado
• 0.1-3: Risco baixo (ameaças de estágio único, baixa especificidade)
• 3.1-7.5: Risco médio (cadeia de ataque parcial, indicadores de metadados ou achados de código de estágio único)
• 7.6-10: Risco alto (cadeia de ataque de múltiplos estágios com evidência no código-fonte — quase certeza de comprometimento)

Estágios da Cadeia de Ataque (baseados no MITRE ATT&CK):

• Início: Acesso inicial, capacidades de execução
• Meio: Persistência, evasão de defesa, acesso a credenciais
• Fim: Comando e controle, exfiltração, impacto

Conheça a nova integração do Datadog Agent e o pacote de conteúdo de Cloud SIEM para o GuardDog.

Começando

Instalação

A maneira mais fácil de executar o GuardDog é usar uvx:

uvx guarddog pypi scan requests

Para instalá-lo localmente:

uv tool install guarddog
# or
pip install guarddog

Ou use a imagem Docker:

docker pull ghcr.io/datadog/guarddog
alias guarddog='docker run --rm ghcr.io/datadog/guarddog'

Nota: No Windows, o único método de instalação suportado é o Docker.

Exemplos de uso

# 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

Varredura em Sandbox

Ao verificar pacotes, o GuardDog executa a análise do código-fonte dentro de um sandbox em nível de kernel (Linux via Landlock, macOS via Seatbelt, usando nono). O sandbox bloqueia todo o acesso à rede e restringe as operações do sistema de arquivos apenas aos caminhos necessários para a análise. Isso protege contra pacotes maliciosos que tentam executar código durante a extração de arquivos ou a varredura.

Por padrão, o sandbox é obrigatório: se ele não estiver disponível na plataforma, a varredura falha em vez de ser executada sem proteção. Para verificar sem ele, você deve passar explicitamente --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

Para pacotes remotos, três fases são executadas com diferentes níveis de privilégio:

1. Download e análise de metadados são executados sem sandbox (precisam de acesso à rede)
2. Extração do arquivo é executada em um subprocesso com sandbox (rede bloqueada, sistema de arquivos restrito)
3. Análise do código-fonte (YARA) é executada no processo principal após a aplicação do sandbox (rede bloqueada, sistema de arquivos restrito aos arquivos extraídos)

O sandbox foi introduzido para mitigar vulnerabilidades de path traversal e execução de código durante a extração de arquivos (CVE-2022-23530, CVE-2022-23531, CVE-2026-22870, CVE-2026-22871).

Verificando pacotes do S3

O GuardDog pode verificar um pacote armazenado no S3, seja como uma pasta/prefixo ou um único objeto de arquivo:

guarddog npm scan s3://my-bucket/path/to/package/
guarddog npm scan s3://my-bucket/path/to/package.tar.gz

Isso usa suas credenciais AWS existentes (variáveis de ambiente, ~/.aws, SSO ou função IAM). O GuardDog verifica a autenticação via STS antes de fazer qualquer coisa e encerra com um erro se nenhuma credencial válida for encontrada. Os objetos são sincronizados para um diretório temporário, verificados sob o sandbox como qualquer outro conteúdo não confiável e removidos do disco em seguida.

Regras

O GuardDog usa dois tipos de regras de detecção, ambos participantes do mecanismo de pontuação baseado em riscos:

• Regras de código-fonte (YARA): Análise estática do código-fonte do pacote que detecta capacidades e ameaças
• Regras de metadados (detectores Python): Análise dos metadados do registro de pacotes que detecta indicadores de ataques à cadeia de suprimentos

Para a lista completa de regras por ecossistema, veja RULES.md.

Para orientações sobre como escrever novas regras, veja WRITING_RULES.md.

Executando o GuardDog em uma GitHub Action

A maneira mais fácil de integrar o GuardDog ao seu pipeline de CI é aproveitar o formato de saída SARIF e enviá-lo para o recurso code scanning do GitHub.

Com isso, você obtém:

• Comentários automatizados nos seus pull requests com base na saída da varredura do GuardDog
• Gerenciamento integrado de falsos positivos diretamente na interface do GitHub

Exemplo de GitHub Action usando o 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

Desenvolvimento

Executando uma versão local do GuardDog

• Garanta que o poetry tenha um ambiente com python >=3.10 poetry env use 3.10.0
• Instale as dependências poetry install
• Execute o guarddog poetry run guarddog ou poetry shell e depois execute guarddog

Testes unitários

Executando todos os testes unitários: make test

Executando testes unitários contra heurísticas de metadados de pacotes: make test-metadata-rules (os testes estão aqui).

Benchmarking

Você pode executar o GuardDog em pacotes legítimos e maliciosos para determinar falsos positivos e falsos negativos. Veja ./tests/samples

Verificações de qualidade de código

Execute o verificador de tipos com

mypy --install-types --non-interactive guarddog

e o linter com

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

Configuração via Variáveis de Ambiente

O comportamento do GuardDog pode ser personalizado usando variáveis de ambiente:

Configuração Geral

Configuração de Regras de Metadados

Limites de Segurança na Extração de Arquivos

O GuardDog implementa várias verificações de segurança ao extrair arquivos de pacotes para proteger contra bombas de compressão e ataques de exaustão de descritores de arquivo:

Mantenedores

• Sebastian Obregoso
• Ian Kretz
• Tesnim Hamdouni

Autores

• Ellen Wang
• Christophe Tafani-Dereeper

Agradecimentos

Inspiração:

• 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