Documentation
¶
Overview ¶
Package gatecases publishes the registry gate's behaviour as data: a table of cases, each a set of findings, the flags the gate reads, a policy, and the outcome the gate reaches (published, needs_review, rejected).
The gate itself (internal/scan's Evaluate) stays internal. The core's gate test runs every case in this table against it, and fails when the gate has a branch no case reaches, so the table is always what the gate does. A client that restates the gate's rule (the CLI's Examiner, which names the outcome a submission would be expected to reach) runs the same table in its own test; a core pin bump that changes the gate then fails that test until the restatement follows.
Two of the gate's inputs come from the manifest: the capability tokens it declares and whether it asks for the network without naming where. The package publishes those two derivations as code (DeclaredCapabilities and UnrestrictedNetwork), which the registry's scanner itself calls, and the table carries derivation cases for a client that reads them another way.
The table carries no other code of the pipeline. Its baseline is the platform baseline compiled into the registry; an operator may store another one, which GET /api/v1/platform/policy answers.
Index ¶
Constants ¶
const ( CapNetwork = "network" CapFSRead = "fs-read" CapFSWrite = "fs-write" CapExec = "exec" CapEnv = "env" CapTargetHosts = "targetHosts" CapBrowser = "browser" // CapDesktop is a release that uses the person's own computer: any // capabilities.desktop line. CapDesktop = "desktop" // CapComputerUse is a desktop line that does computer use. CapComputerUse = "computerUse" // CapSubagents is a persistent release that declares subagents. CapSubagents = "subagents" )
The capability tokens DeclaredCapabilities names, as a publication policy's requireHumanReview.whenCapabilities and blockedCapabilities name them.
const ( OutcomePublished = "published" OutcomeNeedsReview = "needs_review" OutcomeRejected = "rejected" )
The gate's outcomes, as the registry names them.
const ( QueuePlatform = "platform" QueueOrg = "org" )
The review queues a needs_review outcome lands on.
Variables ¶
This section is empty.
Functions ¶
func CapPersistent ¶ added in v0.6.1002
CapPersistent is the token of one key of capabilities.persistent, such as persistent.coder.
func Declaration ¶
Declaration is what a manifest declares, as S4's rating by declaration (rules.RateByDeclaration) reads it, from its canonical JSON. The scanner rates S4 with it, and a client restating the gate's rating reads it the same way. An unreadable manifest declares nothing but the base commands, so every capability family's hit is high.
func DeclaredCapabilities ¶
DeclaredCapabilities is the set of capability tokens a manifest declares, sorted, from its canonical JSON: the gate's Case.DeclaredCapabilities.
- network: egress hosts other than "none", a remote MCP server's host, or a package MCP server's own egress;
- fs-read, fs-write, exec: the line declares more than "none";
- env: a declared secret;
- targetHosts: any target host, a token of its own and never network, because the runner makes the session;
- browser: a browser line, readable or not, a token of its own and never network, because the browser reaches sites through the runner's browse proxy;
- desktop: a line for the person's own computer, readable or not, a token of its own; and computerUse when that line does computer use or does not read. The catalogue's egress for the servers it uses counts as network, as a package server's own egress does;
- persistent.<key>: each key capabilities.persistent declares, and every key when the block does not read;
- subagents: a persistent release that declares subagents, or whose dependencies do not read.
A manifest that is not JSON, or has no capabilities block, declares nothing.
func UnrestrictedNetwork ¶
UnrestrictedNetwork reports whether a manifest asks for the network without naming where: "*" egress, or a browser whose scope is any public site, or a browser line that does not read, which is taken the strict way, or a persistent agent's coding toolchain (capabilities.persistent.coder, or a block that does not read), whose commands reach the open web and whose browser any public site. It is the gate's Case.WildcardEgress, which the policy's wildcardEgress decides.
Types ¶
type Case ¶
type Case struct {
// Name says what the case shows; names are unique in the table.
Name string `json:"name"`
// Branch names the rule of the gate that decides the case.
Branch string `json:"branch"`
Findings []Finding `json:"findings,omitempty"`
// Policy is the effective policy; nil means the table's Baseline.
Policy *Policy `json:"policy,omitempty"`
// WildcardEgress: the manifest declares "*" egress, or a browser whose
// scope is public.
WildcardEgress bool `json:"wildcardEgress,omitempty"`
// JudgeForcesReview: the AI Review provider requires a person whatever
// its scores, or a stage failed closed.
JudgeForcesReview bool `json:"judgeForcesReview,omitempty"`
// DeclaredCapabilities are the manifest's declared capability tokens.
DeclaredCapabilities []string `json:"declaredCapabilities,omitempty"`
// Public: the agent is public.
Public bool `json:"public,omitempty"`
// NamespaceIsOrg: the agent is in an organization's namespace.
NamespaceIsOrg bool `json:"namespaceIsOrg,omitempty"`
// Want is the outcome the gate reaches.
Want Want `json:"want"`
}
Case is one input to the gate and the outcome it reaches.
type Derivation ¶
type Derivation struct {
// Name says what the case shows; names are unique among derivations.
Name string `json:"name"`
// Manifest is the manifest's canonical JSON. Only its capabilities block
// is read.
Manifest json.RawMessage `json:"manifest"`
// Want is what DeclaredCapabilities and UnrestrictedNetwork answer.
Want GateInputs `json:"want"`
}
Derivation is a manifest and what the registry derives from it for the gate.
type Finding ¶
type Finding struct {
// Scanner is the finding's scanner id ("S4/inj-override-001"). The gate
// reads it only to know a finding that says content went unread.
Scanner string `json:"scanner"`
// Severity is info, low, medium, high or critical.
Severity string `json:"severity"`
// Confidence is low, medium or high; a low-confidence finding never
// gates alone.
Confidence string `json:"confidence"`
}
Finding is an open finding as the gate weighs it.
type GateInputs ¶
type GateInputs struct {
// DeclaredCapabilities are the tokens, sorted; empty for none.
DeclaredCapabilities []string `json:"declaredCapabilities"`
// UnrestrictedNetwork is the case's WildcardEgress.
UnrestrictedNetwork bool `json:"unrestrictedNetwork"`
}
GateInputs is the pair of gate inputs a manifest gives.
type Policy ¶
type Policy struct {
// RequireHumanReview is "never", "always" or {"whenCapabilities": [...]};
// absent means "never".
RequireHumanReview json.RawMessage `json:"requireHumanReview,omitempty"`
// MaxAutoPublishSeverity is the worst severity that publishes; absent
// means the gate's fallback, the registry's baseline (medium since
// ruleset 0.3.0).
MaxAutoPublishSeverity string `json:"maxAutoPublishSeverity,omitempty"`
// WildcardEgress is "review" or "reject"; absent means "review".
WildcardEgress string `json:"wildcardEgress,omitempty"`
}
Policy is the part of the publication policy the gate reads, in the policy document's own shape. The other knobs (blockedCapabilities, allowedLicenses, blockedMcpServers, requireEvals) refuse at submission, before the gate.
type Table ¶
type Table struct {
// Baseline is the platform baseline policy. A case with no policy of its
// own is decided under it.
Baseline Policy `json:"baseline"`
// Cases are the gate's cases, each with the outcome it reaches.
Cases []Case `json:"cases"`
// Derivations are manifests and the two gate inputs the registry
// derives from each.
Derivations []Derivation `json:"derivations"`
}
Table is the published table of the gate's cases.