# 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.

## Flags

| 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
```

---
Source: https://docs.kosa8.com/reference/lab-detonate/