rules

package
v1.6.0 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package rules implements Interseptor's rule-pack format: a signed-intent tarball of Starlark checks (passive and active) plus a manifest, so a community can author, share, install, and remove whole bundles of checks — the "OhMy" ecosystem layer over the per-check authoring API.

A pack is a .tar.gz containing: 

manifest.json              — name, version, author, entries[] with per-file sha256
checks/<id>.star           — passive checks
active-checks/<id>.star    — active checks

Integrity: every file's sha256 is recorded in the manifest at build time and verified on read, so a corrupted or tampered pack is rejected before any check is written to disk. Optional ed25519 publisher signatures (signature.json) prove who built the pack — see sign.go and docs/rule-packs.md.

Index

Constants

View Source 
const (
	KindPassive = "passive"
	KindActive  = "active"
)

KindPassive / KindActive are the two check categories a pack can carry.

View Source 
const OfficialKeyID = "interseptor-1"

OfficialKeyID is the key id embedded for Interseptor-published packs.

Variables

This section is empty.

Functions

func ManifestDigest added in v1.6.0 

func ManifestDigest(m Manifest) []byte

ManifestDigest is the canonical bytes signed for a pack: name, version, and sorted entry hashes. File contents are already bound via Entry.SHA256.

func ParsePrivateSeed added in v1.6.0 

func ParsePrivateSeed(raw string) (ed25519.PrivateKey, error)

ParsePrivateSeed loads a 32-byte hex seed (or 64-byte hex private key) from a file or literal.

func ReadPack 

func ReadPack(r io.Reader) (Manifest, []File, error)

ReadPack decodes a pack tarball from r, parses its manifest, and verifies that every check file's sha256 matches the manifest. A missing manifest, an unknown member, or any hash mismatch is an error — nothing is returned partial.

func SignedLabel added in v1.6.0 

func SignedLabel(rec InstallRecord) string

SignedLabel returns a short UI/CLI label for an install record.

func VerifyManifestSignature added in v1.6.0 

func VerifyManifestSignature(m Manifest, keys Keyring) error

VerifyManifestSignature checks m.Signature against the keyring.

func WritePublicKeyFile added in v1.6.0 

func WritePublicKeyFile(path string, pub ed25519.PublicKey) error

WritePublicKeyFile writes pub as hex to path (0600 parent dir caller's job).

Types

type BuildOpts added in v1.6.0 

type BuildOpts struct {
	PrivateKey ed25519.PrivateKey
	KeyID      string
}

BuildOpts controls optional publisher signing when building a pack.

type CatalogPack added in v1.5.1 

type CatalogPack struct {
	Name        string `json:"name"`
	Version     string `json:"version"`
	Description string `json:"description"`
	Author      string `json:"author"`
	Checks      int    `json:"checks"`
}

CatalogPack describes a bundled pack available for one-click install.

func ListCatalog added in v1.5.1 

func ListCatalog() ([]CatalogPack, error)

ListCatalog returns bundled packs (sorted by name) with check counts.

type Entry 

type Entry struct {
	Kind   string `json:"kind"`
	ID     string `json:"id"`
	SHA256 string `json:"sha256"`
}

Entry is one check in a pack manifest: its category, id, and the sha256 of the file bytes — verified before install so a tampered file aborts the pack.

type File 

type File struct {
	Kind string
	ID   string
	Data []byte
}

File is one decoded check from a pack: its category, id, and source bytes.

type InstallOpts added in v1.6.0 

type InstallOpts struct {
	AllowUnsigned bool    // permit packs with no signature.json
	Keys          Keyring // nil → DefaultKeyring(registry root's parent global dir)
	TrustBuiltin  bool    // catalog/embedded packs (same trust as the binary)
}

InstallOpts controls publisher-signature policy on install.

type InstallRecord 

type InstallRecord struct {
	Name      string   `json:"name"`
	Version   string   `json:"version"`
	Installed string   `json:"installed"`
	Source    string   `json:"source,omitempty"`
	Signed    string   `json:"signed,omitempty"` // key id, "builtin", or ""
	IDs       []string `json:"ids"`
}

InstallRecord is one pack the operator has installed: its manifest identity plus the check ids it owns (so `rules remove` can delete exactly those files).

type Keyring added in v1.6.0 

type Keyring map[string]ed25519.PublicKey

Keyring maps key id → ed25519 public key.

func DefaultKeyring added in v1.6.0 

func DefaultKeyring(globalDir string) Keyring

DefaultKeyring returns the official key plus any ~/.interseptor/trusted-pack-keys/*.pub files (hex-encoded 32-byte keys; filename stem = key id).

type Manifest 

type Manifest struct {
	Name        string     `json:"name"`
	Version     string     `json:"version"`
	Description string     `json:"description,omitempty"`
	Author      string     `json:"author,omitempty"`
	Homepage    string     `json:"homepage,omitempty"`
	License     string     `json:"license,omitempty"`
	Created     string     `json:"created,omitempty"`
	Entries     []Entry    `json:"entries"`
	Signature   *Signature `json:"signature,omitempty"` // also mirrored as signature.json
}

Manifest is the pack's front matter plus its file index.

func BuildCatalogPack added in v1.5.1 

func BuildCatalogPack(name string, w *bytes.Buffer) (Manifest, error)

BuildCatalogPack writes a verified pack tarball for the named catalog entry into w. Sources are embedded; install uses the same sha256 gate as community packs.

func BuildPack 

func BuildPack(srcDir string, meta Manifest, w io.Writer) (Manifest, error)

BuildPack writes a pack tarball to w from the checks found under srcDir (expected layout: srcDir/checks/*.star and srcDir/active-checks/*.star). The supplied meta fills the manifest's descriptive fields; entries + hashes are computed from the files. Files are written in a stable (sorted) order so two builds of the same source are byte-identical.

func BuildPackOpts added in v1.6.0 

func BuildPackOpts(srcDir string, meta Manifest, w io.Writer, opts BuildOpts) (Manifest, error)

BuildPackOpts is BuildPack with optional ed25519 signing.

func SignManifest added in v1.6.0 

func SignManifest(m Manifest, priv ed25519.PrivateKey, keyID string) (Manifest, error)

SignManifest attaches an ed25519 signature to a copy of m.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry tracks installed packs in <root>/packs/registry.json. It is the source of truth for `rules list` / `rules remove` and for the REST/MCP pack surfaces. Filesystem layout for installed checks: passive → <root>/checks, active → <root>/active-checks (same dirs the engines already read), so an installed pack's checks run immediately with everything else.

func NewRegistry 

func NewRegistry(root string) *Registry

NewRegistry opens (or creates) the pack registry rooted at root (the global interseptor data dir, e.g. ~/.interseptor).

func (*Registry) Get 

func (r *Registry) Get(name string) (InstallRecord, bool, error)

Get returns one installed pack by name.

func (*Registry) InstallFile 

func (r *Registry) InstallFile(path, checksDir, activeChecksDir string) (Manifest, int, error)

InstallFile installs a pack from a local .tar.gz path.

func (*Registry) InstallFileOpts added in v1.6.0 

func (r *Registry) InstallFileOpts(path, checksDir, activeChecksDir string, opts InstallOpts) (Manifest, int, error)

InstallFileOpts is InstallFile with signature policy.

func (*Registry) InstallStream 

func (r *Registry) InstallStream(rdr readSeekFree, checksDir, activeChecksDir, source string) (Manifest, int, error)

InstallStream reads a pack from r, verifies it, writes its checks to disk, and records it in the registry. source is stored for provenance (e.g. a URL). Unsigned community packs are refused unless opts.AllowUnsigned or opts.TrustBuiltin.

func (*Registry) InstallStreamOpts added in v1.6.0 

func (r *Registry) InstallStreamOpts(rdr readSeekFree, checksDir, activeChecksDir, source string, opts InstallOpts) (Manifest, int, error)

InstallStreamOpts is InstallStream with signature policy.

func (*Registry) List 

func (r *Registry) List() ([]InstallRecord, error)

List returns installed packs, sorted by name.

func (*Registry) Remove 

func (r *Registry) Remove(name, checksDir, activeChecksDir string) (int, error)

Remove deletes a pack's check files and drops its registry entry. Files a user hand-edited are left in place (an entry only owns ids it recorded).

type Signature added in v1.6.0 

type Signature struct {
	Alg   string `json:"alg"` // "ed25519"
	KeyID string `json:"keyId"`
	Sig   string `json:"sig"` // base64 raw 64-byte signature
}

Signature is a detached ed25519 signature over the pack's integrity digest (name, version, and per-file sha256s). It proves publisher identity beyond the manifest sha256 gate (which only detects corruption/tamper-in-transit).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.