prooflayer-runtime 0.1.0__py3-none-any.whl

prooflayer/detection/models.py

@@ -0,0 +1,49 @@
+"""Detection models and dataclasses."""
+
+import re
+import logging
+from typing import Optional, List, Dict, Any, Iterator
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DetectionRule:
+    """A single detection rule."""
+    id: str
+    severity: str  # "low", "medium", "high", "critical"
+    message: str
+    pattern: str
+    score: int
+    category: str
+    owasp: list = field(default_factory=list)
+    compiled_pattern: Optional[re.Pattern] = None
+
+    def __post_init__(self):
+        """Compile the regex pattern after initialization."""
+        try:
+            self.compiled_pattern = re.compile(self.pattern, re.IGNORECASE | re.DOTALL)
+        except re.error as e:
+            logger.warning(f"Failed to compile pattern for rule {self.id}: {e}")
+            self.compiled_pattern = None
+
+
+@dataclass
+class ScanResult:
+    """Result of a detection engine scan."""
+    score: int
+    level: str  # "SAFE", "SUSPICIOUS", "THREAT"
+    action: str  # "ALLOW", "WARN", "BLOCK"
+    matched_rules: List[DetectionRule] = field(default_factory=list)
+    scoring_breakdown: Dict[str, int] = field(default_factory=dict)
+    tool_name: str = ""
+    arguments: Dict[str, Any] = field(default_factory=dict)
+    timestamp: str = ""
+    latency_ms: float = 0.0
+    owasp_mapping: List[str] = field(default_factory=list)
+
+    def __iter__(self) -> Iterator[Any]:
+        """Backwards compatibility: allows `score, rules = engine.scan(...)`."""
+        yield self.score
+        yield self.matched_rules

prooflayer/detection/normalizer.py

@@ -0,0 +1,245 @@
+"""
+Input Normalization and Decoding Layer
+=======================================
+
+Pre-processes input text before regex matching to defeat evasion techniques:
+- Case normalization
+- Unicode homoglyph normalization
+- Encoding decoding (hex, octal, unicode, URL, base64)
+- Whitespace normalization
+- Nested object flattening
+"""
+
+import re
+import base64
+import logging
+import unicodedata
+from typing import Any, Dict, List
+
+logger = logging.getLogger(__name__)
+
+# Mapping of common Unicode homoglyphs (Cyrillic and other lookalikes) to ASCII.
+# This catches attackers substituting visually-similar characters to evade regex.
+HOMOGLYPH_MAP = {
+    # Cyrillic → Latin
+    "\u0410": "A",  # А
+    "\u0412": "B",  # В
+    "\u0421": "C",  # С
+    "\u0415": "E",  # Е
+    "\u041d": "H",  # Н
+    "\u041a": "K",  # К
+    "\u041c": "M",  # М
+    "\u041e": "O",  # О
+    "\u0420": "P",  # Р
+    "\u0422": "T",  # Т
+    "\u0425": "X",  # Х
+    "\u0430": "a",  # а
+    "\u0435": "e",  # е
+    "\u043e": "o",  # о
+    "\u0440": "p",  # р
+    "\u0441": "c",  # с
+    "\u0443": "y",  # у
+    "\u0445": "x",  # х
+    "\u0455": "s",  # ѕ (Cyrillic small letter dze)
+    "\u0456": "i",  # і (Cyrillic small letter byelorussian-ukrainian i)
+    "\u0458": "j",  # ј
+    "\u04bb": "h",  # һ
+    "\u04c0": "l",  # Ӏ (Cyrillic letter palochka)
+    # Greek → Latin
+    "\u0391": "A",  # Α
+    "\u0392": "B",  # Β
+    "\u0395": "E",  # Ε
+    "\u0397": "H",  # Η
+    "\u0399": "I",  # Ι
+    "\u039a": "K",  # Κ
+    "\u039c": "M",  # Μ
+    "\u039d": "N",  # Ν
+    "\u039f": "O",  # Ο
+    "\u03a1": "P",  # Ρ
+    "\u03a4": "T",  # Τ
+    "\u03a5": "Y",  # Υ
+    "\u03a7": "X",  # Χ
+    "\u03b1": "a",  # α (only when used as lookalike)
+    "\u03bf": "o",  # ο
+    # Fullwidth → ASCII
+    "\uff21": "A",
+    "\uff22": "B",
+    "\uff23": "C",
+    "\uff24": "D",
+    "\uff25": "E",
+    "\uff26": "F",
+    "\uff27": "G",
+    "\uff28": "H",
+    "\uff29": "I",
+    "\uff2a": "J",
+    "\uff2b": "K",
+    "\uff2c": "L",
+    "\uff2d": "M",
+    "\uff2e": "N",
+    "\uff2f": "O",
+    "\uff30": "P",
+    "\uff31": "Q",
+    "\uff32": "R",
+    "\uff33": "S",
+    "\uff34": "T",
+    "\uff35": "U",
+    "\uff36": "V",
+    "\uff37": "W",
+    "\uff38": "X",
+    "\uff39": "Y",
+    "\uff3a": "Z",
+    "\uff41": "a",
+    "\uff42": "b",
+    "\uff43": "c",
+    "\uff44": "d",
+    "\uff45": "e",
+    "\uff46": "f",
+    "\uff47": "g",
+    "\uff48": "h",
+    "\uff49": "i",
+    "\uff4a": "j",
+    "\uff4b": "k",
+    "\uff4c": "l",
+    "\uff4d": "m",
+    "\uff4e": "n",
+    "\uff4f": "o",
+    "\uff50": "p",
+    "\uff51": "q",
+    "\uff52": "r",
+    "\uff53": "s",
+    "\uff54": "t",
+    "\uff55": "u",
+    "\uff56": "v",
+    "\uff57": "w",
+    "\uff58": "x",
+    "\uff59": "y",
+    "\uff5a": "z",
+}
+
+# Import decode functions from encoding module (shared with utils.encoding)
+from ..utils.encoding import (
+    HEX_ESCAPE_RE as _HEX_ESCAPE_RE,
+    OCTAL_ESCAPE_RE as _OCTAL_ESCAPE_RE,
+    UNICODE_ESCAPE_RE as _UNICODE_ESCAPE_RE,
+    URL_ENCODE_RE as _URL_ENCODE_RE,
+    BASE64_RE as _BASE64_RE,
+    decode_hex_escapes,
+    decode_octal_escapes,
+    decode_unicode_escapes,
+    decode_url_encoding,
+    decode_base64_payloads,
+)
+
+_WHITESPACE_RE = re.compile(r"[\s\t\n\r]+")
+
+# Zero-width and bidirectional override characters to strip
+_ZERO_WIDTH_RE = re.compile(
+    "[\u200b\u200c\u200d\u2060\ufeff"  # ZWS, ZWNJ, ZWJ, word joiner, BOM
+    "\u202a\u202b\u202c\u202d\u202e"   # bidi overrides
+    "]+"
+)
+
+
+def strip_zero_width(text: str) -> str:
+    """Strip zero-width characters and bidi overrides."""
+    return _ZERO_WIDTH_RE.sub("", text)
+
+
+def normalize_path(text: str) -> str:
+    """
+    Normalize path-like sequences in text.
+
+    Resolves /./  → /
+    Resolves //   → /
+    Strips trailing slashes from path-like segments.
+    Does NOT resolve ../ (that changes semantics).
+    """
+    # Resolve /./  → /
+    text = re.sub(r"/\./", "/", text)
+    # Resolve //   → /  (but preserve protocol://)
+    text = re.sub(r"(?<!:)//+", "/", text)
+    # Strip trailing slashes from path-like segments (but not standalone /)
+    text = re.sub(r"(/[a-zA-Z0-9._-]+)/+(?=\s|$)", r"\1", text)
+    return text
+
+
+def normalize_unicode(text: str) -> str:
+    """
+    Normalize Unicode homoglyphs to ASCII equivalents.
+
+    Uses NFKD decomposition first (handles fullwidth, compatibility forms),
+    then applies explicit homoglyph mapping for Cyrillic/Greek lookalikes.
+    """
+    # NFKD normalization decomposes compatibility characters
+    text = unicodedata.normalize("NFKD", text)
+
+    # Apply homoglyph mapping for characters that survive NFKD
+    result = []
+    for char in text:
+        if char in HOMOGLYPH_MAP:
+            result.append(HOMOGLYPH_MAP[char])
+        else:
+            result.append(char)
+
+    return "".join(result)
+
+
+def normalize_whitespace(text: str) -> str:
+    """Normalize tabs, newlines, and multiple spaces to single spaces."""
+    return _WHITESPACE_RE.sub(" ", text).strip()
+
+
+def flatten_value(value: Any) -> List[str]:
+    """
+    Recursively extract all string values from nested dicts/lists.
+
+    Instead of str() which produces Python repr format (e.g. "{'key': 'value'}"),
+    this extracts the actual string values for proper pattern matching.
+    """
+    strings = []
+    if isinstance(value, str):
+        strings.append(value)
+    elif isinstance(value, dict):
+        for v in value.values():
+            strings.extend(flatten_value(v))
+    elif isinstance(value, (list, tuple)):
+        for item in value:
+            strings.extend(flatten_value(item))
+    elif value is not None:
+        strings.append(str(value))
+    return strings
+
+
+def flatten_arguments(arguments: Dict[str, Any]) -> Dict[str, List[str]]:
+    """
+    Flatten all argument values, returning a mapping of param name
+    to list of extracted string values.
+    """
+    result = {}
+    for key, value in arguments.items():
+        result[key] = flatten_value(value)
+    return result
+
+
+def normalize_text(text: str) -> str:
+    """
+    Apply the full normalization pipeline to a single text string.
+
+    Order matters:
+    1. Base64 decoding (FIRST — base64 is case-sensitive, must decode before lowering)
+    2. Unicode homoglyph normalization (before lowering, to map correctly)
+    3. Encoding decoding (hex, octal, unicode, URL)
+    4. Case normalization (lowercase)
+    5. Whitespace normalization
+    """
+    text = strip_zero_width(text)
+    text = decode_base64_payloads(text)
+    text = normalize_unicode(text)
+    text = decode_hex_escapes(text)
+    text = decode_octal_escapes(text)
+    text = decode_unicode_escapes(text)
+    text = decode_url_encoding(text)
+    text = normalize_path(text)
+    text = text.lower()
+    text = normalize_whitespace(text)
+    return text

prooflayer/detection/rules.py

@@ -0,0 +1,104 @@
+"""Rule loader for YAML detection rules."""
+
+import yaml  # type: ignore[import-untyped]
+import logging
+from pathlib import Path
+from typing import List
+
+from .models import DetectionRule
+
+logger = logging.getLogger(__name__)
+
+
+class RuleLoadError(Exception):
+    """Raised when detection rules fail to load. This is a security-critical error."""
+    pass
+
+
+class RuleLoader:
+    """Load detection rules from YAML files."""
+
+    @staticmethod
+    def load_from_directory(rules_dir: str) -> List[DetectionRule]:
+        """
+        Load all YAML rule files from directory.
+
+        Args:
+            rules_dir: Directory containing YAML rule files
+
+        Returns:
+            List of DetectionRule objects
+
+        Raises:
+            RuleLoadError: If the directory does not exist or no rules are loaded
+        """
+        rules = []
+        rules_path = Path(rules_dir)
+        load_errors = []
+
+        if not rules_path.exists():
+            raise RuleLoadError(
+                f"Rules directory not found: {rules_dir}. "
+                "ProofLayer cannot start without detection rules."
+            )
+
+        for yaml_file in rules_path.glob("*.yaml"):
+            try:
+                file_rules = RuleLoader.load_from_file(str(yaml_file))
+                rules.extend(file_rules)
+                logger.info(f"Loaded {len(file_rules)} rules from {yaml_file.name}")
+            except Exception as e:
+                load_errors.append(f"{yaml_file}: {e}")
+                logger.error(f"Failed to load rules from {yaml_file}: {e}")
+
+        if not rules:
+            error_detail = ""
+            if load_errors:
+                error_detail = " Errors: " + "; ".join(load_errors)
+            raise RuleLoadError(
+                f"No detection rules loaded from {rules_dir}.{error_detail} "
+                "ProofLayer cannot start without detection rules."
+            )
+
+        if load_errors:
+            logger.warning(
+                f"Some rule files failed to load ({len(load_errors)} errors), "
+                f"but {len(rules)} rules were loaded successfully."
+            )
+
+        return rules
+
+    @staticmethod
+    def load_from_file(file_path: str) -> List[DetectionRule]:
+        """
+        Load detection rules from a single YAML file.
+
+        Args:
+            file_path: Path to YAML file
+
+        Returns:
+            List of DetectionRule objects
+        """
+        with open(file_path, "r") as f:
+            data = yaml.safe_load(f)
+
+        if not data or "rules" not in data:
+            return []
+
+        rules = []
+        for rule_data in data["rules"]:
+            try:
+                rule = DetectionRule(
+                    id=rule_data["id"],
+                    severity=rule_data.get("severity", "medium"),
+                    message=rule_data["message"],
+                    pattern=rule_data["pattern"],
+                    score=rule_data.get("score", 10),
+                    category=rule_data.get("category", "unknown"),
+                    owasp=rule_data.get("owasp", [])
+                )
+                rules.append(rule)
+            except KeyError as e:
+                logger.warning(f"Skipping invalid rule in {file_path}: missing {e}")
+
+        return rules

prooflayer/detection/scanner.py

@@ -0,0 +1,160 @@
+"""
+Pattern Scanner
+===============
+
+Regex-based pattern matching with ReDoS protection for threat detection.
+"""
+
+import logging
+import threading
+from typing import List, Set, Tuple
+
+from .models import DetectionRule
+
+logger = logging.getLogger(__name__)
+
+# ReDoS protection constants
+REGEX_TIMEOUT_SECONDS = 0.1  # 100ms
+REGEX_CIRCUIT_BREAKER_THRESHOLD = 3
+
+
+class PatternScanner:
+    """
+    Scans text against detection rules using regex with ReDoS protection.
+
+    Each regex match runs in a daemon thread with a timeout. A circuit breaker
+    trips after consecutive timeouts to block suspicious requests.
+    """
+
+    def match_rule(
+        self, rule: DetectionRule, text: str
+    ) -> Tuple[bool, bool]:
+        """
+        Match a single rule against text with ReDoS protection.
+
+        Args:
+            rule: Detection rule with a compiled regex pattern.
+            text: Text to scan.
+
+        Returns:
+            (matched, timed_out)
+        """
+        if not rule.compiled_pattern:
+            return False, False
+
+        matched_flag = [None]
+
+        def _search():
+            matched_flag[0] = rule.compiled_pattern.search(text) is not None
+
+        t = threading.Thread(target=_search, daemon=True)
+        t.start()
+        t.join(timeout=REGEX_TIMEOUT_SECONDS)
+
+        if t.is_alive():
+            return False, True  # timed out
+
+        return bool(matched_flag[0]), False
+
+    def scan_text(
+        self,
+        rules: List[DetectionRule],
+        text: str,
+        consecutive_timeouts: int,
+        lock: threading.Lock,
+    ) -> Tuple[List[DetectionRule], int, Set[str], int]:
+        """
+        Scan text against all rules.
+
+        Args:
+            rules: List of detection rules to match.
+            text: Normalized search text.
+            consecutive_timeouts: Current consecutive timeout count.
+            lock: Threading lock for timeout counter.
+
+        Returns:
+            (matched_rules, pattern_score, matched_rule_ids, updated_consecutive_timeouts)
+            Returns None for the first element if the circuit breaker tripped.
+        """
+        matched_rules: List[DetectionRule] = []
+        pattern_score = 0
+        matched_rule_ids: Set[str] = set()
+
+        for rule in rules:
+            matched, timed_out = self.match_rule(rule, text)
+            if timed_out:
+                with lock:
+                    consecutive_timeouts += 1
+                logger.warning(
+                    "Regex timeout for rule %s (consecutive: %d)",
+                    rule.id,
+                    consecutive_timeouts,
+                )
+                with lock:
+                    if consecutive_timeouts >= REGEX_CIRCUIT_BREAKER_THRESHOLD:
+                        return matched_rules, pattern_score, matched_rule_ids, consecutive_timeouts
+                continue
+            else:
+                with lock:
+                    consecutive_timeouts = 0
+
+            if matched:
+                matched_rules.append(rule)
+                matched_rule_ids.add(rule.id)
+                pattern_score += rule.score
+                logger.debug("Rule matched: %s (+%d points)", rule.id, rule.score)
+
+        return matched_rules, pattern_score, matched_rule_ids, consecutive_timeouts
+
+    def scan_cross_param(
+        self,
+        rules: List[DetectionRule],
+        combined_variants: List[str],
+        matched_rule_ids: Set[str],
+        consecutive_timeouts: int,
+        lock: threading.Lock,
+    ) -> Tuple[List[DetectionRule], int, Set[str], int]:
+        """
+        Cross-parameter correlation scan.
+
+        Args:
+            rules: List of detection rules.
+            combined_variants: List of combined text variants to scan.
+            matched_rule_ids: Already-matched rule IDs to skip.
+            consecutive_timeouts: Current consecutive timeout count.
+            lock: Threading lock for timeout counter.
+
+        Returns:
+            (new_matched_rules, additional_score, updated_matched_rule_ids, updated_consecutive_timeouts)
+        """
+        new_matched_rules: List[DetectionRule] = []
+        additional_score = 0
+
+        for combined_text in combined_variants:
+            for rule in rules:
+                if rule.id not in matched_rule_ids and rule.compiled_pattern:
+                    matched, timed_out = self.match_rule(rule, combined_text)
+                    if timed_out:
+                        with lock:
+                            consecutive_timeouts += 1
+                        logger.warning(
+                            "Regex timeout for rule %s in cross-param (consecutive: %d)",
+                            rule.id,
+                            consecutive_timeouts,
+                        )
+                        continue
+                    else:
+                        with lock:
+                            consecutive_timeouts = 0
+                    if matched:
+                        new_matched_rules.append(rule)
+                        matched_rule_ids.add(rule.id)
+                        additional_score += rule.score
+                        logger.debug(
+                            "Rule matched via cross-parameter correlation: "
+                            "%s (+%d points)",
+                            rule.id,
+                            rule.score,
+                        )
+
+        return new_matched_rules, additional_score, matched_rule_ids, consecutive_timeouts

prooflayer/detection/scorer.py

@@ -0,0 +1,65 @@
+"""
+Risk Scorer
+============
+
+Calculates composite risk scores from multiple detection signals.
+"""
+
+import logging
+from typing import Dict
+
+from ..utils.entropy import calculate_shannon_entropy
+
+logger = logging.getLogger(__name__)
+
+# Shell metacharacters that indicate potential command injection
+DANGEROUS_CHARS = [';', '|', '&&', '||', '`', '$', '>', '<']
+
+
+class RiskScorer:
+    """
+    Calculates risk scores from 4 components:
+    pattern matching, shell metacharacters, entropy, and semantic analysis.
+    """
+
+    def calculate_risk(
+        self,
+        pattern_score: int,
+        search_text: str,
+        semantic_score: int,
+    ) -> Dict[str, int]:
+        """
+        Calculate composite risk score.
+
+        Args:
+            pattern_score: Sum of matched rule scores.
+            search_text: Normalized text for metachar/entropy analysis.
+            semantic_score: Score from semantic analysis.
+
+        Returns:
+            Dict with pattern_score, metachar_score, entropy_score,
+            semantic_score, total_score, and risk_score (capped at 100).
+        """
+        metachar_score = 0
+        for char in DANGEROUS_CHARS:
+            if char in search_text:
+                metachar_score += 10
+                logger.debug("Dangerous char '%s' detected (+10 points)", char)
+
+        entropy_score = 0
+        entropy = calculate_shannon_entropy(search_text)
+        if entropy > 4.5:
+            entropy_score = 20
+            logger.debug("High entropy detected: %.2f (+20 points)", entropy)
+
+        total_score = pattern_score + metachar_score + entropy_score + semantic_score
+        risk_score = min(total_score, 100)
+
+        return {
+            "pattern_score": pattern_score,
+            "metachar_score": metachar_score,
+            "entropy_score": entropy_score,
+            "semantic_score": semantic_score,
+            "total_score": total_score,
+            "risk_score": risk_score,
+        }

prooflayer/detection/semantic.py

@@ -0,0 +1,73 @@
+"""
+Semantic Analyzer
+=================
+
+Parameter-level semantic validation for MCP tool calls.
+"""
+
+import logging
+from typing import Dict, Any
+
+logger = logging.getLogger(__name__)
+
+
+class SemanticAnalyzer:
+    """
+    Detects semantic mismatches in tool call arguments.
+
+    For example, a "hostname" parameter should not contain URLs or shell commands.
+    """
+
+    def analyze(self, tool_name: str, arguments: Dict[str, Any]) -> int:
+        """
+        Run semantic analysis on tool call arguments.
+
+        Args:
+            tool_name: Name of the MCP tool being called.
+            arguments: Tool call arguments dict.
+
+        Returns:
+            Semantic risk score (0+).
+        """
+        score = 0
+
+        for param_name, param_value in arguments.items():
+            param_lower = param_name.lower()
+            param_value_str = str(param_value).lower()
+
+            # Hostname/server/endpoint should not contain URLs
+            if any(kw in param_lower for kw in [
+                "hostname", "server", "host", "endpoint", "target", "address",
+            ]):
+                if any(proto in param_value_str for proto in [
+                    "http://", "https://", "ftp://",
+                    "ssh://", "file://", "data://", "gopher://",
+                ]):
+                    score += 15
+                    logger.debug("Semantic mismatch: hostname/server contains URL (+15 points)")
+
+            # System ID should be numeric or alphanumeric, not commands
+            if "system_id" in param_lower or "id" in param_lower:
+                if any(cmd in param_value_str for cmd in [
+                    "curl", "wget", "bash", "sh",
+                    "nc", "netcat", "python", "perl", "ruby", "ncat",
+                ]):
+                    score += 20
+                    logger.debug("Semantic mismatch: ID contains command (+20 points)")
+
+            # Numeric params containing non-numeric content with commands
+            if any(kw in param_lower for kw in ["port", "timeout", "count", "limit"]):
+                if any(cmd in param_value_str for cmd in [
+                    "curl", "wget", "bash", "sh", "nc", "netcat",
+                    "python", "perl", "ruby", "ncat",
+                ]):
+                    score += 15
+                    logger.debug("Semantic mismatch: numeric param contains command (+15 points)")
+
+            # Path/file params containing pipe or semicolon
+            if any(kw in param_lower for kw in ["path", "file"]):
+                if "|" in param_value_str or ";" in param_value_str:
+                    score += 20
+                    logger.debug("Semantic mismatch: path/file param contains pipe or semicolon (+20 points)")
+
+        return score