# 📦 @goodandready/dsh-shadow-auditor

<div align="center">

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

<p align="center">
  <a href="https://www.npmjs.com/package/@goodandready/dsh-shadow-auditor"><img src="https://img.shields.io/npm/v/@goodandready/dsh-shadow-auditor.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
</p>

<!-- Обязательная кнопка перехода на витрину всех проектов -->
<p align="center">
  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></a>
</p>

<p align="center">
  <a href="README.md"><b>🇬🇧 English</b></a> •
  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
</p>

<table align="center">
  <tr>
    <td align="center">
      ⭐ <strong>Если вам нравится этот плагин, поставьте ему звезду на GitHub</strong> — это покажет мне, что плагин вам полезен, и будет мотивировать меня развивать его дальше.
      <br><br>
      🐛 <strong>Если вы нашли баг или хотите предложить новый функционал</strong>, создайте issue на GitHub на любом языке — я рассмотрю ваше предложение и реализую полезные идеи в одной из следующих версий плагина.
    </td>
  </tr>
</table>

</div>

---

## ⚡ Обзор

**`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`, сброс баз данных, снос прав доступа);
* Требование явного подтверждения пользователя для рискованных сценариев.

### 3. 📋 Настраиваемые правила и панель Web UI (`lib/client.js`)
* Гибкое управление правилами безопасности;
* Индикатор статуса и журнал инцидентов безопасности в интерфейсе DSH.

---

## 🛠️ Инструменты агента (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  # Блокировать разрушительные команды в терминале
  enableAuditBadge: true        # Отображать бейдж безопасности в интерфейсе и диалогах подтверждения
  enableAuditLog: true          # Вести персистентный JSONL-журнал аудита с ротацией
  maxFileSizeMb: 50             # Сжимать в .gz логи больше 50 МБ
  retentionDays: 30             # Срок хранения сжатых логов аудита в днях
```

---

---

## 🔄 История релизов

### 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: <ruleId>`.

### 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`**: логирование событий в `<DSH_HOME>/shadow-auditor/<yyyy-mm>.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.