Documentation
¶
Overview ¶
Package declarations is the report on an agent's taint and cap declarations (docs/design/untrusted-content-and-amount-caps.md, sections 5.4 and 9). A host dumps the declarations of its agent as a document; the package reads one back strictly, recomputes the digest a run's run:start records (taint_policy_digest) from it, lists findings about one document, and classifies the difference between two as weakened, strengthened or changed. It reads no clock, store or configuration.
Index ¶
Constants ¶
const Format = "bide.declarations.v1"
Format tags a document. A document of another format is refused, never read as a version it is not.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Change ¶
type Change struct {
Class Class
Subject string // "policy", or "tool <name>"
What string
// Covered says the digest covers the declaration (the policy, and a tool's Untrusted, Exempt and Caps).
// A difference in a tool's Effect or its own gate is reported but changes no digest.
Covered bool
}
Change is one difference between two documents.
func Diff ¶
Diff is the changes from old to new, in a fixed order, and an error when the two documents do not agree with their digests: different digests with no covered difference means the digest covers something the documents do not carry; equal digests with a covered difference means the digest does not cover something the documents do. Either way the report cannot be trusted, so it is not given.
type Class ¶
type Class int
Class says which way a change moves what the declarations require.
const ( // Changed is a difference that is neither plainly looser nor plainly stricter (a gate timeout, another // untrusted source name, an amount member), and that a person should read. Anything the report cannot // judge as safe is Weakened, not Changed: a pipeline gate must stop on it. Changed Class = iota // Strengthened requires more than before. Strengthened // Weakened requires less than before: a raised threshold, a removed or renamed rule, a removed // Untrusted, a new TaintExempt, a weaker gate. Weakened )
type Document ¶
type Document struct {
Format string `json:"format"`
// Digest is the taint_policy_digest a run started by this agent records, "" for an agent with no taint
// policy (no run it starts is under taint).
Digest string `json:"digest"`
// TracksIdempotent is set by a version that writes each tool's Idempotent member. A document without it
// predates the member, so a tool's absent idempotent is unknown, not false (see Diff).
TracksIdempotent bool `json:"tracks_idempotent,omitempty"`
// Policy is the agent's taint policy, nil for none.
Policy *Policy `json:"policy,omitempty"`
// Tools is every tool the agent registers, by name.
Tools []Tool `json:"tools"`
}
Document is the declarations of one agent.
func Decode ¶
Decode reads a document strictly: one JSON value, no unknown member (a document written by a newer version is refused, not read with the parts this version knows), the right format, tools sorted by name without a repeat, and a digest that is the digest of what the document declares.
type Finding ¶
Finding is something to look at in one document. It is a note, not a verdict: nothing here says the declarations are wrong, only where a reader should look.
type Gate ¶
type Gate struct {
Single bool `json:"single,omitempty"`
Need int `json:"need,omitempty"`
Approvers []string `json:"approvers,omitempty"`
ExcludePrincipal bool `json:"exclude_principal,omitempty"`
TimeoutMS int64 `json:"timeout_ms,omitempty"`
}
Gate is an approval policy as the digest sees it. The approvers' keys are not part of it.
type Policy ¶
type Policy struct {
Gate *Gate `json:"gate,omitempty"`
Refuse bool `json:"refuse,omitempty"`
// RequireProvenance: every tool declares a provenance and every run states its input's.
RequireProvenance bool `json:"require_provenance,omitempty"`
}
Policy is the taint policy: the escalation gate a tainted turn's side effects need, or Refuse.
type Tool ¶
type Tool struct {
Name string `json:"name"`
Effect bool `json:"effect,omitempty"`
OwnGate *Gate `json:"own_gate,omitempty"`
Untrusted string `json:"untrusted,omitempty"`
// Trusted is the reason the tool's results are the host's own (a positive provenance declaration).
Trusted string `json:"trusted,omitempty"`
Exempt string `json:"exempt,omitempty"`
Caps []string `json:"caps,omitempty"`
// Idempotent is set for a tool that can have a side effect and is retry-safe (Safety.Idempotent without
// ReadOnly). It is for the diff only; the digest does not cover it.
Idempotent bool `json:"idempotent,omitempty"`
// RaisesSafety is the reason a wrapper declares a safer Safety than a tool inside it (agent.RaisesSafety).
RaisesSafety string `json:"raises_safety,omitempty"`
}
Tool is one registered tool. Untrusted, Exempt and Caps are what the digest covers; Effect (the tool can have a side effect) and OwnGate (its own approval gate) are for the findings and the diff only.
Source Files