Threats
Who would attack this forge, what each wants, and what stands in the way.
Every protection is one bullet ending in one Enforced by: line that names
the test file (test/….test.ts) or the gate (scripts/….ts) that enforces
it, or says none yet plainly, with (#N) when an open issue owns the gap.
Each row of the internal-calls table names its enforcer in its last cell the
same way. test/threats-enforced.test.ts fails on a row with no such line or
a named path that does not exist, and prints how many rows say none yet. A
protection nothing enforces is a gap, not a secret: the count is the to-do
list, and only editing a row lowers it.
A snooper on the network
Wants: session cookies, tokens and pushed code in transit, or to learn who talks to whom.
- Sessions are HttpOnly cookies,
Securewhen the request came over https, so
script cannot read one and a plain-http hop does not carry it.
Enforced by: test/own-session.test.ts
- Tokens are shown once; the database keeps only their sha256, so a copy of the
index does not replay as a login.
Enforced by: test/tokens.test.ts
- TLS is terminated by the edge in front of the forge, and certificates are
issued only for names the forge vouches for (on_demand_tls ask).
Enforced by: none yet
- Between the edge and the forge process, and between forge and cell, traffic is
plain HTTP on one machine or a pod network. Nothing encrypts it. Enforced by: none yet
A stolen token
Wants: to act as the person or agent it was issued to, for as long as it works.
- Tokens carry a scope and an optional expiry; a narrower token cannot do what a
wider one can.
Enforced by: test/tokens.test.ts
- A crew run's secrets are named in the brief, opened per run, redacted from the
log, and released when the run ends.
Enforced by: test/run-secrets.test.ts
- The model credential in a crew run's environment is held for redaction like a
granted secret, from before the agent starts until the run ends: a run that
says it leaves [redacted] in its log, its summary and every event. The
two other children the forge starts with that credential, a one-shot and a
conversation turn, are held the same way.
Enforced by: test/boundary-secrets-run.test.ts
- A passport (
fp1.…) is bound to one audience and scope set and dies in
minutes, so a copy lifted from a run is useful to one door briefly.
Enforced by: test/passport.test.ts
- Sign-in attempts are throttled per client, with a whole-forge cap beside it.
Enforced by: test/signin-throttle.test.ts
- Stored provider tokens (origins) are sealed under a key in
secret.key, never
returned by any route.
Enforced by: test/origins-security-auth.test.ts
- The SSH host key and the database files are created 0600; a host key group-
or world-readable is refused, and a database file found too open is a
degraded finding naming the chmod, never a silent change and never a stop.
Enforced by: test/file-modes.test.ts
- The files a forge's family keeps keys in (
parent.json: the heartbeat key, a
proposal token, a read credential offered and not yet sealed; the parent's
spawn/<name>.json: the status token and the heartbeat key) are written 0600
(writePrivate), and one found wider is narrowed at boot and said once.
Enforced by: test/boundary-tokens-follow.test.ts
- A token bound to one repository (a run's, a child's, an outside agent's, an
app's) is refused on every route of every other repository before the
route's handler runs, and ends with its repository: it never becomes an
unbound one.
Enforced by: test/boundary-tokens-gates.test.ts
- Every such token is minted with an end, read on every use, and its own
revoke ends it at the next request, with no restart and no wait. A
repository's admin sees and ends every child's read of it, whoever it was
minted as; a suspended account's tokens stop with it.
Enforced by: test/boundary-tokens-gates.test.ts
- A crew run's git offers its token to this forge's two addresses and to no
other host it talks to, and the token ends with the run.
Enforced by: test/boundary-tokens-crew.test.ts
- The credential a child holds to read a private app is minted for that one
repository and kept by the parent as a hash; the child seals it with its own
key and keeps it in no file, config or address. It lives a week at a time,
renewed while the child follows, and ends when the child is removed, refuses
the offer or is revoked; no log line or event on either forge carries it.
Enforced by: test/boundary-tokens-follow.test.ts
- A child's tokens and an outside agent's contribute token never enter an app
at its own host, whoever's account they ride on. The token a preview's own
process holds reaches its repository, its timers and its printer, and
nothing else of its owner's.
Enforced by: test/boundary-tokens-apphost.test.ts
- Only a forge admin sets or removes a secret, and nothing is opened for
anyone else. An open leaves one secret.read per name opened; no event
carries a value, plain or sealed; the data browser shows no sealed column.
The key file is 32 bytes only its owner reads, and one that others can read
is refused by name. A lost key costs the values and nothing else. Deleting a
repository removes the secrets scoped to it.
Enforced by: test/boundary-secrets-store.test.ts
- A secret kept for the forge or an organization reaches a repository's app
and its crew's runs only after a forge admin granted that name to that
repository; a repository's own secrets need no grant. A name a run declares
and nobody granted is never opened: the run goes on without it and says so
in its log and once on its issue, with the link that grants it.
Enforced by: test/boundary-secrets-store.test.ts
- A production app's
FORGE_TOKENis its owner's read-only token: the app's
code and what it depends on read everything its owner reads, every private
repository included. A preview's is bound to the app's one repository;
production's is not, because reading the whole forge from an app is a
documented feature (docs/APPS.md, examples/forge-live). Binding it too
waits for the owner's word: it needs a per-app grant the owner sees listed,
and until that grant is given it stops an app that reads its owner's other
repositories on purpose.
Enforced by: none yet
- Revoking every token of one account at once, and telling its owner a token was
used from somewhere new. Enforced by: none yet
A compromised vendor
Wants: to run its code on the forge or in an app through something the forge trusts: a package, a model provider, a hosting provider, an origin it syncs from.
- The forge has no runtime dependencies, so there is no package to poison in the
forge itself.
Enforced by: test/deps.test.ts
- An app's code runs in a cell: read-only machine, empty data directory and
home, own pid and network namespaces, memory, CPU and disk watched. A
dependency an app pulls in gets no more than the app does.
Enforced by: test/contain.test.ts
- A cell binds each directory it may write once, nothing inside one by name,
and only a directory that is there itself: a link its code leaves where its
home goes is never mounted. What it hides (the forge's data, home and temp)
is covered under the name it really has as well as the one it was given,
before its own directory is bound back, and no neighbour's directory is
ever shown.
Enforced by: test/boundary-tenancy-cell.test.ts
- What a cell prints costs the forge one line at most, however long it goes
without a newline: an app's or a step's line is cut at 64 KiB as it arrives
and says so, a hosted forge's at 500 characters. That text is held in the
forge's own memory, outside the cell's cap.
Enforced by: test/boundary-tenancy-limits.test.ts
- A cell's disk is counted to the end or the cell is over it: the walk goes as
far as the cell's own limit of files (as many as its disk has 4 KiB blocks,
a million at least), and a cell that reaches it is stopped and told so,
never counted as the part that was seen.
Enforced by: test/boundary-tenancy-limits.test.ts
- Outside Kubernetes a cell sees the machine's mounts minus the ones that may
carry a secret (every tmpfs, everything under /run): a second mount of the
data volume, an env file or a backup volume bound in at another path is
readable in every cell. FORGE_CELL_MOUNTS=allow-list closes it; it is not
yet the default wherever the forge runs in a container.
Enforced by: none yet
- An app that prints the variables, identity key or forge token it was handed
leaves [redacted] in its deploy's log, plain or encoded, so a careless
dependency does not publish them to everyone who can read the runs.
Enforced by: test/boundary-secrets-process.test.ts
- The only way out of a cell is the egress proxy, which reaches the hosts the
repository declared and refuses names that resolve to private, loopback or
metadata addresses.
Enforced by: test/apps-adversarial.test.ts
- A connected origin's replies are validated at the boundary and not trusted for
identity.
Enforced by: test/origins-security-provider.test.ts
- A push to an origin is vetted like a fetch from one: a name that resolves
to a private, loopback, link-local, tailnet or metadata address is refused
before git starts, in the fetch's words; git dials the address that was
judged and follows no redirect. A hosted forge's proposal to its parent
trusts the parent's host by name for that one push.
Enforced by: test/mirror-outbound-push.test.ts
- Pushes from an origin cannot rewrite what the forge protects.
Enforced by: test/origins-security-push.test.ts
- Backups are encrypted before they leave the machine.
Enforced by: test/snapshot-store.test.ts
- A review of lockfile changes (
bun.lock) before they reach an app's cell.
Enforced by: none yet
A hostile agent inside a run
Wants: to read what it was not given, reach what it may not, or land code no person approved.
- The agent's shell may reach only the forge, the package registry and its
own repository's app (production and each open pull's preview), by exact
host, and never another repository's app. The
forge's repositories, index, key and every other agent's clone are denied by
name and by allow-list, and a listing that fails refuses the run.
Enforced by: test/crew-sandbox.test.ts
- The one place a run writes beside its clone and temp directory is its
repository's bun install cache (crew/.cache/<repo id>/bun), which every
run on that repository can write: a run can poison what the next run on the
same repository installs. It is per repository: the cache root is denied whole
and only this repository's directory re-allowed, so a cache made later is
denied too, and deleting the repository removes it.
Enforced by: test/crew-install-cache.test.ts
- A check's cell reads its repository's shared bun cache
(check-install/<repo id>/bun) through a read-only bind and cannot write
it, so one pull cannot plant a package the gate on main installs. The
forge fills it on the host with --ignore-scripts, and reads no
bunfig.toml or .npmrc of the pull's.
Enforced by: test/check-install.test.ts
- An app environment's cell reads that same cache read-only and
copies from it, so a preview cannot plant a package production installs;
the forge fills it through the same lockfile rule as a check's.
Enforced by: test/app-install-cache.test.ts
- The forge fills that cache only from a lockfile whose every package is a
registry name@version with a sha512 integrity (checks/fillable.ts):
the host never fetches a URL a pull chose and reads no file, link or
workspace a pull points at, an override's or resolution's included.
Enforced by: test/check-fillable.test.ts
- The same policy holds against a real bubblewrap, not only as a string.
Enforced by: test/crew-sandbox-real.test.ts
- A pull's check and its preview reach the hosts, and run at the limits, that
its base branch's forge.json declares, never the ones its own asks for,
until the pull lands: code on a branch, the crew's as much as a guest's,
cannot widen where its own check and preview send what they hold. The
pull's page and the top of its logs say in one line what it asked for and
that it applies when the pull lands.
Enforced by: test/boundary-pull-egress.test.ts
- An agent cannot push to the default branch or merge; a person merges.
Enforced by: test/protection.test.ts
- An outside agent that drives a person's account cannot push past the pulls
either: a protected default takes a push from its admins only, so every
other writer lands through a pull, its gate and its review.
Enforced by: test/protected-default-push.test.ts
- A variable set with no scope named is production's alone: a pull's preview,
which runs code nobody has landed, reads a variable only when its owner
chose "Also in previews" or set one for previews.
Enforced by: test/app-env.test.ts
- Merge gates (checks, review) are enforced in the merge path, not by convention.
Enforced by: test/security-merge.test.ts
- Spend, time and turns per run are limited.
Enforced by: test/crew-limits.test.ts
- Rendered output escapes everything an agent wrote.
Enforced by: test/security-xss.test.ts
An automated attacker at scale
Wants: accounts, spam, resources, or a way to exhaust the forge.
- Request bodies are capped at the boundary.
Enforced by: test/body-limits.test.ts
- Parsers survive generated hostile input.
Enforced by: test/fuzz-parsers.test.ts
- Anonymous spawn is rate limited per client address.
Enforced by: test/spawn-anon.test.ts
- Every door a stranger can reach that costs (API reads, clones, code
search on the page, the API and the terminal's guest palette, event
streams, spawn plans) is limited per address and for every stranger
together (src/http/strangers.ts, docs/ARCHITECTURE.md, concurrency
invariant 7); a signed-in push keeps its share of the pool.
Enforced by: test/strangers.test.ts
- The client address is the socket's peer unless that peer is a configured
trusted proxy; X-Forwarded-For is read from the right, past trusted hops.
Enforced by: test/client-address.test.ts
- A new-account guard can refuse repository creation and forks for young
accounts.
Enforced by: test/guard-new-accounts.test.ts
- Sign-up has a ceiling per address and for the whole forge, per minute and per
hour, and an admin can close it at once.
Enforced by: test/guest-contribute.test.ts
- A guest owns only a contribution fork of a public repository. It holds no
settings, secrets or app, nothing runs for it, and its storage, forks and
pulls are limited (docs/ROLES.md).
Enforced by: test/guest-contribute.test.ts
- An outside agent with a contribute token (no account) pushes its branch into
the repository itself, so where a head lives says nothing about who wrote it:
a contrib/<agent>/<segment>/… head is a guest's. Its check runs with
nobody's permission, behind the owner's and the crew's work, in a cell that
holds no variable, token or secret and is held to the hosts and limits the
base branch declares; nothing from its branch is previewed, and the crew
leaves it, until a writer approves the pull once. On a machine with no
cell its check does not run unapproved either, and says the press that
lifts it.
Enforced by: test/boundary-tokens-crew.test.ts
- A fork shares its parent's git objects, and git answers for any object a
store holds to whoever names it by id. So someone who reads a fork and may
not read its parent (the parent was made private after the fork; they left
its organisation or its crew) is held to what the fork's own refs reach: at
the git door over protocol v2 and v0, for a commit, a tree or a file, and at
the fork's pages, API, tools and terminal by a full id or a short one,
answered exactly as an id nothing holds. A parent that is not public no
longer moves a public fork, and a push into such a fork must carry every new
object it names. Everyone else fetches as before, partial clones included.
What a fork's own refs already held stays the fork's: the read-only
forks-beyond-parent script lists the forks to look at.
Enforced by: test/boundary-fork-objects.test.ts
- A pull whose head lives in a fork, here or on the origin, and a child's
proposal run nothing until a person who can write the repository approves
that exact head, and the crew never lands one.
Enforced by: test/guest-contribute.test.ts
- A branch in the repository itself was put there by someone who may write it
(on a mirror, by someone its origin lets write), so its check and preview
run at once. When its author is a guest from the origin, its preview and
that preview's terminal still hold none of the app's variables, no forge
token and no copy of production's data until a writer approves the pull.
Enforced by: test/boundary-secrets-process.test.ts
- Every limit is a setting with its reason, changed by an admin only.
Enforced by: test/limits.test.ts
- Distributed attacks across many addresses: only the whole-forge caps stand
here. Enforced by: none yet
Internal calls
FORGE_SELF_SWAP=1 binds the web port with SO_REUSEPORT so a release can share
it, which also lets any process running as the forge's user join the listener
and take a share of its connections, login posts included. It assumes nothing
else runs as that user on the host network (agents and apps are sandboxed or in
cells). Only one swap is made per process, so two landings never leave two
releases serving. The swap is refused unless net.ipv4.tcp_migrate_req=1, for
without it the old listener closing resets queued connections.
Enforced by: test/release-swap.test.ts
How each part proves itself to the next, today.
| Call | Authenticated by | Enforced by |
|---|---|---|
| runner → forge | the run's scoped token (FORGE_TOKEN) and a few-minute passport (FORGE_PASSPORT) | test/passport-edge.test.ts |
| git hook → forge | per-boot secret in x-forge-hook-secret on the internal listener; a call without it is refused and counted | test/crew-sandbox.test.ts |
| cell → proxy | the proxy's Unix socket bound into the cell's own network namespace; no credential, the namespace is the identity | test/contain.test.ts |
| edge → pod | X-Plat-Edge-Token equal to FORGE_EDGE_TOKEN, compared as fixed-width digests; without it X-Plat-User is ignored; the signin.edge setting (admin, refused for an admin with no password or passkey) turns the edge's identity off on every door | test/edge-auth.test.ts |
| child → parent | a heartbeat and a brokered sign-in are signed (HMAC) with the key spawn gave both sides, looked up by the name inside the signed body, so the door a call arrives on says nothing about whose it is; the lent model by a bearer whose hash the parent keeps; a child's door answers those routes and nothing else. Code is pulled over public git, and the claim link (sha256 kept, 24 hours, single use) hands the child to its person | test/boundary-tenancy-cell.test.ts |
Gaps: edge → pod and runner → forge ride a shared secret, not a per-call signature.
A child forge running its own code (#11144)
A cell child's owner may switch it from the parent's code to its own <org>/forge main (spawn/own_code.ts). The code is then the child's author's, so treat it as hostile code in a cell, the same as any app.
What it cannot reach: the cell's memory, CPU, disk and I/O limits, its sandbox and its egress list are the same as with the parent's code, and nothing in the child's repository is read to make them. The parent's data, home and temporary directory are hidden; only the parent's code and the one checkout (a tree, with no .git) are revealed, read-only. Its forge.json is not run by the parent: the parent finds the repository only as a directory of the child's own (never through a link), refuses a repository or tree over 256 MB or 50,000 files and any symbolic link in either, checks that src/main.ts parses and forge.json is JSON, and never executes the child's code outside the cell. What the parent records about a failed start is fixed wording: one of a list of the parent's own sentences. Nothing the child wrote or printed reaches the ledger, the rollback row or the forge.rolled_back event; its last lines go to the parent's log.
What it can reach: everything a child forge can reach, no more: its own data directory, the parent's heartbeat door and public address, the hosts the admin allowed for models, registry, payment and origins (the public git hosts and the forges its parent holds beside it), and the sign-ins its parent brokers for it. It can lie in what it serves and in its heartbeat, and can break itself: a start that fails to answer within the deadline rolls back to the last commit that came up, then to the parent's code, and the owner's /forges page shows a Rolled back row saying so. A commit that failed is not tried again until main moves. A child that comes up and breaks later is not rolled back; the owner switches it off. Hosted children run inside the parent's process and cannot turn this on.
- The cell limits, sandbox, egress list and hidden parent paths are built by the
parent from outside, never read from the child's repository, so a child's own
code is held exactly like any app.
Enforced by: test/own-code.test.ts
- A forge made in a cell stays a cell child. A cell that does not start
leaves it stopped, its address and its host's forges page saying why and
when the host tries again; it is not opened in the parent's process for
that, since its directory (its repositories' hooks and git config included)
is the child's to write. Only a host that holds no cell at all runs a child
in its own process, and never one that has run code of its own.
Enforced by: test/spawn-cell-stays.test.ts
- A forge that still runs inside its parent's process (made before cells, or
put there by an older release) is moved into a cell of its own, by an
admin's button or by the forge's own pass at boot and when one sleeps; a
move that does not prove itself is put back (the sizes it is given are held
by test/spawn-move-cell-sizes.test.ts).
Enforced by: test/spawn-move-cell.test.ts
- Before such a forge leaves its parent's process its repositories are read,
running nothing, for what that process may have executed while it had no
wall: hooks beyond the forge's own stubs and config keys that make git run
a command, reported by name and never by content.
Enforced by: test/spawn-move-scan.test.ts
- A host that holds every forge in a cell seals: it opens no forge in its
own process again whatever a ledger says, never moves a cell child into
its process because its own probe of cells failed, and places a new forge
in a cell or not at all.
Enforced by: test/spawn-sealed-host.test.ts
- The parent asks a child's database (is this session the child's, is its
crew at work, its public apps) off its serving thread, with a deadline, and
only of plain tables: a view of the same name is never run, and a statement
that does not end costs that child one answer of "unknown" and nobody else
anything.
Enforced by: test/child-db-off-thread.test.ts
- What the parent writes and reads in a child's directory from outside its
cell (the stop note, the plan notice, the credit, the app links, the starts
ledger, the key file) follows no link the child left there: one writer that
makes its own file and moves it into place, one reader that takes a regular
file or nothing and never waits on a pipe. A link under the key's name is a
refusal, never read through and never minted over.
Enforced by: test/boundary-tenancy-files.test.ts
- A child's own code is found and copied only from a repository in its own
directory with no link in it, and what is recorded when its start fails is a
sentence from the parent's list, whatever was handed in.
Enforced by: test/boundary-tenancy-files.test.ts
- Side by side, one child's cell has namespaces of its own for users,
processes, network, IPC and hostname; its way out reaches its own door on
the parent by that exact port and refuses a neighbour's door, a neighbour's
port and the parent's own port on loopback; and a heartbeat or a model
bearer made with one child's key opens nothing of another's.
Enforced by: test/boundary-tenancy-cell.test.ts
- A child is held to its size by the kernel where the forge has a delegated
cgroup: memory (no swap, the whole cell killed together), cores, processes
and disk bandwidth, at a tenth of the forge's own weight. Where it has
none, the hold changes hands and is said: a pin and pausing for cores, the
watch for memory and processes.
Enforced by: test/boundary-tenancy-limits.test.ts
- The forge keeps memory for itself that the cells together cannot take: a
floor on its own cgroup where that is delegated (memory.min and
memory.low, a limit an admin sets), and every cell's and crew run's first
process raises its own oom_score_adj above the forge's, so short of memory
the kernel chooses a cell first. No hosted forge is refused a start for
memory: when the sizes together pass the machine, /forges and the forge's
needs say so in one line. Proven as the files written and the argv a cell
starts as, not as the kernel's behaviour; a cell that sets out to can lower
its figure back to the forge's own, never below it.
Enforced by: test/boundary-tenancy-limits.test.ts
- Beyond its parent, a hosted forge's cell reaches only what the parent's
settings name, each on 443: the model, registry and payment hosts, the
public git hosts, and the forges its parent holds beside it (one name ending
in --<parent's host>). No other name under the parent's domain opens, and
the list never holds a wildcard on a domain: under a shared suffix that
would be everyone's host there.
Enforced by: test/spawn-cell.test.ts
- A name on a cell's list is still held to every address it resolves to: one
private, loopback, link-local, tailnet or metadata answer among public ones
refuses it, in every spelling, whichever entry named it. A name that is not
on the list is refused before it is looked up, and nothing is dialled.
Enforced by: test/boundary-outbound.test.ts
- A name an admin allows a hosted forge beyond that list is one public host
name on 443, for that forge alone or for every one: never an address, a
wildcard, another port or a name that is private by its shape, whether the
forge asked for it or the admin typed it, and a name that resolves inside a
network is not taken as an ask. A granted name is still judged by every
address it resolves to. Only a person who is a site admin answers, from the
parent's own pages; a form sent from another site changes nothing. What the
hosted forge says about who asked and why is cleaned and only ever shown.
Enforced by: test/ask-to-reach.test.ts
- A sign-in the parent brokers for a hosted forge hands the token over once,
inside a minute, to the forge that began it and to no other, and what the
parent keeps is an event naming the forge, the host and the account: never
a token or a code. Before the provider is asked anything, the parent shows
the person one page that names the hosted forge, from the parent's own
ledger, and the provider, with one way on: the provider's own consent names
the parent's application and may ask nothing.
Enforced by: test/origin-broker.test.ts
- A token a brokered sign-in sealed is deleted after its minute across a
restart too: the broker's rows are swept as the forge boots.
Enforced by: test/origin-broker-boot.test.ts
Honeypots (later)
A kind: "honeypot" app, a decoy that records what touches it, is not built.
forge.json accepts web and service only. Before one may exist:
- the cell must hold (above), since the point is to run hostile traffic next to
real apps;
- its egress must be none, not declared hosts;
- it must carry no secret, no token and no data from any real app;
- what it records must be bounded and escaped like any other input.
Until then, nothing here claims one.