Skip to content

sodejm/soc-investigation-workbench

v0.1.0PolyForm-Noncommercial-1.0.0

Plan and review local evidence-backed SOC investigations; external hunt integration remains pending.

SOC Investigation Workbench

SOC Investigation Workbench helps SOC analysts and incident responders build a local, evidence-backed case from exported security records. It preserves competing hypotheses, ranks the next investigative step, creates bounded hunt handoffs, imports immutable observations, and produces reviewable reports. It never queries a live service or assigns an analyst verdict.

Run the complete playback

Use Python 3.11 or later from the repository root. No tenant credentials or network access are required.

PYTHON="${PYTHON:-python3.11}"
"$PYTHON" -m cops demo soc-investigation-workbench

The public command creates an owner-only temporary workspace and removes it after the playback. Use the package runner directly when you need to retain the artifacts:

PYTHON="${PYTHON:-python3.11}"
PACKAGE=plugins/detection-hunting/soc-investigation-workbench
scratch="$(mktemp -d "${TMPDIR:-/tmp}/cops-soc-playback.XXXXXX")"
chmod 700 "$scratch"
OUT="$scratch/playback"
"$PYTHON" "$PACKAGE/scripts/run_demo.py" --out-dir "$OUT"
cat "$OUT/playback-summary.json"

The output directory must not already exist. mktemp creates a private parent while leaving the playback child available for the runner. The script creates that child with owner-only permissions and exercises three cases over the same synthetic tenant, workspace, entities, and UTC time window. The artifacts remain under $OUT for review. When you no longer need them, optionally remove the private parent with rm -rf "$scratch" in the same shell. The playback covers:

  • malicious: imports supporting H01 and H10 observations and ends with a supported malicious-activity hypothesis.
  • benign: imports counterfactual observations that refute malicious activity and support a benign explanation.
  • insufficient_evidence: imports failed-closed observations, records evidence gaps, revises the pending plan, and leaves both hypotheses unresolved.

Omit --out-dir for a transient qualification run. The script creates an owner-only temporary directory, removes it after either success or failure, and returns the three-case assessment as playback_summary without reporting its path. Pass an explicit new --out-dir when you need to retain and inspect the generated artifacts.

Each path executes intake, validation, next-step selection, hunt handoff, fixture evaluation, immutable evidence import, report generation, and timeline export. Success means the script checked every intermediate and final assertion. The vendored evaluator checks reference fixture semantics; it does not execute Kusto Query Language (KQL) or contact Microsoft Sentinel.

For a guided investigation, see the malicious-access walkthrough. For operations and recovery, use the analyst playbook. For package gates and vendor integrity, use the verification guide.

Manual workflow

Start a case from local exports:

PYTHON="${PYTHON:-python3.11}"
scratch="$(mktemp -d "${TMPDIR:-/tmp}/cops-soc-case.XXXXXX")"
chmod 700 "$scratch"
CASE="$scratch/incident-402.json"
HANDOFF="$scratch/incident-402-h01.json"
"$PYTHON" plugins/detection-hunting/soc-investigation-workbench/scripts/investigate.py intake \
  --case-id incident-402 \
  --tenant tenant-a \
  --workspace workspace-a \
  --start 2026-01-01T00:00:00Z \
  --end 2026-01-02T00:00:00Z \
  --sources sentinel:plugins/detection-hunting/soc-investigation-workbench/examples/intake/sentinel-incidents.json \
            splunk:plugins/detection-hunting/soc-investigation-workbench/examples/intake/splunk-events.json \
            entra:plugins/detection-hunting/soc-investigation-workbench/examples/intake/entra-signins.json \
  --out "$CASE"
"$PYTHON" plugins/detection-hunting/soc-investigation-workbench/scripts/investigate.py validate "$CASE"
"$PYTHON" plugins/detection-hunting/soc-investigation-workbench/scripts/investigate.py next "$CASE"
"$PYTHON" plugins/detection-hunting/soc-investigation-workbench/scripts/investigate.py handoff \
  "$CASE" --step signin-triage > "$HANDOFF"

The case and handoff remain in $scratch for review. When you no longer need them, optionally remove the private workspace with rm -rf "$scratch" in the same shell.

The initial evidence is deliberately unassessed. Source severity, risk labels, error codes, and successful actions are observations; an analyst must supply a reasoned assessment after reviewing relevant evidence. Empty or failed evidence cannot establish a benign outcome.

The H01 sign-in handoff carries the account and IP context. The independent H10 consent handoff carries the account and application context. Query aliases supply investigation context and do not promise server-side entity filtering.

Design and data flow

The workbench treats the case snapshot as the single versioned state object. Commands read one validated snapshot and write a new file; evidence imports preserve content hashes and reject conflicting reuse of an evidence ID. Handoffs carry the case scope and question to another tool without embedding credentials. Reports and exports present recorded observations, assessments, reasons, gaps, and the full timeline.

Contract or artifactPurposeKey fieldsProducerConsumerValidationExample
Case snapshotPreserve scoped investigation state and competing hypothesesCase, tenant, workspace, time window, entities, hypotheses, evidence gapsIntake and subsequent case commandsEvery workbench command and analystVersioned schema, scope checks, and immutable evidence identifiersincident-402 with H01 and H10 pending
Hunt handoffAsk a bounded question using case contextStep ID, hunt ID, scope, entities, questionnext and handoff commandsVendored hunt evaluator or another approved toolHunt and scope compatibility checksH01 sign-in triage for one account and IP
Evidence observationImport a content-addressed result without assigning a verdictEvidence ID, source, status, observations, SHA-256Fixture evaluator or analyst importHypothesis assessment and report generationHash verification and conflicting-ID rejectionH10 consent observation supporting malicious activity
Report and timelinePresent recorded facts, assessments, gaps, and chronologyHypothesis status, rationale, evidence references, timeline entriesReporting commandsAnalyst and incident reviewerSnapshot validation and evidence-reference integrityInsufficient-evidence report with both hypotheses unresolved
Playback summaryQualify all three synthetic pathsCase outcomes, step counts, artifact paths, assertionsscripts/run_demo.pyMaintainerSemantic assertions for malicious, benign, and failed-closed casesmalicious ends with a supported hypothesis

The Sentinel hunt catalog is a verified vendored snapshot. vendor-lock.json records its canonical source path, base revision, file hashes, snapshot hash, and license. Package validation fails closed when the snapshot is absent, modified, or inconsistent with the lock.

Package validation

PYTHON="${PYTHON:-python3.11}"
"$PYTHON" plugins/detection-hunting/soc-investigation-workbench/scripts/validate-package.py
"$PYTHON" -m pytest -q tests/step_defs/test_soc_investigation.py

The package is offered under the PolyForm Noncommercial License 1.0.0.