Documentation
¶
Overview ¶
Package auditfwd provides audit data collection and forwarding from plexd mesh nodes to the control plane.
Index ¶
- Constants
- type AuditReporter
- type AuditSource
- type AuditdEntry
- type AuditdReader
- type AuditdSource
- type Config
- type Forwarder
- type IngestClient
- type K8sAuditEntry
- type K8sAuditReader
- type K8sAuditSource
- type K8sObjectRef
- type K8sUser
- type LocalReporter
- type MultiReporter
- type PlatformReporter
- type ProcessSource
- type SecretFetcher
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 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 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.