History

max 02b9d0a645 Tier 3 + Tier 4 deploy runbook in AGENTS.md Repo has all the code paths for Tier 3 (real exploit fire via msfrpcd) and Tier 4 (real malware execution via chunked upload), but neither lab host has run a single Tier-3 episode because msfrpcd and the Metasploitable2 image aren't deployed there. 3009 episodes in flight to date are all Tier 2 (mimic workloads in clean Alpine), which is useful pipeline-validation data but cannot answer the actual research question. This commit makes the deploy push-button: - AGENTS.md: new "Tier 3 + Tier 4 deploy" section listing the three prereqs (install-msfrpcd.sh, fetch-metasploitable2.sh, setup_bridge.sh), the foreground verify command (run_tier3_demo.py), and the Tier-4 promotion path (MB API key → fetch_sample.py → manifest edit → orchestrator restart). - samples/manifest.toml: clearer per-entry comment showing the 4-step sha256 → real-binary promotion path. Replaces the earlier "TBD" placeholder which suggested a single edit unlocks Tier 4 when in fact you need to fetch the binary too. The fleet runner already auto-detects msfrpcd (orchestrator/fleet.py _msfrpcd_available()); once the lab-host operator-AI lands the prereqs, episodes flip to Tier 3 with no orchestrator config change. Tier 4 follows automatically the next time the deterministic selector picks a sample whose sha256 file exists in samples/store/.		2026-04-30 22:57:23 -05:00
..
__init__.py	Collectors 2/4/5 + fleet runner + sample manifest + Tier-3 setup scripts	2026-04-30 00:02:27 -05:00
manifest.py	Close out the open issues: bridge pcap wiring, perf collector, Tier-4	2026-04-30 00:17:49 -05:00
manifest.toml	Tier 3 + Tier 4 deploy runbook in AGENTS.md	2026-04-30 22:57:23 -05:00
README.md	Close out the deployment-readiness gaps	2026-04-30 00:31:55 -05:00

README.md

samples/

Catalog of malware (or behaviour-matched mimics) the fleet draws from. Sample binaries are NEVER committed to this repo.

What's here

manifest.toml      schema-checked catalog (loaded by samples/manifest.py)
manifest.py        loader + per-(host_id, slot, ep) deterministic selection
store/             SHA-256-pinned binary content (gitignored — never commit)
.bazaar.token      MalwareBazaar API key (mode 0600, gitignored)

Manifest schema

Each entry in manifest.toml:

[[sample]]
name        = "xmrig-cryptominer"   # unique within manifest, DNS-safe
family      = "XMRig"               # canonical family label for ML
category    = "cryptominer"         # one of: cryptominer, botnet, ransomware,
                                    # banking-trojan, fileless, rat, worm,
                                    # loader, wiper, other
profile     = "cpu-saturate"        # behaviour profile from
                                    # exploits/workloads.py — gates the
                                    # in-session shell workload when no
                                    # real binary is staged
description = "..."

# Optional — present iff this is a real binary the fetcher should pull:
sha256 = "abc123..."
source = "MalwareBazaar"
url    = "https://bazaar.abuse.ch/sample/abc123/"

The loader rejects unknown categories and duplicate names. See tests/test_fleet.py for the property tests covering selection distribution + catalog walkability.

"real" vs "mimic"

Sample.kind is "real" when sha256 is set, otherwise "mimic".

Mimic — the orchestrator runs the matching profile-shaped shell command (cpu-saturate / scan-and-dial / io-walk / bursty-c2 / low-and-slow / shell-resident) inside the guest. No real binary needed; useful right now for testing the dataset pipeline and as the realistic-but-safe envelope class the trainer expects.
Real — the orchestrator's Tier-3+ driver chunked-uploads samples/store/<sha256> into the shell session, sha256-verifies on the guest side, and execs it. Hash mismatch fail-stops the run; a tampered binary is never executed.

meta.sample.kind lands in every episode's meta.json, so trainers can stratify on it (the realistic-model path consumes only kind == "real" episodes by default).

Fetching a real binary

# 1. Register a (free) account at https://bazaar.abuse.ch and get the API key.
echo "<your-key>" > samples/.bazaar.token
chmod 0600 samples/.bazaar.token

# 2. Add an entry with sha256+source+url to manifest.toml.

# 3. Pull the binary into samples/store/<sha256>:
uv run python tools/fetch_sample.py <sha256>

Idempotent — re-running checks the staged copy's sha256 and skips the download if it already matches.

Per-(host, slot, episode) selection

manifest.py::SampleManifest.select(host_id, slot, episode_index) hashes those three into a uniform integer and indexes the catalog. Two lab hosts on the same slot pick different samples (collision rate ~1/N). A single host walks the whole catalog within ~len(manifest) episodes. No coordinator.

Safety rules

Only download to a lab host, never to a developer workstation. samples/store/ lives only there, gitignored, on a disk that is not auto-mounted elsewhere.
The lab host's br-malware bridge is host-only by design (no NAT, no route). Real malware running in the guest cannot call out unless the operator explicitly opens egress, which we don't.
Snapshot/revert (see EpisodeConfig.revert_at_* + qmp.savevm/ loadvm) means every fresh episode starts from a known-good baseline regardless of what the previous one did to the guest.
The fetcher verifies sha256 on download; the driver verifies again in-guest before exec. Both layers must match the manifest.

Adding a sample

Pick a family + category from the closed enum above.
Pick a profile from exploits/workloads.all_profiles(). If the sample's behaviour doesn't match any of the six existing shapes, add a new factory to exploits/workloads.py first, with tests.
(Real-only) Compute sha256, fetch via tools/fetch_sample.py, verify the staged file's hash matches.
Append the entry to manifest.toml.
Run the test suite — the manifest loader's invariants catch typos.