Download agent_security_engine.py from Moronto/agent-security-service: direct link, hf CLI and curl.
- Browser
- Download file 14.5 kB
-
https://huggingface.co/spaces/Moronto/agent-security-service/resolve/main/agent_security_engine.py
- Command line
-
hf download hf://spaces/Moronto/agent-security-service/agent_security_engine.py
-
curl -L -o agent_security_engine.py https://huggingface.co/spaces/Moronto/agent-security-service/resolve/main/agent_security_engine.py
14.5 kB
| """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|>", | |
| "<<SYS>>", | |
| ) | |
| 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) | |
| 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, | |
| ) | |
| 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) | |
| 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, | |
| ) | |
| 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, | |
| ) | |
| 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() | |