raxe 0.4.6__py3-none-any.whl

raxe/infrastructure/rules/yaml_loader.py

@@ -0,0 +1,286 @@
+"""YAML rule loader for RAXE CE.
+
+Loads and validates rule definitions from YAML files matching
+the v1.1 specification. Infrastructure layer - handles file I/O.
+"""
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import ValidationError
+
+from raxe.domain.rules.models import (
+    Pattern,
+    Rule,
+    RuleExamples,
+    RuleFamily,
+    RuleMetrics,
+    Severity,
+)
+from raxe.domain.rules.schema import RuleSchema
+from raxe.infrastructure.rules.versioning import VersionChecker, VersionError
+
+
+class YAMLLoadError(Exception):
+    """Exception raised when YAML file cannot be loaded or validated."""
+    pass
+
+
+class YAMLLoader:
+    """Load threat detection rules from YAML files.
+
+    Handles file I/O and conversion from YAML to domain Rule objects.
+    Validates against schema and ensures version compatibility.
+    """
+
+    def __init__(
+        self,
+        *,
+        version_checker: VersionChecker | None = None,
+        strict: bool = True,
+    ) -> None:
+        """Initialize YAML loader.
+
+        Args:
+            version_checker: Version compatibility checker (uses default if None)
+            strict: If True, raise on any validation warnings
+        """
+        self.version_checker = version_checker or VersionChecker()
+        self.strict = strict
+
+    def load_rule(self, path: Path) -> Rule:
+        """Load a single rule from YAML file.
+
+        Args:
+            path: Path to YAML file
+
+        Returns:
+            Validated Rule domain object
+
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            YAMLLoadError: If YAML is malformed or validation fails
+            VersionError: If schema version is incompatible
+        """
+        # 1. Validate path exists
+        if not path.exists():
+            raise FileNotFoundError(f"Rule file not found: {path}")
+
+        if not path.is_file():
+            raise YAMLLoadError(f"Path is not a file: {path}")
+
+        # 2. Read and parse YAML
+        try:
+            with open(path, encoding='utf-8') as f:
+                data = yaml.safe_load(f)
+        except yaml.YAMLError as e:
+            raise YAMLLoadError(f"Failed to parse YAML from {path}: {e}") from e
+        except Exception as e:
+            raise YAMLLoadError(f"Failed to read file {path}: {e}") from e
+
+        if data is None:
+            raise YAMLLoadError(f"Empty YAML file: {path}")
+
+        if not isinstance(data, dict):
+            raise YAMLLoadError(f"YAML root must be a dictionary, got {type(data)}: {path}")
+
+        # 3. Check version compatibility
+        version = data.get('version')
+        if not version:
+            raise YAMLLoadError(f"Missing required 'version' field in {path}")
+
+        try:
+            self.version_checker.check_compatibility(str(version))
+        except VersionError as e:
+            raise YAMLLoadError(f"Version incompatibility in {path}: {e}") from e
+
+        # 4. Validate against schema
+        try:
+            schema = RuleSchema(**data)
+        except ValidationError as e:
+            raise YAMLLoadError(
+                f"Validation failed for {path}:\n{self._format_validation_error(e)}"
+            ) from e
+
+        # 5. Convert to domain Rule object
+        try:
+            rule = self._schema_to_domain(schema)
+        except Exception as e:
+            raise YAMLLoadError(f"Failed to convert rule from {path}: {e}") from e
+
+        return rule
+
+    def load_rules_from_directory(
+        self,
+        directory: Path,
+        *,
+        recursive: bool = False,
+        pattern: str = "*.yaml",
+    ) -> list[Rule]:
+        """Load all YAML rules from directory.
+
+        Args:
+            directory: Directory containing rule files
+            recursive: If True, search subdirectories recursively
+            pattern: Glob pattern for rule files (default: *.yaml)
+
+        Returns:
+            List of validated Rule objects
+
+        Raises:
+            NotADirectoryError: If directory doesn't exist or isn't a directory
+            YAMLLoadError: If any rule file fails to load
+        """
+        if not directory.exists():
+            raise NotADirectoryError(f"Directory not found: {directory}")
+
+        if not directory.is_dir():
+            raise NotADirectoryError(f"Path is not a directory: {directory}")
+
+        # Find all matching files
+        if recursive:
+            rule_files = list(directory.rglob(pattern))
+        else:
+            rule_files = list(directory.glob(pattern))
+
+        if not rule_files:
+            return []
+
+        # Load each rule file
+        rules = []
+        errors = []
+
+        for rule_file in sorted(rule_files):
+            try:
+                rule = self.load_rule(rule_file)
+                rules.append(rule)
+            except Exception as e:
+                error_msg = f"{rule_file.name}: {e}"
+                errors.append(error_msg)
+                if self.strict:
+                    raise YAMLLoadError(
+                        "Failed to load rules. Errors:\n" + "\n".join(errors)
+                    ) from e
+
+        if errors and self.strict:
+            raise YAMLLoadError(
+                f"Failed to load {len(errors)} rule file(s):\n" + "\n".join(errors)
+            )
+
+        return rules
+
+    def _schema_to_domain(self, schema: RuleSchema) -> Rule:
+        """Convert Pydantic schema to domain Rule object.
+
+        Args:
+            schema: Validated RuleSchema object
+
+        Returns:
+            Domain Rule object
+
+        Raises:
+            ValueError: If conversion fails
+        """
+        # Convert patterns
+        patterns = [
+            Pattern(
+                pattern=p.pattern,
+                flags=p.flags,
+                timeout=p.timeout,
+            )
+            for p in schema.patterns
+        ]
+
+        # Convert examples
+        examples = RuleExamples(
+            should_match=schema.examples.should_match,
+            should_not_match=schema.examples.should_not_match,
+        )
+
+        # Convert metrics
+        metrics = RuleMetrics(
+            precision=schema.metrics.precision,
+            recall=schema.metrics.recall,
+            f1_score=schema.metrics.f1_score,
+            last_evaluated=schema.metrics.last_evaluated,
+            counts_30d=schema.metrics.counts_30d,
+        )
+
+        # Convert enums
+        try:
+            severity = Severity(schema.severity)
+        except ValueError as e:
+            raise ValueError(f"Invalid severity value: {schema.severity}") from e
+
+        try:
+            family = RuleFamily(schema.family)
+        except ValueError as e:
+            raise ValueError(f"Invalid family value: {schema.family}") from e
+
+        # Create Rule
+        return Rule(
+            rule_id=schema.rule_id,
+            version=schema.version,
+            family=family,
+            sub_family=schema.sub_family,
+            name=schema.name,
+            description=schema.description,
+            severity=severity,
+            confidence=schema.confidence,
+            patterns=patterns,
+            examples=examples,
+            metrics=metrics,
+            mitre_attack=schema.mitre_attack,
+            metadata=schema.metadata,
+            rule_hash=schema.rule_hash,
+            risk_explanation=schema.risk_explanation,
+            remediation_advice=schema.remediation_advice,
+            docs_url=schema.docs_url,
+        )
+
+    @staticmethod
+    def _format_validation_error(error: ValidationError) -> str:
+        """Format Pydantic validation error for user-friendly output.
+
+        Args:
+            error: Pydantic ValidationError
+
+        Returns:
+            Formatted error message
+        """
+        messages = []
+        for err in error.errors():
+            loc = " -> ".join(str(item) for item in err['loc'])
+            msg = err['msg']
+            messages.append(f"  {loc}: {msg}")
+        return "\n".join(messages)
+
+    def validate_yaml_structure(self, data: dict[str, Any]) -> None:
+        """Validate YAML structure matches v1.1 spec.
+
+        Args:
+            data: Parsed YAML data
+
+        Raises:
+            YAMLLoadError: If validation fails
+        """
+        # Check for required top-level fields
+        required_fields = {
+            'version', 'rule_id', 'family', 'sub_family', 'name',
+            'description', 'severity', 'confidence', 'patterns',
+            'examples', 'metrics'
+        }
+
+        missing_fields = required_fields - set(data.keys())
+        if missing_fields:
+            raise YAMLLoadError(
+                f"Missing required fields: {', '.join(sorted(missing_fields))}"
+            )
+
+        # Validate using Pydantic schema
+        try:
+            RuleSchema(**data)
+        except ValidationError as e:
+            raise YAMLLoadError(
+                f"YAML structure validation failed:\n{self._format_validation_error(e)}"
+            ) from e

raxe/infrastructure/security/__init__.py

@@ -0,0 +1,31 @@
+"""Security infrastructure for RAXE CE.
+
+Provides cryptographic signature verification, API key validation,
+and policy security checks.
+"""
+
+from raxe.infrastructure.security.auth import (
+    APIKey,
+    APIKeyValidator,
+    AuthError,
+    KeyType,
+)
+from raxe.infrastructure.security.policy_validator import (
+    PolicyValidationError,
+    PolicyValidator,
+)
+from raxe.infrastructure.security.signatures import (
+    SignatureError,
+    SignatureVerifier,
+)
+
+__all__ = [
+    "APIKey",
+    "APIKeyValidator",
+    "AuthError",
+    "KeyType",
+    "PolicyValidationError",
+    "PolicyValidator",
+    "SignatureError",
+    "SignatureVerifier",
+]

raxe/infrastructure/security/auth.py

@@ -0,0 +1,145 @@
+"""API key validation and parsing.
+
+Validates RAXE API keys without network calls.
+"""
+import re
+from dataclasses import dataclass
+from enum import Enum
+
+
+class KeyType(Enum):
+    """API key type."""
+
+    LIVE = "live"
+    TEST = "test"
+
+
+class AuthError(Exception):
+    """Authentication error."""
+
+    pass
+
+
+@dataclass(frozen=True)
+class APIKey:
+    """
+    Parsed API key.
+
+    Format: raxe_{live|test}_{customer_id}_{random}
+    Example: raxe_live_cust_abc123_a1b2c3d4e5f6
+    """
+
+    raw_key: str
+    key_type: KeyType
+    customer_id: str
+    random_suffix: str
+
+    @classmethod
+    def parse(cls, key: str) -> "APIKey":
+        """
+        Parse API key.
+
+        Args:
+            key: Raw API key string
+
+        Returns:
+            Parsed APIKey object
+
+        Raises:
+            AuthError: If key format invalid
+        """
+        if not key:
+            raise AuthError("API key cannot be empty")
+
+        # Expected format: raxe_{live|test}_{customer_id}_{random}
+        # Pattern allows case-insensitive matching for entire key
+        pattern = r"^raxe_(live|test)_([a-z0-9_]+)_([a-z0-9]+)$"
+        match = re.match(pattern, key.lower())
+
+        if not match:
+            raise AuthError(
+                "Invalid API key format. "
+                "Expected: raxe_{live|test}_{customer_id}_{random}"
+            )
+
+        key_type_str, customer_id, random_suffix = match.groups()
+
+        # Validate customer ID format (already lowercase from above)
+        if not customer_id.startswith("cust_"):
+            raise AuthError("Customer ID must start with 'cust_'")
+
+        # Validate random suffix length
+        if len(random_suffix) < 12:
+            raise AuthError("Random suffix must be at least 12 characters")
+
+        return cls(
+            raw_key=key,
+            key_type=KeyType(key_type_str.lower()),
+            customer_id=customer_id,
+            random_suffix=random_suffix,
+        )
+
+    @property
+    def is_live(self) -> bool:
+        """True if live key."""
+        return self.key_type == KeyType.LIVE
+
+    @property
+    def is_test(self) -> bool:
+        """True if test key."""
+        return self.key_type == KeyType.TEST
+
+
+class APIKeyValidator:
+    """
+    Validate API keys.
+
+    Offline validation only - no network calls.
+    Cloud validation happens separately (optional).
+    """
+
+    def validate_key(self, key: str) -> APIKey:
+        """
+        Validate and parse API key.
+
+        Args:
+            key: Raw API key string
+
+        Returns:
+            Parsed and validated APIKey
+
+        Raises:
+            AuthError: If key invalid
+        """
+        # Parse key
+        api_key = APIKey.parse(key)
+
+        # Additional validation
+        self._validate_customer_id(api_key.customer_id)
+
+        return api_key
+
+    def _validate_customer_id(self, customer_id: str) -> None:
+        """Validate customer ID format."""
+        if len(customer_id) < 10:
+            raise AuthError("Customer ID too short")
+
+        if len(customer_id) > 50:
+            raise AuthError("Customer ID too long")
+
+        # Only lowercase alphanumeric and underscore
+        if not re.match(r"^cust_[a-z0-9_]+$", customer_id):
+            raise AuthError("Customer ID contains invalid characters")
+
+    def extract_customer_id(self, key: str) -> str:
+        """
+        Extract customer ID from key.
+
+        Args:
+            key: API key
+
+        Returns:
+            Customer ID
+        """
+        api_key = self.validate_key(key)
+        return api_key.customer_id

raxe/infrastructure/security/policy_validator.py

@@ -0,0 +1,124 @@
+"""Policy validation and security checks.
+
+Validates customer policies before loading.
+"""
+import base64
+import hashlib
+import json
+from typing import Any
+
+from raxe.infrastructure.security.auth import APIKeyValidator
+from raxe.infrastructure.security.signatures import SignatureVerifier
+
+
+class PolicyValidationError(Exception):
+    """Policy validation failed."""
+
+    pass
+
+
+class PolicyValidator:
+    """
+    Validate customer policies.
+
+    Ensures policies are:
+    1. Signed correctly (if from cloud)
+    2. Match the customer's API key
+    3. Valid schema
+    """
+
+    def __init__(self) -> None:
+        """Initialize validators."""
+        self.key_validator = APIKeyValidator()
+        self._sig_verifier: SignatureVerifier | None = None  # Lazy init only if needed
+
+    def validate_policy(self, policy_data: dict[str, Any], api_key: str) -> None:
+        """
+        Validate policy data.
+
+        Args:
+            policy_data: Policy JSON data
+            api_key: Customer's API key
+
+        Raises:
+            PolicyValidationError: If validation fails
+        """
+        # Parse API key
+        try:
+            parsed_key = self.key_validator.validate_key(api_key)
+        except Exception as e:
+            raise PolicyValidationError(f"Invalid API key: {e}") from e
+
+        # Check customer ID match
+        policy_customer_id = policy_data.get("customer_id")
+        if not policy_customer_id:
+            raise PolicyValidationError("Policy missing customer_id")
+
+        if policy_customer_id != parsed_key.customer_id:
+            raise PolicyValidationError(
+                f"Policy customer_id mismatch: "
+                f"{policy_customer_id} != {parsed_key.customer_id}"
+            )
+
+        # Verify signature if present
+        signature = policy_data.get("signature")
+        if signature:
+            self._verify_policy_signature(policy_data, signature)
+
+        # Validate schema
+        self._validate_policy_schema(policy_data)
+
+    @property
+    def sig_verifier(self) -> SignatureVerifier:
+        """Lazy-load signature verifier."""
+        if self._sig_verifier is None:
+            self._sig_verifier = SignatureVerifier()
+        return self._sig_verifier
+
+    @sig_verifier.setter
+    def sig_verifier(self, value: SignatureVerifier) -> None:
+        """Allow setting custom verifier for testing."""
+        self._sig_verifier = value
+
+    def _verify_policy_signature(
+        self, policy_data: dict[str, Any], signature: str
+    ) -> None:
+        """Verify policy signature."""
+        # Extract policies content (everything except signature)
+        policy_content = {
+            k: v
+            for k, v in policy_data.items()
+            if k not in ["signature", "signature_algorithm"]
+        }
+
+        # Hash content
+        content_str = json.dumps(policy_content, sort_keys=True)
+        content_hash = hashlib.sha256(content_str.encode()).digest()
+
+        # Verify signature
+        sig_algorithm = policy_data.get("signature_algorithm", "ed25519")
+
+        if sig_algorithm != "ed25519":
+            raise PolicyValidationError(
+                f"Unsupported signature algorithm: {sig_algorithm}"
+            )
+
+        try:
+            sig_b64 = signature.split(":", 1)[1]
+            sig_bytes = base64.b64decode(sig_b64)
+
+            self.sig_verifier.public_key.verify(sig_bytes, content_hash)
+        except Exception as e:
+            raise PolicyValidationError(f"Signature verification failed: {e}") from e
+
+    def _validate_policy_schema(self, policy_data: dict[str, Any]) -> None:
+        """Validate policy schema structure."""
+        required_fields = ["customer_id", "policies"]
+
+        for field in required_fields:
+            if field not in policy_data:
+                raise PolicyValidationError(f"Missing required field: {field}")
+
+        # Validate policies is a list
+        if not isinstance(policy_data["policies"], list):
+            raise PolicyValidationError("policies must be a list")