# mcp-sentinel: Шлюз допустимости действий и Circuit Breaker для ИИ-агентов

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
[![Protocol: MCP](https://img.shields.io/badge/Protocol-Model_Context_Protocol-purple.svg)](https://modelcontextprotocol.io)
[![ФСТЭК: Приказ №117](https://img.shields.io/badge/ФСТЭК-Приказ_№117-green.svg)](https://fstec.ru)
[![Zero-Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)]()
[![Tests: Passing](https://img.shields.io/badge/tests-100%25_passed-success.svg)]()

> **Детерминированный шлюз безопасности и In-line Circuit Breaker для защиты инфраструктуры КИИ от деструктивных вызовов инструментов и Prompt Injection**  
> *Разработка: АНО «НИИ системного синтеза» (Лаборатория системного синтеза / ISS Lab)*  
> *Официальный сайт*: [https://isslab.ru](https://isslab.ru) · *Страница кибербезопасности*: [https://isslab.ru/cyber/](https://isslab.ru/cyber/)  
> *Репозиторий (GitVerse)*: [https://git.isslab.ru/isslab/mcp-sentinel](https://git.isslab.ru/isslab/mcp-sentinel)

---

## 🎯 Назначение

`mcp-sentinel` — это детерминированный шлюз безопасности (In-line Circuit Breaker) для любых ИИ-агентов и рабочих сред (Claude Code, Cursor, Gemini IDE, корпоративные боты), работающих по открытому протоколу **Model Context Protocol (MCP)**.

Шлюз встраивается прозрачно между агентом и инструментами (MCP-серверами), проверяет каждый вызов инструмента **до передачи управления в операционную систему или СУБД**, блокирует недопустимые действия менее чем за 2 миллисекунды и автоматически фиксирует доказательную базу в криптографическом журнале по стандарту **ГОСТ Р 34.11-2012 («Стрибог-256»)**.

---

## 🛡️ Контракты допустимости (Security Contracts)

1. **FS-Jail (`contracts/fs_jail.py`)**:
   - Блокировка выхода за пределы доверенной директории (Path Traversal, `..`).
   - Категорический запрет доступа к чувствительным файлам: `.env`, `.git/config`, закрытые ключи `id_rsa`, `/etc/shadow`, `/etc/passwd`, SAM/SYSTEM.
2. **SQL-Guard (`contracts/sql_guard.py`)**:
   - Запрет деструктивных DDL: `DROP TABLE`, `DROP DATABASE`, `TRUNCATE`, `ALTER TABLE ... DROP`.
   - Запрет неконтролируемых мутаций данных: `DELETE` и `UPDATE` без строгого ограничивающего условия `WHERE` (или с фиктивным `WHERE 1=1`).
   - Блокировка эскалации привилегий (`GRANT ALL`, `SUPERUSER`).
3. **Secret-Filter (`contracts/secret_leak.py`)**:
   - Двунаправленный контроль (входящие параметры и исходящие ответы инструментов).
   - Детекция утечек по энтропии Шеннона и шаблонам: приватные ключи (RSA, Ed25519, ГОСТ), токены JWT, API-ключи, строки подключения к БД с паролями.
4. **Shell-Barrier (`contracts/shell_barrier.py`)**:
   - Блокировка деструктивных вызовов: `rm -rf /`, форматирование дисков (`mkfs`, `dd`), отключение межсетевых экранов (`iptables -F`).
   - Защита системного аудита: запрет остановки `auditd`, `syslog` и зачистки журналов.
   - Запрет неконтролируемого скачивания и исполнения из сети (`curl | bash`).

---

## ⚡ Преимущества перед зарубежными аналогами (NeMo Guardrails, Llama Guard)

| Параметр | NeMo Guardrails (NVIDIA) / Llama Guard | mcp-sentinel (ИБ 3.0) |
| :--- | :--- | :--- |
| **Механизм проверки** | Вторичная LLM-модель (вероятностная, недетерминированная) | **Аксиоматические инварианты (AST, строгая логика)** |
| **Задержка (Latency)** | 500–2500 мс (замедляет работу агента в разы) | **< 2 миллисекунд** |
| **Зависимости** | PyTorch, CUDA, гигабайты весов, внешние облака США | **0 внешних зависимостей (чистый Python 3)** |
| **Аппаратные требования**| Видеокарта с 16–24 ГБ VRAM | Работает на любом микрокомпьютере или старом сервере |
| **Аудит по ГОСТ** | Отсутствует | **Интегрирован с `iss-ledger-117` (ГОСТ Р 34.11-2012)** |

---

## 📦 Установка

```bash
# Клонирование из суверенного репозитория GitVerse
git clone https://git.isslab.ru/isslab/mcp-sentinel.git
cd mcp-sentinel

# Установка пакета
pip install -e .
```

---

## 🚀 Интеграция с Claude Code и Cursor

### Добавление в конфигурацию MCP (`claude_desktop_config.json` или `~/.cursor/mcp.json`):

Вместо прямого запуска уязвимого сервера вы оборачиваете его через `mcp-sentinel`:

```json
{
  "mcpServers": {
    "postgres-secure": {
      "command": "mcp-sentinel",
      "args": [
        "wrap",
        "--ledger", "/var/log/fstec117_audit.jsonl",
        "--agent", "claude-code",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/prod"
      ]
    }
  }
}
```

---

## 💻 Проверка вызовов из консоли (CLI)

```bash
# Проверка опасного запроса
mcp-sentinel check \
  --tool sql_query \
  --args '{"query": "DROP TABLE users;"}'

# Вывод:
# [-] ВЕРДИКТ: BLOCK (ЗАБЛОКИРОВАНО)
#     Причина: Unsat Core: Деструктивная команда DDL 'DROP TABLE' запрещена политикой безопасности.
```

---

## 📜 Цитирование

```bibtex
@software{mcp_sentinel_2026,
  author = {Fischuk, Alexander},
  title = {mcp-sentinel: Deterministic Circuit Breaker and Invariant Security Gateway for Model Context Protocol Agents},
  year = {2026},
  publisher = {ANO Institute for System Synthesis},
  url = {https://git.isslab.ru/isslab/mcp-sentinel}
}
```

---
**АНО «НИИ системного синтеза»**  
Официальный сайт: [isslab.ru](https://isslab.ru)  
Канал института: [@agiandhuman](https://t.me/agiandhuman)