Commands / kosa8 lab detonate
kosa8 lab detonate
Run a sample in a fakenet sandbox and write a signed report
Usage
kosa8 detonate SAMPLE --image IMAGE [--timeout 2m] [--cmd "sh {sample}" | -- ARGV...]
Boots a new sandbox whose egress is fakenet with a packet capture from its first frame, starts a container from --image, checks that the host is enforcing fakenet, copies the sample to /kosa8-sample/NAME and runs it. It watches for --timeout (the whole of it, unless --stop-on-exit: a dropper that exits at once usually leaves a child running), snapshots the machine with the sample still in it, then records the process list, the files changed against the image, every fakenet interaction and the capture's digests.
The snapshot is sealed and the report signed with --signer-key (or this machine's key), and written to --out as a package: REPORT.json, REPORT.md, the seal and a signed manifest. The sandbox is stopped afterwards unless --keep; the infected state lives on in the sealed snapshot, for fork and restore.
How the sample runs: by default it is executed directly (an ELF, or a script with a #! line). --cmd gives a command line split on spaces, where {sample} is the sample's path: --cmd "python3 {sample}". Arguments after -- are used as the argv exactly, for arguments with spaces.
The image must have sleep; uname and ps are used when present. It is
pulled by the host if the sandbox does not have it. To have programs trust the
simulated HTTPS, build the image with the lab CA installed (kosa8 lab ca).
Running a sample is an escalating action: under an approval policy it needs a signed approval for exactly this sample digest, image, command and timeout.
Options
| Flag | Type | What it does | Default |
|---|---|---|---|
--cmd | string | command line that runs the sample, split on spaces; {sample} is its path | — |
--cpus | uint | vCPUs for the lab sandbox | 2 |
--image | string | image to run the sample in (required); pulled by the host if the sandbox lacks it | — |
--keep | bool | leave the sandbox running afterwards, sample and all, still on fakenet | — |
--memory | uint64 | memory in MiB for the lab sandbox | 1024 |
--name | string | name for the lab sandbox (default lab-DIGEST-TIME) | — |
--no-seal | bool | do not seal the snapshot (the report then says so, and names no seal) | — |
--out | string | report package to write: a .tar, or a directory (default kosa8-detonation-DIGEST-TIME.tar) | — |
--reason | string | meaning of the seal on the infected snapshot (default names the sample) | — |
--signer | string | the analyst's printed name (default: the current OS user) | — |
--signer-key | string | Ed25519 private key that seals the snapshot and signs the report (default: this machine's key) | — |
--stop-on-exit | bool | end the observation when the sample's process exits, instead of at the timeout | — |
--timeout | string | how long to observe the sample (5s to 2h) | 2m |
Example
kosa8 lab detonate ./dropper.elf --image alpine:3.20 --timeout 3m
kosa8 lab detonate ./stage1.py --image python:3.12-alpine --cmd "python3 {sample}"
kosa8 lab verify kosa8-detonation-*.tar --pubkey analyst.pub --sample ./dropper.elf