guarddog v3.2.0
🐍 🔍 GuardDog — это CLI-инструмент для выявления вредоносных пакетов PyPI и npm
GuardDog
GuardDog — это CLI-инструмент, который выявляет вредоносные пакеты PyPI и npm, модули Go, крейты Rust, гемы RubyGems, GitHub Actions и расширения VSCode. Он выполняет статический анализ исходного кода пакетов (с помощью YARA-правил) и анализирует метаданные пакетов для обнаружения атак на цепочку поставок.
Что делает GuardDog особенным: вместо простого перечисления подозрительных паттернов GuardDog сопоставляет находки, чтобы выявить реальные риски на основе цепочек атак. Пакет должен обладать как возможностью выполнить действие (например, доступ к сети), так и индикатором угрозы (например, подозрительный домен) в одном и том же файле, чтобы быть помеченным как высокорисковый.
Он загружает и сканирует код из:
- NPM: пакеты, размещённые на npmjs.org
- PyPI: исходные файлы (tar.gz) пакетов, размещённых на PyPI.org
- Go: исходные файлы GoLang репозиториев, размещённых на GitHub.com
- Rust: крейты, размещённые на crates.io
- RubyGems: гемы, размещённые на rubygems.org
- GitHub Actions: JavaScript-исходные файлы репозиториев, размещённых на GitHub.com
- Расширения VSCode: пакеты расширений (.vsix), размещённые на marketplace.visualstudio.com
Как работает GuardDog
GuardDog использует риск-ориентированную модель обнаружения, которая сопоставляет возможности кода с индикаторами угроз:
- Обнаружение: правила выявляют либо возможности (что код может делать), либо угрозы (подозрительные индикаторы)
- Сопоставление: возможности и угрозы, найденные в одном файле, образуют риски (совпадения между разными файлами также образуют риски, но с пониженной серьёзностью)
- Оценка: риски получают баллы (0-10) на основе полноты и сложности цепочки атак
- Отчётность: пакеты получают уровень серьёзности (низкий/средний/высокий) с детальной разбивкой рисков
Почему такой подход?
Традиционные SAST-инструменты помечают каждый подозрительный паттерн независимо, что приводит к усталости от ложных срабатываний. GuardDog понимает, что:
- Только возможность не является вредоносной (сетевые библиотеки должны выполнять HTTP-запросы)
- Только индикаторы угроз могут быть ложными срабатываниями (тестовые фикстуры, документация)
- Возможность + угроза вместе указывают на реальный риск (код, который может и будет делать что-то вредоносное)
Оценка рисков
Пакеты получают балл от 0 до 10 на основе четырёх факторов:
| Фактор | Вес | Описание |
|---|---|---|
| Серьёзность | 30% | Наиболее серьёзная находка (низкая/средняя/высокая) |
| Цепочка атак | 20% | Наличие полных стадий атаки (ранняя → средняя/поздняя) |
| Специфичность | 30% | Насколько паттерны специфичны для вредоносного ПО по сравнению с легитимным кодом |
| Сложность | 20% | Уровень продвинутости техники |
Метки оценок:
- 0: риски не обнаружены
- 0.1-3: низкий риск (одностадийные угрозы, низкая специфичность)
- 3.1-7.5: средний риск (частичная цепочка атак, индикаторы в метаданных или одностадийные находки в коде)
- 7.6-10: высокий риск (многостадийная цепочка атак с доказательствами в исходном коде — почти полная уверенность в компрометации)
Стадии цепочки атак (на основе MITRE ATT&CK):
- Ранняя: начальный доступ, возможности выполнения
- Средняя: закрепление, обход защиты, доступ к учётным данным
- Поздняя: командный центр, эксфильтрация, воздействие
Ознакомьтесь с новой интеграцией Datadog Agent и контент-паком Cloud SIEM для GuardDog.
Начало работы
Установка
Самый простой способ запустить GuardDog — использовать uvx:
uvx guarddog pypi scan requests
Для локальной установки:
uv tool install guarddog
# or
pip install guarddog
Или используйте Docker-образ:
docker pull ghcr.io/datadog/guarddog
alias guarddog='docker run --rm ghcr.io/datadog/guarddog'
Примечание: в Windows единственный поддерживаемый способ установки — Docker.
Примеры использования
# Сканировать самую свежую версию пакета '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). Песочница блокирует весь сетевой доступ и ограничивает операции с файловой системой только теми путями, которые необходимы для анализа. Это защищает от вредоносных пакетов, пытающихся выполнить код во время извлечения архива или сканирования.
По умолчанию песочница обязательна: если она недоступна на платформе, сканирование завершается ошибкой, а не выполняется без защиты. Чтобы сканировать без неё, необходимо явно передать --no-sandbox: