datadog/guarddog🐍 🔍 O GuardDog é uma ferramenta CLI para identificar pacotes maliciosos do PyPI e npm
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:
O GuardDog usa um modelo de detecção baseado em riscos que correlaciona capacidades de código com indicadores de ameaça:
Ferramentas SAST tradicionais sinalizam cada padrão suspeito de forma independente, levando à fadiga de alertas. O GuardDog entende que:
Os pacotes recebem uma pontuação de 0 a 10 com base em quatro fatores:
| Fator | Peso | Descrição |
|---|---|---|
| Severidade | 30% | Achado de maior severidade (baixa/média/alta) |
| Cadeia de Ataque | 20% | Presença de estágios completos de ataque (início → meio/fim) |
| Especificidade | 30% | O quanto os padrões são específicos de malware versus código legítimo |
| Sofisticação | 20% | Nível de avanço da técnica |
Rótulos de Pontuação:
Estágios da Cadeia de Ataque (baseados no MITRE ATT&CK):
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.
# 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
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:
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).
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.
O GuardDog usa dois tipos de regras de detecção, ambos participantes do mecanismo de pontuação baseado em riscos:
Para a lista completa de regras por ecossistema, veja RULES.md.
Para orientações sobre como escrever novas regras, veja WRITING_RULES.md.
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:
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
python >=3.10 poetry env use 3.10.0poetry installpoetry run guarddog ou poetry shell e depois execute guarddogExecutando 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).
Você pode executar o GuardDog em pacotes legítimos e maliciosos para determinar falsos positivos e falsos negativos. Veja ./tests/samples
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
O comportamento do GuardDog pode ser personalizado usando variáveis de ambiente:
| Variável de Ambiente | Descrição | Valor Padrão |
|---|---|---|
GUARDDOG_PARALLELISM | Número de threads a serem usadas para processamento paralelo | Número de CPUs disponíveis |
GUARDDOG_VERIFY_EXHAUSTIVE_DEPENDENCIES | Analisa todas as versões possíveis das dependências (true/false) | false |
GUARDDOG_NPM_INCLUDE_DEV_DEPENDENCIES | Inclui devDependencies ao verificar arquivos package.json do npm (true/false); também pode ser alternado por invocação com guarddog npm verify --include-dev-dependencies | false |
GUARDDOG_TOP_PACKAGES_CACHE_LOCATION | Localização do diretório de cache dos pacotes principais | guarddog/analyzer/metadata/resources |
GUARDDOG_YARA_EXT_EXCLUDE | Lista separada por vírgulas de extensões de arquivo a serem excluídas da varredura 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 |
| Variável de Ambiente | Descrição | Valor Padrão |
|---|---|---|
GUARDDOG_NEW_DEPENDENCY_RISK_THRESHOLD | Pontuação mínima de risco para uma dependência recém-introduzida sinalizar o pacote pai na regra risky_new_dependency | 5.0 |
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:
| Variável de Ambiente | Descrição | Valor Padrão |
|---|---|---|
GUARDDOG_MAX_UNCOMPRESSED_SIZE | Tamanho máximo permitido sem compressão em bytes (evita esgotamento do espaço em disco) | 2147483648 (2 GB) |
GUARDDOG_MAX_COMPRESSION_RATIO | Taxa de compressão máxima permitida (detecta padrões de compressão suspeitos) | 100 (100:1) |
GUARDDOG_MAX_FILE_COUNT | Número máximo de arquivos permitido em um arquivo (evita esgotamento de descritores de arquivo/inodes) | 100000 |
Inspiração: