"""4-Layer AI Agent Security Engine (L1 Ingress, L2 Origin/Drift + HMAC Session Chain, L3 PreToolUse, L4 Correlation).""" from __future__ import annotations from dataclasses import asdict, dataclass, field from difflib import SequenceMatcher import hashlib import hmac import json import os from pathlib import PurePath import re import sqlite3 import time import unicodedata import uuid from typing import Any, Literal OriginType = Literal["system", "user_turn", "trusted_tool", "untrusted_metadata"] SideEffectScope = Literal["read", "write", "execute", "network"] # Secret used for L2 cryptographic session tags (override via AGENT_SESSION_SECRET in prod) _SESSION_SECRET = os.environ.get("AGENT_SESSION_SECRET", "shadowspark-dev-hmac-secret-2026").encode("utf-8") PROMPT_DELIMITERS: tuple[str, ...] = ( "###", "[INST]", "[/INST]", "<|im_start|>", "<|im_end|>", "<|system|>", "<>", ) PROTECTED_BASENAMES: frozenset[str] = frozenset({ ".env", ".env.local", ".env.production", "claude.md", "soul.md", "agents.md", ".claude.json", "secrets.odt", "id_rsa", "id_ed25519", }) # Tool-to-side-effect default mapping (Failure Mode 2: bind approval by side effect, not command name alone) TOOL_SIDE_EFFECTS: dict[str, SideEffectScope] = { "read_file": "read", "list_dir": "read", "search": "read", "write_file": "write", "edit_file": "write", "delete_file": "write", "run_command": "execute", "bash": "execute", "exec": "execute", "http_request": "network", "webhook": "network", } ORIGIN_POLICY_MATRIX: dict[OriginType, frozenset[SideEffectScope]] = { "system": frozenset({"read", "write", "execute", "network"}), "user_turn": frozenset({"read", "write", "execute"}), "trusted_tool": frozenset({"read", "write"}), "untrusted_metadata": frozenset(), } _INSTRUCTION_VERBS_RE = re.compile( r"\b(ignore\s+previous|disregard|system\s+prompt|override|execute|run\s+command|curl\s+|wget\s+|rm\s+-rf)\b", re.IGNORECASE, ) def _is_hidden_unicode(ch: str) -> bool: cp = ord(ch) if unicodedata.category(ch) == "Cf": return True return ( 0x200B <= cp <= 0x200F or 0x202A <= cp <= 0x202E or 0x2060 <= cp <= 0x206F or cp == 0xFEFF or 0xE0000 <= cp <= 0xE007F ) def _is_c0_c1_control(ch: str) -> bool: cp = ord(ch) if ch in ("\t", "\n", "\r"): return False return cp < 0x20 or (0x7F <= cp <= 0x9F) @dataclass(frozen=True) class IngressResult: valid: bool sanitized_text: str stripped_unicode_count: int violations: list[str] def to_dict(self) -> dict[str, Any]: return asdict(self) def validate_ingress(text: str) -> IngressResult: """L1 Ingress Filtering (§89): strip hidden Unicode, reject C0/C1 control chars and prompt delimiters.""" violations: list[str] = [] if any(_is_c0_c1_control(c) for c in text): violations.append("L1_C0_C1_CONTROL_CHAR") stripped_chars: list[str] = [] stripped_count = 0 for ch in text: if _is_hidden_unicode(ch): stripped_count += 1 elif not _is_c0_c1_control(ch): stripped_chars.append(ch) sanitized = "".join(stripped_chars) for delim in PROMPT_DELIMITERS: if delim in sanitized: violations.append(f"L1_PROMPT_DELIMITER:{delim}") return IngressResult( valid=len(violations) == 0, sanitized_text=sanitized, stripped_unicode_count=stripped_count, violations=violations, ) @dataclass(frozen=True) class OriginRecord: """L2 Immutable Origin Record (§93, §95) hardened with HMAC-SHA256 multi-turn session chaining.""" origin_id: str origin_type: OriginType session_id: str turn_index: int content_hash: str prev_tag: str timestamp: float hmac_tag: str def to_dict(self) -> dict[str, Any]: return asdict(self) def _compute_hmac_tag( session_id: str, turn_index: int, origin_type: OriginType, content_hash: str, prev_tag: str, ) -> str: payload = f"{session_id}:{turn_index}:{origin_type}:{content_hash}:{prev_tag}".encode("utf-8") return hmac.new(_SESSION_SECRET, payload, hashlib.sha256).hexdigest() def create_origin_record( sanitized_text: str, origin_type: OriginType = "user_turn", session_id: str = "default-session", turn_index: int = 0, prev_tag: str = "GENESIS", ) -> OriginRecord: content_hash = hashlib.sha256(sanitized_text.encode("utf-8")).hexdigest() tag = _compute_hmac_tag(session_id, turn_index, origin_type, content_hash, prev_tag) return OriginRecord( origin_id=f"org-{uuid.uuid4().hex[:12]}", origin_type=origin_type, session_id=session_id, turn_index=turn_index, content_hash=content_hash, prev_tag=prev_tag, timestamp=time.time(), hmac_tag=tag, ) def verify_origin_record( record: OriginRecord, sanitized_text: str | None = None, expected_prev_tag: str | None = None, ) -> tuple[bool, list[str]]: """Verify HMAC tag, optional payload hash, and multi-turn chain link.""" errors: list[str] = [] if sanitized_text is not None: actual_hash = hashlib.sha256(sanitized_text.encode("utf-8")).hexdigest() if not hmac.compare_digest(actual_hash, record.content_hash): errors.append("L2_CONTENT_HASH_MISMATCH") if expected_prev_tag is not None and not hmac.compare_digest(expected_prev_tag, record.prev_tag): errors.append("L2_SESSION_CHAIN_BROKEN") expected_hmac = _compute_hmac_tag( record.session_id, record.turn_index, record.origin_type, record.content_hash, record.prev_tag, ) if not hmac.compare_digest(expected_hmac, record.hmac_tag): errors.append("L2_HMAC_SIGNATURE_INVALID") return (len(errors) == 0, errors) @dataclass(frozen=True) class DriftMetrics: token_drift_ratio: float sequence_drift_ratio: float added_tokens: list[str] removed_tokens: list[str] exceeds_threshold: bool def to_dict(self) -> dict[str, Any]: return asdict(self) def _tokenize(text: str) -> list[str]: return re.findall(r"\w+|[^\w\s]", text.lower()) def compute_prompt_drift(baseline: str, candidate: str, threshold: float = 0.15) -> DriftMetrics: """L2 Baseline Drift Monitor (§95): token-level diff metrics.""" base_tokens = _tokenize(baseline) cand_tokens = _tokenize(candidate) if not base_tokens and not cand_tokens: return DriftMetrics(0.0, 0.0, [], [], False) matcher = SequenceMatcher(None, base_tokens, cand_tokens) seq_drift = round(1.0 - matcher.ratio(), 4) added: list[str] = [] removed: list[str] = [] for tag, i1, i2, j1, j2 in matcher.get_opcodes(): if tag in ("replace", "delete"): removed.extend(base_tokens[i1:i2]) if tag in ("replace", "insert"): added.extend(cand_tokens[j1:j2]) total = max(len(base_tokens), len(cand_tokens), 1) token_drift = round((len(added) + len(removed)) / (2 * total), 4) drift = max(seq_drift, token_drift) return DriftMetrics( token_drift_ratio=token_drift, sequence_drift_ratio=seq_drift, added_tokens=added[:25], removed_tokens=removed[:25], exceeds_threshold=drift > threshold, ) @dataclass(frozen=True) class DispatchDecision: allowed: bool tool_name: str inferred_side_effect: SideEffectScope origin_type: OriginType reasons: list[str] def to_dict(self) -> dict[str, Any]: return asdict(self) def _references_protected_file(args: dict[str, Any]) -> str | None: for val in args.values(): if not isinstance(val, str): continue for token in re.split(r"[\s;|&><'\"]+", val): if not token: continue name = PurePath(token).name.lower() if name in PROTECTED_BASENAMES or name.startswith(".env."): return name if "/.ssh/" in token.replace("\\", "/") or token.endswith(".pem"): return token return None def evaluate_dispatch( tool_name: str, tool_args: dict[str, Any], origin_record: OriginRecord, side_effect: SideEffectScope | None = None, verify_hmac: bool = True, ) -> DispatchDecision: """L3 PreToolUse Hook Enforcement (§90, §93.2): origin matrix, side-effect binding, protected file guard.""" reasons: list[str] = [] effective_scope: SideEffectScope = side_effect or TOOL_SIDE_EFFECTS.get(tool_name, "execute") if verify_hmac: ok, hmac_errors = verify_origin_record(origin_record) if not ok: reasons.extend(hmac_errors) allowed_scopes = ORIGIN_POLICY_MATRIX.get(origin_record.origin_type, frozenset()) if effective_scope not in allowed_scopes: reasons.append( f"L3_ORIGIN_POLICY_DENIED:origin={origin_record.origin_type},side_effect={effective_scope}" ) protected = _references_protected_file(tool_args) if protected is not None: reasons.append(f"L3_PROTECTED_FILE_ACCESS:{protected}") # Side-effect escalation check: read tool smuggled with shell/write flags or traversal for val in tool_args.values(): if isinstance(val, str) and ("../" in val or "..\\" in val): reasons.append("L3_PATH_TRAVERSAL_DETECTED") break return DispatchDecision( allowed=len(reasons) == 0, tool_name=tool_name, inferred_side_effect=effective_scope, origin_type=origin_record.origin_type, reasons=reasons, ) @dataclass class SessionState: last_tag: str = "GENESIS" turn_count: int = 0 cumulative_drift: float = 0.0 l3_denials: int = 0 anomalies: list[str] = field(default_factory=list) class SessionCorrelator: """L4 Asynchronous Correlation (§92): SQLite-persisted cross-turn ladder & metadata anomaly detector.""" def __init__( self, drift_ceiling: float = 0.35, max_denials: int = 2, db_path: str | None = None, ) -> None: self.drift_ceiling = drift_ceiling self.max_denials = max_denials self.db_path = db_path or os.environ.get("AGENT_SESSION_DB", "/tmp/agent_security_sessions.db") self._init_db() def _connect(self) -> sqlite3.Connection: conn = sqlite3.connect(self.db_path, timeout=5.0) conn.execute("PRAGMA journal_mode=WAL") return conn def _init_db(self) -> None: with self._connect() as conn: conn.execute( """ CREATE TABLE IF NOT EXISTS session_state ( session_id TEXT PRIMARY KEY, last_tag TEXT NOT NULL, turn_count INTEGER NOT NULL, cumulative_drift REAL NOT NULL, l3_denials INTEGER NOT NULL, anomalies_json TEXT NOT NULL ) """ ) def get_session(self, session_id: str) -> SessionState: with self._connect() as conn: row = conn.execute( "SELECT last_tag, turn_count, cumulative_drift, l3_denials, anomalies_json " "FROM session_state WHERE session_id = ?", (session_id,), ).fetchone() if row is None: state = SessionState() self._save_session(session_id, state) return state return SessionState( last_tag=row[0], turn_count=int(row[1]), cumulative_drift=float(row[2]), l3_denials=int(row[3]), anomalies=json.loads(row[4]), ) def _save_session(self, session_id: str, state: SessionState) -> None: with self._connect() as conn: conn.execute( """ INSERT INTO session_state ( session_id, last_tag, turn_count, cumulative_drift, l3_denials, anomalies_json ) VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(session_id) DO UPDATE SET last_tag = excluded.last_tag, turn_count = excluded.turn_count, cumulative_drift = excluded.cumulative_drift, l3_denials = excluded.l3_denials, anomalies_json = excluded.anomalies_json """, ( session_id, state.last_tag, state.turn_count, state.cumulative_drift, state.l3_denials, json.dumps(state.anomalies), ), ) def record_turn( self, origin: OriginRecord, raw_text: str, drift_delta: float = 0.0, dispatch_decision: DispatchDecision | None = None, ) -> dict[str, Any]: state = self.get_session(origin.session_id) turn_anomalies: list[str] = [] chain_ok, chain_errs = verify_origin_record(origin, expected_prev_tag=state.last_tag) if not chain_ok: turn_anomalies.extend(chain_errs) if origin.origin_type == "untrusted_metadata" and _INSTRUCTION_VERBS_RE.search(raw_text): turn_anomalies.append("L4_METADATA_INSTRUCTION_LEAK") state.cumulative_drift = round(state.cumulative_drift + drift_delta, 4) if state.cumulative_drift > self.drift_ceiling: turn_anomalies.append(f"L4_CUMULATIVE_DRIFT_EXCEEDED:{state.cumulative_drift}") if dispatch_decision and not dispatch_decision.allowed: state.l3_denials += 1 if state.l3_denials >= self.max_denials: turn_anomalies.append(f"L4_REPEATED_DISPATCH_DENIALS:{state.l3_denials}") if chain_ok: state.last_tag = origin.hmac_tag state.turn_count += 1 state.anomalies.extend(turn_anomalies) self._save_session(origin.session_id, state) return { "session_id": origin.session_id, "turn_count": state.turn_count, "last_hmac_tag": state.last_tag, "cumulative_drift": state.cumulative_drift, "l3_denials": state.l3_denials, "turn_anomalies": turn_anomalies, "halted": len(turn_anomalies) > 0, } GLOBAL_CORRELATOR = SessionCorrelator()