Documentation
¶
Overview ¶
Package auditfwd provides audit data collection and forwarding from plexd mesh nodes to the control plane.
Index ¶
Constants ¶
const DefaultBatchSize = 500
DefaultBatchSize is the default maximum number of audit entries per report batch.
const DefaultCollectInterval = 5 * time.Second
DefaultCollectInterval is the default interval between audit collection cycles.
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.
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.
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 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 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, key string) (*api.SecretResponse, error)
}
SecretFetcher abstracts retrieval of encrypted secrets from the control plane.
Source Files