aisoc-sandbox

Run an AiSOC agent investigation offline in under 30 seconds. No Docker, no API key, no network.

aisoc-sandbox is the quickest possible on-ramp to AiSOC. It walks one alert fixture through a four-stage agent funnel — Detect → Triage → Hunt → Respond — using a deterministic offline reasoner in place of a real LLM, and prints the resulting Investigation Ledger to your terminal.

It is the simulator-equivalent of the production services/agents/ graph, collapsed into a single zero-dependency Python package. When you're ready to run the real stack: pnpm aisoc:demo from a fresh clone of AiSOC.

Why this exists

The production AiSOC stack needs Postgres, Kafka, Redis, an LLM API key, and ~5 minutes to boot. That's the right cost for a buyer evaluating against their own alert data — but it's the wrong cost for a developer who just wants to see how the agent reasons before they commit their evening.

This package collapses the boot time to < 5 seconds and the disk footprint to < 50 KB. The trade-off is that the reasoning is deterministic and the tools are simulated (not executed); see "Differences from the production stack" below.

Install

# Today (from this monorepo):
git clone https://github.com/beenuar/AiSOC.git
cd AiSOC && pip install -e packages/aisoc-sandbox

# Once published to PyPI (ready, unpublished — the upload is blocked on
# registry credentials, which is an account action, not a code change):
#   pip install aisoc-sandbox
#   pipx run aisoc-sandbox demo

Python 3.10+ on Linux / macOS / Windows. Zero runtime dependencies.

Quick start

# Walk the default scenario (lateral-movement) through the funnel
aisoc-sandbox demo

# Pick a different bundled scenario
aisoc-sandbox demo --scenario aws-credential-exfil

# Use your own scenario JSON
aisoc-sandbox demo --file ./my-alert.json

# Machine-readable output
aisoc-sandbox demo --scenario phishing-payload --json | jq

# What scenarios are bundled?
aisoc-sandbox scenarios

Bundled scenarios

Five scenarios ship with the package; each one is a single JSON file under src/aisoc_sandbox/scenarios/ and is small enough to read end-to-end:

What you'll see

Each aisoc-sandbox demo run emits a four-step ledger:

Investigation Ledger
  4 steps · 12 ms total · synthetic offline run (no LLM, no Docker)

Step  0  DETECT  DetectAgent  (3 ms)
  Action     Match incoming events against detection ruleset
  Rationale  2 event(s) ingested; matched detection ruleset against MITRE techniques T1078, T1078.004.
  · events_ingested: 2
  · mitre_techniques: ['T1078', 'T1078.004']
  · severity_at_intake: high
  · entity:user: alice@example.com
  → would-call rules.match({"rule_count": "800+", ...})
  → would-call fusion.score({"window_minutes": 15})
  Decision   Open alert at severity=high

Step  1  TRIAGE  TriageAgent  (3 ms)
  Action     Score alert confidence + cross-reference with prior cases
  Rationale  Authenticated session signals look legitimate at the protocol layer, but the geo pivot between sequential events is physically impossible — classic credential takeover.
  ...

The shape mirrors the production Investigation Rail at /alerts/[id]. The four stages, the evidence chips, and the "Decision" lines are the same — only the LLM rationale and tool execution are simulated.

Library use

The package's surface is small enough to embed:

from aisoc_sandbox import load_scenario, run_investigation

scenario = load_scenario("aws-credential-exfil")
ledger = run_investigation(scenario)

# Iterate the steps
for step in ledger:
    print(step.step, step.agent, step.action, step.decision)

# Or render to a stream (TTY-aware colour)
ledger.render_human()

# Or serialise
print(ledger.to_json())

Differences from the production stack

This is on purpose. The sandbox is the on-ramp, not a replacement: it gives you 30-second visibility into how the funnel hangs together so you can decide whether the full demo is worth the 5-minute boot.

License

MIT — see the repo LICENSE.