""" Движок шлюза допустимости действий «mcp-sentinel» (ИБ 3.0). In-line Circuit Breaker для протокола Model Context Protocol (MCP). Перехватывает и верифицирует вызовы инструментов (Tool Calls) до их исполнения, предотвращает деструктивные воздействия и фиксирует доказательную базу в криптографическом журнале по ГОСТ Р 34.11-2012 («Стрибог-256»). """ import hashlib import json import subprocess import sys import threading from typing import Any, Dict, List, Optional, Tuple from iss_ledger_117 import IssLedger117 from .contracts.base import BaseSecurityContract, ContractVerdict from .contracts.fs_jail import FSJailContract from .contracts.sql_guard import SQLGuardContract from .contracts.secret_leak import SecretLeakContract from .contracts.shell_barrier import ShellBarrierContract from .contracts.personal_data import PersonalDataContract def _parse_tool_call(line: str) -> Optional[Tuple[Any, str, Dict[str, Any]]]: """ Если строка — валидный JSON-RPC вызов `tools/call`, возвращает (id, имя_инструмента, аргументы). Иначе (пустая строка, невалидный JSON, другой метод) — None. Общий разбор для process_incoming_jsonrpc() и run_stdio_proxy() (сопоставление id -> инструмент). """ line_str = line.strip() if not line_str: return None try: msg = json.loads(line_str) except json.JSONDecodeError: return None if isinstance(msg, dict) and msg.get("method") == "tools/call": params = msg.get("params", {}) # Вызов, у которого params или arguments не объект, а имя не строка, контракты # проверить не могут. Такой вызов не пропускается «как есть», а помечается # arguments=None — process_incoming_jsonrpc ответит отказом (закрыто по умолчанию). if not isinstance(params, dict): return msg.get("id"), "malformed", None tool_name = params.get("name", "unknown") arguments = params.get("arguments", {}) if not isinstance(tool_name, str) or not isinstance(arguments, dict): return msg.get("id"), "malformed", None return msg.get("id"), tool_name, arguments return None class MCPSentinel: """ Инспектор допустимости и Circuit Breaker для MCP-агентов. """ def __init__( self, ledger_path: Optional[str] = "audit_fstec117.jsonl", allowed_roots: Optional[List[str]] = None, contracts: Optional[List[BaseSecurityContract]] = None, ): self.ledger = IssLedger117(ledger_path) if ledger_path else None if contracts: self.contracts = contracts else: self.contracts = [ FSJailContract(allowed_roots=allowed_roots), SQLGuardContract(allow_ddl=False, strict_where=True), SecretLeakContract(), ShellBarrierContract(), ] def validate_tool_call( self, agent_id: str, tool_name: str, arguments: Dict[str, Any] ) -> Tuple[bool, str, Optional[Dict[str, Any]]]: """ Проверка входящего вызова инструмента агента через набор контрактов. Возвращает (allowed, reason, details). """ target = tool_name # SEC-PKG-01: target не должен содержать открытый текст аргументов (путей, команд, # SQL-запросов, секретов и ПДн). Формируем target как имя инструмента плюс хеш аргументов. if isinstance(arguments, dict): for k in ("path", "target_file", "file", "query", "sql", "command", "cmd"): if k in arguments and isinstance(arguments[k], str): arg_hash = hashlib.sha256(arguments[k].encode("utf-8", errors="replace")).hexdigest()[:16] target = f"{tool_name}:{arg_hash}" break else: if arguments: arg_bytes = json.dumps(arguments, sort_keys=True, ensure_ascii=False).encode("utf-8", errors="replace") target = f"{tool_name}:{hashlib.sha256(arg_bytes).hexdigest()[:16]}" for contract in self.contracts: verdict: ContractVerdict = contract.check_tool_call(tool_name, arguments) if not verdict.allowed: # Фиксируем инцидент BLOCK в неизменяемом крипто-журнале ГОСТ if self.ledger: self.ledger.append( agent_id=agent_id, action=f"tool_call:{tool_name}", target=target, verdict="BLOCK", reason=verdict.reason, payload=arguments, ) return False, verdict.reason, verdict.details # Все контракты дали согласие (PERMIT) if self.ledger: self.ledger.append( agent_id=agent_id, action=f"tool_call:{tool_name}", target=target, verdict="PERMIT", reason="Ни один контракт не возразил", payload=arguments, ) return True, "Approved", None def validate_tool_result(self, agent_id: str, tool_name: str, content: str) -> Tuple[bool, str]: """Проверка исходящего ответа инструмента на утечки секретов.""" for contract in self.contracts: verdict = contract.check_tool_result(tool_name, content) if not verdict.allowed: if self.ledger: self.ledger.append( agent_id=agent_id, action=f"tool_result:{tool_name}", target=tool_name, verdict="BLOCK", reason=verdict.reason, payload=content[:200], ) return False, verdict.reason return True, "Approved" def process_incoming_jsonrpc( self, line: str, agent_id: str = "ai-agent" ) -> Tuple[str, bool]: """ Обработка одной строки JSON-RPC от агента. Возвращает: (response_or_line, should_forward_to_downstream) Если should_forward_to_downstream == False, response_or_line — это готовый синтетический ответ агенту об отказе в доступе. """ parsed = _parse_tool_call(line) if parsed is not None: msg_id, tool_name, arguments = parsed if arguments is None: allowed, reason = False, "Нарушен инвариант: вызов инструмента имеет некорректную структуру и не может быть проверен." if self.ledger: self.ledger.append(agent_id=agent_id, action="tool_call:malformed", target="malformed", verdict="BLOCK", reason=reason, payload=line.strip()[:200]) else: allowed, reason, _details = self.validate_tool_call( agent_id=agent_id, tool_name=tool_name, arguments=arguments ) if not allowed: # Отказ возвращается агенту синтетическим ответом MCP с текстом причины synthetic_error_resp = { "jsonrpc": "2.0", "id": msg_id, "result": { "content": [ { "type": "text", "text": f"[ИБ 3.0 CIRCUIT BREAKER] Действие заблокировано инвариантом безопасности.\n{reason}" } ], "isError": True } } return json.dumps(synthetic_error_resp, ensure_ascii=False) + "\n", False return line, True def process_outgoing_jsonrpc(self, line: str, agent_id: str, tool_name: str) -> str: """ Проверка одной строки ОТВЕТА нижестоящего MCP-сервера перед пересылкой агенту (обратное направление живого пути, в отличие от process_incoming_jsonrpc). Тестируется без подпроцесса: вызывающая сторона (run_stdio_proxy) отвечает только за сопоставление id ответа с именем инструмента вызова. Возвращает строку для отправки агенту: исходную строку без изменений, если ответ не является объектом с result.content (список) или проверка прошла, либо синтетический ответ с тем же id, если validate_tool_result вернул BLOCK. """ line_str = line.strip() if not line_str: return line try: msg = json.loads(line_str) except json.JSONDecodeError: # Невалидный JSON -- пробрасываем как есть return line if not isinstance(msg, dict): return line result = msg.get("result") if not isinstance(result, dict): return line content = result.get("content") if not isinstance(content, list): return line text = "".join( item.get("text", "") for item in content if isinstance(item, dict) and item.get("type") == "text" ) allowed, reason = self.validate_tool_result(agent_id, tool_name, text) if allowed: return line msg_id = msg.get("id") synthetic_resp = { "jsonrpc": "2.0", "id": msg_id, "result": { "content": [ { "type": "text", "text": f"[ИБ 3.0 CIRCUIT BREAKER] Ответ инструмента задержан инвариантом безопасности.\n{reason}" } ], "isError": True } } return json.dumps(synthetic_resp, ensure_ascii=False) + "\n" def run_stdio_proxy( downstream_cmd: List[str], agent_id: str = "ai-agent", ledger_path: str = "audit_fstec117.jsonl", allowed_roots: Optional[List[str]] = None, ) -> None: """ Запускает прозрачный Stdio-шлюз перед дочерним MCP-сервером. """ sentinel = MCPSentinel(ledger_path=ledger_path, allowed_roots=allowed_roots) # Запускаем дочерний процесс (настоящий MCP-сервер) proc = subprocess.Popen( downstream_cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=sys.stderr, bufsize=0, text=True, encoding="utf-8", ) # Словарь "id запроса -> имя инструмента", чтобы при ответе нижестоящего сервера # знать, каким контрактом проверять содержимое (validate_tool_result требует tool_name). # Заполняется при пробросе tools/call, читается и снимается записью в pipe_stdout. pending_calls: Dict[Any, str] = {} pending_lock = threading.Lock() # В stdout агента пишут два потока (ответы сервера и отказы шлюза): без замка строки # JSON-RPC могут перемешаться, и агент получит невалидный JSON. out_lock = threading.Lock() def emit(text: str) -> None: with out_lock: sys.stdout.write(text) sys.stdout.flush() # Поток чтения вывода от дочернего процесса -> наружу def pipe_stdout(): try: for line in proc.stdout: tool_name = "unknown" line_str = line.strip() if line_str: try: msg = json.loads(line_str) except json.JSONDecodeError: msg = None # id по JSON-RPC — строка или число; иное (список, объект) не хешируется # и уронило бы поток чтения, оставив агента без ответов. if isinstance(msg, dict) and isinstance(msg.get("id"), (str, int)): with pending_lock: tool_name = pending_calls.pop(msg["id"], None) or "unknown" # Проверяется ЛЮБОЙ ответ с result.content, а не только ответ на отслеженный # вызов: сервер, приславший содержимое с незнакомым id, не должен этим обойти # проверку. Имя инструмента нужно лишь для записи в журнал. emit(sentinel.process_outgoing_jsonrpc(line, agent_id, tool_name)) except (BrokenPipeError, OSError): pass t = threading.Thread(target=pipe_stdout, daemon=True) t.start() # Основной поток: чтение от агента -> проверка -> проброс в процесс try: for line in sys.stdin: out_line, should_forward = sentinel.process_incoming_jsonrpc(line, agent_id=agent_id) if should_forward: # Запоминаем id -> имя инструмента для сверки ответа нижестоящего сервера parsed = _parse_tool_call(line) if parsed is not None and isinstance(parsed[0], (str, int)): msg_id, tool_name, _arguments = parsed with pending_lock: pending_calls[msg_id] = tool_name proc.stdin.write(out_line) proc.stdin.flush() else: # Отказ шлюза отправляем агенту сразу, до сервера вызов не доходит emit(out_line) except (KeyboardInterrupt, BrokenPipeError): pass finally: # Агент закрыл ввод: даём серверу дописать последние ответы, а потоку чтения — # доставить их. Немедленный terminate() терял ответ на последний вызов. try: proc.stdin.close() except OSError: pass try: proc.wait(timeout=5) except subprocess.TimeoutExpired: proc.terminate() t.join(timeout=5)