Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

14.2 KB
Raw Blame
"""
Action models for the Action Execution Service.
"""

from __future__ import annotations

from datetime import datetime
from enum import Enum
from typing import Any
from uuid import UUID, uuid4

from pydantic import BaseModel, Field


class ActionType(str, Enum):
    BLOCK_IP = "block_ip"
    BLOCK_DOMAIN = "block_domain"
    ISOLATE_HOST = "isolate_host"
    DISABLE_USER = "disable_user"
    RESET_PASSWORD = "reset_password"
    KILL_PROCESS = "kill_process"
    QUARANTINE_FILE = "quarantine_file"
    CAPTURE_FORENSICS = "capture_forensics"
    NOTIFY_SLACK = "notify_slack"
    CREATE_TICKET = "create_ticket"
    # `add_ioc_to_blocklist` and `run_playbook` were here and had no executor
    # behind either of them, so the API accepted both and answered "No
    # executor found for action type" — which reads as a broken deployment
    # rather than a verb nobody built. Neither was a missing implementation:
    #
    #   add_ioc_to_blocklist  a second name for `block_ioc`, which has a
    #                         Defender arm, a contract, an adapter and a place
    #                         in the vocabulary. Two names for one verb means
    #                         half the callers reach the dead one.
    #   run_playbook          playbook execution lives in services/agents and
    #                         always has. It is also the wrong shape for this
    #                         registry: the contract belongs to the verb, and
    #                         "run an arbitrary bundle of verbs" has no
    #                         verb-level impact, reversal or probe. Approving
    #                         it once would execute whatever steps it contains
    #                         without each one meeting its own contract, which
    #                         is precisely what the per-capability contract
    #                         exists to prevent. Playbooks dispatch step by
    #                         step through this service instead, so every step
    #                         is graded on the way past — via
    #                         `services/agents/app/playbook/action_bridge.py`
    #                         and `POST /api/v1/playbook-steps/dispatch`.
    #
    #                         That last sentence was not true when it was
    #                         written. `_handle_block_ip` and
    #                         `_handle_isolate_host` returned
    #                         `{"simulated": True}` from inside the engine and
    #                         reached no executor, and twelve further step
    #                         types had no handler at all. The bridge named
    #                         above is what made it true; the named modules
    #                         are here so the claim can be checked rather than
    #                         taken on trust.
    # ChatOps user verification: outbound interactive Slack/Teams prompt
    # asking the affected user to confirm or deny an event ("Was this you?").
    # The response is HMAC-validated and routed back into the case timeline.
    CHATOPS_VERIFY = "chatops_verify"
    # WS-E: Live vendor integration action types
    # CrowdStrike Falcon RTR
    RUN_SCRIPT = "run_script"
    # AWS Security Groups / Network
    ALLOW_IP = "allow_ip"
    # Microsoft Defender for Endpoint
    BLOCK_IOC = "block_ioc"
    RUN_AV_SCAN = "run_av_scan"
    # Okta identity response
    SUSPEND_SESSION = "suspend_session"
    FORCE_MFA = "force_mfa"
    # SIEM actions (Splunk + Elastic)
    SEARCH_SIEM = "search_siem"
    CREATE_NOTABLE_EVENT = "create_notable_event"
    SYNC_DETECTION_RULE = "sync_detection_rule"
    UPDATE_WATCHER = "update_watcher"
    # Phase 3.3 — alert lifecycle dispatch. Both verbs are SIEM/EDR
    # agnostic; the executor picks Splunk / Elastic / MDE based on
    # which credentials are present in the request.
    ACK_ALERT = "ack_alert"
    SUPPRESS_ALERT = "suppress_alert"
    # Two-way SIEM loop: project an AiSOC verdict onto the vendor finding that
    # raised the alert. Distinct from ack/suppress because the disposition —
    # not the caller — decides whether the finding is closed or escalated.
    UPDATE_ALERT_DISPOSITION = "update_alert_disposition"
    # Depth 7.1 — mailbox remediation for reported phish. Present here, and
    # not only in the capability vocabulary, because the post-action verifier
    # is keyed by ActionType: a verb absent from this enum can declare a
    # probe and never have it reached, which the contract gate now refuses.
    # `purge_email` is the one verb in the product whose blast radius is a
    # property of the dispatch rather than of the verb, so the entry in
    # ACTION_BLAST_RADIUS below is its single-mailbox floor and
    # `capability_contracts.scaled_impact` raises it per campaign.
    #
    # `search_mailboxes` is deliberately absent: it is read-only, declares no
    # verification probe, and so needs nothing this enum provides. Adding it
    # anyway would put a read on the ungoverned `POST /actions` surface for
    # no gain. Its arms are native read executors in `investigation_reads`.
    PURGE_EMAIL = "purge_email"
    RESTORE_EMAIL = "restore_email"
    BLOCK_SENDER = "block_sender"
    UNBLOCK_SENDER = "unblock_sender"


class ActionStatus(str, Enum):
    PENDING = "pending"
    AWAITING_APPROVAL = "awaiting_approval"
    APPROVED = "approved"
    REJECTED = "rejected"
    #: Claimed for execution. Written to the durable store *before* the vendor
    #: is contacted and never only afterwards, so a replica that dies
    #: mid-dispatch leaves a record that cannot be mistaken for one nobody
    #: started. The member always existed; nothing wrote it.
    RUNNING = "running"
    COMPLETED = "completed"
    FAILED = "failed"
    #: The dispatch did not come back clean and the vendor could not be read
    #: back, so whether the estate changed is genuinely unknown.
    #:
    #: Its absence was the defect. A containment the EDR had accepted, whose
    #: response was then lost, was recorded as ``failed`` — the reading whose
    #: obvious remedy is to run it again. Nothing here may be re-approved;
    #: ``POST /actions/{id}/reconcile`` resolves it by asking the vendor.
    #:
    #: Not a terminal success: `services/api`'s usage meter counts `completed`
    #: as the one status meaning a vendor was touched, and that stays true.
    RECONCILIATION_REQUIRED = "reconciliation_required"
    ROLLED_BACK = "rolled_back"


class BlastRadius(str, Enum):
    MINIMAL = "minimal"  # Notification-only, no infra changes
    LOW = "low"  # Reversible, limited scope
    MEDIUM = "medium"  # Affects single resource, reversible
    HIGH = "high"  # Affects multiple resources or users
    CRITICAL = "critical"  # Broad impact, potential service disruption


# Map action types to their blast radius levels
ACTION_BLAST_RADIUS: dict[ActionType, BlastRadius] = {
    ActionType.BLOCK_IP: BlastRadius.MEDIUM,
    ActionType.BLOCK_DOMAIN: BlastRadius.MEDIUM,
    ActionType.ISOLATE_HOST: BlastRadius.HIGH,
    ActionType.DISABLE_USER: BlastRadius.HIGH,
    ActionType.RESET_PASSWORD: BlastRadius.MEDIUM,
    ActionType.KILL_PROCESS: BlastRadius.MEDIUM,
    ActionType.QUARANTINE_FILE: BlastRadius.LOW,
    ActionType.CAPTURE_FORENSICS: BlastRadius.LOW,
    ActionType.NOTIFY_SLACK: BlastRadius.MINIMAL,
    ActionType.CREATE_TICKET: BlastRadius.MINIMAL,
    ActionType.CHATOPS_VERIFY: BlastRadius.MINIMAL,
    # WS-E live vendor action blast radii
    ActionType.RUN_SCRIPT: BlastRadius.HIGH,
    ActionType.ALLOW_IP: BlastRadius.MEDIUM,
    ActionType.BLOCK_IOC: BlastRadius.MEDIUM,
    ActionType.RUN_AV_SCAN: BlastRadius.LOW,
    ActionType.SUSPEND_SESSION: BlastRadius.HIGH,
    ActionType.FORCE_MFA: BlastRadius.MEDIUM,
    ActionType.SEARCH_SIEM: BlastRadius.MINIMAL,
    ActionType.CREATE_NOTABLE_EVENT: BlastRadius.LOW,
    ActionType.SYNC_DETECTION_RULE: BlastRadius.MEDIUM,
    ActionType.UPDATE_WATCHER: BlastRadius.MEDIUM,
    # Phase 3.3 — ack is just a status flip on a triage queue,
    # suppress is more impactful because it removes the alert from
    # an analyst's view. We rate suppression as LOW (not MEDIUM)
    # because there's a documented unsuppress path in every vendor.
    ActionType.ACK_ALERT: BlastRadius.MINIMAL,
    ActionType.SUPPRESS_ALERT: BlastRadius.LOW,
    # The one member that had no entry, which meant it had no single blast
    # radius: four call sites read this table with two different fallbacks,
    # `blast_radius.py` to MEDIUM and the three tier gates to HIGH. So the
    # legacy door auto-executed the writeback while the registry door held it
    # for a whitelist it could never match — the same verb, two grades,
    # decided by a default nobody chose. LOW is what its own contract asks
    # for: "classified the same as create_notable_event ... it changes a
    # queue item, not an estate", and create_notable_event is LOW.
    ActionType.UPDATE_ALERT_DISPOSITION: BlastRadius.LOW,
    # Depth 7.1 — mailbox remediation. The purge entry is the floor for one
    # mailbox; `BlastRadiusGate` reads this table and cannot see a recipient
    # count, so the campaign-scaled grading happens in the capability
    # contract where the parameters are in scope. MEDIUM is already above
    # `_AUTO_EXECUTE_LIMIT`'s sibling tiers for the legacy door's purposes
    # and `APPROVAL_REQUIRED_ACTIONS` below makes the point unconditional.
    ActionType.PURGE_EMAIL: BlastRadius.MEDIUM,
    ActionType.RESTORE_EMAIL: BlastRadius.LOW,
    ActionType.BLOCK_SENDER: BlastRadius.LOW,
    ActionType.UNBLOCK_SENDER: BlastRadius.LOW,
}

# Actions that require explicit human approval
APPROVAL_REQUIRED_ACTIONS = {
    ActionType.ISOLATE_HOST,
    ActionType.DISABLE_USER,
    ActionType.RESET_PASSWORD,
    ActionType.KILL_PROCESS,
    ActionType.RUN_SCRIPT,
    ActionType.SUSPEND_SESSION,
    ActionType.BLOCK_IOC,
    ActionType.SYNC_DETECTION_RULE,
    # Removing somebody's mail is never automatic, whatever the autonomy
    # tier. The capability contract says the same thing through the matrix;
    # this is the legacy door saying it too, because the two doors
    # disagreeing about one verb is the defect `test_approval_doors_agree`
    # exists to catch.
    ActionType.PURGE_EMAIL,
    ActionType.BLOCK_SENDER,
}


# Wave 4 (W4.2) — least-privilege permission required to EXECUTE each action,
# derived from its blast radius. A principal must hold this permission (or a
# broader one — see `authz.has_action_permission`). MINIMAL/LOW → :low,
# MEDIUM → :medium, HIGH/CRITICAL → :high.
def _perm_for_blast(blast: BlastRadius) -> str:
    if blast in (BlastRadius.HIGH, BlastRadius.CRITICAL):
        return "actions:execute:high"
    if blast == BlastRadius.MEDIUM:
        return "actions:execute:medium"
    return "actions:execute:low"


ACTION_REQUIRED_PERMISSION: dict[ActionType, str] = {action: _perm_for_blast(blast) for action, blast in ACTION_BLAST_RADIUS.items()}


class ActionPrincipal(BaseModel):
    """The authenticated identity on whose behalf an action runs (W4.1).

    Propagated from the API's authenticated user into the actions service so
    execution + approval can be scoped to that user's real permissions —
    replacing the free-text ``requested_by`` string as the authorization basis.
    """

    user_id: str
    tenant_id: UUID | None = None
    email: str | None = None
    roles: list[str] = Field(default_factory=list)
    permissions: list[str] = Field(default_factory=list)


class ChatOpsApprover(BaseModel):
    """A platform identity a bot has already verified (T3.6).

    Carries identity and deliberately **not** permissions. The bot proves who
    clicked — Slack signs the interaction payload, Teams payloads are
    HMAC-signed — but it has no knowledge of what that person may do in AiSOC,
    and a bot permitted to assert its own permissions could grant itself
    anything. The actions service maps this onto a principal.
    """

    platform: str
    platform_user_id: str
    display_name: str | None = None


class ActionRequest(BaseModel):
    """Request to execute an action."""

    id: UUID = Field(default_factory=uuid4)
    incident_id: UUID
    tenant_id: UUID
    action_type: ActionType
    target: str
    parameters: dict[str, Any] = Field(default_factory=dict)
    requested_by: str = "system"
    # W4.1 — structured invoking identity. Optional for back-compat with the
    # legacy `requested_by` string + system-initiated calls.
    principal: ActionPrincipal | None = None
    #: Who originally asked for this action, when that is not the caller.
    #:
    #: Three identities meet on an approved action and collapsing any two
    #: breaks a control. `principal` is the *invoking* identity whose
    #: permissions gate the submit; the approver arrives separately on the
    #: approve call; and this is the originator, read only for separation of
    #: duties and provenance, never for authorization.
    #:
    #: It exists because `services/api` had nowhere to put the originator and
    #: sent the deciding console user as `principal`, which became
    #: `requested_by_user_id`. Separation of duties then compared the approver
    #: against itself and refused: every approval raised in the responder app
    #: was answered 403 upstream and surfaced as a 502. The free-text
    #: `requested_by` beside this is a label and is deliberately not used for
    #: the comparison — it is caller-supplied and trusting it would make the
    #: control forgeable in the other direction.
    requester: ActionPrincipal | None = None
    rationale: str = ""
    auto_rollback: bool = False
    rollback_after_seconds: int | None = None
    #: How sure the finding behind this action is, 0.0-1.0.
    #:
    #: The second axis of the approval matrix. ``None`` is the lowest band,
    #: not a free pass — a caller that omits it gets the most restrictive
    #: treatment, because the alternative is that a scoring bug becomes an
    #: autonomous containment.
    confidence: float | None = Field(default=None, ge=0.0, le=1.0)


class ActionResult(BaseModel):
    """Result of an executed action."""

    action_id: UUID
    status: ActionStatus
    blast_radius: BlastRadius
    output: dict[str, Any] = Field(default_factory=dict)
    error: str | None = None
    rollback_data: dict[str, Any] = Field(default_factory=dict)
    executed_at: datetime = Field(default_factory=datetime.utcnow)
    completed_at: datetime | None = None