aisoc-sandbox 0.1.0__tar.gz

aisoc_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: aisoc-sandbox
+Version: 0.1.0
+Summary: Run an AiSOC agent investigation offline in under 30 seconds. No Docker, no API key.
+Author: AiSOC contributors
+License: MIT
+Project-URL: Homepage, https://github.com/beenuar/AiSOC
+Project-URL: Documentation, https://beenuar.github.io/AiSOC/
+Project-URL: Source, https://github.com/beenuar/AiSOC/tree/main/packages/aisoc-sandbox
+Project-URL: Issues, https://github.com/beenuar/AiSOC/issues
+Project-URL: Changelog, https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md
+Keywords: aisoc,soc,security,agent,investigation,ledger,offline
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+
+# aisoc-sandbox
+
+> Run an AiSOC agent investigation **offline in under 30 seconds**. No Docker, no API key, no network.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg)](https://github.com/beenuar/AiSOC/blob/main/LICENSE)
+[![PyPI release](https://img.shields.io/badge/pypi-not%20yet%20published-f59e0b)](https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md)
+
+`aisoc-sandbox` is the quickest possible on-ramp to [AiSOC](https://github.com/beenuar/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/`](https://github.com/beenuar/AiSOC/tree/main/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](https://github.com/beenuar/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
+
+```bash
+# 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
+
+```bash
+# 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/`](./src/aisoc_sandbox/scenarios) and is small enough to read end-to-end:
+
+| ID | Title | MITRE | Severity |
+|---|---|---|---|
+| `lateral-movement` | Impossible-travel Okta sign-in | T1078, T1078.004 | high |
+| `aws-credential-exfil` | IAM keys used from new ASN, then `s3:GetObject` flood | T1552, T1567, T1078.004 | critical |
+| `phishing-payload` | Click-through to credential-harvest page | T1566, T1566.002 | high |
+| `kubernetes-privesc` | Namespace SA bound to `cluster-admin` | T1098, T1078 | critical |
+| `github-token-theft` | PAT leaked, six private repos cloned in 11 s | T1078, T1555, T1567 | high |
+
+## 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]`](https://github.com/beenuar/AiSOC/blob/main/apps/docs/docs/console/investigation-rail.md). 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:
+
+```python
+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
+
+| | `aisoc-sandbox` | Production `services/agents/` |
+|---|---|---|
+| LLM | Deterministic template-driven stub | OpenAI / Anthropic / Ollama via LiteLLM |
+| Tool calls | Simulated as "would-call(name, args)" | Dispatched to connector / action services |
+| Persistence | In-memory; one CLI invocation | Postgres `investigation_events` table |
+| Latency | Synthetic per-stage numbers | Real LLM + tool latency |
+| Boot time | < 5 s | ~5 min cold, ~3.5 min warm |
+| Dependencies | None | Postgres + Kafka + Redis + LLM API key |
+
+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](https://github.com/beenuar/AiSOC/blob/main/LICENSE).

aisoc_sandbox-0.1.0/README.md

@@ -0,0 +1,127 @@
+# aisoc-sandbox
+
+> Run an AiSOC agent investigation **offline in under 30 seconds**. No Docker, no API key, no network.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg)](https://github.com/beenuar/AiSOC/blob/main/LICENSE)
+[![PyPI release](https://img.shields.io/badge/pypi-not%20yet%20published-f59e0b)](https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md)
+
+`aisoc-sandbox` is the quickest possible on-ramp to [AiSOC](https://github.com/beenuar/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/`](https://github.com/beenuar/AiSOC/tree/main/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](https://github.com/beenuar/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
+
+```bash
+# 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
+
+```bash
+# 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/`](./src/aisoc_sandbox/scenarios) and is small enough to read end-to-end:
+
+| ID | Title | MITRE | Severity |
+|---|---|---|---|
+| `lateral-movement` | Impossible-travel Okta sign-in | T1078, T1078.004 | high |
+| `aws-credential-exfil` | IAM keys used from new ASN, then `s3:GetObject` flood | T1552, T1567, T1078.004 | critical |
+| `phishing-payload` | Click-through to credential-harvest page | T1566, T1566.002 | high |
+| `kubernetes-privesc` | Namespace SA bound to `cluster-admin` | T1098, T1078 | critical |
+| `github-token-theft` | PAT leaked, six private repos cloned in 11 s | T1078, T1555, T1567 | high |
+
+## 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]`](https://github.com/beenuar/AiSOC/blob/main/apps/docs/docs/console/investigation-rail.md). 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:
+
+```python
+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
+
+| | `aisoc-sandbox` | Production `services/agents/` |
+|---|---|---|
+| LLM | Deterministic template-driven stub | OpenAI / Anthropic / Ollama via LiteLLM |
+| Tool calls | Simulated as "would-call(name, args)" | Dispatched to connector / action services |
+| Persistence | In-memory; one CLI invocation | Postgres `investigation_events` table |
+| Latency | Synthetic per-stage numbers | Real LLM + tool latency |
+| Boot time | < 5 s | ~5 min cold, ~3.5 min warm |
+| Dependencies | None | Postgres + Kafka + Redis + LLM API key |
+
+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](https://github.com/beenuar/AiSOC/blob/main/LICENSE).

aisoc_sandbox-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aisoc-sandbox"
+version = "0.1.0"
+description = "Run an AiSOC agent investigation offline in under 30 seconds. No Docker, no API key."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "AiSOC contributors" }]
+keywords = ["aisoc", "soc", "security", "agent", "investigation", "ledger", "offline"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+]
+
+# Zero runtime dependencies on purpose. The whole point of the sandbox
+# is that `pip install aisoc-sandbox && aisoc-sandbox demo` works on a
+# clean machine inside 30 seconds.
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=4.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/beenuar/AiSOC"
+Documentation = "https://beenuar.github.io/AiSOC/"
+Source = "https://github.com/beenuar/AiSOC/tree/main/packages/aisoc-sandbox"
+Issues = "https://github.com/beenuar/AiSOC/issues"
+Changelog = "https://github.com/beenuar/AiSOC/blob/main/CHANGELOG.md"
+
+[project.scripts]
+aisoc-sandbox = "aisoc_sandbox.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+aisoc_sandbox = ["scenarios/*.json", "py.typed"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-markers"
+testpaths = ["tests"]
+
+# Same shape as packages/sdk-py, plugin-sdk-py and aisoc-cli — the three
+# package trees that already declare one. `python_version` is pinned to 3.11
+# even though the wheel supports 3.10+: the baseline has to be reproducible,
+# and 3.11 is the interpreter CI runs.
+[tool.mypy]
+strict = true
+python_version = "3.11"

aisoc_sandbox-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

aisoc_sandbox-0.1.0/src/aisoc_sandbox/__init__.py

@@ -0,0 +1,42 @@
+"""aisoc-sandbox: run an AiSOC agent investigation offline in under 30 seconds.
+
+This package is the quickest possible on-ramp to AiSOC: no Docker, no
+Postgres / Kafka / Redis, no API key, no network — `aisoc-sandbox demo`
+walks one alert fixture through a Detect → Triage → Hunt → Respond
+agent funnel and prints a step-by-step Investigation Ledger to stdout.
+
+It is a deterministic, in-memory simulator of the production stack at
+[`services/agents/`](https://github.com/beenuar/AiSOC/tree/main/services/agents).
+The shape of the ledger, the funnel stages, the decision metadata, and
+the recommended actions all mirror what the real four-agent system in
+the monorepo emits. The simulator is intentionally NOT the production
+graph: the production graph requires Postgres + Kafka + an LLM API
+key, and a 30-second offline demo cannot afford any of those.
+
+When you're ready to run the real stack: `pnpm aisoc:demo`.
+
+Public entry points:
+
+  - :class:`Investigation`  — one investigation run.
+  - :class:`Ledger`         — the step-by-step record.
+  - :func:`load_scenario`   — load a built-in or user-supplied scenario.
+  - :func:`run_investigation` — high-level orchestrator (used by the CLI).
+"""
+
+from __future__ import annotations
+
+from .investigation import Investigation, run_investigation
+from .ledger import Ledger, LedgerStep
+from .scenarios import Scenario, available_scenarios, load_scenario
+
+__all__ = [
+    "Investigation",
+    "Ledger",
+    "LedgerStep",
+    "Scenario",
+    "available_scenarios",
+    "load_scenario",
+    "run_investigation",
+]
+
+__version__ = "0.1.0"

aisoc_sandbox-0.1.0/src/aisoc_sandbox/cli.py

@@ -0,0 +1,150 @@
+"""aisoc-sandbox — command-line entry point.
+
+The two visible subcommands are ``demo`` and ``scenarios``:
+
+  * ``aisoc-sandbox demo`` runs one full Detect → Triage → Hunt →
+    Respond funnel against a bundled or user-supplied scenario and
+    prints the Investigation Ledger to stdout. ``--json`` switches
+    the output to a machine-readable form.
+
+  * ``aisoc-sandbox scenarios`` lists the bundled scenarios so a user
+    can pick one with ``--scenario <id>`` without reading the docs.
+
+Exit codes follow UNIX convention:
+
+  0  success — investigation ran and the ledger was emitted.
+  2  invalid arguments (bad scenario id, missing file, etc).
+  3  internal error during the run.
+
+There is no networked path in this CLI. If you `strace` it you should
+see exactly one ``read`` of the scenario file, zero ``connect`` syscalls.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from typing import Sequence
+
+from . import __version__
+from .investigation import run_investigation
+from .ledger import Ledger
+from .scenarios import available_scenarios, emit_scenario_index, load_scenario
+
+
+_PROG = "aisoc-sandbox"
+_DESCRIPTION = "Run an AiSOC agent investigation offline in under 30 seconds. No Docker, no API key, no network."
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog=_PROG,
+        description=_DESCRIPTION,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Examples:\n"
+            "  aisoc-sandbox demo\n"
+            "  aisoc-sandbox demo --scenario aws-credential-exfil\n"
+            "  aisoc-sandbox demo --file my-alert.json --json\n"
+            "  aisoc-sandbox scenarios\n"
+        ),
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True, metavar="<command>")
+
+    demo = sub.add_parser(
+        "demo",
+        help="Walk one scenario through the Detect → Triage → Hunt → Respond funnel.",
+    )
+    demo.add_argument(
+        "--scenario",
+        choices=available_scenarios(),
+        default="lateral-movement",
+        help="Bundled scenario id (default: %(default)s).",
+    )
+    demo.add_argument(
+        "--file",
+        metavar="PATH",
+        help="Path to a custom scenario JSON. Overrides --scenario when set.",
+    )
+    demo.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit the ledger as a JSON document instead of the human view.",
+    )
+
+    sub.add_parser(
+        "scenarios",
+        help="List the bundled scenarios and exit.",
+    )
+    return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "scenarios":
+        emit_scenario_index()
+        return 0
+
+    if args.command == "demo":
+        try:
+            scenario = load_scenario(args.scenario, file=args.file)
+        except (FileNotFoundError, ValueError) as exc:
+            print(f"{_PROG}: error: {exc}", file=sys.stderr)
+            return 2
+
+        ledger = Ledger()
+        started = time.perf_counter()
+        try:
+            run_investigation(scenario, ledger=ledger)
+        except Exception as exc:  # noqa: BLE001 — surface to the user, exit 3.
+            print(f"{_PROG}: investigation crashed: {exc}", file=sys.stderr)
+            return 3
+        elapsed_ms = int((time.perf_counter() - started) * 1000)
+
+        if args.json:
+            payload = {
+                "tool": _PROG,
+                "version": __version__,
+                "scenario": scenario.to_dict(),
+                "ledger": ledger.to_dict(),
+                "elapsed_ms": elapsed_ms,
+            }
+            print(json.dumps(payload, indent=2, ensure_ascii=False))
+            return 0
+
+        # Human view: brief preamble, then the rendered ledger.
+        _print_preamble(scenario)
+        ledger.render_human()
+        print(
+            f"Ran {len(ledger)} steps in {elapsed_ms} ms.\n"
+            "Ready for the real stack? `pnpm aisoc:demo` from a fresh clone of\n"
+            "  https://github.com/beenuar/AiSOC\n"
+        )
+        return 0
+
+    # argparse refused to leave us here, but Pylance doesn't know that.
+    parser.print_help()
+    return 2
+
+
+def _print_preamble(scenario: object) -> None:
+    sc = scenario  # narrow for the type-checker
+    # We don't depend on rich so the package stays zero-dep. The
+    # output uses plain text + ANSI; piping to a file produces clean
+    # text via Ledger.render_human's TTY-aware colour code.
+    print(f"\nScenario: {sc.id}")
+    print(f"Title:    {sc.title}")
+    if sc.narrative:
+        print(f"Narrative: {sc.narrative}")
+    if sc.mitre_techniques:
+        print(f"MITRE:    {', '.join(sc.mitre_techniques)}")
+    print(f"Severity: {sc.severity}\n")
+
+
+if __name__ == "__main__":  # pragma: no cover — covered by smoke test.
+    sys.exit(main())