# Security

## How to report a vulnerability

Email **security@i9.io**. Include:

- the version, from `i9 --version`;
- your platform (operating system, version and CPU architecture);
- the steps that reproduce it, and what you expected instead.

Please do not post an unfixed vulnerability publicly or in a feedback
form.

Findings in the i9 **source repository** can also be reported privately
through GitHub's security advisory mechanism (see the repository's
`SECURITY.md`); that channel carries its own acknowledgment and
assessment aims, and is the right one for source-code findings.

## What happens next

A person reads every report. Handling is best-effort, with no fixed response
time. Reports about the install path (the scripts at `https://i9.io/vm` and
`https://i9.io/vm/install.ps1`, and the binaries they fetch) and about release
signing keys are handled first.

## Scope

In scope:

- the `i9` binary;
- the installers at `https://i9.io/vm` and `https://i9.io/vm/install.ps1`;
- the websites `i9.io` and `a.i9.io`;
- the published VM images.

Out of scope: third-party services i9 uses (Cloudflare, Google, Stripe), and
denial-of-service testing.

## Good-faith research

Research done in good faith, within the scope above, that avoids harm to
other people's data and to the service and gives us a chance to fix what it
finds before disclosure is welcome. Kurosea, Inc. will not pursue legal action
against it.

## Credit

On request, we credit the reporter in the release notes of the release that
fixes the issue.

## Machine-readable contact

`https://i9.io/.well-known/security.txt` (RFC 9116) names the same contact,
points at this page as the policy, and carries an `Expires` date.

## What is isolated, what is shared, what is not guaranteed

**Isolated.** The VM has its own kernel and its own filesystem, so the agent
cannot reach the host's files or processes. The guest is not a host on your
local network, and nothing reaches into it unless you forward a port.

**Reachable by default.** The guest has outbound internet access through i9's
own user-mode NAT. `i9 run --egress` restricts it: `deny` refuses anything not
allowed, `warn` permits and records, and `allow` restricts nothing but the
host's own networks. The host's own networks (loopback, LAN, VPN) are refused
in every egress mode unless a literal `--allow` names them, and each such
connect is recorded as an `i9.slirp.host_network` span naming the address the
guest dialed and the verdict.

**Shared.** The only ways across the boundary are the ones you open: a
published port or a copied file. The VM runs on the host's CPU and memory,
through the host kernel's virtualization features.

**Not guaranteed.** The guest is isolated, not a security boundary to rely on
for hostile code: no virtual machine is unescapable, so run code you distrust
in a machine you are willing to lose. A fork copies the parent's secrets and
identity (see the secrets section below).

## What leaves the machine

With telemetry on (the default), i9 sends your OS, CPU architecture and a
coarse i9 version on the first request of a remote image fetch, with no
identifier; `i9 config set telemetry.enabled false` turns it off. Everything
else reaches the network only when you ask: an image fetch (`i9 run <url>`,
range requests for the image's bytes), `i9 update` (your version),
`i9 grant request` (nothing) and `i9 grant renew` (the grant id), to i9.io.
i9 has no upload path
of any kind: it cannot send a snapshot, a trace or a guest filesystem anywhere.
What the guest itself sends is the guest's, bounded by `--egress`. The full
table is in [Data handling](DATA-HANDLING.md).

## Archive trust

An archive is checked three ways before it runs: integrity (the bytes are
intact), authenticity (a key signed them) and authorization (that signer is
trusted to have this run). Authorization is decided on who signed, never on how
the archive reached you: a snapshot in a file on your disk and the same
snapshot fetched from a URL get the same answer. A signer you trust, your own
or i9.io's, is accepted in every mode. `provenance.mode` decides what happens
for a signer you do not know:

| Mode | An unknown signer is |
|---|---|
| `strict` | refused, naming the signer |
| `interactive` | refused until you confirm that signer at a terminal |
| `development` | restored under a prominent warning |

Unset, an agent (MCP, `--json`, a non-TTY stdin, a detached run) gets `strict`
and a person at a terminal gets `interactive`. An unrecognised value reads as
unset, so a typo never widens trust. A snapshot is a running machine frozen
mid-life: restoring one resumes its processes, its credentials and its code on
your machine, so restore one from someone you trust. Each restore records the
mode it ran under on its span (`i9 trace` shows it). The details are on the
architecture page.

## Secrets, snapshots, forks and traces

What i9 does with a credential, and what travels when a VM is copied:

- **Secrets you give i9** (`i9 secret set`) live in this machine's keychain or
  an owner-only store. A VM receives one the first time a command names it
  (`--secret NAME` on `run` or `vm exec`), and the value never appears on a
  command line. From then on the file at /run/i9/secrets/NAME is readable,
  and an env or both-mode secret is in the environment, of every later
  command in that VM, named or not, and of a fork that is given it
  (`--fork allow`, or `vm fork --secret NAME`), until the VM stops; `i9 secret rm`
  stops later deliveries. It does not reach into a running VM for a file or
  env secret: the VM keeps the file it has, and a process that read the value
  keeps it. After a remove and set, the next command that names the secret is
  delivered the new value, and a command that names a removed secret is
  refused. A proxy-mode secret is the exception, because the guest
  only holds a stand-in token: a remove or a replacement refuses that token
  on the VM's next request. If an upstream reflects the credential back (an
  error message that quotes the key), the value and its base64, hex and
  percent-encoded forms are masked before the guest reads the response, as
  eight asterisks whatever the credential's length: the guest learns that the
  upstream reflected it, never the value or its length. The mask changes the
  body's length, so a response that carries one leaves chunked (HTTP/1.1) or
  as data frames with no content-length (HTTP/2). Over
  MCP, `i9_secret_set` with `fromFile` stores any host file the user
  running i9 can read, and `i9_vm_cp` copies one into a guest; an agent
  holding those tools reaches every file that user can read. i9 removes
  every live value, and its base64, hex and percent-encoded forms, from the
  trace before it is written. A snapshot never carries the secrets slot
  that delivers file and env values: the capture zeroes it in every chunk it
  writes. But a copy a guest process read is guest state, and the snapshot holds it
  (in the process's memory, or in a file it wrote), which is why `vm save` warns.
  `i9 snapshot export` refuses a snapshot whose guest memory may hold a
  secret's value (a file or env value delivered to the guest, or a proxy
  value an upstream's response carried back, which the proxy records when
  it masks one in a response) when the destination is outside the i9 home,
  unless you pass `--allow-live-secrets`, and that override is recorded in
  the trace; the refusal names each secret and its evidence. A proxy secret
  whose guest only ever held its stand-in does not count, since a stand-in
  works on no other VM. A destination inside the i9 home exports without
  the flag and prints the plaintext warning.
- **A VM's control token**, the bearer in a `ws://...?token=...` control URL,
  is not a secret you gave i9. i9 keeps it in the owner-only session registry
  under the product home (`state/`, directories mode 0700, files mode 0600), so
  a verb given a tokenless control URL or a `--name` attaches without the token
  being printed or typed. `vm ls` and `run --detach` print the URL without it
  (`--show-token` asks for it) and the detach log redacts it. A copy of the
  product home carries the token of every VM it has run, so treat the copy like
  a credential.
- **A snapshot or export** holds the VM's disk and memory as they were, in
  plaintext. A key, `.env` file or credential that a workload copied into the
  guest is readable by whoever has the file. `i9 archive redact` works on
  trace spans, not on guest disk or memory.
- **A fork** begins with everything in its parent's memory and on its disk:
  running processes, open files, the hostname, the kernel's boot id, the
  network MAC address, and any token or session a workload already holds.
  Each child gets its own name and control URL, and
  its guest kernel's random number generator is reseeded, so two children do
  not draw the same random bytes. A secret set with `--fork deny` (the
  default) is not delivered to the child by i9: the child has no file at
  /run/i9/secrets/NAME. What the parent's guest had already received travels
  with the fork in memory, so a process that read the value keeps it in its
  environment, and a save of the child is refused outside the i9 home without
  `--allow-live-secrets`. A rewind returns the same VM to an
  earlier moment and brings back the processes it held then, with any secret
  they had already read. Re-issue the credential when branches must not
  share it.
- **The trace** records every process that runs in the guest, not only the
  commands you submit: each one's command line, parent, exit code and
  duration, including a child a command spawned and one that outlives it.
  Any process in the guest can also write spans to it through
  `/run/i9/trace.sock`, so a span from the guest is the guest's word, not
  i9's.
  Values shaped like credentials (`--password V`, `API_TOKEN=V`,
  `Authorization: Bearer V`, a password in a URL) are masked before the
  trace is written. A credential in any other position, or in a program's
  output, is not recognisable and is recorded as written. Give credentials
  to a workload with `--secret` instead. Each use of a proxy-mode secret is
  traced with the VM it came from, that VM's fork parent and its generation:
  `i9 trace stats --by by-attr --attr i9.vm.id --where
  i9.secrets.proxy.secret=NAME --session <PID>` lists the VMs that used
  NAME (`--attr i9.secrets.proxy.parent_id` or `--attr server.address`
  groups the same uses by lineage or by destination).

What a file, env or both-mode secret reaches once a VM has it. The file and the
environment variable both belong to the VM's grant: a command gets them whether
or not it names the secret (the entrypoint of a VM started with
`i9 run --secret NAME` included):

| Who | The file at /run/i9/secrets/NAME | `$NAME` in the environment |
|---|---|---|
| The command that names it (`vm exec --secret NAME`) | file and both mode | env and both mode |
| A later command in that VM, named or not | file and both mode | env and both mode |
| A fork child, `--fork deny` (the default) | no file | no, for a new command |
| A fork child, `--fork allow` or `vm fork --secret NAME` | file and both mode | env and both mode, for every command in the child |
| A process that already read the value, in the VM or in any fork | keeps what it read | keeps what it read |

## How these claims are checked

Each claim above that i9 can test is held by a cell in its test suite: one that
boots a VM and tries the thing, beside a control that shows the check can fail,
or a unit test on the code that decides. The cells run on every release.

## How releases are signed

Every release is signed, and the installer only sends a binary digest that
matches a verified signature. How to check a release yourself:
<https://i9.io/vm/verify>
