raxe 0.4.6__py3-none-any.whl

raxe/domain/policies/models.py

@@ -0,0 +1,223 @@
+"""Domain models for policy-based threat response.
+
+Pure domain layer - immutable value objects for policy evaluation.
+Policies allow customers to override default threat responses.
+"""
+from dataclasses import dataclass, field
+from enum import Enum
+
+from raxe.domain.rules.models import Severity
+
+
+class PolicyAction(Enum):
+    """Action to take when policy conditions match.
+
+    Overrides default detection behavior.
+    """
+    ALLOW = "ALLOW"      # Allow through despite detection
+    BLOCK = "BLOCK"      # Block despite low severity
+    FLAG = "FLAG"        # Flag for review but allow
+    LOG = "LOG"          # Log only, no enforcement
+
+
+@dataclass(frozen=True)
+class PolicyCondition:
+    """Conditions that must be met for policy to apply.
+
+    All specified conditions are AND-ed together.
+    If a field is None, that condition is ignored.
+
+    Attributes:
+        rule_ids: Specific rule IDs this policy applies to (None = all rules)
+        severity_threshold: Minimum severity level (None = all severities)
+        threat_types: Specific threat types (None = all types)
+        min_confidence: Minimum confidence score (0.0-1.0, None = all)
+        max_confidence: Maximum confidence score (0.0-1.0, None = all)
+        custom_filter: JSONPath expression for advanced filtering (None = no filter)
+    """
+    rule_ids: list[str] | None = None
+    severity_threshold: Severity | None = None
+    threat_types: list[str] | None = None
+    min_confidence: float | None = None
+    max_confidence: float | None = None
+    custom_filter: str | None = None
+
+    def __post_init__(self) -> None:
+        """Validate condition constraints."""
+        if self.min_confidence is not None:
+            if not (0.0 <= self.min_confidence <= 1.0):
+                raise ValueError(
+                    f"min_confidence must be 0-1, got {self.min_confidence}"
+                )
+
+        if self.max_confidence is not None:
+            if not (0.0 <= self.max_confidence <= 1.0):
+                raise ValueError(
+                    f"max_confidence must be 0-1, got {self.max_confidence}"
+                )
+
+        if (
+            self.min_confidence is not None
+            and self.max_confidence is not None
+            and self.min_confidence > self.max_confidence
+        ):
+            raise ValueError(
+                f"min_confidence ({self.min_confidence}) cannot be greater than "
+                f"max_confidence ({self.max_confidence})"
+            )
+
+        if self.rule_ids is not None and not self.rule_ids:
+            raise ValueError("rule_ids cannot be empty list (use None for all rules)")
+
+        if self.threat_types is not None and not self.threat_types:
+            raise ValueError("threat_types cannot be empty list (use None for all types)")
+
+
+@dataclass(frozen=True)
+class Policy:
+    """Policy for overriding threat detection behavior.
+
+    Policies allow customers to customize how threats are handled:
+    - Allow known false positives
+    - Block specific patterns more aggressively
+    - Route detections to webhooks
+    - Override severity levels
+
+    Attributes:
+        policy_id: Unique identifier for this policy
+        customer_id: Customer who owns this policy
+        name: Human-readable policy name
+        description: What this policy does and why
+        conditions: List of conditions (OR logic - any match applies policy)
+        action: Action to take when conditions match
+        override_severity: Optional severity override (None = keep original)
+        priority: Priority for conflict resolution (higher = higher priority)
+        enabled: Whether policy is active
+        metadata: Additional metadata for tracking/auditing
+    """
+    policy_id: str
+    customer_id: str
+    name: str
+    description: str
+    conditions: list[PolicyCondition]
+    action: PolicyAction
+    override_severity: Severity | None = None
+    priority: int = 0
+    enabled: bool = True
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Validate policy configuration."""
+        if not self.policy_id:
+            raise ValueError("policy_id cannot be empty")
+
+        if not self.customer_id:
+            raise ValueError("customer_id cannot be empty")
+
+        if not self.name:
+            raise ValueError("name cannot be empty")
+
+        if not self.conditions:
+            raise ValueError("Policy must have at least one condition")
+
+        if self.priority < 0:
+            raise ValueError(f"priority must be non-negative, got {self.priority}")
+
+        # Security: Cap priority at 1000 to prevent resource exhaustion
+        if self.priority > 1000:
+            raise ValueError(f"priority cannot exceed 1000, got {self.priority}")
+
+
+@dataclass(frozen=True)
+class PolicyDecision:
+    """Result of policy evaluation against a detection.
+
+    Represents the final decision after evaluating all applicable policies.
+
+    Attributes:
+        action: Action to take (from highest priority matching policy)
+        original_severity: Original severity from detection
+        final_severity: Severity after policy override (may be same as original)
+        matched_policies: List of policy IDs that matched (ordered by priority)
+        should_block: True if action is BLOCK
+        should_allow: True if action is ALLOW
+        should_flag: True if action is FLAG
+        metadata: Combined metadata from matched policies
+    """
+    action: PolicyAction
+    original_severity: Severity
+    final_severity: Severity
+    matched_policies: list[str] = field(default_factory=list)
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def should_block(self) -> bool:
+        """True if action is BLOCK."""
+        return self.action == PolicyAction.BLOCK
+
+    @property
+    def should_allow(self) -> bool:
+        """True if action is ALLOW."""
+        return self.action == PolicyAction.ALLOW
+
+    @property
+    def should_flag(self) -> bool:
+        """True if action is FLAG."""
+        return self.action == PolicyAction.FLAG
+
+    @property
+    def severity_changed(self) -> bool:
+        """True if severity was overridden by policy."""
+        return self.original_severity != self.final_severity
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to dictionary for serialization.
+
+        Returns:
+            Dictionary representation of decision
+        """
+        return {
+            "action": self.action.value,
+            "original_severity": self.original_severity.value,
+            "final_severity": self.final_severity.value,
+            "severity_changed": self.severity_changed,
+            "should_block": self.should_block,
+            "should_allow": self.should_allow,
+            "should_flag": self.should_flag,
+            "matched_policies": self.matched_policies,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass(frozen=True)
+class PolicySet:
+    """Collection of policies with security limits.
+
+    Ensures policy count doesn't exceed reasonable limits
+    to prevent resource exhaustion attacks.
+
+    Attributes:
+        policies: List of policies in the set
+        max_policies: Maximum number of policies allowed (default: 100)
+    """
+    policies: list[Policy]
+    max_policies: int = 100
+
+    def __post_init__(self) -> None:
+        """Validate policy set."""
+        if len(self.policies) > self.max_policies:
+            raise ValueError(
+                f"Policy count ({len(self.policies)}) exceeds maximum "
+                f"allowed ({self.max_policies}). This limit prevents resource "
+                f"exhaustion attacks."
+            )
+
+    @property
+    def policy_count(self) -> int:
+        """Number of policies in the set."""
+        return len(self.policies)
+
+    @property
+    def enabled_policies(self) -> list[Policy]:
+        """Return only enabled policies."""
+        return [p for p in self.policies if p.enabled]

raxe/domain/rules/__init__.py

@@ -0,0 +1,32 @@
+"""Domain models and schema for threat detection rules.
+
+Pure domain layer - no I/O operations.
+Provides immutable value objects for rules, patterns, and detections.
+"""
+from raxe.domain.rules.models import (
+    Pattern,
+    Rule,
+    RuleExamples,
+    RuleFamily,
+    RuleMetrics,
+    Severity,
+)
+from raxe.domain.rules.schema import (
+    PatternSchema,
+    RuleExamplesSchema,
+    RuleMetricsSchema,
+    RuleSchema,
+)
+
+__all__ = [
+    "Pattern",
+    "PatternSchema",
+    "Rule",
+    "RuleExamples",
+    "RuleExamplesSchema",
+    "RuleFamily",
+    "RuleMetrics",
+    "RuleMetricsSchema",
+    "RuleSchema",
+    "Severity",
+]

raxe/domain/rules/custom.py

@@ -0,0 +1,286 @@
+"""Custom rule framework for user-defined threat detection.
+
+This module provides functionality for loading, validating, and managing
+custom threat detection rules defined in YAML format.
+
+Pure domain layer - NO I/O operations (loading done in infrastructure layer).
+"""
+import hashlib
+from dataclasses import dataclass
+from typing import Any
+
+from raxe.domain.rules.models import Pattern, Rule, RuleExamples, RuleFamily, RuleMetrics, Severity
+
+
+@dataclass(frozen=True)
+class CustomRuleMetadata:
+    """Metadata for a custom rule.
+
+    Attributes:
+        author: Rule author (username or org)
+        created_at: ISO timestamp when rule was created
+        updated_at: ISO timestamp when rule was last updated
+        tags: List of tags for categorization
+        references: List of reference URLs or documents
+        enabled: Whether the rule is active
+    """
+    author: str
+    created_at: str
+    updated_at: str | None = None
+    tags: list[str] | None = None
+    references: list[str] | None = None
+    enabled: bool = True
+
+
+class CustomRuleValidator:
+    """Validate custom rules.
+
+    Pure domain logic for validating rule structure and correctness.
+    """
+
+    @staticmethod
+    def validate_rule_dict(rule_dict: dict[str, Any]) -> tuple[bool, list[str]]:
+        """Validate a rule dictionary.
+
+        Args:
+            rule_dict: Dictionary representation of a rule
+
+        Returns:
+            Tuple of (is_valid, list of error messages)
+        """
+        errors = []
+
+        # Required fields
+        required_fields = ["id", "name", "description", "version", "detection"]
+        for field in required_fields:
+            if field not in rule_dict:
+                errors.append(f"Missing required field: {field}")
+
+        if errors:
+            return False, errors
+
+        # Validate detection section
+        detection = rule_dict.get("detection", {})
+        if not isinstance(detection, dict):
+            errors.append("detection must be a dictionary")
+            return False, errors
+
+        # Required detection fields
+        detection_required = ["layer", "severity", "category"]
+        for field in detection_required:
+            if field not in detection:
+                errors.append(f"Missing required detection field: {field}")
+
+        # Validate layer
+        layer = detection.get("layer", "")
+        if layer not in ("L1", "L2"):
+            errors.append(f"detection.layer must be 'L1' or 'L2', got '{layer}'")
+
+        # For L1, pattern is required
+        if layer == "L1":
+            if "pattern" not in detection:
+                errors.append("L1 rules require 'pattern' in detection")
+            else:
+                # Try to compile pattern
+                pattern_str = detection.get("pattern", "")
+                try:
+                    import re
+                    re.compile(pattern_str)
+                except re.error as e:
+                    errors.append(f"Invalid regex pattern: {e}")
+
+        # Validate severity
+        severity = detection.get("severity", "").lower()
+        if severity not in ("critical", "high", "medium", "low", "info"):
+            errors.append(
+                f"detection.severity must be one of: critical, high, medium, low, info. Got '{severity}'"
+            )
+
+        # Validate confidence (if present)
+        confidence = detection.get("confidence")
+        if confidence is not None:
+            if not isinstance(confidence, (int, float)):
+                errors.append(f"detection.confidence must be a number, got {type(confidence)}")
+            elif not (0.0 <= float(confidence) <= 1.0):
+                errors.append(f"detection.confidence must be between 0 and 1, got {confidence}")
+
+        # Validate examples (if present)
+        examples = rule_dict.get("examples", {})
+        if examples:
+            if not isinstance(examples, dict):
+                errors.append("examples must be a dictionary")
+            else:
+                if "positive" in examples and not isinstance(examples["positive"], list):
+                    errors.append("examples.positive must be a list")
+                if "negative" in examples and not isinstance(examples["negative"], list):
+                    errors.append("examples.negative must be a list")
+
+        return len(errors) == 0, errors
+
+    @staticmethod
+    def test_rule_examples(rule: Rule) -> tuple[bool, list[str]]:
+        """Test a rule against its examples.
+
+        Args:
+            rule: Rule to test
+
+        Returns:
+            Tuple of (all_passed, list of failures)
+        """
+        failures = []
+
+        # Test positive examples (should match)
+        failed_should_match, failed_should_not_match = rule.matches_examples()
+
+        for example in failed_should_match:
+            failures.append(f"Expected to match but didn't: {example[:50]}...")
+
+        for example in failed_should_not_match:
+            failures.append(f"Expected NOT to match but did: {example[:50]}...")
+
+        return len(failures) == 0, failures
+
+
+class CustomRuleBuilder:
+    """Build Rule objects from custom YAML definitions.
+
+    Pure domain logic - converts validated dictionaries to Rule objects.
+    """
+
+    @staticmethod
+    def from_dict(rule_dict: dict[str, Any]) -> Rule:
+        """Build a Rule from a validated dictionary.
+
+        Args:
+            rule_dict: Validated rule dictionary
+
+        Returns:
+            Rule object
+
+        Raises:
+            ValueError: If rule_dict is invalid
+        """
+        # Validate first
+        is_valid, errors = CustomRuleValidator.validate_rule_dict(rule_dict)
+        if not is_valid:
+            raise ValueError(f"Invalid rule: {', '.join(errors)}")
+
+        detection = rule_dict["detection"]
+
+        # Map YAML fields to Rule fields
+        rule_id = rule_dict["id"]
+        version = rule_dict["version"]
+        name = rule_dict["name"]
+        description = rule_dict["description"]
+
+        # Map severity
+        severity_str = detection["severity"].lower()
+        severity = Severity(severity_str)
+
+        # Map category to family
+        category = detection.get("category", "CUSTOM").upper()
+        try:
+            family = RuleFamily(category)
+        except ValueError:
+            family = RuleFamily.CUSTOM
+
+        sub_family = detection.get("sub_family", category.lower())
+
+        # Build patterns (L1 only)
+        patterns = []
+        if detection.get("layer") == "L1":
+            pattern_str = detection["pattern"]
+            flags = detection.get("flags", [])
+            timeout = detection.get("timeout", 5.0)
+
+            patterns.append(Pattern(
+                pattern=pattern_str,
+                flags=flags,
+                timeout=timeout,
+            ))
+
+        # Build examples
+        examples_dict = rule_dict.get("examples", {})
+        examples = RuleExamples(
+            should_match=examples_dict.get("positive", []),
+            should_not_match=examples_dict.get("negative", []),
+        )
+
+        # Build metrics (initially empty)
+        metrics = RuleMetrics()
+
+        # Get confidence
+        confidence = detection.get("confidence", 0.9)
+
+        # Get MITRE ATT&CK techniques
+        mitre_attack = rule_dict.get("mitre_attack", [])
+
+        # Build metadata
+        metadata_dict = rule_dict.get("metadata", {})
+        # Check for author at top level (legacy) or in metadata
+        author = rule_dict.get("author") or metadata_dict.get("author", "unknown")
+        metadata = {
+            "author": author,
+            "created_at": metadata_dict.get("created_at", ""),
+            "tags": metadata_dict.get("tags", []),
+            "references": metadata_dict.get("references", []),
+            "custom": True,  # Mark as custom rule
+        }
+
+        # Calculate rule hash
+        rule_content = f"{rule_id}{version}{name}{description}{''.join(p.pattern for p in patterns)}"
+        rule_hash = hashlib.sha256(rule_content.encode()).hexdigest()
+
+        return Rule(
+            rule_id=rule_id,
+            version=version,
+            family=family,
+            sub_family=sub_family,
+            name=name,
+            description=description,
+            severity=severity,
+            confidence=confidence,
+            patterns=patterns,
+            examples=examples,
+            metrics=metrics,
+            mitre_attack=mitre_attack,
+            metadata=metadata,
+            rule_hash=rule_hash,
+        )
+
+    @staticmethod
+    def to_dict(rule: Rule) -> dict[str, Any]:
+        """Convert a Rule to YAML-compatible dictionary.
+
+        Args:
+            rule: Rule to convert
+
+        Returns:
+            Dictionary representation suitable for YAML serialization
+        """
+        return {
+            "id": rule.rule_id,
+            "version": rule.version,
+            "name": rule.name,
+            "description": rule.description,
+            "author": rule.metadata.get("author", "unknown"),
+            "detection": {
+                "layer": "L1" if rule.patterns else "L2",
+                "pattern": rule.patterns[0].pattern if rule.patterns else "",
+                "flags": rule.patterns[0].flags if rule.patterns else [],
+                "timeout": rule.patterns[0].timeout if rule.patterns else 5.0,
+                "severity": rule.severity.value,
+                "confidence": rule.confidence,
+                "category": rule.family.value,
+                "sub_family": rule.sub_family,
+            },
+            "examples": {
+                "positive": rule.examples.should_match,
+                "negative": rule.examples.should_not_match,
+            },
+            "metadata": {
+                "tags": rule.metadata.get("tags", []),
+                "references": rule.metadata.get("references", []),
+            },
+            "mitre_attack": rule.mitre_attack,
+        }