# Tutorial: Blue-team honeypot operations (advanced)

**Audience:** SOC analysts, detection engineers, and blue-team operators who
already understand containment, evidence handling, and ATT&CK-oriented triage.

**Time:** 45-90 minutes (depending on optional microVM / purple-team steps)  
**Outcome:** You stand up a research lab, exercise emergency/containment paths,
run purple-team fingerprint checks, and extract structured intel: without
widening real egress or treating the decoy as a jump host.

!!! danger "Do not Internet-expose unfinished sensors"
    Default research binds are loopback. Production / Internet claims require
    verified Gates 0-7 evidence. See [M2 claim status](../assurance/m2-claim-status.md)
    and [safety model](../explanation/safety-model.md).

## Learning objectives

1. Separate **attacker-facing** decoy surfaces from **operator/SOC** ground truth
2. Operate emergency actions (`STATIC_ONLY` / drain / isolate / local-stop)
3. Run continuous purple-team + stealth health checks
4. Pull MITRE/IOC yield from interactive sessions
5. Know when microVM / JA4S / public ingress is still residual scaffolding

## Prerequisites

| Required | Optional (advanced) |
|----------|---------------------|
| Docker Engine/Desktop | Linux host with `/dev/kvm` + Firecracker |
| Repo checkout + `make doctor` / `make build` as needed | Ops Pack (Grafana/Loki) via `make ops-up` |
| Familiarity with SSH/HTTP tooling | External scanners (`nmap`, JA4S tools) for `make external-scan` |

Start from a clean machine state: no leftover research compose.

```bash
make research-down 2>/dev/null || true
make ops-web build
./bin/ops-gui -doctor
```

## Part A: Lab with operator ground truth

### A1. Start Ops (loopback)

```bash
export CYBERHALLUCINET_REPO_ROOT="$PWD"
./bin/ops-gui -addr 127.0.0.1:3080
```

Open Manage/Launch. Prefer a **full_internal** or multi-service lab if your Ops
build supports it; otherwise SSH+HTTP is enough for this tutorial.

### A2. Confirm plane separation

| Plane | Where | You should see |
|-------|--------|----------------|
| Attacker | Decoy ports (`:2222`, `:8081`, …) | Persona fiction only, no containment mode tokens |
| Operator | Ops Manage / private status | True mode, health, telemetry pressure |

If you probe decoy HTTP `/healthz`, it must **not** leak containment mode,
broker wiring, or protocol inventory. Ops-facing status remains the source of
truth ([SOC ground-truth separation](../security/containment.md)).

### A3. Baseline interact

```bash
curl -sS http://127.0.0.1:8081/ | head
ssh -p 2222 -o StrictHostKeyChecking=no lab@127.0.0.1
```

Record session depth (commands, uploads). Do **not** copy attacker-uploaded
binaries to analyst laptops: use quarantine / evidence vault paths only
([guest abuse containment](../security/guest-abuse-containment.md),
[evidence handling](../security/evidence-handling-stub.md)).

## Part B: Emergency and containment drills

Work from the **management plane**, never by SSHing “as root” into the decoy
to “fix” it.

### B1. Status

```bash
./bin/honeypotctl emergency status
```

### B2. Static-only (AI off, listeners may remain)

```bash
./bin/honeypotctl emergency static-only --yes
```

Re-check decoy responses and Manage: attacker-facing view may look like an
outage/maintenance fiction; **SOC/ops must still show true `STATIC_ONLY`**.

### B3. Isolate / local-stop

```bash
./bin/honeypotctl emergency isolate --yes
# or full local stop:
./bin/honeypotctl emergency local-stop
```

Confirm listeners withdrawn and tombstone/kill-switch behavior per
[emergency how-to](../how-to/emergency.md) and [RB-CONT-ISOLATE](../soc/runbooks.md).

### B4. Rebuild lab

Relaunch from Ops Launch (or `make research-up`) only after isolate/stop is
understood. Prefer signed images in production; research rebuilds from compose.

## Part C: Purple-team and stealth assurance

These targets exercise fingerprint / advml / fidelity scaffolding. They do
**not** by themselves authorize Internet exposure.

```bash
make stealth-health-check
make purple-team
make external-scan   # nmap/JA4S optional; skips cleanly if tools missing
```

Review outputs under `evidence/gates/purple-team/` and
`evidence/gates/external-scan/`.

Interpret residuals honestly:

- Stock Go TLS may still be the research face until a live JA4S sidecar exists
- MicroVM guest boot needs pinned `vmlinux` + KVM ([microVM README](../../deploy/microvm/README.md))
- Documented residuals live in [protocol fingerprints](../architecture/protocol-fingerprints.md)

## Part D: Detection yield (ATT&CK / IOCs)

After an interactive session (or from a captured event stream in your lab):

1. Prefer structured extraction via `agti.ExtractIntelligence` (engine): MITRE
   techniques + IOCs + `DET-*` suggestions
2. Attach the record to a case; do **not** treat auto-tags as attribution
3. Follow [detections](../soc/detections.md) and [runbooks](../soc/runbooks.md)

If Ops Pack is up (`make ops-up`), correlate sensor spool / OTLP pressure with
Grafana/Loki: sensors must not hold sink credentials
([ops stack](../how-to/ops-stack.md)).

## Part E, Optional microVM path (Linux + KVM)

Only on a disposable Linux lab host with `/dev/kvm` and Firecracker:

```bash
# Provide a Firecracker-compatible vmlinux, then:
export MICROVM_KERNEL_SRC=/path/to/vmlinux
make microvm-artifacts
# pin digests, then opt-in start (see deploy/microvm/README.md)
CYBERHALLUCINET_MICROVM_START=1 make microvm-up
```

Default research remains **virtual shell**. Guest start refuse-closed without
digest pins / KVM. Attacker uploads stay **noexec**.

## Part F: Change and cover-identity governance (read-through)

Before any non-lab persona/grammar/LoRA rollout:

- [Deception change governance](../governance/deception-change-governance.md) : 
  signed digests, dual approval, canary/rollback
- [Cover identity governance](../governance/cover-identity-governance.md) : 
  no real-org impersonation; CT-log permanence; teardown/burn

## Checkpoint

- [ ] Lab up on loopback; decoy ≠ ops ground truth
- [ ] `static-only` / isolate / local-stop exercised from management plane
- [ ] `make purple-team` (and stealth-health-check) ran
- [ ] At least one intel/runbook path reviewed
- [ ] You did **not** open public ingress without verified gates

## Related references

| Topic | Doc |
|-------|-----|
| Containment modes / kill switch | [containment.md](../security/containment.md) |
| Network isolation checklist | [network-isolation.md](../security/network-isolation.md) |
| Honeypot IR (breakout / jailbreak) | [honeypot-ir-runbook.md](../soc/honeypot-ir-runbook.md) |
| CLI emergencies | [honeypotctl](../reference/honeypotctl.md) |
| Beginner path | [beginner-student-lab.md](beginner-student-lab.md) |