raxe 0.4.6__py3-none-any.whl

raxe/domain/engine/executor.py

@@ -0,0 +1,396 @@
+"""Rule execution engine.
+
+Pure domain layer - executes rules against text to produce detections.
+All functions are stateless and side-effect free.
+
+Performance targets:
+- <5ms P95 for 10KB text with 15 L1 rules
+- <1ms average for typical prompts
+"""
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from raxe.domain.engine.matcher import Match, PatternMatcher
+from raxe.domain.rules.models import Rule, Severity
+
+
+@dataclass(frozen=True)
+class Detection:
+    """A detected threat from a rule match.
+
+    Immutable value object representing a security threat.
+
+    Attributes:
+        rule_id: ID of rule that matched
+        rule_version: Version of rule that matched
+        severity: Threat severity level
+        confidence: Detection confidence (0.0-1.0)
+        matches: List of pattern matches that triggered detection
+        detected_at: ISO timestamp when detected
+        detection_layer: Layer that produced this detection (L1, L2, or PLUGIN)
+        layer_latency_ms: Time taken by this layer to produce detection
+        category: Category of threat (e.g., prompt_injection, jailbreak)
+        message: Human-readable message describing the detection
+        explanation: Optional explanation of why this was detected
+        risk_explanation: Explanation of why this pattern is dangerous
+        remediation_advice: How to fix or mitigate this threat
+        docs_url: Link to documentation for learning more
+        is_flagged: True if detection was matched by a FLAG suppression
+        suppression_reason: Reason for suppression (if flagged or logged)
+    """
+    rule_id: str
+    rule_version: str
+    severity: Severity
+    confidence: float
+    matches: list[Match]
+    detected_at: str
+    detection_layer: str = "L1"  # Default to L1 for backward compatibility
+    layer_latency_ms: float = 0.0
+    category: str = "unknown"
+    message: str = ""
+    explanation: str | None = None
+    risk_explanation: str = ""
+    remediation_advice: str = ""
+    docs_url: str = ""
+    is_flagged: bool = False
+    suppression_reason: str | None = None
+
+    def __post_init__(self) -> None:
+        """Validate detection after construction."""
+        if not (0.0 <= self.confidence <= 1.0):
+            raise ValueError(f"Confidence must be 0-1, got {self.confidence}")
+        if not self.matches:
+            raise ValueError("Detection must have at least one match")
+        if self.detection_layer not in ("L1", "L2", "PLUGIN"):
+            raise ValueError(f"detection_layer must be L1, L2, or PLUGIN, got {self.detection_layer}")
+        if self.layer_latency_ms < 0:
+            raise ValueError(f"layer_latency_ms cannot be negative: {self.layer_latency_ms}")
+
+    @property
+    def match_count(self) -> int:
+        """Number of pattern matches."""
+        return len(self.matches)
+
+    @property
+    def threat_summary(self) -> str:
+        """Human-readable summary of threat.
+
+        Returns:
+            Summary string like "CRITICAL: pi-001 (confidence: 0.95, matches: 2)"
+        """
+        return (
+            f"{self.severity.value.upper()}: {self.rule_id} "
+            f"(confidence: {self.confidence:.2f}, matches: {self.match_count})"
+        )
+
+    @property
+    def versioned_rule_id(self) -> str:
+        """Full versioned rule identifier.
+
+        Returns:
+            String like "pi-001@1.0.0"
+        """
+        return f"{self.rule_id}@{self.rule_version}"
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dictionary for serialization.
+
+        Returns:
+            Dictionary representation of detection
+        """
+        return {
+            "rule_id": self.rule_id,
+            "rule_version": self.rule_version,
+            "severity": self.severity.value,
+            "confidence": self.confidence,
+            "match_count": self.match_count,
+            "detected_at": self.detected_at,
+            "threat_summary": self.threat_summary,
+            "detection_layer": self.detection_layer,
+            "layer_latency_ms": self.layer_latency_ms,
+            "category": self.category,
+            "message": self.message,
+            "explanation": self.explanation,
+            "risk_explanation": self.risk_explanation,
+            "remediation_advice": self.remediation_advice,
+            "docs_url": self.docs_url,
+            "is_flagged": self.is_flagged,
+            "suppression_reason": self.suppression_reason,
+        }
+
+    def with_flag(self, reason: str) -> "Detection":
+        """Create a copy of this detection with is_flagged=True.
+
+        Used by suppression system when FLAG action is matched.
+
+        Args:
+            reason: The reason for flagging this detection
+
+        Returns:
+            New Detection instance with is_flagged=True
+        """
+        # Since Detection is frozen, we must create a new instance
+        return Detection(
+            rule_id=self.rule_id,
+            rule_version=self.rule_version,
+            severity=self.severity,
+            confidence=self.confidence,
+            matches=self.matches,
+            detected_at=self.detected_at,
+            detection_layer=self.detection_layer,
+            layer_latency_ms=self.layer_latency_ms,
+            category=self.category,
+            message=self.message,
+            explanation=self.explanation,
+            risk_explanation=self.risk_explanation,
+            remediation_advice=self.remediation_advice,
+            docs_url=self.docs_url,
+            is_flagged=True,
+            suppression_reason=reason,
+        )
+
+
+@dataclass(frozen=True)
+class ScanResult:
+    """Result of scanning text against rules.
+
+    Aggregates all detections with metadata about the scan.
+
+    Attributes:
+        detections: List of detected threats (may be empty)
+        scanned_at: ISO timestamp when scan started
+        text_length: Length of scanned text in characters
+        rules_checked: Number of rules evaluated
+        scan_duration_ms: Time taken to scan in milliseconds
+    """
+    detections: list[Detection]
+    scanned_at: str
+    text_length: int
+    rules_checked: int
+    scan_duration_ms: float
+
+    def __post_init__(self) -> None:
+        """Validate scan result."""
+        if self.text_length < 0:
+            raise ValueError(f"text_length cannot be negative: {self.text_length}")
+        if self.rules_checked < 0:
+            raise ValueError(f"rules_checked cannot be negative: {self.rules_checked}")
+        if self.scan_duration_ms < 0:
+            raise ValueError(f"scan_duration_ms cannot be negative: {self.scan_duration_ms}")
+
+    @property
+    def has_detections(self) -> bool:
+        """True if any threats detected."""
+        return len(self.detections) > 0
+
+    @property
+    def highest_severity(self) -> Severity | None:
+        """Highest severity across all detections.
+
+        Returns:
+            Highest severity or None if no detections
+        """
+        if not self.detections:
+            return None
+
+        # Severity order (lower number = more severe)
+        severity_order = {
+            Severity.CRITICAL: 0,
+            Severity.HIGH: 1,
+            Severity.MEDIUM: 2,
+            Severity.LOW: 3,
+            Severity.INFO: 4,
+        }
+
+        return min(
+            (d.severity for d in self.detections),
+            key=lambda s: severity_order[s],
+        )
+
+    @property
+    def total_matches(self) -> int:
+        """Total pattern matches across all detections."""
+        return sum(d.match_count for d in self.detections)
+
+    @property
+    def detection_count(self) -> int:
+        """Number of detections (rules that matched)."""
+        return len(self.detections)
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dictionary for serialization.
+
+        Returns:
+            Dictionary representation of scan result
+        """
+        return {
+            "has_detections": self.has_detections,
+            "detection_count": self.detection_count,
+            "highest_severity": self.highest_severity.value if self.highest_severity else None,
+            "total_matches": self.total_matches,
+            "text_length": self.text_length,
+            "rules_checked": self.rules_checked,
+            "scan_duration_ms": self.scan_duration_ms,
+            "scanned_at": self.scanned_at,
+            "detections": [d.to_dict() for d in self.detections],
+        }
+
+
+class RuleExecutor:
+    """Execute rules against text to detect threats.
+
+    Pure domain logic - stateless and side-effect free.
+    Uses PatternMatcher for actual pattern matching.
+
+    Thread-safe for concurrent scans.
+    """
+
+    def __init__(self) -> None:
+        """Initialize with pattern matcher."""
+        self.matcher = PatternMatcher()
+
+    def execute_rule(self, text: str, rule: Rule) -> Detection | None:
+        """Execute a single rule against text.
+
+        Args:
+            text: Text to scan
+            rule: Rule to apply
+
+        Returns:
+            Detection if rule matched, None otherwise
+
+        Note:
+            Implements OR logic: if any pattern matches, rule matches.
+        """
+        # Match all patterns in rule (OR logic)
+        matches = self.matcher.match_all_patterns(text, rule.patterns)
+
+        if not matches:
+            return None
+
+        # Calculate confidence based on match quality
+        confidence = self._calculate_confidence(rule, matches)
+
+        # Derive category from rule family
+        category = rule.family.value.lower() if hasattr(rule.family, 'value') else str(rule.family).lower()
+
+        # Create message from rule
+        message = f"{rule.name}: {rule.description[:100]}"  # Truncate long descriptions
+
+        # Create detection with explainability fields from rule
+        return Detection(
+            rule_id=rule.rule_id,
+            rule_version=rule.version,
+            severity=rule.severity,
+            confidence=confidence,
+            matches=matches,
+            detected_at=datetime.now(timezone.utc).isoformat(),
+            detection_layer="L1",  # Executor always produces L1 detections
+            layer_latency_ms=0.0,  # Will be set by caller if needed
+            category=category,
+            message=message,
+            explanation=None,
+            risk_explanation=rule.risk_explanation,
+            remediation_advice=rule.remediation_advice,
+            docs_url=rule.docs_url,
+        )
+
+    def execute_rules(
+        self,
+        text: str,
+        rules: list[Rule],
+    ) -> ScanResult:
+        """Execute all rules against text.
+
+        Args:
+            text: Text to scan
+            rules: Rules to apply
+
+        Returns:
+            ScanResult with all detections and metadata
+
+        Note:
+            Continues scanning even if individual rules fail.
+            Failed rules are skipped (caller should log).
+        """
+        start_time = time.perf_counter()
+        scan_started_at = datetime.now(timezone.utc).isoformat()
+
+        detections: list[Detection] = []
+
+        for rule in rules:
+            try:
+                detection = self.execute_rule(text, rule)
+                if detection:
+                    detections.append(detection)
+            except Exception:  # noqa: S112
+                # Rule failed - skip it and continue
+                # Note: Broad except is intentional - domain layer can't log
+                # Caller in application layer should log failures
+                continue
+
+        duration_ms = (time.perf_counter() - start_time) * 1000
+
+        return ScanResult(
+            detections=detections,
+            scanned_at=scan_started_at,
+            text_length=len(text),
+            rules_checked=len(rules),
+            scan_duration_ms=duration_ms,
+        )
+
+    def _calculate_confidence(
+        self,
+        rule: Rule,
+        matches: list[Match],
+    ) -> float:
+        """Calculate detection confidence.
+
+        Combines rule's base confidence with match quality factors:
+        - Number of matches (more = higher confidence)
+        - Match length (longer = higher confidence)
+        - Pattern diversity (multiple patterns = higher confidence)
+
+        Args:
+            rule: The rule that matched
+            matches: Pattern matches
+
+        Returns:
+            Confidence score 0.0-1.0 (capped at rule's base confidence)
+        """
+        base_confidence = rule.confidence
+
+        # Quality factors
+        # More matches increases confidence (up to 3 matches = 100% of factor)
+        match_count_factor = min(len(matches) / 3.0, 1.0)
+
+        # Multiple different patterns matching is stronger signal
+        unique_patterns = len({m.pattern_index for m in matches})
+        pattern_diversity_factor = min(unique_patterns / len(rule.patterns), 1.0)
+
+        # Average match length (longer matches = higher confidence)
+        avg_match_length = sum(m.match_length for m in matches) / len(matches)
+        length_factor = min(avg_match_length / 20.0, 1.0)  # 20+ chars = 100%
+
+        # Combined quality (weighted average)
+        quality = (
+            0.4 * match_count_factor +
+            0.4 * pattern_diversity_factor +
+            0.2 * length_factor
+        )
+
+        # Final confidence: base * (0.7 + 0.3 * quality)
+        # This means:
+        # - Minimum 70% of base confidence (at least one match)
+        # - Maximum 100% of base confidence (perfect quality)
+        combined = base_confidence * (0.7 + 0.3 * quality)
+
+        return min(combined, 1.0)
+
+    def clear_cache(self) -> None:
+        """Clear pattern matcher cache.
+
+        Useful for testing or when rules change.
+        """
+        self.matcher.clear_cache()

raxe/domain/engine/matcher.py

@@ -0,0 +1,212 @@
+"""Pattern matching engine for threat detection.
+
+Pure domain layer - NO I/O operations.
+All functions are stateless and side-effect free.
+
+Performance targets:
+- <1ms per pattern match
+- Pattern compilation cached for reuse
+- Timeout protection per pattern (enforced via regex module)
+"""
+import regex
+from dataclasses import dataclass
+from regex import Pattern as RePattern
+
+from raxe.domain.rules.models import Pattern
+
+
+@dataclass(frozen=True)
+class Match:
+    """A single pattern match in text.
+
+    Immutable value object representing where and what matched.
+
+    Attributes:
+        pattern_index: Which pattern in the rule matched (0-based)
+        start: Start position in text
+        end: End position in text
+        matched_text: The actual matched text
+        groups: Captured groups from regex
+        context_before: Up to 50 chars before match
+        context_after: Up to 50 chars after match
+    """
+    pattern_index: int
+    start: int
+    end: int
+    matched_text: str
+    groups: tuple[str, ...]
+    context_before: str
+    context_after: str
+
+    @property
+    def match_length(self) -> int:
+        """Length of matched text."""
+        return self.end - self.start
+
+    @property
+    def full_context(self) -> str:
+        """Full context around match."""
+        return f"{self.context_before}[{self.matched_text}]{self.context_after}"
+
+
+class PatternMatcher:
+    """Stateless pattern matching with timeout support.
+
+    Pure domain logic - no I/O, no side effects.
+    Caches compiled patterns for performance.
+
+    Thread-safe for read operations (cache is write-once per pattern).
+    """
+
+    def __init__(self) -> None:
+        """Initialize matcher with empty pattern cache."""
+        self._compiled_cache: dict[str, RePattern[str]] = {}
+
+    def compile_pattern(self, pattern: Pattern) -> RePattern[str]:
+        """Compile regex pattern with flags.
+
+        Args:
+            pattern: Pattern object from rule
+
+        Returns:
+            Compiled regex pattern
+
+        Raises:
+            ValueError: If pattern is invalid or flags are unknown
+
+        Note:
+            Caches compiled patterns for performance.
+            Cache key includes pattern string and flags.
+        """
+        # Create cache key from pattern and flags
+        cache_key = f"{pattern.pattern}:{':'.join(sorted(pattern.flags))}"
+
+        if cache_key in self._compiled_cache:
+            return self._compiled_cache[cache_key]
+
+        # Convert string flags to regex module flags
+        flags = 0
+        for flag in pattern.flags:
+            flag_upper = flag.upper()
+            if flag_upper == "IGNORECASE":
+                flags |= regex.IGNORECASE
+            elif flag_upper == "MULTILINE":
+                flags |= regex.MULTILINE
+            elif flag_upper == "DOTALL":
+                flags |= regex.DOTALL
+            elif flag_upper == "VERBOSE":
+                flags |= regex.VERBOSE
+            elif flag_upper == "ASCII":
+                flags |= regex.ASCII
+            else:
+                raise ValueError(f"Unknown regex flag: {flag}")
+
+        try:
+            compiled = regex.compile(pattern.pattern, flags)
+        except regex.error as e:
+            raise ValueError(f"Invalid regex pattern '{pattern.pattern}': {e}") from e
+
+        # Cache for future use
+        self._compiled_cache[cache_key] = compiled
+        return compiled
+
+    def match_pattern(
+        self,
+        text: str,
+        pattern: Pattern,
+        pattern_index: int = 0,
+        timeout_seconds: float | None = None,
+    ) -> list[Match]:
+        """Match a single pattern against text with timeout.
+
+        Args:
+            text: Text to search
+            pattern: Pattern to match
+            pattern_index: Index of this pattern in rule (for Match objects)
+            timeout_seconds: Override pattern timeout (default: pattern.timeout or 5.0s)
+
+        Returns:
+            List of Match objects (empty if no matches)
+
+        Raises:
+            ValueError: If pattern compilation fails or matching times out
+        """
+        # Use provided timeout, pattern timeout, or default of 5.0 seconds
+        timeout = timeout_seconds if timeout_seconds is not None else (pattern.timeout or 5.0)
+        compiled = self.compile_pattern(pattern)
+
+        matches: list[Match] = []
+
+        try:
+            # regex module provides native timeout support via timeout parameter
+            for match_obj in compiled.finditer(text, timeout=timeout):
+                start = match_obj.start()
+                end = match_obj.end()
+
+                # Extract context (50 chars before and after)
+                context_before = text[max(0, start - 50):start]
+                context_after = text[end:min(len(text), end + 50)]
+
+                matches.append(Match(
+                    pattern_index=pattern_index,
+                    start=start,
+                    end=end,
+                    matched_text=text[start:end],
+                    groups=match_obj.groups(),
+                    context_before=context_before,
+                    context_after=context_after,
+                ))
+        except TimeoutError as e:
+            raise ValueError(
+                f"Pattern matching timed out after {timeout}s (possible ReDoS): {e}"
+            ) from e
+        except regex.error as e:
+            raise ValueError(f"Pattern matching failed: {e}") from e
+
+        return matches
+
+    def match_all_patterns(
+        self,
+        text: str,
+        patterns: list[Pattern],
+    ) -> list[Match]:
+        """Match all patterns from a rule against text.
+
+        This implements OR logic: any pattern matching means the rule matches.
+
+        Args:
+            text: Text to search
+            patterns: List of patterns to match
+
+        Returns:
+            All matches from all patterns (may be empty)
+
+        Note:
+            Continues matching even if a pattern fails, logging failures
+            for later analysis (though we can't log in pure domain - caller handles).
+        """
+        all_matches: list[Match] = []
+
+        for idx, pattern in enumerate(patterns):
+            try:
+                matches = self.match_pattern(text, pattern, pattern_index=idx)
+                all_matches.extend(matches)
+            except ValueError:
+                # Pattern failed - skip it and continue with others
+                # Caller should log this for debugging
+                continue
+
+        return all_matches
+
+    def clear_cache(self) -> None:
+        """Clear compiled pattern cache.
+
+        Useful for testing or when patterns change.
+        Not typically needed in production.
+        """
+        self._compiled_cache.clear()
+
+    @property
+    def cache_size(self) -> int:
+        """Number of compiled patterns in cache."""
+        return len(self._compiled_cache)