Log Management

LinuxGuard agent log management — precise redaction scope, rate limiting drop summaries, and central log collection patterns for journald, syslog, and structured JSON shipping.

This page covers the operational characteristics of LinuxGuard agent logs: what is and is not redacted, how rate limiting protects the agent under heavy log volume, and recommended patterns for shipping agent logs to central log management or SIEM systems.

For rotation defaults and operational knobs (logging.max_size_mb, log_level runtime reload), see Log Level and Rotation.

Redaction Scope

Important: Redaction matches ONLY slog attribute keys whose name matches the regex ^(api_key|enroll_token|.*_token|.*_secret)$. NO PII redaction occurs. Hostnames, IPs, usernames, file paths, and command-line arguments are NOT additionally redacted.

What Is Redacted

The agent's slog handler wraps every log record and applies a defense-in-depth filter to the attribute keys before the underlying handler writes them. The filter matches attribute keys — not values, not free-text content — against a case-insensitive regex:

^(api_key|enroll_token|.*_token|.*_secret)$

When an attribute key matches, the value is replaced with the literal string [REDACTED] before the record is serialized. Matching is case-insensitive and applies recursively to nested slog groups. Attribute key examples that match:

• api_key (exact match)

• enroll_token (exact match)

• auth_token, refresh_token, bearer_token (suffix match on *_token)

• client_secret, webhook_secret (suffix match on *_secret)

In addition to runtime redaction, a redactvet go/analysis analyzer flags slog.* call sites whose argument list contains identifiers from the package's ForbiddenSymbols set at compile time. Both layers share the same source-of-truth regex.

What Is NOT Redacted (PII Out of Scope)

The agent's log redaction is explicitly limited to secret-bearing attribute keys. The following classes of data are NOT additionally redacted and may appear in agent logs verbatim — PII NOT additionally redacted:

• Hostnames — host identifiers appear in event fields, error messages, and trace lines verbatim

• IP addresses — both IPv4 and IPv6 addresses, including addresses captured from network events

• Usernames — UNIX user names, account names, login UIDs, and any user-identifier captured by eBPF auth probes

• File paths — fully qualified file paths, including paths under user home directories

• Process command-line arguments — exec/execve event payloads include the full argv vector

• Free-text values of any kind — error messages, debug strings, and structured event payloads that are not key-matched by the regex

Customers shipping agent logs to centralized log management or SIEM systems are responsible for any additional PII redaction required by their compliance regime (GDPR, CCPA, HIPAA, or equivalent). Treat agent logs as containing PII-equivalent content by default.

Difference From Support-Bundle Redaction

The support-bundle's config.redacted.json uses an explicit struct mapping with SHA256 fingerprints, NOT the regex-based log redaction described above. The agent log content shipped inside a support bundle uses the same regex-based redaction as live logs — bundle inclusion does NOT add a PII redaction pass. See Support Bundles for the per-file redaction status table.

Rate Limiting and Drop Summaries

Under heavy log volume, the agent's slog handler applies per-level token-bucket rate limiting to protect the rotation file and downstream consumers.

What Is Rate-Limited

Only TRACE and DEBUG levels are rate-limited. INFO, WARN, and ERROR are always allowed and never touch any rate counter — bounding them would hide operator-visible signals under load.

Default per-second rates (configurable per build):

Level	Default rate (events/sec)	Burst
TRACE	1000	1000
DEBUG	500	500
INFO	unlimited	n/a
WARN	unlimited	n/a
ERROR	unlimited	n/a

Burst equals the per-second rate, so a one-second window of events passes through before the limiter starts dropping. Subsequent events at the same level that exceed the bucket are dropped and counted in per-level atomic drop counters.

Drop Summary Emission

Every 60 seconds, a summary goroutine snapshots the per-level drop counters, resets them, and emits a log record describing how many events were dropped at each rate-limited level. The summary is itself a regular log record at INFO level — operators can grep for dropped summaries to detect log floods.

The summary mechanism means a flood at TRACE or DEBUG will NOT silently disappear; the count of dropped records appears in the next 60-second window's summary line. The summary itself is not rate-limited.

Central Log Collection Patterns

The agent writes structured logs (slog text or JSON, depending on build configuration) to /var/log/linuxguard/agent.log. Operators commonly ship these to central log management. Three patterns are validated against the agent's logging characteristics.

journald Integration

When the agent runs under systemd (the standard install on Debian/Ubuntu, RedHat/CentOS, SUSE/openSUSE), systemd's journal captures stdout/stderr of the unit. The packaged unit file writes to a file-based log via lumberjack, NOT stdout, so journald does not capture agent records directly.

To make the agent log visible to journald, an operator can configure systemd to read from the rotated file via journalctl --file /var/log/linuxguard/agent.log or set up a systemd-journald ForwardToSyslog policy. For most operators, scraping /var/log/linuxguard/agent.log with a log shipper (vector, fluent-bit, syslog-ng) is more direct.

Syslog Forwarding

To forward agent logs to a remote syslog endpoint:

1. Configure a local syslog daemon (rsyslog, syslog-ng) to tail /var/log/linuxguard/agent.log.

2. Forward to the remote endpoint using TLS-protected RFC 5424 framing.

3. Configure the SIEM-side redaction layer to strip PII before storage.

See Syslog Forwarding for the integration pattern.

Structured JSON Shipping

For shipping to log aggregators that ingest structured JSON (Splunk HEC, Elasticsearch, Datadog logs):

1. Configure the agent to emit JSON-format records (per build configuration).

2. Run a log shipper (vector, fluent-bit) tailing /var/log/linuxguard/agent.log.

3. Authenticate the shipper to the aggregator using a service-account credential stored as a host-local secret — NOT in the agent's config.

4. Apply field-level redaction at the shipper or aggregator for any PII categories your compliance regime requires.

TLS and Authentication Recommendations

• Always TLS-protect the log transport, including journald-forwarded paths.

• Authenticate the log shipper with a credential that has write-only scope on the destination index/topic — never reuse the agent's API key.

• Do NOT route agent logs through unauthenticated UDP syslog in production. UDP loss + unauthenticated reception together breach almost every compliance regime's audit-log integrity requirement.

Cross-References

• Log Level and Rotation — Operational knobs: rotation defaults, log_level SIGHUP reload, logrotate sample.

• Support Bundles — Per-file redaction status table for the support bundle.

• Syslog Forwarding — Forwarding agent logs to remote syslog endpoints.

---

Related: Log Level and Rotation | Support Bundles | Syslog Forwarding | Troubleshooting