# NS-2026-1008 — SOC Incident Response case study

> **Controlled simulated environment.** All identities, infrastructure,
> telemetry, indicators and incidents in this repository are synthetic.
> Addresses use RFC 5737 documentation ranges (`192.0.2.0/24`,
> `198.51.100.0/24`, `203.0.113.0/24`). There are no real credentials, keys,
> people or organisations here, and no working exploit code. The "malware" is
> an inert stub.

A complete, evidence-driven incident-response investigation built the honest
way round: **environment → attack → telemetry → validation → investigation →
findings → write-up**. The telemetry is generated first and is the source of
truth; every conclusion in the report cites an evidence ID that resolves to an
exact raw record whose SHA-256 is recorded.

**Incident:** valid-account intrusion into a synthetic B2B SaaS environment,
root privilege escalation, three persistence mechanisms, lateral movement to a
workstation, and a confirmed bulk export of customer data.

## Quick start

```bash
python3 scripts/generate_dataset.py --check   # byte-identical regeneration
( cd data && sha256sum -c SHA256SUMS )        # file integrity
python3 scripts/verify_evidence.py --strict   # 65/65 citations resolve
python3 scripts/build_notebook.py --check     # notebook reproduces from data
bash detections/tests/run-tests.sh            # 8/8 detections validated
bash scripts/queries/q00-all-queries.sh       # the investigation queries
```

Requires only `python3`, `jq` and coreutils.

## What is here

| Path | Contents |
| --- | --- |
| `data/` | The synthetic telemetry (auth, auditd, syslog, Windows Security/PowerShell, flows, firewall, DNS, PostgreSQL, nginx) |
| `data/SHA-256SUMS` | Hashes of every data file |
| `evidence/manifest.yaml` | 65 evidence records: timestamp, host, source, classification, raw-record SHA-256, interpretation |
| `evidence/chain.md` | The chain of evidence from first failure to eradication |
| `timeline/timeline.csv` | Machine-generated from the manifest — cannot drift |
| `detections/sigma/` | Seven Sigma rules derived from the observed behaviour |
| `detections/queries/` | The same logic as runnable shell queries |
| `detections/tests/` | Golden outputs + harness; before/after tuning is executable |
| `hunts/` | Four threat hunts with real (including negative) results |
| `notebook/` | Standard-library analysis notebook (reproducible outputs) |
| `iocs/` | IOC database with mandatory provenance and classification |
| `attack-mapping/` | ATT&CK techniques, each tied to evidence |
| `incident-report/` | The full investigation report |
| `uncertainty.md` | What could not be established, and why |
| `lab/` | Environment design + how to reproduce the investigation |
| `scripts/` | Deterministic generator, verifier, timeline builder, queries |

## The evidence hierarchy

Conclusions are labelled, not asserted:

- **FACT** — directly recorded by one source.
- **CORROBORATED FACT** — supported independently by two or more sources.
- **INFERENCE** — strongly supported but not directly observed.
- **HYPOTHESIS** — proposed, testable, not yet established.
- **UNRESOLVED** — cannot be settled from available evidence.
- **DISPROVEN** — searched and positively not found.

Findings additionally carry certainty labels: **CONFIRMED, CORROBORATED,
PROBABLE, SUSPECTED, UNRESOLVED, DISPROVEN, BENIGN**.

## Reproducibility contract

- `scripts/generate_dataset.py` is deterministic. `--check` regenerates the
  dataset and fails if any committed file differs.
- `scripts/verify_evidence.py --strict` re-reads every cited record, re-hashes
  it, and fails if a citation does not resolve or a data file is unreferenced.
- `scripts/build_timeline.py` derives the timeline from the same manifest, so
  the timeline cannot claim an event the dataset does not contain.
- `detections/tests/run-tests.sh` runs every detection against the dataset and
  diffs against golden output.

## Reading order

1. `lab/environment.md` — the environment.
2. `data/README.md` — what each file is and its fidelity.
3. `incident-report/incident-report.md` — the investigation.
4. `evidence/manifest.yaml` — the raw records behind every claim.
5. `detections/README.md` — the detection engineering.
6. `uncertainty.md` — what remains unknown.

## Licence and use

Case study material. The synthetic key in `data/linux/app01_authorized_keys.txt`
is a public key with no private counterpart in this repository and must not be
reused.