Documentation
¶
Overview ¶
Package integrity provides SHA-256 checksum verification for plexd binaries and hook scripts.
Package integrity provides SHA-256 checksum verification for plexd binaries and hook scripts.
Index ¶
- Constants
- func HashFile(path string) (string, error)
- type CheckResult
- type Config
- type Store
- type Verifier
- func (v *Verifier) BinaryChecksum() string
- func (v *Verifier) Run(ctx context.Context, nodeID string) error
- func (v *Verifier) VerifyBinary(ctx context.Context, nodeID string) error
- func (v *Verifier) VerifyHook(ctx context.Context, nodeID, hookPath, expectedChecksum string) (bool, error)
- func (v *Verifier) VerifyHooksDir(ctx context.Context, nodeID string)
- type ViolationReporter
Constants ¶
const ( ViolationTypeBinary = "binary" ViolationTypeHook = "hook" )
Violation type constants used in integrity violation reports.
const DefaultVerifyInterval = 5 * time.Minute
DefaultVerifyInterval is the default interval between integrity verification runs.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type CheckResult ¶
type CheckResult struct {
// Path is the filesystem path that was verified.
Path string
// Expected is the hex-encoded SHA-256 checksum that was expected.
Expected string
// Actual is the hex-encoded SHA-256 checksum that was computed.
Actual string
// OK is true when Expected matches Actual (or when establishing a new baseline).
OK bool
}
CheckResult holds the outcome of a file integrity check.
func VerifyFile ¶
func VerifyFile(path, expectedChecksum string, requireChecksum bool) (CheckResult, error)
VerifyFile computes the SHA-256 checksum of the file at path and compares it against expectedChecksum. When requireChecksum is true and expectedChecksum is empty, an error is returned (hooks must have a control-plane-provided checksum). When requireChecksum is false and expectedChecksum is empty, the computed checksum is returned as a new baseline with OK=true.
type Config ¶
type Config struct {
// Enabled controls whether integrity verification is active.
// Default: true (set by ApplyDefaults).
Enabled bool `yaml:"enabled"`
// BinaryPath is the path to the plexd binary to verify.
BinaryPath string `yaml:"binary_path"`
// HooksDir is the directory containing hook scripts to verify.
HooksDir string `yaml:"hooks_dir"`
// VerifyInterval is the interval between integrity verification runs.
// Must be at least 30s when enabled.
// Default: 5m
VerifyInterval time.Duration `yaml:"verify_interval"`
// WatchEnabled controls whether inotify file watching is active.
// When enabled, file changes in HooksDir trigger immediate checksum
// recomputation instead of waiting for the next periodic verification.
// Default: true (set by ApplyDefaults).
WatchEnabled bool `yaml:"watch_enabled"`
}
Config holds the configuration for integrity verification.
func (*Config) ApplyDefaults ¶
func (c *Config) ApplyDefaults()
ApplyDefaults sets default values for zero-valued fields. On a zero-valued Config, Enabled defaults to true. To disable integrity verification, set Enabled=false before or after calling ApplyDefaults.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store persists known-good checksums as a JSON file in the agent's data directory.
func NewStore ¶
NewStore creates a Store backed by dataDir/checksums.json. If the file does not exist, an empty store is created.
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
Verifier orchestrates integrity verification for the plexd binary and hook scripts.
func NewVerifier ¶
func NewVerifier(cfg Config, store *Store, reporter ViolationReporter, logger *slog.Logger) *Verifier
NewVerifier creates a Verifier with the given configuration, store, reporter, and logger.
func (*Verifier) BinaryChecksum ¶
BinaryChecksum returns the last computed binary checksum (thread-safe). Returns an empty string before any verification has run.
func (*Verifier) Run ¶
Run performs periodic integrity verification for the binary and hooks directory. When WatchEnabled is true, it also monitors the hooks directory via inotify for real-time change detection. Run blocks until the context is cancelled.
func (*Verifier) VerifyBinary ¶
VerifyBinary computes the binary checksum, compares against the stored baseline, and reports a violation on mismatch. On first run (no baseline), the checksum is stored as the new baseline.
func (*Verifier) VerifyHook ¶
func (v *Verifier) VerifyHook(ctx context.Context, nodeID, hookPath, expectedChecksum string) (bool, error)
VerifyHook verifies a hook script against the expected checksum from the control plane. Returns true if the hook is safe to execute, false if there is a mismatch. An error is returned if the expected checksum is empty (hooks require a checksum).
type ViolationReporter ¶
type ViolationReporter interface {
ReportViolation(ctx context.Context, nodeID string, report api.IntegrityViolationReport) error
}
ViolationReporter abstracts control plane violation reporting for testability.