AiSOC

An open-source, self-hostable AI Security Operations Center. It ingests your security telemetry, detects and correlates threats, investigates them with AI agents whose reasoning is fully auditable, and proposes responses a human approves.

Docs · Architecture · What actually works · Discussions

What AiSOC does

   Your security tools  (EDR, cloud, identity, network, SIEM)
             |
   ┌─────────v────────────────────────────────────────────────┐
   │  normalize -> detect -> correlate -> investigate -> respond  │
   └─────────|────────────────────────────────────────────────┘
             v
   SOC analyst: one incident, with the evidence and the reasoning

An alert arrives. AiSOC works out whether it matters, groups it with related
signals, investigates it with an AI agent whose every prompt and tool call is
recorded, and proposes an action. A human approves before anything executes.

Quick start

git clone https://github.com/beenuar/AiSOC && cd AiSOC
make up

Needs Docker Compose v2 with 8 GB memory and 20 GB free disk in the Docker
VM, plus python3 (3.9+) and bash — make doctor checks all of it, and
Installation
says what each number was measured against. The first run downloads a ~2 GB
language model into a named volume; only make clean fetches it again.

make up also creates .env and generates the three secrets in it — the
credential-vault key, the session signing key, and the service-to-service
token — then creates an administrator and prints its password. That password
is generated on your machine, shown once, and stored nowhere: copy it before
the terminal scrolls, or mint a new one with
make bootstrap ARGS=--reset-password.

Then prove it actually works — this is the part that matters. make smoke
posts one real event to the ingest API, follows it through Kafka, detection,
correlation and Postgres, and reads the resulting alert back out of the public
API. Every stage reports PASS or FAIL:

$ make smoke
[PASS] raw telemetry accepted by ingest
[PASS] event traversed the spine and became an alert
[PASS] alert is retrievable by id from the API

Open http://localhost:3000 and sign in with the credentials make up
printed (API docs at http://localhost:8000/api/docs). Deploying somewhere
that is not your laptop? Set AISOC_CONSOLE_URL in .env so the printed
address is the one people browse to.

Something wrong? make doctor checks every dependency and says what to run next.

Try it without connecting anything

make demo

The demo dataset is synthetic. It shows the pipeline shape, not real
activity. Every row is marked is_synthetic = true in the database and
labelled in the console. It is not a benchmark, a customer, or an incident.

Connect real data

Two ways in. Push, from anything that can make an HTTP request:

curl -X POST http://localhost:8081/v1/ingest/batch \
  -H 'Content-Type: application/json' -H 'X-Tenant-ID: <tenant>' \
  -d '{"connector_id":"edr-1","connector_type":"crowdstrike","source_format":"json",
       "events":[{"severity":"high","title":"Encoded PowerShell from Office",
                  "host":"WIN-FIN-01","process_name":"powershell.exe"}]}'

Or pull, by configuring one of 84 click-and-connect data connectors in
Settings → Connectors (needs the full profile). Those with
vendor-specific normalization and live setup docs include Splunk, Microsoft
Sentinel, Elastic, CrowdStrike, Okta, AWS (GuardDuty / CloudTrail / Security
Hub), Wiz, and Kubernetes audit logs — full list in the
connector docs.
A connector without a vendor profile still ingests through a generic mapping
that resolves host, user and source IP from the usual spellings, so the alert
is pivotable either way.

How it works

See docs/architecture/README.md — it walks
one event through the whole system and every box in its diagrams links to the
code that implements it.

The short version: ingest normalizes to a common shape → Kafka carries it →
fusion runs 833 executable detection rules and decides what becomes an alert →
correlation groups related alerts into one incident → an agent investigates
and writes its reasoning to the Investigation Ledger → a human approves any
response.

Deployment profiles

CORE is the smallest deployment that takes a real event and produces a real
alert, and it needs no credentials to do either — for two reasons.

The model ships with the gateway. Ollama runs a pinned ~2 GB
llama3.2:3b-instruct-q4_K_M sized for CPU-only inference, so make up
produces real triage verdicts with real token counts in the Investigation
Ledger — not a stub. A 3B quantized model is not a frontier model; to upgrade,
set OPENAI_API_KEY, AISOC_LLM_MODEL_FAST, AISOC_LLM_MODEL_DEEP and an
empty AISOC_LLM_API_BASE in .env, then make up again. No hosted
provider has ever been exercised here — there is no funded key, so per-model
rows read not measured rather than zero, and an unmeasured cost renders as
absent, never $0.00. (ADR-0006)

One real external feed ships too. services/threatintel polls the
CISA Known Exploited Vulnerabilities
catalog — authoritative, public, no API key — into the console's Threat
Intelligence page: the one thing in a fresh install that is neither synthetic
nor yours.

Real vs synthetic data

This matters more than any feature, so it is stated plainly.

Production never silently falls back to synthetic data. When a backend is
unreachable the console shows an error, not an invented investigation. That
was not always true — see the reality audit
for the five places it was wrong and how each was fixed.

AI agents

Agents triage alerts and investigate incidents. What they can and cannot do:

• They read the alert, its correlated siblings, entity context, and prior
  verdicts for the same signature.
• They call typed tools — lake queries, graph traversals, enrichment
  lookups. The model chooses a tool and passes arguments; it never writes SQL.
• Everything is logged to the Investigation Ledger: prompts, tool calls,
  citations, the verdict, and token cost.
• Grounding is checked. A verdict citing an indicator the evidence never
  contained is demoted to human review rather than auto-closed.
• A prompt is validated before it is sent. Raw logs, OCSF payloads and
  secret-shaped values are refused, not redacted after the fact.
• Nothing executes without a human. Response actions are proposed. An
  approver must hold the required permission tier and must not be the person
  who requested the action.

CORE's bundled local model means agents reason for real out of the box. If no
model is reachable at all they run a deterministic offline path and say so —
they never fabricate a verdict.

Project maturity

What AiSOC is not

• Not a drop-in SIEM replacement. It correlates and investigates; it does
  not replace long-term log retention and compliance search.
• Not able to see telemetry you have not connected. There is no magic
  discovery.
• Not autonomous by default. Response requires explicit policy
  authorization and a human approver.
• Demo incidents are not real incidents, and benchmark corpora are not
  customer telemetry.
• Benchmark numbers are substrate self-consistency measures, not live
  agent accuracy, and are labelled as such wherever published.

Troubleshooting

make doctor diagnoses the deployment and prints the command to run next. It
checks the host tools, free memory and disk in the Docker VM, every port, each
datastore by querying it rather than by asking whether its container is up, and
whether .env still holds template placeholders. The six failures it is most
often right about — and what each one actually means — are tabulated under
Installation → Troubleshooting.

Security

Secrets live in .env, are generated per deployment, and are never committed;
connector credentials are encrypted at rest with a per-deployment key. Tenant
isolation is enforced at the query layer in every store, not by convention.
RBAC gates every mutating route. Prompts are validated before they leave the
deployment, and the default install never sends one anywhere — the model runs
beside it. Report vulnerabilities via SECURITY.md.

Developing

make test        # unit tests for every service
make smoke       # the golden pipeline, against a running stack
make stats       # recount every figure this README publishes

Guides: add a connector ·
add a detection ·
plugin lifecycle ·
contributing. The connector and detection-rule counts above
are recounted from the tree by scripts/project_stats.py, which CI fails if
this README disagrees with it.

Roadmap · Contributing · License

ROADMAP.md · CONTRIBUTING.md · SECURITY.md · MIT