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.

11.0 KB
Raw Blame

Migration Guide: v3 → v4

This guide covers the breaking changes and upgrade path from AiSOC v3 to v4. Read it before running docker compose pull or deploying to production.


Table of Contents

  1. What Changed in v4
  2. Prerequisites
  3. Upgrade Steps
  4. Breaking API Changes
  5. Removed Features
  6. FAQ

What Changed in v4

Area v3 v4
Core engine Rule-based SOAR engine LangGraph multi-agent investigator
Playbook format Custom JSON (no schema) JSON Schema draft-07 (schemas/playbook.schema.json)
Plugin manifest aisoc-plugin.json only plugin.yaml (preferred) + aisoc-plugin.json (legacy)
Plugin types enricher, action, connector + responder, detection, widget
Plugin distribution Local directory only Local directory + OCI images (via oras)
API auth JWT only JWT + scoped API tokens (/api/v1/api-keys)
API schema REST only REST (OpenAPI 3.1) + GraphQL
Observability Prometheus metrics only Prometheus + OpenTelemetry traces (Jaeger/OTLP)
SDKs None Python SDK, Go SDK, TypeScript SDK
Marketplace None Community playbook & plugin marketplace

Prerequisites

  • Docker Compose v2 (docker compose version should show ≥ 2.0)
  • Python 3.11+ (for migration scripts)
  • PostgreSQL 15+ (we recommend 16)
  • 8 GB RAM available for the full stack

Upgrade Steps

Step 1 — Back up your data

# PostgreSQL
docker compose exec postgres pg_dump -U aisoc aisoc > backup_v3_$(date +%Y%m%d).sql

# ClickHouse (event store)
docker compose exec clickhouse clickhouse-client \
  --query "BACKUP DATABASE aisoc TO Disk('backups', 'aisoc_v3_$(date +%Y%m%d).zip')"

# Copy plugin directory
cp -r plugins plugins_v3_backup

Step 2 — Update environment variables

New required variables in v4 (add to your .env / Kubernetes secrets):

# OpenTelemetry — set to "none" to disable, or "otlp" for Jaeger/Tempo
OTEL_EXPORTER=none
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317

# LLM provider for the multi-agent investigator
OPENAI_API_KEY=sk-...        # or use ANTHROPIC_API_KEY
LLM_MODEL=gpt-4o             # recommended; use gpt-4o-mini for lower cost

# Qdrant (new vector store for MITRE ATT&CK embeddings)
QDRANT_URL=http://qdrant:6333

# GraphQL
ENABLE_GRAPHQL=true          # false to keep REST-only mode

# Scoped API tokens (salt for HMAC)
API_TOKEN_SIGNING_SECRET=<32-char-random-string>

Variables removed in v4:

# Remove these — the v4 engine does not use them:
RULE_ENGINE_WORKERS=
SOAR_LEGACY_MODE=
PLUGIN_SANDBOX=

Step 3 — Database migrations

v4 introduces new tables (api_keys, playbook_runs, investigation_steps). Run Alembic:

docker compose run --rm api python -m app.scripts.run_migrations

Expected output. Note this is the forward-only SQL runner, not Alembic — migrations are tracked by filename in aisoc_schema_migrations and there is no downgrade:

INFO  Found 62 migration files
INFO  59 migrations already applied; 3 pending
INFO  ✓ applied 047_alerts_rule_provenance.sql
INFO  ✓ applied 048_outcome_suppressions.sql
INFO  ✓ applied 049_data_lifecycle.sql

Step 4 — Migrate plugins

The preferred manifest file is now plugin.yaml. Existing aisoc-plugin.json files continue to work, but we recommend migrating for richer metadata support.

Automated migration (converts all plugins in ./plugins/):

python3 scripts/migrate_plugins.py

Manual migration example:

plugins/my-plugin/aisoc-plugin.json (v3):

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "type": "enricher",
  "description": "Does something useful"
}

plugins/my-plugin/plugin.yaml (v4):

id: my-plugin
name: My Plugin
version: "1.0.0"
plugin_type: enricher          # ← renamed from "type"
description: Does something useful
author: Your Name
tags: [my-tag]
min_aisoc_version: "4.0.0"
config_schema:
  type: object
  properties: {}

New plugin types available in v4 (no action required if you don't use them):

  • responder — execute response actions (block IP, isolate host, etc.)
  • detection — contribute Sigma/YARA detection rules
  • widget — add custom widgets to the SOC dashboard

Step 5 — Migrate playbooks

Playbooks are now validated against schemas/playbook.schema.json (JSON Schema draft-07).

Check your existing playbooks:

python3 scripts/lint_playbooks.py

Common breaking changes in playbook format:

v3 field v4 field Notes
type: "action" the specific verb action was a meta-type. Use block_ip, isolate_host, disable_user … — the contract belongs to the verb
type: "isolate" / "block" / "create_case" / "script" / "human_approval" isolate_host / block_ip / create_ticket / run_script / approval Renamed
on_error: "stop" on_failure: "abort" Renamed, and a plain string — not an object
retry: { max_attempts: 3 } retry_max: 3 Flattened. Backoff is not configurable; the engine uses min(2**attempt, 30) seconds
condition: { expr: "…", language: "jmespath" } condition: "…" The engine's parser is deliberately restricted: one comparison, no JMESPath, no and/or chains. The structured {field, operator, value} form also works
timeout: 60 timeout_seconds: 60 Renamed. Ceiling is 3600s
blast_radius, depends_on, output_key (removed) Declared by the v3 schema and never read by any engine. blast_radius in particular promised that "the engine enforces analyst approval for destructive steps" and the engine could not see the field. Approval is now decided per capability at dispatch — see Playbooks

loop, parallel, wait and run_playbook have no v4 equivalent. They named control flow this engine does not have — it is a single-threaded index walk — so there is no correct rewrite and the upgrader reports them rather than mapping them onto a nearest neighbour.

Auto-upgrade playbooks:

The upgrader reports before it writes, and validates its own output against schemas/playbook.schema.json before touching anything. A file whose upgrade would not validate is left alone and named.

# Report only — nothing on disk changes. Exit 1 means "something would change",
# exit 2 means a file needs a person.
python3 scripts/upgrade_playbooks.py --dir playbooks

# Apply, once the report looks right
python3 scripts/upgrade_playbooks.py --dir playbooks --write

Step 6 — Pull and restart

# Pull the latest images
docker compose pull

# Recreate all containers with the new images
docker compose up -d --remove-orphans

# Watch logs until healthy
docker compose logs -f api agents web | head -200

Step 7 — Verify

Run the built-in health check suite:

# All services healthy?
curl http://localhost:8000/api/v1/health | jq .

# GraphQL endpoint available?
curl -s -X POST http://localhost:8000/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}' | jq .

# Plugin manager loaded?
curl http://localhost:8000/api/v1/plugins | jq .[].id

# Run the public eval harness against the bundled 200-incident dataset
# (offline, no LLM call required). The dataset size is fixed — there is no
# --count flag, and the output flag is --out, not --report.
python3 scripts/run_evals.py --out eval_report.json

Expected output:

{"status":"ok","version":"4.0.0","services":{"db":"ok","redis":"ok","kafka":"ok"}}
{"data":{"__typename":"Query"}}
["okta-connector","yara-enricher","slack-quarantine","mttr-widget"]
ALL GATES PASSED (alert reduction + 3 substrate self-consistency gates)

The eval harness runs deterministic substrate code (extractors, fusion, templates, judges) against synthetic incidents. It does not call the live LLM agent. See apps/docs/docs/benchmark.md for what each suite measures.


Breaking API Changes

Authentication

Authorization: Bearer <jwt> continues to work. New scoped API tokens:

# Create a read-only token
POST /api/v1/api-keys
{ "name": "ci-reader", "scopes": ["cases:read", "alerts:read"] }

# Use it
curl -H "X-API-Key: aisoc_..." http://localhost:8000/api/v1/cases

Endpoint changes

v3 endpoint v4 endpoint Change
POST /api/v1/investigate POST /api/v1/investigations Renamed
GET /api/v1/investigate/{id} GET /api/v1/investigations/{id} Renamed
POST /api/v1/playbooks/execute POST /api/v1/playbooks/{id}/run Renamed + ID in path
GET /api/v1/plugins/list GET /api/v1/plugins Simplified
N/A POST /graphql New
N/A GET /api/v1/api-keys New

Response shape changes

Investigation responses now include audit_log and iteration fields:

{
  "case_id": "...",
  "status": "completed",
  "iteration": 4,
  "report_md": "...",
  "audit_log": [...]
}

Removed Features

Feature Reason Alternative
Legacy rule engine (SOAR_LEGACY_MODE) Replaced by LangGraph Multi-agent investigator
Plugin sandboxing (PLUGIN_SANDBOX) Too restrictive for LLM tools OCI-isolated plugins
CSV alert ingestion endpoint Low usage Use the REST API or Kafka topic
Built-in SMTP notifier Replaced by plugin slack-quarantine plugin or custom responder

FAQ

Q: Do I need an OpenAI key for v4? A: Only for the multi-agent investigator. Other features (playbooks, plugins, detections) work without an LLM key. Set LLM_PROVIDER=none to disable the investigator entirely.

Q: Can I run v3 and v4 side by side? A: Yes. Use a different Docker Compose project name: docker compose -p aisoc-v4 up -d

Q: Will my v3 playbooks still run? A: Run python3 scripts/upgrade_playbooks.py --dir playbooks first — it reports what would change without writing. Most playbooks need only the field renames above. A playbook using loop, parallel, wait, run_playbook or the generic action type needs a decision from you: those name behaviour the v4 engine does not have, and the upgrader will say so rather than guess.

Q: How do I roll back to v3 if something goes wrong? A: Restore the PostgreSQL backup from Step 1, then docker compose pull with the v3 image tags pinned in your docker-compose.yml.

Q: Where do I get help? A: Open an issue at https://github.com/beenuar/AiSOC/issues.