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>

GuardDog — это CLI-инструмент, который выявляет вредоносные пакеты PyPI и npm, модули Go, крейты Rust, гемы RubyGems, GitHub Actions и расширения VSCode. Он выполняет статический анализ исходного кода пакетов (с помощью YARA-правил) и анализирует метаданные пакетов для обнаружения атак на цепочку поставок.

**Что делает GuardDog особенным:** вместо простого перечисления подозрительных паттернов GuardDog сопоставляет находки, чтобы выявить реальные **риски** на основе цепочек атак. Пакет должен обладать как **возможностью** выполнить действие (например, доступ к сети), так и **индикатором угрозы** (например, подозрительный домен) в одном и том же файле, чтобы быть помеченным как высокорисковый.

Он загружает и сканирует код из:

* NPM: пакеты, размещённые на [npmjs.org](https://www.npmjs.com/)
* PyPI: исходные файлы (tar.gz) пакетов, размещённых на [PyPI.org](https://pypi.org/)
* Go: исходные файлы GoLang репозиториев, размещённых на [GitHub.com](https://github.com)
* Rust: крейты, размещённые на [crates.io](https://crates.io/)
* RubyGems: гемы, размещённые на [rubygems.org](https://rubygems.org/)
* GitHub Actions: JavaScript-исходные файлы репозиториев, размещённых на [GitHub.com](https://github.com)
* Расширения VSCode: пакеты расширений (.vsix), размещённые на [marketplace.visualstudio.com](https://marketplace.visualstudio.com/)

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

## Как работает GuardDog

GuardDog использует **риск-ориентированную модель обнаружения**, которая сопоставляет возможности кода с индикаторами угроз:

1. **Обнаружение**: правила выявляют либо **возможности** (что код *может* делать), либо **угрозы** (подозрительные индикаторы)
2. **Сопоставление**: возможности и угрозы, найденные в одном файле, образуют **риски** (совпадения между разными файлами также образуют риски, но с пониженной серьёзностью)
3. **Оценка**: риски получают баллы (0-10) на основе полноты и сложности цепочки атак
4. **Отчётность**: пакеты получают уровень серьёзности (низкий/средний/высокий) с детальной разбивкой рисков

### Почему такой подход?

Традиционные SAST-инструменты помечают каждый подозрительный паттерн независимо, что приводит к усталости от ложных срабатываний. GuardDog понимает, что:

- **Только возможность** не является вредоносной (сетевые библиотеки должны выполнять HTTP-запросы)
- **Только индикаторы угроз** могут быть ложными срабатываниями (тестовые фикстуры, документация)
- **Возможность + угроза вместе** указывают на реальный риск (код, который может *и будет* делать что-то вредоносное)

### Оценка рисков

Пакеты получают балл от **0 до 10** на основе четырёх факторов:

| Фактор | Вес | Описание |
|--------|--------|-------------|
| **Серьёзность** | 30% | Наиболее серьёзная находка (низкая/средняя/высокая) |
| **Цепочка атак** | 20% | Наличие полных стадий атаки (ранняя → средняя/поздняя) |
| **Специфичность** | 30% | Насколько паттерны специфичны для вредоносного ПО по сравнению с легитимным кодом |
| **Сложность** | 20% | Уровень продвинутости техники |

**Метки оценок:**
- **0**: риски не обнаружены
- **0.1-3**: низкий риск (одностадийные угрозы, низкая специфичность)
- **3.1-7.5**: средний риск (частичная цепочка атак, индикаторы в метаданных или одностадийные находки в коде)
- **7.6-10**: высокий риск (многостадийная цепочка атак с доказательствами в исходном коде — почти полная уверенность в компрометации)

**Стадии цепочки атак** (на основе MITRE ATT&CK):
- **Ранняя**: начальный доступ, возможности выполнения
- **Средняя**: закрепление, обход защиты, доступ к учётным данным
- **Поздняя**: командный центр, эксфильтрация, воздействие
---
### Ознакомьтесь с новой [интеграцией](https://docs.datadoghq.com/integrations/guarddog/) Datadog Agent и [контент-паком](https://app.datadoghq.com/security/siem/content-packs?query=guarddog) Cloud SIEM для GuardDog.
---

## Начало работы

### Установка

Самый простой способ запустить GuardDog — использовать [`uvx`](https://docs.astral.sh/uv/guides/tools/):

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

Для локальной установки:

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

Или используйте Docker-образ:

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

*Примечание: в Windows единственный поддерживаемый способ установки — Docker.*

### Примеры использования

```sh
# Сканировать самую свежую версию пакета 'requests'
guarddog pypi scan requests

# Сканировать конкретную версию пакета 'requests'
guarddog pypi scan requests --version 2.28.1

# Сканировать пакет 'requests' с использованием 2 конкретных эвристик
guarddog pypi scan requests --rules exec-base64 --rules code-execution

# Сканировать пакет 'requests' со всеми правилами, кроме одного
guarddog pypi scan requests --exclude-rules exec-base64

# Сканировать локальный архив пакета
guarddog pypi scan /tmp/triage.tar.gz

# Сканировать локальную директорию пакета
guarddog pypi scan /tmp/triage/

# Сканировать пакет, хранящийся в S3 (папку/префикс или отдельный объект архива)
guarddog pypi scan s3://my-bucket/path/to/package/
guarddog pypi scan s3://my-bucket/path/to/package.tar.gz

# Сканировать каждый пакет, указанный в файле requirements.txt локальной папки
guarddog pypi verify workspace/guarddog/requirements.txt

# Сканировать каждый пакет из requirements.txt и вывести результат в sarif-файл — работает только для verify
guarddog pypi verify --output-format=sarif workspace/guarddog/requirements.txt

# Вывести JSON в стандартный поток вывода — работает для всех команд
guarddog pypi scan requests --output-format=json

# Все команды также работают для npm, go, crates, rubygems
guarddog npm scan express

guarddog go scan github.com/DataDog/dd-trace-go

guarddog go verify /tmp/repo/go.mod

# Сканировать крейты Rust
guarddog crates scan serde

guarddog crates verify /tmp/repo/Cargo.lock

# Сканировать пакеты RubyGems
guarddog rubygems scan rails

guarddog rubygems verify /tmp/repo/Gemfile.lock

# Дополнительно поддерживается сканирование GitHub Actions, реализованных на JavaScript
guarddog github_action scan DataDog/synthetics-ci-github-action

guarddog github_action verify /tmp/repo/.github/workflows/main.yml

# Сканировать расширения VSCode из маркетплейса
guarddog extension scan ms-python.python

# Сканировать конкретную версию расширения VSCode
guarddog extension scan ms-python.python --version 2023.20.0

# Сканировать локальную директорию расширения VSCode или VSIX-архив
guarddog extension scan /tmp/my-extension/

# Запуск в режиме отладки
guarddog --log-level debug npm scan express
```


## Сканирование в песочнице

При сканировании пакетов GuardDog выполняет анализ исходного кода внутри **песочницы на уровне ядра** (Linux через Landlock, macOS через Seatbelt, с использованием [nono](https://github.com/always-further/nono-py)). Песочница блокирует весь сетевой доступ и ограничивает операции с файловой системой только теми путями, которые необходимы для анализа. Это защищает от вредоносных пакетов, пытающихся выполнить код во время извлечения архива или сканирования.

По умолчанию песочница обязательна: если она недоступна на платформе, сканирование завершается ошибкой, а не выполняется без защиты. Чтобы сканировать без неё, необходимо явно передать `--no-sandbox`:

```sh
# По умолчанию: требуется песочница, при её отсутствии выводится ошибка и выход
guarddog pypi scan requests

# Явное отключение песочницы
guarddog pypi scan requests --no-sandbox
```

Для удалённых пакетов три фазы выполняются с разными уровнями привилегий:
1. **Загрузка** и **анализ метаданных** выполняются без песочницы (требуется сетевой доступ)
2. **Извлечение архива** выполняется в изолированном подпроцессе (сеть заблокирована, файловая система ограничена)
3. **Анализ исходного кода** (YARA) выполняется в основном процессе после применения песочницы (сеть заблокирована, файловая система ограничена извлечёнными файлами)

Песочница была введена для снижения риска уязвимостей path traversal и выполнения кода при извлечении архивов (CVE-2022-23530, CVE-2022-23531, CVE-2026-22870, CVE-2026-22871).

## Сканирование пакетов из S3

GuardDog может сканировать пакет, хранящийся в S3, либо как папку/префикс, либо как отдельный объект архива:

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

При этом используются ваши существующие учётные данные AWS (переменные окружения, `~/.aws`, SSO или IAM-роль). GuardDog проверяет аутентификацию через STS перед началом работы и завершается с ошибкой, если действительные учётные данные не найдены. Объекты синхронизируются во временную директорию, сканируются в песочнице, как и любой другой недоверенный контент, а затем удаляются с диска.

## Правила

GuardDog использует два типа правил обнаружения, оба участвуют в риск-ориентированной системе оценки:

* **Правила для исходного кода** (YARA): статический анализ исходного кода пакета для обнаружения возможностей и угроз
* **Правила для метаданных** (детекторы на Python): анализ метаданных реестра пакетов для обнаружения индикаторов атак на цепочку поставок

Полный список правил для каждой экосистемы см. в **[RULES.md](https://github.com/datadog/guarddog/blob/v3/RULES.md)**.

Руководство по написанию новых правил см. в **[WRITING_RULES.md](https://github.com/datadog/guarddog/blob/v3/WRITING_RULES.md)**.

## Запуск GuardDog в GitHub Action

Самый простой способ интегрировать GuardDog в ваш CI-конвейер — использовать формат вывода SARIF и загружать его в функцию [code scanning](https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/about-code-scanning) GitHub.

Благодаря этому вы получаете:
* Автоматические комментарии к вашим pull request на основе результатов сканирования GuardDog
* Встроенное управление ложными срабатываниями прямо в интерфейсе GitHub


Пример GitHub Action с использованием 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
```


## Разработка

### Запуск локальной версии GuardDog

* Убедитесь, что poetry имеет окружение с `python >=3.10`: `poetry env use 3.10.0`
* Установите зависимости: `poetry install`
* Запустите guarddog: `poetry run guarddog` или `poetry shell`, а затем выполните `guarddog`

### Модульные тесты

Запуск всех модульных тестов: `make test`

Запуск модульных тестов для эвристик по метаданным пакетов: `make test-metadata-rules` (тесты находятся [здесь](https://github.com/DataDog/guarddog/tree/v3/tests/analyzer/metadata)).

### Бенчмаркинг

Вы можете запускать GuardDog на легитимных и вредоносных пакетах, чтобы определить ложные срабатывания и пропуски. См. [./tests/samples](https://github.com/datadog/guarddog/blob/v3/tests/samples)

### Проверки качества кода

Запустите проверку типов с помощью
```shell
mypy --install-types --non-interactive guarddog
```
и линтер с помощью
```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
```

### Конфигурация через переменные окружения

Поведение GuardDog можно настраивать с помощью переменных окружения:

#### Общая конфигурация

| Переменная окружения | Описание | Значение по умолчанию |
|---------------------|-------------|---------------|
| `GUARDDOG_PARALLELISM` | Количество потоков для параллельной обработки | Количество доступных CPU |
| `GUARDDOG_VERIFY_EXHAUSTIVE_DEPENDENCIES` | Анализировать все возможные версии зависимостей (`true`/`false`) | `false` |
| `GUARDDOG_NPM_INCLUDE_DEV_DEPENDENCIES` | Включать `devDependencies` при сканировании npm-файлов `package.json` (`true`/`false`); также можно переключать при каждом вызове с помощью `guarddog npm verify --include-dev-dependencies` | `false` |
| `GUARDDOG_TOP_PACKAGES_CACHE_LOCATION` | Расположение директории кэша популярных пакетов | `guarddog/analyzer/metadata/resources` |
| `GUARDDOG_YARA_EXT_EXCLUDE` | Разделённый запятыми список расширений файлов, исключаемых из 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` |

#### Конфигурация правил по метаданным

| Переменная окружения | Описание | Значение по умолчанию |
|---------------------|-------------|---------------|
| `GUARDDOG_NEW_DEPENDENCY_RISK_THRESHOLD` | Минимальный балл риска для недавно добавленной зависимости, чтобы пометить родительский пакет в правиле `risky_new_dependency` | `5.0` |

#### Лимиты безопасности при извлечении архивов

GuardDog реализует несколько проверок безопасности при извлечении архивов пакетов для защиты от бомб сжатия и атак с исчерпанием файловых дескрипторов:

| Переменная окружения | Описание | Значение по умолчанию |
|---------------------|-------------|---------------|
| `GUARDDOG_MAX_UNCOMPRESSED_SIZE` | Максимально допустимый несжатый размер в байтах (предотвращает исчерпание дискового пространства) | 2147483648 (2 ГБ) |
| `GUARDDOG_MAX_COMPRESSION_RATIO` | Максимально допустимый коэффициент сжатия (обнаруживает подозрительные паттерны сжатия) | 100 (100:1) |
| `GUARDDOG_MAX_FILE_COUNT` | Максимальное количество файлов, допустимое в архиве (предотвращает исчерпание файловых дескрипторов/inode) | 100000 |

## Мейнтейнеры

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

## Авторы
* [Ellen Wang](https://www.linkedin.com/in/ellen-wang-4bb5961a0/)
* [Christophe Tafani-Dereeper](https://github.com/christophetd)

## Благодарности

Вдохновение:
* [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)