rules

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
• func ManifestDigest(m Manifest) []byte
• func ParsePrivateSeed(raw string) (ed25519.PrivateKey, error)
• func ReadPack(r io.Reader) (Manifest, []File, error)
• func SignedLabel(rec InstallRecord) string
• func VerifyManifestSignature(m Manifest, keys Keyring) error
• func WritePublicKeyFile(path string, pub ed25519.PublicKey) error
• type BuildOpts
• type CatalogPack
  • func ListCatalog() ([]CatalogPack, error)
• type Entry
• type File
• type InstallOpts
• type InstallRecord
• type Keyring
  • func DefaultKeyring(globalDir string) Keyring
• type Manifest
  • func BuildCatalogPack(name string, w *bytes.Buffer) (Manifest, error)
  • func BuildPack(srcDir string, meta Manifest, w io.Writer) (Manifest, error)
  • func BuildPackOpts(srcDir string, meta Manifest, w io.Writer, opts BuildOpts) (Manifest, error)
  • func SignManifest(m Manifest, priv ed25519.PrivateKey, keyID string) (Manifest, error)
• type Registry
  • func NewRegistry(root string) *Registry
  • func (r *Registry) Get(name string) (InstallRecord, bool, error)
  • func (r *Registry) InstallFile(path, checksDir, activeChecksDir string) (Manifest, int, error)
  • func (r *Registry) InstallFileOpts(path, checksDir, activeChecksDir string, opts InstallOpts) (Manifest, int, error)
  • func (r *Registry) InstallStream(rdr readSeekFree, checksDir, activeChecksDir, source string) (Manifest, int, error)
  • func (r *Registry) InstallStreamOpts(rdr readSeekFree, checksDir, activeChecksDir, source string, opts InstallOpts) (Manifest, int, error)
  • func (r *Registry) List() ([]InstallRecord, error)
  • func (r *Registry) Remove(name, checksDir, activeChecksDir string) (int, error)
• type Signature

Constants

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

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

const OfficialKeyID = "interseptor-1"

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

Functions

func ManifestDigest

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

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

func SignedLabel(rec InstallRecord) string

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

func VerifyManifestSignature

func VerifyManifestSignature(m Manifest, keys Keyring) error

VerifyManifestSignature checks m.Signature against the keyring.

func WritePublicKeyFile

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

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

Types

type BuildOpts

type BuildOpts struct {
	PrivateKey ed25519.PrivateKey
	KeyID      string
}

BuildOpts controls optional publisher signing when building a pack.

type CatalogPack

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

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

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

type Keyring map[string]ed25519.PublicKey

Keyring maps key id → ed25519 public key.

func DefaultKeyring

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

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

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

BuildPackOpts is BuildPack with optional ed25519 signing.

func SignManifest

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

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

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

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).