## Возможности

- **Множество методов сбора**: Поддерживает сбор через API, парсинг HTML, RSS-каналы и многое другое
- **Гибкая фильтрация**: Фильтрация по ключевым словам, дате, источнику и другим критериям
- **Экспорт данных**: Экспорт в JSON, CSV и другие форматы
- **Планирование задач**: Встроенный планировщик для регулярного сбора
- **Управление прокси**: Поддержка HTTP/SOCKS прокси
- **Настраиваемые источники**: Легко добавляйте новые источники через конфигурационные файлы

## Установка

### Из исходного кода

```bash
git clone https://github.com/example/tool.git
cd tool
pip install -r requirements.txt

pip install tool

from tool import Collector

collector = Collector()
collector.add_source("https://example.com/feed")
results = collector.collect()
print(results)

tool collect --source https://example.com/feed --output results.json

sources:
  - name: example
    url: https://example.com/feed
    type: rss
    interval: 3600

filters:
  keywords:
    - security
    - vulnerability
  date_range:
    start: 2024-01-01
    end: 2024-12-31

output:
  format: json
  path: ./output

collector.add_source(
    name="my_source",
    url="https://example.com/api",
    type="api",
    headers={"Authorization": "Bearer TOKEN"}
)

filtered = collector.filter(
    keywords=["security", "CVE"],
    date_from="2024-01-01"
)

collector.export(format="json", path="output.json")
collector.export(format="csv", path="output.csv")

Сканируйте полученный контекст до того, как он достигнет модели:```python
res = shield.protect(user_prompt, my_llm, context=retrieved_docs)
if res.action == "block":
    ...   # a poisoned document was caught before the model saw it

Внедрите решения в ваше логирование один раз, и каждый вызов будет записан:```python
from reasongate import Shield, log_sink, file_sink

shield = Shield(audit_hook=log_sink)                    # -> "reasongate.audit" logger
shield = Shield(audit_hook=file_sink("audit.jsonl"))    # -> JSON-Lines, SIEM-ready

- Щит выключен, отравленная запись: запись отправляется по электронной почте атакующему и запускается передача.
  Это реальные побочные эффекты, записанные на диск.
- Щит включён, отравленная запись: косвенное сканирование перехватывает полезную нагрузку до вызова
  модели. Никаких побочных эффектов.
- Щит включён, чистая запись: агент отвечает нормально.
- Щит включён, **переформулированная** атака: полезная нагрузка перефразируется как обычная деловая заметка, так что
  слой сигнатур её *не* обнаруживает — и всё же никакого побочного эффекта не происходит, потому что
  шлюз действий (ниже) блокирует вызов инструмента: его назначение (адрес эксфильтрации, учётная запись)
  цитируется из недоверенного содержимого, что никакая переформулировка не скроет.

Будьте ясны в том, что делает каждый слой. Сопоставление сигнатур имеет реальный предел: переформулируйте
инъекцию так, чтобы она больше не совпадала с известным шаблоном, и ядро правил её не поймает — вот
почему ядро является первым фильтром, а не границей. Четвёртый прогон — честный ответ на
этот предел: он не делает вид, что обнаружение улучшилось; обнаружение по-прежнему пропускает переформулированную
атаку. То, что останавливает нарушение, — это *другой* слой, который рассуждает о доверии к данным
за действием, а не о формулировке текста. Все четыре условия обеспечиваются как CI-инварианты, так что демо не может незаметно деградировать.

Также есть живая песочница: <https://reasongate-demo-nvgo.onrender.com>. Она запускает
ядро без зависимостей, не требует API-ключа и не отправляет данные за пределы сервера.

## Детекторы в ядре

- **Нормализация / деобфускация.** Удаляет символы нулевой ширины, кириллические гомоглифы,
  leetspeak (`1gn0re`), буквы с пробелами и точками (`i.g.n.o.r.e`) и base64-полезные нагрузки, так что
  замаскированная известная формулировка нормализуется обратно во что-то, что слой шаблонов может сопоставить.
- **Шаблоны инъекций / джейлбрейков.** Слой правил для известных формулировок.
- **Косвенная инъекция.** Запускает то же сканирование на извлечённых документах и выводе инструментов до
  того, как они достигнут модели.
- **Утечка вывода и канарейка.** Помечает секреты и PII на выходе. Канареечный токен,
  внедрённый в системный промпт, делает утечку системного промпта доказуемой, а не предполагаемой.

Движок политик объединяет эти сигналы с калиброванным noisy-OR, так что несколько слабых сигналов
могут в сумме дать блокировку, тогда как изолированный шум от легитимного промпта — нет.

## Шлюз действий (вызовы инструментов агентом)

Детекторы спрашивают: «является ли этот текст инъекцией?» — вопрос, который можно проиграть переформулировкой. Шлюз
действий задаёт другой, не зависящий от формулировки вопрос: *может ли это действие продолжиться, учитывая
доверие к данным, которые его породили?* Это защита на основе возможностей против косвенной
инъекции — разрушение «смертоносной триады» из недоверенного содержимого, чувствительной возможности и
пути наружу — и она ловит переформулированные атаки, которые пропускает слой сигнатур.```python
from reasongate import ToolGate, ToolPolicy, Segment

gate = ToolGate([
    ToolPolicy("transfer_funds", sensitive=True, destination_args=("to_account",)),
    ToolPolicy("send_email",     sensitive=True, destination_args=("to",)),
])

record = Segment(text=retrieved_doc, source="crm", trust="untrusted")
decision = gate.authorize(
    {"name": "transfer_funds", "args": {"to_account": "9900", "amount": "$84,200"}},
    context=[record],
)
decision.allowed       # False — the destination account is quoted from untrusted content
print(decision.explain())

Авторизация не отмывает испорченный пункт назначения: `authorized=True` снимает
соприсутствие, потому что принципал запросил действие — но не снимает значение
аргумента, которое восходит к недоверенному содержимому, потому что принципал его не выбирал.

### Встраивание в существующий агент```python
from reasongate.adapters.toolcalls import from_anthropic, refusal_result
from reasongate.catalog import infer_policies, describe

print(describe(infer_policies([t["name"] for t in tools])))   # draft policies, then correct them

for call in from_anthropic(response.content):
    decision = session.authorize(call)
    if not decision.allowed:
        results.append(refusal_result(call, decision))        # the model is told why
    else:
        results.append(run(call))

**Судья-модель не входит в этот пакет.** Чтобы решить, противоречит ли предложение
политике в виде прозы, нужна модель; без настройки шлюз возвращает *«не оценено»*, а не
разрешение, потому что непроверенный запрос никогда не должен выглядеть как одобренный.
Судья-модель сама по себе также является целью для инъекций, и это носит рекомендательный
характер — слой, с которым нельзя спорить, — это `ToolGate`, который ограничивает то, что
агент может *делать*.

### Измерено на AgentDojo

У шлюза теперь есть собственные показатели на бенчмарке, созданном для этой угрозы
([AgentDojo](https://github.com/ethz-spylab/agentdojo): четыре набора агентов, использующих
инструменты, атакуемых через данные, которые агент читает). Без модели в цикле —
собственные эталонные последовательности вызовов инструментов бенчмарка воспроизводятся
через шлюз как полностью перехваченный агент, и собственные чекеры AgentDojo оценивают
результат:

| | Успех атаки | Полезность на чистом трафике |
|---|---:|---:|
| Без шлюза | 97.4% | 100% |
| Только заражение аргументов | **12.6%** | 64.9% |
| Строгий (совместное присутствие) | 3.4% | 41.2% |

С моделью в цикле (Claude Haiku 4.5, banking) картина ещё резче: модель отклонила все
инъекции самостоятельно, поэтому шлюз не добавил безопасности и стоил 12.5 пункта
полезности — страховка на случай, когда суждение модели даёт сбой, за свою цену.
Читайте оба столбца. 35 пунктов полезности, которых стоит шлюз, — это легитимные
назначения, которые агент прочитал из хранилища — IBAN в счёте, который его попросили
оплатить, — и заражение не может отличить его от IBAN атакующего в том же файле, потому
что оно не смотрит на слова. Что проходит — это три задокументированные формы: цели,
являющиеся чтениями, назначения, найденные поиском, а не процитированные, и вред в поле,
не являющемся назначением. Метод, показатели по наборам и оговорки:
[RESULTS.md → The gate on AgentDojo](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md#the-gate-on-agentdojo).

Обоснование этого слоя — модель угроз, почему обнаружение текста структурно
недостаточно, и гарантии *и не-гарантии* шлюза — изложено в
[docs/threat-model.md](https://github.com/cgrtml/reasongate/blob/main/docs/threat-model.md). Что он всё ещё упускает, измеренное и
процитированное из реального корпуса, — в [docs/coverage-gaps.md](https://github.com/cgrtml/reasongate/blob/main/docs/coverage-gaps.md).

## Бенчмарки

Полная методология, тестовый стенд и отрицательные результаты — в [RESULTS.md](https://github.com/cgrtml/reasongate/blob/main/RESULTS.md).
Три числа стоит читать вместе: что он блокирует сверх меры, что он ловит и во что он
вам обходится на запрос.

**Избыточная защита.** Многие средства защиты блокируют сверх меры безобидные промпты,
которые лишь содержат триггерные слова вроде *ignore*, *system* или *bypass*. На
[NotInject](https://huggingface.co/datasets/leolee99/NotInject)
(339 безобидных, но нагруженных триггерными словами промптов) ядро правил имеет
**0.0% ложноположительных срабатываний** и 100% точность на безобидных данных офлайн.

**Полнота обнаружения при обходе на известных шаблонах.** Когда известная атака
обфусцирована, нормализация восстанавливает большую её часть:

| | Полнота при обходе | FPR | F1 |
|---|---:|---:|---:|
| Только regex | 21.2% | 3.3% | 0.349 |
| Ядро (нормализация + косвенные) | 78.1% | 6.7% | 0.871 |

Это полнота на *обфусцированных вариантах шаблонов, которые ядро уже знает*. Это не
полнота на новых формулировках — это тот показатель 0%, отмеченный выше.

**Стоимость на запрос.** Измерено с помощью `eval/latency.py` (p50/p95 на путь вызова, Apple M3 Pro):

| Вход | p50 | p95 |
|---|---:|---:|
| Промпт чата (60 символов) | 0.178 ms | 0.202 ms |
| Документ 2 KB, чистый | 8.51 ms | 8.94 ms |
| Документ 50 KB, чистый (потолок входа) | 211 ms | 216 ms |
| `ToolGate.authorize` (вызов инструмента, любого размера) | 0.020 ms | 0.021 ms |

Один процесс обрабатывает ~5,400 промптов чата/с, и ядро не хранит состояния, поэтому
оно масштабируется с процессами. То, что стоит знать перед развёртыванием: **путь входа
линеен по длине входа — около 4.2 ms на KB для чистого документа, 1.7 ms, как только
шаблон уже совпал.** При размере чата это примерно в 650 раз дешевле, чем защита на
основе модели (ProtectAI deberta-v3, ~116 ms); при 50 KB это *хуже*, потому что
трансформер обрезает на 512 токенах, а мы сканируем всё. Точка перехода — около 25 KB —
пропускайте целые документы через шлюз, и вы за них платите. У шлюза действий нет этого
свойства: он читает аргументы инструментов и доверие к сегментам, а не прозу, поэтому он
бесплатен при любом размере.

**ML-детектор (отдельное дополнение).** Классификатор на основе эмбеддингов обрабатывает
естественно сформулированные атаки, которые ядро правил не может. Это его показатели, а
не ядра:

| Настройка | Полнота | FPR | F1 |
|---|---:|---:|---:|
| Отложенный тест (~5.5k, объединённые реальные данные) | 96.1% | 0.3% | 0.978 |
| 5-кратная кросс-валидация | 95.5% ± 0.8 | 2.5% ± 1.3 | 0.963 ± 0.010 |
| Вне распределения (обучение A+B, тест на невидимом C) | 87.6% | 10.9% | 0.882 |

Данные: `deepset/prompt-injections`, `jackhhao/jailbreak-classification`,
`xTRam1/safe-guard-prompt-injection`. Один отрицательный результат стоит упомянуть:
более ранняя модель, обученная на синтетических данных, показала F1 0.98, но абляция
показала, что одни лишь пунктуация и регистр достигали 0.96 — оценка была артефактом
генератора данных. Именно объяснимый классификатор это выявил. Падение вне распределения
с 0.97 до 0.88 — это реальное число обобщения: оно ухудшается, но не рушится.

Воспроизведите любое из этого — сгруппировано по тому, что на самом деле нужно каждому
скрипту, потому что начиная с 0.2.0 обученная модель живёт в дополнении, и только
бенчмарки ядра правил запускаются против этого репозитория отдельно:```bash
# Offline, no key, no add-on — runs against this repo as-is:
python eval/public_bench.py     # over-defense on NotInject (339 benign)
python eval/adversarial.py      # evasion robustness of the rule core
python eval/latency.py          # cost per request: p50/p95/p99 and throughput

# Needs `pip install reasongate[eval]` and a VOYAGE_API_KEY (embeddings):
python eval/pipeline_real.py    # train/val/test with a validation-tuned threshold
python eval/validate.py         # leakage check, trivial baselines, 5-fold CV, 5x2cv

# Needs the enterprise add-on (the trained model moved there in 0.2.0):
python eval/ood_test.py         # out-of-distribution generalization
python eval/head_to_head.py     # vs ProtectAI deberta-v3

# Needs `pip install agentdojo` (Python 3.10+), no key — the action gate on AgentDojo:
python eval/agentdojo_gate.py   # ASR and utility, gate off / taint / strict