# 📦 @goodandready/dsh-shadow-auditor

Фоновый аудитор безопасности, сканер утечек ключей и защита от деструктивных команд для DeepSeek Harness

🇬🇧 English • 🇷🇺 Русский • 🇨🇳 中文说明

⭐ Если вам нравится этот плагин, поставьте ему звезду на GitHub — это покажет мне, что плагин вам полезен, и будет мотивировать меня развивать его дальше.

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

--- ## ⚡ Обзор **`dsh-shadow-auditor`** обеспечивает непрерывный фоновый аудит безопасности и защиту от выполнения опасных команд для агентов **DeepSeek Harness**. При написании кода, редактировании файлов или запуске терминальных команд автономными агентами существует риск случайной утечки API-ключей, токенов доступа или выполнения разрушительных скриптов (`rm -rf /`, форк-бомб, случайной перезаписи системных файлов). Плагин действует как внутрипроцессный фаервол безопасности, проверяя дифы кода на наличие секретов и блокируя деструктивные операции в терминале. ```mermaid graph LR subgraph AgentExecution [Действия агента DSH] Agent[🤖 Агент: Пишет код / Запускает команду] --> Intercept{Перехватчик безопасности} end subgraph SecurityEngines [Ядро dsh-shadow-auditor] Intercept --> SecretScan[🔑 Сканер секретов и токенов] Intercept --> CmdGuard[🛡️ Фаервол терминальных команд] end subgraph Enforcement [Контроль и журнал] SecretScan -->|Безопасно| Pass[✅ Разрешить выполнение] SecretScan -->|Обнаружен секрет| Block1[⛔ Блокировка и маскирование токена] CmdGuard -->|Безопасно| Pass CmdGuard -->|Опасная команда| Block2[⛔ Блокировка и запрос подтверждения] Block1 --> AuditLog[📋 Журнал аудита безопасности] Block2 --> AuditLog end style AgentExecution fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4 style SecurityEngines fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4 style Enforcement fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4 ``` --- ## ✨ Ключевые возможности ### 1. 🔑 Сканирование утечек ключей и паролей (`lib/guards/secrets.js`) * Сканирование дифов на API-ключи, приватные сертификаты, RSA/SSH ключи и токены баз данных; * Блокировка отправки конфиденциальных данных до фиксации в коммитах или передачи наружу; * Автоматическая замена секретов на `[REDACTED]` в журналах. ### 2. 🛡️ Защита от опасных команд (`lib/guards/command.js`) * Синтаксический анализ терминальных команд перед выполнением; * Перехват опасных паттернов (`rm -rf /`, деструктивный `dd`, сброс баз данных, снос прав доступа); * Защита границ воркспейса (#103): строгая блокировка рекурсивных удалений, направленных в корень (`/`, `~`, `.`) или за пределы сессионного каталога; * Защита системных префиксов (#105): безусловная защита критических путей (`~/.dsh`, `~/.claude`, `~/.ssh`, `/etc`, `/usr`, системные папки Windows); * Пропуск сухой проверки (#104): распознавание верификационных флагов (`-WhatIf`, `-Confirm`, `--dry-run`, `git clean -n`) без ложных срабатываний; * Требование явного подтверждения пользователя для рискованных сценариев. ### 3. 📋 Настраиваемые правила и панель Web UI (`lib/client.js`) * Гибкое управление правилами безопасности; * Индикатор статуса и журнал инцидентов безопасности в интерфейсе DSH. ### 4. 🪝 Многоуровневый перехват жизненного цикла (`lib/guards/lifecycle-hooks.js`) * **Приоритетная регистрация хуков (`prepend: true`)** (#125): Гарантирует выполнение во главе конвейера обработчиков Cordis до выполнения сторонних расширений; * **Безусловная блокировка критических угроз (`secretBlockCritical`)** (#124): Деструктивные команды высокой опасности (уничтожение корня, форматирование дисков, утечка AWS/приватных ключей) блокируются безусловно даже в режимах `audit_only` или `warning`; * **Интерактивный режим подтверждения (`ask`)** (#108): Интеграция с сервисом подтверждений DSH на этапе `tools/pre-execute` с возвратом `{ kind: 'ask', reason, displayReason }` при подозрительных операциях; * **Предфильтрация входящих промптов (`agent/pre-step`)** (#110): Сканирует сообщения пользователя до передачи в модель, мгновенно отклоняя попытки инъекций и джейлбрейков (`{ kind: 'reject' }`); * **Санитизация результатов инструментов (`tools/post-execute`)** (#111): Перехватывает вывод инструментов и маскирует найденные учетные данные и секреты до их попадания в контекст модели. --- ## 🛠️ Инструменты агента (3 инструмента) | Имя инструмента | Параметры | Описание | |---|---|---| | `shadow_auditor_scan_diff` | `diff: string` | Проверяет диф кода на наличие приватных ключей и токенов | | `shadow_auditor_check_command` | `command: string` | Оценивает терминальную команду на безопасность перед запуском | | `shadow_auditor_rules_list` | *(нет)* | Возвращает список активных правил безопасности и режимов | --- ## 📦 Быстрая установка ```bash dsh plugin --profile web add @goodandready/dsh-shadow-auditor ``` --- ## ⚙️ Пример конфигурации (`settings.yaml`) ```yaml dsh-shadow-auditor: strictSecretScanning: true # Блокировать выполнение при обнаружении ключей в коде blockDangerousCommands: true # Блокировать разрушительные команды в терминале secretBlockCritical: true # Безусловно блокировать критические угрозы в обход мягких режимов enableReversibleMasking: true # Обратимо заменять секреты и ПДн плейсхолдерами shellGuardMode: 'enforce' # Режим защиты команд: enforce (блокировка), audit_only (лог), ask (запрос пользователя) diffGateMode: 'warning' # Режим гейта диффов: disabled, warning или block enableAuditBadge: true # Отображать бейдж безопасности в интерфейсе и диалогах подтверждения enableAuditLog: true # Вести персистентный JSONL-журнал аудита с ротацией maxFileSizeMb: 50 # Сжимать в .gz логи больше 50 МБ retentionDays: 30 # Срок хранения сжатых логов аудита в днях ``` --- ### 🔒 Движок обратимого маскирования и подстановки плейсхолдеров При включённой опции `enableReversibleMasking` (по умолчанию: `true`) входящие пользовательские промпты проверяются на шаге `agent/pre-step`. Обнаруженные токены, API-ключи, приватные ключи, email-адреса, IPv4-адреса и телефоны обратимо заменяются монотонными плейсхолдерами (``, ``, ``). * **Повторное использование значений**: Повторяющиеся в пределах одной сессии значения сохраняют единый присвоенный плейсхолдер. * **Защита от коллизий префиксов**: Восстановление исходных значений строго сортируется по убыванию длины плейсхолдеров (`` перед ``), исключая повреждение подстрок. * **Сессионная команда восстановления**: Авторизованный пользователь может восстановить исходный текст локально в терминале: ```text /shadow-auditor restore ``` * **Инвариант чистоты логов сессии**: Промпты, отправляемые в LLM, и сохраняемые JSONL-журналы аудита не содержат сырых секретов. --- --- ## 🔄 История релизов ### v0.2.9 (Эволюция безопасности и каноническая локализация) - **Канонический языковой стандарт**: Полный переход кода и UI на английский (`en`) и китайский (`zh`); русская локализация ведётся через `goodandready/dsh-russian-lang`. - **Чистота дистрибутива**: Исключение нерелизных файлов (`AGENTS.md`, `index.md`) из репозитория; строгий контроль лимита $\le 256$ КБ на файл. - **Журнал перехватов в реальном времени**: Интерактивная лента событий аудита с фильтрами по типам угроз (All, Shell Guard, Diff Gate, High Risk). - **Пользовательские политики безопасности**: Настройка регулярных выражений для блокировки команд и масок чувствительных файлов, переключатель режимов Enforce / Audit-only. - **Инспектор Diff Gate и безопасные рекомендации**: Визуальный инспектор с подсветкой нарушений и готовыми подсказками безопасного исправления кода. - **Монитор целостности файлов и якорных секретов**: Защита от несанкционированного доступа к `.env`, `settings.yaml`, SSH-ключам и конфиденциальным файлам. - **Экспорт отчётов комплаенса**: Экспорт аудиторского следа в JSON или Markdown-ведомость в один клик из интерфейса. ### v0.2.8 (Унификация UI и синхронизация настроек) * **Единый стиль интерфейса (в стиле `dsh-clinebot`)**: Карточка настроек переработана на 4 структурированных карточки разделов с нативными дизайн-токенами DSH (`--dsw-alias-*`), адаптивной сеткой, бейджами статуса и выверенной типографикой. * **Полная синхронизация настроек**: В состояние формы добавлены и синхронизированы поля `diffGateMode`, `enableSastScan` и `enablePromptInjectionScan`. * **Усиление обработки ошибок**: Заменены немые catch-блоки на логирование через логгер плагина. * **Расширенное тестирование**: Добавлен отдельный набор тестов `test/ui-and-stability-028.test.mjs` (все 26 тестов успешно пройдены). ### v0.2.7 (Повышение стабильности и устранение ложных срабатываний) * **Устранение ложных срабатываний secret-write**: Имена файлов вроде `check_token.js` или `test_secret.py` больше не блокируются как запись секретов; защищаются исключительно реальные хранилища (`.env`, `.credentials`, ключи SSH/PEM). * **Фильтрация комментариев в SAST**: Комментарии, содержащие SQL-запросы или примеры `eval`, больше не вызывают ложных предупреждений. Разрешены безопасные пути через `import.meta.url` и `__dirname`. * **Ограничение ресурсов Diff Gate**: Строки длиннее 2048 символов обрезаются перед анализом для защиты от зависаний на минифицированных бандлах; тестовые файлы пропускают проверку на prompt injection. * **Безопасная команда /audit**: Команда в чате по умолчанию читает последние 50 записей (`readRecent`), предотвращая переполнение памяти на больших журналах (полный лог доступен через `--all`). * **Оптимизация опроса вкладки**: Фоновый опрос `AuditShieldChip` приостанавливается, если вкладка браузера скрыта (`document.hidden`). ### v0.2.6 (Шлюз безопасности кода Code-Security Diff Gate) * **Шлюз безопасности кода (`lib/diff-gate/`)**: Анализ диффов и изменений файлов на границе утверждения/применения агентом. * **Нормализованная схема находок**: Структурированные замечания со стабильными идентификаторами (`SEC-*`, `SAST-*`, `PI-*`), уровнями опасности, объяснением риска и рекомендациями (suggestion-only). * **Улучшенный детектор секретов**: Анализ энтропии Шеннона для высокоэнтропийных строк и расширенные паттерны ключей. * **Встроенный SAST-движок**: Детект SQL-инъекций, внедрения шелл-команд, path traversal, захардкоженных паролей и динамического выполнения кода (`eval`). * **Эвристический детект Prompt-Injection**: Выявление попыток обхода инструкций, джейлбрейков и утечки системного контекста в изменяемых файлах. * **Режимы шлюза (`disabled`, `warning`, `block`)**: Настройка через карточку параметров; режим `block` останавливает критические угрозы. * **Подавление ложных срабатываний**: Поддержка точечных комментариев `// shadow-audit-ignore: `. ### v0.2.5 (Комплексное обновление стабильности, памяти и UI-щита) * **Значок щита безопасности в шапке сессии (`conversation.session.header.utilities`)**: Нативный компонент `AuditShieldChip` со статусом в реальном времени. * **Защита от OOM в `AuditRecorder`**: Метод `readRecent(limit)` читает только свежие записи без распаковки сжатых архивов. * **Слэш-команда `--limit=N`**: По умолчанию команда `/audit` возвращает последние 50 записей. * **Устранение утечек памяти сессий**: Очистка кэшей ходов и событий по событиям уничтожения сессий с ограничением по LRU. * **Устранение ложных срабатываний команд**: Разрешены безопасные вызовы `grep -i kill`, `systemctl status`, `systemctl is-active`. * **Снижение когнитивной нагрузки на LLM**: Удален избыточный инструмент `shadow_auditor_rules_list`. ### v0.2.4 (Исправления авторских стандартов DSH и UI-карточки) * **Полнота параметров в карточке настроек Web UI**: добавлены переключатель записи журнала (`enableAuditLog`), лимит размера файла в МБ (`maxFileSizeMb`) и срок хранения архивов (`retentionDays`) с локализацией на русском и английском языках (#34). * **Устранение двойной регистрации слотов**: удалён отложенный таймер `setTimeout` с запасным переходом в `settings.section`; карточка регистрируется атомарно в целевой слот `settings.plugin.item` (#35). * **Блокировка формы при недоступности настроек**: если снимок настроек находится в статусе `unavailable`, поля ввода и кнопка сохранения отключаются (`disabled: true`), а пользователю выводится понятное предупреждение (#32). * **Очистка неиспользуемых зависимостей**: удалён неиспользуемый пакет `@deepseek-ai/dsh-credentials` из `peerDependencies` в `package.json` (#33). * **Изоляция стилей**: к тегу стилей карточки добавлен атрибут `data-dsh-plugin="dsh-shadow-auditor"` для защиты от очистки стилей соседними плагинами. * **Дизайн-контракт**: добавлен документ `docs/design/DESIGN.md`, фиксирующий спецификацию поверхностей и состояний плагина. ### v0.2.3 (Исправление ложных срабатываний детекта эксфильтрации) * **Устранение ложных блокировок легитимных API-запросов**: разрешено чтение и извлечение ключей из конфигураций (например, `K=$(grep KEY ~/.dsh/.credentials.yaml) && curl ... -H "Authorization: Bearer $K"`). * **Точечный анализ сетевой эксфильтрации**: блокировка срабатывает строго при попытке передачи файлов секретов как полезной нагрузки (`-d @.env`, `-F file=@...`, `--post-file=...`), прямого конвейера (`cat .env | curl/nc`) или перенаправления ввода (`< .env`), а также при удалённой передаче через `scp/rsync`. ### v0.2.0 (Комплексный аудит, скоринг риска и защита от эксфильтрации) * **Слэш-команда `/audit` в чате DSH**: вывод подробной операционной ведомости (Operation Bill) прямо в переписку — счётчик вызовов инструментов, сводка рисков (баллы 0–100), таблица подозрительных операций и список перехваченных действий. Флаги: `--turn` (последний ход), `--all` (вся история), `--json` (для скриптов), `--since=YYYY-MM-DD`, `--limit=N` (по умолчанию 50). * **Долговременное хранилище `AuditRecorder`**: логирование событий в `/shadow-auditor/.jsonl` через сериализующую очередь Promise (защита от гонок при параллельных задачах), автосжатие в `.gz` при превышении 50 МБ и ротация архивов старше 30 дней. * **Глубокие хуки телеметрии ядра DSH**: глобальный перехват `tools/result` для фиксации реального исхода выполнения инструментов (`result.isError`), сохранение санитизированных сообщений об ошибках и границ ходов через `session/event` (`turn/end`). * **Защита от сетевой эксфильтрации секретов**: блокировка сетевых утилит (`curl`, `wget`, `scp`, `ssh`, `nc`, `socat` и др.), если аргументы содержат обращение к файлам ключей (`.env`, `id_rsa`, `.git-credentials` и др.). * **Защита от шелл-редиректов вне проекта**: блокировка перенаправлений `>` и `>>` в системные каталоги (`/etc/`, `~/.bashrc`, `%USERPROFILE%`, cron). * **Умный `git push --force`**: блокировка `--force` исключительно для защищённых веток (`main`, `master`, `prod`) и remotes; сохранена свобода перебазирования локальных фиче-веток. * **Детерминированный скоринг рисков (0–100)**: автоматическое присвоение баллов и тегов риска без привлечения LLM, скользящее 10-минутное окно накопления штрафов за аномальную частоту вызовов. * **Рекурсивная санитизация данных до сходимости**: модуль `redactText` / `redactValue` очищает глубокие структуры от токенов, паролей и значений `.env` до неподвижной точки. ### v0.1.4 (Hotfix регистрации слота настроек) * **Асинхронная регистрация слота (`settings.plugin.item`)**: регистрация карточки настроек переведена на `ctx.slots.inject`, что предотвращает ошибку загрузчика ядра при обращении к ещё не объявленному слоту (`slot is not declared`). * **Запасной раздел (`settings.section`)**: добавлен автоматический fallback на персональный раздел настроек с таймером и очисткой через `ctx.effect`, если в текущей сборке DSH отсутствует слот карточек плагинов. ### v0.1.3 (Hotfix безопасности и стабильности) * **Усиленный разбор цепочек команд (`findDangerous`)**: анализ составных терминальных выражений (`&&`, `||`, `;`, перенос строк) предотвращает обход фаервола разрешёнными подкомандами (`systemctl status && rm -rf /`). * **Точное исключение секретов (`scanSecrets`)**: устранена ложная фильтрация боевых токенов и ключей, содержащих подстроку "example". * **Автоматическое маскирование токенов (`maskSecret`)**: перехваченные секреты маскируются (`sk-pr...****...1234`) перед передачей в HTTP API и отображением в Web UI. * **Неограниченное сканирование файлов**: снято ограничение на размер проверяемого файла (ранее первые 8 КБ), файлы любого размера проверяются полностью. * **Корректный жизненный цикл Cordis**: регистрация инструментов изолирована в `ctx.effect` с автоматической очисткой при перезагрузке; исправлен контекст события `approval/asked`. * **Оптимизация Web UI**: удалён паразитный сброс формы по таймеру, опрос статуса аудита выполняется только при раскрытой карточке, предотвращены утечки памяти. * **Кэширование API**: добавлен HTTP-заголовок `Cache-Control: no-store` для роута `/dsh-shadow-auditor/audit`. --- ## 📄 Лицензия MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY) ## Изменения в v0.2.11 - Стандартизация описаний находок на английском и китайском языках, 0 кириллицы в коде (#47) - Модуль one-click обновления из карточки настроек DSH (#48) - Защита HTTP-маршрутов аудита с ограничением метода GET и проверкой источника (#49) - Исключение внутренних планов из git-индекса и релизного tarball (#50) - Очистка рабочего дерева от устаревших .tgz архивов (#51) - Полный переход стилей на нативные CSS-токены темы DSH без hex и rgba (#52) - Объявление состава клиентских зависимостей в dsh.client.inject (#53) - Метрики и логирование ошибок записи аудита и нечитаемых строк (#54) - Регистрация словарей локалей внутри ctx.effect с корректной отпиской (#55) ## Изменения в v0.2.10 Выпуск устраняет два ложных срабатывания защиты команд, сохраняет запрет на рекурсивное удаление и запись в защищённые файлы, а также добавляет безопасную отладочную диагностику best-effort-сбоев. Защитный фильтр разрешает rm -f, если нет рекурсивного флага. rm -r, rm -rf и раздельно указанные рекурсивные флаги остаются заблокированными. Записи в защищённые файлы проверяются отдельно для каждой shell-команды и этапа конвейера, поэтому перенаправление stderr в одной команде не влияет на последующее чтение. grep, cat и sed без режима изменения на месте могут читать settings.yaml; запись через перенаправление, tee или sed -i остаётся заблокированной. Анализатор учитывает разделители внутри кавычек и экранирование. Эти изменения не затрагивают правила сети, SQL, управления службами, защищённых операций Git, записи на устройства и выхода из рабочей области. Проверка команд ограничена и не является полным Bash AST.