deepsec

deepsec — это сканер уязвимостей на основе агентов, который вы можете запускать в своей собственной инфраструктуре, оптимизированный для выполнения проверки по запросу всего кода в существующих крупномасштабных репозиториях.

deepsec предназначен для выявления труднонаходимых проблем, которые долгое время скрывались в приложениях. Он настроен на использование лучших моделей на максимальных уровнях мышления (настраивается с помощью --thinking-level, см. docs/models.md), что означает, что сканирование может стоить тысячи или даже десятки тысяч долларов для больших кодовых баз. Наши клиенты сочли эту стоимость оправданной из-за скорости, с которой им удалось исправить уязвимости, которые в противном случае остались бы неисправленными.

Для больших кодовых баз работа параллельно распределяется по рабочим машинам. Если выполнение прерывается или завершается с ошибкой на полпути, просто повторно запустите ту же команду — deepsec продолжит с того места, где остановился, пропуская уже проанализированные файлы и исследуя только остальные.

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

Перейдите в корень репозитория, который вы хотите сканировать, затем:

npx deepsec init       # создает .deepsec/ с этим репозиторием в качестве первого проекта
cd .deepsec
pnpm install           # устанавливает deepsec из npm

# Действуйте согласно выводу команды `init`

Теперь попросите вашего агента кода выполнить начальную настройку. Откройте агента по вашему выбору и дайте команду:

Прочитайте .deepsec/node_modules/deepsec/SKILL.md, чтобы понять назначение инструмента. Затем прочитайте .deepsec/data/<id>/SETUP.md и следуйте ему: бегло просмотрите README этого репозитория, любые файлы AGENTS.md/CLAUDE.md и несколько показательных файлов кода, затем замените каждый раздел .deepsec/data/<id>/INFO.md.

Держите ответ КРАТКИМ — цель 50–100 строк в сумме. Выберите 3–5 примеров на раздел, без исчерпывающего перечисления. Называйте примитивы (хелперы аутентификации, промежуточное ПО), но без номеров строк. Пропускайте общие категории CWE — встроенные сопоставители покрывают их. Освещайте только то, что специфично для проекта. INFO.md внедряется в каждый пакет сканирования; избыточный контекст размывает сигнал.

Затем запустите сканирование из папки .deepsec/:

pnpm deepsec scan
pnpm deepsec process    
pnpm deepsec revalidate # опционально, снижает уровень ложных срабатываний
pnpm deepsec export --format md-dir --out ./findings

Если вы считаете, что deepsec должен проанализировать больше частей кода, передайте ему документацию по написанию сопоставителей, чтобы найти более ценные отправные точки в вашей кодовой базе.

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

• docs/getting-started.md — пошаговое руководство по первому сканированию
• docs/reviewing-changes.md — process --diff для проверки PR и CI-шлюзов
• docs/supported-tech.md — фреймворки и экосистемы, которые deepsec распознаёт из коробки
• docs/writing-matchers.md — попросите вашего агента кода расширить ваш набор сопоставителей
• docs/configuration.md — справка по deepsec.config.ts
• docs/plugins.md — создание плагинов
• docs/models.md — выбор модели, настройки по умолчанию, отказы, будущие модели
• docs/vercel-setup.md — ключи/токены AI Gateway + Vercel Sandbox
• docs/architecture.md — внутреннее устройство конвейера
• docs/data-layout.md — схемы data/ (FileRecord, RunMeta, …)
• docs/faq.md — стоимость, выбор модели, режим песочницы, частота ложных срабатываний
• samples/ — отправные точки для копирования (на данный момент: webapp/)

Провайдер ИИ

При локальном запуске deepsec использует вашу существующую подписку claude/codex, если вы вошли в систему на этом компьютере. Подписки (Claude Pro/Max, ChatGPT Plus) полезны для оценки deepsec, но обычно не имеют достаточного запаса для полного сканирования репозитория.

Для реальных сканирований используйте Vercel AI Gateway. Один ключ покрывает как Claude, так и Codex, а квоты шлюза по умолчанию рассчитаны на высокопараллельные исследования.

AI_GATEWAY_API_KEY=vck_...

См. docs/vercel-setup.md для получения ключа и настройки Vercel Sandbox. Чтобы обойти шлюз, явно укажите ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL (или пару OpenAI). Явные значения всегда имеют приоритет над развёртыванием AI_GATEWAY_API_KEY.

Если выполнение process или revalidate останавливается из-за того, что у вышестоящего учётного данного закончилась квота или кредиты, deepsec корректно завершает работу и сообщает, где пополнить баланс. После этого повторно запустите ту же команду — и она продолжит с того места, где остановилась.

Распределённое выполнение (опционально)

Крупные монорепозитории могут распределять работу по микроВМ Vercel Sandbox:

pnpm deepsec sandbox process --project-id my-app --sandboxes 10 --concurrency 4

Требуется учётная запись Vercel. Локальное рабочее дерево архивируется и загружается; .git исключается. Поддерживаются как токены OIDC (локальные), так и токены доступа (CI) — см. docs/vercel-setup.md.

Модель безопасности самого deepsec

Относитесь к deepsec как к агенту кода с полным доступом к оболочке в среде, где он выполняется. Он предназначен для работы с доверенными входными данными (вашим исходным кодом), но вы всё же можете беспокоиться об инъекциях подсказок из-за внешних зависимостей или поставляемого кода.

Запуск в песочнице (см. выше) существенно ограничивает потенциальную угрозу:

• Ключи API для агентов кода внедряются за пределами песочницы и, следовательно, не могут быть скомпрометированы
• Для рабочих песочниц исходящий сетевой трафик ограничен хостами агентов кода (исходящий трафик разрешён во время процесса начальной загрузки, но это не запускает агента кода)

Справочник по командам

Лицензия

Apache 2.0. См. LICENSE и NOTICE.