# iss-ledger-117: Криптографический регистратор доказательной базы ИИ (ГОСТ Р 34.11-2012)

[![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/)
[![ГОСТ: Р 34.11-2012](https://img.shields.io/badge/ГОСТ_Р-34.11--2012-red.svg)](https://datatracker.ietf.org/doc/html/rfc6986)
[![Zero-Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)]()

> **Открытая утилита стека «ИБ 3.0»: журнал действий ИИ-агента с хеш-цепочкой по ГОСТ Р 34.11-2012**  
> *Разработка: АНО «НИИ системного синтеза» (Лаборатория системного синтеза / ISS Lab)*  
> *Официальный сайт*: [https://isslab.ru](https://isslab.ru) · *Страница кибербезопасности*: [https://isslab.ru/cyber/](https://isslab.ru/cyber/)  
> *Репозиторий*: [https://git.isslab.ru/isslab/iss-ledger-117](https://git.isslab.ru/isslab/iss-ledger-117)

---

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

`iss-ledger-117` — это криптографический регистратор событий для автономных систем искусственного интеллекта (LLM, AI-агенты, Claude Code, Cursor, MCP-серверы), функционирующий по принципу **Append-Only Cryptographic Ledger**.

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

### 🛡️ Каким требованиям служит (соответствия сам по себе не даёт):
1. **Приказ ФСТЭК России № 117** (утверждён 11.04.2025, в силе с 01.03.2026, взамен приказа № 17 от 2013 г.):
   - непрерывное протоколирование обращений к компонентам ИИ и сгенерированных вызовов внешних функций;
   - защита журналов аудита от модификации и скрытого удаления стандартизированными криптографическими алгоритмами (ГОСТ Р 34.11-2012);
   - для систем с ИИ (требования req-60 / req-61 методики к приказу): контроль применяемых моделей и обучающих данных, исключение недекларированных деструктивных воздействий.
2. **Федеральный закон № 187-ФЗ «О безопасности КИИ РФ»**: след действий автономных компонентов с контролем целостности как часть доказательной базы субъекта КИИ.

> Формулировки требований даны по отраслевому разбору методики к приказу № 117; дословный текст приказа на fstec.ru построчно не сверялся. Правовой вывод о применимости — за организацией.

---

## ⚡ Свойства

* **Без сторонних зависимостей**: чистый Python 3.10+. Не требует OpenSSL, C-компиляторов, pycryptodome или Rust.
* **Установка без сети**: пакет поставляется файлом `.whl`; установка и все команды этого документа при приёмке каждой версии прогоняются в чистом окружении без доступа в сеть.
* **Контроль целостности**: изменение, удаление, вставка и перестановка отдельных записей обнаруживаются при пересчёте цепочки.
* **Проверка без доверия к составителю**: журнал пересчитывается одним файлом `iss_verifier.py` на стандартном Python, без установки пакета.
* **Сводка по журналу**: рабочий документ для службы ИБ в формате Markdown.

### Границы

* Цепочка сама по себе не обнаруживает ПОЛНУЮ перезапись журнала лицом, имеющим доступ к файлу: такой журнал внутренне согласован. Для доказательной силы голову цепочки закрепляют у стороны, не зависящей от владельца журнала, — меткой доверенного времени или записью во внешнем журнале.
* Реализация хеш-функции проходит контрольные примеры RFC 6986, но не является сертифицированным средством криптографической защиты информации.
* Сводка по журналу не является актом или заключением о соответствии; соответствия приказу ФСТЭК России № 117 пакет не удостоверяет.

---

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

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

---

## 🚀 Быстрый старт (CLI)

### 1. Добавление записи о действии агента
```bash
# Регистрация разрешенного SQL-запроса
iss-ledger append \
  --agent "claude-code" \
  --action "tool_call:sql" \
  --target "db.prod.billing" \
  --verdict "PERMIT" \
  --reason "Policy approved" \
  --payload "SELECT id, balance FROM accounts WHERE id = 42"

# Регистрация заблокированной деструктивной попытки
iss-ledger append \
  --agent "cursor-agent" \
  --action "tool_call:bash" \
  --target "/etc/shadow" \
  --verdict "BLOCK" \
  --reason "Нарушен инвариант: FS-Jail prohibited access to /etc/shadow" \
  --payload "cat /etc/shadow"
```

### 2. Верификация целостности журнала
```bash
iss-ledger verify --file audit_fstec117.jsonl
```
*Вывод:*
```
[OK] Целостность 2 записей успешно подтверждена ГОСТ Р 34.11-2012.
     Всего событий: 2 (PERMIT: 1, BLOCK: 1)
     Хеш среза:     55b5e709eb06745c27d1aebb8932c41eb33da02ddb6d0a78aaf462b19bc7c9d3
```

### 3. Сводка по журналу
```bash
iss-ledger report \
  --file audit_fstec117.jsonl \
  --org "МУП Городской Водоканал" \
  --system "АСУ ТП Очистных Сооружений (Контур ИИ)" \
  --category "2 категория КИИ" \
  --out ledger_summary.md
```

---

## 🔍 Независимая проверка инспектором (`iss_verifier.py`)

Проверяющему — внутреннему аудитору, заказчику, инспектору — не требуется устанавливать пакеты и доверять составителю журнала:

1. Передайте проверяющему один файл `iss_verifier.py` (200 строк чистого кода).
2. Запуск в изолированном контуре:
   ```bash
   python iss_verifier.py audit_fstec117.jsonl
   ```
3. Проверяющий видит итог пересчёта:
   ```
   ========================================================================
    АВТОНОМНЫЙ ИНСПЕКТОРСКИЙ ВАЛИДАТОР ЦЕЛОСТНОСТИ ЖУРНАЛОВ (ИБ 3.0)
    Стандарт: ГОСТ Р 34.11-2012 («Стрибог-256», RFC 6986)
   ========================================================================
   [+] РЕЗУЛЬТАТ ВЕРИФИКАЦИИ:
       Всего записей проверено:    2
       Статус целостности:         ЦЕЛОСТНОСТЬ 100% ПОДТВЕРЖДЕНА ПО ГОСТ
       Разрешено действий (PERMIT): 1
       Предотвращено угроз (BLOCK): 1
       Финальный крипто-якорь:     55b5e709eb06745c27d1aebb8932c41eb...
   [OK] Целостность цепочки записей подтверждена (ГОСТ Р 34.11-2012).
        Проверка целостности не заменяет аттестацию системы по приказу ФСТЭК России № 117.
   ```

---

## 💻 Использование в Python-коде (Интеграция с Агентом / MCP)

```python
from iss_ledger_117 import IssLedger117

# Инициализация регистратора
ledger = IssLedger117("var/log/ai_agent_audit.jsonl")

# Перехват вызова инструмента агента
def on_agent_tool_call(agent_id, action, target, payload):
    # 1. Проверка правилами безопасности (Circuit Breaker)
    if is_forbidden(target):
        # Фиксация предотвращения инцидента
        ledger.append(
            agent_id=agent_id,
            action=action,
            target=target,
            verdict="BLOCK",
            reason="Нарушен инвариант: Security invariant violation",
            payload=payload
        )
        raise PermissionError("Действие заблокировано ИБ 3.0")

    # 2. Фиксация разрешенного действия
    ledger.append(
        agent_id=agent_id,
        action=action,
        target=target,
        verdict="PERMIT",
        reason="Policy OK",
        payload=payload
    )
    return execute_tool(action, target, payload)
```

---

## 📐 Математическая схема связывания блоков

Каждая $n$-я запись в журнале содержит канонический хеш:
$$H_n = \text{Streebog256}\left(Index_n \parallel Timestamp_n \parallel AgentId_n \parallel Action_n \parallel Target_n \parallel H(Payload_n) \parallel Verdict_n \parallel Reason_n \parallel H_{n-1}\right)$$

Где:
* $H_0 = 0^{64}$ (хэш генезис-блока).
* $\parallel$ — канонический разделитель полей `|`.
* $\text{Streebog256}$ — алгоритм ГОСТ Р 34.11-2012 с длиной выхода 256 бит.

---

## 🧪 Верификация и тесты

Запуск полного набора юнит-тестов, включая официальные векторы RFC 6986 §10.1 (M1) и §10.2 (M2):
```bash
python -m unittest discover -s tests
```
*Результат:*
```
Ran 7 tests in 0.58s
OK
```

---

## 📜 Цитирование в научных работах и отчетах

Если вы используете `iss-ledger-117` в научных исследованиях или аттестационных отчетах:
```bibtex
@software{iss_ledger_117_2026,
  author = {Fischuk, Alexander},
  title = {iss-ledger-117: Zero-Dependency Cryptographic Verification Ledger for AI Agents under FSTEC Order No. 117 and GOST R 34.11-2012},
  year = {2026},
  publisher = {ANO Institute for System Synthesis},
  url = {https://git.isslab.ru/isslab/iss-ledger-117}
}
```

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