agentlatch-security 0.4.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,543 @@
1
+ """RuntimeLogImporter: turn runtime trace and payload logs into readable events and gate results.
2
+
3
+ It tails the proxy's trace file (and, optionally, its payloads file), joins each trace record with
4
+ its payload record (``MCPEventNormalizer``), appends one row per event to an events CSV, prints a
5
+ one-line summary per event, and hands the same normalized event to every installed gate in turn,
6
+ appending one CSV row per gate result as soon as that gate finishes.
7
+
8
+ It reads only files the proxy has already written, so it runs in parallel with the MCP flow and
9
+ can neither delay nor change it. A gate that raises is recorded as an error result and the
10
+ remaining gates still run. Restarting is safe: results already in the CSV are not repeated.
11
+
12
+ With an ``EventStore`` (for example ``SQLiteEventStore``), every normalized event is also saved
13
+ there, one transaction per pass. A save that fails while following is retried on the next pass,
14
+ so the store catches up once it is reachable again; a restart catches up from the files.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import copy
20
+ import csv
21
+ import importlib
22
+ import json
23
+ import logging
24
+ import os
25
+ import pkgutil
26
+ import threading
27
+ import time
28
+ from collections import deque
29
+ from collections.abc import Callable, Iterable, Mapping
30
+ from dataclasses import dataclass
31
+ from pathlib import Path
32
+ from typing import Any, Protocol, TextIO
33
+
34
+ from agent_latch.runtime.normalizer import (
35
+ PAYLOAD_METHODS,
36
+ EventKey,
37
+ MCPEventNormalizer,
38
+ is_payload_record,
39
+ is_trace_record,
40
+ payload_key,
41
+ run_id_for,
42
+ trace_key,
43
+ )
44
+ from agent_latch.runtime.trace import summarize_record
45
+
46
+ log = logging.getLogger("agent_latch.runtime")
47
+
48
+ CSV_COLUMNS = ("run_id", "order", "gate_id", "result_json")
49
+ EVENT_COLUMNS = (
50
+ "run_id", "order", "timestamp", "session_id", "request_id", "server", "method", "stage",
51
+ "name", "outcome", "duration_ms", "output_bytes", "has_payload", "excerpt",
52
+ )
53
+ # A spreadsheet runs a cell that starts with one of these as a formula.
54
+ _FORMULA_START = ("=", "+", "-", "@", "\t", "\r")
55
+ POLL_INTERVAL_SECONDS = 0.1
56
+ # How long a trace record waits for its payload record before moving on without it (follow mode).
57
+ PAYLOAD_GRACE_SECONDS = 2.0
58
+ _BATCH_LINES = 1000
59
+
60
+
61
+ class Gate(Protocol):
62
+ """Contract implemented by a runtime gate plugin."""
63
+
64
+ gate_id: str
65
+
66
+ def evaluate(self, event: dict[str, Any], /) -> Mapping[str, Any]: ...
67
+
68
+
69
+ class EventStore(Protocol):
70
+ """Where normalized events are kept. ``SQLiteEventStore`` is the local one.
71
+
72
+ Another destination (a warehouse, or an opt-in trace exporter) implements this same contract.
73
+ ``save`` returns how many events were new and raises ``OSError`` when the batch was not stored.
74
+ """
75
+
76
+ path: Path | None
77
+
78
+ def open(self) -> None: ...
79
+
80
+ def save(self, events: list[dict[str, Any]], /) -> int: ...
81
+
82
+ def close(self) -> None: ...
83
+
84
+
85
+ @dataclass(frozen=True)
86
+ class GatePlugin:
87
+ gate_id: str
88
+ evaluate: Callable[[dict[str, Any]], Mapping[str, Any]]
89
+
90
+
91
+ def discover_gates() -> list[GatePlugin]:
92
+ """Load gate modules from ``agent_latch.gates`` in deterministic order."""
93
+ package = importlib.import_module("agent_latch.gates")
94
+ package_path = getattr(package, "__path__", None)
95
+ if package_path is None:
96
+ raise ValueError("agent_latch.gates is not a package")
97
+
98
+ plugins: list[GatePlugin] = []
99
+ for module_info in sorted(pkgutil.iter_modules(package_path), key=lambda item: item.name):
100
+ if module_info.name.startswith("_"):
101
+ continue
102
+ module = importlib.import_module(f"{package.__name__}.{module_info.name}")
103
+ gate_id = getattr(module, "GATE_ID", None)
104
+ evaluate = getattr(module, "evaluate", None)
105
+ if not isinstance(gate_id, str) or not gate_id.strip() or not callable(evaluate):
106
+ raise ValueError(
107
+ f"gate module {module.__name__} must define non-empty GATE_ID and evaluate(event)"
108
+ )
109
+ plugins.append(GatePlugin(gate_id=gate_id, evaluate=evaluate))
110
+
111
+ ids = [plugin.gate_id for plugin in plugins]
112
+ if len(ids) != len(set(ids)):
113
+ raise ValueError("gate plugin GATE_ID values must be unique")
114
+ return plugins
115
+
116
+
117
+ class _LineTail:
118
+ """Reads complete new lines from a file that may still be growing or not exist yet."""
119
+
120
+ def __init__(self, path: Path) -> None:
121
+ self.path = path
122
+ self.line_no = 0
123
+ self._stream: TextIO | None = None
124
+ self._pending = ""
125
+ self._ready: deque[tuple[int, str]] = deque()
126
+
127
+ def read(self, limit: int = _BATCH_LINES) -> list[tuple[int, str]]:
128
+ out: list[tuple[int, str]] = []
129
+ while len(out) < limit:
130
+ if self._ready:
131
+ out.append(self._ready.popleft())
132
+ elif not self._fill():
133
+ break
134
+ return out
135
+
136
+ def finish(self) -> None:
137
+ """Treat an unterminated last line as complete (one-shot mode only)."""
138
+ if self._pending:
139
+ self.line_no += 1
140
+ self._ready.append((self.line_no, self._pending))
141
+ self._pending = ""
142
+
143
+ def close(self) -> None:
144
+ if self._stream is not None:
145
+ self._stream.close()
146
+ self._stream = None
147
+
148
+ def _fill(self) -> bool:
149
+ if self._stream is None:
150
+ try:
151
+ self._stream = self.path.open("r", encoding="utf-8", newline="")
152
+ except FileNotFoundError:
153
+ return False
154
+ chunk = self._stream.read(64 * 1024)
155
+ if not chunk:
156
+ return False
157
+ parts = (self._pending + chunk).split("\n")
158
+ self._pending = parts.pop()
159
+ for part in parts:
160
+ self.line_no += 1
161
+ self._ready.append((self.line_no, part))
162
+ return True
163
+
164
+
165
+ def _open_private(path: Path) -> TextIO:
166
+ """Open for append and read, creating the file with mode 0600."""
167
+ path.parent.mkdir(parents=True, exist_ok=True)
168
+ fd = os.open(path, os.O_RDWR | os.O_CREAT | os.O_APPEND, 0o600)
169
+ return os.fdopen(fd, "a+", encoding="utf-8", newline="")
170
+
171
+
172
+ def _parse(text: str) -> Any:
173
+ try:
174
+ return json.loads(text)
175
+ except json.JSONDecodeError:
176
+ return None
177
+
178
+
179
+ class RuntimeLogImporter:
180
+ """Joins trace and payload logs into normalized events and runs every gate on each one.
181
+
182
+ ``events_csv`` gets one row per event whether or not any gate is installed; ``output_csv``
183
+ gets one row per gate result and is only created when there are gates. ``summary`` (for
184
+ example ``sys.stderr``) gets one line per newly processed event. ``store`` keeps the same
185
+ events; it is optional and local unless that store itself says otherwise.
186
+
187
+ ``follow=True`` keeps waiting for appended lines until ``stop()`` is called (or the process is
188
+ interrupted); ``follow=False`` processes what is in the files now and returns.
189
+ """
190
+
191
+ def __init__(
192
+ self,
193
+ trace_path: Path,
194
+ output_csv: Path | None,
195
+ gates: Iterable[Gate],
196
+ *,
197
+ payloads_path: Path | None = None,
198
+ events_csv: Path | None = None,
199
+ normalized_path: Path | None = None,
200
+ summary: TextIO | None = None,
201
+ store: EventStore | None = None,
202
+ run_id: str | None = None,
203
+ follow: bool = True,
204
+ poll_interval: float = POLL_INTERVAL_SECONDS,
205
+ payload_grace: float = PAYLOAD_GRACE_SECONDS,
206
+ ) -> None:
207
+ if poll_interval <= 0:
208
+ raise ValueError("poll_interval must be greater than zero")
209
+ store_path = store.path if store is not None else None
210
+ paths = [
211
+ p for p in (
212
+ trace_path, payloads_path, output_csv, events_csv, normalized_path, store_path,
213
+ ) if p
214
+ ]
215
+ if len({p.resolve() for p in paths}) != len(paths):
216
+ raise ValueError("trace, payloads and output files must all be different files")
217
+ self.trace_path = trace_path
218
+ self.payloads_path = payloads_path
219
+ self.output_csv = output_csv
220
+ self.events_csv = events_csv
221
+ self.normalized_path = normalized_path
222
+ self.summary = summary
223
+ self.store = store
224
+ self.gates = list(gates)
225
+ self.follow = follow
226
+ self.poll_interval = poll_interval
227
+ self.payload_grace = payload_grace
228
+ self._run_id = run_id
229
+ self._stop = threading.Event()
230
+ self._trace = _LineTail(trace_path)
231
+ self._payloads = _LineTail(payloads_path) if payloads_path else None
232
+ self._pending: deque[tuple[int, dict[str, Any], float]] = deque()
233
+ self._queues: dict[EventKey, deque[tuple[int, dict[str, Any]]]] = {}
234
+ self._normalizer: MCPEventNormalizer | None = None
235
+ self._csv: TextIO | None = None
236
+ self._writer: csv.DictWriter[str] | None = None
237
+ self._events: TextIO | None = None
238
+ self._events_writer: csv.DictWriter[str] | None = None
239
+ self._normalized: TextIO | None = None
240
+ self._done: set[tuple[str, ...]] = set()
241
+ self._events_done: set[tuple[str, ...]] = set()
242
+ self._normalized_done: set[tuple[str, str]] = set()
243
+ self._unsaved: list[dict[str, Any]] = [] # events waiting for the store
244
+ self._store_failing = False
245
+
246
+ def stop(self) -> None:
247
+ """Ask a following importer to finish its current pass and return."""
248
+ self._stop.set()
249
+
250
+ def run(self) -> None:
251
+ try:
252
+ self._open_outputs()
253
+ if not (
254
+ self.gates or self.events_csv or self.normalized_path or self.summary or self.store
255
+ ):
256
+ log.warning("agent-latch-runtime: no gates and no outputs; nothing will be written")
257
+ while not self._stop.is_set():
258
+ progressed = self._ingest()
259
+ progressed = self._drain(final=False) or progressed
260
+ self._save_events(final=False)
261
+ if progressed:
262
+ continue
263
+ if not self.follow:
264
+ break
265
+ self._stop.wait(self.poll_interval)
266
+ if self.follow:
267
+ self._ingest()
268
+ self._drain(final=False)
269
+ self._save_events(final=False)
270
+ if self._unsaved:
271
+ log.warning(
272
+ "agent-latch-runtime: %d event(s) not saved to the database; they will be"
273
+ " saved on the next run",
274
+ len(self._unsaved),
275
+ )
276
+ else:
277
+ self._finish()
278
+ finally:
279
+ self._close()
280
+
281
+ def _finish(self) -> None:
282
+ self._trace.finish()
283
+ if self._payloads is not None:
284
+ self._payloads.finish()
285
+ while self._ingest():
286
+ pass
287
+ self._drain(final=True)
288
+ self._save_events(final=True)
289
+ unmatched = sum(len(queue) for queue in self._queues.values())
290
+ if unmatched:
291
+ log.warning("agent-latch-runtime: %d payload record(s) had no trace record", unmatched)
292
+
293
+ def _open_outputs(self) -> None:
294
+ if self.store is not None:
295
+ self.store.open() # first, so a bad database leaves no other file open
296
+ if self.events_csv is not None:
297
+ self._events = _open_private(self.events_csv)
298
+ self._events_writer, self._events_done = _csv_writer(
299
+ self._events, EVENT_COLUMNS, ("run_id", "order")
300
+ )
301
+ if self.gates and self.output_csv is not None:
302
+ self._csv = _open_private(self.output_csv)
303
+ self._writer, self._done = _csv_writer(
304
+ self._csv, CSV_COLUMNS, ("run_id", "order", "gate_id")
305
+ )
306
+ if self.normalized_path is not None:
307
+ self._normalized = _open_private(self.normalized_path)
308
+ self._normalized_done = _existing_events(self._normalized)
309
+
310
+ def _close(self) -> None:
311
+ self._trace.close()
312
+ if self._payloads is not None:
313
+ self._payloads.close()
314
+ for stream in (self._csv, self._events, self._normalized):
315
+ if stream is not None:
316
+ stream.close()
317
+ self._csv = self._events = self._normalized = None
318
+ self._writer = self._events_writer = None
319
+ if self.store is not None:
320
+ self.store.close()
321
+
322
+ def _save_events(self, *, final: bool) -> None:
323
+ """Save waiting events in one store transaction; keep them for a retry if that fails."""
324
+ if self.store is None or not self._unsaved:
325
+ return
326
+ try:
327
+ self.store.save(self._unsaved)
328
+ except OSError as error:
329
+ if final:
330
+ raise
331
+ if not self._store_failing:
332
+ log.warning("agent-latch-runtime: %s; retrying", error)
333
+ self._store_failing = True
334
+ return
335
+ if self._store_failing:
336
+ log.warning(
337
+ "agent-latch-runtime: database reachable again; saved %d waiting event(s)",
338
+ len(self._unsaved),
339
+ )
340
+ self._store_failing = False
341
+ self._unsaved = []
342
+
343
+ def _ingest(self) -> bool:
344
+ progressed = False
345
+ for line_no, text in self._trace.read():
346
+ progressed = True
347
+ record = _parse(text)
348
+ if not is_trace_record(record):
349
+ if text.strip():
350
+ log.warning("agent-latch-runtime: skipping trace line %d (not a record)", line_no)
351
+ continue
352
+ if self._normalizer is None:
353
+ self._run_id = self._run_id or run_id_for(text)
354
+ self._normalizer = MCPEventNormalizer(
355
+ self._run_id,
356
+ trace_name=self.trace_path.name,
357
+ payloads_name=self.payloads_path.name if self.payloads_path else None,
358
+ )
359
+ self._pending.append((line_no, record, time.monotonic()))
360
+ if self._payloads is not None:
361
+ for line_no, text in self._payloads.read():
362
+ progressed = True
363
+ record = _parse(text)
364
+ if not is_payload_record(record):
365
+ if text.strip():
366
+ log.warning(
367
+ "agent-latch-runtime: skipping payload line %d (not a record)", line_no
368
+ )
369
+ continue
370
+ self._queues.setdefault(payload_key(record), deque()).append((line_no, record))
371
+ return progressed
372
+
373
+ def _drain(self, *, final: bool) -> bool:
374
+ progressed = False
375
+ while self._pending:
376
+ line_no, trace, arrived = self._pending[0]
377
+ payload_line, payload = None, None
378
+ if self._payloads is not None and trace["method"] in PAYLOAD_METHODS:
379
+ key = trace_key(trace)
380
+ queue = self._queues.get(key)
381
+ if queue:
382
+ payload_line, payload = queue.popleft()
383
+ if not queue:
384
+ del self._queues[key]
385
+ elif not final and not (
386
+ self.follow and time.monotonic() - arrived > self.payload_grace
387
+ ):
388
+ break
389
+ self._pending.popleft()
390
+ self._emit(line_no, trace, payload_line, payload)
391
+ progressed = True
392
+ return progressed
393
+
394
+ def _emit(
395
+ self,
396
+ line_no: int,
397
+ trace: dict[str, Any],
398
+ payload_line: int | None,
399
+ payload: dict[str, Any] | None,
400
+ ) -> None:
401
+ assert self._normalizer is not None
402
+ event = self._normalizer.normalize(
403
+ trace_line=line_no, trace=trace, payload_line=payload_line, payload=payload
404
+ )
405
+ run_id, order = event["run_id"], str(event["order"])
406
+ # Only events new to some output are summarized, so a restart does not repeat old lines.
407
+ fresh = not (self._events or self._csv or self._normalized)
408
+ if self._normalized is not None and (run_id, order) not in self._normalized_done:
409
+ self._normalized.write(json.dumps(event, ensure_ascii=False) + "\n")
410
+ self._normalized.flush()
411
+ fresh = True
412
+ if (
413
+ self._events is not None
414
+ and self._events_writer is not None
415
+ and (run_id, order) not in self._events_done
416
+ ):
417
+ self._events_writer.writerow(_event_row(event))
418
+ self._events.flush()
419
+ fresh = True
420
+ if self.store is not None:
421
+ self._unsaved.append(copy.deepcopy(event)) # saved at the end of this pass
422
+ findings = errors = 0
423
+ if self._csv is not None and self._writer is not None:
424
+ for gate in self.gates:
425
+ if (run_id, order, gate.gate_id) in self._done:
426
+ continue
427
+ result = _evaluate(gate, event)
428
+ findings += len(result["findings"])
429
+ errors += result["status"] == "error"
430
+ self._writer.writerow({
431
+ "run_id": run_id,
432
+ "order": order,
433
+ "gate_id": gate.gate_id,
434
+ "result_json": json.dumps(result, ensure_ascii=False, separators=(",", ":")),
435
+ })
436
+ self._csv.flush()
437
+ fresh = True
438
+ if self.summary is not None and fresh:
439
+ line = f"#{order} {event['server']}: {summarize_record(trace)}"
440
+ if event["payload"] is not None:
441
+ line += " [payload]"
442
+ if self._csv is not None:
443
+ line += f" | gates: {findings} finding(s)"
444
+ if errors:
445
+ line += f", {errors} error(s)"
446
+ self.summary.write(f"agent-latch-runtime: {line}\n")
447
+ self.summary.flush()
448
+
449
+
450
+ def _csv_writer(
451
+ output: TextIO, columns: tuple[str, ...], key: tuple[str, ...]
452
+ ) -> tuple[csv.DictWriter[str], set[tuple[str, ...]]]:
453
+ """Writer appending to ``output`` (header written if empty) and the keys already in it."""
454
+ output.seek(0)
455
+ if not output.readline():
456
+ writer = csv.DictWriter(output, fieldnames=columns)
457
+ writer.writeheader()
458
+ output.flush()
459
+ return writer, set()
460
+ output.seek(0)
461
+ reader = csv.DictReader(output)
462
+ if tuple(reader.fieldnames or ()) != columns:
463
+ raise ValueError(
464
+ f"CSV header must be {','.join(columns)}; found {','.join(reader.fieldnames or ())}"
465
+ )
466
+ done = {tuple(row[field] for field in key) for row in reader}
467
+ output.seek(0, 2)
468
+ return csv.DictWriter(output, fieldnames=columns), done
469
+
470
+
471
+ def _cell(value: Any) -> str:
472
+ """CSV cell text; values from MCP traffic must not run as spreadsheet formulas."""
473
+ if value is None:
474
+ return ""
475
+ text = value if isinstance(value, str) else str(value)
476
+ return "'" + text if text.startswith(_FORMULA_START) else text
477
+
478
+
479
+ def _event_row(event: Mapping[str, Any]) -> dict[str, str]:
480
+ meta = event["metadata"]
481
+ stage = event["stage"]
482
+ if stage == "error":
483
+ outcome = f"error ({meta.get('error_type')})" if meta.get("error_type") else "error"
484
+ elif meta.get("is_error") is True:
485
+ outcome = "error result"
486
+ elif stage == "response":
487
+ outcome = "ok"
488
+ else:
489
+ outcome = ""
490
+ return {
491
+ "run_id": _cell(event["run_id"]),
492
+ "order": _cell(event["order"]),
493
+ "timestamp": _cell(event["timestamp"]),
494
+ "session_id": _cell(event["session_id"]),
495
+ "request_id": _cell(event["request_id"]),
496
+ "server": _cell(event["server"]),
497
+ "method": _cell(event["method"]),
498
+ "stage": _cell(stage),
499
+ "name": _cell(event["name"]),
500
+ "outcome": outcome,
501
+ "duration_ms": _cell(meta.get("duration_ms")),
502
+ "output_bytes": _cell(meta.get("output_bytes")),
503
+ "has_payload": "yes" if event["payload"] is not None else "no",
504
+ "excerpt": _cell(meta.get("excerpt")),
505
+ }
506
+
507
+
508
+ def _existing_events(stream: TextIO) -> set[tuple[str, str]]:
509
+ stream.seek(0)
510
+ seen: set[tuple[str, str]] = set()
511
+ for line in stream:
512
+ record = _parse(line)
513
+ if isinstance(record, dict) and "run_id" in record and "order" in record:
514
+ seen.add((str(record["run_id"]), str(record["order"])))
515
+ stream.seek(0, 2)
516
+ return seen
517
+
518
+
519
+ def _evaluate(gate: Gate, event: dict[str, Any]) -> dict[str, Any]:
520
+ try:
521
+ gate_result = gate.evaluate(copy.deepcopy(event))
522
+ if not isinstance(gate_result, Mapping):
523
+ raise TypeError("evaluate(event) must return a JSON object")
524
+ findings = gate_result.get("findings")
525
+ if not isinstance(findings, list):
526
+ raise TypeError("evaluate(event) result must contain a findings list")
527
+ result: dict[str, Any] = {
528
+ "gate_id": gate.gate_id,
529
+ "status": "ok",
530
+ "findings": findings,
531
+ "error": None,
532
+ }
533
+ return json.loads(json.dumps(result, ensure_ascii=False, allow_nan=False))
534
+ except Exception as error: # noqa: BLE001 - one gate failure must not stop later gates
535
+ log.warning(
536
+ "agent-latch-runtime: gate %r failed (%s)", gate.gate_id, type(error).__name__
537
+ )
538
+ return {
539
+ "gate_id": gate.gate_id,
540
+ "status": "error",
541
+ "findings": [],
542
+ "error": {"type": type(error).__name__},
543
+ }