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:

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:

• 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