guarddog

# GuardDog

[![Test](https://github.com/DataDog/guarddog/actions/workflows/checks.yml/badge.svg)](https://github.com/DataDog/guarddog/actions/workflows/checks.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/DataDog/guarddog/badge)](https://securityscorecards.dev/viewer/?uri=github.com/DataDog/guarddog)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12273/badge)](https://www.bestpractices.dev/projects/12273)

<p align="center">
  <img src="https://raw.githubusercontent.com/DataDog/guarddog/v3/docs/images/logo.png?raw=true" alt="GuardDog" width="300" />
</p>

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](https://www.npmjs.com/)
* PyPI: Arquivos-fonte (tar.gz) de pacotes hospedados em [PyPI.org](https://pypi.org/)
* Go: Arquivos-fonte GoLang de repositórios hospedados em [GitHub.com](https://github.com)
* Rust: Crates hospedados em [crates.io](https://crates.io/)
* RubyGems: Pacotes Gem hospedados em [rubygems.org](https://rubygems.org/)
* GitHub Actions: Arquivos-fonte Javascript de repositórios hospedados em [GitHub.com](https://github.com)
* Extensões do VSCode: extensões (pacotes .vsix) hospedadas em [marketplace.visualstudio.com](https://marketplace.visualstudio.com/)

![GuardDog demo usage](https://raw.githubusercontent.com/DataDog/guarddog/v3/docs/images/demo.png?raw=true)

## 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](https://docs.datadoghq.com/integrations/guarddog/) do Datadog Agent e o [pacote de conteúdo](https://app.datadoghq.com/security/siem/content-packs?query=guarddog) de Cloud SIEM para o GuardDog.
---

## Começando

### Instalação

A maneira mais fácil de executar o GuardDog é usar [`uvx`](https://docs.astral.sh/uv/guides/tools/):

```sh
uvx guarddog pypi scan requests
```

Para instalá-lo localmente:

```sh
uv tool install guarddog
# or
pip install guarddog
```

Ou use a imagem Docker:

```sh
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

```sh
# 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](https://github.com/always-further/nono-py)). 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`:

```sh
# 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:

```sh
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](https://github.com/datadog/guarddog/blob/v3/RULES.md)**.

Para orientações sobre como escrever novas regras, veja **[WRITING_RULES.md](https://github.com/datadog/guarddog/blob/v3/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](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-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:

```yaml
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](https://github.com/DataDog/guarddog/tree/v3/tests/analyzer/metadata)).

### Benchmarking

Você pode executar o GuardDog em pacotes legítimos e maliciosos para determinar falsos positivos e falsos negativos. Veja [./tests/samples](https://github.com/datadog/guarddog/blob/v3/tests/samples)

### Verificações de qualidade de código

Execute o verificador de tipos com
```shell
mypy --install-types --non-interactive guarddog
```
e o linter com
```shell
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

| 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` |

#### Configuração de Regras de Metadados

| 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` |

#### 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:

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

## Mantenedores

* [Sebastian Obregoso](https://www.linkedin.com/in/sebastianobregoso/)
* [Ian Kretz](https://github.com/ikretz)
* [Tesnim Hamdouni](https://github.com/tesnim5hamdouni)

## Autores
* [Ellen Wang](https://www.linkedin.com/in/ellen-wang-4bb5961a0/)
* [Christophe Tafani-Dereeper](https://github.com/christophetd)

## Agradecimentos

Inspiração:
* [Backstabber’s Knife Collection: A Review of Open Source Software Supply Chain Attacks](https://arxiv.org/pdf/2005.09535)
* [What are Weak Links in the npm Supply Chain?](https://arxiv.org/pdf/2112.10165.pdf)
* [A Survey on Common Threats in npm and PyPi Registries](https://arxiv.org/pdf/2108.09576.pdf)
* [A Benchmark Comparison of Python Malware Detection Approaches](https://arxiv.org/pdf/2209.13288.pdf)
* [Towards Measuring Supply Chain Attacks on Package Managers for Interpreted Languages](https://arxiv.org/pdf/2002.01139)