Security
Claims
On this page
Each row of the claims table quotes one security promise Brig makes and names the tests that defend it.
The quotes and section names come from docs/security.md in the Brig repository. Security on this site covers the same facts. Where a promise there rests on detail another page holds, such as broker.md, runtimes.md or secrets.md, a row quotes that page instead. This page lists the rows that quote docs/security.md and summarizes the rest. The full table is in the Brig repository.
Automated check #
script/check-claims.sh reads the table on every pull request. It fails in two cases:
- a quoted sentence is gone from its page
- a named test no longer exists
make claims runs the same check after its self-test.
Row format #
A row has three cells: claim, section, and defences.
Claim. The claim cell quotes the page. The check matches only the part in double quotes. A note in parentheses after the quote says which part of the sentence the row covers.
Quote the whole sentence, through its period. A qualifier added to the sentence on the page then ends the match. A list item or a table cell with no period is quoted whole. The match ignores line breaks and runs of spaces.
Section. The section cell names the heading above the sentence. The quote must be under that heading or under one nested in it. A sentence of a page other than security.md names its page first, with a colon, such as broker.md: Placeholder detection. The page is in docs/, and is not claims.md. A page's # title is not a section, since it holds the whole page.
Table shape. Every line after the table's delimiter row is a row, up to the first blank line, with or without its outer pipes. These fail the check:
- a line in the table that is not three cells
- a pipe line outside the table
Defence tokens #
Each defence in the last column is one token.
| Token | What it names | How the check finds it |
|---|---|---|
go:TestName |
a Go test | func TestName( in a _test.go file |
smoke:<text> |
an assertion in script/smoke.sh |
its ok "<text>" line |
vm:<check> |
a check in script/claims-vm.sh |
its vm_check <check> line |
macos:TestName |
a Go test that runs on macOS alone | as for go: |
macos-smoke:<text> |
an assertion in the part of script/smoke.sh that runs on macOS alone |
as for smoke: |
Any other token, a row with none, or text beside the tokens fails the check.
Mac checks #
CI runs on Linux. There a macos: test skips, and smoke never reaches a macos-smoke: assertion. The CI check resolves both by name and lists them as not run in CI. Before a merge that touches the broker, run go test ./... and script/smoke.sh on a Mac.
VM checks #
A vm check needs a booted sandbox, and CI has no runtime. CI resolves a vm row by name and lists it as not yet run.
| Command | What it tests |
|---|---|
make claims-vm |
builds brig from this checkout and runs the checks against that binary. It runs where hull or nerdctl is on PATH, and skips where neither is. |
script/claims-vm.sh |
run by hand, tests the brig on PATH unless BRIG names another |
script/claims-vm.sh --self-test |
runs in CI, as described below |
Run make claims-vm before a merge that touches the run path.
The self-test answers every check from a fake guest that leaks one thing at a time. Each check must fail on the leak it tests for. A few checks also run their real probes through a stub brig on the host, so a probe with no answer also fails.
The self-test proves that each check judges an answer correctly. Only a booted sandbox proves that the guest leaks nothing.
Claims table #
These rows quote docs/security.md.
| Claim | Section | Defended by |
|---|---|---|
| "Beyond those, the guest does not have your keychain, your SSH agent, your secret manager, or any other directory on the host." (your keychain) | The boundary | go:TestTheRunPathReadsNoKeychain vm:keychain-not-reachable vm:secret-service-not-reachable |
| "Beyond those, the guest does not have your keychain, your SSH agent, your secret manager, or any other directory on the host." (your secret manager) | The boundary | go:TestTheRunPathCannotReachTheImporter go:TestUnresolvedReferencesAreRejectedButOrdinaryURLsAreNot |
| "Beyond those, the guest does not have your keychain, your SSH agent, your secret manager, or any other directory on the host." (your SSH agent) | The boundary | vm:ssh-agent-not-forwarded vm:no-agent-socket |
| "Beyond those, the guest does not have your keychain, your SSH agent, your secret manager, or any other directory on the host." (any other host directory) | The boundary | vm:other-host-directory |
| "Forwarded values go into the runtime process's own environment, and only the variable name appears on its command line." | Not in argv | go:TestSplitEnvKeepsValuesOutOfArgv go:TestRunArgsKeepsSecretValuesOutOfArgv smoke:credential values reach the runtime, but never through argv smoke:argv names the variables only |
| "Nothing is written into the guest home from the host for this." | Credentials | smoke:no credential is written into the workspace |
"So every host-side read and write Brig makes inside the guest home goes through an os.Root opened on it." |
Writing into the workspace | go:TestMarkerWriteRefusesAPlantedSymlink go:TestSetupGitRefusesASymlinkedGitconfig |
"A variable on the profile's deny list is refused, with the reason." |
Credentials | go:TestDenyAppliesToRefdValues go:TestOffSpellingsDoNotForwardADeniedCredential smoke:the metered key is refused, and says why smoke:a denied key never reaches the guest env line of a run smoke:a denied key's value never reaches argv, even under BRIG_ENV_ARGV=1 |
| "Inside Brig, the guest has your guest home mounted as its home, read-write." | The boundary | smoke:the workspace is mounted as the guest home vm:guest-home-read-write |
"Name a project on the run line and that project is a second host directory, also mounted read-write, at /work/<name>." |
The boundary | smoke:the project is mounted at /work/<basename> vm:project-at-work |
| "The guest gets only the credentials you deliver to it." | What the agent can reach | smoke:an undeclared ambient variable and its value reach no runtime argv or env line smoke:an undeclared ambient variable stays out under an override too smoke:the declared credential name reaches the guest |
"--home pointed at a symlink is refused for the same reason, with the same kind of message, and is fixed by naming the real directory." |
Writing into the workspace | go:TestWorkspaceStillRefusesASymlinkAtTheWorkspace go:TestSymlinkedWorkspaceRootIsRefused go:TestWorkspaceRefusesASymlinkedParentComponent |
"The one case with no innocent reading is an image sitting under our registry whose signature does not verify. That is the case that stops." (an image under ghcr.io/brig-sh/) |
Guest images | smoke:a bad signature on our own image is reported smoke:a bad signature stops the boot (exit 5) with no terminal to ask go:TestVerifyRefusesAFailedSignatureWithNoTerminal go:TestVerifyRefusesAFailedSignatureWithStdinOnDevNull |
"A scheme:// value read from the environment is refused as an unresolved secret-manager reference." |
Credentials | smoke:a secret-manager reference is not forwarded go:TestUnresolvedReferencesAreRejectedButOrdinaryURLsAreNot go:TestEnvRefsStillGetTheUnresolvedRefGuard |
| "The object cosign checked is the object that runs, and the success line names the digest instead of the tag it came from." (the object that runs) | Digest pinning | go:TestVerifyResolvesVerifiesAndPinsAMatchingDigest go:TestRunArgsBootsThePinnedDigest go:TestNerdctlBootsTheVerifiedDigest smoke:the verified digest is what hull was told to boot |
"brig info --json names the channel of each credential as its source: environment, secret, file or broker." (broker) |
Credentials | go:TestEnvelopeHasABrokerRow |
| "The broker keeps the keys in memory and writes none of them to the secret store or to a file." | The aws route | go:TestNothingVendedOnDisk |
| "The audit line names the access key id it handed out, and never the secret key or the session token." | The aws route | go:TestVendAuditHasNoSecret |
"A run with a route that vends is refused when the profile or BRIG_FORWARD_ENV also hands the guest AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_PROFILE, AWS_DEFAULT_PROFILE, AWS_CONFIG_FILE, AWS_SHARED_CREDENTIALS_FILE, AWS_WEB_IDENTITY_TOKEN_FILE, AWS_ROLE_ARN, or an AWS_CONTAINER_* variable." |
The aws route | go:TestAVendingRunThatForwardsAWSVariablesIsRefused |
"It is also refused when ~/.aws would be in the guest: a guest home that already holds .aws/credentials or .aws/config (for example --home ~), or a profile volume, files: binding or host config seed at .aws, or a seed copied from your own ~/.aws." |
The aws route | go:TestAVendingRunRefusesAGuestHomeWithAWS go:TestAVendingRunRefusesAWSPutInTheGuestHome |
"In role mode they last 30 minutes, or 25 minutes to an hour with brig secret import --session-duration." |
The aws route | go:TestPointerSessionBounds go:TestFetchAsksForThePointersSession go:TestImportAWSRefusesASessionOutOfRange |
| "It refuses credentials with no expiry, such as the long-lived keys of an IAM user." | The aws route | go:TestFetchRefusesNoExpiration |
"Self mode is never a default: brig secret import refuses an import that names neither mode, or both." |
The aws route | go:TestImportAWSNeedsAnAnswer |
| "A secret you import again with another role or mode takes effect at the next fetch: the broker does not serve keys it fetched for the old secret, and fetches again." | The aws route | go:TestCacheRefetchesOnPointerChange |
| "The secret holds that pointer and no key." | The aws route | go:TestImportAWSStoresNoCredential |
"The broker runs aws with every AWS_ variable removed from its environment, so a variable in your shell, such as AWS_PROFILE or AWS_ACCESS_KEY_ID, never decides which identity a sandbox gets." |
The aws route | go:TestBrokerAWSEnvHasNoAWSVars go:TestFetchEnvIsExactlyCLIEnv go:TestEnvironDropsAWSVariables go:TestExecEmptyEnvIsEmpty |
"No package on the run path links the code that runs aws." |
The aws route | go:TestTheRunPathCannotReachAWS go:TestOnlyTheImportVerbReachesAWSFromTheCLI |
| "The guest holds only the session token of the route." | The gcp route | go:TestGuestEnvGCPRouteHoldsNoSecret go:TestServicesRouteForwardsToTheService go:TestServicesRouteGuestNeverSeesTheGoogleToken |
"A service that allows POST has to list paths that name their verb exactly, such as /v2/entries:list." |
The gcp route | go:TestServicesRouteVerbPathIsExact go:TestServicesRouteWildcardMatchesAVerb go:TestServicesRouteLoggingPostRead |
"The broker refuses the method-override headers X-HTTP-Method-Override, X-HTTP-Method and X-Method-Override, the query parameters $httpMethod and httpMethod, and batch requests." |
The gcp route | go:TestServicesRouteRefusesMethodOverride go:TestServicesRouteRefusesBatch |
"Self mode is never a default: brig secret import refuses a gcloud import that names neither mode, or both." |
The gcp route | go:TestGCloudImportNeedsAMode go:TestGCloudImportRefusesTwoModes |
"A token lives as long as gcloud makes it, about an hour, and the broker mints a new one when it has less than 2 minutes left." (the 2 minutes) |
The gcp route | go:TestGetMintsAgainUnderTheMargin go:TestAMintCloseToExpiryIsServedForTheFloor |
"A minted token is sent only on a route with services, to its Google APIs." |
The gcp route | go:TestAGCPRouteInjectsTheMintedToken go:TestAPointerOnARouteWithoutServicesIsRefused |
"A pointer on any other route is refused with check=credential.gcponly." |
The gcp route | go:TestAPointerOnARouteWithoutServicesIsRefused |
| "A self-mode pointer also names the account of the login, and a token for any other account is refused." | The gcp route | go:TestMintSelfRefusesAnotherAccount go:TestGCloudImportSelfNeedsAnAccount |
| "The secret holds that pointer and no token." | The gcp route | go:TestGCloudImportStoresAPointerNotAToken |
"It runs gcloud without GOOGLE_APPLICATION_CREDENTIALS, CLOUDSDK_CORE_ACCOUNT, CLOUDSDK_ACTIVE_CONFIG_NAME and every CLOUDSDK_AUTH_* variable, so a variable in its environment does not decide which identity a sandbox gets." |
The gcp route | go:TestEnvironDropsIdentityVariables go:TestTheBrokersEnvironmentDoesNotPickTheIdentity |
| "The import applies the same rule." | The gcp route | go:TestDefaultGCloudCLIDropsIdentityVariables |
"Neither keeps CLOUDSDK_CONFIG, so both read the logins under $HOME/.config/gcloud, and the import refuses while CLOUDSDK_CONFIG is set." |
The gcp route | go:TestEnvironDropsIdentityVariables go:TestGCloudImportRefusesWhileCloudSDKConfigIsSet |
"No package on the run path links the code that runs gcloud." |
The gcp route | go:TestTheRunPathCannotReachGCloud |
| "A secret you import again with another configuration, mode or service account takes effect at the next request." | The gcp route | go:TestAPointerChangeIsNotServedTheOldToken |
"When gcloud can mint no token, a new run is refused with exit 6, and a request from a running guest gets a 502." |
The gcp route | go:TestRegistrationIsRefusedWhenTheMintFails go:TestCredentialRefusalExits6 go:TestAFailedMintSendsNothing |
| "An upstream 401 to a minted token goes back to the guest, with no new mint and no retry." | The gcp route | go:TestAMintedTokenPassesA401Through go:TestAMintedTokenIsNotRenewedOnARouteWithALifecycle |
| "The broker serves only a route that vends on that path, and refuses any other route before it reads the token." | The aws route | go:TestLinkLocalRefusesARouteThatDoesNotVend go:TestVendOnlyArrivalRefusesOtherRoutes |
"Brig adds no allow rule for it." (the link-local address of a route that vends) |
Host services | go:TestAVendingRunAllowsNoLinkLocalAddress go:TestRulesetDivertsTheLinkLocalAddress |
Claims on other pages #
The other rows quote the page that holds the detail. Each topic below has several rows, and the full table names the tests.
| Topic | Page and sections | What the rows defend |
|---|---|---|
| Requests through a route | broker.md: Request path, Headers, Response |
A request that fails a step gets the error of that step, and the upstream is never dialed. Request trailers are not forwarded. The response drops every Set-Cookie and every header that holds an injected string, and redacts injected strings in the body. |
| Placeholder detection | broker.md: Placeholder detection, Holding the body |
The broker scans each request for every live token of the sandbox, in several encodings, split across lines and in compressed bodies. A body the budget cannot hold is never forwarded unscanned. |
| Transports and route modes | broker.md: Transports, Route modes; policies.md: Routing brig.internal |
Each request carries the sandbox whose socket it arrived on. brig.internal is served on port 443 alone. A route in a mode this build does not serve is refused before boot, with exit 7. |
| Session tokens | broker.md: Session tokens, Lifecycle, Audit line |
A token of one sandbox fails on another. brig stop, brig rm and brig rm --all revoke the tokens of each sandbox they stop. The audit line never holds a credential, a token, a header value or a body. |
| The aws route | broker.md: Routes that vend, Fetching keys, Registration; secrets.md: A secret behind a route |
A route that vends serves its URL alone. No key is on a command line. A run that cannot get AWS credentials is refused at its start. |
| The gcp route | broker.md: Minting a token, Registration of a gcp route |
No token is on a command line, and no error repeats the token that gcloud prints. A new run on a lapsed gcloud login is refused at its start. A sandbox that was not registered before leaves no tokens behind. |
| Client certificates | broker.md: Upstream, Headers, Audit line; secrets.md: Getting a value in, Certificates and CA bundles |
The client key never leaves the broker, and a vm check confirms it is not in the guest. Two sandboxes never share a connection. Rotating the secret needs no restart. brig secret create --type tls checks the chain and never prints the key. |
| The renewal journal | secrets.md: The renewal journal |
A refresh is not sent without its journal. A crash during a refresh is recovered at the next request or registration. brig secret delete removes the journal with the secret. |