Metadata-Version: 2.4
Name: mcp-sentinel
Version: 1.1.1
Summary: Детерминированный шлюз допустимости действий и Circuit Breaker для ИИ-агентов (MCP Security Gateway)
Author-email: АНО «НИИ системного синтеза» <info@isslab.ru>
License: Apache-2.0
Project-URL: Homepage, https://isslab.ru
Project-URL: Documentation, https://isslab.ru/cyber/
Project-URL: Repository, https://git.isslab.ru/isslab/mcp-sentinel
Keywords: mcp,model-context-protocol,security-gateway,circuit-breaker,ai-agents,prompt-injection,sql-guard,fs-jail,cybersecurity,fstec-117,claude-code,cursor
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Topic :: Security
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: iss-ledger-117>=1.1.1
Dynamic: license-file

# 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/)  
> *Репозиторий*: [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-серверами), проверяет каждый вызов инструмента **до передачи управления в операционную систему или СУБД**, блокирует недопустимые действия детерминированной проверкой по заданным правилам (перехват в памяти — медиана 0,015 мс; сквозной цикл с записью решения в ГОСТ-журнал — медиана 22,5 мс, N=100) и автоматически фиксирует доказательную базу в криптографическом журнале по стандарту **ГОСТ Р 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`).

---

## ⚡ Два подхода к проверке действий агента

Ограждение на второй языковой модели и детерминированная проверка решают разные задачи и
сравниваются по свойствам подхода, а не по громкости:

| Свойство | Проверка второй моделью | `mcp-sentinel` |
| :--- | :--- | :--- |
| **Характер решения** | вероятностный: тот же вход может дать разные вердикты | воспроизводимый: один вход — один вердикт |
| **Что проверяется** | смысл текста запроса | дискретный вызов инструмента и его аргументы |
| **Объяснение отказа** | текстом модели | правилом, которое сработало (`rule_id`), и причиной |
| **Требования к среде** | веса модели, ускоритель или внешняя служба | чистый Python 3.10+, без сторонних зависимостей |
| **Задержка** | определяется временем ответа модели | перехват в памяти: медиана 0,015 мс; сквозной цикл с записью в журнал: медиана 22,5 мс (N=100) |
| **След для аудита** | зависит от реализации | цепочка записей по ГОСТ Р 34.11-2012 (`iss-ledger-117`) |

Числа в колонке `mcp-sentinel` измерены нами (`benchmark_latency.py`); свойств чужих
продуктов мы не измеряли и чисел за них не приводим.

### Границы проверки

Контракты сопоставляют аргументы вызова с образцами (регулярные выражения), а не разбирают
синтаксис SQL или командной оболочки. Отсюда прямые следствия, которые важнее любой таблицы:

* запись, намеренно изменённая до неузнаваемости (иная кодировка, склейка строк на стороне
  СУБД, необычные разделители), может не совпасть с образцом и пройти;
* поиск секретов по энтропии даёт ложные срабатывания на длинных случайных строках,
  не являющихся секретами;
* шлюз проверяет то, что видит в вызове инструмента; действия, совершённые в обход
  протокола MCP, вне его поля зрения.

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

---

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

Пакет — чистый Python без сторонних зависимостей (кроме `iss-ledger-117`). Для изолированного контура скачайте файлы `.whl` и ставьте без сети:
```bash
pip install --no-index --find-links ./wheels mcp-sentinel
```
С доступом в сеть:
```bash
pip install --find-links https://isslab.ru/wp-content/uploads/iss-utils/index.html mcp-sentinel
```
Из исходников:
```bash
git clone https://git.isslab.ru/isslab/iss-ledger-117.git
git clone https://git.isslab.ru/isslab/mcp-sentinel.git
pip install ./iss-ledger-117 ./mcp-sentinel
```

---

## 🚀 Интеграция с 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 (ЗАБЛОКИРОВАНО)
#     Причина: Нарушен инвариант: Деструктивная команда DDL 'DROP TABLE' запрещена политикой безопасности.
```

---

## ⚖️ Границы

Реализация хеш-функции журнала проходит контрольные примеры ГОСТ Р 34.11-2012 (RFC 6986), но не является сертифицированным средством криптографической защиты информации.
Проверка контрактов — сопоставление с образцом, а не разбор синтаксиса: подробности в разделе «Границы проверки» выше.

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

```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)
