Documentation
¶
Overview ¶
Package bundle defines the rule bundle format (docs/bundle-format.md): parsing, validation, signature and key manifest verification.
Index ¶
- Constants
- Variables
- func Build(dir string) ([]byte, error)
- func ParseSignedManifest(b []byte) (*SignedManifest, *KeyManifest, error)
- func Sign(archive []byte, key SigningKey) ([]byte, error)
- func SignManifest(m *KeyManifest, roots ...SigningKey) ([]byte, error)
- type Active
- type AlertRule
- type Budget
- type Bundle
- type EvidencePolicy
- type KeyManifest
- type Manifest
- type ManifestKey
- type Policy
- type ResourceRef
- type Result
- type RootKey
- type Roots
- type RuleMeta
- type Signature
- type SignedManifest
- type SigningKey
- type StateRule
- type Store
- func (s *Store) Activate(archive, signature []byte, vals Validators, pol Policy) (*Active, error)
- func (s *Store) ActivateFetch(res protocol.BundleFetchResult, vals Validators, pol Policy) (*Active, error)
- func (s *Store) Current() (string, bool, error)
- func (s *Store) LoadLastKnownGood(vals Validators, pol Policy) (*Active, bool, error)
- func (s *Store) Rollback(version string, vals Validators, pol Policy) (*Active, error)
- func (s *Store) Versions() ([]StoredVersion, error)
- type StoredVersion
- type SuccessorRoot
- type Validators
- type Verifier
- func (v *Verifier) AcceptManifest(signed []byte) (*KeyManifest, error)
- func (v *Verifier) AcceptManifests(chain ...[]byte) (*KeyManifest, error)
- func (v *Verifier) KeyRevoked(keyID string) bool
- func (v *Verifier) Manifest() (*KeyManifest, bool)
- func (v *Verifier) Sequence() uint64
- func (v *Verifier) SetClock(now func() time.Time)
- func (v *Verifier) TrustedRoots() []RootKey
- func (v *Verifier) VerifyBundle(archive, signature []byte) (string, error)
- func (v *Verifier) VerifyFiles(dir string) (archive, signature []byte, err error)
Constants ¶
const ( MaxArchiveBytes = 16 << 20 MaxMemberBytes = 4 << 20 MaxMembers = 512 )
Archive limits enforced during extraction.
const ( ManifestFile = "bundle.yaml" DirState = "state" DirPrometheus = "prometheus" DirLoki = "loki" )
Archive layout.
const ( ClassState = "state" ClassPromQL = "promql" ClassLogQL = "logql" )
Rule classes (PRD R3).
const ( ScopeNode = "node" ScopeCluster = "cluster" )
Evaluation scopes (PRD R4).
const ( TargetKubernetes = "kubernetes" TargetHost = "host" )
Target types (PRD H7).
const ( CapInventory = "inventory" CapMetrics = "metrics" CapLogs = "logs" )
Capabilities a rule can require (PRD 5.2).
const ( ResolveRecovery = "recovery" ResolveManual = "manual" )
Resolution semantics.
const ( DomainKeyManifest = "EMBv1/keymanifest" DomainBundle = "EMBv1/bundle" )
Signature domains (docs/bundle-format.md).
const ( FileArchive = "bundle.tar.gz" FileSignature = "bundle.sig" FileKeyManifest = "keymanifest.json" )
Air-gap file names.
const DefaultKeepVersions = 5
DefaultKeepVersions is how many verified versions the store retains for rollback.
const DirKeyManifestChain = "keymanifests"
DirKeyManifestChain is the air-gap subdirectory holding earlier key manifests.
const EngineVersion = 1
EngineVersion is the rule engine version implemented by this agent (PRD U1, U4).
const ReasonUpgradeRequired = "agent upgrade required"
ReasonUpgradeRequired marks rules that need a newer rule engine (PRD U4).
const SchemaVersion = 1
SchemaVersion is the bundle.yaml schema version implemented by this agent.
Variables ¶
var ( // ErrNoRoots means the agent has no trust root and verifies nothing. ErrNoRoots = errors.New("bundle: no trust roots configured: set trust.roots or trust.rootsFile to the public half of your ExitMesh workspace agent trust root (shown on the connector page next to the enrollment token), so no key manifest or bundle can be trusted until then") // ErrUntrusted wraps every signature and key manifest failure. ErrUntrusted = errors.New("bundle: untrusted") )
var ErrInvalid = errors.New("bundle: invalid")
ErrInvalid wraps every archive, schema, and validation failure.
var ErrNotStored = errors.New("bundle: version is not stored")
ErrNotStored means the requested version is not retained.
Functions ¶
func Build ¶
Build packs a bundle directory into a reproducible bundle.tar.gz and checks that it parses.
func ParseSignedManifest ¶
func ParseSignedManifest(b []byte) (*SignedManifest, *KeyManifest, error)
ParseSignedManifest decodes the wrapper and the manifest without verifying signatures.
func Sign ¶
func Sign(archive []byte, key SigningKey) ([]byte, error)
Sign signs a bundle archive and returns the signature document.
func SignManifest ¶
func SignManifest(m *KeyManifest, roots ...SigningKey) ([]byte, error)
SignManifest signs a manifest with one or more root keys.
Types ¶
type AlertRule ¶
type AlertRule struct {
Meta RuleMeta
File string
Group string
GroupInterval time.Duration
Alert string
Expr string
For time.Duration
KeepFiringFor time.Duration
Labels map[string]string
Annotations map[string]string
}
AlertRule is one PromQL or LogQL alerting rule resolved from an upstream rule-group file.
type Budget ¶
type Budget struct {
MaxEvalTime time.Duration `yaml:"max_eval_time,omitempty"`
MaxSamples int `yaml:"max_samples,omitempty"`
MaxSeries int `yaml:"max_series,omitempty"`
MaxComplexity int `yaml:"max_complexity,omitempty"`
CounterBytes int `yaml:"counter_bytes,omitempty"`
}
Budget bounds evaluation cost per rule (PRD R6).
type Bundle ¶
type Bundle struct {
Manifest Manifest
Digest [32]byte
State []StateRule
PromQL []AlertRule
LogQL []AlertRule
// Files holds the raw archive members for inspection and persistence.
Files map[string][]byte
}
Bundle is a parsed, verified rule bundle.
type EvidencePolicy ¶
type EvidencePolicy struct {
MaxSamples int `yaml:"max_samples,omitempty"`
MaxBytes int `yaml:"max_bytes,omitempty"`
ContextLines int `yaml:"context_lines,omitempty"`
}
EvidencePolicy bounds evidence per rule (PRD L5, L7).
type KeyManifest ¶
type KeyManifest struct {
Sequence uint64 `json:"sequence"`
IssuedAt time.Time `json:"issued_at"`
SigningKeys []ManifestKey `json:"signing_keys"`
SuccessorRoots []SuccessorRoot `json:"successor_roots,omitempty"`
}
KeyManifest lists bundle signing keys and successor roots.
func NewKeyManifest ¶
func NewKeyManifest(sequence uint64, issuedAt time.Time, keys []ManifestKey, successors []SuccessorRoot) (*KeyManifest, error)
NewKeyManifest builds and checks a key manifest.
func (*KeyManifest) Key ¶
func (m *KeyManifest) Key(id string) (ManifestKey, bool)
Key returns the signing key with id.
func (*KeyManifest) Validate ¶
func (m *KeyManifest) Validate() error
Validate checks manifest structure.
type Manifest ¶
type Manifest struct {
Version string `yaml:"version"`
EngineVersion int `yaml:"engine_version"`
SchemaVersion int `yaml:"schema_version"`
TargetType string `yaml:"target_type"`
CreatedAt time.Time `yaml:"created_at"`
Rules []RuleMeta `yaml:"rules"`
}
Manifest is bundle.yaml.
type ManifestKey ¶
type ManifestKey struct {
ID string `json:"id"`
PublicKey ed25519.PublicKey `json:"public_key"`
NotBefore time.Time `json:"not_before"`
NotAfter time.Time `json:"not_after"`
RevokedAt *time.Time `json:"revoked_at,omitempty"`
}
ManifestKey is a bundle signing key with its validity window.
type Policy ¶
type Policy struct {
// TargetType, when set, must equal the bundle target type.
TargetType string
DefaultBudget Budget
MaxBudget Budget
DefaultEvidence EvidencePolicy
MaxEvidence EvidencePolicy
DefaultInterval time.Duration
MinInterval time.Duration
MaxInterval time.Duration
MaxFor time.Duration
MaxRules int
}
Policy is the local administrator upper bound. Bundle values above a maximum are capped.
type ResourceRef ¶
type ResourceRef struct {
Kind string `yaml:"kind"`
Namespace string `yaml:"namespace,omitempty"`
Name string `yaml:"name"`
}
ResourceRef names the alert labels that identify an affected resource.
type Result ¶
type Result struct {
Active []string
Disabled []string
Unsupported map[string]string
Rejected map[string]string
}
Result holds per-rule verdicts in manifest order.
type Roots ¶
Roots is the deployment's configured root key set; Threshold distinct root signatures are required (default 1).
func LoadRoots ¶
LoadRoots builds the root key set from configuration: a roots file (ParseRoots format) and inline keys ("<id>:<base64 ed25519 public key>"), merged; an empty result is ErrNoRoots.
func ParseRoots ¶
ParseRoots decodes and checks a roots.json document.
type RuleMeta ¶
type RuleMeta struct {
ID string `yaml:"id"`
Version int `yaml:"version"`
Class string `yaml:"class"`
Target string `yaml:"target"`
Scope string `yaml:"scope"`
File string `yaml:"file,omitempty"`
Group string `yaml:"group,omitempty"`
Alert string `yaml:"alert,omitempty"`
// Match selects among alerting rules sharing File, Group, and Alert by their static labels.
Match map[string]string `yaml:"match,omitempty"`
Category string `yaml:"category"`
Severity string `yaml:"severity"`
RequiredFields []string `yaml:"required_fields,omitempty"`
Capabilities []string `yaml:"capabilities"`
Evidence EvidencePolicy `yaml:"evidence,omitempty"`
DedupKey string `yaml:"dedup_key,omitempty"`
Resolution string `yaml:"resolution,omitempty"`
Budget Budget `yaml:"budget,omitempty"`
MinEngine int `yaml:"min_engine,omitempty"`
Disabled bool `yaml:"disabled,omitempty"`
Summary string `yaml:"summary,omitempty"`
// ResourceLabels maps alert labels to affected resources, for example
// {kind: Pod, namespace: namespace, name: pod}.
ResourceLabels *ResourceRef `yaml:"resource_labels,omitempty"`
}
RuleMeta carries the metadata of one rule (PRD R4). For PromQL and LogQL rules it references an alerting rule in an upstream rule-group file by File, Group, and Alert.
func (RuleMeta) DedupLabels ¶
DedupLabels returns the label names listed in dedup_key (comma separated).
type Signature ¶
Signature is one signature over a domain-separated digest.
func ParseSignature ¶
ParseSignature decodes a bundle signature document.
type SignedManifest ¶
type SignedManifest struct {
Manifest []byte `json:"manifest"`
Signatures []Signature `json:"signatures"`
}
SignedManifest carries the exact manifest bytes and root signatures.
type SigningKey ¶
type SigningKey struct {
ID string `json:"id"`
PrivateKey ed25519.PrivateKey `json:"private_key"`
}
SigningKey is a private ed25519 key with its identifier.
func GenerateKey ¶
func GenerateKey(id string) (SigningKey, error)
GenerateKey creates a new signing or root key.
func ParseSigningKey ¶
func ParseSigningKey(b []byte) (SigningKey, error)
ParseSigningKey decodes a private key file.
type StateRule ¶
type StateRule struct {
ID string `yaml:"id"`
Version int `yaml:"version"`
Target string `yaml:"target"`
Kinds []string `yaml:"kinds"`
Expr string `yaml:"expr"`
For time.Duration `yaml:"for,omitempty"`
KeepFiringFor time.Duration `yaml:"keep_firing_for,omitempty"`
Interval time.Duration `yaml:"interval,omitempty"`
Labels map[string]string `yaml:"labels,omitempty"`
Meta RuleMeta `yaml:"-"`
}
StateRule is one rule from state/*.yaml: a CEL predicate over normalized state.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store keeps the last known good bundle and prior versions for rollback.
func (*Store) Activate ¶
Activate verifies and validates a bundle and makes it the last known good; on failure nothing changes.
func (*Store) ActivateFetch ¶
func (s *Store) ActivateFetch(res protocol.BundleFetchResult, vals Validators, pol Policy) (*Active, error)
ActivateFetch accepts the key manifest of a bundle.fetch result, then activates its bundle.
func (*Store) LoadLastKnownGood ¶
LoadLastKnownGood reloads the current version; key expiry is not re-checked, revocation is.
func (*Store) Versions ¶
func (s *Store) Versions() ([]StoredVersion, error)
Versions lists retained versions, oldest first.
type StoredVersion ¶
type StoredVersion struct {
Version string `json:"version"`
Digest string `json:"digest"`
KeyID string `json:"key_id"`
StoredAt time.Time `json:"stored_at"`
Order uint64 `json:"order"`
Current bool `json:"-"`
}
StoredVersion describes one retained bundle version.
type SuccessorRoot ¶
type SuccessorRoot struct {
ID string `json:"id"`
PublicKey ed25519.PublicKey `json:"public_key"`
NotBefore time.Time `json:"not_before"`
}
SuccessorRoot is a root key introduced by a manifest signed by the current root set.
type Validators ¶
type Validators struct {
PromQL func(AlertRule) error
LogQL func(AlertRule) error
CEL func(StateRule) error
}
Validators check expressions; callers inject them to avoid import cycles. A nil validator skips that class.
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier holds the trust state: pinned roots, adopted successor roots, and the latest verified key manifest.
func NewVerifier ¶
NewVerifier returns a Verifier over roots, loading persisted trust state from store.
func (*Verifier) AcceptManifest ¶
func (v *Verifier) AcceptManifest(signed []byte) (*KeyManifest, error)
AcceptManifest verifies a signed key manifest against the current roots and persists it if it advances.
func (*Verifier) AcceptManifests ¶
func (v *Verifier) AcceptManifests(chain ...[]byte) (*KeyManifest, error)
AcceptManifests accepts a chain of signed key manifests in ascending sequence, skipping ones older than the verified sequence, and returns the latest verified manifest (nil when none is known).
func (*Verifier) KeyRevoked ¶
KeyRevoked reports whether the latest verified manifest revokes keyID now.
func (*Verifier) Manifest ¶
func (v *Verifier) Manifest() (*KeyManifest, bool)
Manifest returns the latest verified key manifest.
func (*Verifier) TrustedRoots ¶
TrustedRoots returns the pinned roots followed by adopted successor roots, sorted by id.
func (*Verifier) VerifyBundle ¶
VerifyBundle checks a bundle signature against the latest verified key manifest and returns the key id.