Введение

OWASP dep-scan — это инструмент аудита безопасности и рисков нового поколения, основанный на известных уязвимостях, рекомендациях и ограничениях лицензий для зависимостей проекта. Поддерживаются как локальные репозитории, так и образы контейнеров в качестве входных данных, и инструмент идеально подходит для интеграции с платформами ASPM/VM и в средах CI.

Возможности

Сканирование большинства кода приложений (локальные репозитории, образы Linux-контейнеров, манифесты Kubernetes и ОС) для выявления известных CVE с приоритизацией
Выполнение расширенного анализа достижимости для нескольких языков (см. матрицу достижимости ниже)
Сканирование уязвимостей пакетов выполняется локально и довольно быстро. Сервер не используется
Генерация Software Bill-of-Materials (SBOM) с информацией о отчете о раскрытии уязвимостей (VDR)
Генерация документа VEX Common Security Advisory Framework (CSAF) 2.0/2.1 (см. CSAF Readme)
Выполнение глубокого аудита рисков пакетов для атак путаницы зависимостей и рисков обслуживания (см. документацию по аудиту рисков)

Точные достижимые потоки данных

Детальные потоки данных для идентификации как достижимых, так и недостижимых путей в вашем приложении на основе полного контекста.

Достижимые потоки

Матрица достижимости

dep-scan вычисляет достижимость для семи языковых экосистем через четыре срезчика. Уязвимый пакет, чей код фактически находится на исполняемом пути, помечается как Достижимый, в то время как пакет, который лишь объявлен в BOM, но никогда не вызывается, не помечается. Каждый срезчик передает данные в один и тот же общий движок достижимости, индексированный по purl, поэтому поведение единообразно для всех языков. Достижимость включена по умолчанию (--reachability-analyzer FrameworkReachability); SemanticReachability дополнительно атрибутирует достигнутые сервисы, конечные точки и послесборочную (бинарную/контейнерную) достижимость.

Для понимания концепций достижимости и приоритизации прочитайте главы модель достижимости и приоритизация. Для примеров по языкам см. Руководства по языкам. Для информации о соответствии (VDR и CSAF VEX) см. руководство по VDR и руководство по CSAF VEX.

Достижимость включена по умолчанию при использовании --profile research, который dep-scan использует, когда достижимость активна. Приведенных ниже команд достаточно для начала; руководства по языкам охватывают разрешение бинарных зависимостей, безопасность бэкенда и сети, требования к восстановлению и готовые примеры на фикстурах в репозитории.

Rust (rusi). cdxgen запускает rusi и сохраняет его отчет, который dep-scan преобразует в общий конвейер, поэтому крейт, который фактически вызывается (например, time::now() для RUSTSEC-2020-0071), помечается как Достижимый, а тот, который просто присутствует, — нет. См. руководство по достижимости Rust.```bash depscan -i ./my-rust-app -o ./reports --profile research

**Go (golem).** dep-scan вызывает [golem](https://github.com/cdxgen/cdxgen-plugins-bin) напрямую для проектов на Go (требуется `go` в `PATH`), помечая модуль как Reachable, когда его функции находятся на отслеживаемом пути. Используйте `--go-analyzer-network offline` для ненадёжных репозиториев с тёплым кэшем модулей. Смотрите [руководство по достижимости Go](https://depscan.readthedocs.io/languages/go-reachability).```bash
depscan -i ./my-go-app -o ./reports -t go

.NET (dosai). cdxgen запускает dosai, который выдает явное заключение о достижимости для каждого пакета (PackageReachability с ReachabilityKind и Confidence), которое dep-scan считает авторитетным, поэтому пакет NuGet, фактически вызываемый (например, JsonConvert.DeserializeObject на контролируемом входе), считается Reachable. Сканируйте восстановленное дерево для поиска версионных purl. См. руководство по достижимости .NET.```bash depscan -i ./my-dotnet-app -o ./reports -t dotnet

**JVM, JavaScript/TypeScript, Python и PHP (atom).** Эти четыре экосистемы используют [atom](https://github.com/AppThreat/atom) слайсер, который строит языконезависимое промежуточное представление и выполняет статическое срезание. Смотрите [руководство по достижимости JVM, JS, Python и PHP](https://depscan.readthedocs.io/languages/jvm-js-python-php-reachability).```bash
depscan --profile research -t java -i ./my-java-app -o ./reports --explain

Чтобы выйти за рамки анализа достижимости на уровне фреймворков к конечным точкам, сервисам и этапам после сборки, используйте --reachability-analyzer SemanticReachability с --bom-dir, указывающим на BOM жизненного цикла. См. руководство по семантической достижимости.

Понятные сведения о CVE

Понимайте CVE без необходимости читать описание целиком.

Dependency Tree with Insights

Автоматическая приоритизация

Сосредоточьтесь только на тех CVE, которые требуют вашего внимания.

Prioritization

Будьте проактивны

Всегда будьте на шаг впереди благодаря продвинутому прогнозированию уязвимостей и эксплойтов.

Proactive Measures

Источники данных об уязвимостях

OSV
NVD
GitHub
NPM
Linux vuln-list

Дистрибутивы Linux

AlmaLinux
Debian
Alpine
Amazon Linux
Arch Linux
RHEL/CentOS
Rocky Linux
Ubuntu
OpenSUSE/SLES
Photon
Chainguard
Wolfi OS

Быстрый старт

dep-scan идеально подходит для использования в непрерывной интеграции (CI) и в качестве инструмента локальной разработки.

Сканирование проектов локально (Python-версия)```bash

sudo npm install -g @cyclonedx/cdxgen

Normal version recommended for most users (MIT)

pip install owasp-depscan

For a full version with all extensions and server mode (Multiple Licenses)

pip install owasp-depscan[all]

Это установит две команды с именами `cdxgen` и `depscan`.

Вы можете напрямую вызвать команду сканирования с различными опциями.```bash
cd <project to scan>
depscan --src $PWD --reports-dir $PWD/reports

Полный список опций приведен ниже:```text usage: depscan [-h] [--config CONFIG] [--no-banner] [-i SRC_DIR_IMAGE] [-o REPORTS_DIR] [--csaf] [--profile {appsec,research,operational,threat-modeling,license-compliance,generic,machine-learning,ml,deep-learning,ml-deep,ml-tiny}] [--lifecycle {pre-build,build,post-build} [{pre-build,build,post-build} ...]] [--technique {auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} [{auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} ...]] [--bom-engine {auto,CdxgenGenerator,CdxgenServerGenerator,CdxgenImageBasedGenerator,BlintGenerator} | --vulnerability-analyzer {auto,VDRAnalyzer,LifecycleAnalyzer}] [--reachability-analyzer {off,FrameworkReachability,SemanticReachability}] [--no-suggest] [--risk-audit] [--cdxgen-args CDXGEN_ARGS] [--private-ns PRIVATE_NS] [-t PROJECT_TYPE [PROJECT_TYPE ...]] [--bom BOM | --bom-dir BOM_DIR | --purl SEARCH_PURL] [--report-template REPORT_TEMPLATE] [--report-name REPORT_NAME] [--deep] [--fuzzy-search] [--search-order {purl,pcu,cpe,cpu,url}] [--no-universal] [--no-vuln-table] [--server] [--server-host SERVER_HOST] [--server-port SERVER_PORT] [--cdxgen-server CDXGEN_SERVER] [--debug] [-q | --explain] [-v]

Fully open-source security and license audit for application dependencies and container images based on known vulnerabilities and advisories.

options: -h, --help show this help message and exit --config CONFIG Path to the configuration file. Default: $PWD/.config/depscan.toml --no-banner Do not display the logo and donation banner. Please make a donation to OWASP before using this argument. -i, --src SRC_DIR_IMAGE Source directory or container image or binary file -o, --reports-dir REPORTS_DIR Reports directory --csaf Generate a OASIS CSAF VEX document --profile {appsec,research,operational,threat-modeling,license-compliance,generic,machine-learning,ml,deep-learning,ml-deep,ml-tiny} Profile to use while generating the BOM. For granular control, use the arguments --bom-engine, --vulnerability-analyzer, or --reachability-analyzer. --lifecycle {pre-build,build,post-build} [{pre-build,build,post-build} ...] Product lifecycle for the generated BOM. Multiple values allowed. --technique {auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} [{auto,source-code-analysis,binary-analysis,manifest-analysis,hash-comparison,instrumentation,filename} ...] Analysis technique to use for BOM generation. Multiple values allowed. --bom-engine {auto,CdxgenGenerator,CdxgenServerGenerator,CdxgenImageBasedGenerator,BlintGenerator} BOM generation engine to use. Defaults to automatic selection based on project type and lifecycle. --vulnerability-analyzer {auto,VDRAnalyzer,LifecycleAnalyzer} Vulnerability analyzer to use. Defaults to automatic selection based on bom_dir argument. --reachability-analyzer {off,FrameworkReachability,SemanticReachability} Reachability analyzer to use. Default FrameworkReachability. --no-suggest Disable suggest mode --risk-audit Perform package risk audit (slow operation). Npm only. --cdxgen-args CDXGEN_ARGS Additional arguments to pass to cdxgen --private-ns PRIVATE_NS Private namespace to use while performing oss risk audit. Private packages should not be available in public registries by default. Comma separated values accepted. -t, --type PROJECT_TYPE [PROJECT_TYPE ...] Override project types if auto-detection is incorrect. Multiple values supported. --bom BOM Examine using the given Software Bill-of-Materials (SBOM) file in CycloneDX format. Use cdxgen command to produce one. --bom-dir BOM_DIR Examine all the Bill-of-Materials (BOM) files in the given directory. --purl SEARCH_PURL Scan a single package url. --custom-data CUSTOM_DATA Path to directory containing custom vulnerability data (JSON/YAML/TOML) to override/augment results. --report-template REPORT_TEMPLATE Jinja template file used for rendering a custom report --report-name REPORT_NAME Filename of the custom report written to the --reports-dir --deep Perform deep scan by passing this --deep argument to cdxgen. Useful while scanning docker images and OS packages. --fuzzy-search Perform fuzzy search by creating variations of package names. Use this when the input SBOM lacks a PURL. --search-order {purl,pcu,cpe,cpu,url} Attributes to use while searching for vulnerabilities. Default: PURL, CPE, URL (pcu). --no-universal Depscan would attempt to perform a single universal scan instead of individual scans per language type. --no-vuln-table Do not print the table with the full list of vulnerabilities. This can help reduce console output. --server Run depscan as a server --server-host SERVER_HOST depscan server host --server-port SERVER_PORT depscan server port --server-allowed-hosts [SERVER_ALLOWED_HOSTS ...] List of allowed hostnames or IPs that can access the server (e.g., 'localhost 192.168.1.10'). If unspecified, no host allowlist is enforced. --server-allowed-paths [SERVER_ALLOWED_PATHS ...] List of allowed filesystem paths that can be scanned by the server. Restricts parameter in /scan requests. --cdxgen-server CDXGEN_SERVER cdxgen server url. Eg: --debug Run depscan in debug mode. -q, --quiet Makes depscan quiet. --explain Makes depscan to explain the various analysis. Useful for creating detailed reports. --explanation-mode {Endpoints,EndpointsAndReachables,NonReachables,LLMPrompts} Style of explanation needed. Defaults to Endpoints and Reachables. --annotate Include the generated text VDR report as an annotation. Defaults to true when explain is enabled; false otherwise. -v, --version Display the version

### Автономные бинарные файлы (Python или Node.js не требуются)

Предварительно собранные однофайловые исполняемые файлы прикреплены к каждому [релизу GitHub](https://github.com/owasp-dep-scan/dep-scan/releases). Они содержат соответствующий [cdxgen](https://github.com/cdxgen/cdxgen) SEA бинарный файл, поэтому создание BOM работает "из коробки" без установки Python, Node.js или cdxgen.

| Платформа              | Архитектура   | Артефакт                     |
| ---------------------- | ------------- | ---------------------------- |
| Linux (glibc)          | x86_64        | `depscan-linux-amd64`        |
| Linux (glibc)          | arm64         | `depscan-linux-arm64`        |
| Linux (musl / Alpine)  | x86_64        | `depscan-linux-amd64-musl`   |
| Linux (musl / Alpine)  | arm64         | `depscan-linux-arm64-musl`   |
| macOS                  | Apple silicon | `depscan-darwin-arm64`       |
| macOS                  | Intel         | `depscan-darwin-amd64`       |
| Windows                | x86_64        | `depscan-windows-amd64.exe` |

У каждого артефакта есть соответствующий файл `.sha256` для проверки.```bash
# Example: Linux x86_64
curl -LO https://github.com/owasp-dep-scan/dep-scan/releases/latest/download/depscan-linux-amd64
curl -LO https://github.com/owasp-dep-scan/dep-scan/releases/latest/download/depscan-linux-amd64.sha256
sha256sum -c depscan-linux-amd64.sha256
chmod +x depscan-linux-amd64
./depscan-linux-amd64 --src $PWD --reports-dir $PWD/reports

[!NOTE] macOS-бинарные файлы в настоящее время не подписаны. При первом запуске macOS Gatekeeper может заблокировать их; снимите атрибут карантина с помощью xattr -d com.apple.quarantine ./depscan-darwin-arm64 (или разрешите выполнение бинарного файла в Системных настройках, Конфиденциальность и безопасность).

[!NOTE] База данных уязвимостей по-прежнему загружается при первом запуске. В комплект входит только cdxgen, а не сама база уязвимостей. Используйте команду depscan-vdb, чтобы выбрать конкретный вариант базы данных, например depscan-vdb download --scope app для меньшей базы, содержащей только приложения. Полная матрица образов доступна в руководстве по базам данных уязвимостей.

Все автономные бинарные файлы содержат blint, но не его опциональный бэкенд дизассемблирования nyxstone (для него нет колес и отсутствует поддержка Windows). Таким образом, глубокий анализ бинарных файлов на основе дизассемблирования недоступен в автономных бинарных файлах; используйте пакет Python (pip install owasp-depscan[all]), если он вам необходим.

Сканирование контейнеров локально (версия на Python)

Просканируйте проект на Java.```bash depscan --src -o containertests -t java

Сканируйте тег `latest` контейнера `shiftleft/scan-slim````bash
depscan --src shiftleft/scan-slim -o containertests -t docker

Включите license в тип для выполнения аудита лицензий.```bash depscan --src shiftleft/scan-slim -o containertests -t docker license

Вы также можете указать образ, используя дайджест sha256```bash
depscan --src redmine@sha256:a5c5f8a64a0d9a436a0a6941bc3fb156be0c89996add834fe33b66ebeed2439e -o containertests -t docker

Вы также можете сохранить образы контейнеров с помощью команды docker или podman save и передать архив в depscan для сканирования.```bash docker save -o /tmp/scanslim.tar shiftleft/scan-slim:latest

podman save --format oci-archive -o /tmp/scanslim.tar shiftleft/scan-slim:latest

depscan --src /tmp/scanslim.tar -o reports -t docker

Дополнительные примеры см. в тестах Docker в рабочем процессе GitHub Actions для этого репозитория.

### Сканирование проектов локально (контейнер Docker)

Образ контейнера `ghcr.io/owasp-dep-scan/dep-scan` можно использовать для выполнения сканирования.

Для сканирования с настройками по умолчанию```bash
docker run --rm -v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports

Сканировать с конфигурацией на основе пользовательских переменных окружения```bash docker run --rm
-e VDB_HOME=/db
-e GITHUB_TOKEN=
-v /tmp:/db
-v $PWD:/app ghcr.io/owasp-dep-scan/dep-scan depscan --src /app --reports-dir /app/reports

В приведённом выше примере `/tmp` монтируется как `/db` в контейнер. Этот каталог затем указывается как `VDB_HOME` для кэширования информации об уязвимостях. Таким образом, база данных может быть кэширована и повторно использована для повышения производительности.

### Серверный режим

dep-scan и cdxgen могут быть запущены в серверном режиме. Используйте прилагаемый файл docker-compose для начала работы.```bash
git clone https://github.com/owasp-dep-scan/dep-scan
docker compose up

В комплекте с файлом compose устанавливается DEPSCAN_SERVER_API_KEY по умолчанию в качестве placeholder для разработки, чтобы служба dep-scan могла привязаться к 0.0.0.0. Переопределите это значение перед тем, как предоставлять службу за пределами локальной лаборатории.```bash depscan --server --server-host 127.0.0.1 --server-port 7070

Если вам нужно привязать dep-scan к нелокальному адресу, сначала установите API key:```bash
export DEPSCAN_SERVER_API_KEY="change-this-before-production"
depscan --server --server-host 0.0.0.0 --server-port 7070

[!IMPORTANT] dep-scan отказывается привязываться к нелокальному адресу без DEPSCAN_SERVER_API_KEY или явного согласия через DEPSCAN_SERVER_ALLOW_UNAUTHENTICATED_BIND=true.

Используйте конечную точку /scan для выполнения сканирований.

[!NOTE] Параметр type обязателен в серверном режиме. Если включена аутентификация по API-ключу, отправляйте ключ с помощью X-API-Key или Authorization: Bearer <key>.

Сканирование локальной директории. Сканирование SBOM-файла (находящегося локально).```bash curl
-H 'X-API-Key: dev-only-change-me'
--json '{"path": "/tmp/vulnerable-aws-koa-app/sbom_file.json", "type": "js"}'
http://127.0.0.1:7070/scan

- Сканирование репозитория GitHub.```bash
curl \
  -H 'Authorization: Bearer dev-only-change-me' \
  --json '{"url": "https://github.com/HooliCorp/vulnerable-aws-koa-app", "type": "js"}' \
  http://127.0.0.1:7070/scan \
  -o app.vdr.json

Загрузка файла SBOM и генерация результатов на его основе.```bash curl -X POST
-H 'X-API-Key: dev-only-change-me'
-H 'Content-Type: multipart/form-data'
-F 'file=@/tmp/app/sbom_file.json'
http://127.0.0.1:7070/scan?type=js

## Локальная разработка

Настройте uv, следуя официальной [документации](https://docs.astral.sh/uv/).```shell
uv sync --all-extras --all-packages
uv run depscan --help
uv run pytest

Локальная настройка VDB```shell

vdb --clean vdb --download-image

To scan containers and OS images

vdb --download-full-image

### Сканировать локальные зависимости depscan```shell
uv run depscan --config .config/depscan-dev.toml

Это автоматически использует конфигурацию, указанную в локальном конфигурационном файле.

Документация

Полная документация находится на depscan.readthedocs.io. Ключевые страницы:

Поддерживаемые языки и матрица достижимости
Анализ достижимости (центр)
- Модель достижимости
- Как dep-scan расставляет приоритеты
- SBOM и доказательства
- Языковые руководства: Rust, Go, .NET, JVM/JS/Python/PHP
- Анализаторы: Достижимость фреймворков, Семантическая достижимость
Вывод и соответствие: Руководство по VDR, Руководство по CSAF VEX
Настройка через переменные окружения
Расширенное использование: GitHub Security Advisory, Режим предложений, Аудит рисков пакетов, Сканирование живой ОС, Сканирование лицензий, Пользовательские отчёты

Лицензия

Лицензия MIT

Этот проект был передан Фонду OWASP в августе 2023 года компанией AppThreat Ltd.

Финансирование

Этот проект финансируется через NGI Zero Core, фонд, учреждённый NLnet при финансовой поддержке программы Next Generation Internet Европейской комиссии. Узнайте больше на странице проекта NLnet.

Java / JVM (Groovy, Kotlin, Scala)	atom	`FrameworkReachability`
JavaScript / TypeScript	atom	`FrameworkReachability`
Python	atom	`FrameworkReachability`
PHP	atom	`FrameworkReachability`
Rust	rusi	`FrameworkReachability`
Go	golem	`FrameworkReachability`
.NET (C#, VB, F#, R)	dosai	`FrameworkReachability`

dep-scan

Популярное