auditfwd

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Jul 28, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package auditfwd provides audit data collection and forwarding from plexd mesh nodes to the control plane.

Index

Constants

View Source
const DefaultBatchSize = 500

DefaultBatchSize is the default maximum number of audit entries per report batch.

View Source
const DefaultCollectInterval = 5 * time.Second

DefaultCollectInterval is the default interval between audit collection cycles.

View Source
const DefaultReportInterval = 15 * time.Second

DefaultReportInterval is the default interval between reporting audit events to the control plane.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuditReporter

type AuditReporter interface {
	ReportAudit(ctx context.Context, nodeID string, batch api.AuditBatch) error
}

AuditReporter abstracts the control plane audit reporting API.

type AuditSource

type AuditSource interface {
	Collect(ctx context.Context) ([]api.AuditEntry, error)
}

AuditSource collects audit entries from a specific source.

type AuditdEntry

type AuditdEntry struct {
	Timestamp time.Time
	Type      string
	UID       int
	GID       int
	PID       int
	Syscall   string
	Object    string
	Path      string
	Success   bool
	Raw       string
}

AuditdEntry represents a single entry read from the Linux audit subsystem.

type AuditdReader

type AuditdReader interface {
	ReadEvents(ctx context.Context) ([]AuditdEntry, error)
}

AuditdReader abstracts Linux auditd access for testability.

type AuditdSource

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

AuditdSource implements AuditSource by reading from the Linux audit subsystem.

func NewAuditdSource

func NewAuditdSource(reader AuditdReader, hostname string, logger *slog.Logger) *AuditdSource

NewAuditdSource creates a new AuditdSource.

func (*AuditdSource) Collect

func (s *AuditdSource) Collect(ctx context.Context) ([]api.AuditEntry, error)

Collect reads auditd entries and maps them to api.AuditEntry values.

type Config

type Config struct {
	// Enabled controls whether audit forwarding is active.
	// Default: true (set by ApplyDefaults).
	Enabled bool `yaml:"enabled"`

	// CollectInterval is the interval between collection cycles.
	// Must be at least 1s.
	CollectInterval time.Duration `yaml:"collect_interval"`

	// ReportInterval is the interval between reporting to the control plane.
	// Must be >= CollectInterval.
	ReportInterval time.Duration `yaml:"report_interval"`

	// BatchSize is the maximum number of audit entries per report batch.
	// Must be at least 1. Default: 500.
	BatchSize int `yaml:"batch_size"`

	// LocalEndpoint configures an optional local data-plane endpoint.
	LocalEndpoint api.LocalEndpointConfig `yaml:"local_endpoint"`
}

Config holds the configuration for audit data forwarding.

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 audit forwarding, set Enabled=false before or after calling ApplyDefaults.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks that configuration values are within acceptable ranges.

type Forwarder

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

Forwarder orchestrates audit data collection and reporting.

func NewForwarder

func NewForwarder(cfg Config, sources []AuditSource, reporter AuditReporter, nodeID string, hostname string, logger *slog.Logger) *Forwarder

NewForwarder creates a new Forwarder. Config defaults are applied automatically.

func (*Forwarder) RegisterSource

func (f *Forwarder) RegisterSource(s AuditSource)

RegisterSource adds an audit source to the forwarder. Must be called before Run; it is not safe for concurrent use.

func (*Forwarder) Run

func (f *Forwarder) Run(ctx context.Context) error

Run starts the collect and report loops. It blocks until ctx is cancelled.

func (*Forwarder) Status

func (f *Forwarder) Status() (enabled bool, bufferSize, sourceCount, errorCount int, lastReport time.Time)

Status returns a snapshot of the forwarder's operational status.

type IngestClient added in v0.2.0

type IngestClient interface {
	ReportAudit(ctx context.Context, nodeID string, events []api.AuditEvent) (*api.IngestReceipt, error)
}

IngestClient is the control-plane seam a PlatformReporter reports wire audit events through. It is defined here (rather than reused from the api package) so the auditfwd package owns the exact shape it depends on.

type K8sAuditEntry

type K8sAuditEntry struct {
	Timestamp      time.Time
	Verb           string
	User           K8sUser
	ObjectRef      K8sObjectRef
	RequestURI     string
	ResponseStatus int
	Raw            string
}

K8sAuditEntry represents a single Kubernetes audit log entry.

type K8sAuditReader

type K8sAuditReader interface {
	ReadEvents(ctx context.Context) ([]K8sAuditEntry, error)
}

K8sAuditReader abstracts Kubernetes audit log access for testability.

type K8sAuditSource

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

K8sAuditSource implements AuditSource by reading Kubernetes audit logs.

func NewK8sAuditSource

func NewK8sAuditSource(reader K8sAuditReader, hostname string, logger *slog.Logger) *K8sAuditSource

NewK8sAuditSource creates a new K8sAuditSource.

func (*K8sAuditSource) Collect

func (s *K8sAuditSource) Collect(ctx context.Context) ([]api.AuditEntry, error)

Collect reads Kubernetes audit entries and maps them to api.AuditEntry values.

type K8sObjectRef

type K8sObjectRef struct {
	Resource  string `json:"resource"`
	Namespace string `json:"namespace,omitempty"`
	Name      string `json:"name,omitempty"`
}

K8sObjectRef represents the target object of a Kubernetes audit event.

type K8sUser

type K8sUser struct {
	Username string   `json:"username"`
	Groups   []string `json:"groups,omitempty"`
}

K8sUser represents the user identity from a Kubernetes audit event.

type LocalReporter

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

LocalReporter sends audit batches to a local data-plane endpoint.

func NewLocalReporter

func NewLocalReporter(cfg api.LocalEndpointConfig, fetcher SecretFetcher, nsk []byte, nodeID string, logger *slog.Logger) *LocalReporter

NewLocalReporter creates a LocalReporter that posts audit data to cfg.URL.

func (*LocalReporter) ReportAudit

func (r *LocalReporter) ReportAudit(ctx context.Context, nodeID string, batch api.AuditBatch) error

ReportAudit sends the audit batch to the local endpoint as a JSON POST.

type MultiReporter

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

MultiReporter dispatches audit batches to both a platform and a local reporter in parallel. The platform error is always returned; a local failure is logged as a warning but does not affect the caller.

func NewMultiReporter

func NewMultiReporter(platform, local AuditReporter, logger *slog.Logger) *MultiReporter

NewMultiReporter creates a MultiReporter that fans out to platform and local.

func (*MultiReporter) ReportAudit

func (m *MultiReporter) ReportAudit(ctx context.Context, nodeID string, batch api.AuditBatch) error

ReportAudit sends the batch to both reporters concurrently. Only the platform error is returned; local errors are logged as warnings.

type PlatformReporter added in v0.2.0

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

PlatformReporter implements AuditReporter by converting each audit entry into a wire AuditEvent and posting them to the platform ingest endpoint through an IngestClient.

func NewPlatformReporter added in v0.2.0

func NewPlatformReporter(client IngestClient, logger *slog.Logger) *PlatformReporter

NewPlatformReporter creates a PlatformReporter that reports through client.

func (*PlatformReporter) ReportAudit added in v0.2.0

func (r *PlatformReporter) ReportAudit(ctx context.Context, nodeID string, batch api.AuditBatch) error

ReportAudit converts the batch into wire audit events and posts them through the ingest client. An entry whose source is not part of the contract is skipped (Warn); an entry with an empty action or result, or a zero timestamp, is skipped (Debug), as the contract requires all three and would 400 the whole batch. When no events survive, it returns nil without calling the client (the ingest contract rejects an empty array). Every record the reporter discards is counted and periodically summarized, because dropping is invisible to the forwarder's own status.

type ProcessSource

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

ProcessSource implements AuditSource by emitting a single "plexd_started" audit entry on the first Collect call. Subsequent calls return nil.

func NewProcessSource

func NewProcessSource(hostname string) *ProcessSource

NewProcessSource creates a new ProcessSource.

func (*ProcessSource) Collect

func (s *ProcessSource) Collect(_ context.Context) ([]api.AuditEntry, error)

Collect returns the startup entry on the first call, nil thereafter.

type SecretFetcher

type SecretFetcher interface {
	FetchSecret(ctx context.Context, nodeID, name string, version int) (*api.SecretEnvelope, error)
}

SecretFetcher abstracts retrieval of encrypted secrets from the control plane.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL