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/)
• CONTRIBUTING.md — структура репозитория, рабочий процесс разработки

Провайдер ИИ

При локальном запуске 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 для агентов кода внедряются за пределами песочницы и, следовательно, не могут быть скомпрометированы
• Для рабочих песочниц исходящий сетевой трафик ограничен хостами агентов кода (исходящий трафик разрешён во время процесса начальной загрузки, но это не запускает агента кода)

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