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.

6.0 KB
Raw Blame
/**
 * Playbook / SOAR automation types.
 *
 * These mirror `schemas/playbook.schema.json` and the runtime model in
 * `services/agents/app/playbook/models.py`, and
 * `scripts/check_playbook_schema_parity.py` fails the build when they drift.
 *
 * They used to describe a different product. The previous version declared a
 * 28-member `ActionType` union (`notify_email`, `create_ticket_jira`,
 * `collect_forensics`, `run_query_splunk`, …) that matched neither the schema
 * nor the engine, a `PlaybookStep.action: ActionConfig` shape the engine does
 * not parse, `depends_on` / `run_parallel` / `blast_radius_check` fields
 * nothing reads, and `waiting_approval` / `paused` run states the engine
 * cannot enter — it is a single-threaded index walk with no pause or resume.
 * Nothing imported it, so the drift was invisible; a shared-types package
 * that is wrong is worse than one that is absent, because the next person to
 * import it inherits a contract the server will reject.
 */

/** What can start a playbook. Mirrors `trigger.on` in the schema. */
export type PlaybookTrigger = "alert" | "case" | "manual" | "schedule";

/**
 * Every step type the engine accepts. Mirrors `StepType`.
 *
 * What the engine *does* with each one is published in the schema's
 * `x-aisoc-execution` map and reflected in {@link StepExecution} below —
 * accepting a step type and performing it are different claims, and the
 * distinction is the point.
 */
export type StepType =
  | "enrich"
  | "investigate"
  | "notify"
  | "block_ip"
  | "block_ioc"
  | "isolate_host"
  | "create_ticket"
  | "close_case"
  | "http"
  | "condition"
  | "wait"
  | "parallel"
  | "loop"
  | "osquery_live_query"
  | "approval"
  | "verify_user"
  | "ask_model"
  | "disable_user"
  | "reset_password"
  | "revoke_session"
  | "force_mfa"
  | "kill_process"
  | "quarantine_file"
  | "run_av_scan"
  | "run_script"
  | "search_siem"
  | "create_notable_event";

/**
 * What happens when a step of a given type runs.
 *
 * - `executed` — a handler runs and has a real effect.
 * - `governed` — the step is dispatched to the action registry in
 *   `services/actions`, where the capability contract and the tenant's
 *   autonomy policy decide whether a vendor is touched. Whether one *was* is
 *   answered per run by {@link StepDispatchReport.executed}, never assumed.
 * - `unimplemented` — no handler; the engine fails the step closed rather
 *   than reporting a success it did not achieve.
 */
export type StepExecution = "executed" | "governed" | "unimplemented";

/**
 * Guard on a step. Either the structured form or an expression string.
 *
 * The expression parser is deliberately restricted to one comparison: no
 * `and`/`or` chains, no function calls, no `eval`.
 */
export interface StepCondition {
  field?: string;
  operator?: "eq" | "ne" | "gt" | "lt" | "contains" | "exists";
  value?: unknown;
  expression?: string;
}

export interface PlaybookStep {
  id: string;
  name: string;
  type: StepType;
  /** Free-form per-verb arguments. Each executor declares its own shape. */
  params?: Record<string, unknown>;
  condition?: StepCondition | string;
  on_failure?: "abort" | "continue" | "retry";
  /** Ceiling is 25 (`bounds.ABSOLUTE_MAX_RETRIES`). */
  retry_max?: number;
  /** 1..3600 seconds (`bounds.ABSOLUTE_MAX_TIMEOUT_SECONDS`). */
  timeout_seconds?: number;
  /** Step id to jump to. The engine branches; it does not build a DAG. */
  next_true?: string;
  next_false?: string;
  /**
   * Child steps, for `parallel` (run concurrently, then joined) and `loop`
   * (run in order, once per item). Empty for every other type: the engine
   * fails a `parallel` or `loop` that declares none rather than reporting a
   * success for work it did not do.
   */
  steps?: PlaybookStep[];
}

export interface Playbook {
  id?: string;
  name: string;
  description?: string;
  version?: string;
  tags?: string[];
  trigger?: {
    on?: PlaybookTrigger;
    [key: string]: unknown;
  };
  steps: PlaybookStep[];
  author?: string;
  enabled?: boolean;
  created_at?: string;
  updated_at?: string;
  /**
   * Authored documentation the engine does not read. Declared because real
   * playbooks carry them and a schema that rejected them would be wrong;
   * named here so nobody mistakes them for behaviour.
   */
  inputs?: Record<string, unknown>;
  dry_run_support?: boolean;
}

/** Mirrors `RunStatus`. There is no `paused` and no `waiting_approval`. */
export type PlaybookRunStatus = "pending" | "running" | "completed" | "failed" | "cancelled";

/** Mirrors `StepStatus`. */
export type PlaybookStepStatus = "pending" | "skipped" | "running" | "success" | "failed";

/**
 * What a governed response step reports back.
 *
 * `executed` is the single field that means a vendor was actually touched. A
 * preview, an approval queue, a blocked action and a tenant with no
 * integration are all `false`, and `status` says which.
 */
export interface StepDispatchReport {
  capability: string;
  status:
    | "executed"
    | "awaiting_completion"
    | "dry_run"
    | "simulated"
    | "pending_approval"
    | "blocked"
    | "no_integration"
    | "unsupported"
    | "failed";
  executed: boolean;
  summary: string;
  vendor_id?: string;
  detail?: string;
  /** Absent when the action did not run: there is nothing to read back. */
  verification?: "verified" | "failed" | "unverified";
  verification_reason?: string;
  autonomy_mode?: string;
  blast_radius?: string;
}

export interface PlaybookStepResult {
  step_id: string;
  name: string;
  status: PlaybookStepStatus;
  /** The handler's return value. For a governed step, a {@link StepDispatchReport}. */
  result?: Record<string, unknown>;
  /** Set on a `condition` step: the step id the engine jumped to. */
  branch?: string;
}

export interface PlaybookRun {
  run_id: string;
  playbook_id: string;
  playbook_name: string;
  status: PlaybookRunStatus;
  /** Trigger context plus every step's flattened output. */
  context: Record<string, unknown>;
  step_results: PlaybookStepResult[];
  started_at: string;
  finished_at: string;
  error?: string | null;
}