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.
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
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 versionshould 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 ruleswidget— 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.