# Rules and their gates

**Spinbox is experimental: APIs change and data may be lost.** What is built and what proves it is on [Status](https://docs.spinbox.dev/reference/status.md); what Spinbox does not do is on [Limitations](https://docs.spinbox.dev/overview/limitations.md).

> The rules every entry point of Spinbox must keep, and the test or lint that fails the build when one is broken.

<!-- Generated by tools/refgen from spin:docs/security/README.md. Edit the source, not this file. -->

The rules every entry point must keep, from spin's [`docs/security/README.md`](https://github.com/spin-stack/spin/blob/51f7e0dea53e6f85aa855753766b688634487168/docs/security/README.md) at `51f7e0dea`. Code cites a rule's number at the line that keeps it. **Gate** is what fails a build when the rule is broken; *none* marks a rule kept only by each place remembering it. What is still open is on [Known gaps](https://docs.spinbox.dev/reference/security/known-gaps.md).

| # | Rule | Gate |
|---|---|---|
| I1 | Every procedure and route behind auth names its scope class. | `TestEveryProcedureHasAScope` |
| I2 | Every id taken from a request is authorized for the caller before anything is read or written with it. | `TestEveryHandlerResolvesTheWorkspaceItActsOn`, `TestEveryProcedureUsesTheMechanismItNames` |
| I3 | "Not yours" is answered as "not found", and ownership is checked before state. | the same |
| I4 | Membership and role are asked at the time of the action, not only when the resource was made. | `TestOnlyTheListedProceduresSkipTheTeam`, `TestAnOwnerRemovedFromTheTeamCannotUseItsWorkspace`, `TestAPortOfATeamsWorkspaceIsReachedOnlyByWhoIsInTheTeam`, `TestAStreamIntoATeamsWorkspaceEndsWithItsViewersMembership` - the gate reads handlers that resolve a workspace, and a port's decision is not one, so a new way in that decides for itself is held by a test of its own and not by the gate |
| I5 | A cookie-authenticated request that changes state or opens a socket names the dashboard's origin (or none). | `TestAPageOnAnotherSiteCannotSpendTheVisitorsCookie`, `TestEveryHTTPRouteIsMountedBehindAuth`, `TestOnlyTheDashboardIsTheDashboardsOrigin` |
| I6 | A credential is minted from `crypto/rand`, stored only hashed or sealed with its resource as AAD, compared in constant time, and revoked with what issued it. A guest's supervisor holds none to the control plane: its host carries the supervisor's stream under the host's own (I8), and revoking the host cuts every stream it carries. A workload may hold a key it exchanged its identity for (I26), a client's credential, which the host carries as a client's call and never as its own. | `TestAGuestsStreamIsCarriedByItsHostAndCutWithIt`; otherwise *none* |
| I7 | Bytes a guest controls are bounded (size, count, time) and made valid (UTF-8, paths) where they cross into the host. | the `CHECK`s; `TestWhatAGuestWritesIsBoundedBeforeItIsARow`, `TestAnAgentsThreadIndexIsBoundedAndReplacedWhole`, `TestAFloodOfNoticesIsAReadingAnInterval` |
| I8 | A host is trusted only for what is placed on it, and says only what a host may say - its guests' supervisors included, whose streams it carries under its own token. | `runnerMessageBinding` and its two tests; `TestAHostCarriesOnlyTheSupervisorsOfWorkspacesPlacedOnIt`, `TestWhatReachesTheControlPlaneIsTheSupervisorsCall`; `TestAHostsMintedCredentialWritesOnlyItsOwnSubtree`, against the store; `TestAHostsCredentialsLastAQuarterOfAnHour`, `TestAKeyForgottenIsAskedForAgainAndRefused`, `TestARevokedHostsVolumesArePendingRekey`, `TestAGroupsRunnerRemovedAsTakenHasItsDisksMarkedForRekeying`, `TestARekeyedVolumeOpensWithItsOwnKeyAlone`, `TestAHeadWrittenByAHostThatLeftIsPassedOverAndSaid`, the DST's `a-share-opens-only-its-snapshot` and `a-rekeyed-volume-depends-on-no-other-key`; `TestAMovedVolumeIsRestoredFromItsHoldersHistory`, `TestAMoveGrantsTheVolumeOverItsHistory`, the DST's `a-moved-volume-restores-its-new-holders-history`, the storage lane's `TestAMoveFencesTheHostTheVolumeLeft` |
| I9 | Object-store bytes are checked against the database-anchored digest before use; a shared key is read at its published version. | `TestALayerWrittenOverIsStillReadAsPublished` |
| I10 | An effect outside the database happens before the row that names it is forgotten. | *none* |
| I11 | Every third-party action is pinned by commit. | `task lint:workflows` |
| I12 | A URL a non-operator can set is refused when it resolves into the node's networks. | `TestAConnectionToThisNodeIsRefusedAsItIsMade`, `TestARedirectIsHeldToTheRule`, `TestAProxiedRequestGoesToTheAddressItWasCheckedAt`, `TestAnIssuersEndpointsAreHeldAsTheIssuerIs` |
| I13 | A component that speaks for another principal proves it is that component. | `TestOnlyTheProxyAsksForABrowser`, `TestAProxyIsGivenItsTokenForWhatItProves`, `TestAProxysProofIsGivenATokenOnce`, `TestAnOperatorGivesTheProxyItsTokenFromTheCommandLine`, `TestAMachineJoinsByWhoItIsOnlyAsANewHostOfANamedRole`, `TestAHostIsTheBuildItJoinedAs`, `TestAControlPlaneRetiresTheHostsOfBuildsItNoLongerServes`, `TestARetiredHostIsRevokedOnceItsWorkspacesAreSuspended`, `TestARetiredHostThatKeepsItsWorkspacesIsRevokedAtItsDeadline`, `TestARetiringHostIsGivenOnlyWhatItsDrainTakes`, `TestAHostOfARetiredBuildRunsNoWorkspace` |
| I14 | A machine's QEMU reaches only what it is handed, and holds only what it is bounded to - a core included. | `TestAProductionInstallationPlacesOnlyOnIsolatedHosts`, `TestEveryIsolationIsAskedOnce`, `TestAHostSaysItKeepsWhatItCanGiveAMachine`, `TestSMTTurnedOnGivesTheMachinesCoresOfTheirOwn`, `TestAHostThatNoLongerKeepsItsMachinesApartIsDrained`; the VM lane's `TestAMachinesQEMUReachesNothingOnTheHostOrAnotherMachine`, `TestAGuestAnswersOnlyTheRunner`, `TestAMachineIsBornWithinItsBounds`; `TestAMachineWithAUserOfItsOwnIsLaunchedApart`, `TestARunnersMachineMergesNoPagesAcrossMachines` |
| I15 | A program that parses a tenant's bytes on the host opens only the files of its operation. | `TestOnlyARootRunnerOnANewLandlockSaysItHoldsAProgramToItsFiles`, `TestAProductionInstallationPlacesOnlyOnIsolatedHosts`, `TestQemuImgDoesItsWorkWithOnlyItsFiles`, `TestAProgramReadsOnlyWhatItIsGiven`, `TestAProgramWritesOnlyWhatItIsGiven`, `TestAProgramMakesNoSocket`; the VM lane's `TestARootRunnersProgramHoldsNothingOfRoots`; the storage fakes refuse a file a run was not given, as the kernel does |
| I16 | A store on the control plane's machine is reached by the installation's administrators only through the control plane, and by its processes only for what each is. | `TestOnlyTheControlPlaneSaysWhoTheAdministratorIs`, `TestGrafanaShowsTheStoreToTheAdministratorItIsTold`, `TestNothingWithoutTheStoresKeyTakesItsMetrics`, `TestTheStoresRunWhileTheirControlPlaneDoes` (each account to each port, against the kernel), `TestTheStoresGuardNamesEveryPortAndOnlyAccountsTheImageHas`; the dashboard lane's `Monitoring access` and `Admin Metrics` |
| I17 | Only a workspace's owner and the guests they let in log in to it, each with a key that logs in as them - one they added, or a session's within its twelve hours - under the installation's certificate, never into a prebuild's build; a key, a passkey past the first and a guest are added only with an assertion of the person's passkey over a challenge naming that change, so their session alone adds none; the control plane holds no key that logs in, and is an SSH client of a guest only for a caller of `ExecService` whose key holds `workspace:exec` (ADR-0031). | `TestATunnelCertifiesOnlyAKeyThatLogsInAsTheCaller`, `TestAKeyIsAddedOnlyWithThePasskeysAssertionForIt`, `TestLettingAGuestInTakesTheOwnersPasskey`, `TestAKeyLogsInWhileItIsLive`, `TestAPasskeyIsRegisteredOnlyAsItsRelyingPartysOverItsChallenge`, `TestAnAssertionHoldsOnlyAsItsPasskeysOverItsChallenge`, `TestAPreparedRootLetsInOnlyByTheInstallationsCertificate`, `TestOnlyTheListedProceduresAdmitAGuest`; the sshd lanes' `TestASessionKeyLogsInWithACertificateOverIt`, `TestTheTerminalLogsInToTheClaimedGuest`; the VM lane's `TestOnlyTheOwnerAndTheirGuestsLogInToAWorkspace`, `TestAGuestTakenOutStaysOutOfAWorkspaceRestoredToBeforeIt`, `TestTheOwnerLogsInToACloneOfTheirOwnSnapshot`; `TestAGuestIsConnectedToOnlyByAClaimThatHolds`, `TestASessionIsRefusedBeforeTheRelayIsDialled` |
| I19 | A workspace's identity is signed by the host that runs it, for the machine that asked, named as the control plane's set says it - its team while its owner is in it, its owner, image and parent - never for a prebuild's build, and given only for an audience the installation allows; the control plane holds no key that signs one. | `TestATokenIsTheAskingMachinesWorkspace`, `TestAMachinesCIDIsUnnamedBeforeAnotherMachineIsGivenIt`, `TestAMachineIsNamedOnlyAtTheCIDTheRuntimeRunsItAt`, `TestTheSameCIDNamedAgainIsAnotherNaming`, `TestARestartedMachineIsNeverSignedForAsTheRunBefore`, `TestASessionReachesOnlyTheMachineItsWorkspaceWasNamedAt`, `TestAWorkspacesCIDIsItsRunningMachines`, `TestAMachinesCIDIsTakenBackBeforeAnotherMachineCanHaveIt`, `TestATokenIsForAnAudienceTheInstallationAllows`, `TestARunIsHeldToTheFirstKeyItPresents`, `TestAMachineIsNamedAsItsSetSays`, `TestAMachineNamedByNobodyIsGivenNoIdentity`, `TestACloneIsNamedAsMadeFromItsSnapshot`, `TestAStartNamesTheNewestSupervisorRelease`, `TestAHostOpensTheKeyThroughAnAttestedDecrypt`, `TestAHostWritesOnlyItsOwnIdentityRecords`; the VM lane's `TestAWorkspacesIdentityIsTheHostsSignatureOfItsSet`, `TestAMachineKilledUnderItsWorkspaceIsNoticedAndPutAway`, `TestAMachinesCIDIsHeardOfOnceHoweverItIsEnded`, `TestAnAdoptedMachinesCIDIsHeardOfOnceHoweverItEnds` |
| I18 | What a workspace applies of its owner's - dotfiles, shell, environment, editor settings, Taskfile, the workspace's own environment - is what they saved, with no value that hides what it runs; and the owner's own go only where they alone are root: not to a workspace a guest was asked into, a copy of another person's snapshot, or a prebuild's build. A guest is given its own workspace's environment, never another's. | `TestTheGuestIsHandedTheSettingsItsOwnerSaved`, `TestTheOwnersNewlySavedSettingsReachARunningGuest`, `TestAPrebuildsBuildIsTheProjectsAndNobodysOwn`, `TestTheOwnersSettingsGoOnceAGuestIsLetIn`, `TestSettingsHandedToARunningGuestApplyAsTheyCome`, `TestABuildChecksOutItsCommit`, `TestAPrebuildsCheckoutIsHeldToItsCommit`, `TestSettingsThatHideWhatTheyRunAreRefused`, `TestSettingsThatHideWhatTheyRunAreNotSaved`, `TestAProjectOpensFromItsNewestPrebuild`; the e2e lane's `TestTheOwnersSettingsArriveInTheGuest` |
| I20 | No commit holds a credential, in any file. | `task lint:secrets` |
| I21 | A team's secret kept as a reference is read only as the team whose secret it is, so a team's admin cannot name another team's secret, or the installation's. | `TestASecretIsReadInASessionTaggedWithItsTeam`, `TestASecretSetAsAReferenceIsReadAsTheTeamBeforeItIsKept`, `TestASecretKeptAsAReferenceIsReadAsTheTeamThatKeepsIt`; spin-terraform-aws's posture run `a_teams_secret_is_read_only_as_the_team` |
| I22 | A header the egress proxy sets for a workspace goes on no request its rule's scope - methods, a path prefix by whole segments - leaves out. | `TestAnInjectionIsSetOnlyOnTheRequestsItsScopeNames`, `TestARequestOutsideAnInjectionsScopeIsRefused`, `TestAnInjectionCrossesTheWireWhole` |
| I23 | A span a client sends the installation is kept as the client and the person whose credential sent it, never as anyone or anything else. | `TestAnExportReachesTheCollectorAsWhoSentIt`, `TestAnExportTheProxyCannotStampReachesNoCollector`, `TestExportsPastTheBoundAreToldToSendAgain`, `TestAnExportsSenderIsTheUserAuthFound`; the CLI lane's `TestE2E_ACommandIsASpanOfTheTraceItIsHanded` |
| I24 | A command run or a file read or written in a workspace through the API is the owner's, on a key made with their passkey that holds `workspace:exec`, and is recorded with who asked and the key it came on before it reaches the workspace. | `TestEveryProcedureHasAScope`, `TestOnlyTheListedProceduresAdmitAGuest`, `TestAStrangerGetsNothingOfSomebodyElses`; the e2e lane's `TestAKeyWithExecRunsACommandInAWorkspaceAndOneWithoutIsRefused` |
| I25 | A key delegated from another holds no more than it - scopes, team, projects, end, the workspaces and cores its tree holds, and how far down the chain - reaches no workspace outside its team and projects, and goes when the key it came from does. | `TestADelegatedKeyHoldsNoMoreThanItsParent`, `TestAKeyDelegatesNoMoreThanItHolds`, `TestAKeyReachesOnlyItsTeamsAndProjectsWorkspaces`; the CLI lane's `TestE2E_AnAgentDrivesAWorkspaceThroughMCPOnADelegatedKey` |
| I26 | A workload's identity buys a key only as the SPIFFE spec has it - a JWT-SVID go-spiffe validates against the trust domain's bundle, for the control plane's own audience - and only a child of the live key that made its workspace, within it (I25), for an hour at most, gone when the workspace goes to the trash. | `TestATokenForTheControlPlaneIsAJWTSVIDGoSpiffeValidates`, `TestAWorkloadExchangesItsIdentityForAChildOfTheKeyThatMadeItsWorkspace`; the e2e lane's `TestAnAgentInAWorkspaceDrivesAnotherOnTheIdentityOfItsWorkspace` |
| I27 | An installation's administrator acts on a workspace that is not theirs only through the procedures that say so, each from a session and audited with whose workspace it was: held in quarantine and released, its bandwidth bounded, its disk re-keyed, stopped, moved off a host that is gone - with a reason, which its owner reads on the workspace's history - and where it sends, read. Being an administrator opens no session or command in it, no snapshot of its disk, no start, and no say over who is let in: those are its owner's procedures, which answer an administrator as they answer a stranger. Nor does any of these acts read its env: each answers which workspace it acted on and what the act left, never the workspace itself. | `TestOnlyTheListedProceduresActOnAnybodysWorkspace`, `TestNoAdministratorsActOnAnybodysWorkspaceAnswersItsEnv`, `TestAnAdministratorsActsOnSomebodyElsesWorkspaceAnswerNoneOfItsEnv`, `TestAnAdministratorIsStillRefusedWhatIsTheOwnersAlone`, `TestAnAdministratorActsOnAWorkspaceThatIsNotTheirsAndItIsAudited`, `TestAnAdministratorsRecoverIsRefusedWithoutAReasonOrOfAHeldWorkspace`, `TestAStrangerGetsNothingOfSomebodyElses` |
