brig docs

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.

Type a command, a flag or an error message.