Entries
Each entry inallowlist or blocked is one of:
- A hostname, such as
api.example.com. - A
*.wildcard hostname.*.example.commatches every host below it at any depth, such asapi.example.comanda.b.example.com. It does not matchexample.comitself. - An IPv4 address, such as
203.0.113.7. - An IPv4 range in CIDR form, such as
203.0.113.0/24. The range must start at its first address (1.2.3.0/24, not1.2.3.5/24).
- At most 128 entries. An empty
allowlistmeans no egress; an emptyblockedlist is the same as leaving it out. - An entry names a destination without a port. An allowed destination is reachable on every port, and an entry with a port is rejected.
- IPv6 entries are rejected, because a Sailbox does not reach the internet over IPv6.
- An address no Sailbox could ever reach, such as
127.0.0.1or169.254.0.0/16, is rejected. - A private range such as
10.0.0.0/8is accepted but allows nothing, because a Sailbox cannot reach private addresses. - Entries are stored lowercased, without a trailing dot or duplicates.
What an entry allows
- A hostname entry allows connections that name the host, which HTTPS and plain HTTP do. It also allows a connection that names no host, such as SSH or a database connection, when one of the Sailbox’s most recent name lookups resolved that hostname to the destination address. The remembered lookups stay with the Sailbox’s memory through sleep, pauses, checkpoints, and forks. Resolve a name right before connecting.
- An address the Sailbox never resolved, such as one read from a config file, is reachable only through an address or range entry.
- Name resolution follows the allowlist. A name no hostname or wildcard entry covers does not resolve, so an allowlist of only addresses and ranges resolves nothing but Sail’s own API host.
- A TLS connection that hides the server name with Encrypted Client Hello is closed under an allowlist. Turn that feature off in the client, or add the server’s address to the allowlist.
/etc/hosts cannot redirect the connection. Sail
checks only the name a connection announces, so an allowed server that also
serves other sites, as a shared CDN does, makes those sites reachable too.
Under an allowlist or a blocked entry, a connection the policy does not allow
opens and is then closed by Sail, so a program sees the failure on its first
read or write. Under no network the connection is refused before it opens.
No egress and no network
{"allowlist": []}is no egress. The Sailbox reaches nothing but Sail’s own API host (below), and no other name resolves. Inbound connections are unaffected: exposed ports and SSH keep working, and the policy may be set on a Sailbox that exposes them.blockedandrulesare rejected beside it, since nothing is left to block and no request is sent for a rule to act on.{"no_network": true}is no network. The Sailbox has no outbound connections, no name lookups, and no exposed ports or SSH. Exposing a port or enabling SSH is rejected, and the document cannot be set on a Sailbox that already exposes one. No other field may be set beside it; a document that tries is rejected, naming the field. Running commands, the shell, and mounted volumes still work.- Sail’s own API host,
sailbox-api.sailresearch.com, stays reachable under no egress and under every allowlist, so a Sailbox can always call Sail about itself, for example toreboot. Only no network removes it, and no rule applies to it. - Setting either on a running Sailbox affects connections opened afterwards. Under no network, the connections the Sailbox already has open stall without closing and resume if a later policy restores network access.
Blocked
blocked uses the same entry forms as allowlist, and an entry
only ever removes access. Every entry must be narrower than what covers it.
Anything else is rejected, naming the entry: a wildcard, an entry that also
appears in the allowlist, a hostname on a document without an allowlist, and
any entry beside an empty allowlist or
no_network.
A blocked entry cannot remove Sail’s own API host,
sailbox-api.sailresearch.com: an entry that names it is rejected, and a
range that covers its address does not apply to it.
A hostname can be blocked only under an allowlist: a blocked name takes
effect on connections that name their host, and only an allowlist makes every
connection to a hostname do so. Without an allowlist, block the address or
range instead.
What a blocked entry does
- A blocked hostname does not resolve, and a connection that announces it is refused. Other hosts under the wildcard connect normally. Sail checks the name a connection announces when it opens, so a server the blocked name shares with an allowed name or address stays reachable through that name or address; block the address to keep it off limits.
- A blocked address or range closes any connection to it, whether the Sailbox chose the address itself or an allowed hostname resolved to it.
Rules
rules maps a host to an ordered list of rules for the HTTPS requests the
Sailbox sends to that host. Sail picks the most specific host entry for a
request, then the first rule under it that matches, and applies that rule. If
nothing matches, the request goes out unchanged. Rules act on HTTPS only;
plain HTTP and other traffic pass through untouched.
Hosts
- Write a bare hostname: no
https://, port, or path. api.example.commatches exactly that host.*.example.commatches every host below it at any depth, neverexample.comitself.*matches every host not named elsewhere. Sail picks an exact entry first, then the nearest wildcard (*.api.example.combefore*.example.com), then*.- No rule applies to Sail’s own API host,
sailbox-api.sailresearch.com, not even under*. A Sailbox’s requests to Sail about itself go out unchanged. - Use an exact host whenever a rule adds a credential: a wildcard sends the credential to every host it matches.
Rules and the allowlist
- A rule does not make its host reachable. When the document has an
allowlist, every host underrulesother than*, and every host a rule forwards to, must be covered by the allowlist: an exact host by the same entry or by a wildcard that matches it, and a wildcard by the same wildcard entry or by a wildcard above it. - No rules host or forward host may be a blocked hostname.
- A document that breaks either rule is rejected, naming the host.
Matching
- Leave
matchout to cover every request to the host; such a rule must be last in its list. methodis case-sensitive, so writeGET; give one method or a list.path,headers, andqueryvalues accept a plain string or{"equals": "..."}for an exact match,{"prefix": "..."}, or{"one_of": [...]}.- A header or query condition can also assert
"present": false. - Request bodies cannot be matched.
- A request to a host with rules is answered with status 400 and not sent
on when its path contains a
.or..segment, such as/v1/../admin. Encoded forms like/v1/%2e%2e/admincount too. The destination host, such asapi.example.com, reads/v1/../adminas/admin. A rule matching the prefix/v1/would otherwise add its credential to a request the destination treats as/admin. Clients normally remove these segments before sending, so ordinary requests are unaffected.
Actions
What a rule does is exactly one of:- A
respondrule answers requests and leaves the host reachable. Sail still connects to the host before the rule answers, so arespondrule cannot stand in for a host that is down or does not exist. To block a host, leave it out of the allowlist or add it toblocked. - A
forwardhost must be exact. If Sail cannot reach it, the request fails; nothing is sent to the original host. request.set.headers,request.set.query,request.set.json, andrequest.set.formare templates: every$in them must be part of${secrets.NAME}or$$(a literal dollar sign). In every other string$is plain text, except that an unescaped${is rejected because it looks like an unresolved reference.- Only a saved policy may reference a secret, and the secret must exist before the policy is saved. Credential injection covers storing and rotating secrets.
- Responses cannot be changed.
- When Sail cannot apply a rule’s
requestchange, for example because a secret it names was deleted or a body edit does not fit the request, the Sailbox gets status 502 and the request is not sent.
Request bodies
request.set.json sets string values in a JSON request body. Each key is a
JSON Pointer such as /auth/token
(write ~1 for a / inside a name and ~0 for a ~). Missing parent
objects are created, so /auth/token works on the body {}. A pointer may
name an existing array element by index, but cannot add one.
request.set.form sets fields of a form-encoded body
(application/x-www-form-urlencoded), taking a string or a list of strings
like set.query. Other fields in the body are sent as they came.
- A JSON edit needs a request with a JSON body: Content-Type
application/jsonor a type ending in+json. A form edit needs Content-Typeapplication/x-www-form-urlencoded. - The body must be at most 8 MiB and not compressed: no Content-Encoding
other than
identity. - A request that does not meet these gets status 502 and is not sent. It never goes out without the edit.
- One rule edits a JSON body or a form body, not both. No pointer may sit inside another one in the same rule.
- Sail re-encodes an edited JSON body: the values are unchanged, but whitespace and key order may differ from what the Sailbox sent.
missing_alpn
- Most clients announce their HTTP version during the TLS handshake (ALPN), and a rule applies to the version announced.
- A client that announces none on port 443 is handled as HTTP/1.1, so the host’s rules apply. WebSocket libraries often connect this way. A client that announces none and then speaks something other than HTTP on port 443 gets an HTTP 400.
- On any other port, such a connection passes through untouched and no rule
runs, unless a top-level
missing_alpnmap names the exact host and the version to assume:"missing_alpn": {"api.legacy.example": "http/1.1"}. - The host must have rules, and
"http/1.1"is the only value.
Environment variables
env gives every command in the Sailbox environment variables that hold a
placeholder for a secret, not the secret itself. Code inside uses the
variable as it would the real key. A request.replace entry names the request
fields where the placeholder may appear, and Sail sends the secret in its
place. Only a saved policy may set env.
$OPENAI_API_KEY inside the Sailbox reads like
sail_ph_3kTq9.... A request to api.openai.com with the header
Authorization: Bearer $OPENAI_API_KEY goes out with the real key.
- Each
envvalue is a secret name, or{"secret": "NAME", "placeholder_prefix": "sk-"}to choose the text the placeholder starts with, for a client that checks the format of a key. The default prefix issail_ph_. Every entry for one secret must use the same prefix. - A placeholder is 32 characters, prefix included. It is the same in every Sailbox in your organization, and changes only if you change its prefix.
- Variable names start with a letter or
_and use letters, digits, and_. Names starting withSAILBOX_are reserved. - Commands get the variables whether they run through
execor a login shell. A variable you pass to a command yourself keeps your value. - Setting the policy on a running Sailbox updates the variables for commands started after the call. Processes already running keep the environment they started with.
request.replace maps a field to the secret whose placeholder it may carry,
under headers, query, json (JSON Pointers into the body, as in
Request bodies), or form.
- A field is replaced when its value is exactly the placeholder. A header
value may also be a scheme followed by the placeholder, such as
Bearer <placeholder>; the scheme is kept. - A field that holds no placeholder is sent as it came.
- On a host with rules or TLS settings, a request that carries a placeholder Sail does not replace gets status 502 and is not sent. Sail checks every header, the path, and the query. It checks the body only when a rule edits or replaces a body field, and then a placeholder in any other body field is refused. The check catches a placeholder sent where the policy does not swap it, which would otherwise reach the server in place of the secret.
- Every
envsecret must appear in somerequest.replace, and everyrequest.replacesecret must have anenventry. replaceneeds a named host. It cannot be used under*, where code in the Sailbox would choose which host gets the secret.
Several keys for one host
A field can name a list of secrets, for an agent that calls one API with a different key for each person it acts for. Give each secret its ownenv
variable. The placeholder a request carries selects the secret Sail sends.
api.notion.com with the header
Authorization: Bearer $NOTION_KEY_ALICE goes out with the secret
NOTION_ALICE, and one with $NOTION_KEY_BOB goes out with NOTION_BOB.
Every command in the Sailbox gets both variables, so any of them can send
either key. A list works the same way under query, json, and form.
Identity tokens
oidc_identity_tokens gives the Sailbox OpenID Connect identity tokens that
Sail signs. Each entry gives the token’s audience and the file that holds
the token:
audienceis the token’saudclaim: 1 to 512 printable characters with no spaces.pathmust be a file directly in/run/sailbox/oidc/, named with 1 to 64 letters, digits,.,_, or-, starting with a letter or digit. No two entries may share a path. Sail rewrites the file before the token expires.- A policy has at most 10 entries.
- Only a saved policy may set
oidc_identity_tokens.
Cloud identities
Most APIs take a key in a header, which a rule fills in withset. AWS and
S3-compatible storage work differently: the client uses its secret key to
sign each request, so there is no header to fill in. A cloud identity covers
that case. If your Sailbox does not call AWS or S3-compatible storage, you
can skip this section.
cloud_identities names the accounts. A rule with request.cloud_identity
tells Sail to sign every request to that host as one of them, so the Sailbox
uses the account without holding a real key for it.
Where the keys come from
An identity’stype says where Sail gets the keys it signs with:
For an
aws identity, the role must trust your Sailboxes, set up as in
Identity tokens. Sail gets the role’s keys
with an identity token for the Sailbox whose audience is sts.amazonaws.com,
so your role’s trust policy decides which Sailboxes may use it.
sigv4 is short for Signature Version 4, the signing method that AWS and
S3-compatible storage share.
In the Sailbox
Code in the Sailbox uses the AWS SDKs or the AWS CLI as usual. These tools will not send a request until they have keys to sign with, so give the Sailbox placeholders, such asAWS_ACCESS_KEY_ID=placeholder and
AWS_SECRET_ACCESS_KEY=placeholder. Sail discards the placeholder signature
and signs the request again with the identity’s keys, for the same region and
service. The real keys never enter the Sailbox.
A request sent with no signature, such as one from plain curl, is not
signed and fails.
Writing the rule
- An identity’s name starts with a letter or number and uses only letters, numbers, underscores, and dashes.
cloud_identitycannot share a rule’srequestwithset,add,remove, orreplace.- The rule needs a named host. It cannot be used under
*, where code in the Sailbox would choose who receives the signed request. - Sail signs what the rule matches, so the identity’s own permissions decide what the Sailbox can do with it. Grant only what the work needs. A role allowed to create access keys, for example, lets the Sailbox create one and read it.
What does not work
Ordinary calls from the AWS SDKs and the AWS CLI work, including S3 uploads and downloads of any size. Most Sailboxes never meet the exceptions below. Check them if a request to a host with acloud_identity rule comes back
with status 502. That is Sail’s answer when it cannot sign a request, and the
request is not sent. A role that refuses the Sailbox gets the same answer.
TLS settings
tls_config sets how Sail connects to a host over HTTPS: which certificate
authorities it trusts, and the client certificate it presents. Hosts are
written as under rules, and Sail picks the most specific entry the
same way.
- Each entry needs
trusted_cas,client_certificate, or both. - The private key is always a secret, never written into the policy, so a policy with a client certificate must be saved.
- A host that asks for a client certificate when its entry has none fails the
connection. So does a host whose certificate the entry’s
trusted_casdo not cover. - Like
rules,tls_configapplies to HTTPS only and does not make a host reachable. Its hosts must be covered by the allowlist the same way, as described in Rules and the allowlist. - The settings also apply when a
forwardrule sends a request to the host.
Limits
allowlistandblockedhold at most 128 entries each.rulesnames at most 100 hosts and holds at most 100 rules in total.tls_confignames at most 100 hosts.envholds at most 100 variables.cloud_identitiesholds at most 20 identities.- A request body a rule edits is at most 8 MiB.
- A document is at most 64 KiB.
- A saved policy’s name is at most 128 characters with no control characters.
Errors
- An invalid document fails the call with
InvalidArgumentError(SailError::InvalidArgumentin Rust), naming the part to fix. Nothing is created or changed. - Setting
no_networkon a Sailbox that exposes ports or SSH fails withApiError(SailError::Apiin Rust). - Setting a policy with
envon a Sailbox created beforeenvexisted fails and asks you to upgrade the Sailbox first. - Deleting a saved policy that a Sailbox still uses fails with
EgressPolicyInUseError(SailError::Apiin Rust).