sec-audit-rules 0.1.0a2__py3-none-any.whl

sec_audit/enforcement/__init__.py

@@ -0,0 +1,41 @@
+from sec_audit.enforcement.actions import (
+    ALERT_SEVERITY,
+    BLOCKING_ACTIONS,
+    DEFAULT_BLOCK_SCOPES,
+    PERSISTENT_ACTIONS,
+    TEMPORARY_ACTIONS,
+    RuleAction,
+    effective_action_ttl,
+    resolve_rule_action,
+)
+from sec_audit.enforcement.blocks import (
+    BlockEntry,
+    BlockScope,
+    BlockStore,
+)
+from sec_audit.enforcement.config import EnforcementAuditConfig
+from sec_audit.enforcement.policies import (
+    EnforcementDecision,
+    EnforcementPolicy,
+    SeverityEnforcementPolicy,
+    highest_severity_match,
+)
+
+__all__ = [
+    'ALERT_SEVERITY',
+    'BLOCKING_ACTIONS',
+    'BlockEntry',
+    'BlockScope',
+    'BlockStore',
+    'DEFAULT_BLOCK_SCOPES',
+    'EnforcementAuditConfig',
+    'EnforcementDecision',
+    'EnforcementPolicy',
+    'PERSISTENT_ACTIONS',
+    'RuleAction',
+    'SeverityEnforcementPolicy',
+    'TEMPORARY_ACTIONS',
+    'effective_action_ttl',
+    'highest_severity_match',
+    'resolve_rule_action',
+]

sec_audit/enforcement/actions.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping
+
+from sec_audit.enforcement.policies import EnforcementDecision
+from sec_audit.rules.base import RuleMatch
+
+TEMPORARY_ACTIONS = {'temp_block'}
+PERSISTENT_ACTIONS = {'persist_block'}
+BLOCKING_ACTIONS = {'block', 'temp_block', 'persist_block'}
+ALERT_SEVERITY = 4
+DEFAULT_BLOCK_SCOPES = ('ip',)
+
+
+@dataclass(frozen=True)
+class RuleAction:
+    action: str
+    ttl: int | None = None
+    scopes: tuple[str, ...] = DEFAULT_BLOCK_SCOPES
+    status_code: int | None = None
+    message: str | None = None
+
+
+def _configured_rule_action(spec: object) -> RuleAction:
+    if isinstance(spec, str):
+        return RuleAction(action=spec)
+    data = dict(spec) if isinstance(spec, Mapping) else {}
+    scopes = data.get('scopes') or DEFAULT_BLOCK_SCOPES
+    if isinstance(scopes, str):
+        scopes = (scopes,)
+    return RuleAction(
+        action=str(data.get('action') or 'observe'),
+        ttl=data.get('ttl'),
+        scopes=tuple(str(scope) for scope in scopes),
+        status_code=data.get('status_code'),
+        message=data.get('message'),
+    )
+
+
+def _match_block_ttl(match: RuleMatch, default_ttl: int | None) -> int | None:
+    ttl = match.metadata.get('block_ttl', match.metadata.get('ttl'))
+    if ttl is None and match.decision == 'temp_block':
+        ttl = default_ttl or 300
+    return int(ttl) if ttl is not None else None
+
+
+def effective_action_ttl(
+    rule_action: RuleAction,
+    match: RuleMatch,
+    default_ttl: int | None,
+) -> int | None:
+    return rule_action.ttl or _match_block_ttl(match, default_ttl) or default_ttl
+
+
+def resolve_rule_action(
+    match: RuleMatch,
+    *,
+    configured_actions: Mapping[str, object],
+    block_rules: Mapping[str, int],
+    default_ttl: int | None,
+    policy_decision: EnforcementDecision | None = None,
+    default_action: str = 'observe',
+) -> RuleAction:
+    configured = configured_actions.get(match.rule_name)
+    if configured is not None:
+        return _configured_rule_action(configured)
+    if match.rule_name in block_rules:
+        return RuleAction(action='temp_block', ttl=block_rules[match.rule_name])
+    if match.decision in BLOCKING_ACTIONS or match.decision in {'alert', 'observe'}:
+        return RuleAction(
+            action=str(match.decision),
+            ttl=_match_block_ttl(match, default_ttl),
+        )
+    if policy_decision is not None and not policy_decision.allowed:
+        return RuleAction(
+            action='block',
+            status_code=policy_decision.status_code,
+            message=policy_decision.message,
+        )
+    if default_action == 'alert':
+        return RuleAction(action='alert')
+    if default_action in BLOCKING_ACTIONS:
+        return RuleAction(
+            action=str(default_action),
+            ttl=_match_block_ttl(match, default_ttl),
+        )
+    return RuleAction(action='observe')

sec_audit/enforcement/blocks.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from types import MappingProxyType
+from typing import Mapping, Protocol, Sequence
+
+DEFAULT_BLOCK_MESSAGE = 'Request blocked by audit enforcement policy'
+
+
+@dataclass(frozen=True)
+class BlockScope:
+    scope_type: str
+    scope_value: str
+
+    def __post_init__(self) -> None:
+        scope_type = str(self.scope_type).strip()
+        scope_value = str(self.scope_value).strip()
+        if not scope_type:
+            raise ValueError('scope_type cannot be empty.')
+        if not scope_value:
+            raise ValueError('scope_value cannot be empty.')
+        object.__setattr__(self, 'scope_type', scope_type)
+        object.__setattr__(self, 'scope_value', scope_value)
+
+
+@dataclass(frozen=True)
+class BlockEntry:
+    scope: BlockScope
+    reason: str = ''
+    rule_name: str = ''
+    status_code: int = 429
+    message: str = DEFAULT_BLOCK_MESSAGE
+    created_at: datetime | None = None
+    expires_at: datetime | None = None
+    revoked_at: datetime | None = None
+    metadata: Mapping[str, object] | None = field(default=None)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self, 'metadata', MappingProxyType(dict(self.metadata or {}))
+        )
+
+
+class BlockStore(Protocol):
+    def block(
+        self,
+        scope: BlockScope,
+        *,
+        reason: str = '',
+        rule_name: str = '',
+        status_code: int = 429,
+        message: str = DEFAULT_BLOCK_MESSAGE,
+        ttl: int | None = None,
+        metadata: Mapping[str, object] | None = None,
+    ) -> BlockEntry: ...
+
+    def unblock(self, scope: BlockScope, *, reason: str = '') -> int: ...
+
+    def get_active(self, scope: BlockScope) -> BlockEntry | None: ...
+
+    def first_active(self, scopes: Sequence[BlockScope]) -> BlockEntry | None: ...

sec_audit/enforcement/config.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping
+
+from sec_audit.core.config_validation import int_value, str_value
+from sec_audit.core.exceptions import AuditConfigurationError
+
+RULE_ACTIONS = {'observe', 'alert', 'block', 'temp_block', 'persist_block'}
+
+
+@dataclass(frozen=True)
+class EnforcementAuditConfig:
+    enforcement_block_severity: int | None = None
+    enforcement_status_code: int = 429
+    enforcement_message: str = 'Request blocked by audit enforcement policy'
+    block_cache_ttl: int = 300
+    block_rules: dict[str, int] = field(default_factory=dict)
+    rule_actions: dict[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.enforcement_block_severity is not None:
+            severity = int_value(
+                'enforcement_block_severity', self.enforcement_block_severity
+            )
+            if severity < 0 or severity > 10:
+                raise AuditConfigurationError(
+                    'enforcement_block_severity must be None or between 0 and 10.'
+                )
+            object.__setattr__(self, 'enforcement_block_severity', severity)
+        status_code = int_value('enforcement_status_code', self.enforcement_status_code)
+        if status_code < 100 or status_code > 599:
+            raise AuditConfigurationError(
+                'enforcement_status_code must be an HTTP status code.'
+            )
+        object.__setattr__(self, 'enforcement_status_code', status_code)
+        object.__setattr__(
+            self,
+            'enforcement_message',
+            str_value('enforcement_message', self.enforcement_message),
+        )
+        block_cache_ttl = int_value('block_cache_ttl', self.block_cache_ttl)
+        if block_cache_ttl < 0:
+            raise AuditConfigurationError(
+                'block_cache_ttl must be greater than or equal to 0.'
+            )
+        object.__setattr__(self, 'block_cache_ttl', block_cache_ttl)
+        object.__setattr__(self, 'block_rules', _validate_block_rules(self.block_rules))
+        object.__setattr__(
+            self, 'rule_actions', _validate_rule_actions(self.rule_actions)
+        )
+
+
+def _validate_block_rules(value: object) -> dict[str, int]:
+    if not isinstance(value, Mapping):
+        raise AuditConfigurationError('block_rules must be a mapping.')
+    parsed = {}
+    for rule_name, ttl in value.items():
+        parsed[str(rule_name)] = int_value('block_rules TTL', ttl)
+        if parsed[str(rule_name)] <= 0:
+            raise AuditConfigurationError('block_rules TTLs must be positive.')
+    return parsed
+
+
+def _validate_rule_actions(value: object) -> dict[str, object]:
+    if not isinstance(value, Mapping):
+        raise AuditConfigurationError('rule_actions must be a mapping.')
+    parsed = {}
+    for rule_name, spec in value.items():
+        if isinstance(spec, str):
+            normalized = {'action': spec}
+        elif isinstance(spec, Mapping):
+            normalized = dict(spec)
+        else:
+            raise AuditConfigurationError(
+                'rule_actions values must be action strings or mappings.'
+            )
+        action = normalized.get('action')
+        if not isinstance(action, str) or action not in RULE_ACTIONS:
+            raise AuditConfigurationError(
+                f'rule_actions action for {rule_name!r} must be one of: '
+                f'{", ".join(sorted(RULE_ACTIONS))}.'
+            )
+        if 'ttl' in normalized and normalized['ttl'] is not None:
+            normalized['ttl'] = int_value('rule_actions ttl', normalized['ttl'])
+            if normalized['ttl'] <= 0:
+                raise AuditConfigurationError('rule_actions ttl must be positive.')
+        if 'status_code' in normalized and normalized['status_code'] is not None:
+            normalized['status_code'] = int_value(
+                'rule_actions status_code', normalized['status_code']
+            )
+            if normalized['status_code'] < 100 or normalized['status_code'] > 599:
+                raise AuditConfigurationError(
+                    'rule_actions status_code must be an HTTP status code.'
+                )
+        if 'scopes' in normalized and isinstance(normalized['scopes'], str):
+            raise AuditConfigurationError('rule_actions scopes must be a sequence.')
+        parsed[str(rule_name)] = normalized
+    return parsed

sec_audit/enforcement/policies.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Mapping, Protocol, Sequence
+
+from sec_audit.rules.base import RuleMatch
+from sec_audit.rules.events import RuleEvent
+
+
+@dataclass(frozen=True)
+class EnforcementDecision:
+    allowed: bool = True
+    status_code: int = 429
+    message: str = 'Request blocked by audit enforcement policy'
+    reason: str | None = None
+
+
+class EnforcementPolicy(Protocol):
+    def decide(
+        self,
+        event: RuleEvent | Mapping[str, object],
+        matches: Sequence[RuleMatch],
+    ) -> EnforcementDecision: ...
+
+
+def highest_severity_match(matches: Sequence[RuleMatch]) -> RuleMatch | None:
+    best = None
+    for match in matches:
+        if best is None or match.severity > best.severity:
+            best = match
+    return best
+
+
+class SeverityEnforcementPolicy:
+    def __init__(
+        self,
+        *,
+        block_severity: int | None = 8,
+        status_code: int = 429,
+        message: str = 'Request blocked by audit enforcement policy',
+    ) -> None:
+        self.block_severity = (
+            int(block_severity) if block_severity is not None else None
+        )
+        self.status_code = int(status_code)
+        self.message = message
+
+    def decide(
+        self,
+        event: RuleEvent | Mapping[str, object],
+        matches: Sequence[RuleMatch],
+    ) -> EnforcementDecision:
+        if self.block_severity is None:
+            return EnforcementDecision()
+        triggering = highest_severity_match(
+            [match for match in matches if match.severity >= self.block_severity]
+        )
+        if triggering is None:
+            return EnforcementDecision()
+        return EnforcementDecision(
+            allowed=False,
+            status_code=self.status_code,
+            message=self.message,
+            reason=triggering.rule_name,
+        )

sec_audit/integrations/wazuh/__init__.py

@@ -0,0 +1,3 @@
+from sec_audit.integrations.wazuh.api import WazuhAPISource
+
+__all__ = ['WazuhAPISource']

sec_audit/integrations/wazuh/api.py

@@ -0,0 +1,69 @@
+import time
+
+
+class WazuhAPISource:
+    def __init__(
+        self,
+        *,
+        base_url: str = 'https://localhost:55000',
+        username: str = 'admin',
+        password: str = 'admin',
+        verify_ssl: bool = False,
+    ) -> None:
+        import httpx
+
+        self.base_url = base_url.rstrip('/')
+        self.username = username
+        self.password = password
+        self._session = httpx.Client(verify=verify_ssl)
+        self._token = None
+        self._token_expiry = 0.0
+
+    def _authenticate(self) -> bool:
+        now = time.time()
+        if self._token and now < self._token_expiry - 30:
+            return True
+        try:
+            resp = self._session.post(
+                f'{self.base_url}/security/user/authenticate',
+                json={},
+                auth=(self.username, self.password),
+                timeout=3,
+            )
+            resp.raise_for_status()
+            self._token = resp.json()['data']['token']
+            self._token_expiry = now + 3600
+            return True
+        except Exception:
+            return False
+
+    def is_available(self) -> bool:
+        return self._authenticate()
+
+    def request(self, method: str, path: str, **kwargs):
+        if not self._authenticate():
+            return None
+        headers = kwargs.pop('headers', {})
+        headers['Authorization'] = f'Bearer {self._token}'
+        try:
+            resp = self._session.request(
+                method,
+                f'{self.base_url}{path}',
+                headers=headers,
+                timeout=kwargs.pop('timeout', 15),
+                **kwargs,
+            )
+            resp.raise_for_status()
+            return resp.json()
+        except Exception:
+            return None
+
+    def get_agents(self):
+        result = self.request(
+            'GET', '/agents', params={'select': 'id,name,status,lastKeepAlive'}
+        )
+        return (result or {}).get('data', {})
+
+    def get_manager_info(self):
+        result = self.request('GET', '/manager/info')
+        return (result or {}).get('data', {})

sec_audit/integrations/wazuh/rules/0375-sec-audit.xml

@@ -0,0 +1,7 @@
+<group name="sec_audit,">
+  <rule id="100080" level="3">
+    <decoded_as>json</decoded_as>
+    <field name="attributes.schema_version">1.0</field>
+    <description>sec_audit event</description>
+  </rule>
+</group>

sec_audit/integrations/wazuh/rules/sigma/audit-rule-match.yml

@@ -0,0 +1,8 @@
+title: sec_audit rule match
+logsource:
+  product: python
+detection:
+  selection:
+    attributes.event_type: audit.rule.match
+  condition: selection
+level: medium

sec_audit/rules/__init__.py

@@ -0,0 +1,50 @@
+from sec_audit.rules.base import (
+    ContextRequirements,
+    Rule,
+    RuleContext,
+    RuleMatch,
+    ScopeContext,
+    ScopedHistoryReader,
+)
+from sec_audit.rules.builtins import (
+    BruteForceLoginRule,
+    LoginThrottleRule,
+    RepeatedClientErrorRule,
+    RepeatedRouteRule,
+    RequestBodyThresholdRule,
+    SensitiveFieldChangeRule,
+    SuspiciousProxyHeaderRule,
+)
+from sec_audit.rules.config import RulesAuditConfig
+from sec_audit.rules.engine import RuleEngine
+from sec_audit.rules.events import RuleEvent, SummaryKey
+from sec_audit.rules.history import (
+    HistoryScopeExtractor,
+    ScopeKey,
+    build_history_scope_extractors,
+    extract_scope_keys,
+)
+
+__all__ = [
+    'BruteForceLoginRule',
+    'ContextRequirements',
+    'LoginThrottleRule',
+    'RepeatedClientErrorRule',
+    'RepeatedRouteRule',
+    'RequestBodyThresholdRule',
+    'Rule',
+    'RuleContext',
+    'RuleEngine',
+    'RuleEvent',
+    'RuleMatch',
+    'RulesAuditConfig',
+    'ScopeContext',
+    'ScopeKey',
+    'ScopedHistoryReader',
+    'SensitiveFieldChangeRule',
+    'SuspiciousProxyHeaderRule',
+    'SummaryKey',
+    'HistoryScopeExtractor',
+    'build_history_scope_extractors',
+    'extract_scope_keys',
+]