gatecases

package
v0.6.1002 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 10 Imported by: 0

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

View Source
const (
	CapNetwork     = "network"
	CapFSRead      = "fs-read"
	CapFSWrite     = "fs-write"
	CapExec        = "exec"
	CapEnv         = "env"
	CapTargetHosts = "targetHosts"
	CapBrowser     = "browser"
	// 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.

View Source
const (
	OutcomePublished   = "published"
	OutcomeNeedsReview = "needs_review"
	OutcomeRejected    = "rejected"
)

The gate's outcomes, as the registry names them.

View Source
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

func CapPersistent(key string) string

CapPersistent is the token of one key of capabilities.persistent, such as persistent.coder.

func Declaration

func Declaration(manifestJSON []byte) rules.Declared

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

func DeclaredCapabilities(manifestJSON []byte) []string

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;
  • 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

func UnrestrictedNetwork(manifestJSON []byte) bool

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.

func Load

func Load() (Table, error)

Load decodes and checks the embedded table.

func (Table) PolicyOf

func (t Table) PolicyOf(c Case) Policy

PolicyOf is the effective policy a case is decided under.

type Want

type Want struct {
	// Outcome is published, needs_review or rejected.
	Outcome string `json:"outcome"`
	// Queue is QueuePlatform or QueueOrg when the outcome is needs_review, and
	// empty otherwise.
	Queue string `json:"queue,omitempty"`
}

Want is a gate outcome.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL