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 использует риск-ориентированную модель обнаружения, которая сопоставляет возможности кода с индикаторами угроз:

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

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

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

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

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

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

Метки оценок:

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

# По умолчанию: требуется песочница, при её отсутствии выводится ошибка и выход
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, либо как папку/префикс, либо как отдельный объект архива:

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.

Руководство по написанию новых правил см. в WRITING_RULES.md.

Запуск GuardDog в GitHub Action

Самый простой способ интегрировать GuardDog в ваш CI-конвейер — использовать формат вывода SARIF и загружать его в функцию code scanning GitHub.

Благодаря этому вы получаете:

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

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

Разработка

Запуск локальной версии 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 (тесты находятся здесь).

Бенчмаркинг

Вы можете запускать GuardDog на легитимных и вредоносных пакетах, чтобы определить ложные срабатывания и пропуски. См. ./tests/samples

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

Запустите проверку типов с помощью

mypy --install-types --non-interactive guarddog

и линтер с помощью

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 реализует несколько проверок безопасности при извлечении архивов пакетов для защиты от бомб сжатия и атак с исчерпанием файловых дескрипторов:

Мейнтейнеры

• Sebastian Obregoso
• Ian Kretz
• Tesnim Hamdouni

Авторы

• Ellen Wang
• Christophe Tafani-Dereeper

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

Вдохновение:

• Backstabber’s Knife Collection: A Review of Open Source Software Supply Chain Attacks
• What are Weak Links in the npm Supply Chain?
• A Survey on Common Threats in npm and PyPi Registries
• A Benchmark Comparison of Python Malware Detection Approaches
• Towards Measuring Supply Chain Attacks on Package Managers for Interpreted Languages