# Swarms and the threat feed

A **swarm** is a group of agents forked from one prepared sandbox. Each member is its own microVM with one shared network policy. The **threat feed** is one list of blocked hosts for every sandbox. A block reaches running sandboxes within seconds and every new one after that.

## Start a swarm

Prepare one sandbox the way every agent should start: tools installed, evidence copied in. Then fork it.

```
$ kosa8 swarm up triage --from agent-base -n 8 --allow api.openai.com
$ kosa8 swarm status triage
$ kosa8 swarm ls
```

`swarm up` saves the parent as the swarm's start point, then makes members `triage-1` to `triage-8`, labelled `swarm=triage`. Members start with their network closed and get the swarm's policy before they run anything.

| Flag | What it does |
|---|---|
| `--from` | The running sandbox to fork. Required. |
| `-n` | How many members. Forks count against your plan's fork limit. |
| `--allow HOST` | Members reach only these hosts. Repeat or comma-separate. |
| `--no-internet` | Members reach nothing. |
| `--link FROM:TO` | Lets members matching FROM send files to members matching TO. Globs allowed. |

## Members stay apart

Members cannot reach each other over the network, or your local network. They pass files only with `swarm send`, and only along links you allowed. Every send is in the audit log, allowed or refused.

```
$ kosa8 swarm up triage --from agent-base -n 4 --link 'triage-*:triage-4'
$ kosa8 swarm send triage triage-1 triage-4 /workspace/findings.json
```

PATH may be any path in the guest, and it overwrites what the target has there.

## Anomalies

kosa8 compares members with each other and flags the odd one out:

- **rare host:** a member tried a host no other member tried (swarms of 3 or more).

- **egress spike:** more than 10 times the swarm's median traffic.

- **denied burst:** 20 or more refused connections.

Each anomaly is written once to the audit log as `swarm.anomaly`, so it reaches your SIEM through audit forwarding. Anomalies are alerts. They block nothing on their own.

## The kill switch

```
$ kosa8 swarm pause triage     # every member, at once
$ kosa8 swarm resume triage
$ kosa8 swarm rewind triage    # every member back to the start point
$ kosa8 swarm kill triage      # pause all; cannot be resumed
$ kosa8 swarm kill triage --rm # also delete the members and the start point
```

A killed swarm cannot be resumed or rewound. Start a new swarm instead. The web app and the desktop app have the same controls, with **Pause all** at the top of each swarm.

## The threat feed

```
$ kosa8 threat block evil.example --reason "C2 seen in triage-2"
$ kosa8 threat block '*.evil.example' --reason "whole domain"
$ kosa8 threat block 203.0.113.0/24 --reason "scanner range"
$ kosa8 threat ls
$ kosa8 threat unblock evil.example
```

Every entry is added as a deny to every sandbox's network policy. It only ever narrows a policy: a sandbox never reaches more than its own rules allow. A blocked name is refused at DNS; block the address or range too if a program may already know it.

`kosa8 lab detonate` adds the hosts a sample contacted to the feed, marked `lab`. Pass `--no-feed` to skip that. An org's approval policy can require sign-off to unblock a host.

## On kosa8 Cloud

```
$ kosa8 cloud swarm up triage --from sbx_7f3a -n 20
$ kosa8 cloud swarm status triage
$ kosa8 cloud threat block evil.example --reason "C2"
```

The same verbs, for your organization. A block applies to every running and sleeping sandbox in the organization. Only admins can unblock. The API is `/v1/swarms` and `/v1/threats`; see the [OpenAPI reference](https://docs.kosa8.com/guides/cloud-openapi/).

**Not on Cloud yet.** `swarm send`, links and `rewind` are local only. On Cloud, the rare-host anomaly is not reported yet, because hosts report traffic totals, not host names.

## Where it runs

Swarms need fork support: Apple silicon Macs, x86-64 Linux with KVM, and kosa8 Cloud. On the container backend (Windows without WSL2 and hosts without KVM), `swarm up` says so and makes nothing. The threat feed works wherever kosa8 enforces network rules.

---
Source: https://docs.kosa8.com/guides/swarm/
