kosa8 docs

Guides / Swarms and the threat feed

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.

FlagWhat it does
--fromThe running sandbox to fork. Required.
-nHow many members. Forks count against your plan's fork limit.
--allow HOSTMembers reach only these hosts. Repeat or comma-separate.
--no-internetMembers reach nothing.
--link FROM:TOLets 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:

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.

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.