# Introduction Overview of LinuxGuard's Linux security monitoring agent — what it does, who it is for, and how to navigate the documentation set. LinuxGuard is a Linux-native security monitoring and response platform. It runs an agent on every monitored server, ships telemetry to a multi-tenant console, and provides identity-centric posture, drift detection, vulnerability management, compliance evidence, and active containment response. This documentation set is organized around the operator lifecycle — from first install through day-2 operations, fleet rollout, response, and audit evidence. Reference and Concepts sit alongside the lifecycle groups for lookup and background reading. ## Who this is for LinuxGuard is built for the operators who run Linux fleets day-to-day and the auditors and procurement reviewers who evaluate them: * **Security and platform engineers** running the agent on bare-metal, virtual machine, and container hosts. * **SRE and infrastructure teams** managing fleet rollout, configuration, and lifecycle across distributions. * **SecOps and incident responders** routing signals to ticketing, chat, and SIEM tools, then driving active containment. * **Compliance officers and internal auditors** assembling per-framework evidence and reviewing the vocabulary contract. ## Agent capabilities The LinuxGuard agent is a single Go binary that runs as the unprivileged `linuxguard` user once installed, collects host telemetry, and ships it to the control plane. * **eBPF kernel monitoring.** Process execution, network connections, file access, and authentication events captured via eBPF probes, with graceful fallback to auditd and `/proc` sources where eBPF is unavailable. * **Non-root runtime.** The agent runs as the unprivileged `linuxguard` user. Root is required only during install to drop capabilities and register the service. See [Security Architecture](/concepts/concepts/security-architecture). * **LoginUID identity capture.** Original login identity is preserved across `sudo` and `su` so privileged actions remain attributable across privilege escalation. * **Authentication event collection.** Syslog, journald, and `utmp`/`wtmp`/`btmp` events fused with eBPF-derived login and SSH session events. * **Configuration inventory with drift tracking.** Field-level snapshots of SSHD configuration, accounts, groups, sudo policies, and SSH keys with a per-object drift state machine. * **Container and OCI runtime awareness.** Cgroup-based container identification with containerd CRI enrichment, Docker socket queries, and Kubelet pod-resources integration for workload attribution. * **WebSocket real-time transport.** Bidirectional agent-to-console transport over mTLS with TOTP-based enrollment; HTTP polling remains as a fallback during gradual rollout. * **Runtime log-level control and log lifecycle.** Verbosity switches between `trace`, `debug`, `info`, `warn`, and `error` without a restart, with built-in log rotation, retention, and `SIGHUP` reload. * **Support-bundle collection.** Redacted, size-capped bundles with a redaction manifest and presigned upload, produced by the `support-bundle` command. ## Console and operations The console is a multi-tenant administrative surface organized around operator workflows. * **Dashboard.** Identity risk score, fleet posture snapshot, critical findings feed, and 7-day / 30-day / 90-day time-range tabs. * **Identity Intelligence.** Cross-server identity profiles, risk scoring with detractors and mitigators, non-human identity inventory with a three-tier classification (System Default / Application Service / Custom Service), and SSH key strength and age analysis. * **Access patterns and graph.** Behavioural baseline learning across observation, shadow, and active modes, with activity heatmaps, per-rule server edges, and click-to-highlight path traversal. * **Zero Trust Enforcement.** MITRE-mapped signals, a drift state machine tracking events from detection through resolution, sudo policy analysis, and file-monitoring alerts. * **Baselines.** Known-good snapshots of accounts, groups, SSHD and SSH client configuration, and sudo policies, with per-object baseline creation and drift detection. * **Efficiency.** CPU and memory rightsizing classification, fleet waste assessment, storage growth forecasting, and network I/O analysis. * **Audit.** Authorizations audit (account, group, sudo, SSH key baselines) and SUDO execution audit with fleet-wide command history and multi-dimensional filtering. * **Posture.** Cross-cutting Compliance, Configuration, and Health scoring with per-server ranking and 127-factor security posture recalculation. * **Zero Trust Expansion.** Playbooks, active-response history, sudo policies and executions, SELinux visibility, and a policy-violation ledger. * **Integrations and Notifications.** Jira, Microsoft Teams, Slack, Syslog, and generic webhooks; notification rules with severity filters, throttle windows, quiet hours, and suppression management. ## Detection, response, and compliance * **MITRE-mapped signals.** 100+ signal types covering execution, persistence, privilege escalation, defense evasion, credential access, discovery, lateral movement, and exfiltration. * **Behavioural anomaly detection.** Statistical baseline learning for login patterns (time, location, frequency) with GeoIP enrichment, plus sliding-window brute-force detection for repeated failed logins. * **Vulnerability lifecycle.** NVD, OSV, and OVAL feed ingestion with distribution-aware version matching, plus on-demand live verification probes that return an `is_vulnerable` boolean and drive lifecycle transitions through relevant, verified, not-relevant, remediated, and ignored states. * **Active response with triple opt-in.** Containment requires playbook enabled, trigger configured, and server-group scope, with four containment actions: lock account, kill sessions, disable SSH key, and revoke sudo. Blast-radius controls cap commands per server per hour, servers per execution, and concurrent commands per tenant, with automatic rollback on a configurable timeout and a chain-hashed immutable playbook audit trail. * **13 per-framework compliance mappings.** PCI-DSS v4.0.1, HIPAA, SOC 2, GDPR, NIS2, DORA, EU AI Act, FedRAMP / StateRAMP, HITRUST / FFIEC, NIST CSF 2.0, ISO/IEC 27001:2022, CIS Controls v8.1, and CIS Benchmarks. * **Three-tier vocabulary contract.** Every per-framework mapping uses `Satisfies`, `Supports`, or `Out of scope` with per-control evidence pointers and a canonical shared-responsibility statement. * **Compliance reports and posture scoring.** PDF export with evidence appendix, scoped to an audit period, plus per-object-type composite scores recalculated daily with snapshot history. ## Supported distributions LinuxGuard supports the following Linux distribution families: * **Debian-based systems** (Debian, Ubuntu) * **RedHat-based systems** (RHEL, CentOS, Fedora) * **SUSE-based systems** (openSUSE, SLES) * **Alpine Linux** Available as native binaries for amd64 and arm64, with ARMv7 Degraded and riscv64 best-effort builds. For detailed information about supported distributions, see the [Supported Distributions](/reference/reference/supported-distributions) page. ## Find what you need Choose the section that matches what you are trying to accomplish: * [**Get Started**](/get-started/get-started) — Five-minute quick start, prerequisites, and the choose-your-deployment decision guide. * [**Install**](/install/install) — Per-distribution and container install guides with the unified installer and repository setup. * [**Configure**](/configure/configure) — Enroll the agent to your tenant, set environment and tags, manage log levels. * [**Operate**](/operate/operate) — Day-2 SRE operations: service management, log inspection, signal handling, support bundles, uninstall. * [**Deploy at Scale**](/deploy-at-scale/deploy-at-scale) — Fleet automation across Ansible, Chef, Puppet, AWS, GCP, and Azure with idempotent enrollment. * [**Respond**](/respond/respond) — Notification rules and SecOps integration: webhook delivery, syslog forwarding, Splunk HEC. * [**Audit & Comply**](/audit-and-comply/audit-comply) — 13 per-framework compliance mappings with the Satisfies / Supports / Out-of-scope vocabulary contract. * [**Reference**](/reference/reference) — Cross-cutting lookups: agent commands, CLI per-command pages, supported distributions, glossary. * [**Concepts**](/concepts/concepts) — Background: security architecture, active response, alerting, and the console pillars. *** For support, contact . **Related**: [Changelog](/changelog) | [What Changed in the Console](/concepts/concepts/console/whats-changed) | [Concepts](/concepts/concepts) # Get Started Onboarding entry point for operators evaluating LinuxGuard — quick start, prerequisites, and choose-your-deployment guidance. Onboarding entry point for new operators evaluating LinuxGuard — covers the 5-minute quick start, prerequisites, and the choose-your-deployment decision guide. ## What's in this section * [**Quick Start**](/get-started/get-started/quick-start) — Install the LinuxGuard agent and verify enrollment in five minutes on a supported Linux host. # Quick Start Install the LinuxGuard agent and verify enrollment in five minutes on a supported Linux host. Get LinuxGuard running on your Linux system in 5 minutes. ## Prerequisites Before starting, ensure you have: * Linux system with kernel 4.18 or later (required for eBPF) * Root or sudo access * API Key and Tenant ID from the LinuxGuard console * Network access to `api.linuxguard.io` and `packages.linuxguard.io` For full system requirements, see the [Prerequisites](/install/install/prerequisites) guide. ## Step 1: Install Run the unified installer to download and install the LinuxGuard agent: ```bash curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | sudo bash ``` The installer automatically detects your Linux distribution and configures the appropriate package repository. For installation options and troubleshooting, see the [Installation Guide](/install/install). ## Step 2: Enroll Connect the agent to your LinuxGuard tenant: ```bash sudo linuxguard-agent enroll --api-key= --tenant-id= ``` Replace: * `` with your API key from the LinuxGuard console * `` with your tenant ID You can find both credentials in the **Settings** page of the LinuxGuard console. **Expected output:** ``` >> Sending initial snapshot... >> Initial snapshot sent successfully >> Successfully enrolled to LinuxGuard Endpoint: https://api.linuxguard.io/v1/ ``` For enrollment options like environments and tags, see the [Configuration Guide](/configure/configure). ## Step 3: Verify Confirm the agent is running: ```bash sudo linuxguard-agent status ``` **Expected output:** ``` linuxguard-agent is running with PID: 12345 ``` Your server should now appear in the LinuxGuard console within a few moments. *** **Next Step**: [Console Overview →](/concepts/concepts/console) **Related**: [Installation Guide](/install/install) | [Configuration](/configure/configure) | [What Changed](/concepts/concepts/console/whats-changed) | [Agent Commands](/reference/reference/agent-commands) # Install Install the LinuxGuard agent on supported Linux distributions — per-distro guides, prerequisites, and container deployment. This guide covers installing the LinuxGuard agent on your Linux systems. You can choose between two installation approaches: a unified installer script that automatically detects your distribution (recommended for quick setup), or distribution-specific repository configuration (recommended for production environments). > **Note**: Installing in a container? See the [Container Installation Guide](/install/install/container) for container-specific instructions. ## What's in this section * [**Prerequisites**](/install/install/prerequisites) — Tenant account, credentials, and system prerequisites required before installing the LinuxGuard agent. * [**Installation on Debian / Ubuntu**](/install/install/debian-ubuntu) — Install the LinuxGuard agent on Debian, Ubuntu, and derivatives via the APT repository. * [**Installation on RedHat / CentOS**](/install/install/redhat-centos) — Install the LinuxGuard agent on RedHat, CentOS, Rocky, and AlmaLinux via the DNF repository. * [**Installation on SUSE / openSUSE**](/install/install/suse) — Install the LinuxGuard agent on SUSE Linux Enterprise and openSUSE via the zypper repository. * [**Installation on Alpine Linux**](/install/install/alpine) — Install the LinuxGuard agent on Alpine Linux via the APK repository. * [**Container Deployment**](/install/install/container) — Container deployment options — when to use Dockerfile, runtime install, Kubernetes, and persistent-volume patterns. ## System Requirements Before installing, ensure your system meets these requirements: * **Kernel**: Linux kernel 4.18 or later (required for eBPF runtime detection) * **Architecture**: x86\_64 (AMD64) or aarch64 (ARM64) * **Network**: Outbound HTTPS access to `api.linuxguard.io` and `packages.linuxguard.io` * **Permissions**: Root or sudo access for installation ## Option A: Unified Installer (Recommended for Quick Setup) The unified installer automatically detects your Linux distribution and configures the appropriate package repository: ```bash curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | sudo bash ``` The installer will: * Detect your Linux distribution (Debian/Ubuntu, RedHat/CentOS, openSUSE/SLES, or Alpine) * Configure the appropriate package repository (APT, DNF/YUM, Zypper, or APK) * Install the LinuxGuard agent package and the `sysstat` dependency (provides `iostat`/`mpstat` for system metrics collection) ### Installer Options The installer supports the following options: | Option | Description | | ---------------- | -------------------------------------------------------------------------------------------- | | `--yes` or `-y` | Non-interactive mode for automated deployments (CI/CD, configuration management). | | `--fix-repo` | Repair existing repository configuration. Use if repository configuration becomes corrupted. | | `--help` or `-h` | Display help message. | ### Installation Examples **Basic installation (interactive):** ```bash curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | sudo bash ``` **Non-interactive installation for automation:** ```bash curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | sudo bash -s -- --yes ``` ## Option B: Distribution-Specific Installation For production environments where you want explicit control over repository configuration, follow the guide for your distribution: | Distribution | Guide | | ------------------------------- | ----------------------------------------------------------------- | | Debian, Ubuntu, Linux Mint | [Installation on Debian / Ubuntu](/install/install/debian-ubuntu) | | RedHat Enterprise Linux, CentOS | [Installation on RedHat / CentOS](/install/install/redhat-centos) | | SUSE Linux Enterprise, openSUSE | [Installation on SUSE / openSUSE](/install/install/suse) | | Alpine Linux | [Installation on Alpine Linux](/install/install/alpine) | Each guide provides step-by-step instructions for: * Manual repository configuration with GPG key verification * Distribution-specific package manager commands * Direct package download as an alternative * Distribution-specific troubleshooting tips ## Verification After installation, the LinuxGuard agent service should be installed but not yet running (it needs to be configured first). You can verify the installation by checking if the agent binary exists: ```bash which linuxguard-agent ``` You can also verify that the agent user was created: ```bash id linuxguard ``` ## Security The LinuxGuard agent is installed with security as a top priority. The installer creates a dedicated `linuxguard` user account, and the agent runs without root privileges with read-only access to system components. For detailed information about our security architecture, see the [Security Architecture](/concepts/concepts/security-architecture) page. ## Uninstallation If you need to remove the LinuxGuard agent, we provide a complete cleanup process that removes all agent files, configuration, and user accounts. See the [Uninstallation Guide](/operate/operate/uninstallation) for instructions. *** **Next Step**: [Configuration →](/configure/configure) **Related**: [Prerequisites](/install/install/prerequisites) | [Debian/Ubuntu Installation](/install/install/debian-ubuntu) | [RedHat/CentOS Installation](/install/install/redhat-centos) | [SUSE Installation](/install/install/suse) | [Alpine Installation](/install/install/alpine) | [Automated Deployment](/deploy-at-scale/deploy-at-scale) # Prerequisites Tenant account, credentials, and system prerequisites required before installing the LinuxGuard agent. Before you can start using LinuxGuard, you need to have a tenant account set up. A tenant is your organization's workspace in the LinuxGuard platform where all your agents and data are managed. ## Creating a Tenant If you don't already have a tenant account, you'll need to contact our sales team to have one created for you. **Contact**: When you contact sales, they will: * Set up your tenant account * Configure your organization's workspace * Prepare your access credentials ## Receiving Your Tenant Information Once your tenant has been created, you will receive an email containing: * **Login credentials** - Username and password to access the LinuxGuard console * **Tenant ID** - A unique identifier for your tenant (you'll need this for agent enrollment) > **Important**: Keep this email safe! You'll need the Tenant ID when configuring your agents. ## Accessing Your Tenant ID Later If you need to retrieve your Tenant ID after the initial setup, you can find it in the **Settings** page of the LinuxGuard console. This is also where you can generate API keys for agent enrollment. *** **Next Step**: [Installation →](/install/install) **Related**: [Quick Start](/get-started/get-started/quick-start) | [Supported Distributions](/reference/reference/supported-distributions) | [Troubleshooting](/troubleshooting) # Multi-Architecture Support Per-architecture capability matrix for the LinuxGuard agent — ARMv7 Degraded mode, RISC-V best-effort, and the eBPF probe gap operators must plan around. LinuxGuard ships agent binaries for multiple CPU architectures, but **eBPF probe availability is not uniform across architectures**. This page is the canonical capability matrix every operator MUST consult before deploying to a non-x86\_64 fleet. > **Important**: On **ARMv7 (`arm`)**, the agent runs in **Degraded mode**: it stays running but produces no behavioral telemetry, no auth events, and no eBPF-derived file-monitor events, because eBPF probe support is unavailable on this architecture. Compliance assumptions that depend on behavioral telemetry will not be met on ARMv7. Source: verified against the agent source. > **Important**: **RISC-V (`riscv64`)** is **best-effort**. Whether eBPF probes are available depends entirely on the clang/LLVM toolchain at build time and is not guaranteed on any given release; when unavailable, the agent falls back to the same reduced-telemetry mode described above for ARMv7 rather than failing to start. Source: verified against the agent source. ## Architecture Capability Matrix The columns below describe the granular surface every per-architecture deployment MUST reason about. A single "Supported" column would conflate the build-time eBPF availability with the runtime feature surface and would not match operator reality. | Arch | Binary | eBPF probes | Behavioral telemetry | Auth events | File monitor | CI-tested | | ----------------- | ---------------------------------------------------------------------------- | ----------------------------------------------- | -------------------------------------- | -------------------------------- | -------------------------------- | ----------- | | `amd64` (x86\_64) | Yes | Yes (full clang/LLVM compile) | Yes | Yes | Yes | Yes | | `arm64` (aarch64) | Yes | Yes (full clang/LLVM compile) | Yes | Yes | Yes | Yes | | `armv7` (`arm`) | Yes | **No** (falls back to a reduced-telemetry mode) | **No** | Limited (no eBPF-derived events) | Limited (no eBPF-derived events) | Best-effort | | `riscv64` | Yes | Best-effort (depends on the build toolchain) | Conditional (depends on probe success) | Conditional | Conditional | No | | `s390x` | Unverified — do not rely on without confirmation against latest source build | Unverified | Unverified | Unverified | Unverified | No | | `ppc64le` | Unverified — do not rely on without confirmation against latest source build | Unverified | Unverified | Unverified | Unverified | No | ### Reading the Matrix * **Binary** — Whether the agent binary is produced for the architecture in the published build pipeline. * **eBPF probes** — Whether the compiled eBPF probe object is shipped for this architecture. ARMv7 never ships one; RISC-V ships one only when the clang toolchain succeeds at build time. When unavailable, the agent falls back to a reduced-telemetry mode automatically rather than failing to start. * **Behavioral telemetry** — eBPF-derived process exec, network, and syscall events. Requires functioning eBPF probes. * **Auth events** — eBPF-derived login and SSH session events (`loginUID` capture). Requires functioning eBPF probes. * **File monitor** — eBPF-derived file open/exec/write monitoring. Requires functioning eBPF probes. * **CI-tested** — Whether the architecture runs in the LinuxGuard CI matrix on every build. For `s390x` and `ppc64le`: the agent binary may build via the OCI multi-arch manifest, but the eBPF probe build path is not exercised in the per-architecture build loop. Verify against the latest packaged build before relying on either architecture in production. ## Per-Distribution Architecture Support Each distribution family ships agent packages for the architectures listed below. Distribution order is fixed across this documentation set: Debian/Ubuntu → RedHat/CentOS → SUSE → Alpine. | Distribution Family | amd64 | arm64 | armv7 | riscv64 | Package repo | | ------------------- | ----- | ----- | ------------------- | ----------- | ------------------------------- | | Debian / Ubuntu | Yes | Yes | Yes (Degraded mode) | No | `packages.linuxguard.io/apt` | | RedHat / CentOS | Yes | Yes | No | No | `packages.linuxguard.io/dnf` | | SUSE / openSUSE | Yes | Yes | No | No | `packages.linuxguard.io/zypper` | | Alpine | Yes | Yes | Yes (Degraded mode) | Best-effort | `packages.linuxguard.io/apk` | ARMv7 packages on Debian/Ubuntu and Alpine install the agent binary, but the resulting deployment runs in Degraded mode per the matrix above. Each per-distribution install guide cross-links here. ## How the Agent Detects Architecture and Falls Back At startup, the agent checks whether eBPF probe support is available for the running architecture. When it is not, the agent: 1. Marks its status to reflect the reduced-telemetry mode. 2. Logs the fallback at INFO level so the condition is visible in agent logs. 3. Continues running with the non-eBPF feature subset (configuration management, package inventory, syslog forwarding, support-bundle collection) — no eBPF-derived telemetry is produced. This means **`linuxguard-agent` will start and stay running on ARMv7**. The reduced-telemetry mode does not crash the agent; it silently drops the eBPF-derived telemetry surface. Operators MUST verify the agent status via the console or `linuxguard-agent status` after deploying to an ARMv7 host. ## Operational Notes ### Identifying the Architecture at Runtime Use `uname -m` on the host to confirm the architecture before consulting the matrix above: ```bash uname -m ``` Common mappings: | `uname -m` output | Matrix row | | --------------------------- | ---------- | | `x86_64` | `amd64` | | `aarch64` | `arm64` | | `armv7l` / `armv6l` / `arm` | `armv7` | | `riscv64` | `riscv64` | | `s390x` | `s390x` | | `ppc64le` | `ppc64le` | ### QEMU vs Native Builds Multi-architecture OCI images produced via QEMU may pass the build but exhibit different runtime characteristics on native hardware (kernel version differences, BPF helper availability). Always test the agent on the target hardware before relying on the published image for production. ### Compliance Implications If your compliance posture depends on continuous behavioral telemetry (e.g., process exec audit, SSH session capture, file integrity monitoring), ARMv7 deployments will NOT contribute that evidence. Treat ARMv7 hosts as a documented gap in your evidence chain, or restrict the deployment to architectures with full eBPF support (`amd64`, `arm64`). ## Cross-References * [Supported Distributions](/reference/reference/supported-distributions) — Canonical per-architecture and per-distribution matrix. * [Installation on Debian / Ubuntu](/install/install/debian-ubuntu) — Per-distribution install guide (includes ARMv7 cross-link). * [Installation on RedHat / CentOS](/install/install/redhat-centos) — Per-distribution install guide. * [Installation on SUSE / openSUSE](/install/install/suse) — Per-distribution install guide. * [Installation on Alpine Linux](/install/install/alpine) — Per-distribution install guide. * [Prerequisites](/install/install/prerequisites) — Kernel and system requirements. *** **Related**: [Supported Distributions](/reference/reference/supported-distributions) | [Installation Overview](/install/install) | [Troubleshooting](/troubleshooting) # Debian / Ubuntu Install the LinuxGuard agent on Debian, Ubuntu, and derivatives via the APT repository at packages.linuxguard.io. This guide covers repository-based installation on Debian, Ubuntu, and derivatives (such as Linux Mint). > **Note**: **Supported architectures** — Debian/Ubuntu packages ship for `amd64`, `arm64`, and `armv7`. On architectures without eBPF support, the agent automatically falls back to a reduced-telemetry mode instead of failing to start. See [Multi-Architecture Support](/install/install/multi-architecture) for the per-architecture capability matrix. ## Prerequisites * Linux kernel 4.18+ (for eBPF support) * Root or sudo access * Outbound HTTPS access to `packages.linuxguard.io` > **Note**: See [Prerequisites](/install/install/prerequisites) for full system requirements. ## Repository Setup The recommended installation method uses the official LinuxGuard APT repository. This ensures you receive automatic updates and can easily manage the agent through your package manager. ### Step 1: Install Prerequisites Install required packages for repository configuration: ```bash sudo apt install curl ca-certificates gnupg ``` ### Step 2: Import GPG Key Create the keyrings directory and import the LinuxGuard signing key: ```bash sudo mkdir -p /etc/apt/keyrings curl -fsSL https://packages.linuxguard.io/gpg/linuxguard.asc | \ sudo gpg --dearmor -o /etc/apt/keyrings/linuxguard.gpg ``` ### Step 3: Add Repository Add the LinuxGuard repository to your system: ```bash echo "deb [signed-by=/etc/apt/keyrings/linuxguard.gpg arch=$(dpkg --print-architecture)] \ https://packages.linuxguard.io/apt stable main" | \ sudo tee /etc/apt/sources.list.d/linuxguard.list ``` ### Step 4: Install Agent Update the package index and install the agent: ```bash sudo apt update sudo apt install linuxguard-agent ``` The agent service will be installed but not started until enrollment. ## Direct Download If repository setup is not possible, you can download and install the package directly: ```bash curl -fsSL -o linuxguard-agent.deb \ https://packages.linuxguard.io/apt/pool/linuxguard-agent_latest_$(dpkg --print-architecture).deb sudo dpkg -i linuxguard-agent.deb ``` ## ARM64 installation The APT repository at `packages.linuxguard.io/apt` publishes both `amd64` and `arm64` packages under the same `deb` line. The repository setup snippet in [Step 3](#step-3-add-repository) already pins the architecture via `arch=$(dpkg --print-architecture)`, so an arm64 (aarch64) host pulls the arm64 package without further configuration. To confirm your host is arm64 before installing: ```bash dpkg --print-architecture # arm64 uname -m # aarch64 ``` The arm64 package ships the same agent binary + compiled eBPF probe object as the amd64 package — `arm64` is a **full-eBPF** architecture per the [capability matrix](/install/install/multi-architecture#architecture-capability-matrix). No degradation, no missing telemetry. If your host is ARMv7 (`armv7l`, `armhf`), the package is still available via the APT repository but the agent runs in [Degraded mode](/install/install/multi-architecture) with no behavioral telemetry produced. The `dpkg --print-architecture` value on an ARMv7 host is `armhf`, and the repository serves the corresponding package. Treat ARMv7 hosts as a documented gap in the evidence chain. > **Note**: For containerized arm64 deployments (Kubernetes DaemonSet on an arm64 node pool, Docker on an arm64 host), the OCI multi-arch manifest selects the arm64 image automatically when pulling `packages.linuxguard.io/linuxguard-agent:vX.Y.Z`. See [OCI multi-arch manifest](/install/install/oci-multi-arch-manifest) for the manifest inspection and `--platform` pull syntax. ## Verification After installation, verify the agent is correctly installed: ### Check Agent Binary Confirm the agent binary is in your PATH: ```bash which linuxguard-agent ``` Expected output: ``` /usr/bin/linuxguard-agent ``` ### Verify Agent User Confirm the agent user and group were created: ```bash id linuxguard ``` Expected output: ``` uid=999(linuxguard) gid=999(linuxguard) groups=999(linuxguard) ``` > **Note**: The UID/GID numbers may vary depending on your system. ### Check Service Status Verify the agent service is installed: ```bash sudo systemctl status linuxguard-agent ``` Expected output: ``` ○ linuxguard-agent.service - LinuxGuard Security Agent Loaded: loaded (/lib/systemd/system/linuxguard-agent.service; disabled; preset: enabled) Active: inactive (dead) ``` The service is inactive until you complete enrollment. ## Troubleshooting ### Repository Not Found If `apt update` fails to find the LinuxGuard repository, verify the repository file exists: ```bash cat /etc/apt/sources.list.d/linuxguard.list ``` The file should contain the repository configuration with the correct architecture. ### GPG Key Errors If you encounter GPG signature verification errors, verify the key was imported correctly: ```bash ls -l /etc/apt/keyrings/linuxguard.gpg ``` If the file is missing, repeat Step 2 of the repository setup. ### Package Conflicts If installation fails due to conflicting packages, check for unofficial or third-party LinuxGuard packages: ```bash apt list --installed | grep linuxguard ``` Remove any unofficial packages before installing from the official repository. > **Note**: See the [Troubleshooting Guide](/troubleshooting) for additional help. *** **Next Step**: [Configuration →](/configure/configure) **Related**: [Installation Overview](/install/install) | [Prerequisites](/install/install/prerequisites) | [Troubleshooting](/troubleshooting) # RedHat / CentOS Install the LinuxGuard agent on RedHat Enterprise Linux, CentOS, and CentOS Stream via the DNF/YUM repository at packages.linuxguard.io. This guide covers repository-based installation on RedHat Enterprise Linux (RHEL) and CentOS. > **Note**: CentOS Stream is an upstream preview of RHEL, not a downstream stable rebuild like traditional CentOS. Installation steps are the same, but update cadence differs. > **Note**: **Supported architectures** — RedHat/CentOS packages ship for `amd64` and `arm64`. ARMv7 packages are not published on the DNF/YUM repository. See [Multi-Architecture Support](/install/install/multi-architecture) for the per-architecture capability matrix. ## Prerequisites * Linux kernel 4.18+ (for eBPF support) * Root or sudo access * Outbound HTTPS access to `packages.linuxguard.io` > **Note**: See [Prerequisites](/install/install/prerequisites) for full system requirements. ## Repository Setup The recommended installation method uses the official LinuxGuard DNF/YUM repository. This ensures you receive automatic updates and can easily manage the agent through your package manager. ### Step 1: Add Repository Create the repository configuration file: ```bash sudo tee /etc/yum.repos.d/linuxguard.repo < **Note**: On CentOS 7 or RHEL 7, use `yum` instead of `dnf`: ```bash sudo yum makecache sudo yum install linuxguard-agent ``` ### Step 3: Enable and Start Service Enable the agent service to start at boot: ```bash sudo systemctl enable --now linuxguard-agent ``` > **Important**: Unlike Debian/Ubuntu, RedHat-based distributions do not automatically start services after installation. You must explicitly enable and start the agent. ## Direct Download If repository setup is not possible, you can download and install the RPM package directly: ```bash curl -fsSL -o linuxguard-agent.rpm \ https://packages.linuxguard.io/dnf/pool/linuxguard-agent-latest.$(uname -m).rpm sudo rpm -ivh linuxguard-agent.rpm ``` After manual installation, remember to enable and start the service: ```bash sudo systemctl enable --now linuxguard-agent ``` ## ARM64 installation The DNF/YUM repository at `packages.linuxguard.io/dnf` publishes both `x86_64` and `aarch64` (arm64) packages under the same repo configuration. The `$basearch` variable in the `baseurl` (see [Step 1](#step-1-add-repository)) resolves automatically to the host's architecture, so an arm64 host pulls the arm64 RPM without further configuration. To confirm your host is arm64 before installing: ```bash uname -m # aarch64 rpm --eval '%_arch' # aarch64 ``` The arm64 RPM ships the same agent binary + compiled eBPF probe object as the amd64 RPM — `arm64` is a **full-eBPF** architecture per the [capability matrix](/install/install/multi-architecture#architecture-capability-matrix). No degradation, no missing telemetry. > **Note**: ARMv7 packages are NOT published on the DNF/YUM repository. Hosts running RHEL or CentOS variants on ARMv7 are not supported via the standard package path; consult support for alternative deployment options. > **Note**: For containerized arm64 deployments (Kubernetes DaemonSet on an arm64 node pool, Podman on an arm64 host), the OCI multi-arch manifest selects the arm64 image automatically when pulling `packages.linuxguard.io/linuxguard-agent:vX.Y.Z`. See [OCI multi-arch manifest](/install/install/oci-multi-arch-manifest) for the manifest inspection and `--platform` pull syntax. ## Verification After installation, verify the agent is correctly installed: ### Check Agent Binary Confirm the agent binary is in your PATH: ```bash which linuxguard-agent ``` Expected output: ``` /usr/bin/linuxguard-agent ``` ### Verify Agent User Confirm the agent user and group were created: ```bash id linuxguard ``` Expected output: ``` uid=999(linuxguard) gid=999(linuxguard) groups=999(linuxguard) ``` > **Note**: The UID/GID numbers may vary depending on your system. ### Check Service Status Verify the agent service is installed and running: ```bash sudo systemctl status linuxguard-agent ``` Expected output: ``` ○ linuxguard-agent.service - LinuxGuard Security Agent Loaded: loaded (/usr/lib/systemd/system/linuxguard-agent.service; enabled; preset: disabled) Active: inactive (dead) ``` The service is inactive until you complete enrollment. ## Troubleshooting ### Service Not Running After Install If the service is not enabled after installation, DNF/YUM does not automatically start services. Enable and start it explicitly: ```bash sudo systemctl enable --now linuxguard-agent ``` ### Repository Metadata Errors If `dnf install` fails with repository metadata errors, refresh the cache: ```bash sudo dnf makecache ``` Or verify the repository configuration: ```bash cat /etc/yum.repos.d/linuxguard.repo ``` ### SELinux Denials If the agent fails to start due to SELinux policy violations, check for denials: ```bash sudo ausearch -m avc | grep linuxguard ``` If SELinux denials are found, you may need to create a custom policy or temporarily set SELinux to permissive mode while investigating. > **Note**: See the [Troubleshooting Guide](/troubleshooting) for additional help. *** **Next Step**: [Configuration →](/configure/configure) **Related**: [Installation Overview](/install/install) | [Prerequisites](/install/install/prerequisites) | [Troubleshooting](/troubleshooting) # SUSE / openSUSE Install the LinuxGuard agent on SUSE Linux Enterprise Server, openSUSE Leap, and openSUSE Tumbleweed via the zypper repository. This guide covers installing the LinuxGuard agent on SUSE Linux Enterprise Server (SLES), openSUSE Leap (regular releases), and openSUSE Tumbleweed (rolling release). > **Note**: **Supported architectures** — SUSE/openSUSE packages ship for `amd64` and `arm64`. ARMv7 packages are not published on the Zypper repository. See [Multi-Architecture Support](/install/install/multi-architecture) for the per-architecture capability matrix. ## Prerequisites Before installing, ensure your system meets these requirements: * **Kernel**: Linux kernel 4.18 or later * **Permissions**: Root or sudo access * **Network**: Outbound HTTPS access to `packages.linuxguard.io` > **Note**: For complete system requirements including architecture and detailed prerequisites, see the [Prerequisites Guide](/install/install/prerequisites). ## Repository Setup The recommended installation method uses the Zypper package manager to install LinuxGuard from the official repository. ### Step 1: Import GPG Key Import the LinuxGuard package signing key: ```bash sudo rpm --import https://packages.linuxguard.io/gpg/linuxguard.asc ``` ### Step 2: Add Repository Add the LinuxGuard repository to your system: ```bash sudo zypper addrepo --gpgcheck --refresh \ https://packages.linuxguard.io/zypper/sles/15 linuxguard ``` > **Note**: Zypper may prompt you to accept the GPG key on first installation. This is normal — review and accept the LinuxGuard signing key to proceed. ### Step 3: Install Agent Update the repository cache and install the agent: ```bash sudo zypper refresh sudo zypper install linuxguard-agent ``` The installer will also install the `sysstat` dependency, which provides `iostat` and `mpstat` for system metrics collection. ## Direct Download If you prefer to download and install the package manually, you can download the RPM package directly: ```bash curl -fsSL -o linuxguard-agent.rpm \ https://packages.linuxguard.io/zypper/pool/linuxguard-agent-latest.$(uname -m).rpm sudo rpm -ivh linuxguard-agent.rpm ``` > **Note**: Manual installation does not configure automatic updates. We recommend using the repository method for production systems. ## ARM64 installation The Zypper repository at `packages.linuxguard.io/zypper` publishes both `x86_64` and `aarch64` (arm64) packages. The repository URL in [Step 2](#step-2-add-repository) is architecture-neutral — Zypper inspects the host's architecture and pulls the matching RPM automatically. To confirm your host is arm64 before installing: ```bash uname -m # aarch64 zypper info --provides | head -5 ``` The arm64 RPM ships the same agent binary + compiled eBPF probe object as the amd64 RPM — `arm64` is a **full-eBPF** architecture per the [capability matrix](/install/install/multi-architecture#architecture-capability-matrix). No degradation, no missing telemetry. > **Note**: ARMv7 packages are NOT published on the Zypper repository. Hosts running SLES or openSUSE variants on ARMv7 are not supported via the standard package path; consult support for alternative deployment options. > **Note**: SLES on arm64 (aarch64) historically targeted Server-on-ARM workloads such as Ampere Altra and AWS Graviton. The package builds against the SLES 15 SP4+ kernel; if you run an older SP version, verify kernel compatibility (LinuxGuard requires kernel 4.18+ for eBPF; SLES 15 SP1 and later all satisfy this). > **Note**: For containerized arm64 deployments (Kubernetes DaemonSet on an arm64 node pool, Podman on an arm64 host), the OCI multi-arch manifest selects the arm64 image automatically when pulling `packages.linuxguard.io/linuxguard-agent:vX.Y.Z`. See [OCI multi-arch manifest](/install/install/oci-multi-arch-manifest) for the manifest inspection and `--platform` pull syntax. ## Verification After installation, verify the agent was installed correctly: ### Check Agent Binary Confirm the agent binary is installed: ```bash which linuxguard-agent ``` Expected output: ``` /usr/bin/linuxguard-agent ``` ### Verify Agent User Confirm the dedicated `linuxguard` user was created: ```bash id linuxguard ``` Expected output (UID/GID may vary): ``` uid=999(linuxguard) gid=999(linuxguard) groups=999(linuxguard) ``` ### Check Service Status Verify the agent service is installed (it will not be running until enrollment): ```bash sudo systemctl status linuxguard-agent ``` Expected output: ``` ○ linuxguard-agent.service - LinuxGuard Agent Loaded: loaded (/usr/lib/systemd/system/linuxguard-agent.service; disabled; vendor preset: disabled) Active: inactive (dead) ``` The agent is now installed and ready for enrollment. ## Troubleshooting ### GPG Key Trust Prompt **Issue**: Zypper prompts to accept GPG key during installation. **Solution**: This is normal behavior on first install. Review the key fingerprint and accept to proceed with installation. ### Repository Priority Conflicts **Issue**: Conflicting repository priorities cause package resolution errors. **Solution**: Check repository priorities with: ```bash zypper lr -P ``` Adjust priority if needed using `zypper modifyrepo --priority linuxguard`. ### Tumbleweed Kernel Compatibility **Issue**: Rolling release may have very recent kernel versions. **Solution**: Verify the agent supports your kernel version. Contact support if you encounter compatibility issues with cutting-edge Tumbleweed kernels. > **Note**: For additional troubleshooting guidance, see the [Troubleshooting Guide](/troubleshooting). *** **Next Step**: [Configuration →](/configure/configure) **Related**: [Installation Overview](/install/install) | [Prerequisites](/install/install/prerequisites) | [Uninstallation](/operate/operate/uninstallation) # Alpine Linux Install the LinuxGuard agent on Alpine Linux via the APK repository — OpenRC service management and musl libc considerations. This guide covers installing the LinuxGuard agent on Alpine Linux, commonly used in containers and lightweight environments. > **Important**: Alpine Linux uses **OpenRC** (not systemd) for service management and **musl libc** (not glibc). Commands in this guide differ from other distribution guides accordingly. > **Note**: **Supported architectures** — Alpine packages ship for `amd64`, `arm64`, and `armv7` (with best-effort `riscv64`). On architectures without eBPF support, the agent automatically falls back to a reduced-telemetry mode instead of failing to start. See [Multi-Architecture Support](/install/install/multi-architecture) for the per-architecture capability matrix. ## Prerequisites Before installing, ensure your system meets these requirements: * **Kernel**: Linux kernel 4.18 or later * **Permissions**: Root or sudo access * **Network**: Outbound HTTPS access to `packages.linuxguard.io` * **curl**: The `curl` package (not installed by default on Alpine minimal) > **Note**: For complete system requirements including architecture and detailed prerequisites, see the [Prerequisites Guide](/install/install/prerequisites). To install curl if not already present: ```bash sudo apk add curl ``` ## Repository Setup The recommended installation method uses the APK package manager to install LinuxGuard from the official repository. ### Step 1: Import GPG Key Create the APK keys directory and import the LinuxGuard signing key: ```bash sudo mkdir -p /etc/apk/keys curl -fsSL https://packages.linuxguard.io/gpg/linuxguard.asc | \ sudo tee /etc/apk/keys/linuxguard.asc > /dev/null ``` ### Step 2: Add Repository Add the LinuxGuard repository to your system: ```bash echo "https://packages.linuxguard.io/apk/alpine/v$(cut -d. -f1,2 /etc/alpine-release)/main" | \ sudo tee -a /etc/apk/repositories ``` ### Step 3: Install Agent Update the package index and install the agent: ```bash sudo apk update sudo apk add linuxguard-agent ``` The installer will also install the `sysstat` dependency, which provides `iostat` and `mpstat` for system metrics collection. ### Step 4: Enable and Start Service Alpine uses OpenRC for service management. Enable the agent to start at boot and start the service: ```bash sudo rc-update add linuxguard-agent boot sudo rc-service linuxguard-agent start ``` > **Note**: Alpine uses OpenRC for service management. Use `rc-service` and `rc-update` instead of `systemctl`. ## Direct Download If you prefer to download and install the package manually, you can download the APK package directly: ```bash curl -fsSL -o linuxguard-agent.apk \ https://packages.linuxguard.io/apk/pool/linuxguard-agent-latest.$(uname -m).apk sudo apk add --allow-untrusted linuxguard-agent.apk ``` > **Note**: Manual installation does not configure automatic updates. We recommend using the repository method for production systems. ## ARM64 installation The APK repository at `packages.linuxguard.io/apk/alpine` publishes packages for `x86_64`, `aarch64` (arm64), and `armv7` (with best-effort `riscv64`). The repository URL in [Step 2](#step-2-add-repository) is architecture-neutral — `apk update` selects the matching package automatically based on the host's architecture. To confirm your host is arm64 before installing: ```bash uname -m # aarch64 cat /etc/apk/arch # aarch64 ``` The arm64 APK ships the same agent binary + compiled eBPF probe object as the amd64 APK — `arm64` is a **full-eBPF** architecture per the [capability matrix](/install/install/multi-architecture#architecture-capability-matrix). No degradation, no missing telemetry. If your host is ARMv7 (`armv7l`, `armhf`), the package is still available via the APK repository but the agent runs in [Degraded mode](/install/install/multi-architecture) with no behavioral telemetry produced. Alpine on ARMv7 is commonly used for SBC deployments (e.g., Raspberry Pi 3 / 4 running Alpine in 32-bit mode); treat these hosts as a documented gap in the evidence chain. > **Note**: Alpine on arm64 is widely used as a container base image (and in this case the agent typically runs in a container deployment shape rather than via the APK install — see [Container deployment hub](/install/install/container)). The APK install path applies when the host is bare-metal or VM-based Alpine. > **Note**: For containerized arm64 deployments (Kubernetes DaemonSet on an arm64 node pool, Docker on an arm64 host), the OCI multi-arch manifest selects the arm64 image automatically when pulling `packages.linuxguard.io/linuxguard-agent:vX.Y.Z`. See [OCI multi-arch manifest](/install/install/oci-multi-arch-manifest) for the manifest inspection and `--platform` pull syntax. ## Verification After installation, verify the agent was installed correctly: ### Check Agent Binary Confirm the agent binary is installed: ```bash which linuxguard-agent ``` Expected output: ``` /usr/bin/linuxguard-agent ``` ### Verify Agent User Confirm the dedicated `linuxguard` user was created: ```bash id linuxguard ``` Expected output (UID/GID may vary): ``` uid=999(linuxguard) gid=999(linuxguard) groups=999(linuxguard) ``` ### Check Service Status Verify the agent service is running (OpenRC command): ```bash sudo rc-service linuxguard-agent status ``` Expected output: ``` * status: started ``` The agent is now installed and ready for enrollment. ## Alpine-Specific Considerations ### musl vs glibc Alpine uses musl libc instead of glibc. The LinuxGuard agent package for Alpine is specifically compiled against musl. **Do not install Debian/Ubuntu or RedHat/CentOS packages on Alpine** — they are compiled against glibc and will not run. ### Container Environments Alpine is commonly used as a container base image due to its small size (3-10MB vs 100-300MB for Debian/Ubuntu). For container-specific installation instructions, see the [Container Installation Guide](/install/install/container). ## Troubleshooting ### Service Commands Not Working **Issue**: `systemctl: command not found` or systemctl commands fail. **Solution**: Alpine uses OpenRC, not systemd. Use `rc-service linuxguard-agent ` instead of `systemctl linuxguard-agent`. Most common mistake when switching from other distributions. ### Binary Compatibility Errors **Issue**: Agent fails to start with library or symbol errors. **Solution**: Verify you installed the Alpine-specific package. This error typically indicates a glibc vs musl mismatch. Reinstall using `apk add linuxguard-agent` from the Alpine repository. ### Missing curl **Issue**: Repository setup fails because curl is not installed. **Solution**: Alpine minimal installations don't include curl by default. Install with: ```bash apk add curl ``` > **Note**: For additional troubleshooting guidance, see the [Troubleshooting Guide](/troubleshooting). *** **Next Step**: [Configuration →](/configure/configure) **Related**: [Installation Overview](/install/install) | [Prerequisites](/install/install/prerequisites) | [Container Installation](/install/install/container) # Container Deployment Decision guide for deploying the LinuxGuard agent in containers — scenario matrix, anti-patterns, and per-orchestrator spokes for Docker, Podman, docker-compose, and Kubernetes. This is the hub for running the LinuxGuard agent inside a container — Docker, Podman, docker-compose, or Kubernetes. Start here, pick the deployment scenario that matches your environment, and follow the linked spoke. > **Important**: The agent is published as a **digest-pinned distroless image**. Operators MUST pin to an immutable `vX.Y.Z` tag in production. Floating tags (`:latest`, `:stable`) are an [anti-pattern](#anti-patterns) — see below. ## Scenario matrix The right deployment shape depends on what you are protecting and how the orchestrator manages identity. | Scenario | Recommended | Why | Spoke | | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Pre-existing Kubernetes cluster, broad coverage of all host activity | DaemonSet | One pod per node; the agent observes every workload running on that node through host PID + tracefs | [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset) | | One-shot scan inside an ephemeral CI runner, build pod, or job | Ephemeral mode | TOTP enrol once, in-memory cert chain, no persistent identity to clean up | [Ephemeral mode](/install/install/container/ephemeral-mode) | | Mixed host + container workloads under Kubernetes | DaemonSet only — do NOT also run a per-pod sidecar | The node-level DaemonSet already observes the containerized workloads via host PID; a sidecar produces duplicate events ([anti-pattern](#anti-patterns)) | [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset) | | Single-node Docker host (lab, edge appliance, developer workstation) | Docker run or `docker-compose` | Lightweight; the agent runs as a long-lived container with a tmpfs cert cache | [docker-compose](/install/install/container/docker-compose) | | Rootless container runtime (security-hardened workstation, locked-down host) | Podman | Rootless mode trades eBPF capabilities for least-privilege execution; rootful mode preserves full telemetry | [Podman](/install/install/container/podman) | | Pod-level isolation explicitly required (multi-tenant cluster where the DaemonSet model is rejected by policy) | Sidecar (per pod) | Heavier resource cost — only when DaemonSet cannot meet the policy constraint | [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset) (Sidecar section) | | Air-gapped or strict `restricted` Pod Security Standard cluster | Documented gap — consult support | Many of the agent's required capabilities (elevated kernel-observability permissions, host paths) are disallowed under `restricted` | [Kubernetes DaemonSet § Pod Security Standard](/install/install/container/kubernetes-daemonset#pod-security-standard-compatibility) | ## What's in this section * [**Distroless image reference**](/install/install/container/distroless) — what's in the image, what's excluded (no shell, no package manager), and how to verify the published digest * [**Ephemeral mode**](/install/install/container/ephemeral-mode) — `--ephemeral`, `--workload-id`, PID 1 auto-detection, TLS cache restart semantics * [**Kubernetes DaemonSet**](/install/install/container/kubernetes-daemonset) — copy-pasteable YAML with line-by-line `securityContext` rationale, eBPF prerequisites, and the PSS profile the manifest works under * [**Downward API integration**](/install/install/container/downward-api) — `LINUXGUARD_NODE_NAME` and `LINUXGUARD_POD_UID` via `fieldRef`, workload identity derivation * [**Enrollment tokens**](/install/install/container/enrollment-tokens) — TOTP flow, `valueFrom.secretKeyRef` pattern, why the agent unsets the env var at startup * [**docker-compose**](/install/install/container/docker-compose) — `compose.yaml` example, env-var configuration, volume mounts, restart policies * [**Podman**](/install/install/container/podman) — rootless vs rootful trade-offs, systemd quadlet integration, equivalence to Docker commands See also: * [**OCI multi-arch manifest**](/install/install/oci-multi-arch-manifest) — `docker manifest inspect` output, supported platforms, image digest stability, `--platform` pull syntax * [**`start` command reference**](/reference/reference/cli/start) — all flags consumed by every container scenario below * [**Environment variables**](/reference/reference/cli/env-variables) — every `LINUXGUARD_*` variable the agent reads at startup ## Anti-patterns The four anti-patterns below break real production deployments. Each is called out in the relevant spoke; collected here for fast reference. ### 1. Floating image tags in production (`:latest`, `:stable`) Pinning to `:latest` (or any other moving tag) makes the deployment irreproducible. A node that pulls the image at 09:00 may receive a different binary than a node that pulls at 13:00 after a publish. Audit replay, incident reconstruction, and rollback all break. **Correct:** Pin to an immutable `vX.Y.Z` tag (e.g., `packages.linuxguard.io/linuxguard-agent:v3.0.0`) or to an image digest (`@sha256:...`). The OCI multi-arch manifest guarantees the same `vX.Y.Z` tag resolves to architecture-appropriate images on amd64 and arm64 — see [OCI multi-arch manifest](/install/install/oci-multi-arch-manifest). ### 2. Running a DaemonSet AND a per-pod sidecar A DaemonSet that runs with `hostPID: true` already observes every process on the node — including every containerized workload running on that node. Adding a sidecar to each application pod produces **duplicate events** for the same syscall: once from the node-level DaemonSet's perspective and once from the per-pod sidecar's perspective. Console alerts double-count; dashboards show inflated activity; downstream SIEM ingestion costs double. **Correct:** Pick one model. DaemonSet covers all containerized workloads on the node. Sidecar is reserved for the narrow case where pod-level isolation is mandated by policy and a node-level pod is explicitly rejected. ### 3. Mounting host `/` read-write A deployment that mounts the entire host filesystem (`hostPath: /`, `mountPath: /host`, `readOnly: false`) gives the agent container write access to every file on the node, including kernel modules, systemd unit files, and `/etc/sudoers`. The agent does not need that. The blast radius of a container escape (or a compromised agent image) is the entire node. **Correct:** Mount only the specific host paths the agent needs, and mount each one **read-only** unless the spoke explicitly justifies write access. The four required paths for a DaemonSet are `/sys/kernel/tracing` (tracefs, read-only), `/sys/fs/bpf` (BPF FS, read-write for pinned maps), `/proc` (read-only for process introspection), and a tmpfs at `/run/linuxguard` (read-write, ephemeral) for the TLS cache. See [Kubernetes DaemonSet § Host paths](/install/install/container/kubernetes-daemonset#host-paths). ### 4. Re-using a TOTP enrollment token across pods A TOTP `--enroll-token` is single-use and short-lived. The backend's `/agent/enroll` handler accepts each token exactly once for one workload identity. Re-using the same token across multiple pods in a DaemonSet (e.g., by baking it into a ConfigMap with the literal value) produces unpredictable behavior: the first pod enrols successfully, subsequent pods get `409 conflict` or stale-identity errors, and the cluster's agent fleet ends up partially enrolled with silent gaps in coverage. **Correct:** Each pod gets a **fresh** TOTP token, injected via Kubernetes `valueFrom.secretKeyRef`. The Secret is rotated externally (by an enrollment service or operator-driven process) so that each new pod sees a new value. The agent reads the env var once at startup, immediately calls `os.Unsetenv("LINUXGUARD_ENROLL_TOKEN")` to scrub it from `/proc//environ`, and never persists it — see [Enrollment tokens](/install/install/container/enrollment-tokens). ## Architecture caveats * **ARMv7 (`arm/v7`)**: the agent binary builds and the image is published in the OCI multi-arch manifest. On architectures without eBPF support, the agent automatically falls back to a reduced-telemetry mode instead of failing to start. See [Multi-Architecture Support](/install/install/multi-architecture). Treat ARMv7 container deployments as a documented gap in the evidence chain. * **RISC-V (`riscv64`)**: best-effort. The published image may or may not include compiled eBPF probes depending on the toolchain at build time. Verify against the multi-arch manifest before relying on RISC-V in production. * **s390x / ppc64le**: unverified for container deployment. Surface unsupported in v4.0; consult support before deploying. *** **Next Step**: [Distroless image reference →](/install/install/container/distroless) **Related**: [Multi-Architecture Support](/install/install/multi-architecture) | [OCI Multi-Arch Manifest](/install/install/oci-multi-arch-manifest) | [`start` CLI reference](/reference/reference/cli/start) | [Environment variables](/reference/reference/cli/env-variables) # Distroless image reference Reference for the LinuxGuard agent distroless container image — contents, exclusions, security context, host paths, PSS compatibility, RBAC, and image-signing verification. The LinuxGuard agent ships as a digest-pinned **distroless** container image built on `gcr.io/distroless/static-debian12:nonroot`. This page describes what is in the image, what is explicitly excluded, the security context the image runs under, and how to verify a published image before deployment. > **Important**: The image runs as **nonroot UID 65532** by default. The agent binary carries the Linux capabilities it needs baked in, so it can observe kernel-level activity without running as root. Container runtimes MUST grant the same capabilities at the container level (Docker `--cap-add`, Kubernetes `securityContext.capabilities.add`) — see [Security context](#security-context) below for the exact list — or the agent will fail to start. ## Image coordinates | Coordinate | Value | | ----------------- | --------------------------------------------------------------------------------------------------------------------------- | | Registry host | `packages.linuxguard.io` | | Repository | `packages.linuxguard.io/linuxguard-agent` | | Tag convention | Immutable `vX.Y.Z` semver tags published per release. Floating tags (`:latest`, `:stable`) are anti-patterns in production. | | Base image | `gcr.io/distroless/static-debian12:nonroot` (digest-pinned in the Dockerfile) | | Entrypoint | `/usr/local/bin/linuxguard-agent` | | Default CMD | `start` | | Default user | `nonroot` (UID 65532, GID 65532) | | Working directory | Inherited from base (`/`) | | Exposed ports | None — the agent makes outbound HTTPS to the LinuxGuard API; it does not listen on a port | Pin to an immutable digest when reproducibility matters more than upgrade convenience: ```bash docker pull packages.linuxguard.io/linuxguard-agent@sha256: ``` ## What's in the image The final image contains exactly two artifacts on top of the distroless base: | Path | Contents | Purpose | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | `/usr/local/bin/linuxguard-agent` | Statically-linked Go binary, `CGO_ENABLED=0`, built with tags `osusergo,netgo,nocgo,loader_embedded,pid1`. Required Linux capabilities are baked into the ELF — see [Security context](#security-context) for the exact list. | The agent itself. | | `/usr/local/share/linuxguard/probes.bpf.o` | Compiled eBPF object (amd64/arm64); not present on architectures without eBPF support. | eBPF probe payload loaded at agent startup. | The base layer additionally provides: * `/etc/passwd`, `/etc/group` — entries for `nonroot` UID 65532 and `root` UID 0. * `/etc/ssl/certs/ca-certificates.crt` — the Mozilla CA bundle for mTLS to the LinuxGuard API (no embedded bundle is required). * `/tmp` — writable temporary directory. ## What's NOT in the image The distroless contract is deliberately minimal. Operators familiar with Debian or Alpine container images will find every diagnostic tool absent. This is by design — the attack surface of an image with no shell and no package manager is dramatically smaller than the equivalent `:slim` or `:alpine` variant. | Excluded | Implication | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Shell (`/bin/sh`, `/bin/bash`) | `docker exec -it sh` does NOT work. Use `kubectl debug --image=...` or `docker exec` with a specific command, not an interactive shell. | | Package manager (`apt`, `dnf`, `apk`) | The image cannot install additional packages at runtime. Ship them at build time in a custom layer if you need them. | | Standard utilities (`ls`, `cat`, `ps`, `curl`, `wget`) | Diagnostics from inside the container are limited to what the agent emits to stdout/stderr (its log output) and to its `support-bundle collect` subcommand. | | NSS resolver (`/etc/nsswitch.conf`, `libnss_*`) | The agent uses pure-Go user and network resolution (build tags `osusergo,netgo`). No NSS lookups occur. | | Dynamic linker (`ld-linux-x86-64.so.2`, etc.) | The agent is statically linked (`-extldflags "-static"`). No `.so` dependencies exist. | | `getcap` / `setcap` / `libcap2-bin` | File capabilities are set in the builder stage and copied through `COPY --link` to preserve the security xattr. Inspection inside the running container is not possible. | | `/sys/kernel/tracing` (tracefs) | Distroless does not include `/sys` mounts; tracefs MUST be bind-mounted from the host for probe attach to succeed (see [Host paths](#host-paths)). | ### Debugging a distroless container When you need an interactive shell on a running agent container, do NOT modify the base image. Instead, use a debug ephemeral container that mounts the agent's process namespace: ```bash kubectl debug -it --image=ghcr.io/linuxguardx/debug-tools:latest --target=linuxguard-agent ``` Or for Docker: ```bash docker exec /usr/local/bin/linuxguard-agent support-bundle collect --out=/tmp/bundle.tar.zst docker cp :/tmp/bundle.tar.zst ./bundle.tar.zst ``` The `support-bundle collect` subcommand is the canonical diagnostic surface for distroless deployments — see [`support-bundle` CLI reference](/reference/reference/cli/support-bundle). ## Security context The image is hardened by default; operators MUST preserve these defaults at the orchestrator layer. | Surface | Default in image | Notes | | ---------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | User | `nonroot` (UID 65532, GID 65532) — set by base image `USER` directive | Do NOT override with `USER root` in a downstream layer; the file capabilities baked into the binary make root unnecessary. | | File capabilities (binary) | Baked into the ELF at build time — the binary itself already carries everything it needs. | Container runtimes must still grant the same capabilities at the bounding-set level (next row) — the file capabilities alone are not sufficient without the runtime-side grant. | | Bounding set requirement (runtime) | NOT set by the image — runtime must add | Docker: `--cap-add=BPF --cap-add=PERFMON --cap-add=DAC_READ_SEARCH --cap-add=SYS_PTRACE --cap-add=SETPCAP`. Kubernetes: `securityContext.capabilities.add: [BPF, PERFMON, DAC_READ_SEARCH, SYS_PTRACE, SETPCAP]`. | | Seccomp profile | NOT set by the image — runtime must override default | Docker's default seccomp profile blocks a performance-monitoring syscall the agent needs for kernel-level observability. Use `--security-opt seccomp=unconfined` for UAT/dev, or a custom seccomp profile that allows the required syscall for production. The recommended K8s `localhostProfile` ships in the agent packaging artifacts as `linuxguard-agent.seccomp.json`. | | AppArmor / SELinux profile | NOT set by the image — apply at node level | A reference AppArmor profile (`linuxguard-agent.apparmor`) ships in the agent packaging tree. Install it on every node via the `linuxguard-profile-installer` DaemonSet referenced in [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset). | | `runAsNonRoot` | Implied by base image USER directive (UID 65532) | Set `runAsNonRoot: true` in the Pod spec to enforce it at admission time. | | `allowPrivilegeEscalation` | Should be `false` at the Pod level | The file caps already provide the required capabilities; no `setuid` binary needs to escalate. | | `readOnlyRootFilesystem` | Should be `true` at the Pod level | The agent does not write to the image filesystem; ephemeral state goes to a tmpfs at `/run/linuxguard/`. | ## Host paths The image itself does NOT declare any volume mounts — those are the orchestrator's responsibility. For an image-reference scope, the relevant host paths are the ones the agent **expects** to find when started in ephemeral or DaemonSet mode. Each per-orchestrator spoke documents the exact mount syntax; the table below catalogs what each path is for. | Host path | Mount mode | Required for | Rationale | | --------------------- | ------------------------------------------ | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `/sys/kernel/tracing` | read-only | Required for probe attach | Distroless does not include `/sys` mounts; without this bind mount, probe attach fails and the agent degrades to `DEGRADED_PROBES_PARTIAL`. | | `/sys/fs/bpf` | read-write | BPF map storage | Required for the agent's BPF map storage shared across processes. | | `/proc` | read-only | Process introspection | The agent walks `/proc` for the workload-discovery pass on startup; host PID is required for the DaemonSet shape but not for ephemeral mode. | | `/run/linuxguard` | read-write, tmpfs, mode `0700`, size `10m` | TLS cert cache when `--tls-cache` is set | Ephemeral mode writes the mTLS cert chain + token-hash tag to this directory. Tmpfs (not a hostPath) so cert material never touches durable storage. | | `/var/lib/linuxguard` | read-write | Typical-service-mode persistence | NOT used by ephemeral mode. The agent never writes to this path when `--ephemeral` (or PID-1 auto-detection) is active. | > **Security Note**: Mount each host path **only if** the spoke requires it, and mount it **read-only** unless explicit write access is justified. Do NOT mount the host root filesystem (`/`); see the [anti-patterns hub section](/install/install/container#anti-patterns). ## Pod Security Standard compatibility The distroless image itself is a passive artifact — PSS applies to the Pod specification that runs the image, not to the image bytes. Per-orchestrator PSS classification is documented on each spoke; this table summarizes the binding decision. | Pod spec shape | PSS profile | Workable in restricted? | | ------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | DaemonSet with elevated capabilities + `hostPID: true` + tracefs hostPath | **privileged** | No — `restricted` disallows added capabilities beyond a small allowlist, host namespaces, and most `hostPath` volumes. | | Sidecar with elevated capabilities and no host PID | **baseline** | No — `baseline` allows the agent's capabilities but `restricted` does not. | | Ephemeral one-shot in `restricted` cluster | **Not currently supported** | Requires an explicit `AdmissionPolicy` waiver granting the agent's required capabilities. Consult support. | The image carries no Pod spec opinions — the same image satisfies all three shapes; the difference is the orchestrator manifest. ## RBAC The agent makes **no Kubernetes API calls** at runtime. Workload identity is derived from the Downward API env vars (`LINUXGUARD_NODE_NAME`, `LINUXGUARD_POD_UID`) injected at Pod admission time — see [Downward API](/install/install/container/downward-api). Telemetry is shipped over outbound mTLS to the LinuxGuard API, not via the Kubernetes apiserver. Consequently, the distroless image requires **no ServiceAccount RBAC binding** of its own. The Pod runs under a ServiceAccount (the namespace `default` SA is acceptable), but no `Role`, `ClusterRole`, `RoleBinding`, or `ClusterRoleBinding` needs to be created for the agent to function. RBAC is documented per-spoke only where the spoke's lifecycle requires it (e.g., the profile-installer DaemonSet referenced in [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset) requires its own ServiceAccount because it writes seccomp + AppArmor profiles to host paths). ## Image signing and verification Published images are signed at release time. Verify the signature before deployment: ```bash cosign verify \ --certificate-identity 'https://github.com/linuxguardx/linuxguard-agent/.github/workflows/release.yaml@refs/tags/v3.0.0' \ --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \ packages.linuxguard.io/linuxguard-agent:v3.0.0 ``` The verification step confirms two facts: the image was built by the LinuxGuard release pipeline (not a fork or a typosquatted registry), and the signing transparency log entry exists. A successful verification prints the certificate's subject and the Rekor log index. If `cosign verify` fails, do NOT deploy the image. Open a support case and pin to the most recent verified version while the cause is investigated. For the OCI multi-arch manifest behavior and per-platform digest stability, see [OCI Multi-Arch Manifest](/install/install/oci-multi-arch-manifest). *** **Next Step**: [Ephemeral mode →](/install/install/container/ephemeral-mode) **Related**: [Container deployment hub](/install/install/container) | [OCI multi-arch manifest](/install/install/oci-multi-arch-manifest) | [`start` CLI reference](/reference/reference/cli/start) | [`support-bundle` CLI reference](/reference/reference/cli/support-bundle) # Ephemeral mode Configure the LinuxGuard agent in ephemeral container mode — TOTP enrol, in-memory cert chain, PID 1 auto-detection, TLS cache restart semantics. Ephemeral mode is the container-friendly operating shape of the LinuxGuard agent. The agent enrols once via a short-lived TOTP token, holds the resulting mTLS cert chain in memory, skips PID-file machinery (the orchestrator owns lifecycle), and never writes to `/var/lib/linuxguard/`. This page documents the trigger conditions, the runtime behavior, and the restart semantics — including the optional TLS cache that survives container restarts without re-enrolling. > **Important**: Ephemeral mode is selected by **any** of the following triggers: the `--ephemeral` flag, a non-empty `--enroll-token` (or its `LINUXGUARD_ENROLL_TOKEN` env-var binding), `os.Getpid() == 1` (the agent is the container's init process), or the `LINUXGUARD_PID1_CHILD` re-exec sentinel. Explicit `--ephemeral` is NOT required when any of the implicit triggers fires. ## When ephemeral mode is the right choice Ephemeral mode is designed for containers whose lifecycle is owned by the orchestrator and whose workload identity is derived from the container's runtime context, not from a persisted enrollment on disk: * **Kubernetes DaemonSet pods** — node-level coverage, workload identity from the Downward API. * **Kubernetes sidecars** — pod-level coverage, workload identity from `metadata.uid`. * **Docker / Podman containers running as PID 1** — single-tenant edge appliance, CI runner, build container. * **One-shot CI / build jobs** — a fresh enrol per invocation, no persistent state. It is NOT the right choice for: * A long-lived host installation managed by systemd. Use the [per-distro install guides](/install/install) for that shape. * A container that runs the agent as a **non**-PID-1 worker alongside an application. The PID-file machinery the agent skips in ephemeral mode is the same machinery that prevents two `start` invocations from competing for the same host identity. Use the [host install path](/install/install) inside the container instead. ## Flags consumed by ephemeral mode The flags below are the surface ephemeral mode actually consumes. The full `start` flag reference (defaults, env-var bindings, source line numbers) lives at [`start` CLI reference](/reference/reference/cli/start). | Flag | Purpose in ephemeral mode | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--ephemeral` | Explicit trigger. Optional when any implicit trigger fires (PID 1, non-empty `--enroll-token`, `LINUXGUARD_PID1_CHILD`). | | `--enroll-token` | TOTP enrolment token. Prefer the `LINUXGUARD_ENROLL_TOKEN` env var so the token does not appear on the command line (see [Enrollment tokens](/install/install/container/enrollment-tokens)). | | `--tenant-id` | Tenant the agent enrols into. **Required** on the TOTP path — the backend's `/agent/enroll` handler rejects with `400 "tenantId required for TOTP enrollment"` when missing. Bound to `LINUXGUARD_TENANT_ID`. | | `--workload-id` | Explicit workload identifier (sha256 hex). Required only when the Downward API env vars are absent. Hard-error if neither `--workload-id` nor `LINUXGUARD_NODE_NAME` + `LINUXGUARD_POD_UID` are set. | | `--node-id` | Kubernetes node name from the Downward API. Bound to `LINUXGUARD_NODE_NAME`. Feeds the workload-id derivation when `--workload-id` is not provided. | | `--tls-cache` | Opt-in: mirror the cert chain + token-hash tag to `/run/linuxguard/tls/` (mode `0700`/`0600`) so a container restart can reuse the cache without re-enrolling. Off by default. Requires a `tmpfs` mount at `/run/linuxguard`. | | `--loader-embedded` | Force the in-process embedded eBPF loader. Auto-on under PID 1 or `--ephemeral` when the binary was built with the `loader_embedded` build tag (the published image is built with this tag set). Bound to `LINUXGUARD_LOADER_EMBEDDED`. | | `--api-url` | Override the LinuxGuard API base URL. Bound to `LINUXGUARD_API_URL`. Whitespace-only values treated as empty. Channel default applies when absent. | `LINUXGUARD_POD_UID` is read directly via `os.Getenv` — it has no flag binding. It pairs with `LINUXGUARD_NODE_NAME` for the workload-id derivation. ## PID 1 auto-detection The agent inspects its own PID at startup. When `os.Getpid() == 1` (or when the `LINUXGUARD_PID1_CHILD` sentinel is set by the agent's own init re-exec wrapper), ephemeral semantics activate even if the `--ephemeral` flag was not passed. This matches the common container pattern of running the agent as the container's main process (Dockerfile `CMD ["start"]`, distroless image default). When PID 1 is detected, the agent additionally: 1. Skips `agent.EnsureNotRunning` and `agent.WritePID` so there is no PID-file collision with itself across re-execs. 2. Installs the PID-1 init shim (build tag `pid1`) that reaps zombie children — required for any container that may spawn subprocesses, even transiently. 3. Re-execs itself with `LINUXGUARD_PID1_CHILD=1` set; this sentinel marks the second invocation as the actual agent process, not the init shim. `LINUXGUARD_PID1_CHILD` is **internal-only**. Operators must NOT set it manually. Documented in [Environment variables](/reference/reference/cli/env-variables) only so process-introspection tooling (e.g., reading `/proc//environ` during incident triage) can identify the value as agent-internal rather than user-supplied. ## Workload identity derivation The workload identifier is the value the backend uses to distinguish one ephemeral agent from another. It is also used as the `Idempotency-Key` header on the enrolment POST so a retried request does not produce two server identities. The derivation order is: 1. **Explicit `--workload-id `** → `sha256(explicit)`. The flag value is hashed (not used verbatim) so misuse — passing a non-hex value, passing whitespace — produces a deterministic identifier rather than a backend rejection. 2. **Downward API env vars** → `sha256(LINUXGUARD_NODE_NAME + ":" + LINUXGUARD_POD_UID)`. Both env vars must be set; either one missing falls through to error. 3. **Neither set** → hard error: `--ephemeral requires either Downward API env vars (LINUXGUARD_NODE_NAME and LINUXGUARD_POD_UID, set via valueFrom.fieldRef) OR --workload-id CLI flag; none of the three were present`. There is no silent UUID fallback. An ephemeral agent that cannot derive a workload identity refuses to start, by design — otherwise a misconfigured Pod would silently enrol with a random identity on every restart and produce a sprawl of orphan enrollments in the tenant. For the Kubernetes pattern using `valueFrom.fieldRef`, see [Downward API integration](/install/install/container/downward-api). ## TLS cache restart semantics By default, an ephemeral agent that restarts performs a **fresh enrolment** with the supplied TOTP token. This is the safest default: no cert material survives container exit; a stolen image filesystem yields no live mTLS keys. For deployments where restart is frequent and re-enrolment is undesirable (e.g., a sidecar that restarts on application crashes), the optional `--tls-cache` flag mirrors the cert chain + a token-hash tag to a tmpfs at `/run/linuxguard/tls/`: | File | Mode | Contents | | ------------------------------- | ---- | --------------------------------------------------------------------------------------------------------------- | | `/run/linuxguard/tls/agent.crt` | 0600 | mTLS client certificate | | `/run/linuxguard/tls/agent.key` | 0600 | mTLS client private key | | `/run/linuxguard/tls/ca.crt` | 0600 | Backend CA chain | | `/run/linuxguard/tls/.tag` | 0600 | `hex(sha256(token + ":" + workloadID))` — token-hash tag used to invalidate stale caches across token rotations | On restart with `--tls-cache`, the agent computes the current `.tag` value from the env-var token + workload-id and compares it against the file. If they match, the cached cert chain is reused without re-enrolling. If they diverge — because the TOTP token has been rotated, or because the workload-id changed (a new pod UID under Kubernetes) — the cache directory is deleted and a fresh enrolment runs. > **Important**: `--tls-cache` requires `LINUXGUARD_ENROLL_TOKEN` (or a pre-computed `EnrollTokenTag` value) to be set. The agent refuses to seed a cache that cannot be cryptographically invalidated — otherwise a token rotation would silently leave the agent using cert material attached to the prior identity. Without the token + tag pair, the agent returns the error `--tls-cache requires LINUXGUARD_ENROLL_TOKEN (or pre-computed EnrollTokenTag) to be set; refusing to seed a cache that cannot be cryptographically invalidated`. The tmpfs mount is mandatory when `--tls-cache` is active. Without it, the cert chain ends up on the container's writable layer — discoverable via `docker diff`, persisted in image-export workflows, and survivable to disk. The Docker run incantation is: ```bash --tmpfs /run/linuxguard:rw,mode=0700,size=10m ``` The Kubernetes equivalent (in the Pod spec) is an `emptyDir` with `medium: Memory`: ```yaml volumes: - name: linuxguard-tls emptyDir: medium: Memory sizeLimit: 10Mi ``` ## Restart semantics summary | Scenario | Without `--tls-cache` | With `--tls-cache` | | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Container restart, same TOTP token, same workload-id | Fresh enrol with the token | Cert chain reused from tmpfs; no enrol call | | Container restart, rotated TOTP token, same workload-id | Fresh enrol with the new token | `.tag` mismatch → cache deleted → fresh enrol with the new token | | Container restart, same TOTP token, new workload-id (e.g., new pod UID) | Fresh enrol under the new identity | `.tag` mismatch → cache deleted → fresh enrol under the new identity | | Container exit (`SIGTERM` / `SIGINT`) | Cert chain is GC'd from memory; exits with `os.Exit(143)` / `os.Exit(130)` respectively | Cert chain is GC'd from memory; the tmpfs cache survives until the next start (tmpfs is the orchestrator's lifecycle, not the container's) | ## Security context Ephemeral mode runs the agent under the same security context as any other container deployment of the distroless image — see [Distroless image § Security context](/install/install/container/distroless#security-context) for the canonical reference. Specifically: * Runs as `nonroot` UID 65532. * Uses Linux file capabilities baked into the binary so it can observe kernel-level activity without running as root — see [Distroless image § Security context](/install/install/container/distroless#security-context) for the exact list. * Requires the runtime to add the same capabilities to the bounding set (`--cap-add` or `securityContext.capabilities.add`). * Requires a custom seccomp profile (or `--security-opt seccomp=unconfined` for UAT/dev) so the agent's kernel-tracing syscall is permitted. * Sets `runAsNonRoot: true`, `allowPrivilegeEscalation: false`, `readOnlyRootFilesystem: true` at the Pod level. ## Host paths Ephemeral mode requires fewer host paths than the DaemonSet shape because it does not need to observe other workloads on the node: | Path | Mount | Purpose | | --------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/run/linuxguard` | tmpfs, mode `0700`, size `10m`, read-write | TLS cert cache when `--tls-cache` is set. Mandatory when the flag is active; optional otherwise. | | `/sys/kernel/tracing` | hostPath, read-only | Required for probe attach. On architectures without eBPF support, the agent automatically falls back to a reduced-telemetry mode instead of failing to start — omit this mount in that case. | | `/sys/fs/bpf` | hostPath, read-write | Required for the agent's BPF map storage. | | `/proc` | hostPath, read-only | Required when ephemeral mode is observing other host processes (rare; typical ephemeral is per-pod or per-container scope only). | The DaemonSet shape, by contrast, mounts host PID + the full host-path set. See [Kubernetes DaemonSet § Host paths](/install/install/container/kubernetes-daemonset#host-paths). ## Pod Security Standard compatibility | PSS profile | Compatible? | Notes | | ----------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | privileged | Yes | Default profile that admits all capabilities and host namespaces required by the agent. | | baseline | Yes — with caveat | The agent's required capabilities are within the `baseline` allowlist; tmpfs mount and `runAsNonRoot` satisfy baseline constraints. Caveat: ephemeral mode without `hostPID` works under baseline; ephemeral mode with `hostPID: true` requires `privileged`. | | restricted | **Not currently supported** | The agent's required capabilities are NOT in the restricted allowlist (which drops all capabilities by default). Requires an explicit `AdmissionPolicy` waiver. Consult support. | ## RBAC Ephemeral mode makes **no Kubernetes API calls**. Workload identity comes from Downward API env vars injected at Pod admission time (no apiserver lookups), and telemetry ships via outbound mTLS to the LinuxGuard API (no in-cluster service mesh). The Pod runs under any ServiceAccount (the namespace `default` SA is acceptable). **No `Role`, `ClusterRole`, `RoleBinding`, or `ClusterRoleBinding` needs to be created for the agent itself.** RBAC is required only for sibling components (e.g., the profile-installer DaemonSet that writes seccomp/AppArmor profiles to host paths — that DaemonSet's RBAC is documented in [Kubernetes DaemonSet § RBAC](/install/install/container/kubernetes-daemonset#rbac)). ## Example: Docker run, ephemeral, no cache The simplest ephemeral invocation. Cert chain lives in memory only; a restart re-enrols with whatever value is then in `LINUXGUARD_ENROLL_TOKEN`. ```bash docker run --rm \ --pid=host \ --cap-add=BPF --cap-add=PERFMON --cap-add=DAC_READ_SEARCH \ --cap-add=SYS_PTRACE --cap-add=SETPCAP \ --security-opt seccomp=unconfined \ -v /sys/kernel/tracing:/sys/kernel/tracing:ro \ -e LINUXGUARD_ENROLL_TOKEN="$ENROLL_TOKEN" \ -e LINUXGUARD_TENANT_ID="$TENANT_ID" \ -e LINUXGUARD_NODE_NAME="$(hostname)" \ -e LINUXGUARD_POD_UID="$(uuidgen)" \ packages.linuxguard.io/linuxguard-agent:v3.0.0 ``` Notes on the flags: * `--cap-add` grants the container the elevated capabilities the agent needs; without them, the container will fail to start. * `--security-opt seccomp=unconfined` is acceptable for UAT/dev; production should use a custom seccomp profile that explicitly permits the agent's kernel-tracing syscall. * `-v /sys/kernel/tracing:/sys/kernel/tracing:ro` is the tracefs bind-mount required for probe attach. * The four env vars supply the token, the tenant, and the workload-id inputs. `LINUXGUARD_ENROLL_TOKEN` is read once and immediately unset; the other three persist for the lifetime of the agent process. ## Example: Docker run, ephemeral, with TLS cache The same agent with `--tls-cache` enabled so a container restart reuses the cert chain (within the same TOTP token + workload-id): ```bash docker run -d \ --name linuxguard-agent \ --restart unless-stopped \ --pid=host \ --cap-add=BPF --cap-add=PERFMON --cap-add=DAC_READ_SEARCH \ --cap-add=SYS_PTRACE --cap-add=SETPCAP \ --security-opt seccomp=unconfined \ --tmpfs /run/linuxguard:rw,mode=0700,size=10m \ -v /sys/kernel/tracing:/sys/kernel/tracing:ro \ -e LINUXGUARD_ENROLL_TOKEN="$ENROLL_TOKEN" \ -e LINUXGUARD_TENANT_ID="$TENANT_ID" \ -e LINUXGUARD_NODE_NAME="$(hostname)" \ -e LINUXGUARD_POD_UID="$(uuidgen)" \ packages.linuxguard.io/linuxguard-agent:v3.0.0 \ start --tls-cache ``` The `--restart unless-stopped` policy is appropriate when `--tls-cache` is in use because restart no longer triggers re-enrolment (within the same token + workload-id window). ## Example: Kubernetes DaemonSet env block (abbreviated) The full DaemonSet manifest (with `securityContext`, host-path volumes, PSS comment, and RBAC) lives in [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset). The ephemeral-mode env block within that manifest is: ```yaml env: - name: LINUXGUARD_ENROLL_TOKEN valueFrom: secretKeyRef: name: linuxguard-enroll key: token - name: LINUXGUARD_TENANT_ID valueFrom: secretKeyRef: name: linuxguard-enroll key: tenantId - name: LINUXGUARD_NODE_NAME valueFrom: fieldRef: fieldPath: spec.nodeName - name: LINUXGUARD_POD_UID valueFrom: fieldRef: fieldPath: metadata.uid args: ["start", "--tls-cache"] ``` The TOTP token is sourced from a Kubernetes `Secret` (not a literal value) per the [enrollment-tokens guide](/install/install/container/enrollment-tokens). The node name and pod UID come from the Downward API per [Downward API integration](/install/install/container/downward-api). *** **Next Step**: [Kubernetes DaemonSet →](/install/install/container/kubernetes-daemonset) **Related**: [Container deployment hub](/install/install/container) | [Distroless image reference](/install/install/container/distroless) | [Downward API integration](/install/install/container/downward-api) | [Enrollment tokens](/install/install/container/enrollment-tokens) | [`start` CLI reference](/reference/reference/cli/start) | [Environment variables](/reference/reference/cli/env-variables) # Kubernetes DaemonSet Kubernetes DaemonSet deployment of the LinuxGuard agent — copy-pasteable YAML with PSS profile comment, line-by-line securityContext rationale, eBPF prerequisites, and RBAC. The DaemonSet shape runs one LinuxGuard agent pod per node. The agent observes every workload on that node through host PID + tracefs, so a single DaemonSet covers all containerized and host-native workloads on the cluster. This page provides a complete, copy-pasteable manifest with line-by-line rationale for every privilege the Pod requests. > **Important**: The manifest below is classified `# Pod Security Standard: privileged` because it requests elevated kernel-observability capabilities, `hostPID: true`, and host-path volumes for `/sys/kernel/tracing` and `/sys/fs/bpf`. These cannot be granted under the `baseline` or `restricted` PSS profiles. Clusters that enforce `restricted` cluster-wide require an explicit `AdmissionPolicy` waiver — see [Pod Security Standard compatibility](#pod-security-standard-compatibility) below. ## Prerequisites Before applying the manifest, verify the cluster meets the following requirements. Skipping any of these produces a DaemonSet that admits but does not produce eBPF telemetry — the agent runs in `DEGRADED_PROBES_PARTIAL` mode and the cluster's evidence chain has a silent gap. ### Kernel version The agent's eBPF probes require **Linux kernel 5.8 or later**. On older kernels, the agent's loading strategy adapts automatically, but its behavior is not guaranteed and it may run in a reduced-capability mode. Verify per-node: ```bash kubectl get nodes -o wide # check KERNEL-VERSION column ``` ### `kernel.perf_event_paranoid` sysctl The agent's eBPF probe attachment requires a kernel tracing syscall gated by the host sysctl `kernel.perf_event_paranoid`. The required value is **`<= 2`**. Ubuntu 24.04 ships with `kernel.perf_event_paranoid = 4` by default. SET THIS AT NODE LEVEL — it CANNOT be enforced from the Pod spec. ```bash echo 'kernel.perf_event_paranoid = 2' | sudo tee /etc/sysctl.d/99-linuxguard-ebpf.conf sudo sysctl --system ``` ### Seccomp + AppArmor profiles installed on every node The reference seccomp profile (`linuxguard-agent.seccomp.json`) and AppArmor profile (`linuxguard-agent.apparmor`) MUST be present on every node before the agent DaemonSet schedules. The recommended pattern is a sibling DaemonSet that runs an init container with `privileged: true` to write the profiles to the host's `/var/lib/kubelet/seccomp/profiles/` and `/etc/apparmor.d/` directories. The profile-installer DaemonSet (reference manifest available in the agent packaging artifacts shipped with each release) follows the same shape used by KubeArmor and Falco. Adapt your existing profile-installer if your cluster already runs one. ### Image-registry pull access The published image at `packages.linuxguard.io/linuxguard-agent:v3.0.0` is signed; verify the signature once at build time per [Distroless image § Image signing](/install/install/container/distroless#image-signing-and-verification). If your cluster pulls from a mirrored registry, mirror the digest (not the tag) so the deployed bytes match the signed bytes. ## The manifest ```yaml # Pod Security Standard: privileged # Reason: requires elevated kernel-observability capabilities, hostPID: true, # and host-path volumes for tracefs (/sys/kernel/tracing) and BPF FS # (/sys/fs/bpf). These cannot be granted under baseline or restricted PSS # profiles. apiVersion: apps/v1 kind: DaemonSet metadata: name: linuxguard-agent namespace: linuxguard labels: app: linuxguard-agent spec: selector: matchLabels: app: linuxguard-agent updateStrategy: type: RollingUpdate rollingUpdate: maxUnavailable: 1 template: metadata: labels: app: linuxguard-agent spec: serviceAccountName: linuxguard-agent # hostPID gives the agent visibility of every process on the node. # Required for the DaemonSet shape so a single agent observes all # containerized AND host-native workloads on the node. hostPID: true # hostNetwork is NOT required — the agent makes outbound HTTPS via the # Pod's own network namespace. Leaving it false keeps the agent off the # host network namespace and reduces blast radius. hostNetwork: false # Run on all nodes including tainted ones (control-plane, etc.). tolerations: - operator: Exists # Restrict to Linux nodes — Windows nodes do not support eBPF. nodeSelector: kubernetes.io/os: linux # Pod-level securityContext: seccomp profile required for the agent's # kernel-tracing syscall. Installed by the linuxguard-profile-installer DaemonSet. securityContext: seccompProfile: type: Localhost localhostProfile: profiles/linuxguard-agent.json containers: - name: linuxguard-agent # Pin to an immutable tag; never :latest in production. # Verify the signature with cosign before mirroring to a private registry. image: packages.linuxguard.io/linuxguard-agent:v3.0.0 imagePullPolicy: IfNotPresent args: ["start", "--tls-cache"] env: # TOTP enrol token sourced from a Secret — never a literal value. # The agent reads the env var once at startup and immediately calls # os.Unsetenv to scrub /proc//environ. - name: LINUXGUARD_ENROLL_TOKEN valueFrom: secretKeyRef: name: linuxguard-enroll key: token - name: LINUXGUARD_TENANT_ID valueFrom: secretKeyRef: name: linuxguard-enroll key: tenantId # Downward API: node name + pod UID feed the workload-id derivation. - name: LINUXGUARD_NODE_NAME valueFrom: fieldRef: fieldPath: spec.nodeName - name: LINUXGUARD_POD_UID valueFrom: fieldRef: fieldPath: metadata.uid securityContext: # File capabilities are baked into the agent ELF binary. # The bounding-set capabilities below are also required for the # container to start successfully. capabilities: add: [BPF, PERFMON, DAC_READ_SEARCH, SYS_PTRACE, SETPCAP] drop: [ALL] # AppArmor profile installed by the profile-installer DaemonSet. # Requires K8s 1.30+ for the appArmorProfile field; for EKS 1.29 # in extended support, use the legacy annotation form instead. appArmorProfile: type: Localhost localhostProfile: linuxguard-agent # Run as nonroot UID 65532 (baked into the distroless base image). runAsNonRoot: true runAsUser: 65532 runAsGroup: 65532 # File caps make privilege escalation unnecessary. allowPrivilegeEscalation: false # The agent does not write to its image filesystem. readOnlyRootFilesystem: true volumeMounts: # tracefs: probe attach reads /sys/kernel/tracing/events/... # Read-only — the agent does not write tracefs entries. - name: tracefs mountPath: /sys/kernel/tracing readOnly: true # BPF FS: required when the in-process loader pins maps. - name: bpffs mountPath: /sys/fs/bpf # Read-write because pinned-map creation requires write access. # tmpfs for TLS cert cache — never persists to disk. - name: tls-cache mountPath: /run/linuxguard # /proc for process introspection (hostPID gives visibility; # the mount makes the host's /proc readable inside the container). - name: hostproc mountPath: /host/proc readOnly: true resources: requests: cpu: 100m memory: 128Mi limits: # No CPU limit — eBPF map operations spike briefly under load. # CPU throttling would drop telemetry events silently. memory: 512Mi volumes: - name: tracefs hostPath: path: /sys/kernel/tracing type: Directory - name: bpffs hostPath: path: /sys/fs/bpf type: DirectoryOrCreate - name: tls-cache emptyDir: medium: Memory sizeLimit: 10Mi - name: hostproc hostPath: path: /proc type: Directory # Allow a clean shutdown — the agent re-raises SIGTERM as os.Exit(143) # and the orchestrator records the correct exit code via `kubectl describe`. terminationGracePeriodSeconds: 30 ``` ## Line-by-line rationale Each privilege the Pod requests is documented below with the rationale and the consequence of removing it. ### `hostPID: true` Required for the node-level coverage shape. With `hostPID: true`, the agent's `/proc` view exposes every process on the node — including processes inside other containers. Without it, the agent sees only its own PID namespace (the Pod's `/proc`) and produces telemetry only about itself, defeating the DaemonSet purpose. If your cluster forbids `hostPID`, use the [sidecar shape](#sidecar-alternative) instead. ### `hostNetwork: false` The agent does NOT need host networking. It makes outbound HTTPS to the LinuxGuard API via the Pod's own network namespace; the Pod's CNI handles the outbound routing. Setting `hostNetwork: true` would put the agent on the host network namespace unnecessarily and expand blast radius. ### `capabilities.add: [BPF, PERFMON, DAC_READ_SEARCH, SYS_PTRACE, SETPCAP]` These five capabilities are the bounding-set requirement that lets the container start successfully with the file capabilities already baked into the agent ELF: * `BPF` — load the agent's kernel-level monitoring programs. * `PERFMON` — grants access to the performance-monitoring facilities the agent's kernel-level observability requires. * `DAC_READ_SEARCH` — read process executable and memory-map metadata for arbitrary PIDs (process introspection). * `SYS_PTRACE` — required for symbol resolution on older kernels. * `SETPCAP` — required so the agent can drop capabilities it no longer needs once its monitoring programs are attached. Without it, the agent is non-fatally left holding more privilege than necessary for its full lifetime. ### `capabilities.drop: [ALL]` Drop every capability not explicitly added. Defense-in-depth: a future binary that gains additional caps via image rebuild does not silently get to use them at runtime. ### `appArmorProfile.localhostProfile: linuxguard-agent` The AppArmor profile is installed by the profile-installer DaemonSet (sibling deployment, not shown above). The profile constrains the agent's filesystem access patterns so a compromised binary cannot, for example, write to `/etc/sudoers` or read `/root/.ssh/`. ### `runAsNonRoot: true` + `runAsUser: 65532` The distroless base image runs as nonroot UID 65532 by default. Enforcing it at the Pod level produces an admission rejection rather than a silent base-image override — protective against a downstream layer that sets `USER root`. ### `allowPrivilegeEscalation: false` The agent does not need to `setuid` or `setgid` at runtime. The file capabilities baked into the binary already provide everything it needs. ### `readOnlyRootFilesystem: true` The agent writes only to `/run/linuxguard` (the tls-cache tmpfs) and `/tmp` (writable in the distroless base). The image filesystem is fully read-only at runtime. ### `seccompProfile.localhostProfile: profiles/linuxguard-agent.json` The default Docker / containerd seccomp profile blocks a performance-monitoring syscall the agent needs, regardless of the `CAP_PERFMON` capability grant. The custom profile shipped with the agent (`linuxguard-agent.seccomp.json` in the agent packaging artifacts) allows the required syscall. Without this override, probe attach fails with a permission error and the agent degrades to reduced telemetry. ## Security context The DaemonSet Pod requests the following security context — every field has the same rationale as the equivalent setting on the [Distroless image reference](/install/install/container/distroless#security-context); the table below summarizes what the manifest above sets and links each setting to its full rationale in [Line-by-line rationale](#line-by-line-rationale). | Surface | Setting in the manifest | Rationale | | -------------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `hostPID` | `true` | Node-level coverage. See [`hostPID: true`](#hostpid-true). | | `hostNetwork` | `false` | Agent does not need host networking. See [`hostNetwork: false`](#hostnetwork-false). | | `capabilities.add` | `[BPF, PERFMON, DAC_READ_SEARCH, SYS_PTRACE, SETPCAP]` | Bounding-set caps required for the container to start successfully. See [`capabilities.add`](#capabilitiesadd-bpf-perfmon-dac_read_search-sys_ptrace-setpcap). | | `capabilities.drop` | `[ALL]` | Defense-in-depth. See [`capabilities.drop`](#capabilitiesdrop-all). | | `seccompProfile` | `Localhost: profiles/linuxguard-agent.json` | Custom profile permits the agent's kernel-tracing syscall. See [`seccompProfile`](#seccompprofilelocalhostprofile-profileslinuxguard-agentjson). | | `appArmorProfile` | `Localhost: linuxguard-agent` | AppArmor constraints on filesystem access. See [`appArmorProfile`](#apparmorprofilelocalhostprofile-linuxguard-agent). | | `runAsNonRoot` | `true` | Image runs as nonroot UID 65532. See [`runAsNonRoot: true`](#runasnonroot-true--runasuser-65532). | | `runAsUser` / `runAsGroup` | `65532` / `65532` | Distroless nonroot UID/GID. | | `allowPrivilegeEscalation` | `false` | File caps make `setuid` unnecessary. See [`allowPrivilegeEscalation: false`](#allowprivilegeescalation-false). | | `readOnlyRootFilesystem` | `true` | Agent does not write to image filesystem. See [`readOnlyRootFilesystem: true`](#readonlyrootfilesystem-true). | The manifest's security context corresponds to PSS `privileged` — see [§ Pod Security Standard compatibility](#pod-security-standard-compatibility) below for the classification and the `restricted`-cluster guidance. ## Pod Security Standard compatibility The manifest above is classified as **`privileged`** under the Kubernetes Pod Security Standards. | PSS profile | Compatible with this manifest? | What's blocked | | ----------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | privileged | Yes | No PSS-level constraints. | | baseline | No | `baseline` disallows `hostPID: true`, host-path volumes for `/sys/kernel/tracing` and `/proc`, and the `BPF` + `PERFMON` capabilities. | | restricted | No | `restricted` requires `runAsNonRoot: true` (satisfied), but ALSO disallows ALL added capabilities, host namespaces, and most `hostPath` volumes. | ### Running under `restricted` clusters If your cluster enforces `restricted` cluster-wide and the policy CANNOT be relaxed at the namespace level, two options exist: 1. **AdmissionPolicy waiver.** Carve out the `linuxguard` namespace via a `ValidatingAdmissionPolicy` that exempts the agent's specific privileges. This is the auditable path: the waiver lives in cluster config, is reviewable in change management, and applies only to the agent's namespace + ServiceAccount. 2. **Consult support.** v4.0 does not ship a `restricted`-compatible deployment shape. If your environment requires one, open a support case so the alternative deployment patterns (e.g., a host-installed agent reaching into the cluster's container runtime) can be evaluated. Do NOT attempt to run the manifest with capabilities stripped to fit `restricted` — the agent will start and silently produce no behavioral telemetry, and the cluster's evidence chain will have a silent gap. ## Host paths | Path | Mount mode | Justification | Removable? | | --------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `/sys/kernel/tracing` | read-only hostPath | Required for probe attach at startup. The distroless image does not include `/sys` mounts. | No — without this, probe attach fails and the agent degrades. | | `/sys/fs/bpf` | read-write hostPath | Required for the agent's BPF map storage shared across processes. | No — pinned-map creation fails without write access. | | `/proc` | read-only hostPath (mounted at `/host/proc`) | Process introspection. The agent walks the host's `/proc` for the workload-discovery pass when `hostPID` is set. | No — without it, the agent observes only its own PID namespace. | | `/run/linuxguard` | tmpfs (emptyDir `medium: Memory`) | TLS cert cache when `--tls-cache` is set. Tmpfs (not durable storage) so cert material never reaches disk. | Only if `--tls-cache` is removed from `args`. | > **Security Note**: All host-path mounts are read-only **except** `/sys/fs/bpf` (which requires write for pinned-map creation) and `/run/linuxguard` (which is a tmpfs, not a host path). Do NOT mount the host root (`/`) — the agent does not need it; mounting it expands the blast radius of a container escape to the entire node. See the [anti-patterns hub section](/install/install/container#anti-patterns). ## RBAC The agent makes **no Kubernetes apiserver calls** at runtime. Workload identity is derived from the Downward API env vars (injected at admission time, no apiserver lookups), and telemetry ships via outbound mTLS to the LinuxGuard API. The minimal RBAC is therefore just a ServiceAccount with no `Role` or `ClusterRole`: ```yaml apiVersion: v1 kind: ServiceAccount metadata: name: linuxguard-agent namespace: linuxguard ``` The Pod runs under this ServiceAccount. No `RoleBinding` or `ClusterRoleBinding` is required because no `Role` exists to bind. ### Profile-installer DaemonSet RBAC The sibling profile-installer DaemonSet (which writes seccomp + AppArmor profiles to host paths) DOES require its own ServiceAccount + RBAC for the init-container's privileged host-path writes. Its RBAC ships in the agent packaging artifacts. ### `linuxguard-enroll` Secret The Secret referenced by the `valueFrom.secretKeyRef` env block above must be created out-of-band before the DaemonSet rolls out: ```bash kubectl create namespace linuxguard kubectl create secret generic linuxguard-enroll \ --namespace=linuxguard \ --from-literal=token= \ --from-literal=tenantId= ``` The token is single-use per pod identity — rotate it on every DaemonSet roll if you want each pod to enrol with a fresh identity. See [Enrollment tokens](/install/install/container/enrollment-tokens) for the rotation pattern. ## Sidecar alternative The DaemonSet shape is preferred. The sidecar shape exists for the narrow case where pod-level isolation is mandated by policy and a node-level pod is explicitly rejected. Differences from the DaemonSet manifest: * `hostPID: false` — the sidecar observes only its sibling containers in the same Pod. * No `tolerations` — sidecars run alongside the application. * The agent runs as an additional container in the application's Pod spec, not in a dedicated namespace. * Resource cost is per-pod, not per-node — at 100 application pods, you run 100 agent sidecars instead of one agent per node. > **Important**: Do NOT run both a DaemonSet AND a per-pod sidecar. The DaemonSet's `hostPID: true` already observes every process on the node, including the sidecar's host. Double-deploying produces duplicate events that double-count in console alerts and SIEM ingestion. See the [anti-patterns hub section](/install/install/container#anti-patterns). ## Node selection and tolerations The manifest above selects `kubernetes.io/os: linux` and tolerates all taints. Common adjustments: * **Exclude control-plane nodes** — if your security model excludes the control plane from coverage, replace the `Exists` toleration with a `NoSchedule` toleration that lists only the worker-node taints. * **Restrict to a specific node pool** — add a `nodeSelector` or `nodeAffinity` rule. * **Exclude legacy kernel nodes** — the agent degrades cleanly on kernels older than 5.8, but excluding those nodes via affinity makes the coverage gap explicit. ## Verification After applying the manifest, verify the DaemonSet is fully ready and the agent is producing heartbeats: ```bash # All nodes should have a ready pod. kubectl -n linuxguard rollout status daemonset/linuxguard-agent --timeout=2m # Pick a pod and inspect the recent logs. POD=$(kubectl -n linuxguard get pod -l app=linuxguard-agent -o name | head -n1) kubectl -n linuxguard logs $POD --tail=20 | grep -E 'heartbeat|degraded|error' # Confirm this node is NOT in a degraded-telemetry mode (or DEGRADED_PROBES_PARTIAL). # (On architectures without eBPF support, the agent automatically falls back to a reduced-telemetry mode instead of failing to start — that fallback is expected there, not here.) kubectl -n linuxguard exec $POD -- /usr/local/bin/linuxguard-agent probe --pretty ``` A healthy DaemonSet produces a `heartbeat` log line within 20 seconds of pod start and `probe` reports `kernel/bpf/fanotify/netlink/audit/caps` all green. A degraded probe report points to a missing prerequisite — most commonly `kernel.perf_event_paranoid > 2` or a missing seccomp profile. *** **Next Step**: [Downward API integration →](/install/install/container/downward-api) **Related**: [Container deployment hub](/install/install/container) | [Distroless image reference](/install/install/container/distroless) | [Ephemeral mode](/install/install/container/ephemeral-mode) | [Enrollment tokens](/install/install/container/enrollment-tokens) | [`probe` CLI reference](/reference/reference/cli/probe) # Downward API integration Kubernetes Downward API integration for the LinuxGuard agent — LINUXGUARD\_NODE\_NAME and LINUXGUARD\_POD\_UID via fieldRef, workload identity derivation. The LinuxGuard agent derives its **workload identifier** in ephemeral mode from two Kubernetes Downward API values — the node name and the pod UID. This page documents the binding, the workload-id derivation rule, and the consequences of getting the binding wrong. > **Important**: The agent **refuses to start** in ephemeral mode when neither (a) both `LINUXGUARD_NODE_NAME` AND `LINUXGUARD_POD_UID` are set, NOR (b) `--workload-id ` is supplied on the command line. There is **no silent UUID fallback**. The hard-error message lists all three input sources so the operator can diagnose without reading code. ## Required env-var bindings Two env vars are sourced from the Kubernetes Downward API via `valueFrom.fieldRef`. Both MUST be present in the Pod spec for ephemeral mode to start; missing either one produces the workload-id derivation error. ```yaml env: - name: LINUXGUARD_NODE_NAME valueFrom: fieldRef: fieldPath: spec.nodeName - name: LINUXGUARD_POD_UID valueFrom: fieldRef: fieldPath: metadata.uid ``` | Env var | `fieldRef.fieldPath` | What it resolves to | | ---------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LINUXGUARD_NODE_NAME` | `spec.nodeName` | The name of the node the Pod is scheduled on (e.g., `ip-10-0-0-42`, `worker-node-3`, `gke-default-pool-abc123-xyz`). Kubelet sets this when the Pod is admitted; it never changes for the lifetime of the Pod. | | `LINUXGUARD_POD_UID` | `metadata.uid` | The RFC 4122 v4 UUID Kubernetes assigns to the Pod (e.g., `7b8f9c1d-3e4a-4b5c-9d6e-1f2a3b4c5d6e`). Stable for the lifetime of the Pod; a restart with the same Pod name produces a NEW uid. | Both fields are populated **at Pod admission time** by the Kubernetes API server. No apiserver lookups occur from inside the container — the values are baked into the container's environ block at scheduling time, and the agent reads them with `os.Getenv` at startup. ## Workload identifier derivation The agent uses the two env vars to derive its workload identifier. The derivation is deterministic: ``` workload_id = hex(sha256(LINUXGUARD_NODE_NAME + ":" + LINUXGUARD_POD_UID)) ``` The colon separator distinguishes the two-part hash from a malicious value that crafts a node name containing a UID-looking suffix (or vice versa). The hex-encoded SHA-256 is used as the `Idempotency-Key` HTTP header on the enrolment POST so a retried request does not produce two server identities for the same workload. The derivation order is: 1. **Explicit `--workload-id `** → `sha256(explicit)`. The flag value is hashed (not used verbatim). 2. **Downward API env vars** → `sha256(LINUXGUARD_NODE_NAME + ":" + LINUXGUARD_POD_UID)`. Both must be present. 3. **Neither set** → hard error: ``` --ephemeral requires either Downward API env vars (LINUXGUARD_NODE_NAME and LINUXGUARD_POD_UID, set via valueFrom.fieldRef) OR --workload-id CLI flag; none of the three were present ``` This deliberate hard-error matters: a misconfigured Pod that derived a random UUID at startup would silently enrol a new identity on every restart, producing a sprawl of orphan enrollments in the tenant. The explicit failure forces the operator to fix the manifest before the cluster's agent fleet accumulates phantom identities. ## Stability properties | Event | `LINUXGUARD_NODE_NAME` changes? | `LINUXGUARD_POD_UID` changes? | Workload-id changes? | | -------------------------------------------------------------------- | ------------------------------- | ---------------------------------- | -------------------- | | Pod restarts on the same node (e.g., kubelet restart, container OOM) | No | No (same Pod object) | No | | Pod evicted, rescheduled to the **same** node | No | **Yes** (new Pod object → new uid) | Yes | | Pod evicted, rescheduled to a **different** node | Yes | Yes | Yes | | DaemonSet rolled (new revision) | No | Yes (new Pod per node) | Yes | | Container restarts within the same Pod (e.g., crash loop) | No | No | No | For the DaemonSet shape, this means **every DaemonSet roll produces a new workload identity per node**. The agent re-enrols on each roll because the workload-id has changed. This is the intended behavior — a freshly-deployed agent gets a fresh server identity rather than inheriting state from the prior pod. For the sidecar shape, the workload-id changes whenever the application Pod is rescheduled. Sidecars in a `Deployment` get a new uid on every Pod replacement; sidecars in a `StatefulSet` get a stable uid only when the Pod is recreated under the same name (which still produces a new uid in Kubernetes' model). ## Cross-reference with TLS cache The TLS cert cache (`--tls-cache`, see [Ephemeral mode § TLS cache restart semantics](/install/install/container/ephemeral-mode#tls-cache-restart-semantics)) keys its invalidation tag on the workload-id: ``` tag = hex(sha256(LINUXGUARD_ENROLL_TOKEN + ":" + workload_id)) ``` This means a workload-id change (e.g., Pod evicted and rescheduled) **automatically invalidates the cached cert chain**, and the agent performs a fresh enrolment under the new identity. Operators do not need to manually clear the cache on reschedule. ## Security context The Downward API binding itself has no additional security context implications beyond the base ephemeral mode security context — see [Distroless image § Security context](/install/install/container/distroless#security-context). Both env vars are public Kubernetes metadata (node names and Pod UIDs appear in `kubectl get pods -o wide` output) and do not require Secret-style protection. The `LINUXGUARD_POD_UID` env var is exposed in `/proc//environ` for the agent's lifetime — this is acceptable because the Pod UID is not a secret. The token (`LINUXGUARD_ENROLL_TOKEN`) IS a secret and receives the `os.Unsetenv` scrub at startup; the Downward API env vars do NOT receive that treatment and remain readable for the agent's lifetime. ## Host paths The Downward API binding requires no additional host-path mounts beyond those documented in the per-orchestrator spoke ([Kubernetes DaemonSet § Host paths](/install/install/container/kubernetes-daemonset#host-paths) or [Ephemeral mode § Host paths](/install/install/container/ephemeral-mode#host-paths)). The fieldRef values are baked into the container's environ block at admission time — no node-level filesystem access is involved. ## Pod Security Standard compatibility | PSS profile | Downward API `fieldRef` compatible? | Notes | | ----------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | privileged | Yes | No PSS-level constraints. | | baseline | Yes | The Downward API `fieldRef` mechanism is permitted under baseline; the binding involves no privileged operations. | | restricted | Yes | The Downward API `fieldRef` mechanism is permitted under restricted; the binding involves no privileged operations. | The Downward API binding is PSS-neutral. The agent's other capability requirements (elevated kernel-observability permissions plus `hostPID`) are what classify the Pod spec as `privileged` — not the Downward API itself. A future PSS-compatible deployment shape would inherit the same Downward API binding unchanged. ## RBAC The Downward API `fieldRef` mechanism requires **no RBAC** — the values are populated by the kubelet at Pod admission time, not by an apiserver call from inside the container. The Pod's ServiceAccount needs no `Role` or `ClusterRole` to read `spec.nodeName` or `metadata.uid` because the agent does not read them via the apiserver; it reads them from `os.Environ`. This contrasts with the `Projected ServiceAccount Token` pattern (where the kubelet projects a token into a volume) — that pattern DOES require a workload-identity-binding RBAC, but the LinuxGuard agent does not use it. ## Common mistakes ### Hardcoding the node name in a ConfigMap ```yaml # WRONG env: - name: LINUXGUARD_NODE_NAME value: "worker-node-1" # hardcoded — wrong on every other node ``` This populates the same node name on every pod of the DaemonSet. The workload-id collapses to a single value across the cluster, every agent enrols under the same identity, and the backend de-duplicates them — silently dropping coverage of every node except the first. **Correct:** Always use `valueFrom.fieldRef.fieldPath: spec.nodeName`. ### Hardcoding a UUID ```yaml # WRONG env: - name: LINUXGUARD_POD_UID value: "00000000-0000-0000-0000-000000000000" # placeholder UUID ``` The same problem — the workload-id derives the same value across all pods. Every pod enrols under the same identity; coverage collapses to one phantom workload. **Correct:** Always use `valueFrom.fieldRef.fieldPath: metadata.uid`. ### Using `metadata.name` instead of `metadata.uid` ```yaml # WRONG env: - name: LINUXGUARD_POD_UID valueFrom: fieldRef: fieldPath: metadata.name # name, not uid ``` A Pod's name is not the same as its uid. In a DaemonSet, names follow the pattern `-` and DO vary per pod; this misconfiguration may appear to work in a fresh deployment but produces collisions whenever a Pod is recreated under the same name (StatefulSet recreations under the same ordinal, for example). **Correct:** Use `metadata.uid` — the only field guaranteed unique across the entire cluster lifetime. ### Forgetting one of the two env vars ```yaml # WRONG — LINUXGUARD_POD_UID missing env: - name: LINUXGUARD_NODE_NAME valueFrom: fieldRef: fieldPath: spec.nodeName ``` The agent refuses to start with the hard-error message above. There is no fallback to "node-name-only" workload identity by design. **Correct:** Always set BOTH env vars together, OR supply `--workload-id ` on the command line as the explicit override. ### Non-Kubernetes ephemeral deployment In Docker / Podman ephemeral deployments (no Kubernetes), `spec.nodeName` and `metadata.uid` do not exist. The Downward API binding is Kubernetes-specific. **Correct:** Supply both env vars manually via `-e LINUXGUARD_NODE_NAME= -e LINUXGUARD_POD_UID=`, OR pass `--workload-id ` as the explicit identifier. See [Ephemeral mode § Example: Docker run](/install/install/container/ephemeral-mode#example-docker-run-ephemeral-no-cache). ## Verification After applying a manifest that uses the Downward API binding, verify the env vars are populated correctly: ```bash POD=$(kubectl -n linuxguard get pod -l app=linuxguard-agent -o name | head -n1) kubectl -n linuxguard exec $POD -- /usr/local/bin/linuxguard-agent show-config | grep -E 'workload|node' ``` The output should show the derived workload-id and the node name. If `show-config` reports a missing workload-id, the most common causes are: 1. The Pod was not scheduled with the Downward API env block in its spec — recheck `kubectl -n linuxguard get pod $POD -o yaml | grep -A 3 LINUXGUARD_NODE_NAME`. 2. A `fieldRef.fieldPath` is wrong — confirm it is exactly `spec.nodeName` for the node and `metadata.uid` for the Pod UID. 3. The values were overridden by a ConfigMap or `envFrom` block that took precedence — verify env-var precedence with `kubectl exec $POD -- env | grep LINUXGUARD`. *** **Next Step**: [Enrollment tokens →](/install/install/container/enrollment-tokens) **Related**: [Container deployment hub](/install/install/container) | [Ephemeral mode](/install/install/container/ephemeral-mode) | [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset) | [Environment variables](/reference/reference/cli/env-variables) | [`start` CLI reference](/reference/reference/cli/start) # Enrollment tokens TOTP enrollment token flow for the LinuxGuard agent in containers — LINUXGUARD\_ENROLL\_TOKEN, valueFrom.secretKeyRef pattern, token-hash tag for renewal tracking. A LinuxGuard agent in ephemeral mode enrols once at startup via a short-lived **TOTP enrolment token**. The token is a single-use credential that the backend's `/agent/enroll` handler exchanges for an mTLS cert chain. This page documents how to supply the token securely, why the agent immediately unsets the env var at startup, and the `valueFrom.secretKeyRef` pattern that is the only correct Kubernetes injection path. > **Security Note**: NEVER set `LINUXGUARD_ENROLL_TOKEN` to a literal value in YAML, ConfigMaps, command-line arguments, or anything else that ends up in plain text in your source repository or shell history. The only safe injection paths are: a Kubernetes `Secret` referenced via `valueFrom.secretKeyRef`, an environment variable populated by a secrets manager at container start, or a Docker `-e` flag whose value comes from a shell variable sourced at runtime from a secret store. ## Token format The token is a base32-encoded string of 24-32 characters, typically formatted as four groups separated by dashes (e.g., `ABCD-EFGH-IJKL-MNOP-QRST-UVWX`). Generation is done in the LinuxGuard console (Identity → Enrollment Tokens → Create) — the token is shown once at creation time and never again. If you lose it, generate a new one. | Property | Value | | ------------------------- | ---------------------------------------------------------------------------------------- | | Length | 24-32 characters | | Character set | Base32 alphabet (`A-Z`, `2-7`), plus optional dashes for readability | | Time-to-live | Configured per-tenant; typical 5-15 minutes | | Use count | **Single-use per workload identity** — see [§ Re-use anti-pattern](#re-use-anti-pattern) | | Console path for creation | Identity → Enrollment Tokens → Create | ## Required flags / env vars Three values must be supplied for the TOTP enrolment path to succeed: | Variable | Purpose | Source | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `LINUXGUARD_ENROLL_TOKEN` (or `--enroll-token`) | The TOTP token itself | `valueFrom.secretKeyRef` (K8s) or shell variable sourced from a secret store (Docker) | | `LINUXGUARD_TENANT_ID` (or `--tenant-id`) | Tenant the agent enrols into. **Required** on the TOTP path. | `valueFrom.secretKeyRef` (K8s) or shell variable (Docker); the tenant ID is not secret-sensitive but is typically stored alongside the token for operational convenience | | Workload identity inputs | EITHER `LINUXGUARD_NODE_NAME` + `LINUXGUARD_POD_UID` from the Downward API, OR `--workload-id ` | See [Downward API integration](/install/install/container/downward-api) | The backend's `/agent/enroll` handler **rejects** the enrolment with `400 "tenantId required for TOTP enrollment"` when the request body's `TenantID` is empty AND `EnrollCode` is set. Long-lived API-key enrollments do NOT require the tenant ID (they carry it server-side), but the TOTP path always does. ## Why the agent unsets the env var at startup The agent reads `LINUXGUARD_ENROLL_TOKEN` once at the very top of the `start` action, captures the value, and immediately calls `os.Unsetenv("LINUXGUARD_ENROLL_TOKEN")` BEFORE any goroutine forks. This special handling addresses a Linux process-introspection leak: On Linux, an unprivileged process running as the same UID as the agent can read `/proc//environ` for the lifetime of the agent process and observe every environment variable the agent inherited at exec time. If `LINUXGUARD_ENROLL_TOKEN` remained in the agent's environ block, a hostile co-tenant or a misconfigured monitoring agent could read the raw token and (within its TTL) self-enrol a rogue identity into the same tenant. `os.Unsetenv` updates the Go runtime's internal `environ()` slice and rewrites the same memory the kernel exposes via `/proc//environ`. Subsequent reads of that pseudo-file return the redacted set. Empirically the window in which `/proc//environ` contains the token is approximately the latency between `execve` and `os.Unsetenv` — measured in milliseconds, not minutes. The token is consumed once for the enrol POST and never needed again. The resulting mTLS cert chain is held in memory (or mirrored to `/run/linuxguard/tls/` when `--tls-cache` is set — see [Ephemeral mode § TLS cache restart semantics](/install/install/container/ephemeral-mode#tls-cache-restart-semantics)). The early unset does not impede operation. > **Security Note**: The unset DOES NOT clear the inherited environ block from kernel memory if a child process was already forked before the unset call. Avoid CMD entrypoints that spawn shell wrappers, init scripts, or other intermediary processes before the agent binary executes. The published distroless image's `ENTRYPOINT ["/usr/local/bin/linuxguard-agent"]` execs the agent directly with no shell — preserve this property in any downstream layer. ## Kubernetes: `valueFrom.secretKeyRef` pattern The ONLY correct Kubernetes injection path is `valueFrom.secretKeyRef`. The token lives in a `Secret`, the Pod spec references the Secret key, and the kubelet populates the env var at container start. ### Step 1: Create the Secret ```bash kubectl create namespace linuxguard # The token + tenantId can be in the same Secret object for operational # convenience — they are rotated together at the same cadence. kubectl create secret generic linuxguard-enroll \ --namespace=linuxguard \ --from-literal=token= \ --from-literal=tenantId= ``` Or declaratively (suitable for GitOps when the value is sourced from a secrets manager via `kustomize` / `helm` / `external-secrets-operator`, NEVER from a checked-in literal): ```yaml apiVersion: v1 kind: Secret metadata: name: linuxguard-enroll namespace: linuxguard type: Opaque stringData: token: # injected from secrets manager, NEVER committed tenantId: ``` ### Step 2: Reference the Secret in the Pod spec ```yaml env: - name: LINUXGUARD_ENROLL_TOKEN valueFrom: secretKeyRef: name: linuxguard-enroll key: token - name: LINUXGUARD_TENANT_ID valueFrom: secretKeyRef: name: linuxguard-enroll key: tenantId ``` The kubelet reads the Secret from etcd at Pod admission time and populates the env vars in the container's environ block. The values flow through the same `os.Environ` path the agent reads at startup, and the same `os.Unsetenv` scrub applies to `LINUXGUARD_ENROLL_TOKEN` once it has been consumed. ### Step 3: Confirm the Secret is NOT exposed as a literal value anywhere Audit the Pod spec for the anti-pattern below: ```yaml # WRONG — literal token in plain text env: - name: LINUXGUARD_ENROLL_TOKEN value: "ABCD-EFGH-IJKL-MNOP-QRST-UVWX" ``` Even if the manifest lives in a private repository, this leaks the token to: * Anyone with read access to the repository (including CI build logs that echo the manifest). * `kubectl get pod -o yaml` output, which is visible to anyone with `pods/get` RBAC in the namespace. * Cluster audit logs, which may be retained for years. The `valueFrom.secretKeyRef` pattern keeps the token out of all three surfaces. The Secret object itself can be additionally protected via Kubernetes `--encryption-provider-config` at the etcd layer. ## Docker: shell-sourced env var For Docker / Podman deployments where Kubernetes Secret machinery is not available, the equivalent pattern sources the token from a shell variable that is populated at runtime from a secret store (e.g., HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, 1Password CLI): ```bash # Source the token from your secret store — never hardcode. ENROLL_TOKEN=$(vault kv get -field=token secret/linuxguard/enroll) TENANT_ID=$(vault kv get -field=tenantId secret/linuxguard/enroll) docker run --rm \ --pid=host \ --cap-add=BPF --cap-add=PERFMON --cap-add=DAC_READ_SEARCH \ --cap-add=SYS_PTRACE --cap-add=SETPCAP \ --security-opt seccomp=unconfined \ -v /sys/kernel/tracing:/sys/kernel/tracing:ro \ -e LINUXGUARD_ENROLL_TOKEN="$ENROLL_TOKEN" \ -e LINUXGUARD_TENANT_ID="$TENANT_ID" \ -e LINUXGUARD_NODE_NAME="$(hostname)" \ -e LINUXGUARD_POD_UID="$(uuidgen)" \ packages.linuxguard.io/linuxguard-agent:v3.0.0 ``` The shell variable assignment is ephemeral — it lives only in the current shell process and is GC'd when the script exits. Do NOT `export` the variable into the wider shell environment; the `-e` flag accepts non-exported variables in the same expansion pass. Avoid: * `-e LINUXGUARD_ENROLL_TOKEN=ABCD-EFGH-...` with a literal value (shell history leak). * Docker's environment-file flag pointing at a `linuxguard.env` written to disk in plain text (filesystem persistence leak). * `docker exec` invocations that pass the token as a command-line argument (cmdline leak). ## Token-hash tag for renewal tracking When `--tls-cache` is set, the agent writes a `.tag` sidecar file in the cache directory containing: ``` hex(sha256(token + ":" + workload_id)) ``` This tag value is the agent's mechanism for **detecting token rotation across restarts**. On every start with `--tls-cache`: 1. The agent computes the current `.tag` value from the (just-read) env-var token + the derived workload-id. 2. The agent reads the existing `.tag` file from the cache. 3. **If they match** — the token has not been rotated since the last successful enrolment, and the cached cert chain is reused without an enrol call. 4. **If they diverge** — either the token has been rotated, or the workload-id has changed (e.g., new Pod UID). The cache directory is deleted and a fresh enrolment runs under the new token. The tag value contains a hashed token, not the raw token. An attacker reading `/run/linuxguard/tls/.tag` learns only that some hash of some token + workload-id exists; they cannot recover the token from the tag. ### Rotation cadence Token rotation cadence is a tenant policy choice. Common shapes: * **Per-deployment roll** — rotate the Secret before each DaemonSet roll so every new pod enrols under a fresh token. The token-hash tag invalidates the cache automatically; no manual cache clear required. * **Per-hour rotation** — rotate the Secret hourly via a CronJob that pulls a fresh token from the LinuxGuard API and updates the Kubernetes Secret. Existing pods continue using their cached cert chain (the agent reads the env var only at startup; mid-process rotation has no effect on a running agent). New pods enrol under the freshly-rotated token. * **On-demand rotation** — rotate when a token is suspected of compromise. Delete the old Secret, create a new one, and roll the DaemonSet. The cache-tag mismatch on the rolled pods triggers fresh enrolment. The agent does NOT poll for token rotation while running. The token is consumed only at startup; rotation takes effect on the next restart. ## Re-use anti-pattern > **Important**: Each pod must receive a FRESH TOTP token. Re-using the same token across multiple pods in a DaemonSet produces partial enrolment with silent gaps. The backend's `/agent/enroll` handler treats each token as **single-use per workload identity**. The first pod that POSTs the enrolment with a given token + workload-id succeeds and receives the cert chain. Subsequent POSTs from other pods with the same token + workload-id fall into one of three failure modes: 1. **Same workload-id, replay** — backend returns the cached enrolment response idempotently. The replayed pod gets the same cert chain. This works correctly only when the workload-id matches (the Downward API binding guarantees per-Pod uniqueness; see [Downward API § Workload identifier derivation](/install/install/container/downward-api#workload-identifier-derivation)). 2. **Different workload-id, same token** — backend returns `409 conflict` because the token was already consumed by a different identity. The pod fails to enrol and either exits or retries; either way it does not produce telemetry. 3. **Token expired** — backend returns `400` after the TOTP TTL has elapsed. The pod fails to enrol. Pods that pull a fresh-but-expired token from an out-of-date Secret experience this; rotate the token before the TTL window closes. **Correct rotation pattern:** The Kubernetes Secret is rotated **externally** (by an enrolment service, secrets manager, or operator-driven process) so that each new pod sees a new value. Common shapes: * An external-secrets-operator that syncs the LinuxGuard `/api/tokens/new` response into the Kubernetes Secret on a schedule. * A pre-roll CronJob that rotates the Secret before invoking `kubectl rollout restart`. * A controller pattern that watches DaemonSet events and rotates the Secret on each new pod start. The shape that is INCORRECT: a single token value baked into the Secret at cluster bootstrap and never rotated. The first DaemonSet rollout works; every subsequent pod (on node addition, on Pod eviction, on container restart-without-cache) fails to enrol. ## `--enroll-token` flag vs `LINUXGUARD_ENROLL_TOKEN` env var The `start` command accepts the token via either path. The env var is preferred: | Path | Recommended | Why | | --------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LINUXGUARD_ENROLL_TOKEN` env var | **Yes** | The agent reads the env var, captures the value, immediately calls `os.Unsetenv` to scrub `/proc//environ`. Token does not appear in the process command line, shell history, or `kubectl describe pod` event output. | | `--enroll-token ` flag | No | The token appears in `/proc//cmdline`, which is world-readable by default (any local UID can read it). Also appears in shell history and in container-runtime audit logs that record the command. | The `--enroll-token` flag exists for compatibility (and for one-shot interactive testing where the operator types the token at a controlled shell), but production deployments MUST use the env-var path. ## Security context The enrolment-token flow runs the agent under the same security context as any other ephemeral deployment — see [Ephemeral mode § Security context](/install/install/container/ephemeral-mode#security-context). The token-specific surface adds the env-var scrub described above and the `secretKeyRef` Kubernetes pattern; neither modifies the Pod-level security context. ## Host paths The enrolment-token flow requires no additional host-path mounts beyond those documented in the per-orchestrator spoke. The token is consumed at startup and the resulting cert chain is held in memory (or in the `/run/linuxguard/` tmpfs when `--tls-cache` is active) — no node-level filesystem access is involved in the token flow itself. ## Pod Security Standard compatibility | PSS profile | Compatible with `valueFrom.secretKeyRef`? | Notes | | ----------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | privileged | Yes | No PSS-level constraints. | | baseline | Yes | Secret-backed env vars are permitted under baseline. | | restricted | Yes | Secret-backed env vars are permitted under restricted. The token-flow surface itself is PSS-neutral — the agent's other capability requirements are what classify the Pod as `privileged`. | The enrolment-token flow itself does not influence the Pod's PSS classification. It can be combined with any Pod-level security context the orchestrator permits. ## RBAC The enrolment-token flow requires that the Pod's ServiceAccount can **read** the `linuxguard-enroll` Secret in its own namespace. The default behavior in Kubernetes (RBAC enabled) is that a Pod's ServiceAccount has access to Secrets explicitly referenced in its own Pod spec via the kubelet's Secret-reading credentials — NO explicit `Role` or `RoleBinding` is required for the Pod itself. If your cluster runs additional admission policies that restrict Secret reads (e.g., OPA Gatekeeper, Kyverno), the rules MUST allow the `linuxguard-agent` ServiceAccount to read the `linuxguard-enroll` Secret. The minimal Role + RoleBinding for explicit access: ```yaml apiVersion: rbac.authorization.k8s.io/v1 kind: Role metadata: name: linuxguard-enroll-reader namespace: linuxguard rules: - apiGroups: [""] resources: ["secrets"] resourceNames: ["linuxguard-enroll"] verbs: ["get"] --- apiVersion: rbac.authorization.k8s.io/v1 kind: RoleBinding metadata: name: linuxguard-enroll-reader namespace: linuxguard subjects: - kind: ServiceAccount name: linuxguard-agent namespace: linuxguard roleRef: apiGroup: rbac.authorization.k8s.io kind: Role name: linuxguard-enroll-reader ``` This is required ONLY when an admission policy enforces explicit Secret-read permission. The default Kubernetes RBAC behavior does not require it. ## Verification After applying a manifest with `valueFrom.secretKeyRef`, verify the token is being delivered to the container without appearing in any visible surface: ```bash POD=$(kubectl -n linuxguard get pod -l app=linuxguard-agent -o name | head -n1) # The token should NOT be visible in `kubectl describe`. kubectl -n linuxguard describe pod $POD | grep -i token # expect no match # The agent should have logged a successful enrolment. kubectl -n linuxguard logs $POD --tail=50 | grep -E 'enroll|heartbeat' # After the agent has started, /proc//environ should NOT contain the token. # (Verify from inside the container via a debug ephemeral container if the # distroless image makes this awkward — see Distroless § Debugging.) ``` A successful enrolment produces a log line containing `enrol` or `heartbeat` within 20 seconds of pod start. If the agent logs `enrolment failed: 400 tenantId required for TOTP enrollment`, the `LINUXGUARD_TENANT_ID` env var is missing or empty. If the agent logs `409 conflict`, the token has already been consumed by a different workload-id — rotate the Secret. *** **Next Step**: [docker-compose →](/install/install/container/docker-compose) **Related**: [Container deployment hub](/install/install/container) | [Ephemeral mode](/install/install/container/ephemeral-mode) | [Downward API integration](/install/install/container/downward-api) | [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset) | [Environment variables](/reference/reference/cli/env-variables) # docker-compose Deploy the LinuxGuard agent with docker-compose — compose.yaml example, capabilities, host paths, restart policy, and PID 1 considerations. This page covers running the LinuxGuard agent under docker-compose. The shape is single-node, suitable for a lab host, an edge appliance, a developer workstation, or any environment where a Kubernetes DaemonSet is overkill but a long-lived agent process is desired. > **Important**: docker-compose is the Docker engine's native orchestrator, not a Kubernetes-compatible one. The Kubernetes Pod Security Standard does not apply. The Docker-engine equivalent — capability gating, seccomp profiles, and AppArmor profiles — is documented in [§ Pod Security Standard compatibility](#pod-security-standard-compatibility) below. ## compose.yaml The recommended compose file. Pin the image to an immutable `vX.Y.Z` tag (never `:latest`) and source the enrolment token from a `.env` file that lives outside source control. ```yaml services: linuxguard-agent: # Pin to an immutable tag; never :latest in production. image: packages.linuxguard.io/linuxguard-agent:v3.0.0 container_name: linuxguard-agent # Restart unless explicitly stopped — pairs well with --tls-cache so # restarts reuse the cached cert chain rather than re-enrolling. restart: unless-stopped # PID 1 auto-detection: the agent IS the container's main process. # An init shim is NOT required — the agent's pid1 build tag installs # its own zombie-reaper. Do NOT set `init: true` on this service. init: false # Host PID so the agent observes all processes on the node. pid: host # Add the five capabilities the file-cap transition requires. cap_add: - BPF - PERFMON - DAC_READ_SEARCH - SYS_PTRACE - SETPCAP # Drop everything else; defense-in-depth against image updates that # might add new capabilities silently. cap_drop: - ALL # Default Docker seccomp profile blocks perf_event_open(2). Use # `unconfined` for UAT/dev; for production, supply a custom profile # that adds perf_event_open to the allowlist. security_opt: - seccomp=unconfined # For production, replace the above with: # - seccomp=/etc/docker/seccomp-linuxguard.json # - apparmor=linuxguard-agent # Read-only image filesystem. read_only: true # tmpfs for the TLS cert cache when --tls-cache is set. tmpfs: - /run/linuxguard:rw,mode=0700,size=10m # tracefs bind-mount (read-only) for eBPF probe attach. volumes: - /sys/kernel/tracing:/sys/kernel/tracing:ro # BPF FS for pinned maps (read-write). - /sys/fs/bpf:/sys/fs/bpf # host /proc for process introspection (read-only). - /proc:/host/proc:ro environment: # Source the token from a .env file that is NOT checked into source # control. The agent reads the env var once at startup and immediately # unsets it to scrub /proc//environ. LINUXGUARD_ENROLL_TOKEN: ${LINUXGUARD_ENROLL_TOKEN} LINUXGUARD_TENANT_ID: ${LINUXGUARD_TENANT_ID} # In a non-Kubernetes deployment the workload-id MUST be supplied # explicitly (no Downward API exists). Use a stable host identifier # plus a stable UUID per deployment. LINUXGUARD_NODE_NAME: ${LINUXGUARD_NODE_NAME:-${HOSTNAME}} LINUXGUARD_POD_UID: ${LINUXGUARD_POD_UID} command: ["start", "--tls-cache"] # Resource limits — keep memory bounded; do not cap CPU (eBPF map # operations spike briefly under load and CPU throttling drops events). deploy: resources: limits: memory: 512M ``` The companion `.env` file (referenced by compose at startup): ``` # .env — NEVER commit this file to source control. # Source the token from your secret store at deploy time: # export LINUXGUARD_ENROLL_TOKEN="$(vault kv get -field=token secret/linuxguard/enroll)" LINUXGUARD_ENROLL_TOKEN= LINUXGUARD_TENANT_ID= LINUXGUARD_NODE_NAME= LINUXGUARD_POD_UID= ``` Add `.env` to `.gitignore`. Generate a stable `LINUXGUARD_POD_UID` once per deployment with `uuidgen` and persist it in the `.env` so restart-induced workload-id changes do not produce phantom enrolments. Bring the agent up: ```bash docker compose up -d docker compose logs -f linuxguard-agent # watch for `heartbeat` log line ``` ## Restart policies `docker-compose` exposes three restart policies that matter for the LinuxGuard agent: | Policy | When to use | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `unless-stopped` | **Recommended default.** The agent restarts on container exit (crash, OOM) but stays stopped after an explicit `docker compose stop`. Pairs naturally with `--tls-cache` because restart reuses the cached cert chain without re-enrolling. | | `always` | The agent restarts on every exit, including after `docker compose stop`. Appropriate for fully-unattended edge appliances where the agent must come back up after host reboot regardless of operator intent. | | `on-failure` | Restart only on non-zero exit code. NOT recommended — the agent exits 143 (SIGTERM) on graceful shutdown and 130 (SIGINT) on Ctrl-C, which `on-failure` correctly treats as failure restarts. But `on-failure` interferes with operator stop semantics (a `docker compose stop` sends SIGTERM; the policy sees exit 143 and restarts). | | `no` | The agent never restarts. Use only for one-shot agents (e.g., CI runners that enrol, ship one telemetry snapshot, and exit). For one-shots, the [Ephemeral mode docker run example](/install/install/container/ephemeral-mode#example-docker-run-ephemeral-no-cache) is more idiomatic than docker-compose. | ## PID 1 considerations The agent IS the container's main process — it runs as PID 1 inside the container. Two compose-specific behaviors follow from this: ### Do NOT set `init: true` docker-compose's `init: true` option injects a `tini` or `docker-init` shim as PID 1 to reap zombie children. The agent is built with the `pid1` build tag, which installs its own PID-1 init shim with zombie-reaping. Adding `tini` on top produces two layers of init machinery; the agent's auto-detection of PID 1 (`os.Getpid() == 1`) reports `1` only when it's actually PID 1 — under `init: true`, the agent runs as PID 2 and PID-1 auto-detection silently fails, so ephemeral semantics do NOT activate. If `init: true` is required for some reason (e.g., a multi-process container), set the `LINUXGUARD_PID1_CHILD=1` env var so the agent treats itself as ephemeral despite not being PID 1. This is the same sentinel the agent's own init shim sets when re-execing; setting it from compose is acceptable when `init: true` is mandatory. ### SIGTERM exit code The agent re-raises caught signals as `os.Exit(128 + signum)`: * `SIGTERM` (which `docker compose stop` sends) → exit code 143. * `SIGINT` (which Ctrl-C in `docker compose up` sends) → exit code 130. `docker wait` reports these exit codes correctly. Operators who write health-check scripts that check `docker inspect linuxguard-agent --format '{{ .State.ExitCode }}'` must expect 143/130 on graceful shutdown, not 0 — this is the same behavior documented in the [`start` CLI reference § Exit codes](/reference/reference/cli/start#exit-codes). ## Volume mounts The compose example mounts four paths. Each is justified and minimal: | Mount | Type | Direction | Justification | | -------------------------------------------- | ----- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/sys/kernel/tracing:/sys/kernel/tracing:ro` | bind | host → container, read-only | Required for `link.Tracepoint()` to resolve tracepoint IDs at probe-attach time. Without this, probe attach trips "neither debugfs nor tracefs are mounted" and the agent degrades to `DEGRADED_PROBES_PARTIAL`. | | `/sys/fs/bpf:/sys/fs/bpf` | bind | host → container, read-write | Required when the in-process loader pins maps for cross-process sharing. Read-write because pinned-map creation requires write access. | | `/proc:/host/proc:ro` | bind | host → container, read-only | Required for process introspection when `pid: host` is set. The agent walks the host's `/proc` for the workload-discovery pass on startup. | | `/run/linuxguard:rw,mode=0700,size=10m` | tmpfs | container-only | TLS cert cache when `--tls-cache` is set. Tmpfs (not a hostPath) so cert material never reaches durable storage. | The image filesystem is `read_only: true`. The agent writes ONLY to the tmpfs and to `/tmp` (writable in the distroless base). ## Environment variables Source every value from outside the compose file itself. The compose file is a manifest you commit; the `.env` file is a manifest you do NOT commit. Together they reproduce the deployment without leaking secrets. | Variable | Source | Notes | | ------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `LINUXGUARD_ENROLL_TOKEN` | Secret store (Vault, AWS Secrets Manager, etc.) → shell → `.env` | The token. NEVER hardcode in `compose.yaml`. | | `LINUXGUARD_TENANT_ID` | Same secret store as the token | Required for the TOTP enrolment path. | | `LINUXGUARD_NODE_NAME` | `$HOSTNAME` of the host (typically) | Identifies the host; can be a stable name in your asset registry. | | `LINUXGUARD_POD_UID` | Generated once per deployment with `uuidgen` | A stable UUID. Persist in `.env` so restart-induced workload-id changes do not produce phantom enrolments. | The compose file references the `.env` values via `${VAR}` interpolation. Compose loads `.env` from the same directory as `compose.yaml` automatically. ## Security context docker-compose does not enforce Kubernetes-style Pod Security Standards. The Docker-engine equivalent is the combination of `cap_add` / `cap_drop`, `security_opt`, `read_only`, `tmpfs`, and `pid`. The compose example above sets all five: | Surface | Setting | Rationale | | --------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cap_add` | `[BPF, PERFMON, DAC_READ_SEARCH, SYS_PTRACE, SETPCAP]` | The five capabilities the file-cap transition requires. | | `cap_drop` | `[ALL]` | Defense-in-depth — drop everything not explicitly added. | | `security_opt` | `seccomp=unconfined` (UAT/dev) OR a custom profile (production) | The default Docker seccomp profile blocks `perf_event_open(2)`. | | `security_opt` (production) | `apparmor=linuxguard-agent` | Install the AppArmor profile at host level first (see [Distroless image reference § Security context](/install/install/container/distroless#security-context)). | | `read_only` | `true` | The agent does not write to the image filesystem. | | `pid` | `host` | Required for the node-level coverage shape (analogous to K8s `hostPID`). | | `tmpfs` | `/run/linuxguard` | TLS cert cache; never persists to disk. | User: the distroless image runs as `nonroot` (UID 65532) by default. docker-compose has no `user:` override needed; the image's `USER` directive applies. ## Host paths Identical to the Kubernetes DaemonSet host-path requirements — the four paths above (tracefs, BPF FS, /proc, tmpfs at /run/linuxguard). See [Kubernetes DaemonSet § Host paths](/install/install/container/kubernetes-daemonset#host-paths) for the canonical table including removability notes. > **Security Note**: All host-path mounts are read-only **except** `/sys/fs/bpf` (which requires write for pinned-map creation) and `/run/linuxguard` (which is a tmpfs). Do NOT mount the host root (`/`) — see the [anti-patterns hub section](/install/install/container#anti-patterns). ## Pod Security Standard compatibility PSS is a Kubernetes admission-control concept; it does not apply to docker-compose. The Docker-engine equivalent — capability gating, seccomp, and AppArmor — is documented in [§ Security context](#security-context) above. For deployments that need PSS classification (e.g., a multi-environment fleet where some hosts run docker-compose and others run Kubernetes), use the PSS classification from the [Kubernetes DaemonSet § Pod Security Standard compatibility](/install/install/container/kubernetes-daemonset#pod-security-standard-compatibility) table as the closest analogue. The compose example above corresponds to PSS `privileged` (because `pid: host` and the added capabilities exceed the `baseline` allowlist). ## RBAC RBAC is a Kubernetes concept; it does not apply to docker-compose. The Docker-engine equivalent is the Docker daemon's access control: any local user in the `docker` group can run `docker compose up` against the daemon, and the daemon honors the container's security context as configured. For deployments where Docker daemon access is restricted (e.g., a host where `dockerd` runs under a non-root user with `userns-remap`), the configuration is host-side, not compose-side. Verify that the user running `docker compose` has permission to map the required capabilities and bind-mount the host paths above. ## Verification After `docker compose up -d`, verify the agent is producing heartbeats: ```bash # Check the container is running and not in restart-loop. docker compose ps # Watch the log for the heartbeat line. docker compose logs --tail=50 linuxguard-agent | grep -E 'heartbeat|degraded|error' # Verify probe status. docker compose exec linuxguard-agent /usr/local/bin/linuxguard-agent probe --pretty ``` A healthy agent produces a `heartbeat` log line within 20 seconds. A degraded probe report points to a missing prerequisite — most commonly `kernel.perf_event_paranoid > 2` on the host, or a missing seccomp override. See [Kubernetes DaemonSet § Prerequisites](/install/install/container/kubernetes-daemonset#prerequisites) for the host-level fixes; they apply identically under docker-compose. ## Troubleshooting ### `OCI runtime create failed: ... operation not permitted` The most common cause: the Docker daemon's default seccomp profile is blocking `perf_event_open(2)`. Add `security_opt: [seccomp=unconfined]` for UAT/dev, or supply a custom profile for production. ### Agent exits immediately with `bootstrap ephemeral: ... none of the three were present` The Downward API env vars (`LINUXGUARD_NODE_NAME`, `LINUXGUARD_POD_UID`) are not populated, and `--workload-id` is not set. Verify the `.env` file is being loaded (`docker compose config` prints the resolved env block) and that both variables have non-empty values. ### Agent logs `400 tenantId required for TOTP enrollment` `LINUXGUARD_TENANT_ID` is missing or empty. The TOTP path requires it; long-lived API-key enrollments do not. Verify the tenant ID is set in the `.env` file and that the compose `environment:` block references it. ### `init: true` causes the agent to skip ephemeral semantics docker-compose's `init: true` makes the agent run as PID 2, not PID 1. Either remove `init: true` (recommended — the agent has its own PID-1 init shim) or set `LINUXGUARD_PID1_CHILD=1` to force ephemeral semantics. *** **Next Step**: [Podman →](/install/install/container/podman) **Related**: [Container deployment hub](/install/install/container) | [Ephemeral mode](/install/install/container/ephemeral-mode) | [Distroless image reference](/install/install/container/distroless) | [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset) | [`start` CLI reference](/reference/reference/cli/start) # Podman Deploy the LinuxGuard agent under Podman — rootless vs rootful trade-offs, systemd quadlet integration, Docker-equivalent commands. Podman is a daemonless container engine that runs containers as ordinary user processes. The LinuxGuard agent runs under Podman with two distinct trade-offs: rootful (full eBPF telemetry, ergonomically equivalent to Docker) or rootless (least-privilege execution, restricted telemetry surface). This page documents both shapes plus systemd quadlet integration for hosts where the agent should be a system service. > **Important**: **Rootless Podman cannot grant the elevated kernel-observability capabilities the agent needs** — Podman's user-namespace isolation for rootless containers does not extend those capabilities to the container's PID-1. Rootless agents run in `DEGRADED_PROBES_PARTIAL` mode — the agent process starts and produces non-eBPF telemetry, but no behavioral, auth, or file-monitor events are produced. Use rootful Podman when full telemetry coverage is required. ## When to use Podman * **Hosts where Docker daemon access is restricted** (locked-down workstations, hardened servers, multi-tenant build hosts). Podman's daemonless model fits the security posture. * **systemd-native deployments** where the agent should be a `--user` or system service managed by `systemctl`. The quadlet integration is canonical for this shape. * **RHEL / Fedora / SUSE hosts** where Podman is the supported container engine and Docker is not packaged. If your host runs Docker, the docker-compose shape ([docker-compose deployment](/install/install/container/docker-compose)) is simpler — Podman's `podman-compose` is API-compatible but has fewer eyes on it. ## Rootless vs rootful trade-offs | Property | Rootful Podman | Rootless Podman | | --------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------- | | eBPF probes | Yes (full) | **No** — user namespaces drop the agent's caps; loader degrades to `DEGRADED_PROBES_PARTIAL` | | Behavioral telemetry | Yes | **No** | | Auth events | Yes | **No** | | File monitor | Yes | **No** | | Configuration management | Yes | Yes | | Package inventory | Yes | Yes | | Syslog forwarding | Yes | Yes | | `support-bundle collect` | Yes | Yes | | Privilege required to start | `sudo podman` or member of the `podman` group | Any user; no privilege elevation | | Host filesystem visibility | Full | User-namespace remapped | | `pid=host` | Available | Available but limited to the user's own processes | | Image storage location | `/var/lib/containers/` | `~/.local/share/containers/` | **Choose rootful when** behavioral telemetry coverage is required (the standard case for a security agent). **Choose rootless when** the host's security policy forbids daemonless privileged containers AND the agent's role is limited to configuration management, package inventory, or syslog forwarding (a narrow surface). ## Rootful Podman The rootful shape is ergonomically equivalent to a Docker run with the same flags. The only difference is the engine binary. ### Minimal invocation ```bash sudo podman run -d \ --name linuxguard-agent \ --restart unless-stopped \ --pid=host \ --cap-add=BPF --cap-add=PERFMON --cap-add=DAC_READ_SEARCH \ --cap-add=SYS_PTRACE --cap-add=SETPCAP \ --security-opt seccomp=unconfined \ --tmpfs /run/linuxguard:rw,mode=0700,size=10m \ -v /sys/kernel/tracing:/sys/kernel/tracing:ro \ -v /sys/fs/bpf:/sys/fs/bpf \ -v /proc:/host/proc:ro \ --read-only \ -e LINUXGUARD_ENROLL_TOKEN="$ENROLL_TOKEN" \ -e LINUXGUARD_TENANT_ID="$TENANT_ID" \ -e LINUXGUARD_NODE_NAME="$(hostname)" \ -e LINUXGUARD_POD_UID="$(uuidgen)" \ packages.linuxguard.io/linuxguard-agent:v3.0.0 \ start --tls-cache ``` The flags match the Docker equivalent line-for-line; see [docker-compose deployment](/install/install/container/docker-compose) for the rationale on each. ### Differences from Docker * **`sudo` prefix** — rootful Podman requires either `sudo` or membership in the `podman` group. The `podman` group has no default member; add users explicitly via `usermod -aG podman `. * **No daemon to start** — Podman is daemonless. There is no `systemctl start podman` for the rootful case (the `podman.socket` unit is used only for the Docker-compatibility API). * **Image storage** — rootful Podman stores images in `/var/lib/containers/`. Free space requirements match Docker's `/var/lib/docker/`. * **SELinux labeling** — on RHEL/CentOS/Fedora hosts with SELinux enforcing, Podman applies the `container_t` type to the container's processes. Host-path mounts may require `:z` or `:Z` suffix for SELinux relabeling — see [§ SELinux considerations](#selinux-considerations). ## Rootless Podman Rootless Podman runs the container in a user namespace owned by the invoking user. Capabilities granted at `--cap-add` time are scoped to that namespace, not the host's. The agent's eBPF loader detects this at startup and degrades to `DEGRADED_PROBES_PARTIAL` mode. ### Minimal invocation (rootless) ```bash podman run -d \ --name linuxguard-agent \ --restart unless-stopped \ --tmpfs /run/linuxguard:rw,mode=0700,size=10m \ --read-only \ -e LINUXGUARD_ENROLL_TOKEN="$ENROLL_TOKEN" \ -e LINUXGUARD_TENANT_ID="$TENANT_ID" \ -e LINUXGUARD_NODE_NAME="$(hostname)" \ -e LINUXGUARD_POD_UID="$(uuidgen)" \ packages.linuxguard.io/linuxguard-agent:v3.0.0 \ start --tls-cache ``` Notes on what is OMITTED from the rootless invocation: * No `--cap-add` flags — the capabilities are scoped to the user namespace and have no effect on the host eBPF subsystem. The agent will log a startup warning about degraded mode. * No `--pid=host` — rootless Podman cannot grant host PID visibility; the agent sees only the user's own processes. * No tracefs bind-mount — without `CAP_BPF` the agent does not attempt probe attach. * No host `/proc` mount. ### Verifying degraded mode After the agent starts, the log should contain a clear degradation marker: ``` {"level":"warn","msg":"eBPF probes unavailable in this context — DEGRADED_PROBES_PARTIAL mode"} ``` If your security policy permits, switch to the rootful shape to recover the eBPF telemetry surface. Otherwise, document the rootless deployment as a known coverage gap. ## systemd quadlet integration A quadlet is a systemd unit file that describes a Podman container in a declarative, systemd-native way. Quadlets are preferred over `podman generate systemd` (which generates verbose units that mix Podman state into systemd state) because they are simpler, idempotent, and version-controlled like any other systemd unit. ### Rootful quadlet Place the following file at `/etc/containers/systemd/linuxguard-agent.container`: ```ini [Unit] Description=LinuxGuard agent (rootful) After=network-online.target Wants=network-online.target [Container] Image=packages.linuxguard.io/linuxguard-agent:v3.0.0 ContainerName=linuxguard-agent # PID 1 auto-detection inside the container. PidsLimit=2048 PodmanArgs=--pid=host AddCapability=BPF AddCapability=PERFMON AddCapability=DAC_READ_SEARCH AddCapability=SYS_PTRACE AddCapability=SETPCAP DropCapability=ALL SecurityLabelType=container_t # UAT/dev — replace with a custom profile for production. PodmanArgs=--security-opt=seccomp=unconfined ReadOnly=true Tmpfs=/run/linuxguard:rw,mode=0700,size=10m Volume=/sys/kernel/tracing:/sys/kernel/tracing:ro Volume=/sys/fs/bpf:/sys/fs/bpf Volume=/proc:/host/proc:ro # Source the token from /etc/linuxguard/enroll.env — restricted to root + linuxguard group. EnvironmentFile=/etc/linuxguard/enroll.env Exec=start --tls-cache [Service] Restart=always RestartSec=10 TimeoutStartSec=300 [Install] WantedBy=default.target ``` Generate the systemd unit and enable it: ```bash # systemd reads quadlet files on each reload; no separate `generate` step needed. sudo systemctl daemon-reload sudo systemctl enable --now linuxguard-agent.service sudo systemctl status linuxguard-agent.service ``` The `EnvironmentFile=/etc/linuxguard/enroll.env` references a file with the token + tenant ID: ``` # /etc/linuxguard/enroll.env — chmod 0640, owned by root:linuxguard LINUXGUARD_ENROLL_TOKEN= LINUXGUARD_TENANT_ID= LINUXGUARD_NODE_NAME= LINUXGUARD_POD_UID= ``` Restrict permissions on the env file: ```bash sudo install -d -m 0750 -o root -g linuxguard /etc/linuxguard sudo install -m 0640 -o root -g linuxguard /dev/null /etc/linuxguard/enroll.env sudo $EDITOR /etc/linuxguard/enroll.env # populate with the token + tenant ``` Only root and the `linuxguard` group can read the env file. systemd reads it as root when the service starts; the value is then injected into the container's environ block via Podman. ### Rootless quadlet Place the file at `~/.config/containers/systemd/linuxguard-agent.container` (note the user-scoped path): ```ini [Unit] Description=LinuxGuard agent (rootless) After=default.target [Container] Image=packages.linuxguard.io/linuxguard-agent:v3.0.0 ContainerName=linuxguard-agent ReadOnly=true Tmpfs=/run/linuxguard:rw,mode=0700,size=10m EnvironmentFile=%h/.config/linuxguard/enroll.env Exec=start --tls-cache [Service] Restart=always RestartSec=10 [Install] WantedBy=default.target ``` Enable as a user service: ```bash # Reload the user-systemd generator so the quadlet is picked up. systemctl --user daemon-reload systemctl --user enable --now linuxguard-agent.service systemctl --user status linuxguard-agent.service # Enable lingering so the user service persists across logout. loginctl enable-linger "$USER" ``` The rootless quadlet inherits the same degradation properties as the rootless `podman run` invocation — see [§ Rootless Podman](#rootless-podman). ## Docker-equivalent commands For operators familiar with Docker, the table below maps common workflows to their Podman equivalents. The agent's behavior is identical under either engine. | Docker | Podman | Notes | | ------------------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------ | | `docker run ...` | `podman run ...` | Identical syntax. Rootful Podman requires `sudo`. | | `docker compose up -d` | `podman-compose up -d` | `podman-compose` is a Python wrapper; install with `pip install podman-compose` or via distro package. | | `docker ps` | `podman ps` | Identical. | | `docker logs -f linuxguard-agent` | `podman logs -f linuxguard-agent` | Identical. | | `docker exec linuxguard-agent ` | `podman exec linuxguard-agent ` | Identical. The distroless image has no shell; pass a specific command. | | `docker stop linuxguard-agent` | `podman stop linuxguard-agent` | Identical. Sends SIGTERM; agent exits 143. | | `docker pull ` | `podman pull ` | Identical. | | `docker login ` | `podman login ` | Identical. Credentials stored in `~/.config/containers/auth.json`. | | `docker inspect ` | `podman inspect ` | Identical output structure. | | `docker system df` | `podman system df` | Identical. | ## SELinux considerations On RHEL / CentOS / Fedora / Rocky Linux hosts with SELinux enforcing, Podman applies the `container_t` type to processes inside the container. Host-path mounts must be relabeled or the agent's reads from `/sys/kernel/tracing` are denied with `avc: denied`. Two options: ### Option 1: `:z` / `:Z` mount suffix Append `:z` (shared label) or `:Z` (private label) to the `-v` flag value. This is the simplest approach for single-host deployments: ```bash -v /sys/kernel/tracing:/sys/kernel/tracing:ro,z ``` `:z` relabels the host directory so the container can read it AND other containers can read it (shared). `:Z` relabels for exclusive access by this one container. For `/sys/kernel/tracing` (a kernel pseudo-filesystem, not real disk), `:z` is appropriate. ### Option 2: Set the agent's SELinux profile at host level Install the SELinux policy that ships with the agent's packaging tree, then label the agent's process with the policy's domain: ```bash sudo semodule -i /usr/share/linuxguard/selinux/linuxguard-agent.pp sudo semanage fcontext -a -t linuxguard_agent_exec_t '/usr/local/bin/linuxguard-agent' sudo restorecon -v /usr/local/bin/linuxguard-agent ``` This is the production path. It avoids the `:z` / `:Z` relabel side effect on host directories. ### Verifying SELinux is not blocking ```bash sudo ausearch -m AVC -ts recent | grep linuxguard ``` If recent AVC denials appear, set SELinux to permissive temporarily to confirm the agent works in the absence of policy enforcement: ```bash sudo setenforce 0 podman logs linuxguard-agent | grep heartbeat sudo setenforce 1 ``` Then apply Option 1 or Option 2 to allow the agent under enforcing mode. ## Security context The rootful Podman security context is equivalent to the Kubernetes DaemonSet shape — see [Kubernetes DaemonSet § Line-by-line rationale](/install/install/container/kubernetes-daemonset#line-by-line-rationale) for the per-capability rationale. The rootless Podman security context inherits the user namespace's degradation as documented in [§ Rootless vs rootful trade-offs](#rootless-vs-rootful-trade-offs). Common to both: `read_only` filesystem, tmpfs for the TLS cache, no privilege escalation needed (file caps baked into the binary), `nonroot` user (UID 65532 inside the container, remapped to a high UID range in the rootless case). ## Host paths Identical to the Kubernetes DaemonSet host-path requirements for the rootful case — see [Kubernetes DaemonSet § Host paths](/install/install/container/kubernetes-daemonset#host-paths). The rootless case omits the host-path mounts entirely because the user namespace cannot productively use them. > **Security Note**: For SELinux-enforcing hosts, mount each host path with `:z` (or apply the SELinux module per Option 2 above). For the rootless case, do not mount host paths — the user namespace cannot use them. ## Pod Security Standard compatibility PSS is a Kubernetes concept; it does not apply to Podman. The Podman equivalent is the combination of `--cap-add` / `--cap-drop`, `--security-opt`, `--read-only`, `--tmpfs`, `--pid`, and the rootful-vs-rootless distinction. The rootful Podman shape corresponds to PSS `privileged` (because of `--pid=host` and the added capabilities); the rootless shape has no Kubernetes analogue. ## RBAC RBAC is a Kubernetes concept; it does not apply to Podman. The Podman equivalent is filesystem access control on the Podman binary and the user namespace: * **Rootful** — access is controlled by `sudo` policy or `podman` group membership. Restrict membership to trusted users. * **Rootless** — access is per-user. The Podman binary itself is unprivileged; the user namespace determines what the container can see. For the quadlet integration, systemd's unit-file permissions (`/etc/containers/systemd/` for rootful, `~/.config/containers/systemd/` for rootless) control who can modify the agent's deployment manifest. ## Verification After starting the agent (via `podman run`, `podman-compose`, or the quadlet service): ```bash # Confirm the container is running. podman ps --filter name=linuxguard-agent # Watch the log for the heartbeat line (rootful — expect heartbeat). podman logs --tail=50 linuxguard-agent | grep -E 'heartbeat|degraded|error' # Rootless — expect the DEGRADED_PROBES_PARTIAL warning. # This is normal for rootless; do NOT treat it as an error. # Verify probe status. podman exec linuxguard-agent /usr/local/bin/linuxguard-agent probe --pretty ``` A healthy rootful agent produces a `heartbeat` log line within 20 seconds. A degraded rootless agent produces the degradation warning, then a heartbeat with the reduced telemetry surface. *** **Next Step**: [OCI multi-arch manifest →](/install/install/oci-multi-arch-manifest) **Related**: [Container deployment hub](/install/install/container) | [docker-compose deployment](/install/install/container/docker-compose) | [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset) | [Distroless image reference](/install/install/container/distroless) | [`probe` CLI reference](/reference/reference/cli/probe) # OCI multi-arch manifest OCI multi-arch manifest for the LinuxGuard agent container image — docker manifest inspect output, supported platforms, image digest stability, and per-platform pull syntax. The LinuxGuard agent container image is published as a single multi-platform OCI manifest. Pulling `packages.linuxguard.io/linuxguard-agent:v3.0.0` from an amd64 host produces a different image digest than pulling the same tag from an arm64 host — but both digests are catalogued by the same manifest list, and operators can pin to either the multi-arch tag (host-architecture resolution) or to a per-platform digest (reproducibility). > **Important**: The multi-arch manifest covers `linux/amd64` and `linux/arm64` (full eBPF telemetry) plus `linux/arm/v7` (binary published; eBPF telemetry unavailable — the agent runs in a reduced-telemetry mode instead). RISC-V (`linux/riscv64`) is best-effort and may or may not be present in the manifest depending on the release build. See [Multi-Architecture Support](/install/install/multi-architecture) for the per-architecture capability matrix. ## Inspecting the manifest The OCI manifest list is inspected with `docker manifest inspect` (Docker 19.03+) or `podman manifest inspect`. The output enumerates every platform that resolves under the tag. ```bash docker manifest inspect packages.linuxguard.io/linuxguard-agent:v3.0.0 ``` Sample output (abbreviated): ```json { "schemaVersion": 2, "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json", "manifests": [ { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "size": 1234, "digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "platform": { "architecture": "amd64", "os": "linux" } }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "size": 1234, "digest": "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "platform": { "architecture": "arm64", "os": "linux", "variant": "v8" } }, { "mediaType": "application/vnd.docker.distribution.manifest.v2+json", "size": 1234, "digest": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "platform": { "architecture": "arm", "os": "linux", "variant": "v7" } } ] } ``` Each entry in `manifests` is a per-platform image manifest. The `digest` field is the immutable SHA-256 of THAT platform's image bytes — different from the tag-level digest (`docker pull` reports the platform digest, not the manifest-list digest). ## Supported platforms The platforms below resolve under `packages.linuxguard.io/linuxguard-agent:vX.Y.Z` for current releases. Verify against the live manifest before relying on any specific platform — the manifest is the source of truth. | Platform string | `uname -m` | Image content | eBPF telemetry | | ---------------- | --------------------------- | -------------------------------------------------------- | ------------------------------------------------- | | `linux/amd64` | `x86_64` | Statically-linked agent binary + compiled `probes.bpf.o` | Full | | `linux/arm64/v8` | `aarch64` | Statically-linked agent binary + compiled `probes.bpf.o` | Full | | `linux/arm/v7` | `armv7l` / `armv6l` / `arm` | Statically-linked agent binary; no eBPF probe | **None** — agent runs in a reduced-telemetry mode | | `linux/riscv64` | `riscv64` | Best-effort — depends on the release build's toolchain | Conditional — verify per release | **Not in the manifest:** * `linux/s390x` — agent binary may build but is unverified for container deployment. Surface unsupported in v4.0. * `linux/ppc64le` — same as s390x. * `windows/*` — not supported; the agent is Linux-only. * `darwin/*` — not supported; the agent is Linux-only. ## How pull-time platform resolution works When you run `docker pull packages.linuxguard.io/linuxguard-agent:v3.0.0` on a host without an explicit `--platform` flag, Docker: 1. Fetches the manifest list (the JSON document shown above). 2. Reads the host's architecture from `runtime.GOARCH` (which Docker's daemon obtains at startup). 3. Selects the matching `manifests[i].platform` entry. 4. Pulls THAT entry's image bytes by digest. 5. Reports the per-platform digest as the pulled image's digest. The same tag therefore produces different digests on different host architectures. This is by design — operators on heterogeneous fleets pin to the **tag** (e.g., `:v3.0.0`) and trust the manifest list to resolve per-host. Operators who require byte-identical deployments across the fleet pin to a specific per-platform digest (see [§ Pinning to a digest](#pinning-to-a-digest)). ## Per-platform pull syntax To pull a specific platform on a host whose native architecture differs (e.g., pulling an arm64 image on an amd64 build host for cross-architecture testing), use the `--platform` flag: ```bash # Pull the amd64 variant explicitly, regardless of host architecture. docker pull --platform linux/amd64 packages.linuxguard.io/linuxguard-agent:v3.0.0 # Pull the arm64 variant explicitly. docker pull --platform linux/arm64 packages.linuxguard.io/linuxguard-agent:v3.0.0 # Pull the ARMv7 variant (Degraded mode). docker pull --platform linux/arm/v7 packages.linuxguard.io/linuxguard-agent:v3.0.0 ``` Podman accepts the same flag with identical syntax: ```bash podman pull --platform linux/arm64 packages.linuxguard.io/linuxguard-agent:v3.0.0 ``` Pulling a platform that does NOT exist in the manifest list (e.g., `--platform linux/riscv64` when RISC-V is absent from the current release) produces: ``` no matching manifest for linux/riscv64 in the manifest list entries ``` Verify against `docker manifest inspect` first if you are not sure whether your target platform is present. ## Pinning to a digest The multi-arch tag (`:v3.0.0`) is convenient but produces different bytes per host architecture. For reproducibility — incident replay, audit trails, byte-identical deployments — pin to a specific per-platform digest: ```bash docker pull packages.linuxguard.io/linuxguard-agent@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa ``` The digest above is the `manifests[i].digest` value from the manifest-list inspection. Pinning to a digest: * Is reproducible — the same digest always resolves to the same bytes. * Is platform-specific — an `amd64` digest cannot be pulled on an `arm64` host (Docker will not auto-substitute). * Survives tag re-publishing — if a `:v3.0.0` tag is moved to point at a different manifest list, the digest pin still resolves to the original bytes (until the registry garbage-collects them). For multi-platform digest pinning across a heterogeneous fleet, pin one digest per platform and select per-host at deploy time: ```yaml # Example for a Kubernetes Deployment matrix (Helm values, abbreviated) linuxguard: image: amd64: packages.linuxguard.io/linuxguard-agent@sha256:aaaa... arm64: packages.linuxguard.io/linuxguard-agent@sha256:bbbb... ``` Refresh the digests on each release. Pinning to a digest indefinitely deprives the cluster of upgrades — establish a cadence (e.g., re-pin on every minor release). ## Pinning to the manifest-list digest For tooling that prefers a single digest across all platforms, pin to the manifest list itself rather than to a per-platform manifest. The manifest-list digest is also reported by `docker manifest inspect` and `crane digest`: ```bash crane digest packages.linuxguard.io/linuxguard-agent:v3.0.0 # sha256:LLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLLL ``` The manifest-list digest is stable for the tag — re-publishing the tag with new platform images changes the manifest-list digest. Pinning to it gives you: * One digest across all platforms (heterogeneous fleets pin once). * Reproducibility — the manifest list is immutable once published. * Auto-platform resolution at pull time (Docker still picks the matching platform). The trade-off: when a new minor release is published, the manifest-list digest changes. You pin to a specific manifest list, not to a specific binary; updates require re-pinning. ## Image digest stability Per-platform digests and manifest-list digests are **immutable**: * A given digest always resolves to the same bytes on the same registry. * Re-publishing a tag does NOT modify the digest of the prior manifest list — it creates a new manifest list with a new digest and updates the tag-to-digest mapping. * The registry MAY garbage-collect unreferenced digests (no tag points at them); this is registry policy. Pin to a digest of a tagged release if you need long-term retention guarantees. The `packages.linuxguard.io` registry retains tagged release digests indefinitely. Untagged or development digests may be GC'd. If you pin to a digest, verify that the digest is referenced by at least one tag at the time of pinning. ### Verifying the signed digest Each per-platform manifest is signed at release time via cosign. Verify the signature on the digest you intend to deploy: ```bash cosign verify \ --certificate-identity 'https://github.com/linuxguardx/linuxguard-agent/.github/workflows/release.yaml@refs/tags/v3.0.0' \ --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \ packages.linuxguard.io/linuxguard-agent@sha256:aaaa... ``` The signature verifies the digest as produced by the LinuxGuard release pipeline. A successful verification prints the certificate's subject and the Rekor transparency-log index. A failed verification means either the digest was not produced by the release pipeline (typosquatted registry, repository compromise) or the signature record is corrupt — do NOT deploy. ## Cross-platform considerations ### QEMU vs native builds Multi-architecture OCI images produced via QEMU emulation may pass the build but exhibit different runtime characteristics on native hardware. Specifically: * **Kernel-version differences** — a QEMU build target may have built against a different host kernel than what the deployment target runs. eBPF helper availability is kernel-specific; the build's BTF resolution may select helpers that the deployment kernel does not support. * **CPU feature drift** — QEMU emulates a baseline CPU; native hardware may have additional instructions the binary was not built to use, OR may lack instructions the binary assumes (rare for the agent's static build, but possible for non-standard ARM SoCs). Always run a `linuxguard-agent probe` on a representative target host before relying on a multi-arch image in production. The probe reports kernel, BPF, fanotify, netlink, audit, and capability availability for the running environment — if the probe degrades, the image does not match the kernel. ### Cross-architecture pulls on Apple Silicon macOS hosts running Docker Desktop on Apple Silicon (M-series CPUs) default to `linux/arm64/v8` when pulling Linux images. To pull the `amd64` variant (for build pipelines that target x86 deployment): ```bash docker pull --platform linux/amd64 packages.linuxguard.io/linuxguard-agent:v3.0.0 ``` The image runs under QEMU emulation. Performance is degraded; use this only for build / test workflows, not for production. ### Architecture-specific Docker Hub mirroring If your environment mirrors `packages.linuxguard.io` to an internal registry, mirror **by digest** rather than by tag. Mirroring by tag re-publishes only the active platform's image; the manifest list is lost. Use `crane copy` (which preserves manifest lists) rather than `docker pull` + `docker push` (which does not): ```bash crane copy \ packages.linuxguard.io/linuxguard-agent:v3.0.0 \ registry.example.internal/mirror/linuxguard-agent:v3.0.0 ``` `crane copy` preserves the full manifest list including all platform variants and signatures. ## ARMv7 special handling The ARMv7 variant (`linux/arm/v7`) ships the agent binary, but eBPF probe support is not available on this architecture. The agent detects this automatically at startup and continues running in a reduced-telemetry mode rather than failing to start. The agent then runs without eBPF — no behavioral telemetry, no auth events, no eBPF-derived file monitor. The agent does continue to provide configuration management, package inventory, syslog forwarding, and support-bundle collection. If your compliance posture depends on continuous behavioral telemetry, ARMv7 deployments will NOT contribute that evidence. Treat ARMv7 hosts as a documented gap in the evidence chain — see [Multi-Architecture Support § Operational Notes § Compliance Implications](/install/install/multi-architecture#compliance-implications). ## Cross-references * [Multi-Architecture Support](/install/install/multi-architecture) — the per-architecture capability matrix and degradation modes. * [Container deployment hub](/install/install/container) — orchestrator-specific deployment shapes that consume this manifest. * [Distroless image reference](/install/install/container/distroless) — what is in each platform's image bytes. * [Per-distribution architecture support](/install/install/multi-architecture#per-distribution-architecture-support) — per-distro architecture availability for the package-based install paths. *** **Next Step**: [Container deployment hub →](/install/install/container) **Related**: [Multi-Architecture Support](/install/install/multi-architecture) | [Distroless image reference](/install/install/container/distroless) | [Container deployment hub](/install/install/container) | [Supported Distributions](/reference/reference/supported-distributions) # Configure Enroll the LinuxGuard agent to your tenant and set group, tag, and environment flags so it starts sending telemetry to the console. After installing the LinuxGuard agent, you need to configure it to connect to your tenant and start sending telemetry data to the LinuxGuard console. > **Note**: For container deployments, see the [Container Installation Guide](/install/install/container) which includes container-specific enrollment instructions. ## What's in this section Configure content is authored across upcoming phases of the v4.0 milestone. The forthcoming child pages are: * **Agent configuration reference** — config keys, `config set`/`get`/`unset` subcommands, toggleable keys (Phase 17). * **Log level and rotation** — `log_level` management, lumberjack defaults, runtime SIGHUP reload (Phase 19). * **Enrollment flag handling** — `--api-key`, `--tenant-id`, `--environment`, `--group` backward-compat alias, `--tag` (Phase 17). The enrollment procedure below covers the day-1 setup until those references land. ## Enrollment The agent is enrolled using the `enroll` command, which connects the agent to your tenant account. You'll need two pieces of information: * **API Key**: A secure key for authenticating the agent * **Tenant ID**: Your unique tenant identifier ### Enrollment Command Run the following command on your system: ```bash sudo linuxguard-agent enroll --api-key= --tenant-id= ``` Replace: * `` with your actual API key * `` with your tenant ID ### Example ```bash sudo linuxguard-agent enroll --api-key=ak_1234567890abcdef --tenant-id=tenant_abc123xyz ``` ### Optional Enrollment Flags You can specify additional options during enrollment: ### Server Group Assignment Assign the server to a group during enrollment: ```bash sudo linuxguard-agent enroll \ --api-key=ak_1234567890abcdef \ --tenant-id=tenant_abc123xyz \ --group=production-servers ``` > **Note**: Each server can only belong to one group. Groups can be managed in the LinuxGuard console. ### Server Tags Apply tags to the server during enrollment. Tags can be used for filtering and organizing servers. You can specify multiple tags by repeating the `--tag` flag: ```bash sudo linuxguard-agent enroll \ --api-key=ak_1234567890abcdef \ --tenant-id=tenant_abc123xyz \ --tag=web-server \ --tag=us-east-1 \ --tag=critical ``` ## Finding Your Credentials ### Tenant ID You can find your Tenant ID in two places: 1. **Initial Email**: The Tenant ID was included in the email you received when your tenant was created 2. **Console Settings**: Navigate to the **Settings** page in the LinuxGuard console to view your Tenant ID ### API Key To generate an API key: 1. Log in to the LinuxGuard console 2. Navigate to the **Settings** page 3. Find the **API Keys** section 4. Click **Generate New API Key** 5. Copy the generated key (you won't be able to see it again after closing the dialog) > **Security Note**: Keep your API keys secure and never share them publicly. Each API key can be revoked and regenerated from the Settings page if needed. ## Successful Enrollment If the enrollment is successful, you will see a confirmation message: ``` Successfully enrolled to LinuxGuard Endpoint: https://api.linuxguard.io/v1/ ``` After successful enrollment, the agent will: * Start collecting telemetry data from your system * Send data to the LinuxGuard console * Appear in your console's agent list ## Troubleshooting Enrollment If you encounter any errors during enrollment: 1. Verify your API key and Tenant ID are correct 2. Check your network connectivity to `https://api.linuxguard.io` 3. Review the agent logs (see [Troubleshooting](/troubleshooting)) *** **Next Step**: [Quick Start →](/get-started/get-started/quick-start) **Related**: [Agent Commands](/reference/reference/agent-commands) | [Uninstallation](/operate/operate/uninstallation) | [Troubleshooting](/troubleshooting) # Log Level and Rotation LinuxGuard agent log rotation defaults, configurable knobs, and runtime log level management via config set + SIGHUP reload. This page covers the operator-facing knobs for the LinuxGuard agent's log file: the rotation defaults, the four configurable rotation fields, the strict wire format for log levels, and the runtime reload flow via `config set log_level` + SIGHUP. For redaction scope and rate-limiting behavior, see [Log Management](/operate/operate/log-management). ## Log Rotation Defaults The agent uses the [lumberjack](https://github.com/natefinch/lumberjack) rotator to manage `/var/log/linuxguard/agent.log`. Defaults are verified against the agent source: | Field | Default | Behavior | | -------------- | ------------------- | -------------------------------------------------------------------------------------------- | | `max_size_mb` | 50 MB max file size | When the active log file reaches this size, it is rotated and a new file is opened. | | `max_age_days` | 14-day retention | Rotated backup files older than this are pruned at the next rotation event. | | `max_backups` | 5 backups | At most this many rotated files are retained; older backups are pruned at the next rotation. | | `compress` | gzip compression | Rotated backup files are gzip-compressed and named `agent.log..gz`. | Worst-case live + backup footprint under defaults: approximately 75 MB on disk (50 MB live file + ≈25 MB compressed backups). The `max_size_mb` default is the only field with a built-in fallback at the lumberjack bridge layer (size=0 has no useful lumberjack meaning). The 14-day / 5-backup / gzip-on defaults are applied one layer up in `config.GetLoggingConfig` — operators who pass a zero-valued configuration explicitly get "no age pruning, retain all backups, no compression" rather than the legacy defaults. ## Configurable Rotation Knobs All four rotation fields are configurable via `linuxguard-agent config set logging. `. Validation is enforced by the agent runtime. | Key | Type | Valid range | Notes | | ---------------------- | ---- | ---------------------------- | ------------------------------------------ | | `logging.max_size_mb` | int | 1 – 10000 | Cannot be 0; min 1 MB. | | `logging.max_age_days` | int | 0 – 3650 | 0 means never delete rotated files by age. | | `logging.max_backups` | int | 0 – 100 | 0 means retain all rotated files. | | `logging.compress` | bool | `true` / `false` / `1` / `0` | gzip-compress rotated backup files. | ### Setting a Rotation Knob ```bash sudo linuxguard-agent config set logging.max_size_mb 100 sudo linuxguard-agent config set logging.max_age_days 30 sudo linuxguard-agent config set logging.max_backups 10 sudo linuxguard-agent config set logging.compress true ``` After changing a rotation knob, restart the agent service to pick up the new rotation configuration: ```bash sudo systemctl restart linuxguard-agent ``` Rotation configuration is not re-read on SIGHUP — only log level is reloaded via SIGHUP. See **Log Level Management** below. ## Log Level Management ### Wire Format (Strict Lowercase) The agent enforces a strict lowercase wire format for log levels across every external surface (config file, ack envelope, CLI flag, audit log row). Valid log levels: ``` trace debug info warn error ``` Uppercase variants (`DEBUG`, `INFO`), integer representations, and the empty string are rejected with a descriptive error. There is no `strings.ToLower` normalization — the wire format is strict. ### Performance Impact Per Level | Level | Typical use | Rate-limited | Performance impact | | ------- | ---------------------------------- | -------------------- | ----------------------------------------------------- | | `trace` | Deep diagnostic; off in production | Yes (1000/s default) | Highest cost; can be heavy on disk and CPU under load | | `debug` | Debugging individual subsystems | Yes (500/s default) | Significant overhead under steady load | | `info` | Operator-visible lifecycle events | No | Default production level; low overhead | | `warn` | Recoverable degradations | No | Minimal overhead | | `error` | Operator action required | No | Minimal overhead | TRACE and DEBUG are rate-limited to protect the rotation file under bursty load — see [Log Management § Rate Limiting](/operate/operate/log-management#rate-limiting-and-drop-summaries). ### Persisting a New Log Level + SIGHUP Reload Flow The `config set log_level ` subcommand performs three actions atomically: 1. Validates the level against the strict lowercase wire format. 2. Persists the new level to the agent's local config database. 3. Sends SIGHUP to the running agent process so the new level takes effect without a service restart. ```bash sudo linuxguard-agent config set log_level debug ``` The SIGHUP handler re-reads the config, resolves the new log level, and updates the live slog level. An INFO line `"SIGHUP reload: log level updated"` is emitted on success. If you need to send SIGHUP manually (e.g., after editing the config file directly): ```bash sudo systemctl kill -s HUP linuxguard-agent.service ``` ### Clearing a Persisted Log Level To remove the local pin and revert to the backend-ack-delivered or tenant-default level: ```bash sudo linuxguard-agent config unset log_level ``` `config unset` is supported ONLY for `log_level` — identity fields (api\_key, tenant\_id) are not unsettable via the CLI. ## logrotate Integration The agent ships a packaged logrotate fragment at `/etc/logrotate.d/linuxguard` matching the following template. ``` /var/log/linuxguard/agent.log { missingok notifempty sharedscripts create 0640 linuxguard linuxguard postrotate /bin/kill -HUP $(cat /var/run/linuxguard/agent.pid 2>/dev/null) 2>/dev/null || true endscript } ``` ### How logrotate Coexists With Lumberjack The agent uses lumberjack for in-process rotation, AND it ships the logrotate fragment above so external rotation tooling can drive rotation alongside the in-process rotator. The `postrotate` SIGHUP signals the agent to close and reopen its log file descriptor — implementing the external-rotation close+reopen semantics in the agent runtime. The agent's SIGHUP handler calls `Rotate()` on the active lumberjack rotator to perform the close+reopen on the lumberjack-managed file. The same SIGHUP also triggers log-level reload via a separate handler — both handlers run on every SIGHUP because `signal.Notify` broadcasts the signal to both channels independently. ### Per-Distribution logrotate Behavior | Distribution | logrotate timer | Notes | | --------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------- | | Debian / Ubuntu | systemd `logrotate.timer` (default daily) | Standard daily rotation; fragment in `/etc/logrotate.d/linuxguard`. | | RedHat / CentOS | systemd `logrotate.timer` (default daily) | Standard daily rotation; fragment in `/etc/logrotate.d/linuxguard`. | | SUSE / openSUSE | systemd `logrotate.timer` (default daily) | Standard daily rotation; fragment in `/etc/logrotate.d/linuxguard`. | | Alpine | OpenRC `crond` + logrotate cron job | Daily cron via `/etc/periodic/daily/logrotate`; fragment under `/etc/logrotate.d/linuxguard`. | ## Examples ### Verify Current Rotation Config ```bash sudo linuxguard-agent show-config | grep -E 'logging\.' ``` ### Enable Verbose Debug Logging Temporarily ```bash sudo linuxguard-agent config set log_level debug # diagnose, capture logs, then revert: sudo linuxguard-agent config set log_level info ``` ### Increase Rotation Size and Retention ```bash sudo linuxguard-agent config set logging.max_size_mb 200 sudo linuxguard-agent config set logging.max_age_days 30 sudo linuxguard-agent config set logging.max_backups 10 sudo systemctl restart linuxguard-agent ``` ### Disable Compression on Rotated Backups ```bash sudo linuxguard-agent config set logging.compress false sudo systemctl restart linuxguard-agent ``` Note: Disabling compression increases on-disk footprint by approximately 3-5x per backup file. ## Cross-References * [Log Management](/operate/operate/log-management) — Redaction scope, rate limiting, central log collection patterns. * [Support Bundles](/operate/operate/support-bundles) — Bundle contents and per-file redaction status. *** **Related**: [Log Management](/operate/operate/log-management) | [Support Bundles](/operate/operate/support-bundles) | [Troubleshooting](/troubleshooting) # Operate Day-2 operations for the LinuxGuard agent — service management, log inspection, signal handling, support bundles, and uninstall. Day-2 operations for SREs running LinuxGuard in production: service management, log inspection and rotation, signal handling, support bundles, and uninstall procedures. ## What's in this section * [**Uninstallation**](/operate/operate/uninstallation) — Uninstall the LinuxGuard agent from a Linux host — package removal, config cleanup, and de-enrollment. # 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](/configure/configure/log-level-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](/operate/operate/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](/respond/respond/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](/configure/configure/log-level-rotation) — Operational knobs: rotation defaults, `log_level` SIGHUP reload, logrotate sample. * [Support Bundles](/operate/operate/support-bundles) — Per-file redaction status table for the support bundle. * [Syslog Forwarding](/respond/respond/syslog-forwarding) — Forwarding agent logs to remote syslog endpoints. *** **Related**: [Log Level and Rotation](/configure/configure/log-level-rotation) | [Support Bundles](/operate/operate/support-bundles) | [Syslog Forwarding](/respond/respond/syslog-forwarding) | [Troubleshooting](/troubleshooting) # Support Bundles Support bundle collection and upload — pre-share PII warning, per-file redaction status, 180 MB cap, presigned S3 upload flow, and decision tree for when to collect. The `support-bundle` subcommand collects an agent diagnostic archive intended for sharing with LinuxGuard support staff. This page documents the bundle's contents, the redaction status of each file, the 180 MB pre-compression cap with oldest-first trimming, and the presigned S3 upload flow. > **⚠ Pre-share PII Warning**: Support bundles ship `agent.log` and rotated segments verbatim up to 180 MB. Only attribute-key-format secrets (API keys, enrollment tokens) are redacted. **Hostnames, IPs, usernames, file paths, and command-line arguments are NOT redacted.** Review the bundle contents before sharing externally. ## Synopsis A support bundle is a `.tar.zst` archive containing: * The current `agent.log` plus any rotated `.gz` segments that fit within the cap * A `system.json` host snapshot (kernel, eBPF probe status, agent version, host arch) * A `config.redacted.json` view of the agent config with secrets replaced by SHA256 fingerprints * A `BUNDLE-MANIFEST.json` listing every file in the archive, what was trimmed, and the redaction summary Bundles are produced via `linuxguard-agent support-bundle collect` and shared with LinuxGuard support via `linuxguard-agent support-bundle upload ` (presigned S3 upload) or via the console Support Bundles UI. ## Per-file Redaction Status The table below lists every file the agent places in the bundle, what is redacted, and what is NOT redacted. | File | What's redacted | What's NOT redacted | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `agent.log` | Attribute-key regex only — `api_key`, `enroll_token`, `*_token`, `*_secret` keys replaced with `[REDACTED]` per the agent's log redactor | **Hostnames, IPs, usernames, file paths, process command-line arguments, free-text message bodies. PII NOT additionally redacted.** | | `agent.log..gz` | Same as `agent.log` — attribute-key regex only | Same as `agent.log` — PII not additionally redacted | | `system.json` | Nothing — system metadata only (kernel version, BPF probe status, agent version, host architecture) | Kernel version, host arch, agent version, eBPF probe status, recent error count | | `config.redacted.json` | Secrets replaced with `>` fingerprints; TLS material replaced with ``. Explicit struct mapping in the bundle redactor — `api_key`, `enroll_token`, `encryption_key`, `*_token`, `*_secret`, `*_password`, `*_key`, `*_cert`, `*_cert_pem`, `*_key_pem`, `tls_cert`, `tls_key_pem` | Server ID, Tenant ID, base URL, mode, environment, tags, feature flags, cert/key file paths (paths only — content stays on disk) | | `BUNDLE-MANIFEST.json` | Nothing — manifest is metadata only | Bundle version, agent version, generated-at, trigger, contents list, trimmed segments, redaction summary | ### Verifying Redaction Rules From the Bundle Every bundle includes a `redaction_summary` block in `BUNDLE-MANIFEST.json` so operators can verify the rules without re-reading documentation: ```json { "redacted_keys": ["api_key", "enroll_token", "encryption_key"], "glob_patterns": ["*_token", "*_secret", "*_password", "*_key"], "tls_patterns": ["*_cert", "*_cert_pem", "*_key_pem", "tls_cert", "tls_key_pem"], "format": ">", "tls_format": "", "strategy": "explicit_struct_mapping", "reflection_used": false } ``` The `strategy: explicit_struct_mapping` field is load-bearing — the config redaction uses a hand-maintained struct mapping, NOT reflection. Adding a new secret field to the agent config requires a code change in the bundle redaction layer, not a documentation update. ## Collect Workflow ### Default Behavior ```bash sudo linuxguard-agent support-bundle collect ``` The default behavior: * Writes the bundle to `/var/lib/linuxguard/support/.tar.zst` * Caps the included `agent.log` + rotated `.gz` segments at **180 MB pre-compression** * Applies **oldest-first trimming**: when the cap is reached, the oldest rotated segment is dropped; current `agent.log` is always included * Emits the bundle's SHA256 hex digest and size in bytes to stderr * Stores the trimmed-segment list inside `BUNDLE-MANIFEST.json` for operator visibility ### Custom Output Path ```bash sudo linuxguard-agent support-bundle collect --out /tmp/my-bundle.tar.zst ``` The output file is opened with `O_EXCL` to mitigate symlink attacks. If the destination already exists, the command fails with a clear error rather than overwriting. ### What's Collected | Item | Behavior | | -------------------------- | ------------------------------------------------------------------------------ | | Current `agent.log` | Always included; non-fatal if absent (fresh agent) | | Rotated `agent.log..gz` | Newest first; trimmed to fit the 180 MB cap; trimmed list recorded in manifest | | `system.json` | Always included; required entry | | `config.redacted.json` | Always included; required entry | | `BUNDLE-MANIFEST.json` | Always included last; required entry | The cap counts the current `agent.log` size against the budget before deciding which rotated segments fit. When the cap budget is exhausted, the remaining rotated segments are dropped and their base names are recorded in the manifest's `trimmed_segments` array (never `null`; empty array if no trimming occurred). ### Sample Output ``` support-bundle: wrote /var/lib/linuxguard/support/1735660800.tar.zst support-bundle: sha256=a1b2c3d4...e5f6 size=42184326 support-bundle: trimmed_segments=2 ``` ## Upload Workflow The `upload` subcommand pushes a previously-collected bundle to LinuxGuard support via a three-step presigned URL flow. ```bash sudo linuxguard-agent support-bundle upload /var/lib/linuxguard/support/1735660800.tar.zst ``` ### Flow 1. **Stat + SHA256** — the CLI re-computes the SHA256 of the bundle on disk and stats its size. 2. **Extract manifest** — the CLI reads `BUNDLE-MANIFEST.json` from the archive to recover the `trimmed_segments` and `agent_version` fields (non-fatal if the manifest is missing). 3. **Request presigned URL** — the agent POSTs to `/upload-url` with bundle metadata (SHA256, size, kernel, distro, agent version, eBPF status, recent error count). The backend returns a presigned S3 PUT URL. 4. **PUT to S3** — the agent uploads the bundle bytes via the presigned URL using a raw HTTP request (no Authorization header — auth is in the URL signature). 5. **Register** — the agent POSTs to `/register` with the upload result so the backend records the bundle in its database and exposes it to support engineers. ### Sample Output ``` uploaded bundle_id=bnd_abc123 object_key=tenants//bundles/1735660800.tar.zst uploaded_at=2026-05-31T12:00:00Z ``` On upload failure, the local bundle file is retained — the upload command does not delete it. Operators can re-run the upload command against the same file once connectivity is restored. ### Authentication The `/upload-url` and `/register` endpoints require the agent's standard API key authentication. The presigned PUT to S3 carries its own URL-encoded signature and does NOT require the API key. ### Data Residency The S3 bucket is provisioned in the LinuxGuard tenant's primary region per the tenant's data-residency configuration. Bundles are retained per the tenant's support data retention policy. Contact for details on bucket location and retention for your tenant. ## Console Support-Bundles UI The LinuxGuard console exposes a Support Bundles section under the host detail view where operators can: * List uploaded bundles for the host (by `bundle_id`, upload timestamp, size, agent version) * View the bundle's manifest inline (contents list, trimmed segments, redaction summary) * Download the raw `.tar.zst` archive for offline inspection * See the audit trail of upload and access events The console-driven push path also collects + uploads bundles, with `trigger=console_push` and a `case_id` populated from the support case context. ## When to Collect Use the decision tree below to determine whether a support bundle is needed. On architectures without eBPF support, the agent automatically falls back to a reduced-telemetry mode instead of failing to start — this maps to the tree's "Degraded" branch below. ``` Is the agent running and reporting to the console? ├── Yes — does the console show the host as Healthy? │ ├── Yes — symptom is intermittent or correlation-only │ │ └── Collect bundle if support staff requests; otherwise no. │ └── No — agent reports Degraded or reduced-telemetry status │ └── Collect bundle. Include the time window of the degradation. └── No — agent is not reporting ├── Agent process is running locally │ └── Collect bundle. Check for connectivity errors in agent.log. └── Agent process is not running └── Try to start it first; if it crashes, collect bundle from any available agent.log before re-installing. ``` ### Pre-share Checklist Before sharing a collected bundle externally: 1. **Re-read the redaction status table above.** Confirm you understand what is NOT redacted. 2. **Inspect `agent.log` content** within the bundle for PII categories your data-handling policy regulates. 3. **Inspect `config.redacted.json`** to confirm secret fingerprints are present where expected. 4. **Decide on the share path**: direct upload to LinuxGuard support is safest because access is restricted to the LinuxGuard support team and audited. Email forwarding to third parties is the highest-risk path. 5. **Record the `bundle_id` and SHA256** so you can audit which bundle was shared with which party. ## Cross-References * [Log Management](/operate/operate/log-management) — Live-log redaction scope, central log collection patterns. * [Log Level and Rotation](/configure/configure/log-level-rotation) — Rotation defaults and operator knobs. *** **Related**: [Log Management](/operate/operate/log-management) | [Log Level and Rotation](/configure/configure/log-level-rotation) | [Troubleshooting](/troubleshooting) # Uninstallation Uninstall the LinuxGuard agent from a Linux host — package removal, config cleanup, and de-enrollment from your tenant. We understand that LinuxGuard may not be the right fit for every environment. When you decide to remove the agent, we ensure a complete and clean removal process that leaves no traces behind. ## Complete Cleanup The LinuxGuard uninstallation process is designed to completely remove the agent and all associated components from your system: * **Agent unenrollment**: The agent automatically unenrolls from your tenant before removal * **Service cleanup**: The agent service is stopped and disabled * **File removal**: All configuration files, state data, and logs are removed * **User cleanup**: The dedicated `linuxguard` user and group accounts are removed * **Complete removal**: No traces of the agent remain on your system ## Uninstallation Methods The uninstallation process varies slightly depending on your Linux distribution's package manager. ### Debian-based Systems For Debian, Ubuntu, and other Debian-based distributions: **Remove the agent (keeps configuration files):** ```bash sudo apt remove linuxguard-agent ``` **Remove the agent and all configuration files (complete cleanup):** ```bash sudo apt purge linuxguard-agent ``` The `purge` command ensures complete removal of all agent files, including: * Configuration files in `/etc/linuxguard/` * State files in `/var/lib/linuxguard/` * Log files in `/var/log/linuxguard/` * Runtime files in `/var/run/linuxguard/` * The `linuxguard` user and group accounts ### RedHat-based Systems For RHEL, CentOS, Fedora, and other RedHat/YUM-based distributions: **Remove the agent:** ```bash sudo dnf remove linuxguard-agent ``` Or for older systems using YUM: ```bash sudo yum remove linuxguard-agent ``` On RedHat-based systems, the `remove` command automatically performs a complete cleanup, removing all agent files, configuration, and user accounts. ### Alpine-based Systems For Alpine Linux: **Remove the agent:** ```bash sudo apk del linuxguard-agent ``` The Alpine package manager automatically removes all agent files and performs complete cleanup. ## What Happens During Uninstallation The uninstallation process follows these steps: 1. **Pre-removal cleanup**: * The agent automatically unenrolls from your LinuxGuard tenant * The agent service is stopped * The agent service is disabled to prevent it from starting on boot 2. **Package removal**: * The agent package is removed from your system * All agent binaries and files are removed 3. **Post-removal cleanup** (on Debian-based systems with `purge`): * All configuration directories are removed (`/etc/linuxguard/`) * All state directories are removed (`/var/lib/linuxguard/`) * All log directories are removed (`/var/log/linuxguard/`) * All runtime directories are removed (`/var/run/linuxguard/`) * The `linuxguard` user account is removed * The `linuxguard` group account is removed ## Verification After uninstallation, you can verify that the agent has been completely removed: ```bash # Check if the agent binary is removed which linuxguard-agent # Verify the agent user no longer exists id linuxguard # Check if agent directories are removed ls -la /etc/linuxguard ls -la /var/lib/linuxguard ls -la /var/log/linuxguard # Verify the service is removed systemctl status linuxguard-agent ``` All of these commands should indicate that the agent and its components have been removed. ## Removing the Repository (Optional) If you no longer need the LinuxGuard repository on your system, you can remove it: ### Debian-based Systems ```bash # Remove the repository file sudo rm /etc/apt/sources.list.d/linuxguard.list # Remove the GPG key sudo rm /etc/apt/trusted.gpg.d/linuxguard.gpg # Update package cache sudo apt update ``` ### RedHat-based Systems ```bash # Remove the repository file sudo rm /etc/yum.repos.d/linuxguard.repo # Or for DNF sudo rm /etc/dnf/repos.d/linuxguard.repo # Clean package cache sudo dnf clean all # Or sudo yum clean all ``` ### Alpine-based Systems ```bash # Remove the repository from /etc/apk/repositories sudo sed -i '/linuxguard/d' /etc/apk/repositories # Update package index sudo apk update ``` ## Container Uninstallation If you installed the agent in a container, simply remove the container: ```bash # Docker docker stop docker rm # Kubernetes kubectl delete pod ``` If you used volumes for persistence, you may also want to remove those: ```bash # Docker docker volume rm linuxguard-data linuxguard-logs # Kubernetes volumes are automatically cleaned up when pods are deleted ``` ## Tenant Cleanup After removing the agent from your systems, you may want to: 1. **Remove the agent from your console**: The agent will automatically disappear from your console after unenrollment, but you can also manually remove it if needed 2. **Review your tenant**: Consider whether you want to keep your tenant account active or contact to close your account ## Need Help? If you encounter any issues during uninstallation or have questions about the removal process, our support team is here to help: * **Email**: * **Available**: 24/7 We're committed to making the uninstallation process as smooth and complete as possible. *** **Related**: [Installation](/install/install) | [Troubleshooting](/troubleshooting) | [Support](/support) # Deploy at Scale Deploy the LinuxGuard agent at scale using configuration-management tools and cloud-init mechanisms across Ansible, Chef, Puppet, AWS, GCP, and Azure. Deploying LinuxGuard at scale requires automation — scripts or configuration management tools that install and enroll agents without manual intervention on each host. Two cross-cutting concerns apply regardless of which tool you use: **idempotency** (the deployment is safe to run multiple times without side effects) and **secrets management** (API keys and tenant IDs are never hardcoded in scripts or version control). ## What's in this section * [**Deploy with Ansible**](/deploy-at-scale/deploy-at-scale/ansible) — Deploy the LinuxGuard agent to a fleet of Linux hosts using an Ansible role with Vault-encrypted credentials and idempotent enrollment. * [**Deploy with Chef**](/deploy-at-scale/deploy-at-scale/chef) — Deploy the LinuxGuard agent at scale using a Chef cookbook with chef-vault credentials and idempotent enroll resource. * [**Deploy with Puppet**](/deploy-at-scale/deploy-at-scale/puppet) — Deploy the LinuxGuard agent at scale using a Puppet module with Hiera eyaml credentials and idempotent enroll exec. * [**Deploy with AWS EC2 User-Data**](/deploy-at-scale/deploy-at-scale/aws-userdata) — Provision the LinuxGuard agent on AWS EC2 instances at launch using user-data scripts and AWS Secrets Manager. * [**Deploy with GCP Startup Script**](/deploy-at-scale/deploy-at-scale/gcp-startup) — Provision the LinuxGuard agent on Google Compute Engine instances using startup-script metadata and Secret Manager. * [**Deploy with Azure**](/deploy-at-scale/deploy-at-scale/azure) — Provision the LinuxGuard agent on Azure Virtual Machines using cloud-init or Custom Script Extension with Key Vault credentials. ## Choosing a Deployment Method Select the deployment method that fits your existing infrastructure and tooling: | Tool | Best for | Secrets pattern | Idempotency mechanism | | ---------------------- | --------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------- | | Ansible | Existing Ansible inventory, mixed environments | Ansible Vault (`encrypt_string`) | `args: creates:` file guard on enroll task | | AWS EC2 User-Data | EC2 instances launched via Auto Scaling or CloudFormation | IAM instance profile + Secrets Manager | Agent built-in guard (user-data runs once on launch) | | GCP Startup Script | Compute Engine VMs in GCP projects | Service account + Secret Manager | Explicit file guard required (startup scripts run on every boot) | | Azure cloud-init / CSE | Azure VMs, including VMSS and ARM template deployments | Managed Identity + Key Vault | Agent built-in guard | | Chef | Existing Chef infrastructure with Chef Infra Server | chef-vault | `not_if` file guard on enroll resource | | Puppet | Existing Puppet infrastructure with PuppetDB | Hiera with eyaml encryption | `unless` file guard on enroll exec | > **Where to start:** Already using a configuration management platform? Start with [Ansible](/deploy-at-scale/deploy-at-scale/ansible), [Chef](/deploy-at-scale/deploy-at-scale/chef), or [Puppet](/deploy-at-scale/deploy-at-scale/puppet). Deploying new cloud VMs? Use your cloud provider's native script method: [AWS](/deploy-at-scale/deploy-at-scale/aws-userdata), [GCP](/deploy-at-scale/deploy-at-scale/gcp-startup), or [Azure](/deploy-at-scale/deploy-at-scale/azure). ## Enrollment Idempotency The `linuxguard-agent enroll` command is safe to call on an already-enrolled server. On startup, the agent checks its own configuration: if `/var/lib/linuxguard/config` exists and contains a valid server ID, it prints "Server is already enrolled" and exits with code 0. No duplicate enrollment occurs. ``` /var/lib/linuxguard/config ``` This file is written on successful enrollment. Its existence is the reliable enrollment indicator used by configuration management tool guards. > **Note:** Cloud scripts (AWS, GCP, Azure) rely on the agent's built-in guard as the primary protection. CM tools (Ansible, Chef, Puppet) additionally use a file existence check on `/var/lib/linuxguard/config` as the `when`/`not_if`/`unless` condition — this produces a clean convergence run with no spurious "changed" output when the agent is already enrolled. ## Prerequisites * A LinuxGuard API key and tenant ID (from the LinuxGuard console) * Network access from target hosts to `packages.linuxguard.io` for installation * Tool-specific prerequisites are documented in each individual guide *** **Related**: [Installation](/install/install) | [Deploy with Ansible](/deploy-at-scale/deploy-at-scale/ansible) | [Deploy with AWS EC2 User-Data](/deploy-at-scale/deploy-at-scale/aws-userdata) | [Deploy with GCP Startup Script](/deploy-at-scale/deploy-at-scale/gcp-startup) | [Deploy with Azure](/deploy-at-scale/deploy-at-scale/azure) | [Deploy with Chef](/deploy-at-scale/deploy-at-scale/chef) | [Deploy with Puppet](/deploy-at-scale/deploy-at-scale/puppet) # Deploy with Ansible Deploy the LinuxGuard agent to a fleet of Linux hosts using an Ansible role with Vault-encrypted credentials and idempotent enrollment. This guide provides a complete Ansible role for installing and enrolling LinuxGuard. Credentials are encrypted with Ansible Vault so no secrets appear in plaintext in your repository. The role is idempotent — safe to run repeatedly against already-enrolled servers. ## Prerequisites * Ansible 2.9+ or ansible-core 2.12+ installed on the control node * Target hosts reachable via SSH with sudo access * A LinuxGuard API key and tenant ID (from the LinuxGuard console) ## Role Structure The role follows the standard Ansible role directory layout. Create this structure under your `roles/` directory, or generate the skeleton with `ansible-galaxy role init linuxguard`: ``` roles/ └── linuxguard/ ├── defaults/ │ └── main.yml # Default variable values (lowest precedence) ├── handlers/ │ └── main.yml # Handler: restart agent service ├── meta/ │ └── main.yml # Role metadata (galaxy_info, dependencies) └── tasks/ └── main.yml # Core task list ``` ## Encrypting Secrets with Ansible Vault Use `ansible-vault encrypt_string` to encrypt individual values. This approach encrypts the value while keeping the variable name visible in version control, making it easy to audit which variables are vault-protected. Run these commands on your control node and paste the output into `defaults/main.yml`: ```bash ansible-vault encrypt_string '' --name 'linuxguard_api_key' ansible-vault encrypt_string '' --name 'linuxguard_tenant_id' ``` Each command prompts for a vault password and prints an encrypted block. Copy the full output (including the `!vault |` line) into your defaults file as shown in the next section. ## Role Files ### defaults/main.yml ```yaml --- # Values encrypted with: ansible-vault encrypt_string '' --name '' linuxguard_api_key: !vault | $ANSIBLE_VAULT;1.1;AES256 # paste output from encrypt_string here linuxguard_tenant_id: !vault | $ANSIBLE_VAULT;1.1;AES256 # paste output from encrypt_string here ``` ### tasks/main.yml ```yaml --- - name: Install LinuxGuard agent command: > bash -c "curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes" args: creates: /usr/bin/linuxguard-agent - name: Enable and start LinuxGuard service service: name: linuxguard-agent enabled: true state: started - name: Enroll LinuxGuard agent command: > linuxguard-agent enroll --api-key={{ linuxguard_api_key }} --tenant-id={{ linuxguard_tenant_id }} args: creates: /var/lib/linuxguard/config notify: Restart LinuxGuard agent ``` > **Note:** The `args: creates: /var/lib/linuxguard/config` guard on the enroll task skips enrollment if the agent is already enrolled. See [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) for details on the agent's built-in idempotency behavior. ### handlers/main.yml ```yaml --- - name: Restart LinuxGuard agent service: name: linuxguard-agent state: restarted ``` ### meta/main.yml ```yaml --- galaxy_info: author: your_username description: Install and enroll LinuxGuard agent license: MIT min_ansible_version: "2.9" dependencies: [] ``` ## Running the Role Create a `site.yml` playbook at the root of your project to apply the role to your inventory: ```yaml --- - hosts: all become: true roles: - linuxguard ``` Run the playbook and supply the vault password: ```bash ansible-playbook site.yml --ask-vault-pass # Or with a vault password file: ansible-playbook site.yml --vault-password-file ~/.vault_pass ``` > **Note:** If you use AWX or Ansible Tower, store the vault password as a **Credential** object. The `--ask-vault-pass` flag is not needed — AWX injects the vault password automatically. ## Inline Playbook (Alternative) If you prefer a single-file playbook without a role structure, the equivalent inline form requires no directory layout: ```yaml --- - hosts: all become: true vars: linuxguard_api_key: !vault | $ANSIBLE_VAULT;1.1;AES256 # paste output from encrypt_string here linuxguard_tenant_id: !vault | $ANSIBLE_VAULT;1.1;AES256 # paste output from encrypt_string here tasks: - name: Install LinuxGuard agent command: > bash -c "curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes" args: creates: /usr/bin/linuxguard-agent - name: Enable and start LinuxGuard service service: name: linuxguard-agent enabled: true state: started - name: Enroll LinuxGuard agent command: > linuxguard-agent enroll --api-key={{ linuxguard_api_key }} --tenant-id={{ linuxguard_tenant_id }} args: creates: /var/lib/linuxguard/config handlers: - name: Restart LinuxGuard agent service: name: linuxguard-agent state: restarted ``` Run the same way: `ansible-playbook site.yml --ask-vault-pass`. ## Verifying the Deployment Add a verification task at the end of `tasks/main.yml` to confirm the agent is running after each playbook run: ```yaml - name: Verify LinuxGuard agent is running service_facts: - name: Assert LinuxGuard agent is active assert: that: "'linuxguard-agent' in services and services['linuxguard-agent'].state == 'running'" fail_msg: "LinuxGuard agent is not running" ``` This task fails the play immediately if the service is not active, surfacing installation or enrollment errors before the run is marked successful. Enrolled servers also appear in the LinuxGuard console under **Infrastructure** within a few minutes of enrollment. *** **Related**: [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) | [Installation](/install/install) | [Configuration](/configure/configure) # Deploy with Chef Deploy the LinuxGuard agent at scale using a Chef cookbook with chef-vault credentials and idempotent enroll resource. This guide provides a complete Chef cookbook for installing and enrolling LinuxGuard. Credentials are managed with chef-vault, which encrypts data bag items using each node's public key so only authorised nodes can decrypt them. The recipe is idempotent — safe to run on already-enrolled nodes because the enroll resource includes a `not_if` guard on `/var/lib/linuxguard/config`. ## Prerequisites * Chef Workstation installed on your workstation * Chef Infra Server with nodes registered and their public keys uploaded * The `chef-vault` gem available on your workstation (`chef gem install chef-vault` if not already installed) * A LinuxGuard API key and tenant ID (from the LinuxGuard console) > **Important:** chef-vault requires Chef Infra Server with public/private key pairs per node. It is not compatible with chef-solo or knife-solo. If you are using chef-solo or chef-zero, use the Chef `secret()` helper (available in Chef Infra Client 17.5+) to integrate with AWS Secrets Manager or Azure Key Vault instead. ## Cookbook Structure Create the following structure in your Chef repository's `cookbooks/` directory: ``` cookbooks/ └── linuxguard/ ├── metadata.rb # Cookbook name, version, description ├── attributes/ │ └── default.rb # Default attribute values └── recipes/ └── default.rb # Install, enable, enroll ``` ## Step 1: Create the chef-vault Item Store LinuxGuard credentials in a chef-vault item. The vault encrypts the data bag item using the public keys of the nodes you specify — only those nodes can decrypt it during a Chef run. Run the following command from your workstation: ```bash knife vault create linuxguard credentials \ '{"api_key":"","tenant_id":""}' \ --search "role:linuxguard-node" \ --admins "admin" ``` * **`--search`** — specifies which nodes should have decryption access. Adjust the search query to match the nodes in your environment (for example, `role:linuxguard-node` or `name:*`). * **`--admins`** — specifies Chef Server users who can administer the vault item (read, update, delete). To verify the vault item was created: ```bash knife vault show linuxguard credentials ``` ## Step 2: Create the Cookbook Files ### metadata.rb ```ruby name 'linuxguard' maintainer 'Your Organization' maintainer_email 'ops@example.com' license 'All Rights Reserved' description 'Installs and enrolls LinuxGuard agent' version '1.0.0' chef_version '>= 16.0' ``` ### attributes/default.rb ```ruby # Default attributes — override in roles or environments as needed default['linuxguard']['installer_url'] = 'https://packages.linuxguard.io/install-linuxguard.sh' ``` ### recipes/default.rb ```ruby # Install LinuxGuard agent execute 'install_linuxguard' do command "curl -fsSL #{node['linuxguard']['installer_url']} | bash -s -- --yes" not_if { ::File.exist?('/usr/bin/linuxguard-agent') } end # Enable and start LinuxGuard service service 'linuxguard-agent' do action [:enable, :start] end # Retrieve credentials from chef-vault linuxguard_creds = chef_vault_item('linuxguard', 'credentials') # Enroll LinuxGuard agent (idempotent via not_if guard) execute 'enroll_linuxguard' do command lazy { "linuxguard-agent enroll " \ "--api-key=#{linuxguard_creds['api_key']} " \ "--tenant-id=#{linuxguard_creds['tenant_id']}" } not_if { ::File.exist?('/var/lib/linuxguard/config') } sensitive true end ``` > **Note:** The `not_if { ::File.exist?('/var/lib/linuxguard/config') }` guard skips enrollment if the agent is already enrolled. The `sensitive true` attribute prevents credentials from appearing in Chef run logs. See [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) for details on the agent's built-in idempotency behavior. ## Step 3: Add the Cookbook to a Run List Add the cookbook to a node's run list: ```bash knife node run_list add recipe[linuxguard] ``` Or add `recipe[linuxguard]` to a role's run list so all nodes in that role receive the cookbook automatically: ```bash knife role edit linuxguard-node ``` Then run the Chef client on the target node to apply the cookbook: ```bash chef-client ``` ## Verifying the Deployment After the Chef run completes, you can add a verification step to your recipe to confirm the agent is running: ```ruby # Verify LinuxGuard agent service is running ruby_block 'verify_linuxguard_running' do block do status = `systemctl is-active linuxguard-agent`.strip raise "LinuxGuard agent is not running (status: #{status})" unless status == 'active' end only_if { ::File.exist?('/var/lib/linuxguard/config') } end ``` Enrolled nodes also appear in the **Infrastructure** view of the LinuxGuard console within a few minutes of successful enrollment. *** **Related**: [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) | [Installation](/install/install) | [Configuration](/configure/configure) # Deploy with Puppet Deploy the LinuxGuard agent at scale using a Puppet module with Hiera eyaml credentials and idempotent enroll exec. This guide provides a complete Puppet module for installing and enrolling LinuxGuard. Credentials are stored in Hiera using the eyaml encryption backend, which encrypts individual values in Hiera YAML files while keeping keys readable. The module is idempotent — safe to apply on already-enrolled nodes because the enroll exec resource includes an `unless` guard on `/var/lib/linuxguard/config`. ## Prerequisites * Puppet 7 or 8 with Puppet Server * hiera-eyaml available on Puppet Server (bundled with Puppet Server 5.2.0+; install with `puppetserver gem install hiera-eyaml` if needed) * A LinuxGuard API key and tenant ID (from the LinuxGuard console) ## Module Structure Create the following structure in your Puppet environment's `modules/` directory: ``` modules/ └── linuxguard/ ├── metadata.json # Module name, author, version, dependencies └── manifests/ └── init.pp # Main class: install, service, enroll ``` Hiera data lives in the environment, not in the module: ``` environments/production/ ├── hiera.yaml # Hierarchy with eyaml backend └── data/ └── common.eyaml # Encrypted LinuxGuard credentials ``` ## Step 1: Generate eyaml Encryption Keys eyaml uses PKCS7 key pairs to encrypt Hiera values. Generate the keys on your Puppet Server: ```bash eyaml createkeys ``` The keys are generated in `./keys/` by default. Move them to the standard location: ```bash sudo mkdir -p /etc/puppetlabs/puppet/eyaml sudo mv keys/private_key.pkcs7.pem /etc/puppetlabs/puppet/eyaml/ sudo mv keys/public_key.pkcs7.pem /etc/puppetlabs/puppet/eyaml/ ``` Then fix key ownership so Puppet Server can read them: ```bash sudo chown -R puppet:puppet /etc/puppetlabs/puppet/eyaml sudo chmod -R 0500 /etc/puppetlabs/puppet/eyaml ``` > **Note:** Puppet Server runs as the `puppet` user. If the key files are owned by root, Puppet catalog compilation will fail with a permission error when attempting to decrypt Hiera values. ## Step 2: Encrypt LinuxGuard Credentials Run `eyaml encrypt` for each credential value: ```bash eyaml encrypt -s '' eyaml encrypt -s '' ``` Each command outputs an `ENC[PKCS7,...]` block. Copy the outputs into `environments/production/data/common.eyaml`: ```yaml --- linuxguard::api_key: ENC[PKCS7,MIIBiAYJKoZIhvfQ...] linuxguard::tenant_id: ENC[PKCS7,MIIBmAYJKoZIhvfQ...] ``` Replace the placeholder `ENC[PKCS7,...]` strings with the actual output from the `eyaml encrypt` commands above. ## Step 3: Configure the Hiera eyaml Backend Create or update `environments/production/hiera.yaml` with the eyaml backend configuration: ```yaml --- version: 5 defaults: datadir: data data_hash: yaml_data hierarchy: - name: "Encrypted secrets" lookup_key: eyaml_lookup_key paths: - "common.eyaml" options: pkcs7_private_key: /etc/puppetlabs/puppet/eyaml/private_key.pkcs7.pem pkcs7_public_key: /etc/puppetlabs/puppet/eyaml/public_key.pkcs7.pem ``` Place this file at `environments/production/hiera.yaml`, or the equivalent path for your environment name. ## Step 4: Create the Module Files ### metadata.json ```json { "name": "yourorg-linuxguard", "version": "1.0.0", "author": "yourorg", "license": "Apache-2.0", "summary": "Install and enroll LinuxGuard agent", "source": "https://github.com/yourorg/puppet-linuxguard", "dependencies": [] } ``` Replace `yourorg` with your organisation's name. ### manifests/init.pp ```puppet class linuxguard ( String $api_key = lookup('linuxguard::api_key'), String $tenant_id = lookup('linuxguard::tenant_id'), ) { exec { 'install_linuxguard': command => 'curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes', path => ['/usr/bin', '/bin'], unless => 'test -f /usr/bin/linuxguard-agent', } service { 'linuxguard-agent': ensure => running, enable => true, require => Exec['install_linuxguard'], } exec { 'enroll_linuxguard': command => "/usr/bin/linuxguard-agent enroll --api-key=${api_key} --tenant-id=${tenant_id}", unless => 'test -f /var/lib/linuxguard/config', path => ['/usr/bin', '/bin'], require => Service['linuxguard-agent'], } } ``` > **Note:** The `unless => 'test -f /var/lib/linuxguard/config'` guard skips enrollment if the agent is already enrolled. The `require` attributes enforce ordering: install -> service -> enroll. See [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) for details on the agent's built-in idempotency behavior. ## Step 5: Apply the Module Classify the node with the module using the Puppet site manifest or an ENC: ```puppet # site.pp or node classification node 'my-server.example.com' { include linuxguard } ``` Or classify via the Puppet Enterprise console or your node classifier of choice. Then trigger a Puppet agent run on the target node: ```bash puppet agent --test ``` Enrolled nodes appear in the **Infrastructure** view of the LinuxGuard console within a few minutes of successful enrollment. *** **Related**: [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) | [Installation](/install/install) | [Configuration](/configure/configure) # Deploy with AWS EC2 User-Data Provision the LinuxGuard agent on AWS EC2 instances at launch using user-data scripts and credentials from AWS Secrets Manager. This guide provides a complete EC2 user-data script that installs and enrolls LinuxGuard at instance launch. Credentials are retrieved from AWS Secrets Manager at runtime — no API keys or tenant IDs are hardcoded in the script. ## Prerequisites * AWS CLI installed locally for the one-time setup steps * An EC2 instance role (instance profile) attached to your target instances * A LinuxGuard API key and tenant ID (from the LinuxGuard console) ## Step 1: Store credentials in Secrets Manager Run this command once from your local machine or CI/CD pipeline to create the secret: ```bash aws secretsmanager create-secret \ --name linuxguard/credentials \ --secret-string '{"api_key":"","tenant_id":""}' \ --region ``` Note the **ARN** in the command output — you will reference it when scoping the IAM policy in the next step. ## Step 2: Attach an IAM policy to your instance role The EC2 instance needs permission to read the specific secret created above. Attach the following least-privilege inline or managed policy to the IAM role assigned to your EC2 instances (via the instance profile): ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager:::secret:linuxguard/credentials-*" } ] } ``` > **Note:** The `-*` suffix in the resource ARN matches the random suffix that AWS appends to secret ARNs. Omitting it causes `AccessDeniedException` when the instance attempts to read the secret. Replace `` and `` with your values. ## Step 3: Configure and launch with user-data > **Note:** EC2 user-data scripts run **once** on first instance launch by default. Re-enrollment on subsequent reboots is not a concern — the script does not run again unless you explicitly reconfigure the instance to do so. Paste the script below into the **User data** field when launching your EC2 instance (via the console, CLI, Launch Template, or CloudFormation). Replace the two values in the `# Configuration` section: ```bash #!/usr/bin/env bash set -euo pipefail # =========================================================== # Configuration — replace these values for your environment # =========================================================== SECRET_NAME="linuxguard/credentials" AWS_REGION="" # =========================================================== # Install jq if not present (needed to parse Secrets Manager JSON output) if ! command -v jq &> /dev/null; then apt-get install -y jq 2>/dev/null || yum install -y jq 2>/dev/null || true fi # Retrieve credentials from Secrets Manager (IAM instance role provides access) SECRET=$(aws secretsmanager get-secret-value \ --secret-id "${SECRET_NAME}" \ --region "${AWS_REGION}" \ --query 'SecretString' \ --output text) API_KEY=$(echo "${SECRET}" | jq -r '.api_key') TENANT_ID=$(echo "${SECRET}" | jq -r '.tenant_id') # Install LinuxGuard agent curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes # Enroll agent — built-in guard prevents re-enrollment if already enrolled linuxguard-agent enroll \ --api-key="${API_KEY}" \ --tenant-id="${TENANT_ID}" ``` > **Note:** For operators who want explicit visibility into whether enrollment was skipped, replace the enroll step with a conditional check: > > ```bash > if ! systemctl is-active --quiet linuxguard-agent; then > linuxguard-agent enroll \ > --api-key="${API_KEY}" \ > --tenant-id="${TENANT_ID}" > fi > ``` > > This approach skips enrollment if the service is already running. See [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) for details on the agent's built-in idempotency guard. After launch, enrolled servers appear in the LinuxGuard console under **Infrastructure** within a few minutes. *** **Related**: [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) | [Installation](/install/install) | [Configuration](/configure/configure) # Deploy with GCP Startup Script Provision the LinuxGuard agent on Google Compute Engine instances using startup-script metadata, Secret Manager, and an idempotency guard. This guide provides a complete GCP Compute Engine startup script that installs and enrolls LinuxGuard, retrieving credentials from Secret Manager using the VM's attached service account — no hardcoded credentials in the script. > **Important:** GCP Compute Engine startup scripts run on **every VM boot**, not just the first launch. The script below includes a mandatory idempotency guard to prevent re-enrollment on subsequent reboots. Do not remove this guard. ## Prerequisites * Google Cloud SDK (`gcloud`) installed locally for one-time setup steps * A Compute Engine instance with a service account attached (see Step 1) * A LinuxGuard API key and tenant ID (from the LinuxGuard console) ## Step 1: Create a service account and grant access The VM's attached service account needs the `roles/secretmanager.secretAccessor` role on each LinuxGuard secret. Create and assign it in the following steps. ```bash # Create a service account (if you don't have one already) gcloud iam service-accounts create linuxguard-deployer \ --display-name="LinuxGuard Deployer" ``` > **Note:** If you already have a service account for your instances, use that — you do not need to create a new one. ## Step 2: Store credentials in Secret Manager Store your LinuxGuard credentials as individual secrets — one value per secret, as plain text: ```bash # Store credentials as individual secrets (plain text, one value per secret) gcloud secrets create linuxguard-api-key --data-file=- <<< "" gcloud secrets create linuxguard-tenant-id --data-file=- <<< "" # Grant the service account read access to each secret gcloud secrets add-iam-policy-binding linuxguard-api-key \ --member="serviceAccount:" \ --role="roles/secretmanager.secretAccessor" gcloud secrets add-iam-policy-binding linuxguard-tenant-id \ --member="serviceAccount:" \ --role="roles/secretmanager.secretAccessor" ``` Replace `` with the service account's email address (for example, `linuxguard-deployer@.iam.gserviceaccount.com`). ## Step 3: Attach the service account to your instances When creating a VM instance — via the Console, `gcloud` CLI, or Terraform — specify the service account in the instance configuration. For existing VMs, update the attached service account via the Console or `gcloud compute instances set-service-account`. The startup script uses Application Default Credentials from the attached service account, so no key file or explicit credential configuration is required. ## Step 4: Configure and deploy the startup script Paste the following script into the **Startup script** field when creating a VM instance, or set it via `gcloud compute instances add-metadata --metadata=startup-script=...`. Replace the values in the **Configuration** section at the top. ```bash #!/usr/bin/env bash set -euo pipefail # =========================================================== # Configuration — replace these values for your environment # =========================================================== PROJECT_ID="" API_KEY_SECRET="linuxguard-api-key" TENANT_ID_SECRET="linuxguard-tenant-id" # =========================================================== # Install LinuxGuard agent (installer is idempotent) curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes # Enroll agent — file guard is REQUIRED because startup scripts run on every boot if [ ! -f /var/lib/linuxguard/config ]; then API_KEY=$(gcloud secrets versions access latest \ --secret="${API_KEY_SECRET}" \ --project="${PROJECT_ID}") TENANT_ID=$(gcloud secrets versions access latest \ --secret="${TENANT_ID_SECRET}" \ --project="${PROJECT_ID}") linuxguard-agent enroll \ --api-key="${API_KEY}" \ --tenant-id="${TENANT_ID}" fi ``` > **Note:** The `if [ ! -f /var/lib/linuxguard/config ]` guard prevents unnecessary Secret Manager calls and agent enrollment attempts on every reboot. See [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) for details on what this file indicates. ## Verifying the Deployment After the VM boots, enrolled servers appear in the LinuxGuard console under **Infrastructure** within a few minutes. *** **Related**: [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) | [Installation](/install/install) | [Configuration](/configure/configure) # Deploy with Azure Provision the LinuxGuard agent on Azure Virtual Machines using cloud-init or Custom Script Extension, with Key Vault credentials via managed identity. This guide covers deploying LinuxGuard on Azure VMs using cloud-init — the standard Linux cloud initialization mechanism. Credentials are retrieved from Azure Key Vault using system-assigned managed identity, eliminating hardcoded secrets. A Custom Script Extension alternative is provided for operators using ARM templates or the Azure Portal. ## Prerequisites * Azure CLI installed locally for one-time setup steps * A Linux VM with system-assigned managed identity enabled (see Step 1) * A LinuxGuard API key and tenant ID (from the LinuxGuard console) ## Step 1: Enable managed identity and configure Key Vault System-assigned managed identity lets the VM authenticate to Azure services without credentials. Enable it and grant it access to Key Vault using the following steps. **Enable managed identity on an existing VM** (can also be done at creation time with `--assign-identity`): ```bash az vm identity assign --name --resource-group ``` **Create a Key Vault and store LinuxGuard credentials as secrets:** ```bash # Create Key Vault (skip if you already have one) az keyvault create --name --resource-group --location # Store LinuxGuard credentials as Key Vault secrets az keyvault secret set --vault-name --name linuxguard-api-key --value "" az keyvault secret set --vault-name --name linuxguard-tenant-id --value "" ``` **Grant the VM's managed identity access to read secrets:** ```bash az keyvault set-policy \ --name \ --object-id $(az vm identity show --name --resource-group --query principalId -o tsv) \ --secret-permissions get ``` ## Step 2: Deploy with cloud-init Cloud-init is the standard cloud VM initialization mechanism on Azure Linux VMs. Provide the configuration as user-data when creating the VM. The IMDS (Instance Metadata Service) endpoint provides a bearer token for Key Vault access — no credentials required. Save the following as `cloud-init.yaml`, replacing `` with your Key Vault name: ```yaml #cloud-config packages: - jq runcmd: - | # Configuration — replace VAULT_NAME with your Key Vault name VAULT_NAME="" # Acquire bearer token from IMDS (managed identity provides this — no credentials needed) TOKEN=$(curl -s -H "Metadata: true" \ "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://vault.azure.net" \ | jq -r '.access_token') # Retrieve credentials from Key Vault API_KEY=$(curl -s -H "Authorization: Bearer ${TOKEN}" \ "https://${VAULT_NAME}.vault.azure.net/secrets/linuxguard-api-key?api-version=7.4" \ | jq -r '.value') TENANT_ID=$(curl -s -H "Authorization: Bearer ${TOKEN}" \ "https://${VAULT_NAME}.vault.azure.net/secrets/linuxguard-tenant-id?api-version=7.4" \ | jq -r '.value') # Install LinuxGuard agent curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes # Enroll agent — built-in guard prevents re-enrollment if already enrolled linuxguard-agent enroll \ --api-key="${API_KEY}" \ --tenant-id="${TENANT_ID}" ``` > **Note:** Azure cloud-init runs once on first boot. The agent's built-in enrollment guard provides additional protection if the script runs again. The `api-version=7.4` parameter in Key Vault REST API calls is required — omitting it returns a 400 error. See [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) for details on enrollment idempotency. Create the VM and pass the cloud-init config as user-data: ```bash az vm create \ --name \ --resource-group \ --image Ubuntu2204 \ --custom-data cloud-init.yaml \ --assign-identity \ --admin-username azureuser \ --generate-ssh-keys ``` > **Note:** `--assign-identity` enables system-assigned managed identity at VM creation time — equivalent to the `az vm identity assign` command in Step 1 for new VMs. If you use `--assign-identity` at creation time, the Step 1 identity assignment is not required. ## Alternative: Custom Script Extension Custom Script Extension (CSE) lets you run a script on a VM after creation — useful when deploying via ARM templates or when cloud-init is not available. CSE is an Azure-specific mechanism. The following command runs an inline script on an existing VM using CSE: ```bash az vm extension set \ --resource-group \ --vm-name \ --name customScript \ --publisher Microsoft.Azure.Extensions \ --settings "{\"commandToExecute\": \"apt-get install -y jq && VAULT_NAME= && TOKEN=\$(curl -s -H 'Metadata: true' 'http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://vault.azure.net' | jq -r '.access_token') && API_KEY=\$(curl -s -H \\\"Authorization: Bearer \$TOKEN\\\" 'https://.vault.azure.net/secrets/linuxguard-api-key?api-version=7.4' | jq -r '.value') && TENANT_ID=\$(curl -s -H \\\"Authorization: Bearer \$TOKEN\\\" 'https://.vault.azure.net/secrets/linuxguard-tenant-id?api-version=7.4' | jq -r '.value') && curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes && linuxguard-agent enroll --api-key=\$API_KEY --tenant-id=\$TENANT_ID\"}" ``` > **Note:** For production use, store the script in Azure Blob Storage and reference it via `fileUris` rather than using an inline command — inline commands have length limits and are less maintainable. ## Verifying the Deployment After the VM boots, enrolled servers appear in the LinuxGuard console under **Infrastructure** within a few minutes. *** **Related**: [Automated Deployment Overview](/deploy-at-scale/deploy-at-scale) | [Installation](/install/install) | [Configuration](/configure/configure) # Respond Active response and SecOps integration for LinuxGuard alerts — notification rules, webhooks, syslog, and SIEM forwarding. Active response and SecOps integration: notification rule configuration, webhook delivery, syslog forwarding, and Splunk HEC integration. ## What's in this section * [**Notification Rules**](/respond/respond/notification-rules) — Configure notification rules in the console to route alerts to webhook, syslog, and Splunk HEC delivery channels. * [**Webhook Integration**](/respond/respond/webhook-integration) — Deliver LinuxGuard signals to an HTTPS endpoint using signed webhook requests with retry semantics. * [**Syslog Forwarding**](/respond/respond/syslog-forwarding) — Forward LinuxGuard signals as syslog messages to a SIEM or log aggregator over TCP, UDP, or TLS. * [**Splunk HEC Integration**](/respond/respond/splunk-hec-integration) — Send LinuxGuard signals to Splunk via the HTTP Event Collector with token authentication. # Notification Rules Configure notification rules in the LinuxGuard console to route signals to webhook, syslog, and Splunk HEC delivery channels. Configure notification rules to route LinuxGuard signals to your alerting and SIEM destinations. ## Prerequisites * Access to the LinuxGuard console with administrator role * At least one delivery channel configured: a webhook endpoint, a syslog destination, or a Splunk HEC destination ## Create a Notification Rule 1. Navigate to **Settings** in the LinuxGuard console and open the **Notification Rules** section. 2. Select **New Rule** and provide a descriptive **Name** for the rule. 3. Set the **Trigger Type** to `signal_created`. This is the standard trigger for signal-based alerting and SIEM forwarding. 4. Under **Channels**, select one or more delivery channels to receive signals when this rule fires. A rule can deliver to multiple channels simultaneously — for example, a webhook and a syslog destination at the same time. 5. Optionally configure **Filter Conditions** to limit which signals the rule matches. See [Filter Conditions](#filter-conditions) below for the full reference. Leave conditions empty if you want the rule to match every signal (useful for a catch-all SIEM forwarding rule). 6. Optionally configure **Throttle** to limit delivery volume. See [Throttle](#throttle) below. 7. Optionally configure **Quiet Hours** to suppress deliveries during off-hours windows. See [Quiet Hours](#quiet-hours) below. 8. Save the rule. The rule becomes active immediately for new signals. ## Filter Conditions Conditions use AND logic: all configured conditions must match a signal for the rule to fire. A rule with no conditions configured matches every signal, which is useful for a catch-all forwarding rule that ingests all signals into a SIEM. | Condition | What it filters | Allowed values | Example | | ---------------- | -------------------------- | ------------------------------------------- | ----------------------------------------------------- | | `severity` | Minimum signal severity | `info`, `low`, `medium`, `high`, `critical` | `medium` — matches medium, high, and critical signals | | `categories` | Signal category | Signal category name | `privilege_escalation` | | `environments` | Agent environment tag | Environment name string | `production` | | `tags` | Agent tag | Tag name string | `web-tier` | | `identity_types` | Identity type of the actor | `user`, `service_account` | `user` | > **Note**: The `severity` condition matches the specified level and all higher severities. Configuring `severity: medium` will match medium, high, and critical signals — it does not filter for medium-severity signals only. ## Throttle Throttle limits how many signals a rule delivers within a time window. Use throttle to prevent high-volume incident events from overwhelming a receiving system or generating too many notifications. Two throttle patterns are available. Use one or the other — do not combine `max_per_hour` with `max_per_period`. **Pattern 1 — per-hour limit.** Caps deliveries to a fixed number per hour: ```json { "max_per_hour": 10 } ``` **Pattern 2 — flexible period.** Caps deliveries within a custom period window: ```json { "max_per_period": 5, "period_minutes": 30 } ``` Throttle applies per rule per channel destination. If a rule delivers to two channels, each channel has its own throttle counter. ## Quiet Hours Quiet hours define a daily window during which signal delivery is suppressed for this rule. Configure quiet hours to avoid non-urgent notifications during off-hours. ```json { "start": "22:00", "end": "06:00", "critical_bypass": true } ``` > **Note**: Quiet hours `start` and `end` times are in UTC. Overnight ranges (where `start` is later than `end`) are supported — the example above suppresses from 22:00 UTC to 06:00 UTC. With `critical_bypass: true`, critical-severity signals are delivered even during the quiet window. *** **Related**: [Alerting & SIEM Integration](/concepts/concepts/alerting) | [Webhook Integration](/respond/respond/webhook-integration) | [Syslog Forwarding](/respond/respond/syslog-forwarding) | [Splunk HEC Integration](/respond/respond/splunk-hec-integration) # Webhook Integration Deliver LinuxGuard security signals to an HTTPS endpoint using signed webhook requests with retry semantics. Configure LinuxGuard to deliver security signals to an HTTP endpoint using signed webhook requests. ## Prerequisites * Access to the LinuxGuard console with administrator role * An HTTPS endpoint that can receive POST requests (http\:// URLs are not accepted) ## Create a Webhook Endpoint 1. In the LinuxGuard console, navigate to **Settings** > **Integrations** > **Webhooks**. 2. Select **Add Endpoint**. 3. Enter the **URL** of your receiving endpoint. > **Note**: Only HTTPS URLs are accepted. Endpoints using `http://` are rejected at validation. 4. Enter a descriptive **Name** for the endpoint (for example, `security-siem-webhook`). 5. Optionally, add **Custom Headers** for authentication or routing (see [Custom Headers](#custom-headers)). 6. Select **Create**. > **Important**: The webhook secret is displayed only once when the endpoint is created. Copy and store it securely before navigating away. If you lose the secret, you must delete and re-create the endpoint to generate a new one. ## Verify HMAC Signatures Every webhook request includes a `LinuxGuard-Signature: sha256=` header. This value is an HMAC-SHA256 signature computed over the raw request body using the endpoint secret. Your receiver must validate this signature to confirm the request originated from LinuxGuard. Use a timing-safe comparison function to prevent timing oracle attacks. The examples below use the standard timing-safe functions available in each language. **Python** ```python import hmac import hashlib def verify_signature(payload_bytes: bytes, secret: str, header_value: str) -> bool: expected = 'sha256=' + hmac.new( secret.encode(), payload_bytes, hashlib.sha256 ).hexdigest() return hmac.compare_digest(expected, header_value) ``` **Node.js** ```javascript const crypto = require('crypto'); function verifySignature(payloadBuffer, secret, headerValue) { const expected = 'sha256=' + crypto .createHmac('sha256', secret) .update(payloadBuffer) .digest('hex'); return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(headerValue)); } ``` **Go** ```go import ( "crypto/hmac" "crypto/sha256" "encoding/hex" ) func verifySignature(payload []byte, secret, headerValue string) bool { mac := hmac.New(sha256.New, []byte(secret)) mac.Write(payload) expected := "sha256=" + hex.EncodeToString(mac.Sum(nil)) return hmac.Equal([]byte(expected), []byte(headerValue)) } ``` ## Request Headers Every webhook request includes the following headers: | Header | Value | Description | | ---------------------- | ------------------------ | --------------------------------------------- | | `Content-Type` | `application/json` | Payload format | | `LinuxGuard-Signature` | `sha256=` | HMAC-SHA256 signature of the raw request body | | `LinuxGuard-Event` | `signal_created` | Event type | | `LinuxGuard-Delivery` | UUID | Unique delivery identifier for deduplication | | `LinuxGuard-Timestamp` | Unix epoch | Time the request was sent | | `User-Agent` | `LinuxGuard-Webhook/1.0` | Sender identification | ## Payload Reference All webhook deliveries use the V1 payload envelope. The top-level fields wrap the signal data object. **Top-level fields** | Field | Type | Description | | ------------- | ------ | ----------------------------------------- | | `event_type` | string | Always `signal_created` for signal alerts | | `version` | string | Payload version, currently `v1` | | `timestamp` | string | ISO 8601 timestamp of the delivery | | `tenant_id` | string | Your tenant identifier | | `data` | object | Signal data (see fields below) | | `console_url` | string | Link to the signal in the console | **Signal fields (nested under `data`)** | Field | Type | Description | | --------------- | ------- | ---------------------------------------------- | | `signal_id` | string | Unique signal identifier | | `signal_type` | string | Signal type (e.g., `sudo_command_executed`) | | `severity` | integer | Signal severity: 1 (info) to 5 (critical) | | `description` | string | Human-readable signal description | | `server_id` | string | Identifier of the reporting server | | `server_name` | string | Hostname of the reporting server | | `identity_id` | string | Identifier of the associated identity | | `identity_name` | string | Username or service account name | | `environment` | string | Agent environment tag | | `created_at` | string | ISO 8601 timestamp when the signal was created | **Example payload** ```json { "event_type": "signal_created", "version": "v1", "timestamp": "2026-03-02T14:32:01Z", "tenant_id": "", "data": { "signal_id": "sig_abc123", "signal_type": "sudo_command_executed", "severity": 4, "description": "Sudo command executed", "server_id": "srv_xyz", "server_name": "web-01", "identity_id": "id_jsmith", "identity_name": "jsmith", "environment": "production", "created_at": "2026-03-02T14:31:58Z" }, "console_url": "https://console.linuxguard.io/signals" } ``` ## Custom Headers Each webhook endpoint can be configured with additional request headers that are sent with every delivery. Common uses include authentication tokens for the receiving system (for example, `Authorization: Bearer `) and routing headers for your infrastructure. To add a custom header, enter the header name and value in the **Custom Headers** section when creating or editing an endpoint. *** **Related**: [Alerting & SIEM Integration](/concepts/concepts/alerting) | [Configure Notification Rules](/respond/respond/notification-rules) | [Syslog Forwarding](/respond/respond/syslog-forwarding) | [Splunk HEC Integration](/respond/respond/splunk-hec-integration) # Syslog Forwarding Forward LinuxGuard security signals as syslog messages to a SIEM or log aggregator over TCP, UDP, or TLS transport. Configure LinuxGuard to forward security signals as syslog messages to a SIEM or log aggregator. ## Prerequisites * Access to the LinuxGuard console with administrator role * A syslog receiver accessible from the LinuxGuard backend (host, port, and protocol confirmed) ## Configure a Syslog Destination 1. In the LinuxGuard console, navigate to **Settings** > **Integrations** > **Syslog**. 2. Select **Add Destination**. 3. Enter the **Host** of your syslog receiver. 4. Enter the **Port** (default: `514`). 5. Select the **Protocol**: `udp` (default), `tcp`, or `tls`. 6. Select the **Format**: `rfc5424` (default, recommended) or `rfc3164`. 7. Set the **Facility** (default: `1` — user-level). 8. Select **Save**. ## Protocol Options ### UDP (Default) UDP is the default protocol and is suitable for high-volume environments where occasional message loss is acceptable. It operates without connection state. Syslog over UDP is fire-and-forget — delivery failures are not retried. ### TCP TCP provides ordered delivery with connection state and is suitable when message loss is not acceptable. LinuxGuard makes a single write attempt per delivery over a TCP connection; there is no retry on failure. ### TLS TLS encrypts the syslog stream. When TLS is selected, you can configure the following certificate fields: | Field | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------- | | `ca_cert` | Path to the CA certificate file for server certificate verification (recommended for self-signed or internal CA) | | `client_cert` | Path to the client certificate file (required for mTLS) | | `client_key` | Path to the client private key file (required for mTLS) | | `skip_verify` | Set to `true` to disable server certificate verification (not recommended for production) | #### Mutual TLS (mTLS) To require mutual authentication, provide both `client_cert` and `client_key` in addition to `ca_cert`. The syslog server will verify the client certificate during the TLS handshake. ## RFC Format Options ### RFC 5424 (Default, Recommended) RFC 5424 is the default format and is recommended for SIEM integration. It supports structured data elements that carry LinuxGuard-specific fields, enabling precise SIEM parser rules without relying on free-text message parsing. ## RFC 5424 Structured Data Every RFC 5424 message produced by LinuxGuard includes four structured data elements (SD-IDs) that carry identity, signal, tenant, and MITRE ATT\&CK information. Fields are only included when the corresponding data is non-empty. | SD-ID | Fields | Description | | --------------------- | ------------------------------------ | ------------------------------------------------ | | `identity@linuxguard` | `name`, `type`, `risk` | Identity associated with the signal | | `signal@linuxguard` | `type`, `severity`, `category`, `id` | Signal classification data | | `tenant@linuxguard` | `id` | Tenant identifier | | `mitre@linuxguard` | `technique_id` | MITRE ATT\&CK technique mapping (when available) | **Example RFC 5424 message** ``` <19>1 2026-03-02T14:32:01.123456Z linuxguard linuxguard 12345 - [identity@linuxguard name="jsmith" type="user" risk="high"][signal@linuxguard type="sudo_command_executed" severity="4" category="privilege_escalation" id="sig_abc123"][tenant@linuxguard id="tenant_xyz"][mitre@linuxguard technique_id="T1548.003"] Sudo command executed by jsmith on web-01 ``` > **Note**: Priority value `<19>` = facility 1 (user-level) × 8 + syslog severity 3 (high) = 19. ### RFC 3164 (Legacy) RFC 3164 is the older BSD syslog format and is supported for compatibility with legacy receivers. > **Important**: RFC 3164 enforces a 1024-byte message limit. LinuxGuard truncates message content at this limit and appends `...`. Use RFC 5424 if full signal descriptions are required. ## Severity Mapping LinuxGuard maps its 1–5 signal severity scale to syslog severity levels as follows: | LinuxGuard Severity | Syslog Severity | Syslog Level Name | | ------------------- | --------------- | ----------------- | | critical (5) | 2 | Critical | | high (4) | 3 | Error | | medium (3) | 4 | Warning | | low (2) | 6 | Informational | | info (1) | 6 | Informational | > **Note**: Syslog severities 0 (Emergency) and 1 (Alert) are reserved and not used by LinuxGuard. *** **Related**: [Alerting & SIEM Integration](/concepts/concepts/alerting) | [Configure Notification Rules](/respond/respond/notification-rules) | [Webhook Integration](/respond/respond/webhook-integration) | [Splunk HEC Integration](/respond/respond/splunk-hec-integration) # Splunk HEC Integration Send LinuxGuard security signals to Splunk via the HTTP Event Collector with token authentication and index targeting. Configure LinuxGuard to forward security signals to Splunk using the HTTP Event Collector (HEC). ## Prerequisites * Access to the LinuxGuard console with administrator role * A Splunk HEC token with write access to the target index * Splunk HEC endpoint accessible from the LinuxGuard backend (host and port confirmed) ## Configure a Splunk HEC Destination 1. In the LinuxGuard console, navigate to **Settings** > **Integrations** > **Splunk HEC**. 2. Select **Add Destination**. 3. Enter the **Host**: your Splunk hostname or IP address. 4. Enter the **Port**: the HEC listener port (default: `8088`). 5. Enter the **Token**: your Splunk HEC token. LinuxGuard sends events to `https://{host}:{port}/services/collector/event` and authenticates using the `Authorization` header: ``` Authorization: Splunk ``` 6. Select **Create**. ## Sourcetype and Index LinuxGuard uses the following defaults for all delivered events. All fields are configurable. | Field | Default | Notes | | ------------ | ------------------- | -------------------------------------------------------------- | | `sourcetype` | `linuxguard:signal` | Recommended — keep the default to simplify SIEM search queries | | `source` | `linuxguard` | Identifies the sending application | | `index` | `main` | Change to your preferred index if needed | ## Event Schema Each event is delivered in Splunk HEC JSON format with a wrapper object and a flat event payload. ```json { "time": 1740923521, "host": "web-01", "source": "linuxguard", "sourcetype": "linuxguard:signal", "index": "main", "event": { "tenant_id": "", "signal_type": "sudo_command_executed", "signal_id": "sig_abc123", "severity": 4, "description": "Sudo command executed", "identity_name": "jsmith", "identity_type": "user", "server_hostname": "web-01", "server_id": "srv_xyz", "environment": "production", "category": "privilege_escalation", "created_at": "2026-03-02T14:31:58Z" } } ``` **Event fields** (fields inside `event`): | Field | Type | Description | | ----------------- | ------- | ---------------------------------------------- | | `tenant_id` | string | Your tenant identifier | | `signal_type` | string | Signal type (e.g., `sudo_command_executed`) | | `signal_id` | string | Unique signal identifier | | `severity` | integer | Signal severity: 1 (info) to 5 (critical) | | `description` | string | Human-readable signal description | | `identity_name` | string | Username or service account name | | `identity_type` | string | `user` or `service_account` | | `server_hostname` | string | Hostname of the reporting server | | `server_id` | string | Server identifier | | `environment` | string | Agent environment tag | | `category` | string | Signal category (e.g., `privilege_escalation`) | | `created_at` | string | ISO 8601 timestamp when the signal was created | ## TLS Configuration By default, LinuxGuard verifies the Splunk HEC server certificate. If your Splunk instance uses a non-standard certificate, use one of the following options: * **Internal CA or self-signed certificate (recommended)**: Provide the `ca_cert` path — LinuxGuard will trust the specified CA certificate. * **Disable TLS verification (not recommended for production)**: Set `tls_verify: false`. *** **Related**: [Alerting & SIEM Integration](/concepts/concepts/alerting) | [Configure Notification Rules](/respond/respond/notification-rules) | [Webhook Integration](/respond/respond/webhook-integration) | [Syslog Forwarding](/respond/respond/syslog-forwarding) # Audit & Comply Compliance mapping hub for LinuxGuard — three-tier vocabulary (Satisfies / Supports / Out of scope), framework version pin reference, scope statement template, and per-framework page template. LinuxGuard publishes 13 per-framework compliance mapping pages. This hub defines the binding vocabulary, version pin reference, scope-statement template, shared-responsibility statement, and per-framework page template that every mapping page in the set instantiates. Compliance officers, internal auditors, GRC analysts, and security engineers use this hub as the reference for what the per-framework pages do and do not assert. > **Note**: This hub is reference material for compliance and security teams. It is not legal advice, an audit attestation, or a substitute for an independent audit performed by a qualified assessor. Customers remain responsible for their own compliance assessments. ## What this hub covers The hub is the source of truth for four contract elements that bind every per-framework page in this directory: * **Three-tier vocabulary contract** — strict definitions of *Satisfies*, *Supports*, and *Out of scope* with usage examples per tier. Every per-framework mapping table uses these three tier labels and only these three. * **Framework version pin reference** — single source-of-truth table listing the 13 frameworks documented in this set, with version, effective date, last-verified date, and notes. Per-framework pages cite this table in their front-matter and at the top of the page. * **Scope statement template** — sentence template that every per-framework page instantiates at the top of the page to declare what is in scope and what is not in scope for that framework. * **Per-framework page template** — section-by-section shape that every per-framework page follows. Maintained as `audit-comply/_template.md` for direct copy-paste. The forbidden-words list (see [Forbidden words](#forbidden-words)) is enforced by a CI grep gate against `audit-comply/*.md`. The shared-responsibility statement (see [Shared responsibility](#shared-responsibility)) is canonical text that per-framework pages reference rather than paraphrase. ## Three-tier vocabulary contract Every per-framework control-mapping table uses one of three tier labels per control: **Satisfies**, **Supports**, or **Out of scope**. No fourth tier exists. Pages must not invent new tier names ("partially satisfies", "alternative control", "compensating") — the three-tier vocabulary is intentionally strict because audit conversations turn on it. ### Tier 1 — Satisfies *Definition.* LinuxGuard, as deployed per documented configuration, materially fulfills the control requirement. The customer must still demonstrate operational evidence to an auditor — the tier indicates that the agent's behavior alone is sufficient to address what the control text asks for, not that the auditor will treat the documentation as the evidence. A "Satisfies" claim requires: * A specific agent feature, console page, or API surface that produces the behavior the control text asks for. * A specific evidence pointer the customer can retrieve and show to an auditor (see [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) for the canonical pointer set). * A specific framework requirement number with version (e.g., PCI-DSS v4.0.1 Requirement 10.2.1.1). Usage examples (illustrative — not authoritative; per-framework pages own the actual mappings): * **PCI-DSS v4.0.1 Req 10.2.1.1 (audit log generation for individual user access to system components).** Satisfies via authentication event capture; evidence is the agent log entry with `auth.event` attribute and tamper-resistant identity attribution per [Security Architecture](/concepts/concepts/security-architecture). * **NIST CSF 2.0 DE.CM-01 (the network is monitored to detect potential cybersecurity events).** Satisfies via the agent's behavioral telemetry pipeline; evidence is the signal record on the [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) page. * **ISO/IEC 27001:2022 Annex A 8.16 (monitoring activities).** Satisfies via continuous agent telemetry on enrolled hosts; evidence is the per-server signal history. ### Tier 2 — Supports *Definition.* LinuxGuard provides telemetry, controls, or evidence that contributes to satisfying the control requirement, but full satisfaction depends on additional customer-side controls. The customer must implement those additional controls (identity management, network segmentation, physical security, policy administration, contractual measures) — LinuxGuard provides one input to the customer's control surface, not the complete control. A "Supports" claim requires: * A specific agent feature that produces partial evidence relevant to the control. * An explicit statement of what the customer must implement to achieve full satisfaction. * A specific framework requirement number with version. Usage examples (illustrative): * **PCI-DSS v4.0.1 Req 7 (restrict access to system components and cardholder data by business need to know).** Supports via SUDO rule baselines and authorization audit; full satisfaction also requires customer-administered IAM, role definition, and access review processes outside LinuxGuard. * **HIPAA 45 CFR §164.312(a)(1) (access control — unique user identification).** Supports via tamper-resistant user identity captured across privilege escalation; full satisfaction also requires the customer's IAM system, account-provisioning workflow, and identity governance program. * **SOC 2 TSC CC6.1 (logical access security software, infrastructure, and architectures).** Supports via SSH config baselines, account inventory, and configuration drift detection; full satisfaction also requires the customer's identity store, network access policy, and key management. ### Tier 3 — Out of scope *Definition.* The control concerns a domain LinuxGuard does not address. Silence is not equivalent to *Out of scope* — silence is interpreted by auditors and procurement teams as an implicit *Satisfies* claim. Every control mapping table therefore lists out-of-scope controls explicitly with a one-line note explaining why the control is out of scope for this product. An "Out of scope" claim requires: * A specific framework requirement number with version. * A one-line note stating which domain the control concerns (physical access, application-layer authentication, key management, contract management, employee training, etc.) and that the domain is not addressed by LinuxGuard. Usage examples (illustrative): * **PCI-DSS v4.0.1 Req 9 (restrict physical access to cardholder data).** Out of scope — physical access controls are not addressed by LinuxGuard. * **ISO/IEC 27001:2022 Annex A 6.3 (information security awareness, education, and training).** Out of scope — security training is a customer program responsibility not addressed by LinuxGuard. * **HIPAA 45 CFR §164.310 (physical safeguards).** Out of scope — physical safeguards (facility access, workstation security, device controls) are not addressed by LinuxGuard. ## Shared responsibility Every per-framework page includes the canonical shared-responsibility statement below verbatim. The statement frames the entire mapping set and is the basis on which auditors should read each per-framework page. > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The statement is non-negotiable. Per-framework pages do not paraphrase the statement, abbreviate it, or merge it with framework-specific language. The same wording appears on every per-framework page so that procurement teams and auditors comparing pages see consistent framing rather than per-framework variance. The three responsibility layers implied by the statement: * **LinuxGuard responsibility.** Produce the telemetry, baselines, drift detection, audit trails, and evidence artifacts that the agent's features generate. Maintain framework version pins. Publish per-framework mappings using the three-tier vocabulary. * **Customer responsibility.** Deploy LinuxGuard per documented configuration. Operate the customer-side controls (IAM, network policy, key management, training, physical security, policy administration) that complete the control surface. Maintain evidence retention, suppression decisions, and audit-period scoping. Engage a qualified assessor for audit attestation. * **Out-of-scope domains.** Controls in framework domains LinuxGuard does not address (physical access, application-layer logic, contract management, employee training, business continuity, third-party risk, and others depending on the framework). ## Framework version pin reference This is the binding version pin reference for the 13 frameworks documented in this set. Per-framework pages cite the row corresponding to their framework in their front-matter (`version`, `effective_date`, `last_verified` keys) and in a callout at the top of the page. Bumping a framework version is a deliberate change recorded in the page's `last_verified` date and the table below. | Framework | Version | Effective Date | Last Verified | Notes | | ----------------------- | ---------------------------------------- | -------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PCI-DSS | 4.0.1 | 2024-06-01 | 2026-05-31 | v3.2.1 retired 2024-03-31. Cite v4.x requirement numbers. | | HIPAA | 45 CFR §164 | 2013-03-26 (Omnibus) | 2026-05-31 | Cite specific CFR sections (Privacy / Security / Breach Notification Rules). | | SOC 2 | TSC 2017 (rev 2022) | 2022-12-15 | 2026-05-31 | Distinguish Type I vs Type II in reporting language. | | NIS2 | Directive (EU) 2022/2555 | 2024-10-17 | 2026-05-31 | Member-state transposition varies — note the specific transposing national law for each customer jurisdiction. | | DORA | Regulation (EU) 2022/2554 | 2025-01-17 | 2026-05-31 | Direct-effect regulation — no member-state transposition required. | | EU AI Act | Regulation (EU) 2024/1689 | 2024-08-01 | 2026-05-31 | Direct-effect regulation. Phased applicability: prohibited AI 2025-02-02, GPAI 2025-08-02, high-risk Annex III 2026-08-02, high-risk Annex I 2027-08-02. LinuxGuard supports Art 12 (record-keeping) and Art 15 (cybersecurity) at the host layer. | | GDPR | Regulation (EU) 2016/679 | 2018-05-25 | 2026-05-31 | Cite Article + paragraph. IP addresses are PII under EU case law — relevant to log shipping decisions. | | NIST CSF | 2.0 | 2024-02-26 | 2026-05-31 | CSF 1.1 still widely cited externally — note distinction when customers cross-reference. | | ISO/IEC 27001 | :2022 (Annex A: 93 controls) | 2022-10-25 | 2026-05-31 | :2013 transition deadline 2025-10-31. Annex A controls restructured from 114 to 93 across 4 themes. | | CIS Controls | v8.1 | 2024-06-01 | 2026-05-31 | v8 dropped from 20 to 18 controls vs v7.1. | | CIS Benchmarks | Latest per distro (pin per audit period) | varies | 2026-05-31 | Distro-specific Benchmarks (Ubuntu, RHEL, SUSE, Alpine) versioned independently. Pin a specific Benchmark version per audit period rather than tracking "latest". Distinct from CIS Controls. | | FedRAMP | Rev 5 (May 2023 baselines) + StateRAMP | 2023-05-30 | 2026-05-31 | Rev 4 phased out by ATO renewal cycle. StateRAMP draws on FedRAMP Rev 5 baselines with state-government scope. | | HITRUST CSF + FFIEC CAT | HITRUST CSF v11.x + FFIEC CAT 2017 | varies | 2026-05-31 | HITRUST versioned annually — pin a specific minor version per audit period. FFIEC CAT 2017 is the current Cybersecurity Assessment Tool; FFIEC IT Handbook booklets may also be cited. | The `Last Verified` column tracks the date each row's version pin was last reviewed against the canonical framework document. Per-framework pages MUST NOT carry a `last_verified` date older than the date in this table for their framework — a stale row blocks publication. The table is reviewed at every framework release cycle and at every milestone end. ## Forbidden words Compliance content uses precise, neutral, factual language. Marketing-tone words break the contract by implying coverage or completeness that the three-tier vocabulary intentionally refuses to assert. The following words are forbidden in `audit-comply/*.md`: * `comprehensive` * `complete coverage` * `industry-leading` * `industry leading` * `best-in-class` * `best in class` * `full coverage` * `achieves compliance` The CI grep gate at `scripts/check-compliance-tone.sh` and `.github/workflows/compliance-tone.yml` enforces zero matches across every Markdown file in this directory. The gate runs on every pull request and every push to `main`. Authors who introduce a forbidden word ship a failing CI run; the gate must pass before merge. Why the words are forbidden, grouped by category: * **Coverage-implying words** (`comprehensive`, `complete coverage`, `full coverage`). The three-tier vocabulary explicitly refuses "complete" framing — the only honest statement is per-control, per-tier, with evidence pointers. Coverage-implying words override the tier vocabulary and mislead auditors into reading the page as a global Satisfies claim. * **Marketing superlatives** (`industry-leading`, `best-in-class`). Comparative claims are unverifiable in a compliance context and damage the page's standing as audit-ready reference material. Procurement teams and auditors discount documents that read as sales collateral. * **Compliance-as-outcome wording** (`achieves compliance`). LinuxGuard, like any product, cannot "achieve compliance" — only a customer can be compliant, and only an auditor can attest to compliance. Wording that suggests otherwise misrepresents the product-customer-auditor relationship. Authors who feel a forbidden word is the right fit for a passage are encouraged to rewrite the passage around the three-tier vocabulary instead. The vocabulary itself carries the precision that the marketing word was reaching for. The HTML-comment markers `` and `` above are recognized by the grep gate as allowlist regions — content between the markers is exempt from the check. Markers exist exclusively so this hub and the per-framework template can NAME the forbidden words to declare the policy. Per-framework pages do not use the markers; using the markers in per-framework content is itself a policy violation reviewed by the human reviewer at PR time. ## Per-framework page template Every per-framework mapping page in `audit-comply/` instantiates the template at [`audit-comply/_template.md`](https://github.com/linuxguardx/linuxguard-documentation/tree/main/audit-comply/_template.md). The template is the authoritative shape — the structure below restates the template for reference. ### Section sequence 1. **YAML front-matter.** Description (one sentence ≤160 chars), keywords (5-10 entries), `framework` (canonical name), `version`, `effective_date`, `last_verified`. The version pin matches the row in the [Framework version pin reference](#framework-version-pin-reference) above. 2. **H1 title.** Framework name + version (e.g., `# PCI-DSS v4.0.1 Control Mapping`). 3. **Framework version callout.** A `> **Note**:` blockquote restating the framework version, effective date, last-verified date, and link to the canonical framework document. Reader sees the version pin without scrolling. 4. **Scope statement.** One paragraph at the top declaring what this mapping is scoped to address and what is out of scope. Uses the [Scope statement template](#scope-statement-template) below. 5. **Shared responsibility.** The canonical shared-responsibility statement from this hub, verbatim. No paraphrase. 6. **Control mapping table.** Columns: Control ID, Description (or short citation), Tier (`Satisfies` / `Supports` / `Out of scope`), Evidence, Notes. One row per control or per control group. The Tier column uses one of the three tier labels and only those three. The Evidence column points to a row in the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page; per-framework pages do not duplicate the evidence pointer set. 7. **How to share with auditor.** A short section describing the export path (PDF report from the Compliance Expansion console, support-bundle for host-level evidence, console CSV export) and the pre-share PII warning. References the [Support Bundles](/operate/operate/support-bundles) per-file redaction status table. 8. **Last reviewed.** Trailing line: `_Last reviewed: YYYY-MM-DD against [framework version] published [effective date]._` The template at [`audit-comply/_template.md`](https://github.com/linuxguardx/linuxguard-documentation/tree/main/audit-comply/_template.md) is the copy-paste source. Per-framework page authors copy the template, replace placeholders, and never delete a section. A page missing a section is incomplete by this contract. ## Scope statement template Every per-framework page declares scope with one paragraph at the top. The paragraph instantiates this template: > This page maps LinuxGuard's agent and console capabilities against \[FRAMEWORK NAME and VERSION]. The mapping is scoped to controls in \[FRAMEWORK DOMAIN — e.g., logging, access control, configuration management, network monitoring] that LinuxGuard's telemetry, baseline, drift detection, and audit features address. Controls in \[OUT-OF-SCOPE DOMAINS — e.g., physical safeguards, application-layer authentication, contractual measures, employee training] are out of scope for this product and are listed in the mapping table as `Out of scope` rather than omitted. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The template is instantiated, not paraphrased. The specific in-scope and out-of-scope domain lists vary per framework but the sentence shape stays constant so procurement and audit reviewers can compare pages mechanically. ## When-to-use guide The 13 framework pages split into three categories. Customers use the categories to decide which mapping pages apply to their deployment scenario. ### Regulated frameworks (industry-specific compliance) | Framework | When it applies | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PCI-DSS v4.0.1 | Customers processing, storing, or transmitting payment card data. Applies to any system component in the cardholder data environment (CDE) scope. | | HIPAA 45 CFR §164 | Covered entities and business associates handling protected health information (PHI) in the United States. | | SOC 2 (TSC 2017 rev 2022) | Service organizations producing SOC 2 attestation reports for customers. Common scope: Security TSC; expanded scope adds Availability, Confidentiality, Processing Integrity, Privacy. | | GDPR (EU 2016/679) | Controllers and processors handling personal data of EU residents. Relevant to log shipping decisions because IP addresses are PII under EU case law. | ### Emerging-region and government frameworks | Framework | When it applies | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | NIS2 (Directive (EU) 2022/2555) | Essential and important entities operating in the EU, transposed via national law per member state. Applies to a broader entity scope than the original NIS Directive. | | DORA (Regulation (EU) 2022/2554) | EU financial entities (banks, insurance, investment, crypto-asset service providers) and their critical third-party ICT providers. Direct-effect regulation — no member-state transposition. | | EU AI Act (Regulation (EU) 2024/1689) | Customers placing on the EU market or putting into service high-risk AI systems (Annex III) or AI systems embedded in regulated products (Annex I); also deployers operating high-risk AI systems within the EU. LinuxGuard's mapping is scoped to the host-layer logging (Art 12) and cybersecurity (Art 15) requirements. | | FedRAMP Rev 5 + StateRAMP | U.S. federal cloud service providers (FedRAMP) and state-government cloud providers (StateRAMP). StateRAMP draws on FedRAMP Rev 5 baselines with state-government scope. | | HITRUST CSF + FFIEC CAT | Healthcare organizations adopting HITRUST CSF as a unified control framework; U.S. financial institutions using the FFIEC Cybersecurity Assessment Tool. | ### Technical and standards frameworks | Framework | When it applies | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | NIST CSF 2.0 | Voluntary risk-management framework applicable to any organization. Commonly used as a parent framework that customers map their other compliance work back to. | | ISO/IEC 27001:2022 | Organizations seeking ISO/IEC 27001 certification. Annex A controls restructured from 114 (2013) to 93 (2022) across 4 themes. | | CIS Controls v8.1 | Prescriptive control set (18 controls in v8 vs 20 in v7) suitable for organizations adopting a defense-in-depth posture. Distinct from CIS Benchmarks. | | CIS Benchmarks (Linux) | Distro-specific hardening guides (Ubuntu, RHEL, SUSE, Alpine — and others) versioned independently. Used as a configuration baseline reference. Distinct from CIS Controls. | The 13 framework pages share the same vocabulary contract, the same template, and the same evidence pointer surface. Customers commonly apply two or three of these pages in parallel — e.g., a U.S. healthcare SaaS provider runs HIPAA + SOC 2 + HITRUST + (depending on customer base) PCI-DSS. The vocabulary contract makes parallel adoption cleaner because the tier labels are constant across frameworks. ## Glossary references Framework acronyms and compliance-specific terms are defined in [`reference/glossary.md`](/reference/reference/glossary). Per-framework pages link to the glossary for first-mention definitions of: * **Framework acronyms.** PCI-DSS, HIPAA, SOC 2, NIS2, DORA, GDPR, EU AI Act, NIST CSF, ISO/IEC 27001, CIS Controls, CIS Benchmarks, FedRAMP, StateRAMP, HITRUST CSF, FFIEC CAT. * **Vocabulary tiers.** Satisfies (compliance vocabulary tier), Supports (compliance vocabulary tier), Out of scope (compliance vocabulary tier). * **Compliance-specific terms.** Control mapping, scope statement, shared responsibility, evidence location, framework version pin. A glossary entry exists for every term used in this hub and in the per-framework pages. New terms introduced by a per-framework page are added to the glossary in the same change. ## Cross-references * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar surfacing the frameworks browser, evidence collection, compliance history, reports, and suppressions. The canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table lives there; per-framework pages link to that table rather than restating it. * [**Audit**](/concepts/concepts/console/audit) — console pillar covering authorizations audit and SUDO execution audit, which feed compliance evidence. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table and pre-share PII warning. Per-framework "How to share with auditor" sections reference this page. * [**Log Management**](/operate/operate/log-management) — log retention, rotation, and redaction scope. Relevant to audit-period log evidence retention. *** **Related**: [Compliance Expansion](/concepts/concepts/console/compliance-expansion) | [Audit](/concepts/concepts/console/audit) | [Support Bundles](/operate/operate/support-bundles) | [Log Management](/operate/operate/log-management) | [Glossary](/reference/reference/glossary) # PCI-DSS v4.0.1 PCI-DSS v4.0.1 control mapping — LinuxGuard agent and console capabilities aligned to Requirements 2, 6, 7, 8, 10, and 11 with Satisfies / Supports / Out of scope tiers. > **Note**: This page maps LinuxGuard against **PCI-DSS v4.0.1** (effective 2024-06-01). Last verified against the framework on 2026-05-31. Canonical framework document: [PCI Security Standards Council — PCI-DSS v4.0.1](https://www.pcisecuritystandards.org/document_library/). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). ## Scope This page maps LinuxGuard's agent and console capabilities against PCI-DSS v4.0.1. The mapping is scoped to controls in audit logging, file integrity monitoring, configuration management, identity and access tracking, and behavioral monitoring on Linux systems within the Cardholder Data Environment (CDE). Controls in cardholder data environment scope definition, network segmentation, application-layer authentication, key management, anti-malware, encryption-in-transit, physical access, and information security policy administration are out of scope for this product and are listed in the mapping table as `Out of scope` rather than omitted. This mapping is informational and not a substitute for an independent audit by a qualified assessor. Customers remain responsible for defining CDE boundaries (PCI-DSS scope), implementing and validating network segmentation, completing the annual self-assessment questionnaire or Report on Compliance, and engaging a Qualified Security Assessor (QSA) where required by their merchant level or service provider tier. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for PCI-DSS v4.0.1: * **LinuxGuard responsibility.** Produce continuous audit log generation, file-integrity monitoring telemetry, configuration baselines and drift detection, eBPF-based behavioral monitoring, and identity intelligence for Linux systems in the CDE. Maintain the framework version pin and per-control evidence pointers. * **Customer responsibility.** Define CDE scope, implement network segmentation between CDE and out-of-scope networks, administer cardholder data flows, operate application-layer authentication and authorization, manage cryptographic keys, deploy anti-malware on in-scope systems, validate quarterly vulnerability scans (ASV scans for external-facing systems), and engage a Qualified Security Assessor (QSA) where the merchant level or service provider tier requires. * **Out-of-scope domains for this framework.** Network segmentation enforcement, key management, encryption-in-transit, anti-malware, physical access controls, information security policy administration, and the contractual and training elements of Requirement 12. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. | Control ID | Description | Tier | Evidence | Notes | | -------------- | -------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Req 2.2` | Configuration standards for all system components — secure configuration baseline maintenance | `Supports` | Console Compliance Expansion → framework → control detail; Config Drift events | LinuxGuard surfaces drift against SSH config, SSHD config, account, group, sudo aliases, sudo defaults, and sudo rules baselines. Customer responsible for defining the baseline content itself and for hardening application-layer configuration. | | `Req 6.4.3` | Inventory of payment page scripts and configuration management — change detection | `Supports` | Console Zero Trust Enforcement → Config Drift; Agent log (raw events) | Drift detection surfaces unauthorized changes to monitored configuration files. Customer responsible for the application-layer script inventory (payment pages) outside LinuxGuard's monitored file set. | | `Req 7.1` | Define and document access control policy by business need to know | `Supports` | Console Audit pillar → Authorizations audit; Console Compliance Expansion → control detail | SUDO rule baselines, authorization audit, and account/group inventory provide evidence of access posture. Customer responsible for defining the access control policy and for application-layer role enforcement. | | `Req 7.2` | Establish role-based access control model for system components | `Supports` | Console Audit pillar → Authorizations audit | LinuxGuard observes and audits OS-level access (sudo rules, group membership, SSH access). Customer responsible for the role model definition and for application-layer authorization. | | `Req 8.2` | Strong authentication — unique user identification | `Supports` | Agent log (raw events) with tamper-resistant identity attribution; Console Identity Intelligence | The agent captures tamper-resistant user identity across privilege escalation, preserving non-repudiation. Customer responsible for the IAM platform, account provisioning workflow, password policy, and MFA enforcement. | | `Req 8.3.1` | All access to system components is authenticated using multi-factor authentication | `Supports` | Agent log (raw events); Console Identity Intelligence | LinuxGuard captures authentication events including method (password, publickey, keyboard-interactive). Customer responsible for MFA enforcement at the IdP or PAM layer. | | `Req 10.2.1` | Audit logs are enabled and active for all system components | `Satisfies` | Agent log (raw events) at `/var/log/linuxguard/agent.log`; Support bundle | The LinuxGuard agent generates structured audit logs continuously on every enrolled Linux host in the CDE. Log rotation defaults: 50 MB per file, 14-day retention, 5 backups, gzip compression. See [Log Management](/operate/operate/log-management). | | `Req 10.2.1.1` | Audit logs capture all individual user access to system components | `Satisfies` | Agent log (raw events) with `auth.event` attribute and tamper-resistant identity attribution | Authentication event capture records every login (success and failure) with user, source IP, method, and timestamp. | | `Req 10.2.1.2` | Audit logs capture all actions taken by any individual with administrative access | `Satisfies` | Agent log (raw events); Console Audit pillar → SUDO execution audit | SUDO execution audit and process attribution survive privilege escalation for non-repudiation. | | `Req 10.2.1.4` | Audit logs capture invalid logical access attempts | `Satisfies` | Agent log (raw events); Console Identity Intelligence → Brute Force Detection | Authentication failure events are captured continuously; brute force pattern detection surfaces in the console. | | `Req 10.2.1.7` | Audit logs capture creation and deletion of system-level objects | `Supports` | Console Zero Trust Enforcement → Config Drift; Agent log (raw events) | Drift detection across accounts and groups surfaces creation and deletion of system-level identity objects. Customer responsible for application-layer object lifecycle logging. | | `Req 10.3.1` | Audit logs are protected from unauthorized modification | `Supports` | Agent log on disk with logrotate integration | LinuxGuard writes to `/var/log/linuxguard/agent.log` with standard UNIX permissions; logrotate close+reopen via SIGHUP. Customer responsible for forwarding logs to write-once-read-many (WORM) storage or central log management for tamper resistance. | | `Req 10.4` | Audit log review — daily review of security events | `Supports` | Console Compliance Expansion → History; Console Audit pillar | Console surfaces drift events, signals, and authorization audit for daily review workflow. Customer responsible for assigning the review process and documenting reviewer sign-off. | | `Req 10.5.1` | Retain audit log history for at least 12 months with the most recent 3 months immediately available | `Supports` | Agent log rotation; Console Compliance Expansion → History | Default agent retention is 14 days locally; customers ship to central log management for the 12-month / 3-month retention requirement. See [Log Management § Central Log Collection Patterns](/operate/operate/log-management#central-log-collection-patterns). | | `Req 10.7` | Failures of critical security control systems are detected, alerted, and addressed promptly | `Supports` | Console Notifications; Agent probe status | Agent health, eBPF probe status, and connectivity errors are visible via the `probe` command and console. Customer responsible for the alerting routing and incident response workflow. | | `Req 11.5.1` | Change-detection mechanism is deployed to alert personnel to unauthorized modification of critical files | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Config Drift | File monitoring with eBPF tracks writes to sudoers, sshd\_config, passwd, shadow, authorized\_keys, and operator-configured paths. Drift events feed the console. See [Security Architecture](/concepts/concepts/security-architecture). | | `Req 11.5.2` | Change-detection mechanism alerts on modifications, additions, and deletions of critical system files | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Config Drift | eBPF Configuration File Write Detection and file baseline drift events surface modify, add, and delete operations on monitored paths. | | `Req 11.6.1` | Change- and tamper-detection mechanism for payment page header and script changes | `Out of scope` | n/a | Payment page tamper detection is an application-layer / browser-side concern not addressed by LinuxGuard. | | `Req 1` | Install and maintain network security controls | `Out of scope` | n/a | Network segmentation and firewall rule management are not addressed by LinuxGuard. | | `Req 3` | Protect stored account data | `Out of scope` | n/a | Cardholder data storage protection, key management, and tokenization are not addressed by LinuxGuard. | | `Req 4` | Protect cardholder data with strong cryptography during transmission | `Out of scope` | n/a | Encryption-in-transit for cardholder data is not addressed by LinuxGuard. | | `Req 5` | Protect all systems and networks from malicious software | `Out of scope` | n/a | Anti-malware deployment and signature management are not addressed by LinuxGuard. | | `Req 9` | Restrict physical access to cardholder data | `Out of scope` | n/a | Physical access controls are not addressed by LinuxGuard. | | `Req 12` | Support information security with organizational policies and programs | `Out of scope` | n/a | Information security policy administration, security awareness training, incident response program management, and third-party risk management are organizational responsibilities not addressed by LinuxGuard. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## How to share with auditor Three export paths are available, depending on the QSA's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (PCI-DSS v4.0.1), last-verified date, per-control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host in the CDE produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the QSA wants raw host-level telemetry rather than a console-rendered report. * **Console CSV / JSON export per control.** Compliance Expansion → PCI-DSS v4.0.1 → control detail → Evidence tab exports per-control evidence in machine-readable form for QSAs who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally — particularly relevant for CDE evidence where hostnames and process command-line arguments may correlate to systems handling cardholder data. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to the 12-month audit-period retention requirement (Req 10.5.1). * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against PCI-DSS v4.0.1 published 2024-06-01.* # HIPAA HIPAA 45 CFR §164 control mapping — LinuxGuard agent and console capabilities aligned to Security Rule technical safeguards with Satisfies / Supports / Out of scope tiers. > **Note**: This page maps LinuxGuard against **HIPAA 45 CFR §164** (Omnibus Final Rule effective 2013-03-26). Last verified against the framework on 2026-05-31. Canonical framework document: [U.S. HHS Office for Civil Rights — HIPAA Administrative Simplification 45 CFR §164](https://www.ecfr.gov/current/title-45/subtitle-A/subchapter-C/part-164). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). ## Scope This page maps LinuxGuard's agent and console capabilities against HIPAA 45 CFR §164 (Security Rule). The mapping is scoped to technical safeguards in §164.312 — audit controls, integrity, access control, and person/entity authentication — on Linux systems within the customer's HIPAA scope. Controls in the administrative safeguards of §164.308 (security management program, workforce training, contingency planning, business associate agreements) and the physical safeguards of §164.310 (facility access, workstation security, device and media controls) are largely out of scope for this product and are listed in the mapping table as `Out of scope` or `Supports` (where LinuxGuard provides partial evidence) rather than omitted. The Privacy Rule (§164.500 et seq.) and Breach Notification Rule (§164.400 et seq.) are out of scope for the agent — LinuxGuard does not process Protected Health Information (PHI). This mapping is informational and not a substitute for an independent audit by a qualified assessor. > **Important**: LinuxGuard does NOT process Protected Health Information (PHI). The agent collects operational metadata (hostnames, IPs, usernames, file paths, command-line arguments) from monitored Linux systems. This operational metadata is NOT PHI under HIPAA. Customers running LinuxGuard on systems that ALSO process PHI must implement workforce access controls, log retention, and Business Associate Agreements consistent with their HIPAA program — LinuxGuard is one input to that program, not the program itself. Customers remain responsible for executing Business Associate Agreements with covered entities and downstream business associates, designating a Security Official, conducting the §164.308(a)(1)(ii)(A) risk analysis, implementing workforce security and clearance procedures, administering contingency and disaster recovery plans, and breach notification under §164.400-414. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for HIPAA 45 CFR §164: * **LinuxGuard responsibility.** Produce continuous audit log generation, file-integrity monitoring telemetry, configuration baselines and drift detection, and identity intelligence for Linux systems within the customer's HIPAA scope. Maintain the framework version pin and per-control evidence pointers. Operational metadata captured by the agent is not PHI. * **Customer responsibility.** Designate a Security Official under §164.308(a)(2), conduct and document the risk analysis under §164.308(a)(1)(ii)(A), implement workforce security and training, manage Business Associate Agreements, operate physical safeguards (facility access, workstation security), administer encryption-in-transit and at-rest for PHI, manage cryptographic keys, and execute breach notification timelines under §164.400-414. * **Out-of-scope domains for this framework.** Physical safeguards (§164.310), workforce training and clearance (§164.308(a)(3) and (a)(5)), Business Associate Agreement administration (§164.308(b)), contingency planning (§164.308(a)(7)), encryption-in-transit (§164.312(e)), key management, and the Privacy and Breach Notification Rules. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. | Control ID | Description | Tier | Evidence | Notes | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `§164.308(a)(1)(ii)(D)` | Information system activity review — regular review of audit logs, access reports, security incident tracking | `Supports` | Console Compliance Expansion → History; Console Audit pillar | LinuxGuard provides the system activity log surface for review. Customer responsible for assigning the review workflow, documenting reviewer sign-off, and integrating with the broader information-security program. | | `§164.308(a)(3)(ii)(C)` | Termination procedures — terminate access when workforce member leaves | `Supports` | Console Identity Intelligence → Orphaned Key detection; Console Audit pillar → Authorizations audit | Orphaned SSH key detection and account/group drift surface stale access after termination. Customer responsible for the HR-driven termination workflow and IAM deprovisioning. | | `§164.308(a)(4)(ii)(B)` | Access authorization — implement policies and procedures for granting access to electronic PHI | `Supports` | Console Audit pillar → Authorizations audit | LinuxGuard audits granted access (sudo rules, group membership, SSH access). Customer responsible for the authorization policy and the access-granting workflow itself. | | `§164.308(a)(5)(ii)(C)` | Log-in monitoring — procedures for monitoring log-in attempts and reporting discrepancies | `Satisfies` | Agent log (raw events) with `auth.event` attribute; Console Identity Intelligence → Brute Force Detection | Authentication event capture records every login attempt with method, user, source IP, and timestamp. Brute force detection surfaces credential stuffing and targeted attack patterns. | | `§164.308(a)(6)(ii)` | Security incident procedures — identify, respond, and document security incidents | `Supports` | Console Zero Trust Enforcement; Agent log (raw events); Support bundle | Signals, drift events, and support bundles provide the technical evidence base for incident identification and response. Customer responsible for the incident response procedure, documentation, and notification workflow. | | `§164.308(a)(7)` | Contingency plan — data backup, disaster recovery, emergency mode operation | `Out of scope` | n/a | Contingency planning, data backup, and disaster recovery are not addressed by LinuxGuard. | | `§164.308(a)(8)` | Evaluation — periodic technical and non-technical evaluation against the Security Rule | `Supports` | Console Compliance Expansion → Reports; Console Compliance Expansion → History | LinuxGuard provides the technical evidence packet for the periodic evaluation. Customer responsible for conducting the evaluation, documenting findings, and the broader non-technical evaluation. | | `§164.310(a)` | Facility access controls — physical access to electronic information systems | `Out of scope` | n/a | Physical facility access controls are not addressed by LinuxGuard. | | `§164.310(b)` | Workstation use — policies for proper workstation use | `Out of scope` | n/a | Workstation use policy is an administrative responsibility not addressed by LinuxGuard. | | `§164.310(c)` | Workstation security — physical safeguards for workstations accessing electronic PHI | `Out of scope` | n/a | Physical workstation security is not addressed by LinuxGuard. | | `§164.310(d)` | Device and media controls — receipt and removal of hardware and electronic media | `Out of scope` | n/a | Device and media physical lifecycle controls are not addressed by LinuxGuard. | | `§164.312(a)(1)` | Access control — technical policies and procedures for systems containing electronic PHI | `Supports` | Console Audit pillar → Authorizations audit; Console Identity Intelligence | LinuxGuard provides authorization audit, account inventory, SUDO rule baselines, and identity intelligence. Customer responsible for the IAM system, role definition, and access-granting policy. | | `§164.312(a)(2)(i)` | Unique user identification — assign a unique name and/or number for identifying and tracking user identity | `Supports` | Agent log (raw events) with tamper-resistant identity attribution; Console Identity Intelligence | The agent captures tamper-resistant user identity across privilege escalation, preserving non-repudiation. Customer responsible for the IAM system, account provisioning workflow, and identity governance. | | `§164.312(a)(2)(iii)` | Automatic logoff — terminate an electronic session after a predetermined time of inactivity | `Out of scope` | n/a | Session timeout enforcement at the application or PAM layer is not addressed by LinuxGuard. | | `§164.312(a)(2)(iv)` | Encryption and decryption — encrypt and decrypt electronic PHI | `Out of scope` | n/a | Encryption-at-rest and key management for PHI are not addressed by LinuxGuard. | | `§164.312(b)` | Audit controls — implement hardware, software, and procedural mechanisms that record and examine activity in information systems containing electronic PHI | `Satisfies` | Agent log (raw events) at `/var/log/linuxguard/agent.log`; Console Audit pillar; Support bundle | The agent generates structured audit logs continuously on every enrolled Linux host. Authentication events, file integrity events, SUDO execution events, and configuration drift events are recorded. See [Log Management](/operate/operate/log-management). | | `§164.312(c)(1)` | Integrity — protect electronic PHI from improper alteration or destruction | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Config Drift | File monitoring with eBPF tracks writes to sudoers, sshd\_config, passwd, shadow, authorized\_keys, and operator-configured paths. Drift detection surfaces unauthorized modification of the configuration files that protect electronic PHI access. | | `§164.312(c)(2)` | Mechanism to authenticate electronic PHI — confirm that electronic PHI has not been altered or destroyed in an unauthorized manner | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Config Drift | File baseline integrity verification via hash, permission, and ownership comparison surfaces unauthorized modification. | | `§164.312(d)` | Person or entity authentication — verify that a person or entity seeking access to electronic PHI is the one claimed | `Supports` | Agent log (raw events); Console Identity Intelligence | LinuxGuard captures authentication events including method (password, publickey, keyboard-interactive). Customer responsible for the IAM platform, password policy, MFA enforcement, and identity verification workflow. | | `§164.312(e)(1)` | Transmission security — guard against unauthorized access to electronic PHI being transmitted over an electronic communications network | `Out of scope` | n/a | Encryption-in-transit and transmission integrity for PHI are not addressed by LinuxGuard. | | `§164.400-414` | Breach Notification Rule | `Out of scope` | n/a | Breach notification timeline and notification workflow are not addressed by LinuxGuard. Agent log evidence may be useful as supporting material for incident investigation under the customer's breach notification procedure. | | `§164.500 et seq.` | Privacy Rule | `Out of scope` | n/a | Privacy Rule controls (uses and disclosures, individual rights, minimum necessary) are not addressed by LinuxGuard — the agent does not process PHI. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## How to share with auditor Three export paths are available, depending on the auditor's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (HIPAA 45 CFR §164), last-verified date, per-control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the auditor wants raw host-level telemetry rather than a console-rendered report. * **Console CSV / JSON export per control.** Compliance Expansion → HIPAA → control detail → Evidence tab exports per-control evidence in machine-readable form for auditors who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Although LinuxGuard does not capture PHI, hostnames and file paths from systems that process PHI may be considered sensitive within the customer's HIPAA program. Review every evidence package before sharing externally. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to audit-period evidence. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against HIPAA 45 CFR §164 (Omnibus Final Rule) published 2013-03-26.* # SOC 2 SOC 2 TSC 2017 (rev 2022) control mapping — LinuxGuard agent and console capabilities aligned to Common Criteria and supplemental TSC categories with Satisfies / Supports / Out of scope tiers. > **Note**: This page maps LinuxGuard against the AICPA **SOC 2 Trust Services Criteria 2017 (revised 2022)** (effective 2022-12-15). Last verified against the framework on 2026-05-31. Canonical framework document: [AICPA — 2017 Trust Services Criteria (Revised 2022)](https://www.aicpa-cima.com/resources/download/2017-trust-services-criteria-with-revised-points-of-focus-2022). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). ## Scope This page maps LinuxGuard's agent and console capabilities against the AICPA Trust Services Criteria 2017 (revised 2022). The mapping is scoped to controls in the Common Criteria (CC1-CC9), specifically CC6 (Logical and Physical Access), CC7 (System Operations), and CC8 (Change Management), plus the supplemental Trust Services categories for Availability (A1), Processing Integrity (PI1), and Confidentiality (C1). Controls in the Privacy category (P1-P8) are out of scope for the agent — LinuxGuard does not process personal data on customer behalf — and are listed in the mapping table as `Out of scope` rather than omitted. This mapping is informational and not a substitute for an independent audit by a qualified assessor. Customers remain responsible for selecting the SOC 2 report type (Type I covers design at a point in time; Type II covers operating effectiveness over a period), defining the system description and control objectives, executing the audit period activities, retaining a CPA firm to perform the audit, and remediating any control deficiencies identified. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for SOC 2 TSC 2017 (rev 2022): * **LinuxGuard responsibility.** Produce continuous system access logging, behavioral monitoring, configuration baselines, drift detection, and identity intelligence for Linux systems in the SOC 2 audit scope. Maintain the framework version pin and per-control evidence pointers. Provide auditor-shareable evidence packages via the console. * **Customer responsibility.** Define the system description, identify the controls relevant to the selected Trust Services Criteria, design and operate management-level controls (governance, risk assessment, board oversight), administer the IAM platform and identity governance program, manage cryptographic keys and encryption, operate the business continuity and incident response programs, manage vendor relationships, and engage a CPA firm for attestation. * **Out-of-scope domains for this framework.** Privacy criteria (P1-P8), management governance controls, board oversight, vendor management, business continuity planning, and the customer's chosen application-layer controls. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. | Control ID | Description | Tier | Evidence | Notes | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `CC6.1` | Logical and physical access — implement logical access security software, infrastructure, and architectures over protected information assets | `Supports` | Console Audit pillar → Authorizations audit; Console Identity Intelligence; Config Drift events on SSHD/SSH baselines | LinuxGuard surfaces SSH configuration baselines, account inventory, SUDO rule baselines, and authorization audit. Customer responsible for the IAM platform, role definition, network access policy, and key management. | | `CC6.2` | Prior to issuing system credentials, registration and authorization of new internal and external users | `Supports` | Console Identity Intelligence; Console Audit pillar → Authorizations audit | LinuxGuard observes account creation events and tracks who has access. Customer responsible for the credential registration workflow, identity proofing, and approval gates. | | `CC6.3` | Manage points of access (interfaces, ports, protocols) — restrict access to authorized users | `Supports` | Console Zero Trust Enforcement → Config Drift on SSHD config | SSHD configuration baseline and drift detection surface unauthorized changes to system access points. Customer responsible for network access policy and firewall configuration. | | `CC6.6` | Implement logical access security measures to protect against threats from sources outside system boundaries | `Satisfies` | Agent log (raw events); Console Identity Intelligence → Brute Force Detection | eBPF-based authentication event capture records every login attempt with source IP, method, and timestamp. Brute force and targeted attack detection surface external threat patterns. | | `CC6.7` | Restrict transmission, movement, and removal of information to authorized users | `Out of scope` | n/a | Data loss prevention and information transmission controls are not addressed by LinuxGuard. | | `CC6.8` | Implement controls to prevent or detect and act upon the introduction of unauthorized or malicious software | `Supports` | Console Zero Trust Enforcement → Config Drift; Agent log (raw events) | File monitoring detects unauthorized modification of security-critical configuration files. Customer responsible for anti-malware deployment, software allowlisting, and supply-chain controls. | | `CC7.1` | Use detection and monitoring procedures to identify changes that may introduce new vulnerabilities | `Supports` | Console Zero Trust Enforcement → Config Drift; Config Drift events on six baselines | Drift detection across SSH, SSHD, accounts, groups, sudo, and SSH keys surfaces configuration changes. Customer responsible for vulnerability scanning, patch management, and the broader change-control program. | | `CC7.2` | Monitor system components and the operation of controls for anomalies indicative of malicious acts | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Signals | eBPF-based behavioral telemetry pipeline monitors processes, file access, and authentication events continuously. Signal records surface in the Zero Trust Enforcement console. | | `CC7.3` | Evaluate security events to determine whether they could or have resulted in a failure of the entity to meet its objectives | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Audit pillar | Signal records with process attribution, identity context, and confidence levels (HIGH/MEDIUM/LOW) enable evaluation of security events against objectives. | | `CC7.4` | Respond to identified security incidents through a defined incident-response program | `Supports` | Console Active Response; Support bundle; Agent log (raw events) | Active response playbooks and support bundle collection provide technical incident response capability. Customer responsible for the incident response program, escalation paths, and post-incident review. | | `CC7.5` | Identify, develop, and implement activities to recover from identified security incidents | `Out of scope` | n/a | Recovery program development, disaster recovery planning, and business continuity are not addressed by LinuxGuard. | | `CC8.1` | Authorize, design, develop or acquire, configure, document, test, approve, and implement changes to infrastructure, data, software, and procedures | `Supports` | Console Zero Trust Enforcement → Config Drift; Console Audit pillar → SUDO execution audit | Drift detection and SUDO execution audit surface infrastructure and configuration changes. Customer responsible for the change authorization workflow, change advisory board, and approval gates. | | `CC9.1` | Identify, select, and develop risk mitigation activities for risks arising from potential business disruptions | `Out of scope` | n/a | Business continuity risk identification and disaster recovery planning are not addressed by LinuxGuard. | | `CC9.2` | Assess and manage risks associated with vendors and business partners | `Out of scope` | n/a | Third-party risk management is not addressed by LinuxGuard. | | `A1.1` | Maintain processing capacity to meet system availability commitments | `Supports` | Console Infrastructure; Console Notifications on agent health | Agent health and console availability visibility support capacity monitoring. Customer responsible for capacity planning, autoscaling, and the broader availability program. | | `A1.2` | Authorize, design, develop, implement, operate, approve, maintain, and monitor environmental protections, software, data backup, and recovery infrastructure | `Out of scope` | n/a | Environmental protections, backup, and recovery infrastructure are not addressed by LinuxGuard. | | `PI1.1` | Obtain or generate, use, and communicate relevant, quality information regarding system processing objectives | `Supports` | Console Compliance Expansion → Reports; Console Audit pillar | LinuxGuard provides telemetry-driven evidence of system processing objectives. Customer responsible for defining processing objectives and the information-quality program. | | `PI1.4` | Implement policies and procedures to make available or deliver output completely, accurately, and timely | `Supports` | Console Zero Trust Enforcement → Config Drift | Drift detection surfaces unauthorized changes that could affect output integrity. Customer responsible for the application-layer output validation. | | `C1.1` | Identify and maintain confidential information to meet confidentiality commitments | `Out of scope` | n/a | Information classification and confidentiality program administration are not addressed by LinuxGuard. | | `C1.2` | Dispose of confidential information to meet confidentiality commitments | `Out of scope` | n/a | Information disposal and sanitization are not addressed by LinuxGuard. | | `P1.1 - P8.1` | Privacy criteria — notice, choice, collection, use/retention/disposal, access, disclosure, quality, monitoring | `Out of scope` | n/a | Privacy criteria are not addressed by LinuxGuard. The agent does not process personal data on customer's behalf — operational metadata (hostnames, IPs, usernames, paths) is collected for security monitoring purposes. | | `CC1.x` | Control environment — management governance, board oversight, organizational structure, commitment to integrity | `Out of scope` | n/a | Management-level governance controls are organizational responsibilities not addressed by LinuxGuard. | | `CC2.x` | Communication and information — internal and external communication of objectives and responsibilities | `Out of scope` | n/a | Communication program controls are organizational responsibilities not addressed by LinuxGuard. | | `CC3.x` | Risk assessment — specify objectives, identify and analyze risk, assess fraud risk | `Out of scope` | n/a | Risk assessment program controls are organizational responsibilities not addressed by LinuxGuard. | | `CC4.x` | Monitoring activities — ongoing and separate evaluations | `Supports` | Console Compliance Expansion → History; Console Compliance Expansion → Reports | LinuxGuard provides the technical evidence base for monitoring activities. Customer responsible for the monitoring program design and management evaluation. | | `CC5.x` | Control activities — selection and development of control activities, technology general controls, policies and procedures | `Supports` | Console Compliance Expansion → control detail | LinuxGuard provides telemetry-driven evidence of control activity operating effectiveness. Customer responsible for control design, policy administration, and procedure documentation. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## How to share with auditor Three export paths are available, depending on the CPA's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (SOC 2 TSC 2017 rev 2022), last-verified date, per-control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. For a Type II engagement, generate reports across the audit period to demonstrate operating effectiveness. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the CPA wants raw host-level telemetry rather than a console-rendered report. * **Console CSV / JSON export per control.** Compliance Expansion → SOC 2 → control detail → Evidence tab exports per-control evidence in machine-readable form for CPAs who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to Type II audit-period evidence. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against SOC 2 TSC 2017 (revised 2022) published 2022-12-15.* # GDPR GDPR Regulation (EU) 2016/679 control mapping — LinuxGuard agent and console capabilities aligned to Article 32 security of processing with IP-as-PII gotcha and Satisfies / Supports / Out of scope tie > **Note**: This page maps LinuxGuard against the EU **General Data Protection Regulation (Regulation (EU) 2016/679)** (effective 2018-05-25). Last verified against the framework on 2026-05-31. Canonical framework document: [EUR-Lex — Regulation (EU) 2016/679](https://eur-lex.europa.eu/eli/reg/2016/679/oj). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). > **Important**: Under GDPR (Recital 30 + CJEU Breyer C-582/14), IP addresses are personal data when they can be linked to an identifiable individual. The LinuxGuard agent log captures hostnames, source IPs, and command-line arguments verbatim per the [log redaction policy](/operate/operate/log-management). Customers processing data subject to GDPR must implement additional log access controls, retention limits, and erasure-on-request capability beyond what LinuxGuard provides. Support bundles also ship logs verbatim — review pre-share PII warning at [operate/support-bundles.md](/operate/operate/support-bundles). ## Scope This page maps LinuxGuard's agent and console capabilities against the General Data Protection Regulation (Regulation (EU) 2016/679). The mapping is scoped to Article 32 (security of processing) — technical and organizational measures to ensure a level of security appropriate to the risk — and supporting articles for breach notification (Articles 33-34) and data protection by design (Article 25). Controls in lawful basis (Article 6), data subject rights (Articles 12-22), Data Protection Impact Assessment (Article 35), records of processing activities (Article 30), and the appointment and role of the Data Protection Officer (Articles 37-39) are out of scope for this product and are listed in the mapping table as `Out of scope` rather than omitted. This mapping is informational and not a substitute for an independent legal review by a qualified data protection professional. Customers remain controllers (or processors, depending on context) of personal data and remain responsible for lawful basis determination under Article 6, transparency notices under Articles 13-14, data subject request handling under Articles 12-22, Data Protection Impact Assessments under Article 35, breach notification to the supervisory authority within 72 hours under Article 33, breach notification to data subjects under Article 34, records of processing activities under Article 30, and (where applicable) appointment of a Data Protection Officer under Article 37. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for GDPR Regulation (EU) 2016/679: * **LinuxGuard responsibility.** Produce technical security measures consistent with Article 32(1)(b) (confidentiality, integrity, availability) and Article 32(1)(d) (testing and evaluation) on Linux systems in the customer's processing environment. Maintain the framework version pin and per-control evidence pointers. Capture authentication events, file integrity events, and configuration drift events that may inform breach detection under Articles 33-34. * **Customer responsibility.** Determine the role (controller vs processor) and lawful basis under Article 6, draft and publish transparency notices under Articles 13-14, handle data subject requests (access, rectification, erasure, restriction, portability, objection) under Articles 12-22, conduct Data Protection Impact Assessments under Article 35, maintain records of processing activities under Article 30, notify the supervisory authority of personal data breaches within 72 hours under Article 33, notify affected data subjects under Article 34, appoint a Data Protection Officer where required by Article 37, and implement log access controls, retention limits, and erasure-on-request capability appropriate to the personal data captured in agent logs. * **Out-of-scope domains for this framework.** Lawful basis determination, transparency notices, data subject rights handling, Data Protection Impact Assessments, records of processing activities, Data Protection Officer responsibilities, cross-border transfer controls (Chapter V), and the customer-side governance program. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. | Control ID | Description | Tier | Evidence | Notes | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Art 5(1)(f)` | Integrity and confidentiality — processed in a manner that ensures appropriate security | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Config Drift | LinuxGuard provides one technical input (authentication, file integrity, drift) to the integrity-and-confidentiality program. Customer responsible for the overall security program and for access controls beyond the OS layer. | | `Art 24` | Responsibility of the controller — implement appropriate technical and organisational measures | `Supports` | Console Compliance Expansion → Reports | LinuxGuard provides telemetry-driven evidence supporting the technical measures component. Customer responsible for the organisational measures, governance, and the controller's accountability framework. | | `Art 25(1)` | Data protection by design — implement appropriate technical and organisational measures at the time of determining the means of processing | `Supports` | Console Compliance Expansion → control detail; Config Drift events on baselines | LinuxGuard surfaces configuration baselines and drift, contributing to the technical-measures component of data protection by design. Customer responsible for incorporating data protection by design into the broader system development lifecycle. | | `Art 25(2)` | Data protection by default — only personal data necessary for each specific purpose is processed | `Out of scope` | n/a | Data minimisation decisions are a controller responsibility not addressed by LinuxGuard. The agent itself collects only operational metadata for security monitoring purposes. | | `Art 32(1)(a)` | Pseudonymisation and encryption of personal data | `Out of scope` | n/a | Pseudonymisation and encryption of customer's processed personal data are not addressed by LinuxGuard. | | `Art 32(1)(b)` | Ability to ensure the ongoing confidentiality, integrity, availability and resilience of processing systems and services | `Supports` | Agent log (raw events); Console Zero Trust Enforcement; Console Infrastructure | LinuxGuard provides continuous monitoring of system integrity (file monitor), confidentiality (authentication events), and availability (agent health) at the OS layer. Customer responsible for resilience design at the architecture layer and for application-layer integrity. | | `Art 32(1)(c)` | Ability to restore the availability and access to personal data in a timely manner in the event of a physical or technical incident | `Out of scope` | n/a | Backup, recovery, and restoration are not addressed by LinuxGuard. LinuxGuard is a security monitoring agent, not a backup product. | | `Art 32(1)(d)` | Process for regularly testing, assessing and evaluating the effectiveness of technical and organisational measures | `Supports` | `linuxguard-agent probe` command; Console Compliance Expansion → History | The probe command tests kernel, BPF, fanotify, netlink, audit, and capability prerequisites on demand. Compliance history surfaces ongoing posture evaluation. Customer responsible for the broader testing program and management evaluation. | | `Art 32(2)` | Risk assessment — take into account the risks presented by processing (accidental or unlawful destruction, loss, alteration, unauthorised disclosure of, or access to personal data) | `Supports` | Console Zero Trust Enforcement → Signals; Agent log (raw events) | Behavioral telemetry and authentication event capture provide visibility into unauthorised access attempts. Customer responsible for the risk assessment itself and the documentation of risk treatment decisions. | | `Art 32(4)` | Steps to ensure that any natural person acting under the authority of the controller or processor with access to personal data does not process them except on instructions | `Supports` | Console Audit pillar → SUDO execution audit; Agent log (raw events) with tamper-resistant identity attribution | SUDO execution audit and tamper-resistant identity capture across privilege escalation provide evidence of administrator actions. Customer responsible for the authorisation policy and personnel instructions. | | `Art 33(1)` | Notification of a personal data breach to the supervisory authority within 72 hours | `Supports` | Agent log (raw events) with timestamps; Console Zero Trust Enforcement → Signals; Support bundle | Agent log timestamps and signal records provide the technical timeline evidence supporting breach notification. Customer responsible for the breach assessment, supervisory authority notification workflow, and the 72-hour timeline operationally. | | `Art 33(3)` | Content of the breach notification — nature of breach, categories and approximate number of data subjects and records, contact point, consequences, measures taken | `Supports` | Console Zero Trust Enforcement → Signals; Support bundle; Agent log (raw events) | Signal records, agent logs, and support bundles provide source evidence for the notification content. Customer responsible for synthesising the notification and identifying affected data subjects. | | `Art 33(5)` | Documentation of personal data breaches — facts, effects, remedial action | `Supports` | Console Compliance Expansion → History; Agent log (raw events); Support bundle | Console history and bundle evidence provide the technical documentation surface. Customer responsible for the documentation workflow, remedial action tracking, and the broader incident management program. | | `Art 34` | Communication of a personal data breach to the data subject | `Out of scope` | n/a | Data subject notification workflow and content are controller responsibilities not addressed by LinuxGuard. | | `Art 35` | Data Protection Impact Assessment | `Out of scope` | n/a | DPIA conduct, documentation, and supervisory authority consultation under Article 36 are controller responsibilities not addressed by LinuxGuard. | | `Art 6` | Lawfulness of processing — lawful basis (consent, contract, legal obligation, vital interests, public task, legitimate interests) | `Out of scope` | n/a | Lawful basis determination is a controller responsibility not addressed by LinuxGuard. | | `Arts 12-22` | Data subject rights — transparency, information, access, rectification, erasure, restriction, portability, objection, automated decision-making | `Out of scope` | n/a | Data subject rights handling is a controller responsibility not addressed by LinuxGuard. Customer must implement an erasure-on-request workflow for personal data captured in agent logs (hostnames, IPs, usernames) if their data subjects are within scope. | | `Art 30` | Records of processing activities | `Out of scope` | n/a | Records of processing activities are a controller and processor responsibility not addressed by LinuxGuard. | | `Arts 37-39` | Data Protection Officer — designation, position, tasks | `Out of scope` | n/a | DPO appointment and responsibilities are controller and processor responsibilities not addressed by LinuxGuard. | | `Chapter V (Arts 44-50)` | Transfers of personal data to third countries or international organisations | `Out of scope` | n/a | Cross-border transfer mechanisms (adequacy decisions, Standard Contractual Clauses, Binding Corporate Rules) are not addressed by LinuxGuard. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## Agent log content and GDPR considerations Because GDPR treats IP addresses as personal data when linkable to an identifiable individual (Recital 30; CJEU C-582/14 Breyer v Bundesrepublik Deutschland), customers operating under GDPR must consider the following when deploying LinuxGuard: * **Agent log content.** The agent log at `/var/log/linuxguard/agent.log` captures hostnames, source IPs (IPv4 and IPv6), usernames, file paths, and process command-line arguments verbatim. Attribute-key redaction (`api_key`, `*_token`, `*_secret`) is applied at the slog handler; **PII is NOT additionally redacted**. See [Log Management § Redaction Scope](/operate/operate/log-management#redaction-scope) for the precise statement. * **Support bundles.** The `support-bundle collect` workflow ships `agent.log` and rotated segments verbatim up to 180 MB. Review the pre-share PII warning at [Support Bundles](/operate/operate/support-bundles) before sharing externally. * **Customer controls required.** Implement access controls on the host-level agent log (UNIX permissions, central log management with role-based access), set retention limits consistent with the controller's records-of-processing-activities and storage-limitation principles (Article 5(1)(e)), and operate an erasure-on-request workflow that covers central log archives — see [Log Management § Central Log Collection Patterns](/operate/operate/log-management#central-log-collection-patterns) for log-shipping guidance. The IP-as-PII consideration is the load-bearing reason GDPR is a frequent cross-reference from the [Log Management](/operate/operate/log-management) and [Support Bundles](/operate/operate/support-bundles) pages — those pages name LinuxGuard's redaction scope precisely so GDPR customers can plan accordingly. ## How to share with auditor Three export paths are available, depending on the supervisory authority's or auditor's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (GDPR Regulation (EU) 2016/679), last-verified date, per-control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the supervisory authority wants raw host-level telemetry rather than a console-rendered report. * **Console CSV / JSON export per control.** Compliance Expansion → GDPR → control detail → Evidence tab exports per-control evidence in machine-readable form for auditors who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. **This is the GDPR-relevant gotcha** — IP addresses in agent logs are personal data under GDPR. Review every evidence package before sharing externally; consider whether the recipient (supervisory authority, auditor, third party) is a controller-side recipient or an external transfer requiring Chapter V safeguards. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention, rotation, and the precise PII-NOT-redacted statement that is load-bearing for GDPR customers. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against GDPR Regulation (EU) 2016/679 published 2018-05-25.* # NIS2 NIS2 Directive (EU) 2022/2555 control mapping — LinuxGuard agent and console capabilities aligned to Article 21 risk management measures with member-state transposition note and Satisfies / Supports / > **Note**: This page maps LinuxGuard against the EU **Network and Information Security Directive 2 (Directive (EU) 2022/2555)** (entered into force 2023-01-16, member-state transposition deadline 2024-10-17). Last verified against the framework on 2026-05-31. Canonical framework document: [EUR-Lex — Directive (EU) 2022/2555](https://eur-lex.europa.eu/eli/dir/2022/2555/oj). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). > **Important**: NIS2 is a directive, not a regulation — each EU member state transposes the directive into national law, with the deadline for transposition having been 2024-10-17. Specific implementation requirements, designated competent authorities, supervisory powers, registration regimes, incident reporting deadlines, and administrative penalties vary by member state. This mapping is scoped to the directive's text (Article 21 risk management measures, Article 23 incident reporting) and is not a substitute for verification against the customer's national transposing law. Customers in scope of NIS2 must consult their national implementation (for example, NIS2UmsuCG in Germany, the NIS2 transposing decree in France, the National Cyber Security Bill in Ireland, the NIS2 transposition act in the Netherlands) for the binding obligations applying to their entity. ## Scope This page maps LinuxGuard's agent and console capabilities against NIS2 Directive (EU) 2022/2555. The mapping is scoped to the technical and operational measures listed in Article 21(2)(a-i) (cybersecurity risk-management measures: incident handling, business continuity, supply chain security, security of network and information systems, vulnerability handling and disclosure, policies for the effectiveness of cybersecurity risk-management measures, basic cyber hygiene practices and training, cryptography, human resources security and access control, multi-factor authentication and continuous authentication) on Linux systems within scope of the customer's NIS2 deployment. Controls in Article 20 (governance — management body accountability), Article 23 incident notification procedure timing and content beyond technical detection, Article 24 (use of European cybersecurity certification schemes), Article 25 (standardisation), governance, training programmes, third-party contractual measures, and member-state-specific registration, supervisory, and penalty regimes are out of scope for this product and are listed in the mapping table as `Out of scope` or `Supports` rather than omitted. This mapping is informational and not a substitute for an independent audit by a qualified assessor or for verification against the customer's national transposing law. Customers remain responsible for confirming whether they are an essential entity (Annex I sector) or important entity (Annex II sector), registering with their national competent authority, designating a single point of contact, conducting the Article 21(1) risk assessment, training their management body on risks and risk-management measures per Article 20(2), notifying significant incidents to the CSIRT or competent authority within the directive's tiered deadlines (early warning within 24 hours, incident notification within 72 hours, final report within one month under Article 23), and implementing the broader cybersecurity risk-management programme that the technical and operational measures support. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for NIS2 Directive (EU) 2022/2555: * **LinuxGuard responsibility.** Produce telemetry, baselines, drift detection, audit trails, and evidence artifacts on Linux systems in the customer's NIS2 scope that support the Article 21(2) technical measures (incident handling evidence, network and information systems security telemetry, vulnerability handling evidence, access control evidence). Maintain the framework version pin and per-control evidence pointers. Surface authentication events, file integrity events, behavioral signals, and configuration drift events relevant to incident detection and the technical timeline supporting the Article 23 notification procedure. * **Customer responsibility.** Confirm entity classification (essential vs important) and sector under NIS2 Annexes I and II, register with the national competent authority, designate a single point of contact and (where required by the national transposing law) a security officer, conduct the Article 21(1) risk assessment proportionate to the entity's exposure, train the management body on cybersecurity risks per Article 20(2), implement governance and policies for the effectiveness of risk-management measures, operate the Article 21(2) measures that LinuxGuard supports (incident response process, business continuity and crisis management, supply chain security including direct supplier assessments, vulnerability management programme, training programme, cryptography programme, human resources security and access control policy, MFA enforcement at the IdP layer), notify significant incidents to the CSIRT or competent authority within the Article 23 tiered deadlines, and engage with the national supervisory regime applicable to the entity. * **Out-of-scope domains for this framework.** Entity classification, registration with national authorities, management body governance and accountability, training programmes, business continuity programme administration, supplier contracting and assessment workflow, cryptography programme administration, MFA enforcement at the IdP layer, human resources security policy administration, and member-state-specific registration, supervisory, and penalty regimes. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. | Control ID | Description | Tier | Evidence | Notes | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Art 20(1)` | Management bodies of essential and important entities approve and oversee the implementation of the cybersecurity risk-management measures | `Out of scope` | n/a | Management-body governance and accountability is an organisational responsibility not addressed by LinuxGuard. | | `Art 20(2)` | Management body members follow training on cybersecurity risks and risk-management measures | `Out of scope` | n/a | Management body training is an organisational responsibility not addressed by LinuxGuard. | | `Art 21(1)` | Entities take appropriate and proportionate technical, operational and organisational measures based on risk | `Supports` | Console Compliance Expansion → Reports; Console Zero Trust Enforcement | LinuxGuard provides one technical input (continuous telemetry, baselines, drift detection) to the risk-based measures programme. Customer responsible for the risk assessment, measure selection, and proportionality determination. | | `Art 21(2)(a)` | Policies on risk analysis and information system security | `Supports` | Console Compliance Expansion → control detail; Config Drift events on baselines | LinuxGuard surfaces configuration baselines (SSH config, SSHD config, accounts, groups, sudo aliases, sudo defaults, sudo rules) and drift events that produce evidence for the information-system-security policy. Customer responsible for the policy text itself and for the broader risk-analysis programme. | | `Art 21(2)(b)` | Incident handling | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Support bundle; Console Compliance Expansion → History | LinuxGuard captures authentication events, file integrity events, behavioral signals, configuration drift events, and SUDO execution audit trails with timestamps suitable for the technical timeline supporting an Article 23 notification. Customer responsible for the incident response procedure, role assignments, communication workflow, and the Article 23 tiered notification process (24-hour early warning, 72-hour notification, 1-month final report). | | `Art 21(2)(c)` | Business continuity, such as backup management and disaster recovery, and crisis management | `Out of scope` | n/a | Backup management, disaster recovery, and crisis management are not addressed by LinuxGuard. LinuxGuard is a security monitoring agent, not a backup or BCP product. | | `Art 21(2)(d)` | Supply chain security, including security-related aspects concerning the relationships between each entity and its direct suppliers or service providers | `Supports` | Console Compliance Expansion → Reports; Agent log (raw events) | LinuxGuard provides observability for one supplier's product (LinuxGuard itself) — version pinning, framework version pins, evidence chain integrity (SHA-256 manifest) on collected evidence packages. Customer responsible for the supplier assessment programme, contractual security requirements, supply-chain risk register, and direct-supplier security review workflow. | | `Art 21(2)(e)` | Security in network and information systems acquisition, development and maintenance, including vulnerability handling and disclosure | `Supports` | Console Zero Trust Enforcement → Config Drift; Agent log (raw events); `linuxguard-agent probe` command | LinuxGuard surfaces configuration drift and runtime telemetry contributing to maintenance-phase security. The probe command tests kernel, BPF, fanotify, netlink, audit, and capability prerequisites supporting deployment-time verification. Customer responsible for the development lifecycle, the vulnerability handling and disclosure process, and the broader acquisition controls. | | `Art 21(2)(f)` | Policies and procedures to assess the effectiveness of cybersecurity risk-management measures | `Supports` | Console Compliance Expansion → History; Console Compliance Expansion → Reports | Compliance history surfaces per-framework posture trends over time supporting the effectiveness-assessment workflow. Customer responsible for the assessment policy, criteria, and management review workflow. | | `Art 21(2)(g)` | Basic cyber hygiene practices and cybersecurity training | `Supports` | Console Compliance Expansion → control detail; Config Drift events on baselines | LinuxGuard surfaces evidence of OS-layer hygiene (SSH/SSHD baselines, account inventory, drift). Customer responsible for the training programme, hygiene policy, and the broader cybersecurity awareness workflow. | | `Art 21(2)(h)` | Policies and procedures regarding the use of cryptography and, where appropriate, encryption | `Out of scope` | n/a | Cryptography policy administration and key management are not addressed by LinuxGuard. LinuxGuard uses TLS in transit to the console — the customer's cryptography programme covers application-layer encryption choices and key management. | | `Art 21(2)(i)` | Human resources security, access control policies and asset management | `Supports` | Console Audit pillar → Authorizations audit; Agent log (raw events) with tamper-resistant identity attribution; Console Identity Intelligence | LinuxGuard observes and audits OS-level access control (SUDO rules, group membership, SSH access, authentication events with tamper-resistant identity capture across privilege escalation). Customer responsible for HR security policy, joiner-mover-leaver workflow, access control policy text, asset register, and the broader IAM programme. | | `Art 21(2)(j)` | The use of multi-factor authentication or continuous authentication solutions, secured voice, video and text communications and secured emergency communication systems within the entity, where appropriate | `Supports` | Agent log (raw events); Console Identity Intelligence | LinuxGuard captures authentication events including method (password, publickey, keyboard-interactive). Customer responsible for MFA enforcement at the IdP or PAM layer and for the secured-communications programme outside the OS layer. | | `Art 21(3)` | When considering measures, entities take into account the supplier and service provider list, the quality and resilience of products and services, including security development procedures | `Supports` | Console Compliance Expansion → Reports | LinuxGuard provides supplier-side documentation including framework version pins, last-verified dates, evidence chain integrity verification (SHA-256 manifests), and per-framework mapping pages. Customer responsible for the supplier assessment process and for cross-checking supplier products against the entity's risk acceptance criteria. | | `Art 21(4)` | Entities take corrective action without undue delay when they become aware that the measures taken do not comply | `Supports` | Console Notifications; Console Compliance Expansion → control detail | Compliance Expansion surfaces per-control pass/fail status feeding the corrective-action workflow. Customer responsible for the corrective-action process, accountability assignment, and timely remediation. | | `Art 23(1)` | Notify significant incidents to the CSIRT or competent authority without undue delay | `Supports` | Agent log (raw events) with timestamps; Console Zero Trust Enforcement → Signals; Support bundle | Agent log timestamps and signal records provide the technical timeline supporting the notification. Customer responsible for the significance assessment, the CSIRT or competent authority notification workflow, and the tiered deadlines operationally. | | `Art 23(4)` | Tiered incident notification — early warning within 24 hours, incident notification within 72 hours, final report within one month | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Support bundle; Console Compliance Expansion → History | LinuxGuard supplies technical incident detection telemetry, drift events, signal records, and audit trails feeding the notification content. Customer responsible for synthesising the notification, classifying significance per the national transposing law, and the operational notification workflow within the directive's tiered deadlines. | | `Art 23(5)` | Final report contents — detailed description of the incident, its severity and impact, type of threat or root cause, mitigation measures applied, cross-border impact | `Supports` | Console Compliance Expansion → History; Support bundle; Agent log (raw events) | Console history, bundle evidence, and agent logs supply source material for the final report. Customer responsible for the report drafting, severity classification, root-cause analysis, and cross-border impact assessment. | | `Art 24` | Use of European cybersecurity certification schemes | `Out of scope` | n/a | European cybersecurity certification scheme adoption (e.g., Common Criteria EUCC) is not addressed by LinuxGuard at the framework-mapping layer. | | `Art 25` | Standardisation — Member States encourage the use of European and international standards | `Out of scope` | n/a | Standardisation programme participation is an organisational responsibility not addressed by LinuxGuard. | | `Member-state transposition specifics` | National implementation requirements, designated competent authorities, supervisory powers, registration regimes, sector-specific addenda, administrative penalty regimes | `Out of scope` | n/a | Member-state-specific implementation requirements vary by national transposing law (NIS2UmsuCG in Germany, the NIS2 transposing decree in France, the National Cyber Security Bill in Ireland, the NIS2 transposition act in the Netherlands, and equivalents elsewhere). Customer must consult their national implementation. Not addressed by LinuxGuard. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## Entity classification NIS2 distinguishes two categories of in-scope entities. Customers determine their classification before applying the Article 21 measures because the supervisory regime, registration obligations, and (in many member states) the penalty maxima differ between categories. * **Essential entities (Annex I).** Sectors include energy (electricity, district heating and cooling, oil, gas, hydrogen), transport (air, rail, water, road), banking, financial market infrastructures, health, drinking water, waste water, digital infrastructure (internet exchange points, DNS service providers, TLD name registries, cloud computing service providers, data centre service providers, content delivery networks, trust service providers, public electronic communications networks and services), ICT service management (managed service providers, managed security service providers), public administration entities, and space. * **Important entities (Annex II).** Sectors include postal and courier services, waste management, manufacture, production and distribution of chemicals, production, processing and distribution of food, manufacturing (medical devices, computer, electronic, optical products, electrical equipment, machinery, motor vehicles, trailers and other transport equipment), digital providers (online marketplaces, online search engines, social networking services platforms), and research. Within these sectors, the directive applies the size-cap rule from Article 2(1): entities exceeding the size-cap (medium-sized enterprises per Recommendation 2003/361/EC) are in scope; entities below the cap are out of scope unless the member state specifically extends scope (Article 2(2-4)). The member-state transposing law refines the threshold and may add national entities to scope. Customers in the digital infrastructure or ICT service management sectors are in scope regardless of size per Article 2(2)(b-c), reflecting the directive's expanded scope versus the original NIS Directive. Customers operating in multiple sectors are subject to the obligations of the highest-category sector in which they operate. LinuxGuard does not perform entity classification. Customers consult their national transposing law and, where required, the designated competent authority's guidance to determine classification. ## Member-state transposition considerations NIS2 is a directive (not a regulation), which means the binding obligations applying to a customer's entity are set by the national transposing law of each EU member state in which the entity operates. The directive establishes the floor — member states may impose stricter requirements, designate sector-specific competent authorities, set the size threshold separating essential from important entities at finer granularity, and define the supervisory and penalty regimes. Customers operating in multiple member states are subject to multiple national transposing laws in parallel. Implementation specifics that vary by member state include: * **Designated competent authorities and CSIRTs.** Each member state designates its competent authority (in some jurisdictions a national cybersecurity agency, in others a sector regulator) and its CSIRT. The incident notification under Article 23 is submitted to the designated CSIRT or, where the national transposing law provides, the competent authority. * **Registration regime.** Most member states require essential and important entities to register with the competent authority. The registration data, deadlines, and update obligations vary. * **Sector-specific addenda.** Member states may add national sector-specific obligations (for example, additional requirements for the energy or financial sector beyond NIS2's Annex I and Annex II classification). * **Administrative penalty regimes.** The directive sets minimum maximum administrative fines but member states may set higher caps and define the calculation basis (turnover-percentage vs fixed amount) within the floor. * **Incident-significance thresholds.** While the directive defines significant incidents in Article 23(3), member states may issue guidance refining the significance test for sector-specific contexts. This mapping is scoped to the directive's text and is not a substitute for verification against the customer's applicable national transposing law. The customer's legal and compliance function determines which national transpositions apply and what additional national obligations layer on top of the Article 21 measures mapped above. ## Incident reporting timeline and evidence NIS2 Article 23 introduces a tiered notification model that is meaningfully different from the original NIS Directive. Customers in scope must produce three artifacts on a defined timeline: * **Early warning within 24 hours** of becoming aware of the significant incident. Whether the incident is suspected to be the result of unlawful or malicious action; cross-border impact indicators; preliminary indication of severity. * **Incident notification within 72 hours** of becoming aware. Update on the early warning; initial assessment of the incident, its severity and impact; indicators of compromise where available. * **Final report within one month** of submitting the incident notification. Detailed description; severity and impact; type of threat or root cause; mitigation measures applied; cross-border impact where applicable. LinuxGuard's telemetry-driven evidence (agent log timestamps, signal records, drift events, SUDO execution audit, support-bundle archive) supports the technical content of all three artifacts. The customer's incident response procedure remains responsible for assessing significance, classifying the incident, drafting the artifacts, and meeting the directive's deadlines operationally. The console's [Compliance Expansion → History](/concepts/concepts/console/compliance-expansion#compliance-history) view and per-server signal timeline are the recommended starting points for the technical timeline content. ### Significant incident threshold Article 23(3) defines a significant incident as one that has caused or is capable of causing severe operational disruption of the services or financial loss for the entity concerned, or has affected or is capable of affecting other natural or legal persons by causing considerable material or non-material damage. The threshold is qualitative, and member-state guidance provides operational interpretations. Customers determine significance using their incident response procedure. The LinuxGuard signal record (Zero Trust Enforcement → Signals) carries severity tagging that informs the customer's significance assessment but does not substitute for it. A high-severity signal is not necessarily a significant incident under NIS2, and a significant incident may aggregate multiple lower-severity signals over time. The 24-hour early-warning deadline starts at the moment the entity becomes aware of the significant incident — not at the moment the incident occurred. Customers calibrate their detection and triage workflow against the awareness moment rather than the signal-emission moment. ### Evidence mapping per notification stage The table below maps the three Article 23 notification stages against the LinuxGuard evidence surface that supports each stage. | Stage | Deadline | Evidence sources | | --------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Early warning | Within 24 hours of awareness | Agent log timestamps for the suspected incident window; first-tier signal classification from Zero Trust Enforcement → Signals; preliminary cross-border indicators from per-server scope metadata | | Incident notification | Within 72 hours of awareness | Agent log (raw events) for the incident window; signal records with severity and category; drift events on monitored baselines; SUDO execution audit for any administrative actions in the window; initial support-bundle archive for the affected hosts | | Final report | Within 1 month of incident notification | Full agent log archive; full signal timeline; complete drift event history; SUDO execution audit; one or more support-bundle archives; Console Compliance Expansion → History annotation events covering the incident period; final mitigation evidence (configuration changes, baseline updates) | The evidence surface is the same across stages — the difference between stages is the completeness of the timeline and the analytical work the customer performs on top of it. LinuxGuard does not assign incident severity, classify cross-border impact, or determine root cause — those are customer decisions supported by the telemetry. ## Supply chain security considerations NIS2 Article 21(2)(d) requires entities to address supply chain security including the security-related aspects of relationships with their direct suppliers and service providers. The Article 21(3) requirement to take into account the supplier's product quality, resilience, and security development procedures is one of the most operationally demanding measures in the directive, particularly for entities with deep supplier dependencies. LinuxGuard is one supplier in the customer's supply chain. The Article 21(2)(d) implementation against LinuxGuard typically draws on: * **Framework version pins.** Every per-framework page in this directory cites a `version`, `effective_date`, and `last_verified` value. The customer's supplier assessment records the version pin set at the time of assessment. * **Evidence chain integrity.** Console Compliance Expansion reports include a SHA-256 manifest over the included evidence files. Support bundles include a `BUNDLE-MANIFEST.json` with per-file hashes. Both serve as tamper-evident evidence that the artifacts shared with the customer match what the agent produced. * **Per-framework mapping pages.** This page and the other 11 framework pages in this directory are the supplier-side documentation for what LinuxGuard does and does not address per framework. Customers reference the pages in their supplier assessment narratives. * **Source-of-truth verification.** The LinuxGuard agent source code at `/usr/bin/linuxguard-agent` is the binary that produces the telemetry. Customers seeking deeper assurance request supplier documentation on the agent's build pipeline, signing keys, and SBOM (separate from the per-framework mapping pages). Customers responsible for the broader supply chain programme — beyond LinuxGuard as one supplier — operate the supplier-assessment workflow, the contractual security requirements process, and the supply-chain risk register. NIS2 expects this to be an ongoing programme, not a one-time assessment, with reassessments triggered by supplier version changes, supplier security incidents, and the customer's own risk reassessment cycle. ## Article 21 measures cross-reference The Article 21(2) measures map to recurring categories that customers commonly use as the implementation lens. The table below restates the directive's measures grouped by category and points to the LinuxGuard surface the customer uses for evidence. | Category | Article 21(2) measures | LinuxGuard evidence surface | | -------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Governance and policy | (a) risk analysis and information system security policies; (f) effectiveness assessment policies | Console Compliance Expansion → Reports for ongoing posture documentation; Console Compliance Expansion → History for effectiveness trend evidence | | Incident management | (b) incident handling | Agent log; Console Zero Trust Enforcement → Signals; Support bundle; Console Compliance Expansion → History | | Resilience | (c) business continuity, backup management, disaster recovery, crisis management | Out of scope at the agent layer — see [Support Bundles](/operate/operate/support-bundles) for log retention configuration relevant to investigation continuity | | Supply chain | (d) supplier and service provider security | Framework version pins; per-control evidence pointers; SHA-256 manifest on collected support bundles | | System security | (e) acquisition, development, maintenance, vulnerability handling and disclosure | Console Zero Trust Enforcement → Config Drift; `linuxguard-agent probe` for deployment-time prerequisite verification | | Cyber hygiene and training | (g) basic hygiene; cybersecurity training | OS-layer hygiene evidence (SSH/SSHD baselines, account inventory, drift); training is customer responsibility | | Cryptography | (h) cryptography and encryption policies | Out of scope at the agent layer | | Human resources and access | (i) human resources security, access control policies, asset management | Console Audit pillar → Authorizations audit; tamper-resistant identity attribution; Console Identity Intelligence | | Authentication | (j) MFA and continuous authentication; secured communications | Authentication event capture with method telemetry; MFA enforcement remains customer-side (IdP / PAM) | Customers commonly approach NIS2 implementation by category rather than article-by-article. The mapping above lets the customer locate the evidence surface per category for their internal Article 21 readiness documentation. ### Differences from the original NIS Directive Customers transitioning from NIS (Directive (EU) 2016/1148) to NIS2 face several substantive changes beyond the directive's rename. The mapping above reflects NIS2 text only; customers maintaining historical NIS documentation should treat it as separate from this page's mapping. * **Expanded sector scope.** NIS2 covers more sectors (essential entities: 11 sectors vs NIS's operators of essential services in 7; important entities: 7 additional sectors) and applies size-cap-based scoping rather than per-entity designation by member states. * **Two-tier entity classification.** Essential entities (Annex I) and important entities (Annex II) replace NIS's operators of essential services (OES) and relevant digital service providers (RDSP) categories. * **Tiered incident notification.** NIS2's 24-hour / 72-hour / one-month tiered notification under Article 23 replaces NIS's single notification step. * **Management body accountability.** Article 20 explicitly assigns approval and oversight responsibility to the management body, and Article 20(2) requires management body training. NIS did not surface management body responsibilities in the directive text. * **Supervisory regime alignment.** NIS2 provides for proactive supervision of essential entities and ex-post supervision of important entities, with administrative fines harmonised at a minimum maximum across member states. LinuxGuard's mapping addresses the NIS2 measures as written; NIS-era mappings are not maintained. ### Operational integration patterns Customers commonly integrate LinuxGuard's evidence surface into their NIS2 readiness programme along three patterns. Each pattern requires the customer-side incident response, governance, and supplier-assessment programmes — LinuxGuard supplies one input to each pattern. * **Compliance dashboard pattern.** Console Compliance Expansion → NIS2 framework view becomes the day-to-day posture dashboard. Compliance officers and the management body review per-control coverage, per-server breakdown, and trend annotations. Drift events on baselines and signal events surface in the dashboard's history view. The customer's governance review cadence (quarterly, annually) aligns to the report-export cadence. * **Incident response integration pattern.** Agent log, signal records, and SUDO execution audit feed the customer's SIEM or central log management. The incident response team uses LinuxGuard telemetry as one source within a broader monitoring surface. Support bundles serve the forensic and post-incident review workflow. The Article 23 notification artifacts are drafted by the incident response team using LinuxGuard telemetry as evidence input. * **Audit-period evidence pattern.** Compliance Expansion → Reports produces dated evidence packages at the start and end of the audit period (and at intermediate milestones). The customer's audit file archives the evidence packages alongside the customer's own governance documentation (risk assessment, policy approvals, training records, supplier assessments). The customer-side auditor receives the evidence packages alongside the customer's narrative. Customers commonly mix two or three of the patterns. The compliance dashboard pattern is recommended as the foundation; the incident response and audit-period patterns layer on top. ## How to share with auditor Three export paths are available, depending on the auditor's or competent authority's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (NIS2 Directive (EU) 2022/2555), last-verified date, per-control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the competent authority or auditor wants raw host-level telemetry rather than a console-rendered report, particularly when reconstructing the technical timeline supporting an Article 23 notification. * **Console CSV / JSON export per control.** Compliance Expansion → NIS2 → control detail → Evidence tab exports per-control evidence in machine-readable form for auditors who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally — particularly relevant when the recipient is a national CSIRT or competent authority and when the entity also processes EU personal data under GDPR. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table and [GDPR](/audit-and-comply/audit-comply/gdpr) for the IP-as-PII consideration relevant to log-shipping decisions. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to incident reporting evidence retention. * [**GDPR**](/audit-and-comply/audit-comply/gdpr) — IP-as-PII consideration relevant to log-shipping decisions for NIS2 customers also in scope of GDPR. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against NIS2 Directive (EU) 2022/2555 published 2022-12-27, in force 2023-01-16, member-state transposition deadline 2024-10-17.* # DORA DORA Regulation (EU) 2022/2554 control mapping — LinuxGuard agent and console capabilities aligned to ICT risk management, incident reporting, and digital operational resilience testing with effective > **Note**: This page maps LinuxGuard against the EU **Digital Operational Resilience Act (Regulation (EU) 2022/2554)** (applies from 2025-01-17). Last verified against the framework on 2026-05-31. Canonical framework document: [EUR-Lex — Regulation (EU) 2022/2554](https://eur-lex.europa.eu/eli/reg/2022/2554/oj). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). > **Important**: **DORA applies from 2025-01-17**. Unlike NIS2, DORA is a direct-effect regulation — it does NOT require member-state transposition. The obligations bind in-scope EU financial entities and their critical ICT third-party service providers directly from the application date. Customers in scope must already be operating against the DORA ICT risk management framework (Chapter II), the ICT-related incident reporting regime (Chapter III), and the digital operational resilience testing requirements (Chapter V) on the application date. > **Important**: Chapter V (Articles 28-44) introduces a tiered oversight regime for ICT third-party service providers. **Security vendors providing ICT services to in-scope financial entities may be designated as critical ICT third-party service providers (CTPPs) by the European Supervisory Authorities (ESAs).** Designation as a CTPP imposes direct oversight obligations from the lead overseer (ECB, EBA, EIOPA, or ESMA depending on sector). Customers operating a financial-sector LinuxGuard deployment should review the supplier landscape against the CTPP criteria in Article 31 and, where their supplier set includes a designated CTPP, factor the oversight regime into their supplier monitoring plan. ## Scope This page maps LinuxGuard's agent and console capabilities against the Digital Operational Resilience Act (Regulation (EU) 2022/2554). The mapping is scoped to Chapter II (ICT risk management framework — Articles 5-16), Chapter III (ICT-related incident management, classification, and reporting — Articles 17-23), and Chapter V (managing of ICT third-party risk and oversight framework for critical ICT third-party service providers — Articles 28-44, in particular Articles 28-30 and 35-44) on Linux systems within scope of the customer's DORA deployment. Controls in Chapter IV (digital operational resilience testing — Articles 24-27 covering test programmes including threat-led penetration testing, vulnerability assessments, and scenario-based testing), Chapter VI (information sharing arrangements — Articles 45-46), governance at the management body level (Articles 5(2-4)), the supplier-contract content requirements of Article 30, third-party risk strategy, the financial-entity-side classification and reporting workflow, the lead overseer's powers and processes, and the broader prudential supervision regime are out of scope for this product and are listed in the mapping table as `Out of scope` or `Supports` rather than omitted. This mapping is informational and not a substitute for an independent audit by a qualified assessor. Customers remain responsible for confirming entity scope (banks, insurance and reinsurance undertakings, investment firms, payment and electronic-money institutions, central securities depositories, central counterparties, trading venues, trade repositories, crypto-asset service providers, account information service providers, crowdfunding service providers, and others enumerated in Article 2(1); micro-enterprises proportionality adjustments per Article 16), establishing the ICT risk management framework under management-body oversight, classifying ICT-related incidents per Article 18, reporting major ICT-related incidents to the competent authority per Article 19 within the regulation's tiered deadlines, conducting the digital operational resilience testing programme under Chapter IV (including threat-led penetration testing for designated entities per Article 26), administering the third-party risk strategy and supplier register under Articles 28-30, and engaging with the lead overseer's processes where their supplier set includes a designated CTPP. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for DORA Regulation (EU) 2022/2554: * **LinuxGuard responsibility.** Produce telemetry, baselines, drift detection, audit trails, and evidence artifacts on Linux systems in the customer's DORA scope supporting the Chapter II ICT risk management framework (continuous monitoring, anomaly detection evidence, ICT asset configuration evidence) and the Chapter III incident management and reporting workflow (technical timeline, authentication and access event capture, file integrity event capture, support-bundle evidence). Provide supplier-side documentation per the Chapter V third-party risk management expectations: framework version pins, per-framework mapping pages, evidence chain integrity (SHA-256 manifests). Maintain the framework version pin and per-control evidence pointers. * **Customer responsibility.** Confirm entity scope per Article 2 and Article 16, establish and maintain the ICT risk management framework under management-body oversight per Articles 5-16, classify ICT-related incidents per Article 18 and the related Regulatory Technical Standards, report major ICT-related incidents to the competent authority per Article 19 within the tiered deadlines (initial notification, intermediate report, final report), notify significant cyber threats per Article 19(2) where deemed relevant, conduct the digital operational resilience testing programme under Chapter IV including threat-led penetration testing for designated entities per Articles 26-27, administer the third-party risk strategy and the register of information per Articles 28-30, evaluate suppliers against the CTPP criteria where applicable, and engage with the lead overseer's processes for any supplier designated as a CTPP. * **Out-of-scope domains for this framework.** Management-body governance and oversight of the ICT risk management framework, financial-entity-side incident classification and reporting workflow administration, Chapter IV testing programme administration (including threat-led penetration testing engagement), Chapter V supplier-contract content requirements, third-party risk strategy administration, Chapter VI information-sharing arrangement administration, prudential supervision relationship management, and the lead overseer's processes. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. | Control ID | Description | Tier | Evidence | Notes | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Art 5(1)` | Internal governance and control framework that ensures effective and prudent management of ICT risk | `Out of scope` | n/a | Internal governance framework administration is a financial-entity responsibility not addressed by LinuxGuard. | | `Art 5(2-4)` | Management body responsibility — define, approve, oversee implementation, allocate resources, training | `Out of scope` | n/a | Management body responsibilities (definition, approval, oversight, resource allocation, training) are organisational responsibilities not addressed by LinuxGuard. | | `Art 6(1)` | Sound, well-documented, and broadly scoped ICT risk management framework | `Supports` | Console Compliance Expansion → Reports; Console Compliance Expansion → control detail | LinuxGuard provides telemetry-driven evidence supporting the technical layer of the framework. Customer responsible for the framework documentation, the risk-tolerance levels, and management body approval. | | `Art 6(2)` | ICT risk management framework includes strategies, policies, procedures, ICT protocols, and tools | `Supports` | Console Compliance Expansion → control detail; Config Drift events on baselines | LinuxGuard provides one tooling input (OS-layer telemetry, baselines, drift) to the framework's tooling layer. Customer responsible for the strategies, policies, procedures, and ICT protocols. | | `Art 8(1)` | Identification — identify, classify, document all ICT-supported business functions, roles, responsibilities, information assets, ICT assets, ICT third-party dependencies | `Supports` | Console Infrastructure; Console Compliance Expansion → control detail; Agent log (raw events) | LinuxGuard inventory of enrolled hosts, per-host configuration, and per-host signal activity contributes to ICT asset identification at the OS layer. Customer responsible for business-function mapping, information-asset classification, and the broader ICT asset register. | | `Art 9(1)` | Protection and prevention — appropriate ICT security strategies, policies, procedures, protocols, and tools | `Supports` | Console Zero Trust Enforcement → Config Drift; Console Zero Trust Enforcement → Signals; Agent log (raw events) | LinuxGuard provides OS-layer protection and prevention telemetry (auth events, drift events, signals). Customer responsible for the security strategies, policies, and broader protection programme. | | `Art 9(3)` | Maintain high levels of availability, authenticity, integrity and confidentiality of data | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals | LinuxGuard provides OS-layer evidence supporting integrity (file monitor) and confidentiality (authentication events). Customer responsible for availability engineering and data-layer confidentiality controls. | | `Art 9(4)(b)` | Authentication mechanisms — strong customer authentication, secure communication channels | `Supports` | Agent log (raw events); Console Identity Intelligence | LinuxGuard captures OS-layer authentication events including method (password, publickey, keyboard-interactive). Customer responsible for MFA, customer-authentication mechanisms, and secure-communication-channel administration. | | `Art 10(1)` | Detection — mechanisms to detect anomalous activities including ICT network performance issues, ICT-related incidents and to identify all potential material single points of failure | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Zero Trust Enforcement → Config Drift | eBPF-based behavioral telemetry, authentication event capture, drift detection, and signal classification provide continuous anomalous-activity detection at the OS layer. Single-point-of-failure identification at the architecture layer is a customer responsibility. | | `Art 10(2)` | Detection mechanisms — multiple layers of control, define alert thresholds and criteria to trigger and initiate ICT-related incident response processes | `Supports` | Console Notifications; Console Zero Trust Enforcement → Signals; Agent log (raw events) | LinuxGuard signals carry severity and category metadata feeding the customer's alerting thresholds. Customer responsible for the threshold definitions, alert routing, and incident response process. | | `Art 11(1)` | Response and recovery — ICT business continuity policy and ICT response and recovery plans | `Out of scope` | n/a | ICT business continuity policy, response and recovery plans are financial-entity responsibilities not addressed by LinuxGuard. | | `Art 12(1)` | Backup policies and procedures, restoration and recovery procedures | `Out of scope` | n/a | Backup, restoration, and recovery are not addressed by LinuxGuard. LinuxGuard is a security monitoring agent, not a backup product. | | `Art 13(1)` | Learning and evolving — capabilities and staff to gather information on vulnerabilities and cyber threats, ICT-related incidents and analyse their likely impacts | `Supports` | Console Zero Trust Enforcement → Signals; Console Compliance Expansion → History; Support bundle | LinuxGuard surfaces signal categorisation, drift event categorisation, and historical posture trends supporting the lessons-learned workflow. Customer responsible for the staff capability, the threat intelligence programme, and impact analysis. | | `Art 14(1)` | Communication — crisis communication plans, communication policies for staff and external stakeholders, public communications | `Out of scope` | n/a | Crisis communication and stakeholder communication policy administration is a financial-entity responsibility not addressed by LinuxGuard. | | `Art 17(1)` | ICT-related incident management process — record all ICT-related incidents and significant cyber threats | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Compliance Expansion → History; Support bundle | LinuxGuard captures the technical event stream (auth events, file integrity events, drift events, signals) with timestamps that feed the customer's incident record. Customer responsible for the incident record format, classification, and lifecycle workflow. | | `Art 18(1)` | Classify ICT-related incidents and determine their impact based on a number of criteria including the number of clients or financial counterparts affected, the duration of the incident, the geographical spread, the data losses, the criticality of the services affected, and the economic impact | `Supports` | Console Zero Trust Enforcement → Signals; Console Compliance Expansion → History; Support bundle | Signal records, drift event history, and SUDO execution audit provide the technical input. Customer responsible for classification against the Article 18 criteria, the impact assessment, and the related Regulatory Technical Standards. | | `Art 19(1)` | Report major ICT-related incidents to the relevant competent authority | `Supports` | Agent log (raw events) with timestamps; Console Zero Trust Enforcement → Signals; Support bundle | Agent log timestamps and signal records provide the technical timeline supporting the report. Customer responsible for the major-incident determination, the competent authority reporting workflow, and the tiered notification deadlines (initial notification, intermediate report, final report). | | `Art 19(2)` | Voluntarily notify the relevant competent authority of significant cyber threats when deemed relevant to the financial system | `Supports` | Console Zero Trust Enforcement → Signals; Agent log (raw events) | Signal records and agent log carry threat indicators supporting the voluntary notification content. Customer responsible for the relevance determination and the notification workflow. | | `Art 19(4)` | Initial notification, intermediate report, and final report — tiered reporting timeline | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Compliance Expansion → History; Support bundle | LinuxGuard telemetry supports the technical content of all three reporting stages. Customer responsible for the report drafting, the tiered timeline operationally, and synthesising the report against the Article 18 classification criteria. | | `Art 24-27` | Digital operational resilience testing — basic and advanced testing including threat-led penetration testing (TLPT) for designated entities | `Supports` | `linuxguard-agent probe` command; Console Compliance Expansion → History | The probe command tests kernel, BPF, fanotify, netlink, audit, and capability prerequisites supporting deployment-time verification within the testing programme. Customer responsible for the broader testing programme administration, including vulnerability assessments, scenario-based testing, performance and capacity testing, and threat-led penetration testing engagement under Articles 26-27. | | `Art 28(1)` | Manage ICT third-party risk as an integral component of ICT risk management | `Supports` | Console Compliance Expansion → Reports; Audit & Comply per-framework pages | LinuxGuard provides supplier-side documentation: framework version pins, per-framework mapping pages, evidence chain integrity (SHA-256 manifests). Customer responsible for the third-party risk programme covering all suppliers. | | `Art 28(4)` | Register of information on contractual arrangements with ICT third-party service providers | `Out of scope` | n/a | Maintaining the register of information is a financial-entity responsibility not addressed by LinuxGuard. | | `Art 30` | Key contractual provisions for ICT services | `Out of scope` | n/a | Supplier contractual content (description of services, locations, data processing, performance levels, exit strategies, audit rights) is a financial-entity responsibility not addressed by LinuxGuard. | | `Art 31` | Designation of critical ICT third-party service providers (CTPPs) by the ESAs | `Out of scope` | n/a | CTPP designation is an ESA process not addressed by LinuxGuard. Customers monitor the ESA designation list and adjust their supplier register accordingly. | | `Art 35-44` | Oversight framework for critical ICT third-party service providers | `Out of scope` | n/a | The oversight framework (lead overseer processes, oversight plan, on-site investigations, requests for information, recommendations, penalties) applies to designated CTPPs and the ESAs — not to financial entities directly. Customers track lead overseer activity affecting suppliers in scope. | | `Art 45-46` | Information-sharing arrangements between financial entities concerning cyber threat information and intelligence | `Out of scope` | n/a | Information-sharing arrangement administration is a financial-entity responsibility not addressed by LinuxGuard. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## Entity scope DORA applies to a broad set of EU financial entities. Article 2(1) enumerates the categories in scope; the customer's compliance function determines applicability based on entity type and supervisory perimeter. Categories explicitly in scope per Article 2(1): * Credit institutions, payment institutions, account information service providers, electronic money institutions * Investment firms, crypto-asset service providers, central securities depositories, central counterparties, trading venues, trade repositories * Managers of alternative investment funds, management companies (UCITS), data reporting service providers, insurance and reinsurance undertakings, insurance intermediaries, reinsurance intermediaries, ancillary insurance intermediaries * Institutions for occupational retirement provision (subject to proportionality), credit rating agencies, administrators of critical benchmarks, crowdfunding service providers, securitisation repositories * ICT third-party service providers — for the oversight regime under Chapter V where designated as a CTPP Article 16 establishes a simplified regime for small and non-interconnected investment firms, payment institutions exempted under Directive (EU) 2015/2366, electronic money institutions exempted under Directive 2009/110/EC, institutions exempted under Directive 2013/36/EU, and small institutions for occupational retirement provision. The simplified regime reduces (but does not eliminate) the framework's obligations on these entities, with the reduction details set by the supplementing technical standards. LinuxGuard does not perform entity classification or determine simplified-regime applicability. Customers consult their lead competent authority and (where applicable) the ESAs for entity-specific scoping. ## Effective-date considerations DORA applies from **2025-01-17**. The Level 1 text (Regulation (EU) 2022/2554) is supplemented by Regulatory Technical Standards (RTS) and Implementing Technical Standards (ITS) developed by the European Supervisory Authorities (ESAs) — the European Banking Authority (EBA), the European Insurance and Occupational Pensions Authority (EIOPA), and the European Securities and Markets Authority (ESMA), with input from the European Central Bank (ECB). The RTS and ITS provide operational detail (incident classification thresholds, register-of-information format, testing programme scope criteria, supplier-contract minimum content, oversight framework procedures) that customers integrate alongside the Level 1 text. Customers should: * Treat the 2025-01-17 application date as a hard deadline for the ICT risk management framework, the incident classification and reporting workflow, and the supplier register. * Track RTS and ITS publication and amendments through their compliance function. The supplementary instruments may be amended after the application date as the ESAs iterate based on supervisory experience. * Confirm the lead competent authority for the entity's sector. For most banking entities, the national competent authority for prudential supervision is the lead competent authority for DORA. Significant institutions under the Single Supervisory Mechanism may have the ECB as their direct supervisor and the national authority as the DORA competent authority — the customer's compliance function determines the applicable arrangement. LinuxGuard does not track RTS / ITS amendments at the framework-mapping layer; the version pin in this page's front-matter reflects the Level 1 regulation only. Customers maintain their own RTS / ITS tracking. ## Chapter V third-party oversight considerations DORA's third-party oversight regime under Chapter V is the most operationally distinctive part of the regulation for security vendors. The regime introduces direct supervision of suppliers designated as Critical ICT Third-Party Service Providers (CTPPs). The designation criteria in Article 31 consider the systemic impact of the provider's failure or disruption on the financial system, the criticality of the financial entities that rely on the provider, and the degree of substitutability. For customers operating a financial-sector LinuxGuard deployment, the practical implications are: * **Supplier register impact.** Article 28(4) requires the register of information to include all contractual arrangements with ICT third-party service providers, with additional fields for designated CTPPs. The register format is standardised by ITS. * **Concentration risk monitoring.** Customers monitor concentration risk where multiple suppliers are CTPPs or where a single supplier is critical to multiple supported functions. * **Exit strategies.** Article 28(8) requires exit strategies for ICT services supporting critical or important functions, including alternative supplier identification and the transition plan. * **Audit rights.** Article 30(3) requires contractual audit rights enabling the financial entity (and the competent authority) to access the supplier's premises, systems, and documentation related to the contracted services. * **Subcontracting transparency.** Article 30(2)(f) requires contractual provisions on subcontracting of ICT services supporting critical or important functions, with the supplier disclosing its subcontracting chain. LinuxGuard's framework-mapping page set, framework version pins, evidence chain integrity, and per-control evidence pointers support the customer's supplier-monitoring workflow. The customer's third-party risk function operates the supplier register, monitors the ESA designation list, evaluates concentration risk, and administers the contractual provisions. ## Chapter II ICT risk management framework cross-reference DORA Chapter II structures the ICT risk management framework around six functions that recur across the regulation. The table below restates the functions and maps each to the LinuxGuard surface that supports the function. | Function | DORA articles | LinuxGuard evidence surface | | ------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Governance and organisation | Article 5 | Out of scope at the agent layer | | ICT risk management framework | Articles 6-7 | Console Compliance Expansion → Reports; Console Compliance Expansion → control detail; framework version pins | | Identification | Article 8 | Console Infrastructure (host inventory); Console Compliance Expansion → control detail (per-control evidence per host) | | Protection and prevention | Article 9 | Console Zero Trust Enforcement → Config Drift; Console Zero Trust Enforcement → Signals; Agent log (raw events) | | Detection | Article 10 | Console Zero Trust Enforcement → Signals (continuous behavioural detection); Console Zero Trust Enforcement → Config Drift; Agent log | | Response and recovery | Article 11 | Out of scope at the agent layer — see Operate → Support Bundles for forensic-evidence support | | Backup policies | Article 12 | Out of scope at the agent layer | | Learning and evolving | Article 13 | Console Compliance Expansion → History (trend evidence); signal categorisation history | | Communication | Article 14 | Out of scope at the agent layer | | ICT-related incident management | Articles 15, 17 | Agent log (raw events); Console Zero Trust Enforcement → Signals; Support bundle; Console Compliance Expansion → History | Customers commonly use this function-level mapping as the on-ramp for their internal DORA readiness documentation, organising evidence by function before drilling down to per-article evidence. ## Incident reporting timeline and evidence DORA Article 19 introduces a tiered reporting model for major ICT-related incidents. The RTS / ITS supplementing Article 19 define the precise timelines and content requirements; the table below restates the model at the Level 1 layer. | Stage | Trigger | Content | | -------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Initial notification | Promptly after the financial entity becomes aware of the major ICT-related incident | Preliminary information: incident classification under Article 18 criteria; impact estimate; initial mitigation actions | | Intermediate report | At an intermediate point defined by the supplementing RTS | Update on the incident progression; refined classification; updated impact assessment; mitigation actions completed | | Final report | After the incident is resolved | Root-cause analysis; complete impact assessment; lessons learned; preventive measures | The evidence surface for each stage draws on the same LinuxGuard telemetry as the customer's incident-record process: agent log timestamps, signal records, drift event history, SUDO execution audit, and support-bundle archives. The Console Compliance Expansion → History annotation events covering the incident period support the lessons-learned narrative in the final report. LinuxGuard does not classify incidents under Article 18, determine major-incident status, or schedule the tiered reports — those are customer decisions supported by the telemetry. ## Operational integration patterns Customers commonly integrate LinuxGuard's evidence surface into their DORA readiness programme along three patterns. Each pattern requires the customer-side ICT risk management framework, the incident classification and reporting workflow, and the third-party risk programme — LinuxGuard supplies one input to each pattern. * **ICT risk management framework integration pattern.** Console Compliance Expansion → DORA framework view becomes the day-to-day posture dashboard. The ICT risk function reviews per-control coverage, per-server breakdown, and trend annotations. Drift events on baselines and signal events surface in the dashboard's history view. The management body's framework approval cycle aligns to the report-export cadence (typically annual). * **Incident classification integration pattern.** Agent log, signal records, drift events, and SUDO execution audit feed the customer's SIEM or central log management. The incident response team uses LinuxGuard telemetry as one source within a broader monitoring surface. Support bundles serve the forensic and post-incident review workflow. The Article 18 classification and Article 19 reporting artifacts are drafted by the incident response team using LinuxGuard telemetry as evidence input. * **Third-party risk integration pattern.** The third-party risk function references this page, the supplier register entry for LinuxGuard, and the framework version pin. Concentration risk monitoring layers on top of the supplier register. Where the supplier set includes a designated CTPP, the function tracks the lead overseer's activity affecting the supplier. Customers commonly mix two or three of the patterns. The ICT risk management framework integration pattern is recommended as the foundation; the incident classification and third-party risk patterns layer on top. ## Cross-framework considerations Customers in scope of DORA are commonly also in scope of NIS2 (financial sector entities are listed in NIS2 Annex I), GDPR (where processing personal data of EU residents), and potentially national regulatory regimes (e.g., the German BSI's BAIT and VAIT for banking and insurance, the Swiss FINMA Circular 2023/01 for outsourcing). DORA acts as lex specialis for financial entities in scope of NIS2 — where the two frameworks overlap, DORA's requirements prevail for financial entities for the topics covered. NIS2 continues to apply for topics not covered by DORA. Operational alignment patterns customers commonly adopt: * **Single ICT risk register.** Maintain one risk register satisfying DORA Article 6 and NIS2 Article 21(1) risk-management measures, with framework-specific annotations. * **Unified incident notification workflow.** Build one incident response procedure that produces the DORA Article 19 major-incident report, the NIS2 Article 23 tiered notification, the GDPR Article 33 supervisory authority notification, and any national regulatory notifications. The customer's incident response team assesses each incident against the applicable framework thresholds. * **Supplier register reconciliation.** Maintain one supplier register satisfying DORA Article 28(4) requirements for the format and content; NIS2 Article 21(2)(d) supply chain security expectations layer on top. LinuxGuard's per-framework mapping pages share the same vocabulary contract and template. Customers operating against multiple framework pages in parallel benefit from the vocabulary consistency — a `Satisfies` claim on one framework is structurally equivalent to a `Satisfies` claim on another framework, supporting reusable evidence packaging. ### Supplier-side documentation expectations Customers in scope of DORA Article 28 expect supplier-side documentation to support their own third-party risk programme. LinuxGuard provides the following documentation surface as the supplier side of the relationship: * **Framework-mapping pages.** This page and the 11 other framework pages in this directory state per-framework coverage at the control level with three-tier vocabulary. * **Framework version pins.** Every page declares the framework version, effective date, and last-verified date in front-matter and at the top of the page. Pinning is deliberate and updates are tracked through the page's `last_verified` field. * **Evidence chain integrity.** Console Compliance Expansion reports and support-bundle archives include SHA-256 manifests over included evidence files. * **Source-of-truth verification.** The agent source code at `/usr/bin/linuxguard-agent` is the binary producing telemetry. Customers requesting deeper supplier assurance (SBOM, build pipeline attestation, signing-key provenance) receive supplier documentation separately from this framework-mapping set. Customers reference this documentation surface in their supplier register entry for LinuxGuard and in any supplier-assessment narratives required by their Article 28 third-party risk programme. ## How to share with auditor Three export paths are available, depending on the auditor's or competent authority's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (DORA Regulation (EU) 2022/2554), last-verified date, per-control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the competent authority or auditor wants raw host-level telemetry rather than a console-rendered report, particularly when reconstructing the technical timeline supporting an Article 19 major-incident report. * **Console CSV / JSON export per control.** Compliance Expansion → DORA → control detail → Evidence tab exports per-control evidence in machine-readable form for auditors who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally — particularly relevant when the recipient is a national competent authority for prudential supervision or the lead overseer for a designated CTPP, and when the entity also processes EU personal data under GDPR. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table and [GDPR](/audit-and-comply/audit-comply/gdpr) for the IP-as-PII consideration relevant to log-shipping decisions. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to incident reporting evidence retention. * [**GDPR**](/audit-and-comply/audit-comply/gdpr) — IP-as-PII consideration relevant to log-shipping decisions for DORA customers also in scope of GDPR. * [**NIS2**](/audit-and-comply/audit-comply/nis2) — DORA acts as lex specialis for financial sector entities in scope of NIS2; customers commonly map both frameworks. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against DORA Regulation (EU) 2022/2554 published 2022-12-27, applies from 2025-01-17.* # EU AI Act EU AI Act Regulation (EU) 2024/1689 control mapping — LinuxGuard host-layer telemetry for Art 12 record-keeping and Art 15 cybersecurity of high-risk AI. > **Note**: This page maps LinuxGuard against the EU **Artificial Intelligence Act (Regulation (EU) 2024/1689)** (entered into force 2024-08-01 per Article 113). Last verified against the framework on 2026-05-31. Canonical framework document: [EUR-Lex — Regulation (EU) 2024/1689](https://eur-lex.europa.eu/eli/reg/2024/1689/oj). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). > **Important**: The `effective_date` recorded in front-matter is the entry-into-force date (Article 113) — operational deadlines are staggered. **Prohibited AI practices under Chapters I and II apply from 2025-02-02. General-purpose AI (GPAI) obligations under Chapter V (together with Chapter III Section 4, Chapter VII, and Chapter XII) apply from 2025-08-02. General application — including high-risk AI systems under Annex III via Article 6(2) — applies from 2026-08-02. The obligations for high-risk AI systems embedded in regulated products under Annex I via Article 6(1) apply from 2027-08-02.** Customers in scope must determine which staggered deadline binds their AI system before relying on this mapping for evidence preparation. ## Scope This page maps LinuxGuard's agent and console capabilities against the EU AI Act (Regulation (EU) 2024/1689). The mapping is scoped to Chapter III Section 2 (Articles 8-15 — high-risk AI system technical and operational requirements) on Linux systems on which customers operate high-risk AI systems, with concentration on Article 12 (record-keeping / automatic logging of events at the host layer) and Article 15 (accuracy, robustness and cybersecurity of the runtime environment). Controls in Article 9 (AI risk management system), Article 10 (data and data governance), Article 11 (Annex IV technical documentation), Article 13 (transparency and information to deployers), Article 14 (human oversight), the AI-specific cybersecurity controls of Article 15(4-5), GPAI obligations under Chapter V, the conformity assessment under Article 43, the EU declaration of conformity under Article 47, registration in the EU database under Article 49, post-market monitoring under Article 72, and deployer-specific obligations under Article 26 are out of scope for this product and are listed in the mapping table as `Out of scope` or `Supports` rather than omitted. This mapping is informational and not a substitute for an independent audit by a qualified assessor. Customers remain responsible for confirming their role under Article 3 (provider vs deployer vs importer vs distributor), classifying the AI system (Annex III high-risk via Article 6(2), Annex I embedded high-risk via Article 6(1), limited-risk with transparency obligations under Article 50, minimal risk, or general-purpose AI model), establishing the AI risk management system under Article 9, operating the data governance programme under Article 10, drawing up the Annex IV technical documentation under Article 11, providing transparency and instructions for use to deployers under Article 13, designing and implementing human oversight under Article 14, conducting the conformity assessment under Article 43, drawing up the EU declaration of conformity under Article 47, registering the AI system in the EU database under Article 49, operating the post-market monitoring plan under Article 72, and the broader provider obligations under Articles 16-22 (or deployer obligations under Article 26) that the technical and operational measures support. LinuxGuard does not perform any of these AI-system-internal responsibilities — the agent operates at the Linux host layer beneath the AI system. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for EU AI Act Regulation (EU) 2024/1689: * **LinuxGuard responsibility.** Produce host-layer telemetry (authentication events, file integrity events, configuration baselines and drift, behavioural signals, SUDO execution audit) on the Linux infrastructure where the customer operates a high-risk AI system, supporting the Article 12 record-keeping inputs and Article 15 cybersecurity inputs the customer presents to an auditor or competent authority. Maintain the framework version pin and per-control evidence pointers. Surface the technical timeline (timestamped events, signal records, drift events, support-bundle archive) that contributes to the post-market monitoring evidence surface and to the technical incident timeline for any serious incident reportable under Article 73. * **Customer responsibility.** Confirm provider vs deployer status under Article 3(3) and Article 3(4); classify the AI system (Annex III high-risk vs Annex I embedded high-risk vs limited-risk subject to Article 50 transparency vs minimal risk vs GPAI under Chapter V); establish and operate the AI-system-internal risk management system under Article 9; administer the data and data governance programme under Article 10; draw up and maintain the Annex IV technical documentation under Article 11; design the AI system for transparency and provide instructions for use under Article 13; design and implement effective human oversight under Article 14; design and operate the AI-specific cybersecurity controls under Article 15(4-5) (model resilience against adversarial input, data poisoning, model poisoning, model evasion, confidentiality attacks); conduct the conformity assessment under Article 43; draw up the EU declaration of conformity under Article 47; register the high-risk AI system in the EU database under Article 49; operate the post-market monitoring plan under Article 72; and engage with the supervisory regime applicable to the system. * **Out-of-scope domains for this framework.** AI model risk management, training and validation and testing data governance, Annex IV technical documentation administration, deployer transparency and instructions for use, human oversight UI design, conformity assessment workflow, EU declaration of conformity drafting, EU database registration, post-market monitoring administration, GPAI provider obligations under Chapter V, sectoral integration for Annex I embedded high-risk systems, and the broader supervisory and penalty regime under Chapters VII-XII. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. | Control ID | Description | Tier | Evidence | Notes | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Art 8(1)` | High-risk AI systems comply with the requirements laid down in this Section (Arts 9-15), taking into account the intended purpose, the state of the art, and the risk management system under Art 9 | `Supports` | Console Compliance Expansion → Reports; Console Compliance Expansion → control detail | LinuxGuard provides host-layer evidence for the Art 12 (record-keeping) and Art 15 (cybersecurity) requirements that contribute to the provider's overall Art 8 compliance demonstration. Provider responsible for orchestrating compliance across all of Arts 9-15 at the AI system layer, the conformity assessment under Art 43, and the EU declaration of conformity under Art 47. | | `Art 8(2)` | Where the high-risk AI system relates to a product covered by Union harmonisation legislation listed in Annex I Section A, the provider's obligations under this Regulation are integrated with the obligations under the relevant sectoral legislation | `Out of scope` | n/a | Integration with sectoral Union harmonisation legislation (machinery, medical devices, in-vitro diagnostics, civil aviation, motor vehicles, others) is a provider responsibility not addressed by LinuxGuard. | | `Art 9` | Risk management system — establish, implement, document, and maintain a continuous iterative risk management process throughout the entire lifecycle of the high-risk AI system | `Out of scope` | n/a | The AI-system-internal risk management process (risk identification, estimation, evaluation, mitigation across the AI lifecycle) is a provider responsibility addressed at the AI system layer, not the Linux host layer. Not addressed by LinuxGuard. | | `Art 10` | Data and data governance — training, validation, and testing data sets meet the quality criteria of Art 10(2-5), including relevance, representativeness, accuracy, statistical properties, and bias examination | `Out of scope` | n/a | Training and dataset governance (data collection processes, data preparation, examination for biases, identification of data gaps, data minimisation) is an AI-provider responsibility not addressed by LinuxGuard. | | `Art 11` | Technical documentation — draw up and keep up to date the technical documentation of the high-risk AI system as set out in Annex IV before placing on the market or putting into service | `Out of scope` | n/a | Annex IV technical documentation (general description of the AI system, detailed description of the elements and development process, monitoring, functioning, control, risk management system, lifecycle changes) is a provider responsibility not addressed by LinuxGuard. | | `Art 12(1)` | Record-keeping — high-risk AI systems technically allow for the automatic recording of events (logs) over the lifetime of the system | `Supports` | Agent log (raw events); Console Audit pillar → SUDO execution audit; Console Zero Trust Enforcement → Signals | LinuxGuard captures host-layer events (authentication events, file integrity events, configuration drift events, SUDO execution audit, behavioural signals) with timestamps for the Linux environment in which the high-risk AI system runs. Provider responsible for the AI system's own application-layer automatic logging required by Art 12(1-3), including events identifying situations under Art 79(1), the period of each use, the reference database, and the natural persons involved in verification. | | `Art 12(2)` | Logging capabilities enable monitoring of operation, identification of situations resulting in risk under Art 79(1), and facilitate post-market monitoring under Art 72 | `Supports` | Console Zero Trust Enforcement → Signals; Console Compliance Expansion → History; Support bundle | Host-layer signal categorisation, drift events, and the support-bundle archive provide one input to the post-market monitoring evidence surface. Provider responsible for the AI-system-internal log content satisfying Art 12(2)(a-c) and for the Art 72 post-market monitoring plan. | | `Art 12(3)` | Logging capabilities of high-risk AI systems referred to in Annex III(1)(a) (biometric identification) record specific data — period of each use, reference database, input data, identity of natural persons involved in result verification | `Out of scope` | n/a | The Annex III(1)(a) biometric-identification-specific log fields are AI-system-internal record-keeping that LinuxGuard's host-layer telemetry does not produce. | | `Art 13` | Transparency and provision of information to deployers — design and develop high-risk AI systems so deployers can interpret the system's output and use it appropriately; provide instructions for use | `Out of scope` | n/a | Transparency design choices, output interpretability, and deployer instructions for use are AI-system properties and provider responsibilities not addressed by LinuxGuard. | | `Art 14` | Human oversight — high-risk AI systems designed and developed so that they can be effectively overseen by natural persons during the period in which they are in use | `Out of scope` | n/a | Human oversight measures (oversight interface design, ability to intervene, ability to interrupt, stop button) are AI-system properties and provider responsibilities not addressed by LinuxGuard. | | `Art 15(1)` | Accuracy, robustness and cybersecurity — high-risk AI systems designed and developed so that they achieve an appropriate level of accuracy, robustness, and cybersecurity, and perform consistently throughout their lifecycle | `Supports` | Console Zero Trust Enforcement → Config Drift; Console Zero Trust Enforcement → Signals; Agent log (raw events) | LinuxGuard provides host-layer cybersecurity telemetry (authentication events, file integrity events, configuration baselines and drift, behavioural signals) protecting the runtime environment in which the high-risk AI system operates. Provider responsible for the AI-system-internal accuracy and robustness metrics, the AI-specific cybersecurity controls under Art 15(4-5) (resilience against attempts to alter use, output, or performance through exploiting system vulnerabilities), and the lifetime declared accuracy levels and metrics in instructions for use. | | `Art 15(2)` | Levels of accuracy and relevant accuracy metrics declared in the instructions of use | `Out of scope` | n/a | AI-system-level accuracy declaration is a provider responsibility not addressed by LinuxGuard. | | `Art 15(3)` | Robustness — resilient against errors, faults, or inconsistencies; technical redundancy solutions, including backup or fail-safe plans, may be appropriate | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals | Host-layer agent health telemetry, authentication event capture, and file-integrity events surface degradations of the runtime environment that may affect AI system robustness. Provider responsible for the AI-system-internal redundancy, backup, fail-safe design, and the architecture-layer resilience choices. | | `Art 15(4)` | High-risk AI systems are resilient against attempts by unauthorised third parties to alter their use, outputs, or performance by exploiting system vulnerabilities | `Supports` | Console Audit pillar → Authorizations audit; Agent log (raw events) with tamper-resistant identity attribution; Console Zero Trust Enforcement → Signals; Console Zero Trust Enforcement → Config Drift | LinuxGuard observes OS-layer unauthorised access attempts (authentication events, signals, drift events) and provides tamper-resistant user identity capture across privilege escalation for non-repudiation of administrator actions on the AI system's host. Provider responsible for the AI-system-internal cybersecurity controls (model robustness against adversarial input, data poisoning, model evasion, model inversion, confidentiality of model artefacts) at the application layer. | | `Art 15(5)` | Technical solutions to address AI-specific vulnerabilities — measures to prevent, detect, respond to, resolve, and control for attacks attempting to manipulate the training data set (data poisoning), or pre-trained components used in training (model poisoning), inputs designed to cause the AI model to make a mistake (adversarial examples or model evasion), confidentiality attacks or model flaws | `Out of scope` | n/a | AI-specific attack mitigations (data poisoning, model poisoning, adversarial examples, model evasion, confidentiality attacks, model flaws) are AI-system-internal cybersecurity controls not addressed by LinuxGuard at the Linux host layer. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## How to share with auditor Three export paths are available, depending on the auditor's, notified body's, or competent authority's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (EU AI Act Regulation (EU) 2024/1689), last-verified date, per-control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. Reports support the Article 12 record-keeping and Article 15 cybersecurity evidence inputs the customer presents to a notified body during the Article 43 conformity assessment or to a competent authority during post-market supervision. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the auditor or competent authority wants raw host-level telemetry rather than a console-rendered report, particularly when reconstructing the technical timeline supporting an Article 73 serious-incident notification or the Article 72 post-market monitoring evidence record. * **Console CSV / JSON export per control.** Compliance Expansion → EU AI Act → control detail → Evidence tab exports per-control evidence in machine-readable form for auditors who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally — particularly relevant when the recipient is a notified body, a national competent authority, or the AI Office, and when the entity also processes EU personal data under GDPR. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table and [GDPR](/audit-and-comply/audit-comply/gdpr) for the IP-as-PII consideration relevant to log-shipping decisions. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to Art 12 record-keeping evidence retention. * [**GDPR**](/audit-and-comply/audit-comply/gdpr) — IP-as-PII consideration relevant to log-shipping decisions for EU AI Act customers also in scope of GDPR (high overlap, since EU AI Act customers commonly process personal data). * [**NIS2**](/audit-and-comply/audit-comply/nis2) — cybersecurity risk-management measures for essential and important entities in the EU; many EU AI Act customers (especially in finance, health, digital infrastructure) are also in NIS2 scope. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against EU AI Act Regulation (EU) 2024/1689 published 2024-07-12, entered into force 2024-08-01, general application 2026-08-02.* # FedRAMP / StateRAMP FedRAMP Rev 5 and StateRAMP control mapping — LinuxGuard agent and console capabilities aligned to NIST SP 800-53 Rev 5 control families AC, AU, CM, CP, IA, IR, SC, SI, SR with authorization-boundary > **Note**: This page maps LinuxGuard against **FedRAMP Rev 5 baselines** (released 2023-05-30) and **StateRAMP**, both of which derive from **NIST Special Publication 800-53 Revision 5**. Last verified against the framework on 2026-05-31. Canonical framework documents: [FedRAMP — Rev 5 Baselines](https://www.fedramp.gov/rev5/), [NIST SP 800-53 Rev 5](https://csrc.nist.gov/pubs/sp/800/53/r5/upd1/final), [StateRAMP](https://stateramp.org/). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). > **Important**: **LinuxGuard is a component, not a full system.** Customers seeking FedRAMP authorization integrate LinuxGuard into their authorization boundary as one of many system components. The authorization boundary — defined per NIST SP 800-37 Rev 2 and FedRAMP guidance — encompasses the complete information system being authorized, including all interconnections, supporting infrastructure, and inherited controls. LinuxGuard's per-control coverage applies to the agent and console functions within that boundary; the Cloud Service Provider (CSP) remains responsible for the complete System Security Plan (SSP), the authorization-boundary diagram, the data flow diagram, and the inherited-vs-customer-implemented control allocations across the full boundary. > **Important**: StateRAMP draws on FedRAMP Rev 5 baselines with state-government scope adjustments. Where this page references FedRAMP control allocations, StateRAMP customers apply the equivalent allocation under StateRAMP's adopted baseline (Low, Moderate, or High Impact) with state-specific overlays where applicable. The control IDs and content map one-to-one for the families covered; differences arise in the authorization process (3PAO assessment, PMO review, authorization body), not in the control text. ## Scope This page maps LinuxGuard's agent and console capabilities against FedRAMP Rev 5 and StateRAMP, both derived from NIST SP 800-53 Rev 5. The mapping is scoped to controls within the families that LinuxGuard's telemetry, baselines, drift detection, and audit features address: AC (Access Control), AU (Audit and Accountability), CM (Configuration Management), CP (Contingency Planning) — narrow subset, IA (Identification and Authentication), IR (Incident Response), SC (System and Communications Protection) — narrow subset, SI (System and Information Integrity), and SR (Supply Chain Risk Management) — supplier-side documentation only. Controls in the families AT (Awareness and Training), CA (Assessment, Authorization, and Monitoring) — assessment-process administration, MA (Maintenance) — outside the OS layer, MP (Media Protection), PE (Physical and Environmental Protection), PL (Planning), PM (Program Management), PS (Personnel Security), PT (PII Processing and Transparency), RA (Risk Assessment) — risk-assessment-process administration, and SA (System and Services Acquisition) — outside the OS layer, are out of scope for this product and are listed in the mapping table as `Out of scope` or `Supports` rather than omitted. This mapping is informational and not a substitute for a 3PAO independent assessment. Customers remain responsible for the System Security Plan (SSP) including the authorization-boundary definition under NIST SP 800-37 Rev 2; the control implementation summary and customer-responsibility matrix; the inherited-control allocations from underlying IaaS / PaaS providers; engagement of a Third Party Assessment Organization (3PAO) for FedRAMP Moderate / High assessments or the StateRAMP equivalent; the System Assessment Report (SAR) and Plan of Action and Milestones (POA\&M); the Authorization to Operate (ATO) package; continuous monitoring per NIST SP 800-137; and the Significant Change Authorization process for changes affecting the authorization boundary. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for FedRAMP Rev 5 + StateRAMP: * **LinuxGuard responsibility.** Produce telemetry, baselines, drift detection, audit trails, and evidence artifacts on Linux systems within the customer's authorization boundary supporting the AC, AU, CM, IA, IR, SC, SI, and SR control families. Maintain the framework version pin and per-control evidence pointers. Capture authentication events, file integrity events, configuration drift events, behavioral signals, SUDO execution audit, and support-bundle evidence that feed the customer's continuous monitoring obligations and incident response workflow. * **Customer responsibility.** Define the authorization boundary per NIST SP 800-37 Rev 2 and FedRAMP guidance; draft the System Security Plan and the customer-responsibility matrix; allocate controls between inherited (from underlying IaaS / PaaS), shared, system-specific, and component-specific (LinuxGuard) implementations; engage the 3PAO; produce the SAR and POA\&M; obtain and maintain the ATO; operate the continuous monitoring programme per NIST SP 800-137 including monthly POA\&M updates and annual control reassessments; and administer the Significant Change Authorization process. For StateRAMP customers, follow the StateRAMP authorization process and PMO review workflow. * **Out-of-scope domains for this framework.** Authorization boundary definition, SSP authoring, 3PAO engagement, ATO maintenance, AT family (training), MP family (media protection), PE family (physical protection), PL family (planning), PM family (program management), PS family (personnel security), PT family (PII processing and transparency at the application layer), and the assessment-process administration aspects of CA and RA. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. ### Access Control (AC) | Control ID | Description | Tier | Evidence | Notes | | ---------- | --------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AC-2` | Account Management — establish, enable, modify, disable, remove accounts | `Supports` | Console Audit pillar → Authorizations audit; Console Compliance Expansion → Config Drift on accounts baseline; Agent log (raw events) | LinuxGuard surfaces account inventory and drift on accounts baseline supporting account-management evidence. Customer responsible for IAM workflow (provisioning, modification, deprovisioning) and account-management policy. | | `AC-3` | Access Enforcement — enforce approved authorizations | `Supports` | Agent log (raw events) with tamper-resistant identity attribution; Console Audit pillar → SUDO execution audit | Tamper-resistant identity capture across privilege escalation provides evidence of access enforcement at the OS layer. Customer responsible for the access-enforcement mechanism (PAM, LDAP, SSO) and the policy administered through it. | | `AC-6` | Least Privilege — principle of least privilege for accounts and processes | `Supports` | Console Audit pillar → SUDO execution audit; Console Compliance Expansion → control detail; Config Drift on sudo rules and sudo defaults baselines | SUDO rule baselines, sudo defaults baseline, and SUDO execution audit support least-privilege evidence. Customer responsible for the privilege-allocation decisions and the broader least-privilege policy. | | `AC-7` | Unsuccessful Logon Attempts — automatic account lockout after configurable number of attempts | `Supports` | Agent log (raw events); Console Identity Intelligence → Brute Force Detection | Authentication failure capture and brute-force detection surface unsuccessful logon patterns. Customer responsible for the account-lockout enforcement (PAM `pam_faillock` or equivalent) and lockout policy. | ### Audit and Accountability (AU) | Control ID | Description | Tier | Evidence | Notes | | ---------- | --------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AU-2` | Event Logging — identify event types selected for logging | `Satisfies` | Agent log (raw events) at `/var/log/linuxguard/agent.log`; Support bundle | LinuxGuard generates structured audit logs continuously on every enrolled Linux host, covering authentication, file integrity, configuration changes, and SUDO execution. See [Log Management](/operate/operate/log-management). | | `AU-3` | Content of Audit Records — record content of events sufficient for after-the-fact investigations | `Satisfies` | Agent log (raw events) with tamper-resistant identity attribution, source IP, user, method, timestamp, command | Agent log records carry tamper-resistant user identity attribution, source, method, and timestamp on each event supporting investigation reconstruction. | | `AU-6` | Audit Record Review, Analysis, and Reporting — review and analyse audit records | `Supports` | Console Compliance Expansion → History; Console Zero Trust Enforcement → Signals | Console surfaces signals, drift events, and authorization audit for the review workflow. Customer responsible for the review cadence, reviewer assignment, and analysis reporting. | | `AU-9` | Protection of Audit Information — protect audit records from unauthorised modification | `Supports` | Agent log on disk with logrotate integration; Support bundle | LinuxGuard writes to `/var/log/linuxguard/agent.log` with standard UNIX permissions; logrotate close+reopen via SIGHUP. Customer responsible for forwarding to write-once central log management for tamper resistance and for the WORM / hash-chain configuration on the receiving system. | | `AU-11` | Audit Record Retention — retain audit records consistent with records retention policy | `Supports` | Agent log rotation (`logging.max_age_days`); Console Compliance Expansion → History | Default agent retention is 14 days locally; customers ship to central log management for the federal records retention requirement. See [Log Management § Central Log Collection Patterns](/operate/operate/log-management#central-log-collection-patterns). | | `AU-12` | Audit Record Generation — provide audit record generation capability for the events defined in AU-2 | `Satisfies` | Agent log (raw events) | Continuous audit record generation by the agent on every enrolled host. | ### Configuration Management (CM) | Control ID | Description | Tier | Evidence | Notes | | ---------- | ----------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CM-2` | Baseline Configuration — develop, document, and maintain a current baseline configuration | `Supports` | Console Compliance Expansion → control detail; Config Drift events on baselines | LinuxGuard surfaces drift against SSH config, SSHD config, accounts, groups, sudo aliases, sudo defaults, and sudo rules baselines. Customer responsible for defining the baseline content and for application-layer baseline configurations. | | `CM-3` | Configuration Change Control — determine and document configuration changes | `Supports` | Console Zero Trust Enforcement → Config Drift; Agent log (raw events) | Drift detection surfaces configuration changes against the established baseline. Customer responsible for the change control board, change authorization workflow, and change documentation. | | `CM-6` | Configuration Settings — establish and document configuration settings | `Supports` | Console Compliance Expansion → control detail; Config Drift events | Baseline content captures configuration settings; drift events surface deviations. Customer responsible for the settings content and the policy authorising deviations. | | `CM-7` | Least Functionality — configure system to provide only essential capabilities | `Supports` | Console Compliance Expansion → control detail; Agent log (raw events) | Process activity capture and configuration baselines support least-functionality evidence. Customer responsible for the prohibited-software policy, port and protocol restrictions, and disabling-unnecessary-services workflow. | | `CM-8` | System Component Inventory — develop and document an inventory of system components | `Supports` | Console Infrastructure; Agent log (raw events) | LinuxGuard inventory of enrolled hosts and per-host metadata (kernel, distro, arch, agent version) contributes to component inventory at the OS layer. Customer responsible for the broader inventory across all system components. | ### Identification and Authentication (IA) | Control ID | Description | Tier | Evidence | Notes | | ---------- | --------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `IA-2` | Identification and Authentication (organizational users) — uniquely identify and authenticate | `Supports` | Agent log (raw events) with tamper-resistant identity attribution; Console Identity Intelligence | The agent captures tamper-resistant user identity across privilege escalation, providing unique identity attribution. Customer responsible for the IAM system, account-provisioning workflow, password policy, and MFA enforcement (IA-2(1) and IA-2(2)). | | `IA-5` | Authenticator Management — manage system authenticators | `Out of scope` | n/a | Authenticator content management (password policies, key rotation, certificate provisioning) is outside the OS-layer telemetry domain. Customer's IAM and PAM configuration administers authenticators. | ### Incident Response (IR) | Control ID | Description | Tier | Evidence | Notes | | ---------- | ------------------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `IR-4` | Incident Handling — implement incident handling capability for incidents | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Support bundle; Console Compliance Expansion → History | LinuxGuard provides the technical detection and timeline surface supporting the customer's incident handling capability. Customer responsible for the incident response procedure, role assignments, training, and the broader handling workflow. | | `IR-6` | Incident Reporting — report incidents within reporting timeframes | `Supports` | Agent log (raw events) with timestamps; Console Zero Trust Enforcement → Signals; Support bundle | Agent log timestamps and signal records provide the technical timeline supporting incident reports. Customer responsible for US-CERT reporting (FedRAMP requires reporting per agency-specific procedures and the FedRAMP PMO Incident Communications Procedure) and the broader reporting workflow. | ### System and Communications Protection (SC) — narrow subset | Control ID | Description | Tier | Evidence | Notes | | ---------- | ------------------------------------------------------------------------------------------------ | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SC-7` | Boundary Protection — monitor and control communications at external and key internal boundaries | `Out of scope` | n/a | Boundary protection (firewalls, network segmentation, perimeter enforcement) is a customer responsibility outside the OS-layer telemetry domain. | | `SC-13` | Cryptographic Protection — implement FIPS-validated cryptography | `Out of scope` | n/a | FIPS-validated cryptographic module deployment is outside the OS-layer telemetry domain. Customer responsible for FIPS-validated module deployment (OpenSSL FIPS, Linux kernel FIPS mode). | ### System and Information Integrity (SI) | Control ID | Description | Tier | Evidence | Notes | | ---------- | ------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SI-3` | Malicious Code Protection — implement signature-based or non-signature-based malicious code protection | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals | LinuxGuard provides behavioural detection supporting non-signature malicious-code protection. Customer responsible for signature-based anti-malware deployment where required by the baseline. | | `SI-4` | System Monitoring — monitor system to detect attacks and indicators of potential attacks | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Zero Trust Enforcement → Config Drift | eBPF-based behavioural telemetry, authentication event capture, file integrity monitoring, drift detection, and signal classification provide continuous system monitoring with attack-indicator detection at the OS layer. See [Security Architecture](/concepts/concepts/security-architecture). | | `SI-7` | Software, Firmware, and Information Integrity — employ integrity verification tools | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Config Drift | File monitoring with eBPF tracks writes to sudoers, sshd\_config, passwd, shadow, authorized\_keys, and operator-configured paths feeding the integrity verification capability. | ### Supply Chain Risk Management (SR) — supplier-side documentation only | Control ID | Description | Tier | Evidence | Notes | | ---------- | --------------------------------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SR-3` | Supply Chain Controls and Processes — establish process for identifying and addressing supply chain risks | `Supports` | Audit & Comply per-framework pages; Console Compliance Expansion → Reports | LinuxGuard provides supplier-side documentation: framework version pins, per-framework mapping pages, evidence chain integrity (SHA-256 manifests on collected evidence packages). Customer responsible for the supply chain risk management programme covering all suppliers. | | `SR-11` | Component Authenticity — develop and implement anti-counterfeit policy | `Out of scope` | n/a | Component authenticity policy administration (covering hardware procurement, anti-counterfeit verification, suspect-component handling) is outside the OS-layer telemetry domain. | ### Out-of-family controls | Control ID | Description | Tier | Evidence | Notes | | ------------------ | ------------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `AT family` | Awareness and Training | `Out of scope` | n/a | Training programme administration is an organisational responsibility not addressed by LinuxGuard. | | `MP family` | Media Protection | `Out of scope` | n/a | Media protection (digital and non-digital media handling, marking, storage, transport, sanitisation) is outside the OS-layer telemetry domain. | | `PE family` | Physical and Environmental Protection | `Out of scope` | n/a | Physical and environmental controls (facility access, environmental monitoring, fire protection, temperature and humidity control) are not addressed by LinuxGuard. | | `PS family` | Personnel Security | `Out of scope` | n/a | Personnel security (position categorisation, screening, termination, transfer, sanctions) is an organisational responsibility not addressed by LinuxGuard. | | `PT family` | PII Processing and Transparency | `Out of scope` | n/a | PII processing and transparency requirements (data tagging, consent management, redaction at the application layer) are outside the OS-layer telemetry domain. | | `CP family` (most) | Contingency Planning — most controls | `Out of scope` | n/a | Contingency planning, backup management, alternate processing sites, and disaster recovery are not addressed by LinuxGuard. Limited support via support-bundle archives for forensic continuity. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## Authorization boundary considerations The authorization boundary is the central organising concept for FedRAMP and StateRAMP authorization. NIST SP 800-37 Rev 2 defines the boundary as "all components of an information system to be authorized for operation by an authorizing official." For cloud service providers, the boundary encompasses the application, supporting infrastructure, interconnections with external systems, and inherited controls from underlying IaaS / PaaS providers. LinuxGuard sits within the authorization boundary as a system component when deployed on hosts in the boundary. The customer's SSP allocates control implementations across: * **Customer-implemented controls.** Controls the CSP implements directly within the boundary. LinuxGuard contributes to customer-implemented controls in the AC, AU, CM, IA, IR, SI families per the table above. * **Inherited controls.** Controls implemented by an underlying provider (e.g., the IaaS provider's PE family for physical controls). LinuxGuard does not produce evidence for inherited controls — the underlying provider's authorization package supplies that evidence. * **Shared controls.** Controls partially implemented by the CSP and partially inherited. LinuxGuard's telemetry may contribute one input to a shared control where the OS-layer activity is one part of the broader implementation. * **Customer-responsibility controls.** Controls the consumer of the cloud service is responsible for (e.g., application-layer access control). LinuxGuard does not produce evidence for customer-responsibility controls — those are implemented by the agency or customer consuming the CSP's service. The customer-responsibility matrix in the SSP documents the allocation explicitly. LinuxGuard's mapping above states what the agent and console produce as evidence; the SSP allocation states where in the customer-responsibility matrix that evidence lives. ## Baseline considerations FedRAMP defines three baselines reflecting impact level: Low, Moderate, and High. StateRAMP adopts the same three baselines with state-government scope adjustments. The control selection per baseline derives from NIST SP 800-53 Rev 5 with FedRAMP-specific parameter values, additional controls beyond the NIST baselines, and tailoring guidance. This page maps LinuxGuard's coverage at the control level without distinguishing baseline; the customer's SSP records the per-baseline applicability. Practical observations across baselines: * **Low Impact.** A smaller control set with less granular implementation evidence. LinuxGuard's `Satisfies` claims on AU-2, AU-3, AU-12, SI-4, and SI-7 typically map directly into the customer's Low baseline SSP. * **Moderate Impact.** A more granular control set including additional control enhancements. LinuxGuard's `Supports` claims become more important — the customer's implementation must also address the additional enhancements that LinuxGuard does not directly address. * **High Impact.** The most granular control set with the most stringent enhancements. The customer's implementation typically includes additional controls (e.g., AU-6 enhancements requiring automated review) for which LinuxGuard provides telemetry but the customer adds review automation. The 3PAO assessment evaluates implementation evidence against the per-baseline applicable controls. LinuxGuard's evidence pointers feed the assessment for the controls covered above; the 3PAO determines control satisfaction at the assessment level. ## Continuous monitoring considerations FedRAMP authorization is followed by ongoing continuous monitoring per NIST SP 800-137. The CSP submits monthly POA\&M updates, monthly vulnerability scan results, and annual control reassessments to the authorizing official. LinuxGuard's compliance dashboard supports the continuous monitoring obligations: * **Monthly POA\&M evidence.** Console Compliance Expansion → History surfaces per-control posture trends supporting POA\&M remediation evidence. * **Vulnerability monitoring.** LinuxGuard does not perform vulnerability scanning. Customer's vulnerability scanning solution feeds the monthly scan submission separately. * **Annual control reassessment.** The 3PAO's annual reassessment scope includes the OS-layer controls in the mapping above. LinuxGuard's framework version pin and last-verified date on this page support the reassessment cadence. * **Significant change authorization.** Changes affecting the authorization boundary require Significant Change Authorization. LinuxGuard's version updates within the agent are reflected in the customer's component version inventory; major version bumps may trigger Significant Change review. ## FedRAMP vs StateRAMP differences FedRAMP (federal) and StateRAMP (state and local government) share the same underlying control catalog (NIST SP 800-53 Rev 5) and the same three impact baselines (Low, Moderate, High). The differences are procedural and audience-related, not control-text-related, for the families this page covers. | Dimension | FedRAMP | StateRAMP | | -------------------------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | Authorizing body | Federal agency Authorizing Official (AO) or FedRAMP Joint Authorization Board (JAB) for P-ATO | StateRAMP Program Management Office and individual state authorizing bodies | | Target consumers | Federal agencies and federal contractors | State and local government entities, public sector consumers | | Assessment organization | 3PAO accredited by A2LA | 3PAO accredited by A2LA (often the same accreditation supports both) | | Continuous monitoring submission | FedRAMP PMO Marketplace and consuming agency | StateRAMP PMO and consuming state | | Reuse model | Inheritance via FedRAMP Marketplace authorizations | Reciprocity across StateRAMP participating states | | Reauthorization cadence | Annual ATO maintenance with 3-year reassessment cycle | Annual posture renewal aligned with FedRAMP cadence | For the controls in this page's mapping, the customer's implementation evidence and the assessment evidence are structurally identical between the two programs. Customers operating in both federal and state markets commonly produce one unified evidence package satisfying both programs' assessment requirements with program-specific submission packaging. ## Cross-framework considerations Customers in scope of FedRAMP or StateRAMP are commonly also in scope of agency-specific overlays (DoD CC SRG for defense systems, IRS Publication 1075 for tax-data systems, CJIS Security Policy for criminal-justice-data systems) and adjacent frameworks (NIST CSF 2.0 for the broader risk-management view, ISO/IEC 27001:2022 for international expansion). Operational alignment patterns customers commonly adopt: * **Unified evidence package.** Maintain one evidence package satisfying FedRAMP, StateRAMP, NIST CSF 2.0, and ISO/IEC 27001:2022 for the OS-layer controls covered above. The three-tier vocabulary consistency across LinuxGuard's per-framework pages supports the unified packaging. * **Overlay-specific addenda.** Where agency-specific overlays apply (DoD CC SRG, IRS 1075, CJIS), add overlay-specific evidence as an addendum to the base NIST SP 800-53 Rev 5 evidence rather than rebuilding evidence from scratch. * **Continuous monitoring consolidation.** Use Console Compliance Expansion → History as the single posture-trend source feeding the FedRAMP / StateRAMP continuous monitoring submissions and the customer's broader posture reporting. LinuxGuard's per-framework mapping pages share the same vocabulary contract and template. Customers operating against multiple framework pages in parallel benefit from the vocabulary consistency. ## How to share with auditor Three export paths are available, depending on the 3PAO's, PMO's, or authorizing official's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (FedRAMP Rev 5 + StateRAMP), last-verified date, per-control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the 3PAO wants raw host-level telemetry rather than a console-rendered report, particularly during the SAR-supporting evidence-collection phase. * **Console CSV / JSON export per control.** Compliance Expansion → FedRAMP → control detail → Evidence tab exports per-control evidence in machine-readable form for the 3PAO's GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally — particularly relevant for federal-system evidence where hostnames and process command-line arguments may correlate to system identifiers within the authorization boundary. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to AU-11 audit record retention. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against FedRAMP Rev 5 baselines (released 2023-05-30) and StateRAMP; both derived from NIST SP 800-53 Revision 5 (released 2020-09-23, updates per NIST errata).* # HITRUST + FFIEC HITRUST CSF v11.x and FFIEC CAT 2017 control mapping — LinuxGuard agent and console capabilities aligned to HITRUST access control, audit, incident response domains and FFIEC Domain 3 (Cybersecurity C > **Note**: This page maps LinuxGuard against **HITRUST CSF v11.x** (versioned annually — pin a specific minor version per audit period) and the **FFIEC Cybersecurity Assessment Tool (CAT) 2017** (still the current CAT publication as of last verification). Last verified against the frameworks on 2026-05-31. Canonical framework documents: [HITRUST Alliance — CSF](https://hitrustalliance.net/hitrust-csf), [FFIEC — Cybersecurity Assessment Tool](https://www.ffiec.gov/cyberassessmenttool.htm). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). > **Important**: This page covers two frameworks on one mapping page intentionally. **Dual-framework rationale**: HITRUST CSF is the healthcare-sector integrated control framework deriving from HIPAA Security Rule, NIST SP 800-53, ISO/IEC 27001, PCI-DSS, COBIT, and additional source authorities. FFIEC CAT is the U.S. banking-sector self-assessment tool aligned with NIST CSF and the FFIEC Information Technology Examination Handbook booklets. Both frameworks derive from the same underlying control catalogs that LinuxGuard's per-framework pages already map (NIST CSF, ISO/IEC 27001, NIST SP 800-53). Customers in healthcare commonly adopt HITRUST as their unified control framework; customers in U.S. banking commonly adopt FFIEC CAT for the supervisory examination workflow. The two customer populations have known overlap (banks providing healthcare services, healthcare entities providing financial services), and the LinuxGuard evidence surface is the same for both. The dual-framework page reflects the shared evidence surface while preserving framework-specific control IDs. > **Important**: HITRUST CSF is **versioned annually** (v11.0 in 2023, v11.1 in 2024, v11.2 in 2024, with subsequent minor versions following). Customers pin a specific minor version per audit period and engage a HITRUST Authorized External Assessor (CSF Assessor Organization) for HITRUST e1, i1, or r2 assessments. FFIEC CAT 2017 has not been formally retired as of last verification; the FFIEC has signaled future replacement with a NIST CSF 2.0-aligned tool. Customers tracking FFIEC guidance updates should monitor the FFIEC examination procedures and the IT Examination Handbook booklets in parallel with this mapping. ## Scope This page maps LinuxGuard's agent and console capabilities against HITRUST CSF v11.x and FFIEC CAT 2017. The HITRUST mapping is scoped to control categories 01 (Information Protection Program — relevant sub-domains only), 06 (Configuration Management), 09 (Communications and Operations Management — audit and monitoring sub-domains), 10 (Information Systems Acquisition, Development, and Maintenance — security-relevant sub-domains), 11 (Information Security Incident Management), and 13 (Privacy Practices — minimal coverage) on Linux systems within the customer's HITRUST scope. The FFIEC CAT mapping is scoped to Domain 3 (Cybersecurity Controls — Preventive Controls, Detective Controls, Corrective Controls) and Domain 5 (Cyber Incident Management and Resilience — Incident Resilience Planning and Strategy, Detection, Response, and Mitigation, Escalation and Reporting). Controls in HITRUST categories 02 (Endpoint Protection — anti-malware emphasis), 03 (Portable Media Security), 04 (Mobile Device Security), 05 (Wireless Security), 07 (Vulnerability Management) — limited coverage, 08 (Network Protection), 12 (Business Continuity), 14 (Third Party Assurance) — partial coverage; and FFIEC CAT Domain 1 (Cyber Risk Management and Oversight), Domain 2 (Threat Intelligence and Collaboration), and Domain 4 (External Dependency Management) are out of scope for this product and are listed in the mapping table as `Out of scope` or `Supports` rather than omitted. This mapping is informational and not a substitute for a HITRUST Authorized External Assessor's review or an FFIEC examination. Customers remain responsible for engaging a HITRUST Authorized External Assessor for the customer's chosen HITRUST assessment level (e1, i1, or r2); maintaining the HITRUST corrective action plan (CAP) and the assessment-period scope definition; conducting the FFIEC inherent-risk-profile assessment; selecting the appropriate cybersecurity maturity level (baseline, evolving, intermediate, advanced, innovative) for each assessment factor; preparing for FFIEC examination cycles per the customer's prudential supervisor's examination schedule; and integrating both frameworks with the customer's broader compliance programme. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for HITRUST CSF v11.x + FFIEC CAT 2017: * **LinuxGuard responsibility.** Produce telemetry, baselines, drift detection, audit trails, and evidence artifacts on Linux systems in the customer's HITRUST or FFIEC scope supporting the access control, audit, configuration management, monitoring, and incident response domains across both frameworks. Maintain the framework version pin (with explicit notation that the HITRUST minor version requires per-audit-period pinning) and per-control evidence pointers. * **Customer responsibility.** For HITRUST: engage a HITRUST Authorized External Assessor, select the assessment level (e1, i1, r2), define the assessment-period scope and the systems within scope, maintain the corrective action plan, administer the Privacy Practices controls outside the OS-layer telemetry domain, and integrate HITRUST with the customer's HIPAA programme where applicable. For FFIEC: complete the FFIEC inherent-risk-profile assessment, select the appropriate maturity level per assessment factor, prepare for the prudential supervisor's examination cycle, integrate FFIEC CAT with the FFIEC Information Technology Examination Handbook booklets the supervisor references, administer the broader cyber risk management and oversight programme (Domain 1) and threat intelligence programme (Domain 2), and operate the external dependency management programme (Domain 4). * **Out-of-scope domains for this framework.** HITRUST assessment-process administration, HITRUST Privacy Practices, HITRUST Business Continuity, HITRUST Third Party Assurance programme administration; FFIEC Domain 1 (Cyber Risk Management and Oversight), FFIEC Domain 2 (Threat Intelligence and Collaboration), FFIEC Domain 4 (External Dependency Management), and FFIEC examination-process administration. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. ### HITRUST CSF v11.x — selected control objectives | Control ID | Description | Tier | Evidence | Notes | | ---------- | -------------------------------------------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `01.b` | User Registration — formal user registration and de-registration procedure | `Supports` | Console Audit pillar → Authorizations audit; Config Drift on accounts baseline | LinuxGuard surfaces account inventory and drift supporting user-registration evidence. Customer responsible for the registration workflow, identity proofing, and the broader IAM programme. | | `01.c` | Privilege Management — restrict and control the allocation and use of privileges | `Supports` | Console Audit pillar → SUDO execution audit; Config Drift on sudo rules and sudo defaults baselines | SUDO rule baselines, sudo defaults baseline, and SUDO execution audit support privilege-management evidence. Customer responsible for the privilege-allocation decisions and the broader least-privilege policy. | | `01.j` | User Authentication for External Connections — authentication for external network connections | `Supports` | Agent log (raw events); Console Identity Intelligence | LinuxGuard captures authentication events from external sources including SSH-from-internet patterns. Customer responsible for the external-connection authentication enforcement (PAM, IdP, VPN) and policy. | | `01.q` | User Identification and Authentication — unique identifier for each user with authentication mechanism appropriate to risk | `Supports` | Agent log (raw events) with tamper-resistant identity attribution; Console Identity Intelligence | Tamper-resistant identity capture across privilege escalation provides unique-identifier evidence at the OS layer. Customer responsible for the IAM platform, authentication mechanism selection, and risk-based authentication policy. | | `06.h` | Technical Compliance Checking — periodically check information systems against published security implementation standards | `Supports` | Console Compliance Expansion → control detail; Config Drift events on baselines | LinuxGuard surfaces drift against configuration baselines supporting technical compliance checking. Customer responsible for defining the implementation standards content and the checking cadence. | | `09.aa` | Audit Logging — produce audit logs recording user activities, exceptions, and information security events | `Satisfies` | Agent log (raw events) at `/var/log/linuxguard/agent.log`; Support bundle | LinuxGuard generates structured audit logs continuously on every enrolled Linux host. See [Log Management](/operate/operate/log-management). | | `09.ab` | Monitoring System Use — establish procedures for monitoring use of information processing facilities | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Zero Trust Enforcement → Config Drift | eBPF-based behavioral telemetry, authentication event capture, drift detection, and signal classification provide continuous monitoring at the OS layer. | | `09.ad` | Administrator and Operator Logs — log system administrator and system operator activities | `Satisfies` | Agent log (raw events); Console Audit pillar → SUDO execution audit | SUDO execution audit and tamper-resistant identity capture across privilege escalation provide administrator-activity logging for non-repudiation. | | `09.ae` | Fault Logging — log faults reported by users or system programs | `Supports` | Agent log (raw events); `linuxguard-agent probe` command | Agent log captures errors, warnings, and probe failures from the agent's own operation. Customer responsible for the broader fault-logging programme across the system stack. | | `09.af` | Clock Synchronisation — synchronise clocks of relevant information processing systems | `Out of scope` | n/a | Clock synchronisation (NTP / chrony configuration) is outside the OS-layer telemetry domain. LinuxGuard logs timestamps using the system clock; customer is responsible for NTP configuration. | | `10.k` | Change Control Procedures — formal change control procedures for changes to information processing facilities | `Supports` | Console Zero Trust Enforcement → Config Drift; Agent log (raw events) | Drift detection surfaces configuration changes. Customer responsible for the change control board, change authorization workflow, and change documentation. | | `11.a` | Reporting Information Security Events — formal reporting and escalation procedures | `Supports` | Console Notifications; Console Zero Trust Enforcement → Signals; Support bundle | LinuxGuard surfaces signals and supports the reporting workflow. Customer responsible for the reporting procedure, escalation matrix, and assignment. | | `11.b` | Reporting Security Weaknesses — formal reporting of observed or suspected security weaknesses | `Supports` | Console Zero Trust Enforcement → Signals; Agent log (raw events) | Signal records surface observed weaknesses (e.g., authentication anomalies). Customer responsible for the weakness reporting workflow. | | `11.c` | Responsibilities and Procedures — establish management responsibilities and procedures for incident management | `Out of scope` | n/a | Incident management responsibilities and procedures are organisational responsibilities not addressed by LinuxGuard. | | `13.x` | Privacy Practices category | `Out of scope` | n/a | HITRUST Privacy Practices controls (covering PHI handling, consent management, breach notification under HIPAA, GDPR-related provisions) are administered by the customer's privacy programme, not addressed by LinuxGuard. | | `14.x` | Third Party Assurance category | `Supports` | Audit & Comply per-framework pages; Console Compliance Expansion → Reports | LinuxGuard provides supplier-side documentation: framework version pins, per-framework mapping pages. Customer responsible for the third-party assurance programme covering all suppliers. | ### FFIEC CAT 2017 — Domain 3 (Cybersecurity Controls) | Assessment Factor | Description | Tier | Evidence | Notes | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `Preventive Controls` — Infrastructure Management — Network Security | Network security controls including firewalls, IDS/IPS, network segmentation | `Out of scope` | n/a | Network security controls are outside the OS-layer telemetry domain. | | `Preventive Controls` — Access and Data Management — Access Controls | Access control mechanisms including authentication and authorization | `Supports` | Console Audit pillar → Authorizations audit; Agent log (raw events) with tamper-resistant identity attribution | LinuxGuard observes and audits OS-level access controls (SUDO rules, group membership, SSH access, authentication events). Customer responsible for the access-control policy and the IAM programme. | | `Preventive Controls` — Device/End-Point Security — Endpoint Protection | Endpoint protection including anti-malware, host-based intrusion prevention, file integrity monitoring | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Zero Trust Enforcement → Config Drift | LinuxGuard provides behavioural endpoint protection telemetry, file integrity monitoring, and signal-based detection at the OS layer. Customer responsible for the signature-based anti-malware deployment where required by the maturity level. | | `Preventive Controls` — Secure Coding | Secure software development lifecycle practices | `Out of scope` | n/a | Secure coding is an application-development responsibility outside the OS-layer telemetry domain. | | `Detective Controls` — Threat and Vulnerability Detection — Anomalous Activity Detection | Anomalous activity detection at network, endpoint, and user levels | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Signals | eBPF-based behavioural telemetry detects anomalous activity at the OS layer (authentication anomalies, file integrity events, privilege escalation patterns). | | `Detective Controls` — Event Detection — Logging | Audit logging of security-relevant events with sufficient detail | `Satisfies` | Agent log (raw events) at `/var/log/linuxguard/agent.log`; Support bundle | LinuxGuard generates structured audit logs continuously on every enrolled host with tamper-resistant identity attribution, source, method, and timestamp on each event. | | `Detective Controls` — Event Detection — Monitoring | Continuous security monitoring with established baselines and deviation detection | `Satisfies` | Console Zero Trust Enforcement → Signals; Console Zero Trust Enforcement → Config Drift; Console Compliance Expansion → History | Configuration baselines (SSH, SSHD, accounts, groups, sudo aliases, sudo defaults, sudo rules), drift detection, and signal classification provide continuous monitoring with baseline-deviation detection at the OS layer. | | `Corrective Controls` — Patch Management | Patch management programme including identification, testing, deployment | `Out of scope` | n/a | Patch management programme administration is outside the OS-layer telemetry domain. Customer's patch management solution feeds the programme. | | `Corrective Controls` — Remediation | Remediation of identified vulnerabilities and incidents | `Supports` | Console Compliance Expansion → control detail; Console Notifications | Console surfaces per-control pass/fail status feeding the remediation workflow. Customer responsible for the remediation process, accountability assignment, and timely action. | ### FFIEC CAT 2017 — Domain 5 (Cyber Incident Management and Resilience) | Assessment Factor | Description | Tier | Evidence | Notes | | --------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Incident Resilience Planning and Strategy` — Planning | Documented incident response plan and resilience strategy | `Out of scope` | n/a | Incident response plan documentation and resilience strategy administration are organisational responsibilities not addressed by LinuxGuard. | | `Detection, Response, and Mitigation` — Detection | Detection mechanisms to identify cyber incidents | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Zero Trust Enforcement → Config Drift | eBPF-based behavioural telemetry, authentication event capture, file integrity monitoring, drift detection, and signal classification provide continuous incident-detection capability at the OS layer. | | `Detection, Response, and Mitigation` — Response and Mitigation | Response and mitigation processes for cyber incidents | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Support bundle | LinuxGuard provides the technical detection and forensic-evidence surface supporting the response and mitigation workflow. Customer responsible for the response process, role assignments, and mitigation execution. | | `Escalation and Reporting` — Escalation | Internal escalation procedures for cyber incidents | `Supports` | Console Notifications | Console notification routing supports escalation. Customer responsible for the escalation matrix and the broader procedure. | | `Escalation and Reporting` — Reporting | External reporting to regulators, law enforcement, and other stakeholders | `Supports` | Agent log (raw events) with timestamps; Console Zero Trust Enforcement → Signals; Support bundle; Console Compliance Expansion → History | Agent log timestamps and signal records provide the technical timeline supporting external reports. Customer responsible for the regulator notification workflow (prudential supervisor, FinCEN where applicable), law enforcement engagement, and stakeholder communication. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## Dual-framework rationale Healthcare and financial-services organisations frequently overlap in scope, vendor selection, and audit obligations. The dual-framework page reflects the operational reality that the same LinuxGuard deployment commonly satisfies both customer populations' assessment requirements, and the evidence surface (agent logs, signals, drift events, SUDO execution audit, support bundles) is identical between the two. The decision to combine HITRUST and FFIEC on one page is driven by: * **Shared underlying control catalogs.** HITRUST CSF integrates HIPAA Security Rule, NIST SP 800-53, ISO/IEC 27001, PCI-DSS, and COBIT. FFIEC CAT aligns with NIST CSF and the FFIEC IT Examination Handbook booklets, which themselves derive from NIST SP 800-53 and related publications. The control text in both frameworks ultimately traces back to the same underlying catalogs that LinuxGuard's per-framework pages already address. * **Overlapping customer populations.** Banks providing health savings accounts (HSAs), pharmacy benefit managers (PBMs), or healthcare-financing services face both HITRUST and FFIEC obligations. Healthcare organisations operating revenue-cycle services that fall under bank-secrecy-act-style reporting face FFIEC adjacent obligations. The combined page reduces page proliferation for customers who would otherwise reference both frameworks in parallel. * **Identical evidence surface.** Agent log, signals, drift events, SUDO execution audit, and support bundles are the same artifacts whether the customer is preparing for a HITRUST r2 assessment or an FFIEC examination. The mapping table preserves framework-specific control IDs while sharing the evidence pointer set. The dual-framework approach is deliberate. Customers seeking only HITRUST coverage (without FFIEC) use the HITRUST section of the mapping table; customers seeking only FFIEC coverage (without HITRUST) use the FFIEC Domain 3 and Domain 5 sections. Customers in scope of both reference the combined surface. ## HITRUST assessment level considerations HITRUST offers three assessment levels with increasing rigor. The customer's choice depends on the audience for the assessment report (internal stakeholders, business partners, regulators) and the customer's risk tolerance. LinuxGuard's evidence surface is the same across the levels; the difference is the assessor's evaluation depth. * **e1 (Entry-Level)** — 1-year validity, 44 controls, foundational cybersecurity hygiene assessment. Suitable for organisations beginning their HITRUST journey. * **i1 (Implemented)** — 1-year validity, 182 controls, broader cybersecurity assessment with maturity assessment. * **r2 (Risk-Based)** — 2-year validity (annual interim assessment), control selection driven by the organisation's risk factors, with full maturity scoring (Policy, Procedure, Implemented, Measured, Managed). The most rigorous HITRUST assessment, suitable for organisations seeking HITRUST CSF Certified status. The mapping above covers controls present across all three levels for the categories LinuxGuard addresses. Customers pursuing r2 certification produce additional evidence at each maturity tier; LinuxGuard's continuous telemetry supports the Implemented, Measured, and Managed tiers for the OS-layer controls in scope. ## FFIEC maturity level considerations FFIEC CAT defines five cybersecurity maturity levels per assessment factor: Baseline, Evolving, Intermediate, Advanced, Innovative. The customer's selection per assessment factor reflects the institution's cybersecurity programme maturity relative to the inherent risk profile. The mapping above applies across maturity levels with the following notes: * **Baseline maturity** for the assessment factors covered above is typically achievable with LinuxGuard's `Satisfies` claims plus the customer-implemented controls noted in `Supports` claims. * **Intermediate and Advanced maturity** require additional declarative statements (documented procedures, formal training, metrics) beyond the OS-layer telemetry. LinuxGuard's telemetry supports the technical-implementation aspect; the customer adds the procedural and metrics aspects. * **Innovative maturity** requires demonstrated practices beyond standard cybersecurity programme expectations. LinuxGuard's behavioural telemetry, drift detection, and continuous monitoring contribute to the Innovative-maturity narrative for the assessment factors in scope. The mapping above does not declare maturity levels — the customer's self-assessment determines maturity per factor. ### FFIEC CAT to NIST CSF mapping FFIEC published a CAT-to-NIST-CSF mapping in 2017 supporting institutions wishing to use either framework. The mapping identifies the NIST CSF Subcategories that each FFIEC CAT declarative statement aligns with. The FFIEC has signaled future replacement of CAT with a NIST CSF 2.0-aligned tool; the mapping work to date supports the transition path. For LinuxGuard customers, the practical implication is that the evidence supporting the FFIEC Domain 3 and Domain 5 mappings on this page also feeds the NIST CSF 2.0 mapping (Phase 25). Customers in scope of both frameworks produce evidence once and present it under the framework-specific narrative the audience expects. ## HITRUST scoring considerations HITRUST r2 assessments evaluate each control against five maturity tiers, each scored on a scale of 0 to 5: Policy (documented policy approving the control), Procedure (documented procedure operationalising the policy), Implemented (control implementation in place), Measured (metrics on control effectiveness), and Managed (continuous improvement based on metrics). The final control score is a weighted aggregate of the five tiers. LinuxGuard's continuous telemetry supports the Implemented, Measured, and Managed tiers for the OS-layer controls in scope: * **Implemented tier evidence.** Agent log, signals, drift events, and SUDO execution audit demonstrate the control is in place and operating on enrolled hosts. * **Measured tier evidence.** Console Compliance Expansion → History provides per-control posture trends supporting metrics on control effectiveness. Per-server pass / fail breakdowns over the assessment period feed the metrics narrative. * **Managed tier evidence.** Suppressions and remediation history (drift event resolution, signal triage outcomes) support the continuous-improvement narrative. The annotation events in Compliance Expansion → History distinguish posture changes driven by remediation from changes driven by definitional updates. The Policy and Procedure tiers are administered by the customer's compliance function outside LinuxGuard. The assessor evaluates the customer's documented policy and procedure alongside the implementation evidence LinuxGuard provides. ### FFIEC examination cycle considerations FFIEC-regulated institutions are examined by their prudential supervisor (OCC, FDIC, NCUA, Federal Reserve, or state banking regulator) on a cycle defined by the institution's risk profile and examination history. The cycle is typically annual for larger institutions, with risk-based extensions or accelerations. LinuxGuard's evidence surface supports the examination cycle: * **Examination preparation.** Console Compliance Expansion → Reports produces a dated evidence package at the start of the examination preparation period. The report serves as the per-server posture snapshot the examiner receives. * **In-examination evidence requests.** Console CSV / JSON export per control supports examiner requests for specific control evidence (e.g., authentication event evidence for the prior quarter, drift event evidence for the configuration baseline). * **Post-examination remediation tracking.** Where the examination produces findings affecting the controls in this page's mapping, Console Compliance Expansion → History tracks the remediation progress over time. Suppressions document any findings the institution intentionally accepts under risk-based criteria. The examination cycle is administered by the prudential supervisor — not by LinuxGuard. The customer's compliance function manages examination scheduling, scope, and response. ## Cross-framework considerations Customers in scope of HITRUST CSF or FFIEC CAT are commonly also in scope of one or more of: * **HIPAA 45 CFR §164** — for HITRUST customers handling PHI; the HITRUST CSF integrates HIPAA Security Rule requirements as one of its source authorities. See [HIPAA](/audit-and-comply/audit-comply/hipaa) for the HIPAA-specific mapping. * **PCI-DSS v4.0.1** — for HITRUST or FFIEC customers in the cardholder data environment scope. See [PCI-DSS](/audit-and-comply/audit-comply/pci-dss). * **SOC 2** — for HITRUST or FFIEC customers acting as service organisations producing SOC 2 reports. See [SOC 2](/audit-and-comply/audit-comply/soc2). * **NIST CSF 2.0** — for FFIEC customers tracking the FFIEC's signaled future alignment with CSF 2.0. The NIST CSF 2.0 mapping (Phase 25) is the canonical NIST CSF page; FFIEC CAT alignment with CSF carries through to that page. * **FedRAMP / StateRAMP** — for healthcare or financial-services customers also serving federal or state-government consumers. See [FedRAMP / StateRAMP](/audit-and-comply/audit-comply/fedramp-stateramp). * **GLBA Safeguards Rule** — for FFIEC customers in scope of the Gramm-Leach-Bliley Act Safeguards Rule. LinuxGuard does not currently publish a dedicated GLBA mapping page; FFIEC CAT alignment carries most of the same control surface. Operational alignment patterns customers commonly adopt: * **Unified evidence package.** Maintain one evidence package satisfying HITRUST, FFIEC, HIPAA, and SOC 2 for the OS-layer controls covered above. The three-tier vocabulary consistency across LinuxGuard's per-framework pages supports the unified packaging. * **Framework-specific narrative layering.** Use one evidence base and layer framework-specific narrative documents per audience (HITRUST Assessor for healthcare, FFIEC examiner for banking supervision, HIPAA OCR for breach response, SOC 2 auditor for service-organisation attestation). * **Suppression-tracking consolidation.** Use the Console Compliance Expansion → Suppressions surface to track intentional out-of-scope decisions across all applicable frameworks. Each suppression carries its framework + control reference, scope, reason, approver, effective date, and expiration date as first-class evidence. LinuxGuard's per-framework mapping pages share the same vocabulary contract and template. Customers operating against multiple framework pages in parallel benefit from the vocabulary consistency. ## How to share with auditor Three export paths are available, depending on the HITRUST Authorized External Assessor's, FFIEC examiner's, or audit firm's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (HITRUST CSF v11.x and FFIEC CAT 2017), last-verified date, per-control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the assessor wants raw host-level telemetry rather than a console-rendered report, particularly for HITRUST r2 Measured / Managed maturity evidence or FFIEC Detection / Response factor evidence. * **Console CSV / JSON export per control.** Compliance Expansion → HITRUST or FFIEC → control detail → Evidence tab exports per-control evidence in machine-readable form for the assessor's GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally — particularly relevant for healthcare-sector deployments where hostnames and process command-line arguments may correlate to systems processing PHI, and for banking-sector deployments where similar correlations may apply to systems processing customer financial data. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table and [HIPAA](/audit-and-comply/audit-comply/hipaa) for the HIPAA cross-reference for healthcare customers. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to audit-period evidence retention. * [**HIPAA**](/audit-and-comply/audit-comply/hipaa) — HIPAA Security Rule technical safeguards relevant to healthcare-sector HITRUST customers. * [**SOC 2**](/audit-and-comply/audit-comply/soc2) — TSC alignment relevant to healthcare and financial-services service organisations producing SOC 2 reports alongside HITRUST or FFIEC engagement. * [**FedRAMP / StateRAMP**](/audit-and-comply/audit-comply/fedramp-stateramp) — NIST SP 800-53 Rev 5 alignment relevant where the customer maps HITRUST or FFIEC findings to federal or state-government overlays. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against HITRUST CSF v11.x (versioned annually — pin a specific minor version per audit period) and FFIEC CAT 2017 (current CAT publication as of last verification).* # NIST CSF 2.0 NIST Cybersecurity Framework 2.0 control mapping — LinuxGuard agent and console capabilities aligned to PROTECT, DETECT, and RESPOND functions with Satisfies / Supports / Out of scope tiers. > **Note**: This page maps LinuxGuard against the **NIST Cybersecurity Framework 2.0** (effective 2024-02-26). Last verified against the framework on 2026-05-31. Canonical framework document: [NIST CSF 2.0 — NIST.CSWP.29](https://doi.org/10.6028/NIST.CSWP.29). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). > **Important — CSF 2.0 vs CSF 1.1**: CSF 2.0 (published February 2024) added a sixth function — **GOVERN (GV)** — alongside the original five functions (IDENTIFY, PROTECT, DETECT, RESPOND, RECOVER) from CSF 1.1. The GOVERN function consolidates organizational context, risk management strategy, roles and responsibilities, policy, and oversight content that was scattered across CSF 1.1's IDENTIFY function. Customers cross-referencing legacy CSF 1.1 documentation should treat 1.1 category IDs as deprecated; this mapping uses CSF 2.0 category and subcategory IDs only. The 1.1-to-2.0 mapping crosswalk is published separately by NIST at the [CSF 2.0 Reference Tool](https://csrc.nist.gov/Projects/cybersecurity-framework/Filters). ## Scope This page maps LinuxGuard's agent and console capabilities against NIST CSF 2.0. The mapping is scoped to subcategories in the PROTECT function (Identity Management, Authentication, and Access Control — PR.AA; Data Security — PR.DS; Platform Security — PR.PS), the DETECT function (Continuous Monitoring — DE.CM; Adverse Event Analysis — DE.AE), and the RESPOND function (Incident Management — RS.MA; Incident Analysis — RS.AN) that LinuxGuard's telemetry, baselines, drift detection, and audit features address. Subcategories in the GOVERN function (organizational governance, risk management strategy, roles and responsibilities, policy, oversight), most of the IDENTIFY function (asset management at the organizational level, business environment, risk assessment program administration), the RECOVER function (incident recovery plan execution, communications, improvements), and the customer-side program elements of every function are out of scope for this product and are listed in the mapping table as `Out of scope` rather than omitted. This mapping is informational and not a substitute for an independent audit by a qualified assessor. Customers remain responsible for the GOVERN function as a whole, the organizational-level risk assessment under ID.RA, the recovery planning and execution under the RC function, and the broader cybersecurity program that the technical subcategories support. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for NIST CSF 2.0: * **LinuxGuard responsibility.** Produce continuous telemetry, configuration baselines, drift detection, authentication event capture, file integrity monitoring, behavioral signals, and audit trails on Linux systems that map to specific PROTECT, DETECT, and RESPOND subcategories. Maintain the framework version pin and per-subcategory evidence pointers. * **Customer responsibility.** Operate the GOVERN function (organizational context, risk management strategy, roles, policy, oversight), conduct the organizational-level risk assessment under ID.RA, administer the broader IDENTIFY function (asset management programs, business environment characterization, supply chain risk management program), operate the customer-side controls layered above LinuxGuard's telemetry (IAM platform, network policy, key management, training, physical security, vendor management, BCP), and execute the RECOVER function (recovery planning, communications, improvements). * **Out-of-scope domains for this framework.** The GOVERN function in its entirety, organizational-level risk assessment, asset management program administration, business environment characterization, supply chain risk management program (beyond LinuxGuard as one supplier), recovery planning and execution, communications and stakeholder engagement, and the policy administration elements of every function. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. | Control ID | Description | Tier | Evidence | Notes | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `GV.OC` | Organizational Context — the circumstances surrounding the organization's cybersecurity risk management decisions are understood | `Out of scope` | n/a | Organizational context characterization is a governance responsibility not addressed by LinuxGuard. | | `GV.RM` | Risk Management Strategy — the organization's priorities, constraints, risk tolerance, and risk appetite are established and used to support operational risk decisions | `Out of scope` | n/a | Risk management strategy is a governance responsibility not addressed by LinuxGuard. | | `GV.RR` | Roles, Responsibilities, and Authorities — cybersecurity roles, responsibilities, and authorities are established and communicated | `Out of scope` | n/a | Role and responsibility assignment is a governance responsibility not addressed by LinuxGuard. | | `ID.AM-01` | Inventories of hardware managed by the organization are maintained | `Supports` | Console Infrastructure → server inventory; Console Compliance Expansion → control detail | LinuxGuard surfaces the per-server inventory of enrolled hosts including hostname, architecture, distribution, and agent version. Customer responsible for the organizational hardware asset register beyond LinuxGuard-monitored hosts. | | `ID.AM-02` | Inventories of software, services, and systems managed by the organization are maintained | `Supports` | Console Infrastructure; Console Baselines → accounts and groups | LinuxGuard surfaces account and group inventories per host. Customer responsible for the application software inventory and the broader system inventory beyond OS-layer accounts. | | `PR.AA-01` | Identities and credentials for authorized users, services, and hardware are managed by the organization | `Supports` | Console Audit pillar → Authorizations audit; Console Baselines → accounts and groups; Agent log (raw events) with tamper-resistant identity attribution | LinuxGuard observes account and group inventories, authorization changes, and authentication events with tamper-resistant identity capture across privilege escalation. Customer responsible for the identity platform, credential issuance, and identity lifecycle workflow. | | `PR.AA-03` | Users, services, and hardware are authenticated | `Supports` | Agent log (raw events) with `auth.event` attribute; Console Identity Intelligence | LinuxGuard captures authentication events including user, source IP, method (password, publickey, keyboard-interactive), and outcome. Customer responsible for the authentication platform, MFA enforcement, and password policy administration. | | `PR.AA-05` | Access permissions, entitlements, and authorizations are defined in a policy, managed, enforced, and reviewed | `Supports` | Console Audit pillar → Authorizations audit; Console Baselines → SUDO rules, SSH config, SSHD config; Console Zero Trust Enforcement → Config Drift | SUDO rule baselines, SSH/SSHD baselines, authorization audit, and config drift surface OS-layer entitlement evidence. Customer responsible for the access policy text, role definition, and access review workflow. | | `PR.DS-01` | The confidentiality, integrity, and availability of data-at-rest are protected | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Config Drift | File integrity monitoring on sensitive paths (sudoers, sshd\_config, passwd, shadow, authorized\_keys, operator-configured paths) contributes to integrity assurance for OS-layer data-at-rest. Customer responsible for application-layer data-at-rest controls and encryption-at-rest. | | `PR.PS-01` | Configuration management practices are established and applied | `Satisfies` | Console Baselines → SSH config, SSHD config, SUDO aliases, SUDO defaults, SUDO rules; Console Zero Trust Enforcement → Config Drift; Agent log (raw events) | Baselines capture the expected configuration state for SSH client, SSHD daemon, SUDO aliases, SUDO defaults, SUDO rules, accounts, and groups; drift detection surfaces deviations on each scan cycle. See [Baselines](/concepts/concepts/console/baselines). | | `PR.PS-04` | Log records are generated and made available for continuous monitoring | `Satisfies` | Agent log (raw events) at `/var/log/linuxguard/agent.log`; Support bundle | The LinuxGuard agent generates structured audit logs continuously on every enrolled host. Default retention: 50 MB per file, 14-day retention, 5 backups, gzip compression. See [Log Management](/operate/operate/log-management). | | `PR.PS-05` | Installation and execution of unauthorized software are prevented | `Out of scope` | n/a | Application allow-listing and execution prevention are not addressed by LinuxGuard. LinuxGuard observes and reports but does not enforce execution policy. | | `DE.CM-01` | Networks and network services are monitored to find potentially adverse events | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals | Behavioral telemetry surfaces network-related signals (e.g., suspicious connection attempts visible at the kernel layer). Customer responsible for network-layer monitoring (NDR, IDS/IPS, flow logs) beyond OS-layer observability. | | `DE.CM-03` | Personnel activity and technology usage are monitored to find potentially adverse events | `Satisfies` | Agent log (raw events) with tamper-resistant identity attribution; Console Audit pillar → SUDO execution audit; Console Identity Intelligence | Authentication event capture, SUDO execution audit, and tamper-resistant identity capture across privilege escalation produce continuous personnel-activity monitoring on enrolled hosts. | | `DE.CM-09` | Computing hardware and software, runtime environments, and their data are monitored to find potentially adverse events | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Config Drift; Console Zero Trust Enforcement → Signals | eBPF-based behavioral telemetry, file integrity monitoring on critical paths, configuration drift on baselines, and signal records constitute continuous monitoring of the runtime environment. See [Security Architecture](/concepts/concepts/security-architecture). | | `DE.AE-02` | Potentially adverse events are analyzed to better understand associated activities | `Supports` | Console Zero Trust Enforcement → Signals; Agent log (raw events); Support bundle | Signal records, agent logs, and support bundles supply the source material for adverse event analysis. Customer responsible for the analyst workflow, triage process, and decision criteria. | | `DE.AE-03` | Information is correlated from multiple sources | `Supports` | Console Zero Trust Enforcement → Signals; Console Audit pillar; Console Baselines | Console surfaces correlate authentication events, drift events, SUDO execution audit, and behavioral signals per server and per identity. Customer responsible for cross-source correlation with non-LinuxGuard telemetry (network logs, application logs, identity provider logs). | | `DE.AE-06` | Information on adverse events is provided to authorized staff and tools | `Supports` | Console Notifications; Console Compliance Expansion → Reports | Console notifications and reports route adverse-event information to operators. Customer responsible for the notification routing configuration, on-call rotation, and integration with the broader operations stack. | | `RS.MA-01` | The incident response plan is executed in coordination with relevant third parties once an incident is declared | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Support bundle | LinuxGuard supplies telemetry-driven evidence supporting incident response plan execution. Customer responsible for the incident response plan, declaration criteria, and coordination with third parties. | | `RS.MA-03` | Incidents are categorized and prioritized | `Supports` | Console Zero Trust Enforcement → Signals (severity); Console Notifications | Signal severity tagging informs the customer's categorization and prioritization workflow. Customer responsible for the incident categorization scheme and prioritization criteria. | | `RS.AN-03` | Analysis is performed to establish what has taken place during an incident and the root cause of the incident | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Audit pillar → SUDO execution audit; Support bundle | Agent logs, signal timelines, SUDO execution audit, and support bundles provide forensic source material. Customer responsible for the analyst workflow, root cause analysis, and incident reconstruction narrative. | | `RS.AN-06` | Actions performed during an investigation are recorded, and the records' integrity and provenance are preserved | `Supports` | Console Compliance Expansion → History annotations; Support bundle BUNDLE-MANIFEST.json with SHA-256 verification | Compliance history annotations and bundle manifest integrity verification support investigation recordkeeping. Customer responsible for the investigation workflow, case management, and chain of custody. | | `RC.RP-01` | The recovery portion of the incident response plan is executed once initiated from the incident response process | `Out of scope` | n/a | Recovery plan execution is a customer process not addressed by LinuxGuard. LinuxGuard is a security monitoring agent, not a recovery or restoration product. | | `RC.CO-03` | Recovery activities and progress in restoring operational capabilities are communicated to designated internal and external stakeholders | `Out of scope` | n/a | Recovery communications are an organizational responsibility not addressed by LinuxGuard. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## Function-level coverage summary CSF 2.0 organizes subcategories under six functions. The summary below restates which functions LinuxGuard addresses materially and which are left to the customer's broader program. | Function | LinuxGuard coverage | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GOVERN (GV) | Out of scope — governance, risk strategy, roles, policy, and oversight are organizational responsibilities. | | IDENTIFY (ID) | Partial Supports — asset inventory (ID.AM) at the per-host level only; broader IDENTIFY subcategories (risk assessment, supply chain) are out of scope. | | PROTECT (PR) | Partial — configuration management (PR.PS-01) and log generation (PR.PS-04) are Satisfies; identity management (PR.AA) and data security (PR.DS) are Supports. | | DETECT (DE) | Substantial — personnel and technology monitoring (DE.CM-03) and runtime environment monitoring (DE.CM-09) are Satisfies; event analysis subcategories are Supports. | | RESPOND (RS) | Supports across incident management (RS.MA) and incident analysis (RS.AN); response execution remains customer-side. | | RECOVER (RC) | Out of scope — recovery planning, execution, and communications are customer-side. | The function-level summary is descriptive; the per-subcategory mapping table above is the authoritative content. ## How to share with auditor Three export paths are available, depending on the auditor's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (NIST CSF 2.0), last-verified date, per-subcategory coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the auditor wants raw host-level telemetry rather than a console-rendered report. * **Console CSV / JSON export per subcategory.** Compliance Expansion → NIST CSF 2.0 → subcategory detail → Evidence tab exports per-subcategory evidence in machine-readable form for auditors who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Baselines**](/concepts/concepts/console/baselines) — configuration baselines and drift detection that PR.PS-01 satisfies. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to PR.PS-04 audit log evidence. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against NIST CSF 2.0 published 2024-02-26.* # ISO/IEC 27001:2022 ISO/IEC 27001:2022 control mapping — LinuxGuard agent and console capabilities aligned to Annex A Technological controls (A.8.x) with :2013 transition note and Satisfies / Supports / Out of scope tier > **Note**: This page maps LinuxGuard against **ISO/IEC 27001:2022** (published 2022-10-25). Last verified against the framework on 2026-05-31. Canonical framework document: [ISO/IEC 27001:2022 — Information security, cybersecurity and privacy protection — Information security management systems — Requirements](https://www.iso.org/standard/27001). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). > **Important — :2013 to :2022 transition**: ISO/IEC 27001:2013 (114 controls organized in 14 domains across Annex A.5–A.18) was replaced by ISO/IEC 27001:2022 (93 controls reorganized into 4 themes: Organizational, People, Physical, Technological). The IAF transition period required certification bodies to migrate active certifications to the :2022 standard by **2025-10-31** — certifications still on :2013 after that date are not recognized. This mapping references :2022 Annex A control IDs only. Customers maintaining historical :2013 mappings should use the ISO/IEC 27001:2022 Annex B mapping table (in the standard itself) for crosswalking — A.12.4.1 (Event logging) maps to A.8.15 (Logging), A.9.4.2 (Secure log-on procedures) maps to A.8.5 (Secure authentication), and so on. The control count reduction reflects consolidation, not removed coverage — :2022 introduces 11 new controls (most notably A.5.7 Threat intelligence, A.5.23 Information security for use of cloud services, A.8.9 Configuration management, A.8.10 Information deletion, A.8.16 Monitoring activities, A.8.28 Secure coding). ## Scope This page maps LinuxGuard's agent and console capabilities against ISO/IEC 27001:2022. The mapping is scoped to Annex A Technological controls (theme A.8 — 37 controls covering technology-level security) that LinuxGuard's telemetry, baselines, drift detection, and audit features address. Controls in the Organizational theme (A.5 — 37 controls covering policies, roles, ISMS administration, supplier and asset management programs), the People theme (A.6 — 8 controls covering screening, training, and HR practices), the Physical theme (A.7 — 14 controls covering physical access, equipment security, and clear desk/screen practices), and the broader Information Security Management System (ISMS) requirements in clauses 4–10 of the standard's main body are out of scope for this product and are listed in the mapping table as `Out of scope` rather than omitted. This mapping is informational and not a substitute for an independent audit by a qualified ISO/IEC 27001 lead auditor or certification body. Customers remain responsible for the ISMS itself — context establishment, leadership commitment, planning (including the risk assessment and risk treatment plan that drives Statement of Applicability), support resources, operational planning and control, performance evaluation, and continual improvement under clauses 4–10. The mapping below addresses Annex A technological controls only and is not a substitute for the customer's ISMS scope definition, Statement of Applicability, or certification audit. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for ISO/IEC 27001:2022: * **LinuxGuard responsibility.** Produce continuous telemetry, configuration baselines, drift detection, authentication event capture, file integrity monitoring, behavioral signals, and audit trails on Linux systems that map to specific Annex A Technological controls. Maintain the framework version pin and per-control evidence pointers. * **Customer responsibility.** Establish and operate the ISMS per clauses 4–10 of ISO/IEC 27001:2022, conduct the risk assessment and risk treatment plan, draft and maintain the Statement of Applicability (SoA) declaring which Annex A controls apply and how they are addressed, implement Annex A Organizational, People, and Physical theme controls, engage a qualified certification body for the certification audit, and complete the surveillance and recertification cycles. * **Out-of-scope domains for this framework.** ISMS administration (clauses 4–10), Annex A Organizational theme (A.5 — 37 controls), Annex A People theme (A.6 — 8 controls), Annex A Physical theme (A.7 — 14 controls), and the certification body engagement workflow. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. Annex A control IDs reference ISO/IEC 27001:2022 numbering. | Control ID | Description | Tier | Evidence | Notes | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `A.5` | Organizational theme (37 controls — policies, ISMS administration, supplier and asset management) | `Out of scope` | n/a | Organizational controls (information security policies, roles, segregation of duties, contact with authorities, threat intelligence program, asset register, classification, supplier security programs, ISMS administration) are not addressed by LinuxGuard. | | `A.6` | People theme (8 controls — screening, training, awareness, disciplinary, remote working, NDA) | `Out of scope` | n/a | People controls are HR and program responsibilities not addressed by LinuxGuard. | | `A.7` | Physical theme (14 controls — physical security perimeters, entry controls, equipment security, clear desk/screen, secure disposal) | `Out of scope` | n/a | Physical controls are not addressed by LinuxGuard. | | `A.8.2` | Privileged access rights — the allocation and use of privileged access rights are restricted and managed | `Supports` | Console Baselines → SUDO rules, SUDO aliases, SUDO defaults; Console Audit pillar → Authorizations audit; Agent log (raw events) with tamper-resistant identity attribution | SUDO rule baselines, SUDO defaults baseline, SUDO aliases baseline, authorization audit, and tamper-resistant identity capture across privilege escalation produce evidence of privileged access posture. Customer responsible for the privileged access policy, role definition, and access review workflow. | | `A.8.3` | Information access restriction — access to information and other associated assets is restricted in accordance with the established topic-specific policy on access control | `Supports` | Console Baselines → SSH config, SSHD config, accounts, groups; Console Audit pillar → Authorizations audit | SSH/SSHD baselines, account/group inventories, and authorization audit surface OS-layer access-restriction evidence. Customer responsible for the access control policy, application-layer access restriction, and IAM platform. | | `A.8.5` | Secure authentication — secure authentication technologies and procedures are implemented based on information access restrictions and topic-specific policy on access control | `Supports` | Agent log (raw events) with `auth.event` attribute; Console Identity Intelligence | Authentication event capture records every login (success and failure) with user, source IP, method (password, publickey, keyboard-interactive), and outcome. Customer responsible for MFA enforcement at the IdP or PAM layer, password policy administration, and the broader authentication architecture. | | `A.8.7` | Protection against malware — protection against malware is implemented and supported by appropriate user awareness | `Out of scope` | n/a | Anti-malware deployment, signature management, and user awareness programs are not addressed by LinuxGuard. LinuxGuard is not an anti-malware product. | | `A.8.8` | Management of technical vulnerabilities — information about technical vulnerabilities of information systems in use is obtained, the organization's exposure to such vulnerabilities is evaluated, and appropriate measures are taken | `Supports` | `linuxguard-agent probe` command; Console Compliance Expansion → History | The probe command tests kernel, BPF, fanotify, netlink, audit, and capability prerequisites at deployment time. Compliance history surfaces posture trends. Customer responsible for the vulnerability management program, scanning cadence, and remediation tracking. | | `A.8.9` | Configuration management — configurations, including security configurations, of hardware, software, services and networks are established, documented, implemented, monitored and reviewed | `Satisfies` | Console Baselines → SSH config, SSHD config, SUDO aliases, SUDO defaults, SUDO rules, accounts, groups; Console Zero Trust Enforcement → Config Drift; Agent log (raw events) | Baselines capture the expected configuration state for SSH client, SSHD daemon, SUDO aliases, SUDO defaults, SUDO rules, accounts, and groups; drift detection surfaces deviations on each scan cycle. See [Baselines](/concepts/concepts/console/baselines). This is the load-bearing control for LinuxGuard's baseline pillar. | | `A.8.10` | Information deletion — information stored in information systems, devices or in any other storage media is deleted when no longer required | `Out of scope` | n/a | Information deletion policies and execution are not addressed by LinuxGuard. | | `A.8.11` | Data masking — data masking is used in accordance with the organization's topic-specific policy on access control and other related topic-specific policies, and business requirements, taking applicable legislation into consideration | `Out of scope` | n/a | Data masking is an application-layer or database-layer responsibility not addressed by LinuxGuard. | | `A.8.12` | Data leakage prevention — data leakage prevention measures are applied to systems, networks and any other devices that process, store or transmit sensitive information | `Out of scope` | n/a | DLP enforcement is not addressed by LinuxGuard. | | `A.8.13` | Information backup — backup copies of information, software and systems are maintained and regularly tested in accordance with the agreed topic-specific policy on backup | `Out of scope` | n/a | Backup management and testing are not addressed by LinuxGuard. | | `A.8.15` | Logging — logs that record activities, exceptions, faults and other relevant events are produced, stored, protected and analysed | `Satisfies` | Agent log (raw events) at `/var/log/linuxguard/agent.log`; Support bundle; Console Compliance Expansion → History | The LinuxGuard agent generates structured audit logs continuously on every enrolled host with timestamps, event categories, and identity attribution. Default retention: 50 MB per file, 14-day retention, 5 backups, gzip compression. See [Log Management](/operate/operate/log-management). | | `A.8.16` | Monitoring activities — networks, systems and applications are monitored for anomalous behaviour and appropriate actions taken to evaluate potential information security incidents | `Satisfies` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Zero Trust Enforcement → Config Drift | Continuous agent telemetry, behavioral signal records, and drift detection produce continuous monitoring of enrolled hosts. See [Security Architecture](/concepts/concepts/security-architecture). | | `A.8.17` | Clock synchronization — the clocks of information processing systems used by the organization are synchronized to approved time sources | `Out of scope` | n/a | Clock synchronization (NTP / chronyd) is an OS-administration responsibility not addressed by LinuxGuard. LinuxGuard reads the system clock for event timestamps but does not enforce time-sync configuration. | | `A.8.20` | Networks security — networks and network devices are secured, managed and controlled to protect information in systems and applications | `Out of scope` | n/a | Network device security is not addressed by LinuxGuard. | | `A.8.21` | Security of network services — security mechanisms, service levels and service requirements of network services are identified, implemented and monitored | `Out of scope` | n/a | Network service security architecture is not addressed by LinuxGuard. | | `A.8.22` | Segregation of networks — groups of information services, users and information systems are segregated in the organization's networks | `Out of scope` | n/a | Network segmentation is not addressed by LinuxGuard. | | `A.8.24` | Use of cryptography — rules for the effective use of cryptography, including cryptographic key management, are defined and implemented | `Out of scope` | n/a | Cryptography policy and key management are not addressed by LinuxGuard at the framework-mapping layer. LinuxGuard uses TLS in transit to the console — the customer's cryptography program covers application-layer encryption choices. | | `A.8.25` | Secure development life cycle — rules for the secure development of software and systems are established and applied | `Out of scope` | n/a | Secure development lifecycle policies are not addressed by LinuxGuard. | | `A.8.28` | Secure coding — secure coding principles are applied to software development | `Out of scope` | n/a | Secure coding practices are a development-program responsibility not addressed by LinuxGuard. | | `A.8.32` | Change management — changes to information processing facilities and information systems are subject to change management procedures | `Supports` | Console Zero Trust Enforcement → Config Drift; Console Baselines | Drift detection surfaces unauthorized or out-of-band changes to OS-layer configuration. Customer responsible for the change management procedure, approval workflow, and change advisory board process. | | `A.8.34` | Protection of information systems during audit testing — audit tests and other assurance activities involving assessment of operational systems are planned and agreed between the tester and appropriate management | `Out of scope` | n/a | Audit planning and coordination are an organizational responsibility not addressed by LinuxGuard. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## Statement of Applicability considerations ISO/IEC 27001:2022 clause 6.1.3 requires the customer to produce a Statement of Applicability (SoA) declaring which Annex A controls apply, how they are implemented, and the justification for any exclusions. The SoA is the load-bearing document for an :2022 certification audit and is the place where the mapping above feeds the customer's broader documentation. Practical SoA implications of this mapping: * **Annex A.8.9, A.8.15, and A.8.16 are the three Satisfies rows.** Customers documenting LinuxGuard in their SoA list these three controls with LinuxGuard as the implementation surface, and reference this page as the supporting evidence pointer. * **Annex A.8.2, A.8.3, A.8.5, A.8.8, and A.8.32 are the Supports rows.** Customers documenting LinuxGuard in their SoA list these controls with LinuxGuard as one input and the customer-side control (IAM platform, vulnerability management program, change management procedure) as the complementary surface. * **Out-of-scope rows.** The SoA may include or exclude these controls based on the customer's ISMS scope; if included, LinuxGuard is not part of the implementation surface for them. The SoA template itself is the customer's responsibility — LinuxGuard does not produce or maintain an SoA artifact. The console's [Compliance Expansion](/concepts/concepts/console/compliance-expansion) reports provide the per-control evidence the SoA references. ## Annex A theme summary ISO/IEC 27001:2022 reorganizes Annex A into four themes. The summary below restates LinuxGuard coverage per theme. | Theme | Controls | LinuxGuard coverage | | ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | A.5 Organizational | 37 | Out of scope — policies, ISMS administration, supplier and asset management programs. | | A.6 People | 8 | Out of scope — HR practices, training, awareness, NDA. | | A.7 Physical | 14 | Out of scope — physical security, equipment security, clear desk/screen. | | A.8 Technological | 37 | Substantial — Satisfies A.8.9, A.8.15, A.8.16; Supports A.8.2, A.8.3, A.8.5, A.8.8, A.8.32; balance Out of scope at the LinuxGuard layer. | The theme summary is descriptive; the per-control mapping table above is the authoritative content. ## How to share with auditor Three export paths are available, depending on the certification body's or internal auditor's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (ISO/IEC 27001:2022), last-verified date, per-control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the auditor wants raw host-level telemetry rather than a console-rendered report. * **Console CSV / JSON export per control.** Compliance Expansion → ISO/IEC 27001:2022 → control detail → Evidence tab exports per-control evidence in machine-readable form for auditors who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table. ## Cross-references * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Baselines**](/concepts/concepts/console/baselines) — configuration baselines and drift detection that A.8.9 satisfies. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to A.8.15 logging. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against ISO/IEC 27001:2022 published 2022-10-25.* # CIS Controls v8.1 CIS Controls v8.1 control mapping — LinuxGuard agent and console capabilities aligned to the 18 control families with explicit separation from CIS Benchmarks and Satisfies / Supports / Out of scope ti > **Note**: This page maps LinuxGuard against **CIS Controls v8.1** (published 2024-06-01). Last verified against the framework on 2026-05-31. Canonical framework document: [CIS Critical Security Controls v8.1 — Center for Internet Security](https://www.cisecurity.org/controls/cis-controls-list). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). > **Important — Not the same as CIS Benchmarks**: CIS Controls v8.1 are 18 strategic security control families addressing the *what* of organizational security (e.g., "Establish and Maintain an Inventory of Enterprise Assets"). CIS Benchmarks are OS-specific *configuration hardening guides* (e.g., "set `net.ipv4.tcp_syncookies=1` in `/etc/sysctl.conf`" or "ensure `PermitRootLogin no` in `/etc/ssh/sshd_config`"). They are complementary, not interchangeable: Controls describe organizational program scope; Benchmarks describe per-host configuration settings. Citing the wrong one in an audit conversation or procurement RFP is a common error. See [CIS Benchmarks](/audit-and-comply/audit-comply/cis-benchmarks) for the Linux hardening configurations LinuxGuard's baseline detection complements. ## Scope This page maps LinuxGuard's agent and console capabilities against CIS Controls v8.1. The mapping is scoped to controls in audit log management (CIS Control 8), account management (CIS Control 5), access control management (CIS Control 6), secure configuration (CIS Control 4), enterprise asset inventory (CIS Control 1), continuous vulnerability management (CIS Control 7), and incident response (CIS Control 17) that LinuxGuard's telemetry, baselines, drift detection, and audit features address. Controls in data protection (CIS Control 3), email and browser protections (CIS Control 9), malware defenses (CIS Control 10), data recovery (CIS Control 11), network infrastructure and monitoring management (CIS Controls 12-13), security awareness training (CIS Control 14), service provider management (CIS Control 15), application software security (CIS Control 16), and penetration testing (CIS Control 18) are out of scope for this product and are listed in the mapping table as `Out of scope` rather than omitted. This mapping is informational and not a substitute for an independent audit by a qualified assessor. Customers remain responsible for selecting the appropriate Implementation Group (IG1, IG2, or IG3) for their organization, conducting the broader security program that the technical controls support, and documenting the organizational policies and procedures that complement the agent's telemetry surface. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for CIS Controls v8.1: * **LinuxGuard responsibility.** Produce continuous audit log generation, file integrity monitoring telemetry, configuration baselines and drift detection, account and group inventories, authorization audit, and behavioral signals on Linux systems within the customer's enterprise asset scope. Maintain the framework version pin and per-control evidence pointers. * **Customer responsibility.** Determine the applicable Implementation Group (IG1, IG2, or IG3) and assign sub-controls accordingly, operate the customer-side controls layered above LinuxGuard's telemetry (IAM platform, network monitoring, vulnerability scanning, malware defenses, backup management, training program), engage in the broader security program (data protection, email and browser protections, application security, penetration testing), and document the policies and procedures that complement the technical control surface. * **Out-of-scope domains for this framework.** Data protection (CIS Control 3), email and browser protections (CIS Control 9), malware defenses (CIS Control 10), data recovery (CIS Control 11), network infrastructure and monitoring management (CIS Controls 12-13), security awareness training (CIS Control 14), service provider management (CIS Control 15), application software security (CIS Control 16), and penetration testing (CIS Control 18). ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. | Control ID | Description | Tier | Evidence | Notes | | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CIS 1` | Inventory and Control of Enterprise Assets — Actively manage all enterprise assets connected to the infrastructure | `Supports` | Console Infrastructure → server inventory; Agent enrollment record | LinuxGuard surfaces the per-server inventory of enrolled Linux hosts including hostname, architecture, distribution, agent version, and last-seen timestamp. Customer responsible for the broader enterprise asset inventory beyond LinuxGuard-monitored hosts (network devices, IoT, mobile, virtual). | | `CIS 2` | Inventory and Control of Software Assets — Actively manage all software on the network | `Out of scope` | n/a | Software inventory and execution control are not addressed by LinuxGuard. Application allow-listing, software lifecycle tracking, and unauthorized-software detection are separate-product concerns. | | `CIS 3` | Data Protection — Develop processes and technical controls to identify, classify, securely handle, retain, and dispose of data | `Out of scope` | n/a | Data classification, handling, retention, and disposal are not addressed by LinuxGuard. | | `CIS 4` | Secure Configuration of Enterprise Assets and Software — Establish and maintain the secure configuration of enterprise assets and software | `Satisfies` | Console Baselines → SSH config, SSHD config, SUDO aliases, SUDO defaults, SUDO rules, accounts, groups; Console Zero Trust Enforcement → Config Drift; Agent log (raw events) | Baselines capture the expected configuration state for SSH client, SSHD daemon, SUDO aliases, SUDO defaults, SUDO rules, accounts, and groups; drift detection surfaces deviations on each scan cycle. See [Baselines](/concepts/concepts/console/baselines). LinuxGuard's coverage applies to the OS layer; application-software configuration management is out of scope. | | `CIS 5` | Account Management — Use processes and tools to assign and manage authorization to credentials for user accounts | `Supports` | Console Baselines → accounts, groups; Console Audit pillar → Authorizations audit; Agent log (raw events) with tamper-resistant identity attribution | Account and group baselines surface unexpected account creation, deletion, and modification. Authorization audit and tamper-resistant identity capture across privilege escalation contribute to credential management evidence. Customer responsible for the identity platform, account provisioning workflow, joiner-mover-leaver process, and credential issuance. | | `CIS 6` | Access Control Management — Use processes and tools to create, assign, manage, and revoke access credentials and privileges for user, administrator, and service accounts for enterprise assets and software | `Supports` | Console Baselines → SUDO rules, SUDO aliases, SUDO defaults; Console Audit pillar → Authorizations audit; Console Identity Intelligence | SUDO rule baselines, SUDO defaults and aliases baselines, and authorization audit surface OS-layer access control evidence. Identity Intelligence surfaces per-identity posture. Customer responsible for the access control policy, role-based access model definition, application-layer authorization, and access review workflow. | | `CIS 7` | Continuous Vulnerability Management — Develop a plan to continuously assess and track vulnerabilities on all enterprise assets within the enterprise's infrastructure | `Supports` | `linuxguard-agent probe` command; Console Compliance Expansion → History | The probe command tests kernel, BPF, fanotify, netlink, audit, and capability prerequisites supporting deployment-time verification. Compliance history surfaces ongoing posture evaluation. Customer responsible for the vulnerability scanning program (network scanners, host scanners, container scanners), prioritization workflow, and remediation tracking. | | `CIS 8` | Audit Log Management — Collect, alert, review, and retain audit logs of events that could help detect, understand, or recover from an attack | `Satisfies` | Agent log (raw events) at `/var/log/linuxguard/agent.log`; Support bundle; Console Compliance Expansion → History | The LinuxGuard agent generates structured audit logs continuously on every enrolled host with timestamps, event categories, and tamper-resistant identity attribution across privilege escalation. Default retention: 50 MB per file, 14-day retention, 5 backups, gzip compression. See [Log Management](/operate/operate/log-management). This is the load-bearing control for LinuxGuard's audit logging pillar. | | `CIS 9` | Email and Web Browser Protections — Improve protections and detections of threats from email and web vectors | `Out of scope` | n/a | Email and browser security are not addressed by LinuxGuard. | | `CIS 10` | Malware Defenses — Prevent or control the installation, spread, and execution of malicious applications, code, or scripts on enterprise assets | `Out of scope` | n/a | Anti-malware deployment and execution prevention are not addressed by LinuxGuard. LinuxGuard is a security monitoring agent, not an anti-malware product. | | `CIS 11` | Data Recovery — Establish and maintain data recovery practices sufficient to restore in-scope enterprise assets to a pre-incident and trusted state | `Out of scope` | n/a | Data recovery, backup management, and restoration testing are not addressed by LinuxGuard. | | `CIS 12` | Network Infrastructure Management — Establish, implement, and actively manage network devices | `Out of scope` | n/a | Network device management is not addressed by LinuxGuard. | | `CIS 13` | Network Monitoring and Defense — Operate processes and tooling to establish and maintain network monitoring and defense against security threats across the enterprise's network infrastructure and user base | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals | Behavioral telemetry at the OS layer surfaces network-related signals visible at the kernel layer. Customer responsible for network-layer monitoring (NDR, IDS/IPS, flow logs, perimeter defense) beyond OS-layer observability. | | `CIS 14` | Security Awareness and Skills Training — Establish and maintain a security awareness program to influence behavior among the workforce to be security conscious and properly skilled to reduce cybersecurity risks to the enterprise | `Out of scope` | n/a | Security awareness training is an organizational responsibility not addressed by LinuxGuard. | | `CIS 15` | Service Provider Management — Develop a process to evaluate service providers who hold sensitive data, or are responsible for an enterprise's critical IT platforms or processes, to ensure these providers are protecting those platforms and data appropriately | `Supports` | Console Compliance Expansion → Reports; framework version pins; SHA-256 manifest on collected support bundles | LinuxGuard is one service provider in the customer's supplier chain. Framework version pins, per-control evidence pointers, and SHA-256 evidence chain integrity support the customer's supplier assessment workflow for LinuxGuard itself. Customer responsible for the broader service provider management program and assessments of other suppliers. | | `CIS 16` | Application Software Security — Manage the security life cycle of in-house developed, hosted, or acquired software | `Out of scope` | n/a | Application software security (SDLC, secure coding, application testing) is not addressed by LinuxGuard. | | `CIS 17` | Incident Response Management — Establish a program to develop and maintain an incident response capability to prepare, detect, and quickly respond to an attack | `Supports` | Agent log (raw events); Console Zero Trust Enforcement → Signals; Console Audit pillar → SUDO execution audit; Support bundle | LinuxGuard supplies telemetry-driven evidence supporting incident response — authentication events, drift events, signal records, SUDO execution audit, and support bundles. Customer responsible for the incident response plan, role assignments, communication workflow, and tabletop exercises. | | `CIS 18` | Penetration Testing — Test the effectiveness and resiliency of enterprise assets through identifying and exploiting weaknesses in controls (people, processes, and technology), and simulating the objectives and actions of an attacker | `Out of scope` | n/a | Penetration testing is a third-party assessment activity not addressed by LinuxGuard. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## Implementation Group considerations CIS Controls v8.1 organizes sub-controls (called Safeguards) into three Implementation Groups (IGs). Customers select the IG that matches their organization's risk profile, expertise, and resource availability. The IG selection determines which Safeguards apply. * **Implementation Group 1 (IG1) — Essential cyber hygiene.** Smaller organizations with limited IT and cybersecurity expertise. 56 Safeguards covering the most basic protections every organization should implement. * **Implementation Group 2 (IG2) — Risk-based cyber defense.** Organizations with moderate resources and greater risk exposure than IG1 organizations. Includes all IG1 Safeguards plus 74 additional Safeguards (130 total). * **Implementation Group 3 (IG3) — Advanced cyber defense.** Organizations with substantial IT and cybersecurity expertise managing significant risk. Includes all IG1 and IG2 Safeguards plus 23 additional Safeguards (153 total). LinuxGuard does not select an IG for the customer. The mapping above identifies which Controls LinuxGuard addresses at the family level; per-Safeguard coverage depends on the customer's selected IG and the specific Safeguard text. Customers documenting LinuxGuard in their CIS Controls implementation tracker reference the family-level mapping and add per-Safeguard notes as needed. ## v8 vs v7.1 CIS Controls v8 (and v8.1) consolidated v7.1's 20 Controls into 18 Controls, reorganized the Sub-Controls into Safeguards, and introduced the Implementation Groups model. Customers cross-referencing legacy CIS Controls v7.1 documentation should treat v7.1 Control numbers as deprecated. The Center for Internet Security publishes a v7.1-to-v8 mapping crosswalk separately. Notable consolidations from v7.1 to v8: * v7.1 CIS 3 (Continuous Vulnerability Management) and v7.1 CIS 4 (Controlled Use of Administrative Privileges) merge content into v8 CIS 7 (Continuous Vulnerability Management) and v8 CIS 5/6 (Account Management / Access Control Management). * v7.1 CIS 6 (Maintenance, Monitoring and Analysis of Audit Logs) becomes v8 CIS 8 (Audit Log Management). * v7.1 CIS 16 (Account Monitoring and Control) merges with v7.1 CIS 5 into v8 CIS 5 (Account Management). This mapping uses v8.1 numbering only. Customers maintaining historical v7.1 documentation should crosswalk per the CIS-published table. ## How to share with auditor Three export paths are available, depending on the auditor's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (CIS Controls v8.1), last-verified date, per-Control coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the auditor wants raw host-level telemetry rather than a console-rendered report. * **Console CSV / JSON export per Control.** Compliance Expansion → CIS Controls v8.1 → Control detail → Evidence tab exports per-Control evidence in machine-readable form for auditors who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table. ## Cross-references * [**CIS Benchmarks**](/audit-and-comply/audit-comply/cis-benchmarks) — distinct from CIS Controls: OS-specific configuration hardening guides referenced by LinuxGuard's baseline detection. See the callout at the top of this page for the separation rationale. * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Audit**](/concepts/concepts/console/audit) — authorizations and SUDO execution audit feeding compliance evidence. * [**Baselines**](/concepts/concepts/console/baselines) — configuration baselines and drift detection that CIS 4 satisfies. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to CIS 8 audit log management. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against CIS Controls v8.1 published 2024-06-01.* # CIS Benchmarks (Linux) CIS Benchmarks Linux control mapping — LinuxGuard agent and console capabilities aligned to per-distro hardening configurations with explicit separation from CIS Controls and Satisfies / Supports / Ou > **Note**: This page maps LinuxGuard against the **CIS Benchmarks for Linux distributions** (per-distro versioning — see the version table below). Last verified against the published Benchmarks on 2026-05-31. Canonical framework documents: [CIS Benchmarks — Linux/Unix Operating Systems](https://www.cisecurity.org/cis-benchmarks#linux-unix). For the vocabulary contract used here, see [Audit & Comply](/audit-and-comply/audit-comply). > **Important — Not the same as CIS Controls**: CIS Benchmarks are OS-specific *configuration hardening guides* — distro-by-distro prescriptive settings for `/etc/sshd_config`, kernel sysctls, package selection, filesystem permissions, audit daemon rules, and similar host-level configuration. CIS Controls v8.1 are 18 *strategic* security control families addressing organizational program scope (e.g., "Audit Log Management"). The two are produced by the same organization (Center for Internet Security) for related but distinct purposes: Benchmarks for system administrators tuning a single host; Controls for security program owners defining what the organization should do. See [CIS Controls](/audit-and-comply/audit-comply/cis-controls) for the strategic mapping that complements this host-level Benchmark mapping. ## Scope This page maps LinuxGuard's agent and console capabilities against the CIS Benchmarks for Linux distributions in scope of LinuxGuard's per-distro support (Debian/Ubuntu, RHEL/CentOS, SUSE/openSUSE, Alpine Linux). The mapping is scoped to Benchmark recommendations that LinuxGuard's baseline detection surface — SSH server configuration, SSH client configuration, account inventory, group inventory, SUDO aliases, SUDO defaults, SUDO rules — observes and reports drift against. Benchmark recommendations covering filesystem mount options, kernel sysctl parameter values, package selection, auditd rule sets, AppArmor / SELinux profile content, firewall rule sets, systemd unit configuration, and per-service hardening (Apache, nginx, PostgreSQL, etc.) are out of scope for this product and are listed in the mapping table as `Out of scope` rather than omitted. This mapping is informational and not a substitute for an independent audit by a qualified assessor. Customers remain responsible for selecting the appropriate Benchmark profile (Level 1 vs Level 2; Server vs Workstation) for their deployment scenario, applying the Benchmark recommendations through configuration management (Ansible, Chef, Puppet, kickstart, cloud-init), and engaging in the per-distro hardening workflow that produces the configured state LinuxGuard's baseline detection observes. ## Shared responsibility > LinuxGuard is a security monitoring agent and console. Compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities. This mapping is informational and not a substitute for an independent audit by a qualified assessor. The shared-responsibility framing for CIS Benchmarks Linux: * **LinuxGuard responsibility.** Detect drift from the customer's baseline configuration of SSH server, SSH client, accounts, groups, SUDO aliases, SUDO defaults, and SUDO rules. The agent compares the current OS-layer configuration state against the customer-defined baseline on each scan cycle and surfaces deviations as Config Drift events. Maintain the framework version pin and per-recommendation evidence pointers. * **Customer responsibility.** Select the applicable Benchmark profile (Level 1 baseline vs Level 2 defense-in-depth; Server vs Workstation), apply the Benchmark recommendations to the host via configuration management or per-distro hardening workflow, define the baseline content in LinuxGuard reflecting the Benchmark-aligned state, and address Benchmark recommendations outside LinuxGuard's baseline surface (filesystem mount options, kernel sysctls, package selection, auditd, AppArmor/SELinux, firewall, systemd, per-service hardening). * **Out-of-scope domains for this framework.** Filesystem mount options, kernel sysctl parameter values, package selection and removal, auditd rule sets, AppArmor / SELinux profile content, firewall rule sets, systemd unit configuration, per-service hardening (Apache, nginx, PostgreSQL, etc.), and the Benchmark application workflow itself (LinuxGuard does not apply hardening — it observes the configured state). ## Per-distro Benchmark version pins The customer's audit period typically pins a specific Benchmark version per in-scope distribution. The table below lists the LinuxGuard-supported distributions, the corresponding CIS Benchmark family, and the load-bearing version-pinning consideration for each. | Distribution family | LinuxGuard support scope | CIS Benchmark name | Version-pinning notes | | ------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Debian / Ubuntu | Debian 12, Ubuntu 22.04 LTS, Ubuntu 24.04 LTS | CIS Debian Linux 12 Benchmark; CIS Ubuntu Linux 22.04 LTS Benchmark; CIS Ubuntu Linux 24.04 LTS Benchmark | Each distro release has its own Benchmark family with independent versioning. Pin the specific Benchmark version (e.g., "CIS Debian Linux 12 Benchmark v1.0.0") at the start of the audit period. | | RedHat / CentOS | RHEL 9, CentOS Stream 9, Rocky Linux 9, AlmaLinux 9 | CIS Red Hat Enterprise Linux 9 Benchmark | The RHEL 9 Benchmark also applies to the RHEL-compatible derivatives (Rocky, Alma, Oracle Linux 9). Pin a single version per audit period. | | SUSE / openSUSE | SUSE Linux Enterprise Server 15, openSUSE Leap 15 | CIS SUSE Linux Enterprise 15 Benchmark | SLES 15 service pack (SP4, SP5, SP6) may affect specific recommendations — verify the Benchmark version covers the customer's SP. | | Alpine Linux | Alpine 3.18, 3.19, 3.20 | CIS Alpine Linux 3 Benchmark | Alpine's musl libc and OpenRC init differ from glibc / systemd-based distros — many Linux-generic recommendations require Alpine-specific adaptation. Verify the Benchmark covers the customer's Alpine minor version. | > **Important — Pin vs floating**: CIS publishes updated Benchmark versions on a per-distro cadence (typically annually or per distro major release). Customers running long audit periods should pin a specific Benchmark version at the start of the period and assess against that version throughout, rather than tracking "latest" — a Benchmark version bump mid-period changes the recommendation set and breaks the audit-period continuity. Document the pinned version in the customer's audit narrative and the LinuxGuard baseline configuration metadata. ## Control mapping The Tier column uses one of three labels and only those three: `Satisfies`, `Supports`, `Out of scope`. The Evidence column points to a row of the canonical [Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location) table or to a specific console page. See [Audit & Comply](/audit-and-comply/audit-comply) for the three-tier vocabulary contract. The Recommendation ID column references the recommendation category common across the per-distro Benchmarks; per-distro recommendation numbering varies. | Recommendation category | Description | Tier | Evidence | Notes | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | SSH server (sshd) configuration | Ensure `sshd_config` hardening — `PermitRootLogin no`, `PasswordAuthentication no`, `Protocol 2`, `MaxAuthTries`, `ClientAliveInterval`, `LoginGraceTime`, `Banner`, ciphers and MACs allowlist, key exchange algorithm allowlist, `AllowUsers` / `AllowGroups` | `Satisfies` | Console Baselines → SSHD config; Console Zero Trust Enforcement → Config Drift | The SSHD config baseline captures `/etc/ssh/sshd_config` and `/etc/ssh/sshd_config.d/*` contents; drift detection surfaces any change to the file (including reversions of hardening). See [Baselines § SSHD config](/concepts/concepts/console/baselines#sshd-config). | | SSH client (ssh) configuration | Ensure `/etc/ssh/ssh_config` hardening — outbound cipher choices, `StrictHostKeyChecking`, `ForwardAgent`, `IdentityFile` preferences | `Satisfies` | Console Baselines → SSH config; Console Zero Trust Enforcement → Config Drift | The SSH config baseline captures `/etc/ssh/ssh_config` and `/etc/ssh/ssh_config.d/*` contents; drift detection surfaces deviations including package-upgrade-induced changes. See [Baselines § SSH config](/concepts/concepts/console/baselines#ssh-config). | | Account inventory and lifecycle | Ensure local user accounts match the expected inventory; ensure no unauthorized accounts; ensure UID consistency where required; ensure account removal on employee departure | `Satisfies` | Console Baselines → accounts; Console Zero Trust Enforcement → Config Drift | The accounts baseline records the expected user accounts (optionally with UID, primary GID, home directory, login shell); drift detection surfaces unexpected creation, deletion, or modification. See [Baselines § Accounts](/concepts/concepts/console/baselines#accounts). | | Group inventory and membership | Ensure groups match the expected inventory; ensure sensitive group membership (wheel, sudo, docker, adm) is restricted | `Satisfies` | Console Baselines → groups; Console Zero Trust Enforcement → Config Drift | The groups baseline records expected group memberships with sensitive groups receiving stricter scrutiny in drift attribution. See [Baselines § Groups](/concepts/concepts/console/baselines#groups). | | SUDO aliases | Ensure `Host_Alias`, `User_Alias`, `Runas_Alias`, `Cmnd_Alias` definitions in `/etc/sudoers` and `/etc/sudoers.d/*` match the expected set | `Satisfies` | Console Baselines → SUDO aliases; Console Zero Trust Enforcement → Config Drift | The SUDO aliases baseline catches aliases gaining unexpected entries (a `Cmnd_Alias DEPLOY` gaining `/bin/bash`) that expand the reach of rules referencing the alias. See [Baselines § SUDO aliases](/concepts/concepts/console/baselines#sudo-aliases). | | SUDO defaults | Ensure `Defaults` lines in sudoers configuration match the expected set — `timestamp_timeout`, `passwd_tries`, `env_reset`, `secure_path`, `requiretty`, `logfile` | `Satisfies` | Console Baselines → SUDO defaults; Console Zero Trust Enforcement → Config Drift | The SUDO defaults baseline catches changes that weaken audit posture (a `logfile` removal) or relax authentication friction (`timestamp_timeout` extension). See [Baselines § SUDO defaults](/concepts/concepts/console/baselines#sudo-defaults). | | SUDO rules | Ensure user / group / runas / command rule lines in sudoers match the approved rule set | `Satisfies` | Console Baselines → SUDO rules; Console Zero Trust Enforcement → Config Drift | The SUDO rules baseline catches rule additions, modifications, and removals — the core surface of who-can-do-what under privilege escalation. See [Baselines § SUDO rules](/concepts/concepts/console/baselines#sudo-rules). | | Filesystem configuration | Ensure separate filesystems for `/tmp`, `/var`, `/var/log`, `/var/log/audit`, `/home`; ensure mount options (nodev, nosuid, noexec) on temporary and removable media | `Out of scope` | n/a | Filesystem mount configuration is not addressed by LinuxGuard. | | Kernel sysctl parameters | Ensure kernel parameter hardening — `net.ipv4.tcp_syncookies=1`, `kernel.randomize_va_space=2`, `fs.suid_dumpable=0`, IPv6 redirect / source-routing disabling | `Out of scope` | n/a | Kernel sysctl parameter values are not addressed by LinuxGuard. | | Package management | Ensure unauthorized packages removed (telnet, rsh, talk, ypbind, tftp); ensure mail and DNS clients restricted; ensure package signature verification enabled | `Out of scope` | n/a | Package selection and removal are not addressed by LinuxGuard. | | Audit daemon (auditd) rules | Ensure `auditd` running, audit log retention, audit rule set covering account changes, system administration, file access, login events | `Supports` | Agent log (raw events); Console Compliance Expansion → History | LinuxGuard's own audit log surface (eBPF-based authentication and file integrity events) provides additional audit coverage independent of auditd. Customer responsible for auditd configuration, rule set, and audit log retention. | | AppArmor / SELinux | Ensure mandatory access control enabled and enforcing; ensure profile / policy set covers in-scope services | `Out of scope` | n/a | MAC enforcement is not addressed by LinuxGuard. The console's [Zero Trust Expansion → SELinux status](/concepts/concepts/console/zero-trust-expansion) surface reports SELinux mode but does not enforce. | | Firewall configuration | Ensure firewall enabled (iptables, nftables, firewalld, ufw); ensure default-deny inbound; ensure rule set covers in-scope services | `Out of scope` | n/a | Firewall rule sets are not addressed by LinuxGuard. | | systemd unit hardening | Ensure systemd unit `RestrictNamespaces`, `NoNewPrivileges`, `ProtectSystem`, `ProtectHome`, `PrivateTmp` directives configured per service | `Out of scope` | n/a | systemd unit configuration is not addressed by LinuxGuard. | | Per-service hardening | Ensure Apache, nginx, PostgreSQL, MySQL/MariaDB, Bind, NTP, time daemons hardened per service-specific Benchmark sections | `Out of scope` | n/a | Per-service application hardening is not addressed by LinuxGuard. | > **Important**: Every Satisfies claim cites a specific agent feature and a specific evidence pointer. Every Supports claim states what the customer must implement to achieve full satisfaction. Every Out-of-scope row carries a one-line note explaining why — silence is interpreted as an implicit Satisfies claim. ## LinuxGuard relationship to CIS Benchmarks LinuxGuard's relationship to CIS Benchmarks is observation, not enforcement. The agent does not apply Benchmark recommendations to the host — applying recommendations is the customer's responsibility, handled through configuration management or a one-time hardening campaign. The agent observes the configured state and, given a customer-defined baseline reflecting the Benchmark-aligned state, surfaces drift when the host's configuration moves away from the baseline. The practical workflow: 1. **Customer applies the CIS Benchmark** to the host through Ansible, Chef, Puppet, kickstart, cloud-init, or a manual hardening pass. The host reaches a Benchmark-aligned configured state. 2. **Customer defines the LinuxGuard baseline** reflecting the Benchmark-aligned state — for SSHD config, the baseline captures the hardened `/etc/ssh/sshd_config` contents; for SUDO rules, the baseline captures the approved rule set; and so on. 3. **LinuxGuard's baseline scan cycle** compares the current OS-layer configuration against the baseline on each run. The scan cadence is configurable; defaults are documented in [Baselines § Baseline settings](/concepts/concepts/console/baselines#baseline-settings). 4. **Drift events surface in Zero Trust Enforcement → Config Drift** when the host's configuration deviates from the baseline. Drift attribution identifies the change source where the agent can determine it. The Baselines pillar in the console is the canonical surface for this workflow — see [Baselines](/concepts/concepts/console/baselines) for the per-category capabilities. The baseline content itself (the configured state the customer declares as "expected") encodes the Benchmark recommendation; LinuxGuard does not ship pre-built CIS-Benchmark-aligned baseline templates. ### What LinuxGuard does not do The boundary is sharp at a few points worth naming explicitly: * **No Benchmark-as-a-service hardening engine.** LinuxGuard does not apply CIS Benchmark recommendations to hosts. Customers run their own hardening workflow. * **No Benchmark recommendation-to-baseline auto-translation.** The customer manually translates the Benchmark recommendation set into the baseline content (e.g., reading `5.2.x SSH Server Configuration` recommendations and reflecting them in the SSHD config baseline). There is no automated import of a CIS Benchmark profile into a LinuxGuard baseline. * **No coverage of Out-of-scope recommendation categories.** Filesystem mount options, kernel sysctls, package selection, auditd rules, AppArmor/SELinux profiles, firewall rule sets, systemd unit hardening, and per-service hardening are observed neither at the baseline layer nor at the drift layer. * **No remediation action on drift.** Drift detection surfaces deviations but does not revert them. The customer's incident response and configuration management workflows determine remediation. The boundary is the source of the "Satisfies" rating on the seven baseline categories above and the "Out of scope" rating on everything else — the Benchmark's coverage is broader than the baseline pillar's coverage, and the page names which subset overlaps. ## Profile selection CIS Benchmarks ship in profile variants per distro. The customer selects the profile matching the deployment scenario before applying recommendations. * **Level 1 — Server profile.** Baseline hardening recommendations applicable to most servers. The default starting point for production server hardening. * **Level 1 — Workstation profile.** Baseline hardening recommendations applicable to most workstations. Differs from Server in service expectations (X11, browser plugins, etc.). * **Level 2 — Server profile.** Defense-in-depth recommendations on top of Level 1 Server. Higher friction; reserved for high-risk servers. * **Level 2 — Workstation profile.** Defense-in-depth recommendations on top of Level 1 Workstation. LinuxGuard does not select a profile for the customer. The mapping above is profile-agnostic — the baseline categories (SSH server, SSH client, accounts, groups, SUDO aliases, SUDO defaults, SUDO rules) apply across all profiles, with the customer's baseline content encoding the profile-specific settings. ## How to share with auditor Three export paths are available, depending on the auditor's evidence preference: * **Console Compliance Expansion reports.** Console pillar → Compliance Expansion → Reports produces dated, signed, auditor-shareable evidence packages (PDF / CSV / JSON) per [Compliance Expansion](/concepts/concepts/console/compliance-expansion#reports). Each report includes the framework version (the pinned per-distro Benchmark version), last-verified date, per-recommendation-category coverage, per-server pass / fail breakdown, suppressions in effect, and a manifest with SHA-256 verification. * **Support bundles for host-level evidence.** `support-bundle collect` on each host produces a tar.zst archive with agent logs, redacted configuration, and a bundle manifest — see [Support Bundles](/operate/operate/support-bundles). Bundles are useful when the auditor wants raw host-level telemetry rather than a console-rendered report. * **Console CSV / JSON export per recommendation category.** Compliance Expansion → CIS Benchmark → recommendation category detail → Evidence tab exports per-category evidence in machine-readable form for auditors who want to ingest evidence into their own GRC tooling. > **Security Note**: Support bundles include the raw `agent.log` and rotated segments. Attribute-key redaction (api\_key / \*\_token / \*\_secret) is applied; PII (hostnames, IPs, usernames, paths, command args) is NOT additionally redacted. Review every evidence package before sharing externally. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table. ## Cross-references * [**CIS Controls**](/audit-and-comply/audit-comply/cis-controls) — distinct from CIS Benchmarks: 18 strategic security control families. See the callout at the top of this page for the separation rationale. * [**Baselines**](/concepts/concepts/console/baselines) — the load-bearing console surface for the baseline categories this Benchmark mapping references. * [**Audit & Comply**](/audit-and-comply/audit-comply) — vocabulary contract, framework version pin reference, forbidden-words list, scope statement template. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — console pillar; canonical Evidence Location pointer set. * [**Support Bundles**](/operate/operate/support-bundles) — per-file redaction status table; pre-share PII warning. * [**Log Management**](/operate/operate/log-management) — log retention and rotation relevant to evidence retention. * [**Glossary**](/reference/reference/glossary) — framework acronyms and compliance vocabulary definitions. *** *Last reviewed: 2026-05-31 against the per-distro CIS Benchmarks listed in the Per-distro Benchmark version pins table above.* # Reference Cross-cutting reference lookups for LinuxGuard — agent commands, supported distributions, and the v4.0 glossary. Cross-cutting information lookups: per-command CLI pages, environment variables, exit codes, signals, configuration keys, supported distributions matrix, and glossary. ## What's in this section * [**Agent Commands**](/reference/reference/agent-commands) — Reference for the linuxguard-agent command-line interface — start, stop, status, show-config, enroll, and unenroll commands. * [**Supported Distributions**](/reference/reference/supported-distributions) — Supported Linux distributions for the LinuxGuard agent — Debian, RedHat, SUSE, and Alpine families with version coverage. * [**Glossary**](/reference/reference/glossary) — Glossary of LinuxGuard terminology — agent, console, eBPF, enrollment, modules, and related security concepts. # Agent Commands Reference for the linuxguard-agent command-line interface — start, stop, status, show-config, enroll, and unenroll commands. This page documents the `linuxguard-agent` command-line interface. Use these commands to manage the LinuxGuard agent on your system. ## Command Reference | Command | Description | | ----------- | ----------------------------- | | start | Start the LinuxGuard agent | | stop | Stop the LinuxGuard agent | | status | Check if the agent is running | | show-config | Display current configuration | | enroll | Enroll system into LinuxGuard | | unenroll | Remove agent from tenant | ## linuxguard-agent start Start the LinuxGuard agent. **Synopsis:** ```bash sudo linuxguard-agent start ``` **Description:** Starts the LinuxGuard agent process. The agent typically starts automatically after installation, so this command is primarily used to manually restart the agent after it has been stopped. ## linuxguard-agent stop Stop the LinuxGuard agent. **Synopsis:** ```bash sudo linuxguard-agent stop ``` **Description:** Stops the LinuxGuard agent process. While stopped, no monitoring data will be collected and the server will appear offline in the LinuxGuard console. ## linuxguard-agent status Check if the agent is running. **Synopsis:** ```bash sudo linuxguard-agent status ``` **Description:** Reports whether the LinuxGuard agent is currently running and displays the process ID if active. **Examples:** When the agent is running: ```bash $ sudo linuxguard-agent status linuxguard-agent is running with PID: 1234 ``` When the agent is not running: ```bash $ sudo linuxguard-agent status linuxguard-agent is not running ``` ## linuxguard-agent show-config Display current agent configuration. **Synopsis:** ```bash linuxguard-agent show-config ``` **Description:** Displays the current agent configuration in JSON format. This command does not require sudo and is useful for verifying enrollment settings and troubleshooting configuration issues. **Example:** ```bash $ linuxguard-agent show-config { "tenant_id": "tenant_abc123", "api_key": "ak_***", "endpoint": "https://api.linuxguard.io/v1/", "environment": "production", "tags": ["web-server", "us-east"] } ``` ## linuxguard-agent enroll Enroll this system into LinuxGuard. **Synopsis:** ```bash sudo linuxguard-agent enroll --api-key= --tenant-id= [OPTIONS] ``` **Description:** Enrolls the system into your LinuxGuard tenant. After enrollment, the agent begins sending monitoring data to the LinuxGuard console. **Options:** | Option | Required | Description | | ------------- | -------- | ------------------------------------------------------------------- | | --api-key | Yes | API Key from LinuxGuard console | | --tenant-id | Yes | Tenant ID from LinuxGuard console | | --environment | No | Environment name to assign (e.g., production, staging, development) | | --group | No | Alias for --environment (backward compatible) | | --tag | No | Tag to assign (can be repeated for multiple tags) | > **Note**: The agent accepts both `--environment` and `--group`. The `--group` flag is an alias for backward compatibility. Use `--environment` for new enrollments. **Examples:** Basic enrollment: ```bash sudo linuxguard-agent enroll --api-key=ak_xxx --tenant-id=tenant_xxx ``` With environment and tags: ```bash sudo linuxguard-agent enroll \ --api-key=ak_xxx \ --tenant-id=tenant_xxx \ --environment=production \ --tag=web-server \ --tag=us-east ``` **Success output:** ``` >> Sending initial snapshot... >> Initial snapshot sent successfully >> Successfully enrolled to LinuxGuard Endpoint: https://api.linuxguard.io/v1/ ``` **Already enrolled output:** ``` This server has been enrolled since Mon, 01 Feb 2026 12:00:00 UTC ``` > **Note**: After enrollment, the environment and tags are persisted locally and reused across agent restarts. To change the environment or tags, unenroll and re-enroll with the desired values. ## linuxguard-agent unenroll Remove this agent from the LinuxGuard tenant. **Synopsis:** ```bash sudo linuxguard-agent unenroll ``` **Description:** Removes the server from LinuxGuard management. After unenrolling, the server will no longer appear in the LinuxGuard console and no monitoring data will be collected. To resume monitoring, you must run the enroll command again with valid credentials. *** **Related**: [Quick Start](/get-started/get-started/quick-start) | [Configuration Guide](/configure/configure) | [Glossary](/reference/reference/glossary) # CLI Reference Per-command reference for the linuxguard-agent CLI — start, config, probe, and additional commands shipping in subsequent phases. Per-command reference for the `linuxguard-agent` binary. Each page documents one command with five mandatory sections: **Flags**, **Environment**, **Signals**, **Exit codes**, and **Examples**. Flags, environment variables, signals, and exit codes are verified against the agent source. For day-to-day operator workflows (install, configure, deploy, respond), see the lifecycle phases in the left navigation. This section is the canonical destination when you need to look up a flag or env-var mid-task. ## Available commands | Command | Purpose | Page | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | `start` | Run the LinuxGuard agent in typical service mode or ephemeral (container/Kubernetes) mode. | [start](/reference/reference/cli/start) | | `config` | Read or mutate individual runtime configuration keys (`set`, `get`, `unset`, `list-keys`). | [config](/reference/reference/cli/config) | | `probe` | Check kernel, eBPF, fanotify, netlink, audit, and Linux-capability availability on the host. | [probe](/reference/reference/cli/probe) | | `enroll` | Bind the agent to a tenant via long-lived API key. | [enroll](/reference/reference/cli/enroll) | | `unenroll` | Remove the agent from its tenant (currently a placeholder — see page for the operator workaround). | [unenroll](/reference/reference/cli/unenroll) | | `support-bundle` | Collect a diagnostic archive locally (`collect`) or upload an existing archive via a presigned S3 URL (`upload`). | [support-bundle](/reference/reference/cli/support-bundle) | | `show-config` | Print the entire current configuration as indented JSON to stdout. | [show-config](/reference/reference/cli/show-config) | | `status` | Report whether the agent process is running (PID-file check + signal-0 probe). | [status](/reference/reference/cli/status) | | `--version` / `-v` | Print the agent build version, commit, and build time. | [version](/reference/reference/cli/version) | For a brief overview of the v3.0 agent commands surface, see [Agent Commands](/reference/reference/agent-commands). The pages above are the v4.0 canonical reference and supersede that overview for the commands they cover. ## Cross-cutting reference pages The reference pages below document surface that cuts across multiple commands. Each per-command page above links into these from its Signals / Environment / Exit codes sections. | Page | Purpose | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | [signals](/reference/reference/cli/signals) | Which POSIX signals the agent handles (`SIGHUP`, `SIGTERM`, `SIGINT`), what each handler does, and the `128+signum` re-raise convention. | | [env-variables](/reference/reference/cli/env-variables) | Every `LINUXGUARD_*` environment variable the agent reads, including the `LINUXGUARD_ENROLL_TOKEN` immediately-unset-after-read protection. | | [exit-codes](/reference/reference/cli/exit-codes) | Universal exit codes (`0`, `1`, `2`, `130`, `143`) and per-command divergences (e.g., `probe` always `0`). | ## Conventions These conventions apply to every per-command page in this section. ### Flag form User-facing flags are documented in their long form (`--api-key`, `--tenant-id`, `--environment`). The agent source uses urfave/cli/v2's flag plumbing which may expose short aliases internally; only the long forms are part of the public interface and only the long forms are documented here. The `--environment` flag has one documented alias, `--group`, preserved for backward compatibility with v3.0 enrollment scripts; see [Conventions](/) for the policy. ### Environment-variable precedence For flags that bind to an environment variable (notably `--enroll-token` → `LINUXGUARD_ENROLL_TOKEN`, `--node-id` → `LINUXGUARD_NODE_NAME`, `--api-url` → `LINUXGUARD_API_URL`, `--tenant-id` → `LINUXGUARD_TENANT_ID`, `--loader-embedded` → `LINUXGUARD_LOADER_EMBEDDED`), an explicit flag value takes precedence over the environment variable. When the flag is omitted, urfave/cli/v2 reads the bound `EnvVars` entry. When neither is set, the agent uses its built-in default. `LINUXGUARD_ENROLL_TOKEN` is a special case: the agent reads it once at startup and immediately calls `os.Unsetenv` on it so the raw token cannot leak via `/proc//environ` while the agent runs. Do not rely on it being readable after the first read. ### Exit-code summary | Code | Convention | | ----- | ------------------------------------------------------------------------------------------------------------------------ | | `0` | Success — command completed without error, or the command is non-fatal by design (`probe` always exits 0; see its page). | | `1` | General error — surfaced via `log.Fatal` after the agent run returns a non-nil error. | | `130` | SIGINT (Ctrl-C) — interactive cancellation; `os.Exit(128 + int(syscall.SIGINT))`. | | `143` | SIGTERM — orchestrator-driven shutdown; `os.Exit(128 + int(syscall.SIGTERM))`. | The `128 + signum` convention is the standard shell exit code for signal-induced termination. The agent re-raises caught signals from `main` (not the goroutine) so containerized PID-1 deployments exit with the conventional code rather than the Go runtime's `dieFromSignal` exit(2) fallback. ### Signal handling The `start` command installs handlers for `SIGINT`, `SIGTERM`, and `SIGHUP` via `signal.Notify`. `SIGINT` and `SIGTERM` trigger graceful shutdown and the signal-derived exit code. `SIGHUP` has two effects in the start process: 1. The active log writer (lumberjack rotator) calls `Rotate()` to close and reopen the log file descriptor. This enables coexistence with external `logrotate`. 2. A separate handler re-reads the persisted log level from disk and applies it without a restart. Other commands (`config`, `probe`, `enroll`, etc.) are one-shot invocations and do not install signal handlers. *** **Related**: [Agent Commands](/reference/reference/agent-commands) | [Reference](/reference/reference) | [Configure](/configure/configure) # start Reference for linuxguard-agent start — typical service mode and ephemeral mode flags, environment variables, signals, and exit codes. ## Synopsis Start the LinuxGuard agent. Two operating modes are supported: * **Typical service mode** — the agent runs as a long-lived systemd service on a host, reads its enrollment from the persisted local config database (`/var/lib/linuxguard/`), and writes a PID file to coordinate with `linuxguard-agent stop` and `linuxguard-agent status`. * **Ephemeral mode** — the agent runs as the main process inside a container (typically PID 1), enrols once via a short-lived TOTP token supplied through `LINUXGUARD_ENROLL_TOKEN`, holds the resulting mTLS cert chain in memory, and skips PID-file machinery because the container orchestrator owns lifecycle. Triggered by any of: the `--ephemeral` flag, a non-empty `--enroll-token` value, or detection of PID 1 / the `LINUXGUARD_PID1_CHILD` re-exec sentinel. ```bash linuxguard-agent start [flags] ``` ## Flags | Flag | Type | Default | Description | | ------------------------ | ------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--api-url ` | string | channel-derived (`stable`→`https://api.linuxguard.io/v1/`; otherwise `https://dev-api.linuxguard.io/v1/`) | Override the LinuxGuard API base URL for ephemeral mode. Whitespace-only values are treated as empty. Reads `LINUXGUARD_API_URL` when the flag is omitted. | | `--config-dir ` | string | `/var/lib/linuxguard/` on Linux, `./` for local builds | Override the local config directory. Ignored in ephemeral mode. | | `--enroll-token ` | string | — | Enrollment token for ephemeral mode. Prefer the `LINUXGUARD_ENROLL_TOKEN` env var: the agent reads the env-bound value once at startup and immediately unsets it so the raw token does not remain visible via `/proc//environ`. | | `--ephemeral` | bool | `false` | Run in ephemeral (containerised) mode: enrol via `LINUXGUARD_ENROLL_TOKEN`, hold the cert chain in memory, never write to `/var/lib/linuxguard/`. Requires either Downward API env vars (`LINUXGUARD_NODE_NAME` + `LINUXGUARD_POD_UID`) or `--workload-id`. | | `--loader-embedded` | bool | auto-on with the `loader_embedded` build tag under PID 1 or `--ephemeral` | Force the in-process embedded eBPF loader. Reads `LINUXGUARD_LOADER_EMBEDDED` when the flag is omitted. | | `--node-id ` | string | — | Kubernetes node name (Downward API). Populates the workload-id derivation. Reads `LINUXGUARD_NODE_NAME` when the flag is omitted. | | `--server-id ` | string | — | Pre-fill server ID for re-enrol continuity. Optional. | | `--tenant-id ` | string | — | Tenant ID the agent enrols into. Required for the TOTP-token ephemeral path (the backend's `/agent/enroll` handler rejects with `400 "tenantId required for TOTP enrollment"` when the body is missing this value). Optional on the long-lived API-key path. Reads `LINUXGUARD_TENANT_ID` when the flag is omitted. | | `--tls-cache` | bool | `false` | Opt-in: write cert chain + token-hash tag to `/run/linuxguard/tls/` (mode `0700`/`0600`) so a container restart can reuse the cache without re-enrolling. Docker operators additionally pass `--tmpfs /run/linuxguard:rw,mode=0700,size=10m`. | | `--workload-id ` | string | — | Explicit workload identifier (sha256 hex). Required when the Downward API env vars are absent. Hard-error if neither this flag nor `LINUXGUARD_NODE_NAME` + `LINUXGUARD_POD_UID` are set. | ### Enrollment flags Two enrollment paths are supported on the `start` command: * **Long-lived API key (typical service mode).** The agent reuses an enrollment performed previously via `linuxguard-agent enroll` (documented in [Agent Commands](/reference/reference/agent-commands) for the v3.0 surface; phase 18 will ship the per-command v4.0 page). `start` reads the persisted `tenant_id`, `api_key`, `base_url`, and `server_id` from the local config database. * **Short-lived TOTP enrollment token (ephemeral mode).** Supply the token via `LINUXGUARD_ENROLL_TOKEN` (preferred) or the `--enroll-token` flag, plus `--tenant-id` (required by the backend for the TOTP path), plus a workload identifier either via Downward API env vars or `--workload-id`. The agent posts a one-shot enrollment, receives the mTLS cert chain in the response, holds it in memory (or in `/run/linuxguard/tls/` when `--tls-cache` is set), and never writes to `/var/lib/linuxguard/`. The `--server-id` flag is optional in either path and provides re-enrol continuity when an existing server identity is being recycled. ### Ephemeral mode flags The trio `--ephemeral` + `--workload-id` + `--tls-cache` configures the container-friendly mode. The agent treats the presence of a non-empty `--enroll-token` (or its env-bound equivalent) as an implicit `--ephemeral`, so the explicit flag is not required when `docker run -e LINUXGUARD_ENROLL_TOKEN=...` supplies the token. The agent also auto-detects PID 1 as ephemeral so containerised PID-1 deployments do not need the flag at all. In ephemeral mode the agent does NOT call `agent.EnsureNotRunning` or `agent.WritePID`; the container orchestrator owns lifecycle and a parent-vs-worker PID race would otherwise kill the worker before the first heartbeat. ### Network and storage flags `--api-url` (or `LINUXGUARD_API_URL`) overrides the channel-baked default base URL. Whitespace-only values are treated as empty so an operator who exports `LINUXGUARD_API_URL=""` does not silently route the agent to a no-host enrol POST. The resolution order is: explicit flag > env var > channel default. Channel default is determined by the binary's build-time `channel` ldflag: `stable` returns `https://api.linuxguard.io/v1/`; anything else (including `unstable` and empty) returns the dev backend. `--tls-cache` controls whether the ephemeral cert chain is mirrored to a tmpfs path for restart continuity. Off by default. Without `--tls-cache`, a container restart triggers a fresh enrollment. ## Environment | Variable | Default | Description | Used by | | ---------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | | `LINUXGUARD_ENROLL_TOKEN` | — | TOTP enrollment token consumed once at startup and immediately unset to avoid `/proc//environ` leaks. Bound to the `--enroll-token` flag. | `start` (ephemeral) | | `LINUXGUARD_NODE_NAME` | — | Kubernetes node name supplied via the Downward API `fieldRef`. Bound to the `--node-id` flag. Feeds the workload-id derivation. | `start` (ephemeral) | | `LINUXGUARD_POD_UID` | — | Kubernetes pod UID supplied via the Downward API `fieldRef`. Read directly via `os.Getenv` (no flag binding). Required when `--workload-id` is not provided. | `start` (ephemeral) | | `LINUXGUARD_TENANT_ID` | — | Tenant ID the agent enrols into. Bound to the `--tenant-id` flag. Required for the TOTP path; optional for the API-key path. | `start` (ephemeral) | | `LINUXGUARD_API_URL` | channel default | Override the LinuxGuard API base URL. Bound to the `--api-url` flag. Whitespace-only values are treated as empty. | `start` (ephemeral) | | `LINUXGUARD_LOADER_EMBEDDED` | — | Force the in-process embedded eBPF loader. Bound to the `--loader-embedded` flag. | `start` | | `LINUXGUARD_PID1_CHILD` | — | Internal sentinel set by the agent's PID-1 init re-exec wrapper. Operators should not set this manually. When present (or when `os.Getpid() == 1`), the agent treats the context as ephemeral and skips PID-file machinery. | `start` (PID-1 detection) | ## Signals The `start` command installs a single handler goroutine plus a separate SIGHUP listener for log-level reload. All other agent commands are one-shot and do not install signal handlers. | Signal | Behavior | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SIGHUP` | Two independent effects: (1) the active lumberjack rotator calls `Rotate()` to close and reopen the current log file descriptor — enables coexistence with external `logrotate` via a postrotate `kill -HUP`. (2) The log-level reload handler re-runs `config.Setup` and applies the resolved level via `lglog.SetLevel` so a `config set log_level` change takes effect without restart. | | `SIGTERM` | Graceful shutdown. The signal is stored in the `caughtSignal` atomic value, the agent context is cancelled, and `main` returns. After the agent run unwinds, the agent calls `os.Exit(128 + int(syscall.SIGTERM))` = **`os.Exit(143)`**. | | `SIGINT` | Graceful shutdown (Ctrl-C). Same path as SIGTERM. The agent calls `os.Exit(128 + int(syscall.SIGINT))` = **`os.Exit(130)`**. | The agent re-raises caught signals from `main` (not the signal-handling goroutine) so the re-raise is guaranteed to run on a goroutine the runtime keeps alive until `main` returns. The earlier `signal.Reset` + `syscall.Kill` approach routed through Go's `dieFromSignal` and silently exited 2 in containerized PID-1 deployments; the `os.Exit(128+signum)` approach matches `docker wait`'s reported exit code. > **Important**: An external `logrotate` postrotate script must `kill -HUP` the running agent PID to close and reopen the agent's log file descriptor; otherwise the rotated file remains open via the inherited fd and disk usage continues growing on the inode of the rotated file. ## Exit codes | Code | Meaning | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Successful operation. `start` does not exit 0 in normal long-running service mode; `0` is observed only for `--help` and similar early-exit paths. | | `1` | General error — surfaced via `log.Fatal(err)` after the agent run returns a non-nil error. Includes enrollment failures, PID-file collisions in typical service mode, and most agent-runtime errors. | | `130` | SIGINT (Ctrl-C) — graceful interactive cancellation. `os.Exit(128 + int(syscall.SIGINT))`. | | `143` | SIGTERM — graceful orchestrator-driven shutdown. `os.Exit(128 + int(syscall.SIGTERM))`. | ## Examples ### Typical service mode (host install) The agent has already been enrolled via `linuxguard-agent enroll`; `start` reuses the persisted enrollment from `/var/lib/linuxguard/`. ```bash sudo linuxguard-agent start ``` In packaged installs this is invoked by the `linuxguard-agent.service` systemd unit on boot; manual invocation is for development and incident-response scenarios. ### Ephemeral mode (Docker) Supply the enrollment token through an environment variable so the value never appears on the command line or in shell history. The agent reads it once and unsets it before any goroutine forks. ```bash docker run --rm \ --pid=host \ --cap-add=SYS_ADMIN --cap-add=BPF --cap-add=PERFMON \ -e LINUXGUARD_ENROLL_TOKEN="$ENROLL_TOKEN" \ -e LINUXGUARD_TENANT_ID="$TENANT_ID" \ -e LINUXGUARD_NODE_NAME="$(hostname)" \ -e LINUXGUARD_POD_UID="$(uuidgen)" \ --tmpfs /run/linuxguard:rw,mode=0700,size=10m \ ghcr.io/linuxguardx/linuxguard-agent:vX.Y.Z \ linuxguard-agent start --tls-cache ``` ### Ephemeral mode (Kubernetes DaemonSet, abbreviated) ```yaml env: - name: LINUXGUARD_ENROLL_TOKEN valueFrom: secretKeyRef: name: linuxguard-enroll key: token - name: LINUXGUARD_TENANT_ID valueFrom: secretKeyRef: name: linuxguard-enroll key: tenantId - name: LINUXGUARD_NODE_NAME valueFrom: fieldRef: fieldPath: spec.nodeName - name: LINUXGUARD_POD_UID valueFrom: fieldRef: fieldPath: metadata.uid args: ["start", "--tls-cache"] ``` The full DaemonSet manifest with `securityContext`, `hostPath` rationale, Pod Security Standard profile, and RBAC ships in Phase 20. ### Reload log level without restart `config set log_level` persists the new value and sends `SIGHUP` to the running agent. The SIGHUP handler in `start` re-reads the persisted config and applies the new level immediately. ```bash sudo linuxguard-agent config set log_level debug ``` The single `config set` command performs the persist + SIGHUP in one step (see [`config`](/reference/reference/cli/config)). External tools that bypass `config set` (e.g., editing the config database directly) must `kill -HUP $(cat /var/run/linuxguard-agent.pid)` themselves. *** **Related**: [config](/reference/reference/cli/config) | [probe](/reference/reference/cli/probe) | [CLI Reference](/reference/reference/cli) | [Reference](/reference/reference) # config Reference for linuxguard-agent config — set, get, unset, and list-keys subcommands for runtime configuration without restarting the agent. ## Synopsis Read or mutate individual runtime configuration keys. The `config` command exposes only **toggleable** fields — fields whose Go type is `bool`, `string`, or `[]string`. Identity fields (`server_id`, `tenant_id`, `api_key`, `env`, `mode`, `base_url`) are NOT exposed via this command; they are bound at enrollment and immutable for the agent's lifetime. ```bash linuxguard-agent config [args] ``` ## Subcommands | Subcommand | Synopsis | Purpose | | ----------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `set` | `linuxguard-agent config set ` | Persist a toggleable key. Bool values: `true`/`false`/`1`/`0`. String slices: comma-separated. The `log_level` key triggers a special path (validate + persist + SIGHUP). | | `get` | `linuxguard-agent config get ` | Print the current value of a single toggleable key. Bool fields render as `true`/`false`; string slices render comma-separated. | | `unset` | `linuxguard-agent config unset ` | Clear a key. Currently supports only `log_level` (clears the local pin and SIGHUPs the running agent so the precedence chain falls back to ack-delivered → tenant default → built-in info). | | `list-keys` | `linuxguard-agent config list-keys` | Print all toggleable keys with their current values in struct declaration order. | ## Toggleable keys The full set of toggleable keys is enumerated by `linuxguard-agent config list-keys` against the running binary — the canonical list is exposed by the agent's `Config.ListKeys()` API and depends on the `json:` struct tags present in the `Config` type. The matrix below documents the keys whose behavior is non-obvious. Bool values accept `true`/`false`/`1`/`0`; string slices are comma-separated. | Key | Type | Default | Description | Reload behavior | | ---------------------- | -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `log_level` | string | `info` | Wire-format level: lowercase `trace` / `debug` / `info` / `warn` / `error`. Strict — `INFO`, `Info`, integer codes, or any other casing are rejected. Uses the special path described below. | **Validate + persist + SIGHUP** delivered to the running agent. Applied without restart. | | `logging.max_size_mb` | int (1..10000) | 50 | Lumberjack rotation size threshold in MB. Set to e.g. `100` to allow 100 MB per rotated segment. | Applied at next rotation point. | | `logging.max_age_days` | int (0..3650) | 14 | Days a rotated backup is retained before lumberjack deletes it. Explicit `0` means no age-based pruning. | Applied at next rotation point. | | `logging.max_backups` | int (0..100) | 5 | Maximum number of rotated backup files lumberjack retains. Explicit `0` means retain all. | Applied at next rotation point. | | `logging.compress` | bool | `true` | Whether lumberjack gzip-compresses each rotated backup. | Applied at next rotation point. | | `tags` | string slice | — | Comma-separated tag names applied to the agent's identity. Documented elsewhere; included here as a list-keys example. | | > **Important**: Identity fields (`server_id`, `tenant_id`, `api_key`, `env`, `mode`, `base_url`) are NOT toggleable via `config set`. They are owned by the `enroll` subcommand and ephemeral-mode enrollment via `LINUXGUARD_ENROLL_TOKEN`; once set they remain immutable for the agent's lifetime. The `config` command rejects attempts to set them by returning `unknown config key` (they are excluded from the exposed key set). ### The `log_level` special path When the `set` subcommand receives `log_level` as the key, the agent runs a four-step flow distinct from the generic `SetField` path: 1. **Validate** the value via `lglog.ParseLevel` against the strict lowercase wire format. Invalid values (uppercase, integer, empty) return an error and the persist step is skipped. 2. **Persist** both `LogLevel` and `LogLevelLocalPinned = true` to the local config database. The sentinel pair signals "operator pinned this level explicitly" so backend acks do not overwrite it. 3. **SIGHUP** the running agent. The signal triggers the agent's log-level reload handler which re-reads the persisted config and applies the new level via `lglog.SetLevel`. 4. **Report** the result. The command prints `>> log_level = (persisted, SIGHUP delivered)` on success, or `>> log_level = (persisted; agent not running — applies on next start)` if no agent process is found at the PID-file path. The `unset log_level` flow mirrors this in reverse: it clears both `LogLevel` and `LogLevelLocalPinned`, persists, and SIGHUPs. After `unset`, the agent's precedence chain resolves to: cached ack-delivered value > tenant default > built-in `info`. ## Flags The top-level `config` command has no flags of its own. Subcommands take positional arguments (`` and optionally ``) as documented in the Subcommands table above. ## Environment `config` reads no environment variables beyond what `config.Setup` reads for the agent process at start time (notably the local-config-environment selection that resolves to `dev` or `prod` configuration paths). The `LINUXGUARD_*` env vars documented for [`start`](/reference/reference/cli/start) do not affect `config` invocations. ## Signals `config` is a one-shot CLI invocation — it does not install signal handlers via `signal.Notify`. The agent's process model for `config` is: run the subcommand, persist if applicable, optionally deliver a single SIGHUP via `syscall.Kill` to the running `start` process (the `log_level` special path), and exit. The SIGHUP delivery is the agent's only signal interaction during a `config` invocation. It targets the PID discovered via `pidfile.Discover(cfg.PidFilePath)`; `ESRCH` (process exited between discovery and kill) is treated as "agent not running" and not an error. ## Exit codes | Code | Meaning | | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Successful operation. The key was read or set; the SIGHUP was delivered (or `ESRCH`-tolerated). | | `1` | General error. Surfaced via `log.Fatal` after the agent run returns a non-nil error. Includes: unknown config key, invalid value (e.g., non-bool for a bool field, out-of-range integer for a `logging.*` key, invalid log level), wrong argument count, config-service init failure, persist failure, SIGHUP delivery failure for reasons other than `ESRCH`. | ## Examples ### Pin the log level to debug at runtime ```bash sudo linuxguard-agent config set log_level debug ``` Expected stdout: ``` >> log_level = debug (persisted, SIGHUP delivered) ``` If the agent is not running: ``` >> log_level = debug (persisted; agent not running — applies on next start) ``` ### Clear the local log-level pin ```bash sudo linuxguard-agent config unset log_level ``` Expected stdout: ``` >> log_level cleared (persisted, SIGHUP delivered) ``` After `unset`, the precedence chain resolves to the cached ack value (if the backend has delivered one), the tenant default (if configured), or the built-in `info`. ### Inspect a single key ```bash linuxguard-agent config get logging.max_size_mb ``` Expected stdout (default): ``` 50 ``` ### List all toggleable keys with current values ```bash linuxguard-agent config list-keys ``` Sample stdout (truncated; exact key set depends on the binary's `Config` struct): ``` log_level debug logging.max_size_mb 50 logging.max_age_days 14 logging.max_backups 5 logging.compress true tags web-server,us-east ... ``` ### Increase log retention without restart ```bash sudo linuxguard-agent config set logging.max_age_days 30 sudo linuxguard-agent config set logging.max_backups 10 ``` The new values are applied at the next rotation point; the active log file is not rotated immediately. To force an immediate close-and-reopen for an external `logrotate` step, send SIGHUP to the running agent. ### Reject an invalid log level ```bash sudo linuxguard-agent config set log_level INFO ``` Expected exit code: `1`. Expected stderr (paraphrased): ``` unknown log level "INFO" (must be one of: trace, debug, info, warn, error) ``` The strict lowercase wire format prevents subtle drift between the agent CLI, the config file, the ack envelope, and the audit log row. *** **Related**: [start](/reference/reference/cli/start) | [probe](/reference/reference/cli/probe) | [CLI Reference](/reference/reference/cli) | [Reference](/reference/reference) # probe Reference for linuxguard-agent probe — host capability check covering kernel, BPF, fanotify, netlink, audit, and Linux capabilities. ## Synopsis Check whether the host kernel and runtime environment support the building blocks the LinuxGuard agent depends on: kernel version, BTF availability, BPF ringbuf support, bpffs writability, fanotify, netlink sock\_diag, auditd reachability, and the Linux capabilities the agent needs to operate (see [Capabilities](#capabilities) below for the full list). Designed for pre-flight checks before enrolling an agent and for CI-host validation in container images. The probe is bounded by a 3-second outer context timeout and a per-check 200ms budget. Per-check failures are recorded as `false` on the result and logged via `slog.Warn`. ```bash linuxguard-agent probe [flags] ``` > **Important**: `probe` always exits 0 — including when capability checks fail. The command is non-fatal by design: the exit code reports CLI success, not host suitability. Always inspect the JSON output to determine the actual outcome. CI and Ansible callers should parse the JSON and fail their own pipeline based on the boolean fields, not on the agent's exit code. ## Flags | Flag | Type | Default | Description | | ---------- | ---- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | | `--json` | bool | `true` | Emit machine-readable JSON to stdout. Accepted for forward compatibility — JSON is the only supported output format today. | | `--pretty` | bool | `false` | Indent the JSON output for human reading. When `true`, output is produced via `json.MarshalIndent` with two-space indentation. | ## Environment `probe` reads no environment variables. It does not respect any of the `LINUXGUARD_*` variables that influence the [`start`](/reference/reference/cli/start) command. The probe is intentionally self-contained so it can run inside a freshly-pulled image with no prior configuration. ## Signals `probe` is a one-shot CLI invocation — it does not install signal handlers via `signal.Notify`. The 3-second outer context timeout is the only interrupt path. `Ctrl-C` aborts the process via Go's default `SIGINT` handler (no graceful unwind, no JSON output). ## Exit codes | Code | Meaning | | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Always. `probe` is non-fatal by design. The exit code does NOT reflect probe outcome — inspect the JSON output's boolean fields to determine actual capability availability. | The non-fatal behavior is intentional — even when `json.Marshal` fails (which should not happen for a struct of basic types), the agent logs the error via `slog.Warn`, emits `{}` to stdout, and returns `nil`. This guarantees that callers parsing the output do not block on a missing newline or a non-zero status. ## Output schema `probe` emits a single JSON object matching the `capability.Capabilities` struct: | Field | Type | Meaning | | -------------------- | --------- | ------------------------------------------------------------------------ | | `kernel_version` | string | Full uname-style kernel version (e.g. `5.15.0-amd64`). | | `kernel_major` | int | Parsed major component of the kernel version. | | `kernel_minor` | int | Parsed minor component of the kernel version. | | `architecture` | string | `runtime.GOARCH` value: `amd64`, `arm64`, `arm` (armv7), `riscv64`, etc. | | `btf_available` | bool | Whether the kernel's BTF type information is available for CO-RE. | | `ringbuf_supported` | bool | Whether the BPF ringbuf map type is supported by the kernel. | | `bpffs_writable` | bool | Whether the bpf filesystem can be written by the agent. | | `fanotify_available` | bool | Whether `fanotify_init` returns a usable fd. | | `netlink_sock_diag` | bool | Whether the agent can open a `NETLINK_SOCK_DIAG` socket. | | `auditd_reachable` | bool | Whether the audit netlink socket is reachable. | | `caps` | object | Effective Linux capabilities — see [Capabilities](#capabilities) below. | | `probed_at` | timestamp | RFC3339 timestamp when the probe ran. | | `probe_duration_ms` | int | Total wall-clock duration of the probe in milliseconds. | All boolean fields default to `false` on per-check failure (the probe never returns an error; failures are recorded as flags on the result, per `capability` package documentation). ### Capabilities Each field under `caps` reports whether a specific Linux capability is effective for the agent process: * `caps.bpf` — `CAP_BPF` (kernel 5.8+). * `caps.dac_read_search` — `CAP_DAC_READ_SEARCH`. * `caps.sys_admin` — `CAP_SYS_ADMIN`. * `caps.sys_ptrace` — `CAP_SYS_PTRACE`. * `caps.net_admin` — `CAP_NET_ADMIN`. * `caps.perfmon` — `CAP_PERFMON` (kernel 5.8+). ## Examples ### Pretty-print a probe to stdout ```bash linuxguard-agent probe --pretty ``` Sample stdout on a typical Ubuntu 22.04 host with sufficient privileges: ```json { "kernel_version": "5.15.0-78-generic", "kernel_major": 5, "kernel_minor": 15, "architecture": "amd64", "btf_available": true, "ringbuf_supported": true, "bpffs_writable": true, "fanotify_available": true, "netlink_sock_diag": true, "auditd_reachable": true, "caps": { "bpf": true, "perfmon": true, "dac_read_search": true, "sys_admin": true, "sys_ptrace": true, "net_admin": true }, "probed_at": "2026-05-31T12:00:00Z", "probe_duration_ms": 142 } ``` ### JSON probe for CI parsing ```bash linuxguard-agent probe | jq '.btf_available, .caps.bpf, .caps.perfmon' ``` ### Fail a CI step when any required capability is missing `probe` always exits 0, so the CI step must parse the JSON and decide: ```bash output=$(linuxguard-agent probe) required_keys='.btf_available, .ringbuf_supported, .bpffs_writable, .fanotify_available, .caps.bpf, .caps.perfmon' missing=$(echo "$output" | jq -r "[$required_keys] | map(select(. == false)) | length") if [ "$missing" != "0" ]; then echo "Pre-flight FAILED: $missing required capability check(s) returned false." echo "$output" | jq . exit 1 fi echo "Pre-flight OK." ``` ### Probe inside a container image ```bash docker run --rm \ --cap-add=SYS_ADMIN --cap-add=BPF --cap-add=PERFMON \ ghcr.io/linuxguardx/linuxguard-agent:vX.Y.Z \ linuxguard-agent probe --pretty ``` A reduced-capability container will show `caps.sys_admin = false` etc. while the kernel-level booleans remain accurate. ### Probe via Ansible pre-flight ```yaml - name: LinuxGuard host capability check ansible.builtin.command: linuxguard-agent probe register: linuxguard_probe changed_when: false - name: Parse probe result ansible.builtin.set_fact: probe_data: "{{ linuxguard_probe.stdout | from_json }}" - name: Fail when BTF is unavailable ansible.builtin.fail: msg: | Host {{ inventory_hostname }} reports btf_available=false. eBPF probes will not load. Install a kernel with BTF or switch to the agent's degraded mode. when: not probe_data.btf_available ``` The `changed_when: false` is important because `probe` is read-only — Ansible should not record a change. *** **Related**: [start](/reference/reference/cli/start) | [config](/reference/reference/cli/config) | [CLI Reference](/reference/reference/cli) | [Reference](/reference/reference) # support-bundle Reference for linuxguard-agent support-bundle — collect a redacted diagnostic archive locally or upload an existing bundle via a presigned S3 URL. ## Synopsis Collect a redacted diagnostic bundle from the host and (optionally) upload it to LinuxGuard for analysis by support staff. The command has two subcommands: `collect` (assemble a `tar+zstd` archive locally) and `upload` (send a previously-collected archive via a presigned S3 URL). Bundles include the current `agent.log`, rotated log segments, a system metadata file, a redacted copy of the agent config, and a `BUNDLE-MANIFEST.json` describing the archive. ```bash linuxguard-agent support-bundle [args] ``` > **Important**: `agent.log` is shipped in the bundle with **attribute-key regex redaction only** — values associated with attribute keys matching `^(api_key|enroll_token|.*_token|.*_secret)$` are masked, but other sensitive content (hostnames, IPs, usernames, file paths, command arguments) is not. Review bundles before sharing with parties outside your organisation. ## Subcommands | Subcommand | Synopsis | Purpose | | ---------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `collect` | `linuxguard-agent support-bundle collect [--out ]` | Assemble a `.tar.zst` bundle on the local filesystem. Prints the bundle path to stdout; emits `sha256=...` and `size=...` lines to stderr. | | `upload` | `linuxguard-agent support-bundle upload ` | Upload an existing bundle to LinuxGuard via a three-step presigned-URL flow. Requires an enrolled agent (the API key carries the tenant scope). | ## Flags `collect` is the only subcommand with a flag; `upload` takes a single positional argument (``). ### `collect` flags | Flag | Type | Default | Description | | -------------- | ------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--out ` | string | `/var/lib/linuxguard/support/.tar.zst` | Override the output path. The parent directory is created with mode `0750` if absent. The output file is opened with `O_EXCL` — a pre-existing file at the path causes the command to fail (symlink-attack mitigation). | ### `upload` arguments | Argument | Required | Description | | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | yes | Path to a `.tar.zst` bundle produced by `collect`. The file's SHA-256 is computed on disk and included in the register call; the size is compared against the manifest. | ## Environment `support-bundle` reads no `LINUXGUARD_*` environment variables. `collect` consults only the agent's persisted local config (for the log path and tenant identity); `upload` uses the API client built from the persisted enrolment (`base_url`, `api_key`) so the agent must already be enrolled. `upload` performs three network calls: `POST /v1/support/bundle/upload-url` (returns a presigned S3 URL + object key + expiry), `PUT ` (uploads the bundle bytes without an `Authorization` header — required for AWS Signature V4 verification), and `POST /v1/support/bundle/register` (records the upload metadata server-side). The presigned URL has a 15-minute server-enforced TTL. ## Signals `support-bundle` is a one-shot CLI invocation — neither subcommand installs signal handlers via `signal.Notify`. `Ctrl-C` aborts via Go's default `SIGINT` handler; in-progress archive writes use `O_EXCL` so a partially-written bundle does not linger as a stable file at the target path. `upload` is interruptible at the network layer via the standard library's HTTP client cancellation; partial uploads are discarded server-side when the presigned URL expires. ## Exit codes | Code | Meaning | | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Successful operation. `collect` printed the bundle path; `upload` printed `bundle_id`, `object_key`, and `uploaded_at`. | | `1` | General error — surfaced via `log.Fatal` after `app.Run` returns a non-nil error. Includes: pre-existing file at the `--out` path (`O_EXCL` rejection), output directory creation failure, missing or unreadable bundle file, SHA-256 / size mismatch between the file and the manifest, presign request failure, presigned PUT failure, register-call failure, or unrecoverable redaction error. | | `143` | SIGTERM during a long-running upload — orchestrator-driven shutdown. Re-raised from `main` per the convention documented for [`start`](/reference/reference/cli/start). | | `130` | SIGINT (Ctrl-C) during a long-running upload. Re-raised from `main`. | ## Examples ### Collect a bundle at the default path ```bash sudo linuxguard-agent support-bundle collect ``` Stdout: ``` /var/lib/linuxguard/support/1716998400.tar.zst ``` Stderr: ``` sha256=2b3f...c1 size=42137088 ``` The stdout path is the only token consumed by shell pipelines (`bundle=$(sudo linuxguard-agent support-bundle collect)`); diagnostic output is on stderr so it does not pollute the pipeline. ### Collect to a specific path ```bash sudo linuxguard-agent support-bundle collect --out /tmp/incident-2026-05-31.tar.zst ``` Use a non-default path when collecting during incident response so the bundle does not collide with timestamped bundles in `/var/lib/linuxguard/support/`. The output directory is created if it does not exist. ### Inspect the bundle contents before sharing ```bash zstd -d < /var/lib/linuxguard/support/1716998400.tar.zst | tar -tvf - ``` The bundle is a standard `tar+zstd` archive. Contents: | File | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent.log` | The current agent log file. **Attribute-key regex redaction only — review before sharing externally.** | | `..gz` | Rotated log segments included newest-first within the 180 MB pre-compress cap. Segments that exceed the cap are listed in `BUNDLE-MANIFEST.json` under `trimmed_segments` and not included. | | `system.json` | Kernel version, distro identity, eBPF probe status, recent error count, and agent version. | | `config.redacted.json` | The agent's runtime config with identity + credential fields removed. | | `BUNDLE-MANIFEST.json` | Bundle version, agent version, generation timestamp, trigger (`cli` / `console_push`), contents list, trimmed-segment list, and redaction summary. | ### Pre-compress size cap The bundle assembles rotated log segments newest-first, accumulating against a **180 MB pre-compression cap** (`MaxPreCompressBytes: 180 * 1024 * 1024` in the agent runtime). The current `agent.log` size counts toward the cap. Segments that would push the total above 180 MB are listed in `BUNDLE-MANIFEST.json` under `trimmed_segments` and NOT included in the archive. The cap is hard-coded — operators who need a larger bundle should collect logs out-of-band (e.g., `journalctl`). ### Upload a previously-collected bundle ```bash sudo linuxguard-agent support-bundle upload /var/lib/linuxguard/support/1716998400.tar.zst ``` Expected stdout: ``` uploaded bundle_id=b-2024-05-31-abc1234 object_key=tenants/T-1/bundles/1716998400.tar.zst uploaded_at=2026-05-31T12:34:56Z ``` The local file is NEVER deleted by `upload`. After a successful upload, decide whether to retain or remove the bundle per your retention policy. ### Collect-and-upload in one shell pipeline ```bash bundle=$(sudo linuxguard-agent support-bundle collect) sudo linuxguard-agent support-bundle upload "$bundle" rm -f -- "$bundle" # optional — bundle persists otherwise ``` `collect` prints the bundle path on stdout (one line); `upload` reads the path as a positional argument. The trailing `rm` is operator discretion — `upload` does not auto-delete. ### Failure mode: pre-existing file at `--out` path ```bash sudo linuxguard-agent support-bundle collect --out /tmp/incident.tar.zst # (first invocation succeeds) sudo linuxguard-agent support-bundle collect --out /tmp/incident.tar.zst # Error: support-bundle collect: bundle: open output "/tmp/incident.tar.zst": file exists # Exit code: 1 ``` The `O_EXCL` open semantics prevent overwriting a previous bundle (and reject symlink swaps at the target path). Move or remove the prior bundle before re-running `collect` to the same path. *** **Related**: [start](/reference/reference/cli/start) | [config](/reference/reference/cli/config) | [signals](/reference/reference/cli/signals) | [CLI Reference](/reference/reference/cli) # enroll Reference for linuxguard-agent enroll — bind a host to a tenant using a long-lived API key, with environment / tag assignment and mTLS certificate provisioning. ## Synopsis Bind a host to a LinuxGuard tenant using a long-lived API key. `enroll` writes the tenant identity to the local config database, requests an mTLS client certificate from the backend (when the tenant has a CA provisioned), and sends an initial snapshot so the host appears in the console without waiting for the first scheduled heartbeat. Once enrolled, [`start`](/reference/reference/cli/start) reuses the persisted credentials and the host operates in typical service mode. The alternative enrollment path — short-lived TOTP tokens for ephemeral / containerised deployments — does NOT use this command. See [`start` § Enrollment flags](/reference/reference/cli/start#enrollment-flags) for the TOTP path, which fires the enrol POST from inside `start` rather than from a separate subcommand. ```bash linuxguard-agent enroll --api-key --tenant-id [flags] ``` ## Flags | Flag | Type | Required | Default | Description | | ---------------------- | ------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--api-key ` | string | yes | — | Long-lived API key issued from the LinuxGuard console (Settings → API Keys). Authenticates the enrol POST and is persisted as `cfg.ApiKey` for subsequent heartbeats. | | `--tenant-id ` | string | yes | — | Tenant UUID the host enrols into. Persisted as `cfg.TenantID`. Must match the API key's owning tenant — mismatch produces a backend rejection. | | `--environment ` | string | no | — | Logical environment name (e.g., `production`, `staging`, `development`). Persisted as `cfg.Environment` and surfaced in console filters. Has one backward-compatible alias: `--group` (v3.0 vocabulary). | | `--tag ` | string slice | no | — | Tag name applied to the host's identity. Repeat the flag to assign multiple tags (`--tag web --tag us-east`). Persisted as `cfg.Tags`. | If the host is already enrolled (`cfg.ServerID != ""`), `enroll` is a no-op: it prints the existing server ID and the `RegisteredAt` timestamp and exits `0` without contacting the backend. ## Environment `enroll` reads no `LINUXGUARD_*` environment variables of its own. Channel-baked defaults govern the enrollment URL: `stable` builds POST to `https://api.linuxguard.io/v1/agent/enroll`, every other channel POSTs to `https://dev-api.linuxguard.io/v1/agent/enroll`. Override the URL out-of-band by rebuilding the agent against a different channel — there is no user-facing override flag. The persisted enrollment is stored in the agent's local config database under `/var/lib/linuxguard/` on Linux hosts. `start` reads the same database to recover the tenant identity, API key, base URL, and server ID at boot. ## Signals `enroll` is a one-shot CLI invocation — it does not install signal handlers via `signal.Notify`. `Ctrl-C` aborts the enrol POST or the initial-snapshot POST via Go's default `SIGINT` handler; an aborted enrol mid-flight does NOT roll back partial config writes (the cfg.ApiKey / cfg.TenantID / cfg.BaseURL fields are persisted BEFORE the API client is reconfigured). ## Exit codes | Code | Meaning | | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Enrolment succeeded (mTLS certificate stored if the tenant has a CA; initial snapshot sent or warned non-fatally). Or: the host was already enrolled and the no-op path printed the existing identity. | | `1` | General error — surfaced via `log.Fatal` after the agent run returns a non-nil error. Includes: config-service init failure, persist failure for the pre-enrol config write, network failure for the enrol POST, backend rejection (HTTP 4xx/5xx — including "tenantId required" or "API key invalid"), nil enrollment response, or post-enrol config-save verification mismatch. | | `2` | Argument parsing error — missing one of the required flags `--api-key` or `--tenant-id`, or unknown flag passed on the command line. | ## Examples ### Enrol a host into production ```bash sudo linuxguard-agent enroll \ --api-key 4f8c1e9d-...-7a2b \ --tenant-id 11111111-2222-3333-4444-555555555555 \ --environment production \ --tag web-server --tag us-east-1 ``` Expected stdout (truncated): ``` >> mTLS client certificate stored successfully >> Sending initial snapshot... >> Initial snapshot sent successfully >> Successfully enrolled to LinuxGuard Endpoint: https://api.linuxguard.io/v1/ ``` After the command returns, start the agent service: ```bash sudo systemctl enable --now linuxguard-agent ``` ### Re-running enrol on an already-enrolled host ```bash sudo linuxguard-agent enroll --api-key X --tenant-id Y ``` Stdout: ``` This server has been enrolled since Mon, 31 May 2026 12:34:56 UTC ``` Exit code: `0`. The flags are accepted but ignored — `cfg.ServerID` is non-empty so the enrol POST is short-circuited. To re-enrol the host into a different tenant, run `linuxguard-agent unenroll` first. ### Enrol via the backward-compatible `--group` alias ```bash sudo linuxguard-agent enroll \ --api-key X --tenant-id Y \ --group staging ``` Equivalent to `--environment staging`. Preserved for v3.0 deployment scripts; new automation should use `--environment` directly. Both forms persist to the same `cfg.Environment` field. ### Handling the initial-snapshot warning If the enrol POST succeeds but the initial-snapshot POST fails (e.g., the host took longer than the snapshot collector's timeout), stdout shows: ``` >> Warning: Initial snapshot failed (...), will retry on agent start >> Successfully enrolled to LinuxGuard Endpoint: ... ``` Exit code: `0`. The enrolment is complete; the snapshot will be retried at the next `linuxguard-agent start`. No operator action is required. *** **Related**: [start](/reference/reference/cli/start) | [unenroll](/reference/reference/cli/unenroll) | [show-config](/reference/reference/cli/show-config) | [CLI Reference](/reference/reference/cli) # unenroll Reference for linuxguard-agent unenroll — remove the host from its tenant binding so the agent can be enrolled into a different tenant. ## Synopsis Remove the host's binding to its current tenant. The command's primary use case is preparing a host for re-enrolment into a different tenant — typical service-mode hosts are normally retired by stopping the agent and uninstalling the package rather than by un-enrolling. ```bash linuxguard-agent unenroll ``` > **Important**: In the current release, `unenroll` is a placeholder that prints `>> Unenrolling server...` and exits successfully without modifying the persisted enrollment. Operators who need to fully detach a host should stop the agent service, remove `/var/lib/linuxguard/` (which contains the persisted tenant identity, API key, and mTLS material), and re-enrol from scratch. Console-side tenant detach is independent of the agent invocation and is performed via the LinuxGuard console (Settings → Servers → remove). ## Flags `unenroll` takes no flags. ## Environment `unenroll` reads no environment variables. The command does not contact the backend in its current implementation. ## Signals `unenroll` is a one-shot CLI invocation — it does not install signal handlers via `signal.Notify`. The command returns immediately after printing the status line. ## Exit codes | Code | Meaning | | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | The command completed (placeholder implementation always returns nil; future versions that perform an actual un-enrolment will continue to return `0` on success). | | `1` | General error — reserved for future implementations that perform a backend detach or local-state removal and encounter persist / network failures. The current placeholder cannot return `1`. | ## Examples ### Run the placeholder ```bash sudo linuxguard-agent unenroll ``` Stdout: ``` >> Unenrolling server... ``` Exit code: `0`. No state has changed; the host is still bound to its previous tenant. ### Operator workflow: re-enrol into a different tenant The current effective workflow for moving a host between tenants (until `unenroll` performs a real detach): ```bash sudo systemctl stop linuxguard-agent sudo rm -rf /var/lib/linuxguard/ sudo linuxguard-agent enroll \ --api-key NEW-KEY \ --tenant-id NEW-TENANT-UUID \ --environment production sudo systemctl start linuxguard-agent ``` After step 4, the host appears in the new tenant's console as a new server (a fresh `ServerID` is issued by the backend during the enrol POST). Detach the stale server in the old tenant's console under Settings → Servers. ### Operator workflow: retire a host For a host that is being decommissioned (not re-enrolled), prefer package removal over `unenroll`: ```bash sudo systemctl stop linuxguard-agent sudo apt-get purge linuxguard-agent # or dnf remove / zypper remove / apk del sudo rm -rf /var/lib/linuxguard/ /var/log/linuxguard/ ``` Then detach the host from the tenant via the console (Settings → Servers → remove). The agent's local state is gone, the package is uninstalled, and the console no longer counts the host against the tenant's seat allocation. *** **Related**: [enroll](/reference/reference/cli/enroll) | [start](/reference/reference/cli/start) | [show-config](/reference/reference/cli/show-config) | [CLI Reference](/reference/reference/cli) # show-config Reference for linuxguard-agent show-config — print the entire current configuration as indented JSON for inspection or debugging. ## Synopsis Print the full agent configuration as indented JSON to stdout. Useful for verifying enrolment state, inspecting `logging.*` settings, or capturing the live config for a support ticket. The output is NOT redacted — fields like `api_key`, `tenant_id`, and `base_url` appear verbatim. For a redacted form suitable for sharing externally, use [`support-bundle collect`](/reference/reference/cli/support-bundle), which produces a `config.redacted.json` file inside the archive. ```bash linuxguard-agent show-config ``` ## Comparison with `config list-keys` `show-config` and `config list-keys` overlap but serve different purposes: | Command | Output | Scope | Format | | ----------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------- | | `show-config` | Entire `config.Config` struct | All fields, including identity (`server_id`, `tenant_id`, `api_key`, `base_url`) and operational state | Indented JSON, full structure | | [`config list-keys`](/reference/reference/cli/config) | Only **toggleable** keys (those mutable via `config set`) | Excludes identity fields by design | Flat ` ` per line | Use `show-config` for full inspection (incident triage, support ticket attachment). Use `config list-keys` when you specifically need to know what `config set` accepts. ## Flags `show-config` takes no flags. ## Environment `show-config` reads no `LINUXGUARD_*` environment variables of its own. The command operates entirely on the already-loaded config object held by the agent context (which is populated by `config.Setup` at the binary's `Before` hook). ## Signals `show-config` is a one-shot CLI invocation — it does not install signal handlers via `signal.Notify`. `Ctrl-C` aborts the command via Go's default `SIGINT` handler. ## Exit codes | Code | Meaning | | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | The configuration was marshalled to JSON and printed. Followed by `>> Configuration displayed above` on stdout. | | `1` | General error — `json.MarshalIndent` failed (should not happen for a struct of supported types) or the config context was not initialised. Surfaced via `log.Fatal`. | ## Examples ### Inspect an enrolled host ```bash sudo linuxguard-agent show-config ``` Sample stdout (truncated): ```json { "ServerID": "srv-abc1234", "TenantID": "11111111-2222-3333-4444-555555555555", "ApiKey": "4f8c1e9d-...-7a2b", "BaseURL": "https://api.linuxguard.io/v1/", "Environment": "production", "Tags": ["web-server", "us-east-1"], "Mode": "AGENT", "RegisteredAt": "2026-05-31T12:34:56Z", "LogLevel": "info", "LogLevelLocalPinned": false, "PidFilePath": "/var/run/linuxguard-agent.pid", ... } >> Configuration displayed above ``` > **Security Note**: The output includes the long-lived API key in plaintext. Do NOT paste `show-config` output into support tickets, chat threads, or screenshots. Use [`support-bundle collect`](/reference/reference/cli/support-bundle) instead — it emits the same struct with credentials redacted as `config.redacted.json`. ### Pipe to `jq` for a single field ```bash sudo linuxguard-agent show-config 2>/dev/null \ | sed '/^>>/d' \ | jq -r .ServerID ``` Stdout: ``` srv-abc1234 ``` `show-config` writes the closing status line `>> Configuration displayed above` to stdout after the JSON. The `sed '/^>>/d'` filter strips it so `jq` only sees valid JSON. ### Diff config between two hosts On two hosts in the same tenant, capture the JSON and compare: ```bash sudo linuxguard-agent show-config | sed '/^>>/d' > /tmp/host-a.json # (on host B) sudo linuxguard-agent show-config | sed '/^>>/d' > /tmp/host-b.json diff /tmp/host-a.json /tmp/host-b.json ``` Per-host differences in `ServerID`, `RegisteredAt`, `Tags`, and PID-file paths are expected; differences in `LogLevel`, `LogLevelLocalPinned`, or `logging.*` flag the config-drift to investigate. *** **Related**: [config](/reference/reference/cli/config) | [enroll](/reference/reference/cli/enroll) | [support-bundle](/reference/reference/cli/support-bundle) | [CLI Reference](/reference/reference/cli) # status Reference for linuxguard-agent status — check whether the agent process is running, by inspecting the PID file and verifying the process is alive. ## Synopsis Report whether the `linuxguard-agent start` process is running on the local host. The check is informational: the answer is conveyed by the stdout text, NOT by the exit code (the command always exits `0`). For programmatic health checks in shell scripts, parse the stdout or use `pgrep linuxguard-agent` / `systemctl is-active linuxguard-agent` instead. ```bash linuxguard-agent status ``` ## How the check works `status` reads the PID file at `cfg.PidFilePath` (default `/var/run/linuxguard-agent.pid`), parses the integer, and calls `syscall.Kill(pid, 0)` to verify the process exists. Sending signal `0` is a standard POSIX existence probe — it returns no signal to the target process; it returns success when the process exists or `ESRCH` when it does not. A successful "is running" verdict therefore requires both: 1. The PID file at `cfg.PidFilePath` exists and contains a parseable integer. 2. The process with that PID is alive AND the caller has permission to signal it (root or the same UID). The check is local-only — `status` does NOT contact the backend or verify that the running agent is heartbeating to LinuxGuard. A `running` verdict means "a process exists at the PID file's PID"; it does not mean "the agent is healthy and reporting". > **Note**: Ephemeral and PID-1 deployments (containerised) skip PID-file machinery entirely. Running `linuxguard-agent status` inside a container reports `not running` even when the agent IS running, because the PID file was never written. For container health checks, use the orchestrator's native process supervision (Kubernetes liveness probe, Docker `HEALTHCHECK`) instead. ## Flags `status` takes no flags. ## Environment `status` reads no `LINUXGUARD_*` environment variables. The PID-file path comes from the agent context's resolved config (`cfg.PidFilePath`), populated by `config.Setup` at the binary's `Before` hook. ## Signals `status` is a one-shot CLI invocation — it does not install signal handlers via `signal.Notify`. The signal-0 probe is sent to the agent's PID for the existence check; the agent's `start` process receives nothing observable (signal 0 is a no-op probe by POSIX definition). ## Exit codes | Code | Meaning | | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `0` | Always. The "running" / "not running" answer is on stdout. `status` does not return a non-zero exit when the agent is stopped, missing, or unreadable. | ## Examples ### Check a running agent ```bash sudo linuxguard-agent status ``` Stdout: ``` linuxguard-agent is running with PID: 4217 ``` ### Check a stopped agent ```bash sudo linuxguard-agent status ``` Stdout: ``` linuxguard-agent is not running ``` The same output is produced when the PID file is missing (clean stop or fresh install), corrupt, or when the PID points to a process that has exited. ### Use `status` in a shell script Because the exit code is always `0`, the answer must come from stdout. Capture and grep: ```bash state=$(sudo linuxguard-agent status) case "$state" in *"is running"*) echo "OK" ;; *) echo "DOWN" >&2; exit 1 ;; esac ``` Or use the systemd integration on packaged installs (no agent invocation needed): ```bash if systemctl is-active --quiet linuxguard-agent; then echo "OK" else echo "DOWN" >&2 exit 1 fi ``` `systemctl is-active` returns exit code `0` for `active` (running) and non-zero for any other state — easier than parsing stdout. ### Combine with `show-config` for triage ```bash if sudo linuxguard-agent status | grep -q "is running"; then echo "Agent process: UP" sudo linuxguard-agent show-config | sed '/^>>/d' | jq -r .ServerID else echo "Agent process: DOWN — checking enrolment state" sudo linuxguard-agent show-config | sed '/^>>/d' | jq -r 'select(.ServerID != "")' fi ``` The combination distinguishes "agent not running and never enrolled" (fresh install) from "agent not running but enrolled" (crashed or stopped service that needs investigation). *** **Related**: [start](/reference/reference/cli/start) | [show-config](/reference/reference/cli/show-config) | [signals](/reference/reference/cli/signals) | [CLI Reference](/reference/reference/cli) # version Reference for linuxguard-agent --version and the build-time metadata (version string, git commit, build timestamp) the agent reports. ## Synopsis Print the agent's build-time version string, git commit hash, and build timestamp, then exit. Used for support-ticket attachments, CI artefact identification, and runtime drift detection ("is the binary on disk the version I expect?"). The version surface is implemented by urfave/cli/v2's built-in `--version` and `-v` flags — there is no `linuxguard-agent version` subcommand; the version is a top-level flag on the binary. ```bash linuxguard-agent --version ``` > **Note**: `support-bundle collect` embeds the same version string in `BUNDLE-MANIFEST.json` and `system.json` (via `supportbundle.SetAgentVersion(version)` called from `main`). When triaging a bundle, prefer the manifest's `agent_version` over running `--version` on a current binary — the binary may have been upgraded between the bundle collection time and the triage time. ## How the version string is composed The string printed by `--version` is composed from three `ldflags`-injected build-time variables: ``` (commit: , built: ) ``` | Component | Source | Set by | | -------------- | --------------------------------------------------------------- | ------------------------------------------------ | | `` | semantic version tag (e.g., `v3.0.0`) or `dev` for local builds | `-ldflags="-X main.version=..."` at build time | | `` | short or full git commit SHA the build was produced from | `-ldflags="-X main.gitCommit=..."` at build time | | `` | UTC RFC3339 timestamp of the build | `-ldflags="-X main.buildTime=..."` at build time | The string is assembled at startup via `fmt.Sprintf("%s (commit: %s, built: %s)", version, gitCommit, buildTime)`. Local `go build` invocations that omit the ldflags produce `dev (commit: , built: )` — useful for distinguishing a developer build from a packaged release on disk. ## Flags `--version` (and its short form `-v`) is the only flag in scope. urfave/cli/v2 provides both forms by default: | Flag | Description | | -------------- | ----------------------------------------------------------------- | | `--version` | Print the version string and exit `0`. | | `-v` | Short alias for `--version`. | | `--help`, `-h` | Print the top-level help including the agent's command catalogue. | ## Environment `--version` reads no environment variables. The version string is fully baked into the binary at build time. ## Signals `--version` is a one-shot CLI invocation — it does not install signal handlers via `signal.Notify`. The command returns immediately after printing the string. ## Exit codes | Code | Meaning | | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Always. The version string was printed to stdout. urfave/cli/v2's built-in `--version` cannot fail at runtime — the string is a compile-time constant assembled in `main`. | ## Examples ### Inspect a packaged release ```bash linuxguard-agent --version ``` Stdout: ``` LinuxGuard Agent version v3.0.0 (commit: 7a8b9c1, built: 2026-05-15T08:23:11Z) ``` The leading `LinuxGuard Agent version` is urfave/cli/v2's default prefix; the rest is the agent-supplied string. Stable channel packages include a non-empty git commit and build timestamp. ### Inspect a developer build ```bash go build -o /tmp/linuxguard-agent . /tmp/linuxguard-agent --version ``` Stdout: ``` LinuxGuard Agent version dev (commit: , built: ) ``` The empty `commit` and `built` fields identify the binary as a local build that did not pass through the release ldflags. Treat such binaries as test artefacts; do NOT deploy them to production hosts. ### Capture the version for a support ticket ```bash linuxguard-agent --version > /tmp/lg-version.txt sudo linuxguard-agent support-bundle collect --out /tmp/lg-bundle.tar.zst ``` Attach both files to the support ticket. The bundle's `BUNDLE-MANIFEST.json` and `system.json` already embed the version, but the standalone `--version` output captures the exact build of the binary running at ticket-open time (the bundle may be older). ### Distinguish two binaries on disk ```bash /usr/bin/linuxguard-agent --version /opt/linuxguard/bin/linuxguard-agent --version ``` Useful when an unpackaged build was dropped alongside the system-managed package — the version string identifies which binary is which without inspecting file timestamps. *** **Related**: [start](/reference/reference/cli/start) | [show-config](/reference/reference/cli/show-config) | [support-bundle](/reference/reference/cli/support-bundle) | [CLI Reference](/reference/reference/cli) # signals Signal-handling reference for the linuxguard-agent start process — SIGHUP (log-level reload + log rotation), SIGTERM (143), SIGINT (130), and the re-raise convention. This page documents which POSIX signals the `linuxguard-agent` process handles, what each handler does, and which exit code results when the agent terminates because of a signal. Only the [`start`](/reference/reference/cli/start) command installs signal handlers — every other subcommand (`config`, `probe`, `support-bundle`, `enroll`, `unenroll`, `show-config`, `status`, `version`, `stop`) is a one-shot invocation with no `signal.Notify` calls. ## Handled signals The `start` process installs two cooperating handlers — a primary goroutine for `SIGINT` / `SIGTERM` / `SIGHUP` and a separate `SIGHUP` listener for log-level reload. Go's `signal.Notify` broadcasts a delivered `SIGHUP` to both handlers independently, so the two effects are guaranteed to fire on the same signal. | Signal | Handler location | Behavior | | --------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SIGHUP` | Primary handler + dedicated log-level reload handler | Two independent effects: (1) the active lumberjack rotator calls `Rotate()` to close and reopen the current log file descriptor; (2) `config.Setup` re-runs and the resolved log level is applied via `lglog.SetLevel`. | | `SIGTERM` | Primary handler | The signal is stored in the `caughtSignal` atomic value, the agent context is cancelled, and `main` returns. After the agent run unwinds, the agent calls `os.Exit(128 + int(syscall.SIGTERM))` = **`os.Exit(143)`**. | | `SIGINT` | Primary handler | Same path as `SIGTERM`. The agent calls `os.Exit(128 + int(syscall.SIGINT))` = **`os.Exit(130)`**. | Signals not in the table above (`SIGUSR1`, `SIGUSR2`, `SIGPIPE`, etc.) are handled by the Go runtime defaults. The agent installs `signal.Notify` for exactly the three signals above; nothing else is intercepted. ## Why send `SIGHUP`? `SIGHUP` is the agent's runtime-reload signal. Two distinct workflows depend on it. ### Coexistence with external `logrotate` The agent writes to `/var/log/linuxguard/agent.log` via a `lumberjack.Logger` rotator that handles its own size-based and age-based rotation. Operators who additionally configure system `logrotate` need the agent to release the inherited file descriptor on the rotated file so disk usage stops growing on the old inode. The recommended `/etc/logrotate.d/linuxguard` fragment is: ``` /var/log/linuxguard/agent.log { daily rotate 14 compress missingok notifempty postrotate /bin/kill -HUP $(cat /var/run/linuxguard-agent.pid 2>/dev/null) 2>/dev/null || true endscript } ``` The `postrotate` `kill -HUP` triggers the lumberjack `Rotate()` call which closes and reopens the agent's log writer. Without the postrotate hook, the rotated file remains open via the inherited fd and disk usage continues growing on the old inode. ### Log-level reload without restart `linuxguard-agent config set log_level ` persists the new level to the local config database AND sends `SIGHUP` to the running agent via `deliverSighup`. The agent's SIGHUP reload goroutine then re-reads the persisted config (via `config.Setup`) and applies the new level via `lglog.SetLevel`. The agent does not need a restart for the new level to take effect. External tooling that bypasses `config set log_level` (e.g., editing the config database directly) must `kill -HUP $(cat /var/run/linuxguard-agent.pid)` itself for the new level to apply. ## Re-raise convention When the agent catches `SIGINT` or `SIGTERM`, it does NOT re-raise via `signal.Reset` + `syscall.Kill(getpid, sig)`. Instead, `main` calls `os.Exit(128 + int(sig))` directly: | Caught signal | Resulting exit code | Shell convention | | -------------- | ------------------- | ---------------- | | `SIGINT` (2) | `130` | `128 + 2` | | `SIGTERM` (15) | `143` | `128 + 15` | The `os.Exit(128+signum)` path is intentional. An earlier `signal.Reset` + `syscall.Kill` approach routed through Go's runtime `dieFromSignal` (`runtime/signal_unix.go`). Empirically, on Go 1.25 inside a distroless containerized PID-1 deployment, the synchronous self-`raise(sig)` did NOT terminate the process before the runtime's 5 `osyield`s elapsed, so `dieFromSignal` fell through to its `exit(2)` fallback and `docker wait` reported exit code `2` for every signal-induced shutdown. The `os.Exit(128+signum)` approach matches the shell convention that `docker wait` reports, regardless of `WIFEXITED` vs `WIFSIGNALED`. Operators and orchestrators see `143` for `SIGTERM` deterministically. ## Sending signals to the agent The agent writes its PID to `/var/run/linuxguard-agent.pid` on `start` (typical service mode only — ephemeral and PID-1 modes skip the PID file). Standard tooling for signal delivery: | Goal | Command | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Reload log level + close-and-reopen log file | `sudo kill -HUP $(cat /var/run/linuxguard-agent.pid)` | | Graceful shutdown (orchestrated) | `sudo kill -TERM $(cat /var/run/linuxguard-agent.pid)` or `sudo systemctl stop linuxguard-agent` | | Interactive cancellation (foreground) | `Ctrl-C` in the terminal hosting the agent | | Force kill (LAST RESORT) | `sudo kill -KILL $(cat /var/run/linuxguard-agent.pid)` — bypasses the signal handler; the agent does not unwind cleanly and the next start performs a stale-pidfile check. | The systemd unit (`/lib/systemd/system/linuxguard-agent.service` in packaged installs) uses `KillSignal=SIGTERM` so `systemctl stop` produces the expected `143` exit. The systemd-journal log shows `Stopped LinuxGuard Agent` and `Main process exited, code=exited, status=143/n/a` on a graceful stop. ## Signals NOT handled by other commands `config`, `probe`, `support-bundle`, `enroll`, `unenroll`, `show-config`, `status`, and `version` are one-shot invocations: they do not call `signal.Notify`. The Go runtime's default `SIGINT` / `SIGTERM` behavior applies — `Ctrl-C` during `linuxguard-agent probe` (for example) aborts the process via the runtime default with no graceful JSON output and no `128+signum` re-raise. The single exception is the SIGHUP that `config set log_level` and `config unset log_level` send via `syscall.Kill` to the running `start` process. That is a signal sent BY `config`, not handled by `config`; `config` itself does not install a handler. *** **Related**: [start](/reference/reference/cli/start) | [config](/reference/reference/cli/config) | [exit-codes](/reference/reference/cli/exit-codes) | [env-variables](/reference/reference/cli/env-variables) | [CLI Reference](/reference/reference/cli) # env-variables Environment-variable reference for linuxguard-agent — LINUXGUARD\_ENROLL\_TOKEN, LINUXGUARD\_NODE\_NAME, LINUXGUARD\_POD\_UID, and related variables used by the start command. This page enumerates every `LINUXGUARD_*` environment variable that the agent reads from `os.Environ` at startup. All variables are scoped to the [`start`](/reference/reference/cli/start) command — they do not affect `config`, `probe`, `support-bundle`, or other one-shot subcommands. Internal-only variables surfaced by the agent's PID-1 init wrapper are documented here as informational so operators reading process metadata can identify them; they are not for operators to set. ## Variables The table below is exhaustive for the user-facing environment surface. Variables not listed are either internal helpers (no documented effect) or do not exist in the agent source. | Variable | Format | Default | Used by | Description | | ---------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LINUXGUARD_ENROLL_TOKEN` | string (TOTP enrollment token, e.g. `XXXX-XXXX-XXXX`) | — | `start` (ephemeral mode) | Short-lived enrollment token. Bound to the `--enroll-token` flag via urfave/cli/v2's `EnvVars`. **The agent reads this once at startup and immediately calls `os.Unsetenv` on it before any goroutine forks** so the raw value does not remain readable via `/proc//environ`. See [Why immediately unset?](#why-immediately-unset) below. | | `LINUXGUARD_NODE_NAME` | string (Kubernetes node name, e.g. `ip-10-0-0-42`) | — | `start` (ephemeral mode) | Kubernetes node name supplied via the Downward API `fieldRef: spec.nodeName`. Bound to the `--node-id` flag via `EnvVars`. Feeds the workload-id derivation: `sha256(node_name + ":" + pod_uid)` becomes the workload identifier when `--workload-id` is not provided. | | `LINUXGUARD_POD_UID` | string (Kubernetes pod UID, RFC 4122 v4) | — | `start` (ephemeral mode) | Kubernetes pod UID supplied via the Downward API `fieldRef: metadata.uid`. **Read directly via `os.Getenv` (no flag binding)** — no `--pod-uid` flag exists. Required when `--workload-id` is absent; pairs with `LINUXGUARD_NODE_NAME` for the workload-id derivation. | | `LINUXGUARD_TENANT_ID` | string (UUID) | — | `start` (ephemeral mode) | Tenant identifier the agent enrols into. Bound to the `--tenant-id` flag via `EnvVars`. Required on the TOTP enrollment path — the backend's `/agent/enroll` handler rejects with `400 "tenantId required for TOTP enrollment"` when the request body's `TenantID` is empty AND `EnrollCode` is set. Long-lived API keys carry their own tenant scope server-side, so the variable is optional on that path. | | `LINUXGUARD_API_URL` | string (URL with trailing slash, e.g. `https://dev-api.linuxguard.io/v1/`) | channel-derived | `start` (ephemeral mode) | Override the LinuxGuard API base URL. Bound to the `--api-url` flag via `EnvVars`. Whitespace-only values are treated as empty so `export LINUXGUARD_API_URL=""` does not silently route to a no-host enrol POST. Channel default: `stable` → `https://api.linuxguard.io/v1/`; otherwise → `https://dev-api.linuxguard.io/v1/`. | | `LINUXGUARD_LOADER_EMBEDDED` | `true` / `false` (boolean) | — (auto-on with `loader_embedded` build tag under PID 1 or `--ephemeral`) | `start` | Force the in-process embedded eBPF loader. Bound to the `--loader-embedded` flag via `EnvVars`. When unset, the agent infers the loader mode from build tags + PID-1 / ephemeral detection. | | `LINUXGUARD_PID1_CHILD` | string (any non-empty value) | — | `start` (PID-1 detection only) | **Internal sentinel surfaced for transparency.** Set by the agent's PID-1 init re-exec wrapper to mark the child process so the agent code path detects "we are running under the init shim" without parsing the kernel's process tree. Operators should NOT set this manually — doing so causes the agent to skip PID-file machinery on a non-PID-1 host as if it were containerized, which produces a stale `linuxguard-agent stop` workflow. Documented here so process-introspection tooling (e.g., reading `/proc//environ` during incident triage) can identify the value as agent-internal rather than user-supplied. | ### Resolution precedence (flag-bound variables) For variables bound to a flag via urfave/cli/v2's `EnvVars`, the resolution order is: 1. **Explicit `--` value on the command line** — takes precedence over everything else. 2. **`EnvVars`-bound environment variable** — read when the flag is omitted. 3. **Built-in default** — used when neither the flag nor the env var is set. `LINUXGUARD_POD_UID` is the exception: it is NOT bound to a flag (no `--pod-uid` exists), so it is read directly via `os.Getenv` and has no command-line override. ## Why immediately unset? The `LINUXGUARD_ENROLL_TOKEN` variable receives special handling: the agent reads it once at the very top of the `start` action, captures the value, and calls `os.Unsetenv("LINUXGUARD_ENROLL_TOKEN")` BEFORE any goroutine forks. The rationale is the `/proc//environ` leak surface. On Linux, an unprivileged process running as the same UID as the agent can read `/proc//environ` for the lifetime of the agent process and observe every environment variable the agent inherited at exec time. If `LINUXGUARD_ENROLL_TOKEN` remained in the agent's environ block, a hostile co-tenant or a misconfigured monitoring agent could read the raw enrollment token and (within its TTL) self-enrol a rogue identity into the same tenant. `os.Unsetenv` does not retroactively scrub the inherited environ block from kernel memory — the data is allocated at `execve` time and persists as long as the process lives. The Go runtime's `Unsetenv` updates the process-internal `environ()` slice and rewrites the same memory the kernel exposes via `/proc//environ`, so subsequent reads of that pseudo-file return the redacted set. Empirically this means the window in which `/proc//environ` contains the token is approximately the latency between `execve` and `os.Unsetenv` — measured in milliseconds, not minutes. The token is consumed once for the enrol POST and never needed again (the agent stores the resulting mTLS cert chain in memory or in `/run/linuxguard/tls/` when `--tls-cache` is set), so the early unset does not impede operation. Operators must continue to inject the token via container runtime environment-injection (Docker `-e LINUXGUARD_ENROLL_TOKEN=...`, Kubernetes `valueFrom.secretKeyRef`) — NOT via the agent command line — so the value does not appear in: 1. The process command line visible via `/proc//cmdline` to ANY local UID. 2. Shell history (`~/.bash_history`, `~/.zsh_history`). 3. The container runtime's audit log (Docker logs the command; not the environ block). The Kubernetes `valueFrom.secretKeyRef` pattern is the recommended injection path — see [`start` § Examples](/reference/reference/cli/start#ephemeral-mode-kubernetes-daemonset-abbreviated). ## Variables NOT documented here Variables that exist in the agent source but are NOT user-facing belong to debug/internal surface deliberately omitted per the hidden-CLI policy. The public flag for selecting the tenant environment is `--environment` on `enroll`, with `--group` as the backward-compatible alias. If you encounter an undocumented `LINUXGUARD_*` variable in a process environ block, it is either an internal helper (e.g., the PID-1 init shim's coordination variables) or a test-mode override. Open a support case if you need confirmation; do not rely on undocumented variables for operational workflows — they may be renamed, removed, or made non-functional in any release. *** **Related**: [start](/reference/reference/cli/start) | [signals](/reference/reference/cli/signals) | [exit-codes](/reference/reference/cli/exit-codes) | [CLI Reference](/reference/reference/cli) # exit-codes Exit-code reference for linuxguard-agent — universal codes (0/1/2), signal-induced 128+N codes (130 SIGINT, 143 SIGTERM), and per-command divergences. This page documents the exit codes that `linuxguard-agent` returns to the calling shell, init system, or container runtime. Codes are deterministic and follow standard POSIX conventions; the only command whose exit code does NOT reflect operational outcome is [`probe`](/reference/reference/cli/probe), which is non-fatal by design. ## Universal codes These codes apply to every subcommand unless a per-command override is documented below. | Code | Source | Meaning | | ----- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Normal return | Successful operation. The command completed and produced its expected output (or `probe` ran and emitted JSON regardless of capability check outcome). | | `1` | `log.Fatal(err)` after the agent run returns non-nil | General error. Includes: invalid argument value, unknown config key, persist failure, network failure, enrollment failure, PID-file collision in typical service mode, missing required flag, and any unwrapped error returned by a subcommand's `Action`. | | `2` | `urfave/cli/v2` framework | Argument parsing error. Returned when the CLI parser rejects the command line before the subcommand `Action` runs (e.g., unknown flag, missing required positional argument). The framework prints a synopsis to stderr in addition to the exit code. | | `130` | `os.Exit(128 + int(syscall.SIGINT))` | Process terminated by `SIGINT` — Ctrl-C in an interactive shell. The agent caught the signal, stored it in `caughtSignal`, cancelled the agent context, returned from `main`, and explicitly called `os.Exit(130)`. | | `143` | `os.Exit(128 + int(syscall.SIGTERM))` | Process terminated by `SIGTERM` — orchestrator-driven shutdown (`systemctl stop linuxguard-agent`, `docker stop`, `kubectl delete pod`). The agent caught the signal, stored it in `caughtSignal`, cancelled the agent context, returned from `main`, and explicitly called `os.Exit(143)`. | ### The `128 + signum` convention `linuxguard-agent` re-raises caught signals as exit codes following the standard shell convention: | Signal | `signum` (Linux) | Exit code | | --------- | ---------------- | ---------------------- | | `SIGINT` | 2 | `128 + 2` = **`130`** | | `SIGTERM` | 15 | `128 + 15` = **`143`** | The re-raise happens via `os.Exit(128+signum)` directly from `main` (NOT from the signal-handling goroutine). The rationale and the history of why an earlier `signal.Reset` + `syscall.Kill(getpid, sig)` approach was replaced are documented in [`signals` § Re-raise convention](/reference/reference/cli/signals#re-raise-convention). The short version: under Go 1.25 inside a distroless containerized PID-1 deployment, the runtime's `dieFromSignal` path fell through to its `exit(2)` fallback before the synchronous re-raise terminated the process; `docker wait` reported `2` for every `SIGTERM`. Direct `os.Exit(128+signum)` returns the expected `143` deterministically. ## Per-command divergences | Command | Code | Difference from universal table | | ------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`probe`](/reference/reference/cli/probe) | `0` | **Always `0`.** Probe is non-fatal by design. Capability check failures are reported as `false` JSON fields, NOT as a non-zero exit. Even a JSON marshal failure (which should not happen for a struct of basic types) emits `{}` to stdout and returns `nil`. CI and Ansible callers MUST parse the JSON output and decide their own pipeline disposition. | | [`start`](/reference/reference/cli/start) | `0` | Never observed in normal long-running service mode. `0` only on `--help`, `--version`, or other early-exit paths that bypass the agent worker. A `start` that returned `0` after running is itself a bug — the agent is expected to either run indefinitely or terminate via signal (`130` / `143`) or error (`1`). | | [`status`](/reference/reference/cli/status) | `0` | Always `0` — `status` is informational. The "is the agent running?" answer is conveyed by the stdout text (`linuxguard-agent is running with PID: ` vs `linuxguard-agent is not running`), not by the exit code. Shell scripts that need a programmatic check should grep the stdout or use `pgrep linuxguard-agent`. | | [`stop`](/reference/reference/cli/exit-codes) | `0` or `1` | `0` when the PID file is absent (agent not running — non-error per the agent's logic) or when the agent acknowledged `SIGTERM` and exited within 10 seconds. `1` when the agent did not exit within the 10-second wait window or the PID file was unreadable. | | [`config set log_level`](/reference/reference/cli/config) | `0` | `0` even when no agent process is found at the PID file — `set` persists the new level and reports `(persisted; agent not running — applies on next start)` to stdout. The persist succeeded; the SIGHUP was skipped because the target did not exist. Distinguishing "persisted + SIGHUP delivered" from "persisted only" is the stdout message, not the exit code. | | [`support-bundle collect`](/reference/reference/cli/support-bundle) | `0` or `1` | `1` when the `--out` path is occupied (the `O_EXCL` open rejects pre-existing files), when the output directory cannot be created with mode `0750`, or when archive assembly fails. Otherwise `0` with the bundle path on stdout and `sha256=... size=...` on stderr. | | [`support-bundle upload`](/reference/reference/cli/support-bundle) | `0` or `1` | `1` when: the bundle file is missing or unreadable, its size disagrees with the manifest (file changed after `collect`), the presign call (`POST /upload-url`) fails, the PUT to S3 fails, or the register call (`POST /register`) fails. Otherwise `0` with `bundle_id`, `object_key`, and `uploaded_at` on stdout. The local bundle file is NEVER deleted regardless of outcome. | ## Examples ### Read the exit code in a shell ```bash linuxguard-agent probe > /dev/null echo "probe exit code: $?" # always 0 — see probe page ``` ```bash sudo linuxguard-agent config set log_level INFO || echo "rejected: invalid log level" # Exit code: 1 — strict lowercase wire format rejects INFO ``` ### Use SIGTERM for orchestrated shutdown ```bash sudo systemctl stop linuxguard-agent sudo systemctl show linuxguard-agent --property=ExecMainStatus # ExecMainStatus=143 ``` `systemctl stop` delivers `SIGTERM` via the unit file's `KillSignal=SIGTERM` (the systemd default). The agent's signal handler catches it and re-raises as `143`. `ExecMainStatus=143` is the recorded exit code. ### Detect signal-induced shutdown in CI / orchestrator logs `docker wait ` and `kubectl get pod -o jsonpath='{.status.containerStatuses[0].state.terminated.exitCode}'` both report the integer exit code. Treat `130` and `143` as graceful, signal-induced shutdowns (not failures) when the orchestrator initiated the stop. Treat `1` and `2` as actual errors that warrant log inspection. ### Distinguish argument parsing errors (`2`) from runtime errors (`1`) ```bash linuxguard-agent start --no-such-flag echo $? # 2 — urfave/cli rejected the flag before Action ran ``` ```bash sudo linuxguard-agent config set unknown_key value echo $? # 1 — SetField returned 'unknown config key' from the Action ``` Code `2` is a CLI-framework rejection; the subcommand never executed. Code `1` is a runtime error from inside the subcommand's `Action`. Both surface a non-zero exit, but the distinction is useful when triaging in CI logs. *** **Related**: [signals](/reference/reference/cli/signals) | [start](/reference/reference/cli/start) | [probe](/reference/reference/cli/probe) | [support-bundle](/reference/reference/cli/support-bundle) | [CLI Reference](/reference/reference/cli) # Supported Distributions Per-architecture capability matrix and per-distribution support matrix for the LinuxGuard agent — Debian, RedHat, SUSE, Alpine across amd64, arm64, armv7, and riscv64. LinuxGuard supports a range of Linux distributions across four family lines (Debian, RedHat, SUSE, Alpine) on multiple CPU architectures. This page is the canonical reference for which architecture × distribution combinations ship a working agent binary, and what the runtime feature surface looks like on each. > **Important**: Architecture support is **per-capability**, not binary. On architectures without eBPF support, the agent automatically falls back to a reduced-telemetry mode instead of failing to start — see the [Multi-Architecture Support](/install/install/multi-architecture) page for the full callout. The matrix below carries the same source-verified status. ## Architecture Capability Matrix The columns describe the granular surface every per-architecture deployment MUST reason about. A single "Supported" column would conflate the build-time eBPF availability with the runtime feature surface. | Arch | Binary | eBPF probes | Behavioral telemetry | Auth events | File monitor | CI-tested | | ----------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------- | -------------------------------- | -------------------------------- | ----------- | | `amd64` (x86\_64) | Yes | Yes (full clang/LLVM compile) | Yes | Yes | Yes | Yes | | `arm64` (aarch64) | Yes | Yes (full clang/LLVM compile) | Yes | Yes | Yes | Yes | | `armv7` (`arm`) | Yes | **No (falls back to reduced-telemetry mode)** | **No** | Limited (no eBPF-derived events) | Limited (no eBPF-derived events) | Best-effort | | `riscv64` | Yes | Best-effort (clang attempt; `.skip` on toolchain failure) | Conditional (depends on probe success) | Conditional | Conditional | No | | `s390x` | Unverified — do not rely on without confirmation against latest source build | Unverified | Unverified | Unverified | Unverified | No | | `ppc64le` | Unverified — do not rely on without confirmation against latest source build | Unverified | Unverified | Unverified | Unverified | No | For the column definitions and the runtime fallback flow, see [Multi-Architecture Support](/install/install/multi-architecture). ## Per-Distribution Architecture Support Each distribution family ships agent packages for the architectures listed below. Distribution order is fixed across this documentation set: Debian/Ubuntu → RedHat/CentOS → SUSE → Alpine. | Distribution Family | amd64 | arm64 | armv7 | riscv64 | Minimum kernel | Package repo | | ------------------- | ----- | ----- | ------------------- | ----------- | -------------- | ------------------------------- | | Debian / Ubuntu | Yes | Yes | Yes (Degraded mode) | No | 4.18 | `packages.linuxguard.io/apt` | | RedHat / CentOS | Yes | Yes | No | No | 4.18 | `packages.linuxguard.io/dnf` | | SUSE / openSUSE | Yes | Yes | No | No | 4.18 | `packages.linuxguard.io/zypper` | | Alpine | Yes | Yes | Yes (Degraded mode) | Best-effort | 4.18 | `packages.linuxguard.io/apk` | ARMv7 packages on Debian/Ubuntu and Alpine install the agent binary, but the resulting deployment runs in Degraded mode with no eBPF-derived telemetry. Plan compliance and detection-coverage assumptions accordingly. ## Distribution Families LinuxGuard organizes support by distribution families, which share similar package management systems and system architectures. ### Debian-based Systems LinuxGuard supports all Debian-based distributions that use the APT package manager. **Supported Distributions:** * **Debian**: All currently supported versions (Debian 10+, including Debian 11 "Bullseye", Debian 12 "Bookworm") * **Ubuntu**: All LTS and current versions (Ubuntu 20.04+, including 22.04, 24.04) * **Linux Mint**: Versions based on supported Ubuntu LTS releases * **Other Debian derivatives**: Any distribution using APT package management **Package Manager**: APT (Advanced Package Tool) **Repository Setup**: Uses the Debian/APT repository format ### RedHat-based Systems LinuxGuard supports RedHat-based distributions that use YUM or DNF package managers. **Supported Distributions:** * **Red Hat Enterprise Linux (RHEL)**: RHEL 7, 8, 9 and later versions * **CentOS**: CentOS 7, 8, and CentOS Stream * **Fedora**: Current and recent Fedora releases (Fedora 35+) * **Rocky Linux**: All versions * **AlmaLinux**: All versions * **Oracle Linux**: Versions compatible with RHEL * **Amazon Linux**: Amazon Linux 2 and Amazon Linux 2023 **Package Manager**: DNF (or YUM on older systems) **Repository Setup**: Uses the YUM/DNF repository format ### openSUSE/SLES-based Systems LinuxGuard supports openSUSE and SUSE Linux Enterprise Server distributions. **Supported Distributions:** * **openSUSE Leap**: 15.x and later versions * **openSUSE Tumbleweed**: Rolling release * **SUSE Linux Enterprise Server (SLES)**: SLES 15 and later **Package Manager**: Zypper **Repository Setup**: Uses the Zypper repository format ### Alpine-based Systems LinuxGuard supports Alpine Linux and Alpine-based distributions. **Supported Distributions:** * **Alpine Linux**: Alpine 3.14+ (all currently supported versions) **Package Manager**: APK (Alpine Package Keeper) **Repository Setup**: Uses the Alpine APK repository format ## System Requirements ### Minimum Requirements * **Kernel**: Linux kernel 4.18 or later (required for eBPF runtime detection on supported architectures) * **Architecture**: See the architecture capability matrix above * **Disk Space**: 100 MB for agent installation * **Memory**: 50 MB RAM for agent operation * **Network**: Outbound HTTPS connectivity to `api.linuxguard.io` * **Permissions**: Root or sudo access for installation and configuration ### Recommended Requirements * **Disk Space**: 500 MB (for logs and temporary files) * **Memory**: 100 MB RAM * **Network**: Stable internet connection for real-time telemetry ## Installation Methods LinuxGuard uses a unified installer script that automatically detects your distribution and configures the appropriate package repository: ```bash curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | sudo bash ``` The installer supports all distribution families listed above and handles: * Automatic distribution detection * Repository configuration for your package manager (APT, DNF/YUM, Zypper, or APK) * Package installation For installation options and examples, see the [Installation Guide](/install/install). ## Version Support Policy LinuxGuard maintains support for: * All currently supported versions of each distribution * LTS (Long Term Support) versions for distributions that offer them * Recent stable releases For questions about support for specific distribution versions, contact . *** **Related**: [Multi-Architecture Support](/install/install/multi-architecture) | [Installation](/install/install) | [Prerequisites](/install/install/prerequisites) | [Troubleshooting](/troubleshooting) # Glossary Glossary of LinuxGuard terminology — agent, console, eBPF, enrollment, modules, compliance frameworks, and related security concepts. This glossary defines key concepts used throughout LinuxGuard documentation. ## Access Pattern Recurring behavior profile for a user or service account. LinuxGuard establishes access pattern baselines over an observation period and surfaces deviations that may indicate compromised credentials or insider threat. See [Identity Intelligence](/concepts/concepts/console/identity-intelligence). ## Active Response Automated containment action executed by LinuxGuard when a playbook's trigger conditions are met. Active responses require triple opt-in (playbook enabled, scope confirmed, blast radius set) and produce an audited action history with automatic timeout-based rollback. See [Active Response](/concepts/concepts/active-response). ## Attribution Confidence Reliability level for process attribution showing how LinuxGuard identified the process behind a security event. HIGH confidence uses eBPF kernel-level tracing, MEDIUM uses /proc filesystem parsing, LOW uses fallback methods when primary sources unavailable. See [Console Overview](/concepts/concepts/console). ## Authentication Event A record of a login attempt (success or failure) with method, source IP, username, and timestamp. LinuxGuard collects authentication events from syslog, journald, and utmp/wtmp/btmp logs. See [Console Overview](/concepts/concepts/console). ## Authentication Method Login mechanism used for system access: password, publickey, keyboard-interactive, or GSSAPI. Captured during authentication event collection and displayed in the console. See [Console Overview](/concepts/concepts/console). ## Baseline Known-good reference state for a security-relevant object (account, group, SSH config, SSHD config, sudo defaults, sudo aliases, sudo rules). LinuxGuard captures baselines per server and surfaces deviations as drift events. The Baselines section of the console hosts the per-object-type baseline browsers and editing UI. See [Baselines](/concepts/concepts/console/baselines). ## Behavioral Baseline Statistical model of normal activity for a user or service account, learned over an observation period. LinuxGuard uses behavioral baselines to identify anomalous access that deviates from established norms. See [Identity Intelligence](/concepts/concepts/console/identity-intelligence). ## Blast Radius System-enforced limit on how many servers a playbook's containment action can affect in a single trigger event. Blast radius is configured as a hard cap during playbook setup and cannot be exceeded at runtime, even if more servers match the trigger condition. See [Active Response](/concepts/concepts/active-response). ## Brute Force Detection Automated detection of credential stuffing and targeted attack patterns in authentication events. LinuxGuard analyzes login attempts to identify suspicious patterns like many users from few IPs or one user from many IPs. See [Console Overview](/concepts/concepts/console). ## CIS Benchmarks (Linux) Distribution-specific configuration hardening guides published by the Center for Internet Security — Ubuntu, RHEL, SUSE, Alpine, and others — each versioned independently. Used as a configuration baseline reference and frequently cited in audit programs. Distinct from CIS Controls. See [Audit & Comply](/audit-and-comply/audit-comply). ## CIS Controls v8.1 Prescriptive control set published by the Center for Internet Security (18 controls in v8 vs 20 in v7) covering defense-in-depth practices applicable across organization sizes. Distinct from CIS Benchmarks (which are distro-specific configuration guides). See [Audit & Comply](/audit-and-comply/audit-comply). ## Compliance Score Measure of adherence to security compliance frameworks with pass/fail/not-applicable check counts. LinuxGuard evaluates compliance at both fleet-wide and per-server levels against enabled frameworks. See [Console Overview](/concepts/concepts/console). ## Config Drift Unexpected changes to server configurations detected by comparing against baselines. Tracked across six component types: Accounts, Groups, Sudo, SSH, SSHD, and SSH Keys. See [Console Overview](/concepts/concepts/console). ## Configuration File Write Detection eBPF-based monitoring of writes to security-critical files including sudoers, sshd\_config, passwd, shadow, and authorized\_keys. This feature may not be visible until enabled by your LinuxGuard administrator. See [Security Architecture](/concepts/concepts/security-architecture). ## Containment Action Specific automated response step executed by a playbook: lock account, kill sessions, disable SSH key, or revoke sudo. Each containment action is reversible (except kill sessions) via automatic timeout rollback or manual console rollback. See [Active Response](/concepts/concepts/active-response). ## Control Mapping Documented relationship between an agent or console capability and a specific framework requirement. LinuxGuard publishes per-framework control mappings using the three-tier vocabulary (Satisfies / Supports / Out of scope), each with an evidence pointer and a version pin. See [Audit & Comply](/audit-and-comply/audit-comply). ## Credential Stuffing Brute force pattern where attacker tries many usernames from one or few source IPs. Indicates the attacker is testing credential lists against the system. See [Console Overview](/concepts/concepts/console). ## Cron Job Scheduled task defined in user or system crontab files, executed at specified intervals. LinuxGuard inventories cron jobs as part of NHI automation monitoring. See [Console Overview](/concepts/concepts/console). ## DegradedNoEBPFArch Agent status indicating the host architecture has no eBPF-based monitoring available. Always returned on ARMv7; may also occur on RISC-V, depending on build support for that platform. Behavioural detections requiring eBPF are unavailable in this status; auth-event, file-monitor (read-path), and config-drift collectors continue running. See [Multi-Architecture Support](/install/install/multi-architecture). ## Delivery Channel Mechanism through which LinuxGuard sends alert notifications: webhook (HTTP POST to a custom endpoint), syslog (RFC 3164 or RFC 5424 UDP/TCP/TLS forwarding), or Splunk HEC (native Splunk HTTP Event Collector integration). Each notification rule specifies one delivery channel. See [Alerting & SIEM Integration](/concepts/concepts/alerting). ## Detractor Risk factor that increases a posture score, such as no password expiry, unencrypted SSH key, or weak authentication configuration. Detractors have configurable weights affecting overall score calculation. See [Console Overview](/concepts/concepts/console). ## Distroless Container image built without a shell, package manager, or general-purpose userland — only the binary, its runtime libraries, and minimum required CA certs/timezone data. The LinuxGuard distroless image (`linuxguard/agent`) ships only `linuxguard-agent` and `linuxguard-init-shim`. Reduces attack surface and image size; trade-off is no in-container debugging shell. See [Distroless image reference](/install/install/container/distroless). ## DORA (Digital Operational Resilience Act) EU Regulation (EU) 2022/2554, effective 2025-01-17. Direct-effect regulation applicable to EU financial entities (banks, insurance, investment, crypto-asset service providers) and their critical third-party ICT providers. No member-state transposition required. See [Audit & Comply](/audit-and-comply/audit-comply). ## Downward API Kubernetes mechanism that exposes Pod and Node metadata to a container through environment variables or volume-mounted files. LinuxGuard reads `LINUXGUARD_NODE_NAME` (Node name) and `LINUXGUARD_POD_UID` (Pod UID) via `valueFrom.fieldRef` to bind a containerised agent to its workload identity. See [Downward API integration](/install/install/container/downward-api). ## Drift Difference between an object's current observed state and its baseline. LinuxGuard surfaces drift as events that progress from initial detection through investigation to resolution, each with field-level diffs. Tracked across accounts, groups, SSH config, SSHD config, sudo defaults, sudo aliases, sudo rules, and SSH keys. See [Baselines](/concepts/concepts/console/baselines). ## eBPF Access Monitoring Kernel-level tracing of file access to track file read/write activity with process attribution. LinuxGuard uses eBPF to capture file access events at the kernel layer without requiring kernel modules. See [Security Architecture](/concepts/concepts/security-architecture). ## eBPF Probe The kernel-level eBPF instrumentation LinuxGuard uses to observe system activity on a given architecture. LinuxGuard ships this instrumentation per supported architecture; on an architecture where it is not available (always on ARMv7; possibly on RISC-V), the agent falls back to `DegradedNoEBPFArch` and runs without that capability. See [Multi-Architecture Support](/install/install/multi-architecture). ## Ephemeral Mode Containerised agent mode enabled by `--ephemeral`. Skips on-disk state persistence (TLS material lives in tmpfs at `--tls-cache`), re-enrols on every container start using a TOTP enrollment token, and exits cleanly on SIGTERM with code 143. Designed for short-lived workloads and immutable infrastructure where the agent must not write to the host filesystem. See [Ephemeral mode](/install/install/container/ephemeral-mode). ## Environment Named server grouping (e.g., production, staging, development) assigned during enrollment using the --environment flag. Environments help organize servers and filter console views by deployment stage. See [Agent Commands](/reference/reference/agent-commands). ## EU AI Act EU Regulation (EU) 2024/1689, entered into force 2024-08-01. Direct-effect regulation laying down harmonised rules on artificial intelligence. Distinguishes four risk tiers (prohibited, high-risk, limited risk with transparency obligations, minimal risk) plus general-purpose AI models. Phased applicability: prohibited AI from 2025-02-02; GPAI obligations from 2025-08-02; high-risk AI under Annex III from 2026-08-02; high-risk AI embedded in regulated products under Annex I from 2027-08-02. LinuxGuard's per-framework mapping is scoped to host-layer record-keeping (Art 12) and cybersecurity (Art 15) requirements for customers operating high-risk AI systems on Linux infrastructure. See [Audit & Comply](/audit-and-comply/audit-comply). ## Evidence Location Canonical pointer set identifying where compliance evidence for a control is retrieved (agent log, support bundle, console Evidence tab, signals, drift events, SUDO execution audit, compliance history, compliance reports, bundle manifest). Per-framework mapping pages cite a row of the Evidence Location table rather than restating evidence pointers per page. See [Compliance Expansion § Evidence Location](/concepts/concepts/console/compliance-expansion#evidence-location). ## Exfiltration Detection Pattern recognition for data theft via local copy or network transfer. LinuxGuard analyzes file system events to identify potential data exfiltration activities. See [Console Overview](/concepts/concepts/console). ## Factor Weight Configurable importance assigned to individual detractors and mitigators in posture scoring. Administrators can adjust weights to match organizational priorities. See [Console Overview](/concepts/concepts/console). ## FedRAMP U.S. federal cloud-service authorization program operated by the GSA. LinuxGuard documents control mapping against FedRAMP Rev 5 baselines (May 2023). Cloud service providers serving federal agencies use FedRAMP to obtain an Authority to Operate (ATO). See [Audit & Comply](/audit-and-comply/audit-comply). ## FFIEC CAT Federal Financial Institutions Examination Council Cybersecurity Assessment Tool (2017), used by U.S. financial institutions and their regulators to evaluate cybersecurity preparedness. FFIEC IT Handbook booklets may also be referenced in audit programs. See [Audit & Comply](/audit-and-comply/audit-comply). ## File Baseline Known-good state of a file including hash, permissions, and ownership used to detect changes. LinuxGuard compares current file state against baselines to identify configuration drift. See [Console Overview](/concepts/concepts/console). ## File Monitoring Real-time tracking of file system changes (create, modify, delete, rename) and access events. Administrators configure which files and folders the agent monitors via console settings. See [Console Overview](/concepts/concepts/console). ## Fleet Aggregation Method for combining server scores into fleet-level scores. Configurable in posture scoring settings to match organizational risk tolerance. See [Console Overview](/concepts/concepts/console). ## Framework Version Pin Explicit version, effective date, and last-verified date attached to a per-framework compliance mapping page. Per-framework pages cite the corresponding row in the [Audit & Comply hub framework version pin reference](/audit-and-comply/audit-comply#framework-version-pin-reference). A stale `last_verified` date blocks publication. See [Audit & Comply](/audit-and-comply/audit-comply). ## GDPR EU General Data Protection Regulation, Regulation (EU) 2016/679, effective 2018-05-25. Applies to controllers and processors handling personal data of EU residents. IP addresses are PII under EU case law, which is relevant to log shipping and SIEM forwarding decisions. See [Audit & Comply](/audit-and-comply/audit-comply). ## GeoIP Enrichment Agent-side IP geolocation identifying source country and region for authentication events. LinuxGuard enriches login events with geographic information to help identify suspicious access patterns. See [Console Overview](/concepts/concepts/console). ## HIPAA U.S. Health Insurance Portability and Accountability Act. LinuxGuard documents control mapping against HIPAA 45 CFR §164 (Privacy, Security, and Breach Notification Rules) — covered entities and business associates handling protected health information cite specific CFR sections rather than "HIPAA" generally. See [Audit & Comply](/audit-and-comply/audit-comply). ## HITRUST CSF HITRUST Common Security Framework, versioned annually (v11.x current as of 2026-05-31). Unified control framework commonly adopted by healthcare organizations consolidating HIPAA, NIST, ISO/IEC 27001, and other framework requirements into a single assessment program. Pin a specific minor version per audit period. See [Audit & Comply](/audit-and-comply/audit-comply). ## Hub Page Top-level index page for one of the nine IA groups (Get Started, Install, Configure, Operate, Deploy at Scale, Respond, Audit & Comply, Reference, Concepts). Each hub introduces the group, links to its child spoke pages (usually via a card grid), and serves as the landing page for the corresponding SUMMARY.md section. Hub pages do not contain task content; spokes do. See the [IA framework decision record](https://github.com/linuxguardx/linuxguard-documentation/tree/main/.planning/decisions/IA-FRAMEWORK.md) for the full hub catalogue. ## IA Shell The on-disk directory structure of the nine top-level IA groups plus their hub READMEs. The IA shell is created independently of page content so migrations and new authoring can target the final layout without race-conditioning the GitBook build. The v4.0 IA shell replaces the v3.0 Diataxis four-quadrant tree (`tutorials/`, `how-to/`, `reference/`, `explanation/`). See [IA Framework](https://github.com/linuxguardx/linuxguard-documentation/tree/main/.planning/decisions/IA-FRAMEWORK.md). ## Identity Unified representation of a user or service account aggregated across all enrolled servers. LinuxGuard builds an identity by linking authentication events, SSH keys, sudo rules, and NHI automation entries from every server where the account appears. See [Identity Intelligence](/concepts/concepts/console/identity-intelligence). ## ISO/IEC 27001:2022 Joint ISO/IEC standard for information security management systems. The 2022 revision restructured Annex A controls from 114 (in :2013) to 93 controls across four themes. Transition deadline for :2013-certified organizations is 2025-10-31. See [Audit & Comply](/audit-and-comply/audit-comply). ## Lifecycle Phase One of the nine canonical operational phases used to organise LinuxGuard documentation: Get Started, Install, Configure, Operate, Deploy at Scale, Respond, Audit & Comply, Reference, Concepts. A page lives in exactly one lifecycle phase based on when in the agent's lifecycle the reader needs it. See [Lifecycle-First Hybrid](#lifecycle-first-hybrid). ## Lifecycle-First Hybrid Information architecture adopted in v4.0. Nine top-level groups arranged by the lifecycle phase the reader is in (Get Started → Install → Configure → Operate → Deploy at Scale → Respond → Audit & Comply → Reference → Concepts), plus three footer pages (Troubleshooting, Support, Changelog). Replaces the v3.0 Diataxis four-quadrant model (Tutorials, How-to Guides, Reference, Explanation). Optimises for "I'm in phase X, what do I need to do?" navigation. See [IA framework decision record](https://github.com/linuxguardx/linuxguard-documentation/tree/main/.planning/decisions/IA-FRAMEWORK.md). ## LoginUID Original login user identity that survives `sudo`/`su` privilege escalation, preserving non-repudiation. LinuxGuard attributes actions to the actual user even when a process is running as root. See [Security Architecture](/concepts/concepts/security-architecture). ## Mitigator Positive factor that decreases a posture score, such as strong authentication or encrypted SSH keys. Mitigators have configurable weights reducing risk scores for servers with good security practices. See [Console Overview](/concepts/concepts/console). ## Multi-Arch Manifest OCI Image Index (also called a "fat manifest") that references one per-platform manifest under a single image tag. `docker pull linuxguard/agent:latest` from an amd64 host pulls the amd64 manifest; the same command on arm64 pulls the arm64 manifest. LinuxGuard publishes a multi-arch manifest covering amd64, arm64, armv7, riscv64, s390x, and ppc64le; eBPF availability per platform is documented separately in the per-capability matrix. See [OCI multi-arch manifest](/install/install/oci-multi-arch-manifest). ## NHI Automation Non-Human Identity scheduled tasks (cron jobs, systemd timers) that run without direct user interaction. LinuxGuard inventories NHI automation to provide visibility into automated system activities. See [Console Overview](/concepts/concepts/console). ## NIS2 EU Directive (EU) 2022/2555, effective 2024-10-17. Network and Information Security Directive (second iteration), applicable to essential and important entities operating in the EU. Member-state transposition varies — the specific transposing national law applies to each customer jurisdiction. See [Audit & Comply](/audit-and-comply/audit-comply). ## NIST CSF 2.0 U.S. National Institute of Standards and Technology Cybersecurity Framework version 2.0, published 2024-02-26. Voluntary risk-management framework commonly used as a parent framework that organizations map their other compliance work back to. CSF 1.1 is still widely cited externally — note the version distinction when customers cross-reference. See [Audit & Comply](/audit-and-comply/audit-comply). ## Non-Human Identity (NHI) Service account, API credential, or automated process that accesses systems without direct user interaction. LinuxGuard automatically identifies and classifies NHIs across your infrastructure to give visibility into automated system activity that would otherwise go unmonitored. See [Identity Intelligence](/concepts/concepts/console/identity-intelligence). ## Notification Rule Console-configured rule that sends an alert through a delivery channel when specified trigger conditions are met. Notification rules support severity filters, throttle windows, quiet hours, and scope filters; a rule with no conditions forwards all signals. See [Alerting & SIEM Integration](/concepts/concepts/alerting). ## OCI Manifest Container image manifest in Open Container Initiative format. For a single architecture, the manifest lists the image's config and layer digests. For multi-architecture images, the OCI Image Index references one manifest per platform (see [Multi-Arch Manifest](#multi-arch-manifest)). Inspect with `docker manifest inspect ` or `crane manifest `. See [OCI multi-arch manifest](/install/install/oci-multi-arch-manifest). ## Orphaned Key SSH public key that remains authorized on a server after the associated user account has been deleted or disabled. LinuxGuard detects orphaned keys by cross-referencing authorized\_keys entries against active account lists. See [Identity Intelligence](/concepts/concepts/console/identity-intelligence). ## Out of scope (compliance vocabulary tier) Third tier of the LinuxGuard compliance vocabulary contract. A control marked `Out of scope` concerns a framework domain that LinuxGuard does not address (physical access, application-layer authentication, key management, contract management, employee training, etc.). Per-framework mapping tables list out-of-scope controls explicitly — silence is interpreted as an implicit `Satisfies` claim. See [Audit & Comply § Three-tier vocabulary contract](/audit-and-comply/audit-comply#three-tier-vocabulary-contract). ## PCI-DSS v4.0.1 Payment Card Industry Data Security Standard, version 4.0.1 (effective 2024-06-01). PCI-DSS v3.2.1 retired 2024-03-31; control mapping pages cite v4.x requirement numbers. Applies to organizations processing, storing, or transmitting payment card data. See [Audit & Comply](/audit-and-comply/audit-comply). ## Playbook Console-configured automation rule that defines trigger conditions and one or more containment actions to execute when a security signal matches. Playbooks require explicit opt-in at three levels (playbook enabled, scope defined, blast radius set) before they become active. See [Active Response](/concepts/concepts/active-response). ## Posture Score Composite score (0-100, lower is better) evaluating security posture across accounts, groups, sudo, SSHD configuration, and SSH keys. Posture scores use configurable detractors, mitigators, and weights. See [Console Overview](/concepts/concepts/console). ## Presigned Upload Two-phase support-bundle upload flow: the agent POSTs `/v1/support/bundle/upload-url` to obtain a presigned S3 PUT URL, PUTs the bundle bytes directly to S3, then POSTs `/v1/support/bundle/register` to record the bundle metadata. The bundle bytes never traverse the LinuxGuard API; only the metadata round-trip does. See [Support Bundles](/operate/operate/support-bundles). ## Process Attribution Identifying which process, user, and command caused a security event. LinuxGuard uses eBPF and kernel data to provide reliable attribution with confidence levels (HIGH/MEDIUM/LOW). See [Console Overview](/concepts/concepts/console) and [Security Architecture](/concepts/concepts/security-architecture). ## PSS (Pod Security Standard) Kubernetes namespace-level admission policy with three profiles: `privileged` (unrestricted, required for the LinuxGuard host-level DaemonSet), `baseline` (minimally restrictive — disallows known privilege escalations), `restricted` (heavily restricted — forbids running as root, host namespaces, host paths). Each LinuxGuard container deployment manifest declares the PSS profile it works under so platform teams can validate against their namespace policies. See [Kubernetes DaemonSet](/install/install/container/kubernetes-daemonset). ## Redaction Summary JSON block emitted at the start of every rotated agent log segment and embedded in the support-bundle manifest. Lists, per redacted attribute key, the count of redactions applied since the last rotation. Allows operators to verify that the attribute-key regex (`^(api_key|enroll_token|.*_token|.*_secret)$`) is matching expected fields. Does NOT track PII because PII redaction is out of scope (LOG-04). See [Log Management](/operate/operate/log-management). ## Satisfies (compliance vocabulary tier) First tier of the LinuxGuard compliance vocabulary contract. A control marked `Satisfies` means LinuxGuard, as deployed per documented configuration, materially fulfills the control requirement — the customer must still demonstrate operational evidence to an auditor. Every Satisfies claim cites a specific agent feature, a specific evidence pointer, and a specific framework requirement number with version. See [Audit & Comply § Three-tier vocabulary contract](/audit-and-comply/audit-comply#three-tier-vocabulary-contract). ## Score Band Configurable threshold ranges for interpreting posture scores. Administrators define score band boundaries in posture scoring configuration to match organizational risk appetite. See [Console Overview](/concepts/concepts/console). ## Scope Statement One-paragraph declaration at the top of every per-framework compliance mapping page stating what the page is scoped to address and what is out of scope. Per-framework pages instantiate (not paraphrase) the [scope statement template](/audit-and-comply/audit-comply#scope-statement-template) so procurement and audit reviewers can compare pages mechanically. See [Audit & Comply](/audit-and-comply/audit-comply). ## Sensitive Group POSIX group whose membership grants privileged access (`wheel`, `sudo`, `docker`, `lxd`, `kvm`, `disk`, `adm`, and configurable additions). LinuxGuard tracks membership of sensitive groups as part of the Groups baseline and surfaces additions/removals as drift events. See [Baselines](/concepts/concepts/console/baselines). ## Shared Responsibility Canonical statement appearing verbatim on every per-framework mapping page: LinuxGuard is a security monitoring agent and console; compliance with any framework requires customer-side controls in addition to LinuxGuard's capabilities; the mapping is informational and not a substitute for an independent audit by a qualified assessor. Frames the LinuxGuard / customer / out-of-scope responsibility layers. See [Audit & Comply § Shared responsibility](/audit-and-comply/audit-comply#shared-responsibility). ## Signal Deduplication Grouping identical security signals within a time window, preserving occurrence counts. LinuxGuard deduplicates signals to reduce noise while maintaining visibility into repeated events. See [Console Overview](/concepts/concepts/console). ## SOC 2 (TSC 2017 rev 2022) AICPA Service Organization Control 2 attestation framework, based on the Trust Services Criteria 2017 (revised 2022). Service organizations produce SOC 2 reports for customers — common scope is the Security TSC; expanded scope adds Availability, Confidentiality, Processing Integrity, and Privacy. Distinguish Type I (point-in-time design) vs Type II (operating effectiveness over a period) in reporting language. See [Audit & Comply](/audit-and-comply/audit-comply). ## StateRAMP U.S. state-government cloud authorization program drawing on FedRAMP Rev 5 baselines, scoped to state and local government cloud service providers. Counterpart to FedRAMP at the state level. See [Audit & Comply](/audit-and-comply/audit-comply). ## Support Bundle Compressed archive (`.tar.zst`) collected by `linuxguard-agent support-bundle collect` containing the agent log, rotated log segments (newest-first, trimmed to a 180 MB pre-compress cap), the redacted config snapshot, the bundle manifest, and lightweight host metadata. Default path is `/var/lib/linuxguard/support/.tar.zst`; sha256 + size are printed to stderr. Used for support escalation and offline diagnosis. See [Support Bundles](/operate/operate/support-bundles). ## Supports (compliance vocabulary tier) Second tier of the LinuxGuard compliance vocabulary contract. A control marked `Supports` means LinuxGuard provides telemetry, controls, or evidence that contributes to satisfying the control requirement, but full satisfaction depends on additional customer-side controls (IAM, network segmentation, key management, etc.). Every Supports claim explicitly states what the customer must implement to achieve full satisfaction. See [Audit & Comply § Three-tier vocabulary contract](/audit-and-comply/audit-comply#three-tier-vocabulary-contract). ## Systemd Timer Modern systemd-based scheduling mechanism as an alternative to cron for automated tasks. LinuxGuard inventories systemd timers as part of NHI automation monitoring. See [Console Overview](/concepts/concepts/console). ## Targeted Attack Brute force pattern where attacker targets one username from many source IPs. Indicates a distributed attack on a single account. See [Console Overview](/concepts/concepts/console). ## TOTP Enrollment Token Time-based one-time password used to bootstrap a container or ephemeral agent into a tenant. Read from `LINUXGUARD_ENROLL_TOKEN` (preferred — immediately unset from the process environment to avoid `/proc//environ` leakage) or `--enroll-token`. Requires `--tenant-id` to scope the enrolment. A hash of the token is tagged on the resulting workload identity for renewal tracking. See [Enrollment tokens](/install/install/container/enrollment-tokens). ## Webhook HTTP endpoint that receives LinuxGuard alert payloads as JSON POST requests. Webhooks include an HMAC-SHA256 signature in the `X-LinuxGuard-Signature` header for payload verification. See [Alerting & SIEM Integration](/concepts/concepts/alerting). ## Workload Identity Tenant-scoped identifier for an ephemeral or containerised agent instance, distinct from a server identity. In Kubernetes-aware deployments LinuxGuard derives the workload identity from `LINUXGUARD_POD_UID` (via Downward API) or `sha256(--workload-id)` when an explicit ID is passed. The workload identity binds collected telemetry to the workload (pod, job, ephemeral task) rather than to a long-lived host. See [Downward API integration](/install/install/container/downward-api). ## Zero Trust Enforcement Console pillar that surfaces security signals enriched with identity context and tracks configuration drift with who-changed-it attribution. Zero Trust Enforcement connects behavioral anomalies to the specific identities involved, enabling identity-aware incident response. See [Console Overview](/concepts/concepts/console/zero-trust-enforcement). *** **Related**: [Console Overview](/concepts/concepts/console) | [Security Architecture](/concepts/concepts/security-architecture) | [Agent Commands](/reference/reference/agent-commands) | [Audit & Comply](/audit-and-comply/audit-comply) # Concepts Conceptual scaffolding for LinuxGuard — security architecture, active response, alerting, and the console pillars. Cross-cutting understanding pages: security architecture, identity intelligence, active response model, alerting model, and the console pillars sub-group. ## What's in this section * [**Security Architecture**](/concepts/concepts/security-architecture) — LinuxGuard's zero-trust, least-privilege security architecture — privilege model, eBPF monitoring, and runtime protections. * [**Active Response**](/concepts/concepts/active-response) — How LinuxGuard's active-response model executes automated containment actions with triple opt-in safety and audited rollback. * [**Alerting & SIEM Integration**](/concepts/concepts/alerting) — How LinuxGuard routes security signals to webhook, syslog, and Splunk HEC delivery channels via notification rules. * [**Console**](/concepts/concepts/console) — Overview of the LinuxGuard console — the five pillars (Dashboard, Identity Intelligence, Zero Trust, Compliance, Infrastructure) and module gating. # Security Architecture LinuxGuard's zero-trust, least-privilege security architecture — privilege model, eBPF monitoring, and runtime protections. LinuxGuard is designed with security as a foundational principle. The agent follows a zero-trust, least-privilege model to ensure the monitoring solution does not become a security risk to your infrastructure. This document explains LinuxGuard's security architecture, covering privilege requirements, eBPF-based monitoring, and the protections that keep your systems safe. ## Privilege Model LinuxGuard separates installation-time privileges from runtime privileges. Root access is required only during installation; normal operation runs as an unprivileged user. ### Installation (Root Required) Root or sudo access is required during installation for: * **Creating the linuxguard user and group** - A dedicated system account for running the agent * **Installing files to system directories** - Binaries in `/usr/bin/`, configuration in `/etc/linuxguard/` * **Registering the systemd service** - Adding the service unit file and enabling automatic startup * **Setting up audit integration** - Configuring audit rules and granting audit log access * **Granting auth log access** - Setting ACLs on authentication logs so the agent can collect login events without root After installation completes, root access is no longer required for normal operation. ### Runtime (Non-Root) The LinuxGuard agent runs as the unprivileged `linuxguard` user: * **No system file modification** - Cannot alter files in `/etc/`, `/usr/`, or other system directories * **Read-only monitoring** - Observes system activity without changing it * **Isolated directories** - All writes limited to agent-specific locations (`/var/lib/linuxguard/`, `/var/log/linuxguard/`) * **No login shell** - The linuxguard account cannot be used for interactive access This separation ensures that even if the agent were compromised, the attacker would have no ability to modify the system or escalate privileges. ## Response Executor Privilege Model When active response is enabled, LinuxGuard deploys a second binary — the **response executor** (`/usr/bin/linuxguard-response-executor`) — that runs as a separate, privilege-separated service alongside the monitoring agent. ### Executor vs Agent The monitoring agent and the response executor are distinct binaries with distinct privilege models: | Component | Binary | Runtime User | Purpose | | ----------------- | ------------------------------ | ----------------------- | ------------------------------------------------ | | Monitoring agent | `linuxguard-agent` | `linuxguard` (non-root) | Collect telemetry and send events to the console | | Response executor | `linuxguard-response-executor` | `root` | Execute containment actions on demand | The monitoring agent's privilege model — described in the sections above — is unchanged by the presence of the executor. ### Why the Executor Runs as Root The four containment actions require root privileges: `usermod`, `loginctl terminate-user`, writes to `/etc/sudoers.d/`, and writes to `/home/*/.ssh/authorized_keys` require effective root UID. Linux capabilities are not sufficient for these operations. The executor runs as root because the containment actions require it — not as a general escalation. Its write access is restricted by systemd to four specific paths: * `/etc/sudoers.d` — for the revoke sudo action * `/home` — for the disable SSH key action * `/run/linuxguard` — for the IPC socket * `/var/log/linuxguard` — for the executor audit log ### Privilege Separation The executor does not run as a long-running privileged process. It listens on a Unix domain socket (`/run/linuxguard/`) and executes operations on demand when the monitoring agent sends a validated command. Communication between the monitoring agent and the executor uses SO\_PEERCRED authentication on the Unix socket — only the `linuxguard` user (the monitoring agent's operating user) can call the executor. All other callers are rejected at the socket level. ### Executor Audit Log Every containment action executed by the response executor is recorded to `/var/log/linuxguard/executor.log` as structured JSON. Entries are append-only. This log is separate from the command audit trail in the console and provides a local host-level record of all response operations. > **Note**: The response executor service is installed only when the active response package is installed. Systems without the active response package run only the monitoring agent, with no root-privileged component present. See [Active Response](/concepts/concepts/active-response) for the full safety model, playbook configuration, and containment action documentation. ## eBPF Architecture LinuxGuard uses eBPF (extended Berkeley Packet Filter) for kernel-level monitoring. Unlike traditional kernel modules, eBPF programs run in a sandboxed environment with built-in safety guarantees. ### Why eBPF Traditional security agents often use kernel modules to gain visibility into system activity. Kernel modules operate with full kernel privileges, which means a bug in the module can crash the entire system. LinuxGuard uses eBPF instead, which provides equivalent visibility with stronger safety guarantees: | Approach | Risk if Bug | Crash Recovery | Verification | | ------------- | ------------------------------ | -------------------- | ----------------- | | Kernel module | Kernel panic, system crash | Reboot required | None before load | | eBPF program | Program rejected or terminated | Automatic, no reboot | Built-in verifier | eBPF programs are verified by the kernel before they run. If a program contains unsafe operations, the kernel rejects it entirely rather than allowing it to execute. ### Loader/Runtime Architecture LinuxGuard uses a split architecture that separates privileged and unprivileged operations: 1. **Loader process** - Performs the brief, privileged setup needed to activate eBPF-based monitoring, then exits. eBPF instrumentation automatically reactivates when the agent binary changes, eliminating the need for manual daemon restarts during updates. 2. **Runtime process** - Processes events in userspace. This component runs continuously as the unprivileged linuxguard user, receiving events from the kernel and transmitting them to the LinuxGuard console. This separation limits the code running with elevated capabilities to the minimal loader component. The long-running runtime process operates without elevated privileges. ### Safety Guarantees The Linux kernel's eBPF verifier ensures all LinuxGuard eBPF programs meet strict safety requirements: * **Memory safety** - Cannot access arbitrary kernel memory; limited to designated data structures * **Termination** - Must complete execution (no infinite loops allowed) * **Kernel stability** - Cannot destabilize the kernel or cause a panic * **Spectre hardening** - Protected against speculative execution attacks If verification fails for any reason, the program is rejected and never runs. This is fundamentally different from kernel modules, which can execute arbitrary code with full kernel privileges. ### LoginUID Capture LinuxGuard captures the original login user identity (LoginUID) for all security events. LoginUID survives privilege escalation via `sudo` or `su`, enabling non-repudiation for privileged actions. **Why it matters:** When a user runs `sudo command`, the effective user changes to root, but the LoginUID remains the original user. This allows LinuxGuard to attribute actions to the actual person responsible, even when sudo is involved. **Example attribution:** A file event shows `ubuntu (sudo -> root)` indicating: * **Original login user:** ubuntu * **Effective user after sudo:** root This is critical for security investigations: distinguishing "root logged in directly" from "user X used sudo to become root" provides accountability for privileged actions. LinuxGuard captures LoginUID directly at the kernel level rather than through a later process-table lookup, which avoids race conditions where a short-lived process could otherwise exit before its identity was queryable. > **Note**: Kernel 5.5 or later is required for full eBPF userspace argument reads. On older kernels (4.18-5.4), LoginUID capture may have reduced reliability. See [Glossary](/reference/reference/glossary) for the LoginUID definition. ### eBPF File Access Monitoring LinuxGuard uses eBPF to monitor file access at the kernel level, providing real-time visibility into file read and write access across monitored paths. **How it works:** 1. eBPF-based tracing captures each file open at the point of access, before the process can exit or hide its activity 2. Each file open operation is captured with: file path, process ID, user ID, command name, and open flags (read/write intent) 3. Write events are correlated with the corresponding filesystem change to provide high-confidence process attribution 4. Read events enable exfiltration detection by identifying processes reading monitored files **Attribution confidence levels:** | Level | Source | When Used | | ------ | ------------------------- | ----------------------------------------------------------------------- | | HIGH | eBPF kernel-level tracing | eBPF successfully captures process context at the moment of file access | | MEDIUM | /proc lookup | Kernel-level event received but supplemented with /proc/\[pid] data | | LOW | Fallback | Process exited before attribution could be completed | eBPF-based attribution provides the highest confidence because it captures process information at the kernel level, before the process can exit or change state. See [Console Overview](/concepts/concepts/console) for how attribution levels appear in the File Monitoring page, and [Glossary](/reference/reference/glossary) for related terms. ### Configuration File Write Detection LinuxGuard detects writes to security-critical configuration files in real time, generating a security signal with full process attribution as soon as an unauthorized change is made. **Monitored files:** | Category | Files | | --------------------- | ---------------------------------------------------------- | | Privilege escalation | `/etc/sudoers`, `/etc/sudoers.d/*` | | Authentication | `/etc/ssh/sshd_config`, `/etc/pam.d/*`, `/etc/security/*` | | User/group management | `/etc/passwd`, `/etc/group`, `/etc/shadow`, `/etc/gshadow` | | SSH access | `~/.ssh/authorized_keys` (all users) | **Why it matters:** Unauthorized modifications to these files are common persistence and escalation techniques: * Adding a sudoers rule grants an attacker root access * Modifying `sshd_config` can weaken SSH security * Adding entries to `authorized_keys` creates a backdoor * Changing `/etc/passwd` or `/etc/shadow` can create unauthorized accounts Each signal includes the process name, full command line, working directory, and LoginUID for complete attribution of who made the change. > **Important**: Configuration File Write Detection may not be visible until enabled by your LinuxGuard administrator. Contact support to enable this feature. See [Glossary](/reference/reference/glossary) for the Configuration File Write Detection definition. ## Linux Capabilities Linux capabilities split root privileges into discrete units. LinuxGuard uses only the specific capabilities needed for monitoring, avoiding broad privileges like CAP\_SYS\_ADMIN. ### Capabilities Used | Capability | Purpose | Why Needed | | ---------------------- | ---------------------------- | ------------------------------------------------------------------------------------- | | CAP\_BPF | Load eBPF programs | Attach monitoring programs to kernel hooks | | CAP\_PERFMON | Performance monitoring | Access performance counters for security monitoring | | CAP\_DAC\_READ\_SEARCH | Read file permissions bypass | Read authentication logs and scan files for security analysis regardless of ownership | | CAP\_AUDIT\_READ | Read audit logs | Access kernel audit events for security monitoring | ### Capabilities NOT Used LinuxGuard deliberately avoids broad capabilities: * **CAP\_SYS\_ADMIN** - Full administrative access; too broad for monitoring purposes * **CAP\_NET\_ADMIN** - Network configuration; not needed for read-only monitoring * **CAP\_SYS\_PTRACE** - Process tracing; not needed for eBPF-based monitoring This capability model follows the principle of least privilege: the agent has only the specific capabilities required for its monitoring function, nothing more. ## Systemd Hardening LinuxGuard's systemd service includes hardening directives that restrict what the agent can do, even if compromised. These directives provide defense-in-depth beyond the agent's own security model. ### Hardening Directives | Directive | Protection | What It Prevents | | -------------------------- | ------------------------ | ----------------------------------------- | | ProtectSystem=strict | Read-only filesystem | Agent cannot modify system files | | PrivateTmp=true | Isolated /tmp | Cannot access other processes' temp files | | ProtectHome=true | No home directory access | Cannot access user home directories | | NoNewPrivileges=true | No privilege escalation | Cannot gain additional capabilities | | ProtectKernelTunables=true | Read-only /proc and /sys | Cannot modify kernel parameters | ### Verify Hardening You can inspect the actual hardening configuration: ```bash # View the complete service configuration systemctl cat linuxguard-agent # Check systemd security score (lower is better) systemd-analyze security linuxguard-agent ``` The `systemd-analyze security` command scores services based on their hardening. A score under 5.0 indicates a well-hardened service. ## Package Integrity ### RPM Package Signing LinuxGuard signs all RPM packages with a GPG key. When DNF or YUM installs or updates the `linuxguard-agent` package, the package manager verifies the signature against the LinuxGuard GPG key before installing any files. **What this provides:** * **Origin verification** — The package was built and signed by LinuxGuard, not a third party * **Tamper detection** — Any modification to the package after signing invalidates the signature, and the package manager rejects installation **Key details:** The LinuxGuard GPG public key is imported to the host at repository setup time: * **Key location on host:** `/etc/pki/rpm-gpg/RPM-GPG-KEY-linuxguard` * **Key source URL:** `https://packages.linuxguard.io/dnf/packages/repodata/RPM-GPG-KEY-linuxguard` * **Repository setting:** `gpgcheck=1` in the LinuxGuard DNF/YUM repository configuration With `gpgcheck=1`, DNF and YUM will refuse to install any package whose signature does not verify against the imported key. This applies to every install and every update. > **Note**: GPG signature verification applies to RPM packages (RedHat, CentOS, SUSE distributions). See the [RedHat / CentOS installation guide](/install/install/redhat-centos) for repository setup instructions. ## What LinuxGuard Does NOT Do LinuxGuard is designed with explicit limitations. Understanding what the agent deliberately does not do is as important as understanding what it does. ### Does not modify system files * No changes to `/etc/`, `/usr/`, or other system directories * All writes limited to `/var/lib/linuxguard/` and `/var/log/linuxguard/` * Configuration changes require administrator action, not agent action ### Does not install kernel modules * Uses eBPF, not loadable kernel modules * Cannot crash the kernel or cause kernel panics * Does not require kernel rebuilds or module signing ### Does not require persistent root access * Root/sudo used only during installation * Runtime uses the unprivileged `linuxguard` user * No sudo rules or SUID binaries required ### Does not intercept or modify network traffic * Read-only network monitoring * No proxy functionality * No firewall rules or traffic modification * No man-in-the-middle capabilities ### Does not collect or transmit without consent * Only enrolled agents send data to the LinuxGuard console * Unenrollment stops all data transmission immediately * No background data collection before enrollment ### Does not act without explicit operator configuration * Response actions (account lock, session termination, SSH key disable, sudo revocation) only fire when a playbook is explicitly created, scoped to specific server groups, and enabled by an operator * No automated response occurs on any server until a playbook targeting that server's group is enabled * The monitoring agent collects and reports telemetry at all times; automated response is a separate, explicitly-configured capability that is disabled by default ## How LinuxGuard Compares Security teams evaluating LinuxGuard often compare it to other agent architectures. This section provides factual comparison across three categories: kernel module agents, userspace-only agents, and cloud-native security tools. ### vs Kernel Module Agents Traditional security agents use loadable kernel modules for deep visibility into system activity. While effective, this approach carries inherent risks. | Aspect | Kernel Module Agent | LinuxGuard (eBPF) | | -------------------- | ---------------------------------- | --------------------------------- | | Kernel crash risk | Module bugs can panic kernel | eBPF programs cannot crash kernel | | Kernel compatibility | Requires module per kernel version | Portable across kernels 4.18+ | | Update impact | May require reboot | Hot-reload without reboot | | Code verification | None before load | Built-in eBPF verifier | LinuxGuard's eBPF approach provides equivalent visibility with the kernel's built-in safety guarantees. If an eBPF program contains an error, the kernel rejects it before execution rather than risking system instability. ### vs Userspace-Only Agents Some security agents operate entirely in userspace, avoiding kernel integration to minimize risk. | Aspect | Userspace-Only Agent | LinuxGuard (eBPF) | | ----------------- | ---------------------- | ----------------------------- | | Kernel visibility | Limited to /proc, logs | Direct kernel event stream | | Detection latency | Polling-based delays | Real-time event capture | | Resource overhead | Higher CPU for polling | Efficient in-kernel filtering | Userspace-only agents cannot see kernel events as they happen. They rely on polling system files or parsing logs, which introduces delays and increases CPU usage. LinuxGuard's eBPF programs run inside the kernel, capturing events at the source with minimal overhead. ### vs Cloud-Native Security Tools Container-focused security tools (like those using eBPF for Kubernetes security) share many of eBPF's benefits but target different use cases. | Aspect | Cloud-Native Tools | LinuxGuard | | ------------- | -------------------------- | ------------------------- | | Primary focus | Container/K8s security | Host-level security | | Deployment | DaemonSet/Sidecar | System package | | Scope | Pod-centric policies | Server-centric monitoring | | Integration | K8s API, admission control | Audit system, systemd | Cloud-native tools excel at container workload protection and Kubernetes policy enforcement. LinuxGuard focuses on host-level security monitoring across physical servers, virtual machines, and the underlying infrastructure that containers run on. ## Security Q\&A Common questions from security teams evaluating LinuxGuard. ### Does LinuxGuard need root? **For installation:** Yes. Creating the `linuxguard` user, installing files to system directories, and registering the systemd service requires root or sudo access. **For runtime:** No. The agent runs as the unprivileged `linuxguard` user. Root access is not required for normal operation after installation. ### What kernel access does it have? LinuxGuard uses eBPF to monitor kernel events. eBPF programs are: * Verified by the kernel before loading * Unable to access arbitrary kernel memory * Unable to modify kernel state * Running in a sandboxed environment The agent observes kernel activity but cannot change kernel behavior. ### Can the agent be compromised? Any software can theoretically be compromised. LinuxGuard employs defense-in-depth to limit the impact of a potential compromise: 1. **Least privilege** - Runs as non-root with minimal Linux capabilities 2. **Systemd hardening** - NoNewPrivileges, ProtectSystem, PrivateTmp restrict what the process can do 3. **eBPF sandboxing** - Even eBPF code is verified and sandboxed by the kernel 4. **Network encryption** - All API communication uses HTTPS 5. **Automatic updates** - Security patches delivered via package manager If the agent process were compromised, the attacker would have: * Access limited to linuxguard-owned directories (`/var/lib/linuxguard/`, `/var/log/linuxguard/`) * No ability to escalate privileges (NoNewPrivileges=true) * Read-only access to system files (ProtectSystem=strict) * No network configuration capabilities ### What data does LinuxGuard collect? LinuxGuard collects security-relevant telemetry: * Process execution events (what programs run, who runs them) * File access events (what files are read, written, modified) via eBPF-based file monitoring * Network connection events (what connections are established) * Authentication events from syslog, journald, and utmp/wtmp/btmp logs (login successes, failures, brute force detection) * Audit log events (kernel audit subsystem data) * System resource metrics (CPU, memory, disk, network utilization via `sysstat`) * User behavior baselines for anomaly detection LinuxGuard does **not** collect: * File contents (only metadata: path, timestamps, hashes, permissions) * Keystrokes or screen captures * Personal data beyond process metadata * Data before enrollment (agent must be enrolled to transmit) ## Verification Commands Verify LinuxGuard's security configuration yourself. Each command includes expected output. ### Check agent runs as non-root ```bash ps aux | grep linuxguard-agent ``` **Expected:** Process shows `linuxguard` user in the first column, not `root`. ### View systemd hardening configuration ```bash systemctl cat linuxguard-agent ``` **Expected:** Shows hardening directives including `ProtectSystem=strict`, `NoNewPrivileges=true`, `PrivateTmp=true`. ### Check systemd security score ```bash systemd-analyze security linuxguard-agent ``` **Expected:** Overall exposure level under 5.0 indicates a well-hardened service. Lower scores mean more restrictions are in place. ### Verify file permissions ```bash ls -la /etc/linuxguard /var/lib/linuxguard ``` **Expected:** Directories owned by `linuxguard:linuxguard` with restrictive permissions (750 or similar). ### Verify agent user has no login shell ```bash getent passwd linuxguard ``` **Expected:** Shell field shows `/usr/sbin/nologin` or `/bin/false`, preventing interactive login. ### Check agent user exists with correct properties ```bash id linuxguard ``` **Expected:** Shows uid, gid, and groups for the linuxguard system account. ## Directory Structure and Permissions The installer creates a secure directory structure with appropriate ownership and permissions: **Agent-Owned Directories** (read-write access): * `/etc/linuxguard/` - Agent configuration files * `/var/lib/linuxguard/` - Agent state and data files * `/var/run/linuxguard/` - Runtime files and process information * `/var/log/linuxguard/` - Agent log files All agent-owned directories are: * Owned by the `linuxguard` user and group * Protected with restrictive permissions (750 or 755) * Isolated from other system components **System Component Access** (read-only access): * The agent requires read-only access to certain system components for monitoring purposes * This includes system logs, configuration files, and audit data * Read access is granted only where necessary for security monitoring functionality * The agent cannot modify any system files or configurations ## Dedicated User Account The installer creates a dedicated `linuxguard` user and group specifically for running the agent. This user account: * Has no login shell (cannot be used for interactive access) * Is a system account (not intended for human users) * Operates with minimal system privileges * Is isolated from other system processes and users ## Audit System Integration LinuxGuard integrates with the Linux audit system (auditd) to provide comprehensive security monitoring. The installer: * Installs audit rules that define what events to monitor * Creates a dedicated audit group (`linuxguard-audit`) for accessing audit logs * Configures the audit daemon to allow the agent to read audit logs securely * Ensures audit logs are accessible without requiring root privileges This integration allows LinuxGuard to monitor system calls, file access, network activity, and other security-relevant events without running with elevated privileges. ## Service Management The agent runs as a system service under the `linuxguard` user account. The installer: * Registers the agent as a system service (systemd or OpenRC, depending on your distribution) * Configures the service to start automatically on system boot * Ensures the service runs with the correct user permissions * Provides standard service management capabilities (start, stop, restart, status) ## Runtime Security Once installed and running, the LinuxGuard agent: * **Runs as non-root**: All agent processes execute under the `linuxguard` user account * **Read-only monitoring**: Monitors system activity with read-only access to system components * **Isolated data**: Stores all agent data in dedicated directories with restricted access * **Secure communication**: All communication with the LinuxGuard console uses encrypted HTTPS connections * **No system modifications**: The agent never modifies system files, configurations, or other components outside its own directories ## Security Benefits This security model provides several key benefits: 1. **Reduced Attack Surface**: By running without root privileges, the agent cannot be used to escalate privileges or compromise the system 2. **Compliance**: The least-privilege model helps meet security compliance requirements 3. **Isolation**: Agent processes and data are isolated from other system components 4. **Transparency**: Clear separation between agent operations and system operations 5. **Auditability**: The agent's own operations can be monitored and audited like any other system process ## Best Practices When deploying LinuxGuard in your environment: * **Review permissions**: Periodically review the agent's file permissions to ensure they remain restrictive * **Monitor agent activity**: Use your existing security monitoring to track agent behavior * **Keep updated**: Regularly update the agent to receive security patches and improvements * **Network security**: Ensure network policies allow the agent to communicate with `api.linuxguard.io` over HTTPS * **Audit logs**: Review agent logs regularly to ensure normal operation *** **Related**: [Installation](/install/install) | [Console Overview](/concepts/concepts/console) | [Glossary](/reference/reference/glossary) | [Troubleshooting](/troubleshooting) # Active Response How LinuxGuard's active-response model executes automated containment actions with triple opt-in safety and audited rollback. Active response is LinuxGuard's automated containment capability: when a monitored identity exhibits behaviour matching a configured trigger condition, the platform can execute targeted containment actions on that identity across the affected servers — without waiting for manual intervention. What distinguishes active response from simple alerting is its safety model: the system is designed so that automated action is structurally impossible unless every layer of the configuration has been explicitly set up to allow it. ## Safety Model The safety model establishes the conditions under which automated response can occur. Understanding these conditions before configuring any playbook provides the confidence that response commands execute precisely where intended — and cannot fire outside that boundary. ### Triple Opt-In Active response requires three independent conditions to be satisfied simultaneously. Each layer represents a deliberate architectural decision that prevents a specific class of accidental execution: **Layer 1 — Playbook enabled with trigger conditions configured.** A playbook must be explicitly enabled and must have at least one trigger condition (a signal type, severity threshold, and identity type match) set before any response can fire. This ensures that tenants which have not deliberately activated automated response are never affected, even if signals matching the playbook's pattern are observed. **Layer 2 — Server group membership.** A playbook's scope is defined at configuration time by one or more server groups. At runtime, the playbook can only act on servers that belong to those groups. The scope boundary is fixed — it cannot be extended by a signal, an operator action, or any runtime condition. A playbook scoped to a staging server group cannot act on production servers, regardless of what signals fire. **Layer 3 — Agent-level response flag.** Each agent has an individual `response_enabled` flag. Even when Layer 1 and Layer 2 conditions are fully satisfied, a command issued to an agent with this flag disabled will sit in QUEUED state until it times out. No action is taken on that host. This allows operators to opt individual hosts in or out of automated response independently of their group membership. **Exclusion list.** At the playbook level, specific identities can be excluded from automated response entirely regardless of what signals they generate. Common exclusions include service accounts performing scheduled tasks, break-glass emergency accounts, and monitoring infrastructure agents. An excluded identity matching a trigger condition generates the alert signal but receives no containment command. **Audit trail.** Every response command is recorded with the full context of why it fired: the identity that was acted upon, the action taken, the triggering signal, the timestamp, and the pre-action state of the affected resource. The audit trail uses a chain hash to ensure integrity — records cannot be altered after the fact. > **Note**: Before enabling response at scale, you can configure a playbook scoped to a single non-critical test account. Observe the trigger behaviour and response execution in the Active Responses page before expanding scope. ### Blast Radius A playbook's scope — the server groups it can act on — is set at configuration time. This is a design property of how playbooks work, not a runtime safety net: a playbook simply has no mechanism to act outside its configured scope. In addition to scope, the system enforces built-in execution limits as system properties. These are not configurable console settings: * **Maximum 10 commands per server per hour** — prevents a single host from receiving a high volume of commands in a short window * **Maximum 50 distinct servers per playbook execution window** — bounds the number of hosts a single playbook execution can affect * **Maximum 5 concurrent tenant-wide commands** (commands in QUEUED, DISPATCHED, or EXECUTING state combined) — limits overall response activity across the tenant at any moment A **circuit breaker** provides an additional safeguard: if a playbook's failure rate exceeds 20% across five or more commands within a 15-minute window, the playbook is automatically disabled. This prevents a misconfigured or partially failing playbook from continuing to issue commands when the success rate indicates a systemic problem. ### Rollback Most containment actions are temporary by design. Two rollback mechanisms ensure that containment state does not persist beyond its useful window. **Automatic timeout-based rollback.** The system polls completed commands on a five-minute cycle and automatically reverses eligible actions when their configured rollback window expires. The system default is four hours from command completion. Eligible actions are: lock account, disable SSH key, and revoke sudo. Automatic rollback is recorded in the audit trail with the initiator identity `system:auto_rollback`. Kill sessions does not support automatic rollback. Terminated sessions cannot be restored — there is no session state to recover. **Manual console rollback.** An operator can trigger rollback for any completed, eligible action directly from the Active Responses page. Manual rollback is available once per original action — a second rollback of the same command is not permitted. The rollback is linked to the original command in the audit trail with the operator's identity as initiator. ## Playbooks A playbook is a named, scoped policy that connects a trigger condition to one or more containment actions. Its configuration elements are: * **Trigger conditions** — a combination of signal type, severity threshold, and identity type that causes the playbook to fire * **Server group scope** — the set of server groups the playbook can act on (fixed at configuration time) * **Containment actions** — one or more of the four available actions, optionally including notifications * **Exclusion list** — identities that are never acted on by this playbook * **Auto-rollback timeout** — the window after which eligible containment actions are automatically reversed (system default: four hours) Playbooks are created and configured in the **Zero Trust Enforcement** section of the console. In addition to containment actions, playbooks can also trigger notifications — alerting a security operations channel without taking containment action, or in combination with containment. See [Notification Rules](/respond/respond/notification-rules) for setup instructions. ## Containment Actions Four containment actions are available. Each is a targeted operation on a specific identity on a specific set of servers within the playbook's server group scope. ### Lock Account **What it does:** Disables the account's password authentication by locking the account (`usermod -L`). The account continues to exist but cannot authenticate using a password. Existing sessions are not affected — only new password-based authentication attempts are blocked. **Rollback:** The action is reversed automatically at the rollback timeout, or manually from the console. Reversal restores the account to its pre-action state. If the account was already locked before the response fired, the rollback does not unlock it — the pre-action state was locked, and that state is preserved. **Scope:** Acts on the named account on each server within the playbook's server group scope. ### Kill Sessions **What it does:** Terminates all active sessions for the identity on every server in scope — not only the session that triggered the signal. The operation uses `loginctl terminate-user` with a `pkill` fallback for robustness across distributions. **Rollback:** There is no rollback for kill sessions. Terminated sessions cannot be restored. Kill sessions is not eligible for automatic or manual rollback. **Scope note:** Because kill sessions acts across all servers in scope rather than just the triggering server, it has a higher default severity threshold than other containment actions. This reflects the broader reach of the operation. ### Disable SSH Key **What it does:** Disables the specific SSH public key that triggered the signal in the identity's `authorized_keys` file. The key entry is marked as disabled rather than deleted, preserving the original file state for accurate rollback. **Rollback:** Automatic rollback at the timeout restores the original `authorized_keys` contents. Manual rollback is also available from the console. Reversal restores the exact pre-action state of the file. **Scope:** Acts on the named SSH key for the named identity on each server in the playbook's server group scope. ### Revoke Sudo **What it does:** Installs a deny rule in `sudoers.d` that prevents the identity from using `sudo`. The deny file passes a `visudo` syntax check before being installed atomically, ensuring no partial or malformed sudoers state is left on the host. **Rollback:** Automatic or manual rollback removes the deny file. Reversal only removes the file that was installed by this action — if the identity had no sudo access before the response fired, the state after rollback is unchanged. > **Important**: Revoke sudo is only available when a sudo policy is configured for the identity. If no sudo policy exists for the identity, this action has no effect. ## Active Responses Page The **Active Responses** page in the Zero Trust Enforcement section of the console provides a real-time view of all response commands — past and present — across the tenant. **In-flight commands.** A command is in-flight when it is in QUEUED, DISPATCHED, or EXECUTING state: * **QUEUED** — the command has been issued by the platform and is waiting to be picked up by the agent. If the agent's `response_enabled` flag is off, the command remains QUEUED until it times out. * **DISPATCHED** — the agent has acknowledged the command and is preparing to execute. * **EXECUTING** — the operation is actively running on the host. **Pending rollback window.** COMPLETED commands for actions with an active auto-rollback window also appear as active in the page. These commands have completed their containment action but have not yet been automatically reversed — they will be rolled back when the configured timeout expires. **History.** All commands — completed, failed, timed out, and rolled back — appear in the history view with their full lifecycle timestamps, the initiator identity, the signal that triggered the playbook, and any linked rollback commands. **Status tracking.** Each entry shows the full lifecycle state (QUEUED → DISPATCHED → EXECUTING → COMPLETED, FAILED, or TIMED\_OUT), the identity acted upon, the target server, the action type, and the linked rollback command if one exists. *** **Related**: [Security Architecture](/concepts/concepts/security-architecture) | [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) # Alerting & SIEM Integration How LinuxGuard routes security signals to webhook, syslog, and Splunk HEC delivery channels via notification rules. LinuxGuard routes security signals to external alerting and SIEM destinations through a delivery system built on two components: delivery channels and notification rules. A delivery channel is a configured connection to a specific destination — a webhook endpoint, a syslog receiver, or a Splunk HTTP Event Collector. A notification rule is the routing layer that connects signals to one or more channels, applying conditions to select which signals are delivered, and optional throttle and quiet hours controls to manage delivery volume and timing. ## Delivery Channels Three delivery channel types are available. Choose based on your existing alerting infrastructure: **Webhook** — delivers a structured JSON payload to any HTTPS endpoint via HTTP POST. Use webhooks when you have a custom receiver, an automation platform (such as a SOAR or ticketing system), or any service that accepts HTTP callbacks. LinuxGuard signs every request with HMAC-SHA256 so the receiving system can verify authenticity. See [Webhook Integration](/respond/respond/webhook-integration) for setup and signature verification guidance. **Syslog** — forwards signals as standard syslog messages to any receiver that accepts UDP, TCP, or TLS connections. Syslog is the broadest-compatibility option: virtually every SIEM, log aggregator, and log management system accepts syslog input. Both RFC 3164 and RFC 5424 formats are supported. RFC 5424 is recommended for structured environments because it preserves signal metadata in structured data elements. See [Syslog Forwarding](/respond/respond/syslog-forwarding) for protocol, format, and TLS configuration. **Splunk HEC** — delivers signals directly to the Splunk HTTP Event Collector using the native HEC JSON format. Use this channel in Splunk-native environments where signals should appear with a consistent sourcetype in your Splunk index. See [Splunk HEC Integration](/respond/respond/splunk-hec-integration) for token configuration and event field reference. ## Notification Rules A notification rule defines when and where signals are delivered. When a signal is created, the platform evaluates each enabled notification rule in turn. If a rule's conditions match the signal, the platform delivers the signal to every channel configured on that rule. Conditions use AND logic: all configured conditions on a rule must match the signal for the rule to fire. A rule can filter by signal severity, category, agent environment, agent tag, or identity type — or any combination of these. A rule with no conditions configured matches every signal. This is a deliberate design choice: an unconditioned rule is the simplest way to forward all signals to a SIEM destination for ingestion and correlation. See [Configure Notification Rules](/respond/respond/notification-rules) for the full conditions reference and setup steps. ## Throttle Throttle limits the number of deliveries a rule makes within a time window. It protects receiving systems from high signal volumes during incident peaks and reduces noise when many signals of the same type fire in quick succession. Two throttle patterns are available: a simple per-hour cap (`max_per_hour`) and a flexible period-based cap (`max_per_period` combined with `period_minutes`). Throttle is configured per rule, so different rules can have different delivery rate limits. Signals that exceed the throttle limit for a rule are not delivered for that rule during the current window. ## Quiet Hours Quiet hours define a daily time window during which a rule suppresses signal delivery. Configure quiet hours when a rule targets an on-call channel and you want to avoid non-urgent notifications during off-hours. The window is specified as start and end times in `HH:MM` format, and all times are evaluated in UTC. Overnight windows — where the start time is later than the end time — are supported. An optional `critical_bypass` flag allows critical-severity signals to be delivered even during the quiet window, ensuring that the highest-severity events are never silently suppressed. *** **Related**: [Configure Notification Rules](/respond/respond/notification-rules) | [Webhook Integration](/respond/respond/webhook-integration) | [Syslog Forwarding](/respond/respond/syslog-forwarding) | [Splunk HEC Integration](/respond/respond/splunk-hec-integration) # Console Overview of the LinuxGuard console — the v3.0 five pillars plus v4.0 expanded pillars (Baselines, Efficiency, Audit, Integrations, Posture, Notifications). The LinuxGuard console organizes security, compliance, configuration, and operational surfaces into pillars accessible from the left sidebar. The v3.0 release shipped six pillars (Dashboard, Identity Intelligence, Zero Trust Enforcement, Compliance & Audit, Infrastructure, What Changed). v4.0 adds eight new pillars covering baseline management, efficiency analysis, privileged-action audit, expanded compliance and Zero Trust program surfaces, integrations, cross-cutting posture views, and notifications. Pillars with module assignments are only visible to tenants with the corresponding module license; tenants without an entitled module see an upgrade prompt in place of that pillar's content. Settings, accessible below the pillar navigation, provides API key management, alert routing, and behavioral analytics configuration. ## What's in this section ### v3.0 pillars * [**Dashboard**](/concepts/concepts/console/dashboard) — Identity risk score, fleet posture, top identity risks, and critical findings feed. * [**Identity Intelligence**](/concepts/concepts/console/identity-intelligence) — Cross-server identity profiles, risk scoring, SSH keys, NHI inventory, and access patterns. * [**Zero Trust Enforcement**](/concepts/concepts/console/zero-trust-enforcement) — Signals with MITRE mapping, config drift attribution, SUDO policy analysis, file monitoring, and findings. * [**Compliance & Audit**](/concepts/concepts/console/compliance-audit) — Framework scores, history, suppressions, audit logs, and reports. * [**Infrastructure**](/concepts/concepts/console/infrastructure) — Fleet inventory, server detail tabs, efficiency, and baseline configuration. * [**What Changed**](/concepts/concepts/console/whats-changed) — Mapping from the old flat section list to the 5-pillar model. ### v4.0 new pillars * [**Baselines**](/concepts/concepts/console/baselines) — Known-good snapshots of accounts, groups, SSH/SSHD config, and SUDO with drift detection. * [**Efficiency**](/concepts/concepts/console/efficiency) — Rightsizing, storage, network IO, JVM, waste assessment, labor savings, and reports. * [**Audit**](/concepts/concepts/console/audit) — Authorizations audit and SUDO execution audit for privileged-action reconciliation. * [**Compliance Expansion**](/concepts/concepts/console/compliance-expansion) — Frameworks browser, evidence collection, history, reports, suppressions; evidence-location reference for per-framework pages. * [**Integrations**](/concepts/concepts/console/integrations) — JIRA, Teams, Slack, Syslog, SIEM, generic webhooks, and per-integration deliveries. * [**Zero Trust Expansion**](/concepts/concepts/console/zero-trust-expansion) — Policies, findings, playbooks, active responses history, SUDO policies/executions, SELinux, and policy violations. * [**Posture**](/concepts/concepts/console/posture) — Cross-cutting Compliance / Configuration / Health posture with per-server ranking. * [**Notifications**](/concepts/concepts/console/notifications) — Notification rules, suppressions, and rule edit/new flows. *** **Related**: [Security Architecture](/concepts/concepts/security-architecture) | [Active Response](/concepts/concepts/active-response) | [Alerting & SIEM Integration](/concepts/concepts/alerting) | [Glossary](/reference/reference/glossary) # Dashboard The LinuxGuard console Dashboard — identity risk score, fleet posture, top identity risks, and findings feed. The Dashboard provides an identity-centric view of fleet security posture, surfacing the highest-risk identities, critical findings, and module-gated security metrics. ## Identity Risk Score The Identity Risk Hero widget occupies the top of the Dashboard. It displays the fleet-wide identity risk score, highest risk first, alongside a trend line showing how that score has changed over recent periods. Below the score, a breakdown shows the proportion of identities by type: Human, Service, and Dormant. This score reflects identity-level risk signals across the fleet, not server posture or uptime. The Environment and Tag selectors at the top of the page apply to all Dashboard widgets. Changing the environment or tag filter narrows every widget — including the identity risk score, summary cards, and the findings feed — to the selected subset of the fleet. ## Top Identity Risks Three summary cards sit below the identity risk score, each highlighting a specific risk dimension: **Who can root** shows the count of identities across the fleet that have a path to root access — through direct UID 0 membership, SUDO rules, group membership in privileged groups, or other mechanisms. A high count indicates broad privilege exposure. **Privilege drift** captures changes in privilege scope over the measured period — identities that gained or lost elevated access, new SUDO rules added, and group membership changes that affect privileged access. Unexpected upward drift warrants investigation. **SSH exposure** surfaces the SSH key risk signal across the fleet: keys with weak algorithms, keys authorized on multiple servers, and orphaned keys associated with accounts that no longer exist. ## Critical Findings Feed The Critical Findings Feed is a chronological, auto-refreshing stream of the highest-priority findings from across all pillars. It draws from four sources simultaneously: security signals from Zero Trust Enforcement, configuration drift events, compliance control failures, and identity risk events. Findings appear in a unified view regardless of which pillar generated them, making it the fastest place to see what requires immediate attention. ## Module-Gated Sections Professional and Enterprise tenants see additional sections below the Critical Findings Feed that are not present on the Starter tier: The **Zero Trust section** shows an activity summary for signals detected in the current period, a drift event count with severity breakdown, and an SSH key health summary across the fleet. The **Compliance section** shows pass/fail scores for each enabled compliance framework. Scores reflect the current state of enrolled servers against each framework's control requirements. The **Response Summary Widget** appears when the zero-trust module is present. It shows active response commands currently in flight and a log of recently completed response actions. Starter tier tenants see an expanded Identity Risk Hero widget with additional findings in the Critical Findings Feed in place of these sections. > **Note**: Module-gated sections display an upgrade prompt for tenants without the required module license. The Dashboard structure adapts to the modules enabled on your account — sections that require an unentitled module are replaced with information about enabling that module. *** **Related**: [Console Overview](/concepts/concepts/console) | [Identity Intelligence](/concepts/concepts/console/identity-intelligence) | [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) | [Compliance & Audit](/concepts/concepts/console/compliance-audit) # Identity Intelligence Identity Intelligence pillar in the LinuxGuard console — cross-server identity profiles, risk scoring, SSH keys, and access patterns. Identity Intelligence aggregates identity data across all monitored servers into unified profiles with cross-server risk scoring, behavioral baselines, and non-human identity inventory. The pillar contains six pages accessible from the left sidebar: **Identity Overview**, **Accounts**, **Groups**, **Non-Human Identities**, **SSH Keys**, and **Access Patterns**. This page walks through each sub-section, explaining what it shows, how risk signals are surfaced, and how to interpret the data. ## Identity Overview The Identity Overview page (`/identity`) is the entry point to the Identity Intelligence pillar. It presents a fleet-wide view of all identities — human and service — aggregated across every monitored server. **Five metric cards** appear at the top of the page, each clickable to cross-filter the identity table below: * **Total** — all identities discovered across the fleet * **Human** — accounts classified as human users * **Service** — accounts classified as service accounts * **Dormant** — accounts with no recent activity * **High Risk** — accounts flagged as high risk by their fleet-wide score Clicking a card filters the table to show only matching identities. Hold Ctrl or Cmd and click additional cards to build a multi-category selection. The **identity table** is sorted by risk score in descending order by default, placing the highest-risk identities first. Each row represents a single identity aggregated across all servers where that identity appears — not a per-server row. The table supports search, paginates at 25 items per page, and offers CSV export. **Risk scoring** is a cross-server composite — LinuxGuard evaluates each identity's profile across every server it appears on and produces a single fleet-wide score. Identities crossing the high-risk threshold get the High Risk classification. **Use case:** Identify your highest-risk human accounts fleet-wide, regardless of which servers they log into. An account whose risk adds up across several servers will surface near the top before a per-server review would catch it. ## Accounts The Accounts page (`/identity/accounts`) provides a complete inventory of all accounts across the fleet in an identity-centric view. One row represents one identity, with data aggregated across all servers where that account exists — not one row per server instance. Key columns include username, type (human or service), risk score, server count, last seen date, and status. The status column surfaces dormancy detection — accounts that have not authenticated recently appear as dormant. The table defaults to risk score descending, showing the most concerning accounts first. Use this page to audit which accounts exist fleet-wide, verify whether expected accounts are present across the right servers, and spot accounts that have gone dormant but remain active. ## Groups The Groups page (`/identity/groups`) shows group memberships across the fleet with cross-server correlation. A group that exists on multiple servers appears as a single entry with a server count column rather than duplicated per-server rows. This view is useful for identifying groups with unexpectedly broad server presence or unusual membership composition. A group appearing on 30 servers where you expected 5, or a group that has gained new members without an accompanying change ticket, becomes visible here. ## Non-Human Identities Non-Human Identities (NHI) are Linux user accounts that run automated processes rather than interactive human sessions. LinuxGuard links each NHI account to the automated work it performs, so you can see what a service account is actually doing across the fleet. LinuxGuard auto-sorts every non-human identity into one of three tiers based on where the account came from. **System Default** accounts are created by the operating system or system packages during installation. These accounts are expected, low-churn, and rarely change after initial provisioning. When a system default account shows unexpected credential aging or configuration changes, it signals potential system-level compromise. **Application Service** accounts are created by well-known third-party software during package installation. Package managers typically manage these accounts, so their lifecycle is usually predictable. The primary risk here is credential rotation compliance: application service accounts frequently hold SSH keys used by deployment pipelines, and stale keys in those pipelines can persist long after a rotation policy requires remediation. **Custom Service** accounts are everything your organization created for specific automation purposes that does not match the system or application lists. These are your homegrown automation accounts, cron runners, and pipeline service accounts. Custom Service accounts carry the highest operational risk because there is no shared knowledge base: you must verify their purpose, confirm an owner, and establish a credential lifecycle yourself. **Six metric cards** appear at the top of the NHI page, cross-filtering the table: * **Total NHIs** — all non-human identities across the fleet * **System Default** — count of OS/system-package accounts * **Application Service** — count of well-known third-party service accounts * **Custom Service** — count of organization-defined automation accounts * **Unowned** — NHIs with no owner assigned; shows a grace period subtitle when any newly discovered NHIs are still within their grace period before appearing as unowned * **Stale Credentials** — NHIs whose SSH keys or credentials require rotation A **classification donut chart** shows the proportion of System Default, Application Service, and Custom Service accounts. Clicking a segment filters the table. The **NHI table** has eight columns: name, classification, risk level, server count, credential age in days, a freshness indicator (fresh, warning, or critical), owner, and last seen. Available filters include account type, risk level, owner status (yes or no), search, minimum server count, and maximum credential age. **Risk factors** for NHIs are credential age, owner assignment, and grace period status. A Custom Service account with no owner, stale credentials, and high server count represents the highest-priority remediation target. ## SSH Keys The SSH Keys page (`/identity/ssh-keys`) provides fleet-wide visibility into all SSH keys discovered across monitored servers, with classification by algorithm strength, age, and cross-server presence. **Five metric cards** appear at the top, cross-filtering the table: * **Total Keys** — all SSH keys discovered fleet-wide * **User Keys** — `authorized_keys` entries (user-type keys) * **Host Keys** — server host keys * **Inactive (>90d)** — keys not observed in the last 90 days * **Shared** — keys whose fingerprint appears in `authorized_keys` on multiple server accounts Two **charts** follow the metric cards: an algorithm distribution donut showing the proportion of key types across the fleet, and a key age histogram displaying how many keys fall into each age bucket with severity coloring. ### Algorithm Strength LinuxGuard grades each SSH key by algorithm strength — Critical, Weak, Acceptable, or Strong — with matching severity coloring, so the weakest keys in your fleet are easy to spot. Deprecated or undersized algorithms grade low; modern algorithms grade Strong. ### Key Age LinuxGuard assigns each key an age bucket — from Fresh to Stale — so keys overdue for rotation are easy to spot at a glance. ### Cross-Server Sprawl A key is flagged as **shared** when the same fingerprint (SHA-256) appears in `authorized_keys` on multiple server accounts across the fleet. Sprawl severity scales with how broadly the key has been authorized. The risk of sprawl is compounding: a single compromised credential grants access to every system where that key is authorized. One leaked private key becomes a fleet-wide incident rather than an isolated one. The SSH Keys page surfaces the most broadly shared keys first, enabling targeted deprovisioning before a compromise occurs. ### Orphaned Keys An **orphaned key** is a key entry that remains in `authorized_keys` on one or more servers after the account that originally owned the key has been deleted. LinuxGuard finds these keys left behind after account removal, even when they're still authorized on other servers. Orphaned keys represent persistent access credentials with no associated owner — a particular concern because no active account lifecycle governs their rotation or removal. ### SSH Keys Table The SSH keys table has the following columns: fingerprint (SHA-256, truncatable and copyable), key type, key size, algorithm grade, age and age bucket, posture score, primary owner, and server count. Additional fields visible in the row or detail panel include whether the key is shared (`is_shared`), whether it is inactive (`is_inactive`), and a detractor count summarizing negative posture contributors. **Default sort** is by posture score ascending — the most problematic keys (lowest posture) appear first. **Available filters:** key type (user or host), algorithm grade, inactive (yes or no), shared (yes or no), environment, and tag. ## Access Patterns The Access Patterns page (`/identity/access-patterns`) provides behavioral analytics for identities across the fleet, with a supervised rollout that administrators explicitly control at every stage — nothing advances or reaches other users automatically. Analytics starts disabled. Once enabled, LinuxGuard spends an observation period learning baselines, with no anomalies surfaced yet. From there, administrators can promote to a shadow stage, where detection runs and alerts are visible to admins only, and finally to an active stage, where anomalous events and the full behavioral feed become visible to all users. Administrators can revert to observation or disable analytics entirely at any point. > **Note**: Access Patterns does not surface anomalies immediately after deployment. During observation mode, LinuxGuard learns behavioral baselines for each identity. Anomaly detection only becomes active after observation mode completes and baselines are established. ### Observation Period During observation mode, LinuxGuard records behavioral patterns for each identity and shows a progress bar toward completion. The observation period length is configurable per server group. ### Baselines and Maturity The **Baseline Maturity %** metric shows what proportion of tracked identities have accumulated enough data to support anomaly detection. Administrators should wait for high maturity before promoting to Shadow mode — promoting too early results in higher false positive rates because immature baselines have not learned full behavioral patterns for the identities they cover. ### Stat Cards The Access Patterns page shows four stat cards whose labels change depending on the active mode: * **Identities Monitored** — count of identities being tracked, with how many servers are reporting in * **Anomalous Events** (labeled "Behavioral Insights" in observation mode, "Shadow Alerts" in shadow mode) — mode-aware count of behavioral anomalies * **FP Rate** — false positive rate with a trend indicator showing whether the rate is improving, stable, or worsening * **Days Remaining** (observation mode) or **Baseline Maturity %** (shadow and active modes) ### Activity Heatmap The heatmap is a 7-day by 24-hour grid. Each cell shows the activity count for a specific day-of-week and hour-of-day combination. Color intensity indicates activity volume — the deepest color marks peak activity cells. An optional overlay highlights statistically unusual activity relative to the baseline. Heatmap filters include: dimension (combined, SSH, sudo, or other activity types), identity (typeahead search by name), server group, and time range (30, 60, or 90 days). ### Behavioral Feed In shadow and active modes, the **Behavioral Feed** appears below the heatmap as a chronological list of anomalous access events. Each entry shows the identity name, what looked unusual about the event, a confidence level (low, medium, or high), server, and timestamp. In **active mode**, entries carry severity badges (critical, high, medium, or low) at full opacity — these are live signals integrated into the alert system. In **shadow mode**, severity badges are shown at 50% opacity to indicate that detection is running but signals have not yet been promoted to full alerts. Shadow mode lets administrators validate detection quality before committing to active enforcement. *** **Related**: [Console Overview](/concepts/concepts/console) | [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) (SUDO Policies) | [Glossary](/reference/reference/glossary) | [Security Architecture](/concepts/concepts/security-architecture) # Zero Trust Enforcement Zero Trust Enforcement pillar in the LinuxGuard console — signals with MITRE mapping, config drift, SUDO policy, and findings. Zero Trust Enforcement surfaces security signals and configuration drift events with full identity context, and provides privilege analysis tools for validating the principle of least privilege. ## Signals Signals are security-relevant events collected from monitored servers and enriched with identity context at ingestion time. Each signal carries an identity risk badge (critical, high, medium, or low) drawn from the identity profile of the account involved. The signal row displays the associated MITRE ATT\&CK technique ID alongside the event summary. This mapping allows you to correlate observed behavior with known adversary techniques without leaving the Signals view. Identical signals collected within a deduplication window appear as a single entry with an occurrence count. This reduces noise from high-frequency events while preserving accurate event totals. The **response\_status** and **available\_actions** fields indicate whether a response playbook matches this signal type. When a matching playbook exists, a containment action can be triggered from the signal. Playbook configuration and active response execution are covered in the [Active Response](/concepts/concepts/active-response) documentation. ## Config Drift Config Drift tracks changes to seven component types across your fleet: Account, Group, Sudo, SSH, SSHD, SSH Key, and PAM. Each change event is enriched with attribution data so you can identify who made the change. **Attribution** shows the username and UID LinuxGuard attributes the change to, the original logged-in user via LoginUID (preserved even through privilege elevation), the process that made the change, and a confidence level for that attribution. Each drift event includes a **risk\_impact\_summary** describing the security relevance of the change, and a **recommendations** array with suggested remediation steps. **Status lifecycle:** Each drift event carries a status that reflects where it stands in the review workflow, from initial detection through to resolution. Events can also be suppressed with an optional expiration date, after which they return to active status if the condition persists. ## SUDO Policies SUDO Policies analyzes sudo rule configurations across your fleet to identify privilege escalation paths and unsafe rule patterns. The sidebar label is **SUDO Policies** (uppercase SUDO). **Shell escape vector enumeration:** Flags sudo rules where the allowed command is an interactive editor (such as `vi`, `vim`, `nano`, or `emacs`), a pager (`less`, `more`), or an interpreter (`python`, `perl`, `ruby`, `bash`) that enables an interactive shell escape. A user with a rule allowing `vi` effectively has unrestricted root access. **Wildcard abuse detection:** Flags sudo rules that use `ALL` for the command or host specifications, or that use dangerous glob patterns such as trailing `*` that could be exploited to match unintended binaries. **Privilege escalation path analysis:** Surfaces unexpected privilege chains — for example, a service account with a narrowly scoped sudo rule that transitively enables root access through a wildcard or escape vector. ## File Monitoring File Monitoring provides fleet-wide visibility into file system changes: file creates, modifications, deletes, renames, and permission changes across all monitored paths. Each event includes process attribution with a confidence level: * **HIGH** — captured at syscall time via eBPF kernel tracing; the process was identified at the moment of the file operation * **MEDIUM** — identified via `/proc` lookup after the event; the process was still running when attribution was attempted * **LOW** — the process had exited before attribution could be completed; fallback identification only **SHA-256 hash changes** distinguish content modifications from metadata-only updates such as timestamp or permission changes. A hash change confirms that file content was altered. **Exfiltration alert detection** flags suspicious data movement out of watched paths, indicating potential data staging or exfiltration. File Monitoring watch paths and file patterns are configured under **Settings > File Monitoring**. ## SELinux SELinux provides policy audit and violation detection for servers with SELinux enforcement enabled. LinuxGuard collects SELinux policy evaluations and surfaces denials and policy anomalies alongside the identity context of the processes involved. Use this view to identify processes operating outside their expected security domain. ## Playbooks and Active Responses **Playbooks** defines automated response rules. Each playbook specifies a signal match condition and a corresponding containment action — for example, isolating a host or blocking an account when a specific signal type is detected with a severity threshold. **Active Responses** shows in-flight and historical response command execution, including command status, target server, triggering signal, and execution timestamps. > **Note**: Active response configuration requires the Zero Trust module and involves safety controls described in the [Active Response](/concepts/concepts/active-response) documentation. Review the [Active Response](/concepts/concepts/active-response) documentation before configuring playbooks in production environments. ## Findings Findings is a paginated list of security findings aggregated across your fleet. Filter by severity (Critical, High, Medium, Low) and by finding category to focus on specific risk areas. A severity breakdown summary at the top of the page shows the distribution of findings across the fleet at a glance. *** **Related**: [Console](/concepts/concepts/console) | [Identity Intelligence](/concepts/concepts/console/identity-intelligence) | [Active Response](/concepts/concepts/active-response) | [Security Architecture](/concepts/concepts/security-architecture) | [Glossary](/reference/reference/glossary) # Compliance & Audit Compliance & Audit pillar in the LinuxGuard console — framework scores, history, suppressions, and audit log export. Compliance & Audit tracks your fleet's posture against security frameworks, maintains a tenant-level audit trail, and provides evidence export for compliance reporting. ## Frameworks Frameworks shows pass, fail, and not-applicable check counts for each compliance framework enabled on your tenant. The summary view gives an at-a-glance score per framework — you can drill into individual checks to see which servers are failing specific requirements. Server-level compliance scores are available from the drill-down view. Identifying servers with consistently low scores helps prioritize remediation where it will have the greatest impact on overall compliance posture. Framework views support filtering and per-server drill-down to isolate specific failure patterns. ## History History shows compliance score trends over time for your enabled frameworks. Use this view to track improvement or regression across compliance periods, validate the effect of remediation campaigns, and provide trend evidence for auditors. ## Suppressions Suppressions manages compliance findings that have been intentionally acknowledged and suppressed. Each suppression record shows the original finding, the suppression reason, and an optional expiration date — after which the finding returns to active status if the condition persists. Compliance suppressions are distinct from Config Drift suppressions. These records apply specifically to compliance check findings, not to drift events. ## Audit Logs Audit Logs is a tenant-level audit trail of actions taken within the LinuxGuard console itself. It captures administrator activity — configuration changes, suppression creation, user management, and other console operations — recording who performed each action and when. Audit Logs record console activity, not server-side changes. Server-side configuration changes appear in Config Drift under Zero Trust Enforcement. Audit Logs document what administrators did in the LinuxGuard interface. ## Reports Reports provides compliance evidence export for external reporting and audit workflows. Export compliance findings, check results, and posture summaries to support audit evidence packages and compliance certification processes. *** **Related**: [Console](/concepts/concepts/console) | [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) | [Glossary](/reference/reference/glossary) # Infrastructure Infrastructure pillar in the LinuxGuard console — fleet inventory, efficiency and rightsizing analysis, and baseline configuration. Infrastructure provides fleet-wide server inventory, efficiency and rightsizing analysis, and baseline configuration management. ## Servers Servers is the fleet view — a table of all monitored servers showing security scores, agent status, environment assignment, and assigned tags. Use this view to identify servers with degraded security posture, offline agents, or missing environment and tag assignments. Selecting a server opens the server detail page, which organizes server-specific data into tabs: | Tab | Content | | --------------- | --------------------------------------------------------- | | Overview | Security score summary, agent version, enrollment details | | Accounts | User accounts present on this server | | Groups | Group memberships on this server | | Sudo | Sudo rules configured on this server | | SSHD Config | SSH daemon configuration | | SSH Keys | Authorized keys entries on this server | | SSH Client | SSH client configuration (`~/.ssh/config`, known\_hosts) | | Efficiency | Per-server resource utilization and rightsizing data | | Drift | Config Drift events for this server | | Auth | Authentication events and session history for this server | | File Monitoring | File system events for this server | The server detail tabs provide a per-server hierarchy distinct from the top-level pillar navigation. ## Efficiency Efficiency provides CPU, memory, and storage rightsizing recommendations across the fleet. An over-provisioning summary at the top of the page shows estimated monthly cost impact broken down by CPU, memory, and storage waste. **Storage Recommendations** identifies mount points with low utilization or stale data. Each entry includes a growth forecast using linear regression analysis and projected time to capacity, helping you decide whether to reclaim, expand, or monitor a volume. **CPU/MEM Rightsizing** shows per-server resource utilization trend charts with a recommendation classification for each server: downsize, maintain, or upsize. Servers that are consistently under-utilized appear as downsize candidates; servers approaching capacity limits appear as upsize candidates. **JVM application optimization** surfaces Java processes with heap sizing or garbage collection configuration issues that are contributing to memory waste or instability. ## Baselines Baselines lets you define expected configurations for accounts, groups, and sudo policies across your fleet. LinuxGuard compares the actual state of each server against the defined baselines and records any deviations. Baseline deviations surface as Config Drift events in Zero Trust Enforcement. This creates a direct link between your configuration expectations and the drift detection system — an administrator reviewing drift events can distinguish between expected changes and unexpected deviations from your stated baseline. Optional UID and GID tracking toggles control whether numeric ID changes are included in baseline comparisons. Enabling these provides more precise detection for environments where account UID/GID assignments must remain consistent across servers. *** **Related**: [Console](/concepts/concepts/console) | [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) | [Security Architecture](/concepts/concepts/security-architecture) # What Changed What Changed in the LinuxGuard console — mapping from the old flat section list to the 5-pillar model. The LinuxGuard console has been reorganized from a flat section list to a 5-pillar model. This page maps the previous top-level sections to their new locations. Use Ctrl+F to search for any old section name. | Old Location | New Location | | ---------------------------- | ------------------------------------------------------ | | Dashboard | Dashboard | | Servers | Infrastructure > Servers | | Accounts | Identity Intelligence > Accounts | | Posture Scoring | Identity Intelligence > Identity Overview | | Identity | Identity Intelligence > Identity Overview | | Compliance | Compliance & Audit > Frameworks | | Infrastructure Efficiency | Infrastructure > Efficiency | | Security > Signals | Zero Trust Enforcement > Signals | | Security > Config Drift | Zero Trust Enforcement > Config Drift | | Security > Security Findings | Zero Trust Enforcement > Findings | | Security > File Monitoring | Zero Trust Enforcement > File Monitoring | | Security > Suppressions | Compliance & Audit > Suppressions | | Security > Auth | Infrastructure > Servers > \[server detail] > Auth tab | | NHI Automation | Identity Intelligence > Non-Human Identities | | Baselines | Infrastructure > Baselines | | Settings | Settings (unchanged, below pillar navigation) | > **Note**: The per-server Auth tab is now accessed from the server detail page within Infrastructure > Servers, rather than as a top-level section. *** **Related**: [Console](/concepts/concepts/console) | [Dashboard](/concepts/concepts/console/dashboard) | [Identity Intelligence](/concepts/concepts/console/identity-intelligence) | [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) | [Compliance & Audit](/concepts/concepts/console/compliance-audit) | [Infrastructure](/concepts/concepts/console/infrastructure) # Baselines Baselines pillar in the LinuxGuard console — known-good snapshots of accounts, groups, SSH, and SUDO configuration with drift detection. Baselines capture the known-good configuration state of accounts, groups, SSH, and SUDO across the fleet. Administrators define what "expected" looks like for each component type, and LinuxGuard compares every server against those expectations on each scan cycle. Deviations surface as Config Drift events in Zero Trust Enforcement, giving operators a direct line from "what we said the fleet should look like" to "where reality diverges." > **Note**: The LinuxGuard Console is the canonical reference for screen-by-screen layout. This page describes the conceptual scope and integration points. Baselines differ from real-time monitoring. Real-time signals fire when an event occurs (a SUDO invocation, a syscall, a file write). Baselines describe a desired steady state — they answer "is this server still in the configuration we approved?" rather than "what just happened?" A server can be free of recent signals and still fail a baseline check, which is why both surfaces matter for posture. ## Accounts The Accounts baseline records which user accounts are expected to exist on a server, with optional checks on UID, primary GID, home directory, and login shell. A server that gains an unexpected account, loses an expected one, or has an account whose UID has changed surfaces a deviation. UID tracking is opt-in per baseline because not all environments require numeric ID consistency — environments using automated provisioning where UIDs may legitimately differ across servers typically disable it. The accounts baseline is most useful for catching out-of-band account creation (an operator who adds a local account without using configuration management) and for spotting accounts that should have been removed but were not (an employee departure where one server kept the local account). ## Groups The Groups baseline records group memberships expected on each server, with optional GID tracking. The same opt-in pattern as accounts applies. Group membership baselines are particularly load-bearing for sensitive groups — `wheel`, `sudo`, `docker`, `adm` — where unexpected additions confer broad privilege. A group baseline deviation often precedes a privilege-escalation event in Zero Trust Enforcement. An account quietly added to `wheel` on one server is visible here before the first sudo invocation makes it visible in Config Drift. ## SSH config The SSH config baseline captures the contents of system-level SSH client configuration — `/etc/ssh/ssh_config` and `/etc/ssh/ssh_config.d/*` — covering settings that govern outbound SSH connections from the server. Examples: default ciphers, MACs, HostKeyAlgorithms, IdentityFile preferences, ForwardAgent behavior, and StrictHostKeyChecking defaults. A change to the client SSH config can silently weaken outbound encryption choices, enable agent forwarding where it was previously disabled, or relax host-key verification. Baseline tracking surfaces those changes whether they originated from package upgrades, hand edits, or configuration management runs that drifted from the documented standard. ## SSHD config The SSHD config baseline captures the contents of `/etc/ssh/sshd_config` and `/etc/ssh/sshd_config.d/*` — the daemon-side configuration controlling inbound SSH on the server. This includes PermitRootLogin, PasswordAuthentication, PubkeyAuthentication, AllowUsers / AllowGroups, MaxAuthTries, ClientAliveInterval, and the AuthorizedKeysFile path. SSHD config drift is high-impact because it changes who can log in and how. A baseline that flags `PermitRootLogin yes` returning after a hardening campaign, or `PasswordAuthentication yes` reappearing after key-only enforcement was rolled out, is exactly the kind of regression that this baseline exists to catch. ## SUDO aliases The SUDO aliases baseline tracks the `Host_Alias`, `User_Alias`, `Runas_Alias`, and `Cmnd_Alias` definitions in `/etc/sudoers` and `/etc/sudoers.d/*`. Aliases by themselves do not grant privilege — they are reusable names that downstream rules reference — but a change to an alias definition can broaden the reach of every rule that mentions it. A `Cmnd_Alias DEPLOY = /usr/bin/systemctl restart deploy-svc` that quietly gains `, /bin/bash` is a privilege expansion of every rule referencing `DEPLOY`, even if no rule was edited directly. ## SUDO defaults The SUDO defaults baseline tracks `Defaults` lines in the sudoers configuration. These set tenant-wide behaviors: `timestamp_timeout`, `passwd_tries`, `env_reset`, `secure_path`, `requiretty`, `lecture`, and `logfile`. Defaults changes can weaken audit posture (a `logfile` removal that takes per-invocation logging offline) or relax authentication friction (`timestamp_timeout` extended from minutes to hours). ## SUDO rules The SUDO rules baseline tracks the user / group / runas / command rule lines in sudoers. This is the core surface of who-can-do-what under privilege escalation. Rule changes are the most common source of Config Drift events for the SUDO category, and a baseline gives operators the ability to define the approved rule set and surface every deviation from it. Rules added through configuration management are visible here just as rules added by hand are — the baseline does not distinguish source, only whether the rule was expected. Rule attribution (who made the change and via which process) is provided by Config Drift in Zero Trust Enforcement. ## Baseline settings Baseline settings control how strictly each baseline category is enforced and which optional comparisons are included. The settings page exposes per-category toggles: | Setting | Purpose | | ------------------------ | ------------------------------------------------------------------------------- | | Track UID | Include numeric UID in account comparisons | | Track GID | Include numeric GID in group comparisons | | Include sudoers.d | Extend SUDO comparisons to drop-in directory files | | Include sshd\_config.d | Extend SSHD comparisons to drop-in directory files | | Sensitive groups | Comma-separated group names that receive stricter scrutiny in drift attribution | | Baseline refresh cadence | How often the agent re-scans each component for baseline comparison | Sensitive groups are a load-bearing concept — groups named here produce higher-severity drift events when membership changes, and get extra scrutiny in identity risk scoring. ## Data sources Baselines are populated from agent telemetry — the agent scans accounts, groups, SSH config files, SSHD config files, and sudoers content on each run and reports them to the backend. Baseline state is per-server and per-component; comparison happens server-side at scan time. No external sources feed baselines. The agent component performing each scan: | Baseline category | Agent surface | | ------------------------------- | ------------------------------------------------------------------- | | Accounts | `/etc/passwd`, `/etc/shadow` (presence only, content not collected) | | Groups | `/etc/group` | | SSH config | `/etc/ssh/ssh_config`, `/etc/ssh/ssh_config.d/*` | | SSHD config | `/etc/ssh/sshd_config`, `/etc/ssh/sshd_config.d/*` | | SUDO aliases / defaults / rules | `/etc/sudoers`, `/etc/sudoers.d/*` | ## Module gating Baselines is part of the Identity Intelligence module. Tenants without the Identity Intelligence module see the Baselines section in the sidebar with an upgrade prompt; baseline scan data is collected by the agent regardless but is not surfaced for comparison without the module. Subscription gating for individual baseline categories (per-component opt-in vs all-or-nothing) is documented in the console settings — categories may be selectively enabled on tenants where collection of certain config files is restricted by policy. ## Cross-references * Related CLI commands: [`config`](/reference/reference/cli/config) (baseline-related keys), [`probe`](/reference/reference/cli/probe) (per-component collection verification) * Related Concepts: [Identity Intelligence](/concepts/concepts/console/identity-intelligence) (account / group / SSH key inventory), [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) (Config Drift consumes baseline deviations), [Infrastructure](/concepts/concepts/console/infrastructure) (server-level Baselines tab) * Related How-to: [Configure](/configure/configure) (baseline tunables in agent config) *** **Related**: [Console](/concepts/concepts/console) | [Infrastructure](/concepts/concepts/console/infrastructure) | [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) | [Identity Intelligence](/concepts/concepts/console/identity-intelligence) | [Glossary](/reference/reference/glossary) # Efficiency Efficiency pillar in the LinuxGuard console — rightsizing, storage, network IO, JVM, waste assessment, labor savings, and reports. The Efficiency pillar surfaces resource utilization and cost-impact analysis across the fleet. Where Identity Intelligence and Zero Trust answer security questions, Efficiency answers operational ones: which servers are over-provisioned, which storage volumes are wasting space, which JVM applications are mis-tuned, and what the cumulative cost of those conditions looks like in dollars and operator hours. It is used by infrastructure leads, FinOps practitioners, and platform teams running capacity reviews. > **Note**: The LinuxGuard Console is the canonical reference for screen-by-screen layout. This page describes the conceptual scope and integration points. Efficiency findings are advisory — LinuxGuard does not act on them automatically. The pillar surfaces evidence and recommendations; the decision to downsize an instance, archive a volume, or retune a JVM remains with the operator. This separation is deliberate: cost-driven changes have cross-team dependencies (capacity planning, application owner sign-off, change windows) that automated remediation cannot navigate safely. ## Rightsizing Rightsizing analyzes CPU and memory utilization per server over a configurable time window and classifies each server as a downsize candidate, maintain candidate, or upsize candidate. The classification draws on percentile-based utilization metrics — typical inputs include p50, p95, and p99 of CPU and memory over the window — rather than peak values alone, so a single transient spike does not move a server out of the downsize category. A downsize candidate is a server whose p95 utilization sits consistently below the configured threshold (commonly 30-40% for CPU, 50-60% for memory). An upsize candidate is one whose p95 approaches the configured ceiling (commonly 75-85%) over multiple periods, indicating that the workload is bumping into the current instance size. The rightsizing table includes a per-server recommended instance size where the tenant has provided an instance-size catalog (e.g., AWS / GCP / Azure SKU list). When no catalog is configured, recommendations are expressed as a relative target — "reduce vCPU by 50%" or "increase memory by 100%" — rather than as a specific SKU name. ## Storage Storage Recommendations identifies mount points with low utilization, stale data, or growth trajectories worth highlighting. Each entry includes a growth forecast computed via linear regression over the observed history, and a projected time-to-capacity estimate. Operators use this to decide whether to reclaim, expand, or watch a volume. Stale data detection flags directories whose access times indicate no recent reads — typical findings are archived log directories, old backup staging paths, and application caches that were never wired up to a retention policy. The findings are advisory; LinuxGuard does not delete data. For environments where filesystem access time tracking is disabled (`noatime` or `relatime` mount options), stale-data detection falls back to modification time and file-creation cadence, with a lower confidence indicator on the resulting findings. ## Network IO Network IO analysis surfaces bandwidth utilization, connection patterns, and per-interface throughput across the fleet. The view highlights servers whose interface utilization sits in an unusual band — chronically near saturation (capacity-constrained), chronically near zero (likely candidate for instance class downsize), or showing patterns that suggest a config issue (asymmetric duplex, NIC-bond imbalance, link flapping). Network IO findings often correlate with rightsizing — a server with low CPU but saturated network throughput is not a downsize candidate at the instance level; it may instead be a candidate for an instance class with better network performance at similar compute cost. ## JVM applications JVM application optimization surfaces Java processes with heap sizing or garbage collection configuration issues. The agent collects JVM process metadata — heap configuration, garbage collector choice, observed GC pause distribution, allocation rate, and heap utilization — and flags processes where the configuration is contributing to memory waste, GC churn, or instability. Typical findings: | Pattern | Likely cause | | --------------------------------------- | --------------------------------------------------------------- | | Heap >> working set | Over-provisioned `-Xmx`; reclaim memory | | Heap ≈ working set, frequent old-gen GC | Under-provisioned heap; expand | | High allocation rate, short pauses | Allocation tuning opportunity (object pooling, escape analysis) | | Long pauses, low allocation rate | GC algorithm mismatch (CMS / G1 / ZGC / Shenandoah selection) | These findings are surfaced for review by application owners. LinuxGuard does not modify JVM flags directly. ## Waste assessment Waste Assessment aggregates rightsizing, storage, and JVM findings into a tenant-wide view with estimated monthly and annual cost impact. The cost model requires a cost catalog — either configured by the operator (per-vCPU-hour, per-GB-month) or imported from a cloud provider billing integration where available. Without a cost catalog, waste assessment shows units-of-waste (vCPU-hours, GB-months) rather than dollar figures. The view groups waste by category (CPU, memory, storage, JVM) and by environment / tag, allowing finance teams to attribute cost-impact recommendations to the team or product that owns each environment. ## Labor savings Labor Savings estimates the operator time recovered by acting on Efficiency findings. The estimate is based on time-per-action baselines configured per tenant (e.g., "a single rightsizing change takes 30 minutes including change management") multiplied by the number of pending findings. The metric is intentionally directional rather than precise. It exists to give operators and managers a sense of the recurring overhead a fleet's drift surfaces represent, not to commit to a specific hours-saved number. Tenants typically calibrate the baselines once and then track the trend over quarters. ## Efficiency reports Efficiency Reports produces exportable summaries of rightsizing, storage, JVM, waste assessment, and labor savings findings for a configurable period. Exports include a per-server breakdown, a per-environment summary, and the cost-impact aggregation if a cost catalog is configured. Output formats: CSV, JSON, and PDF. Reports are used in capacity-planning reviews, quarterly business reviews, and FinOps presentations. They are also a natural feed into chargeback / showback workflows where infrastructure cost is attributed to the team owning each environment. ## Data sources Efficiency draws on agent-collected resource telemetry — process listings, CPU and memory utilization sampled at the agent's metric interval, mount-point utilization, network interface statistics, and JVM process metadata. No external sources feed Efficiency by default. Cost catalogs (per-SKU pricing) and time-per-action baselines (labor savings) are operator-supplied through console settings. | Data | Agent surface | | ------------------------ | -------------------------------------------------------------------------- | | CPU / memory utilization | `/proc/stat`, `/proc/meminfo`, per-process `/proc/[pid]/stat` | | Mount utilization | `/proc/mounts`, `statfs()` per mount | | Network IO | `/proc/net/dev`, per-interface ethtool statistics where available | | JVM metadata | Per-process command-line, JMX where exposed, GC log scraping where present | | Storage stale data | Atime / mtime / ctime across watched filesystems | ## Module gating Efficiency is part of the Infrastructure module. Subscription gating documented in console — the Efficiency Reports export, cost catalog configuration, and labor savings estimation are typically gated on higher tiers, while the underlying rightsizing and storage findings are available across tiers. JVM application analysis requires the agent to be able to inspect Java processes, which is conditional on process visibility and may be subject to per-tier limits on the number of JVMs analyzed. ## Cross-references * Related CLI commands: [`probe`](/reference/reference/cli/probe) (verifies agent's resource-collection probes are healthy) * Related Concepts: [Infrastructure](/concepts/concepts/console/infrastructure) (per-server Efficiency tab on server detail), [Baselines](/concepts/concepts/console/baselines) (config-drift findings can correlate with efficiency drift) * Related How-to: [Log Management](/operate/operate/log-management) (log volume contributes to storage findings) *** **Related**: [Console](/concepts/concepts/console) | [Infrastructure](/concepts/concepts/console/infrastructure) | [Baselines](/concepts/concepts/console/baselines) | [Glossary](/reference/reference/glossary) # Audit Audit pillar in the LinuxGuard console — authorizations audit and SUDO execution audit for privileged-action reconciliation. The Audit pillar reconciles what was authorized against what actually executed across the fleet. It answers two related questions: "what privileged actions did our policies and rules permit?" and "what privileged actions actually ran, by whom, and were they within scope?" Audit is used by security analysts producing privilege-review evidence, compliance auditors validating that least-privilege controls are working, and incident responders reconstructing the path a privileged action took through the system. > **Note**: The LinuxGuard Console is the canonical reference for screen-by-screen layout. This page describes the conceptual scope and integration points. Audit is distinct from the tenant-level Audit Logs surface (under Compliance & Audit). Audit Logs record actions taken inside the LinuxGuard console — administrator activity in the UI. The Audit pillar records actions taken on monitored servers — authorizations granted and privileged commands executed at the OS level. Both surfaces are evidence-grade; they answer different questions. ## Authorizations audit Authorizations audit catalogues the privilege grants that exist across the fleet and produces an evidence record of what is currently authorized to run as a privileged user. The view consolidates four input sources: * **SUDO rule grants** — `user / group ALL = (runas) command` rules from sudoers and sudoers.d, expanded to enumerate the full set of (identity, command) pairs the rule authorizes * **Group memberships in privileged groups** — accounts in `wheel`, `sudo`, `adm`, `docker`, and tenant-configured sensitive groups * **PAM policy outcomes** — which authentication methods are enabled for elevation (password, key, hardware token) * **SELinux role / type bindings** — where SELinux is in enforcing mode, the SELinux roles each user can transition into The authorizations audit table answers questions like: "Which accounts can run `systemctl restart deploy-svc` as root, across the entire fleet?" or "Show every account with sudo access to any file-system-modifying command on production servers." It is the evidence record an auditor or reviewer consumes when asked to demonstrate that privilege scope is bounded. Each authorization row carries provenance — which file granted the privilege, which line, which group membership, and which baseline (if any) the authorization is part of. Provenance is what lets an operator answer the follow-up "and where does that grant come from?" without leaving the view. A common use of authorizations audit is the quarterly access review: export the table, route per-server slices to the owning team, and require sign-off that each row remains appropriate. Privilege grants that no team will own are removal candidates. ## SUDO execution audit SUDO execution audit records what privileged commands actually ran on each monitored server, with full identity attribution. Each execution event captures: | Field | Source | | ------------------ | ------------------------------------------------------------------------------------------------ | | Invoker username | Process credentials at exec time | | LoginUID | Linux Audit LoginUID; identifies the original logged-in user, independent of privilege elevation | | Effective UID | Final UID under which the command executed | | Command | Full command line (`argv`) | | Target host | Server hostname | | Timestamp | UTC, agent-side | | Authorization path | Which SUDO rule, group membership, or PAM policy granted the execution | LoginUID identifies the human who authorized a privileged action, independent of which account ultimately executed it. This keeps every command traceable to the person responsible — even after a privilege change — instead of every escalated command appearing to have been run by `root`. Execution events surface the **authorization path** that permitted the command. This is the reconciliation between the authorizations audit (what was permitted) and the executions audit (what ran): every executed command should map to a permitted authorization. Commands that executed but do not map to any current authorization — typically a result of an authorization that was revoked after the command ran, or a misattribution case — surface as reconciliation gaps for review. The audit feed supports filtering by invoker, LoginUID, server, command pattern, time window, and authorization path. CSV and JSON export are available for evidence packages. ## Data sources The Audit pillar draws on the same baseline and policy inputs used by Baselines (sudoers, group membership, PAM, SELinux) for authorization data, and on the agent's kernel-level telemetry for execution data: | Data | Agent surface | | --------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Authorization grants | `/etc/sudoers`, `/etc/sudoers.d/*`, `/etc/group`, `/etc/pam.d/*`, `getsebool` / `semodule -l` where SELinux is enforced | | LoginUID correlation | Linux Audit subsystem (`/proc/[pid]/loginuid`) and the agent's kernel-level telemetry | | Command execution | Agent kernel-level telemetry; Linux Audit rules where kernel-level telemetry is unavailable | | Effective credentials | The process's effective credentials at the time it ran | LoginUID correlation and command execution auditing require the Linux Audit subsystem to be enabled on monitored servers (`auditd` running), or the agent's kernel-level telemetry to be functional. On hosts where kernel-level telemetry is unavailable, LoginUID correlation falls back to auditd-only and may be unavailable if auditd is also disabled. ## Module gating The Audit pillar is part of the Zero Trust module. Authorizations audit and SUDO execution audit are available together. Subscription gating documented in console — historical retention windows for execution events and CSV / JSON export cadence may vary by tier. ## Cross-references * Related CLI commands: [`config`](/reference/reference/cli/config) (audit-related collection toggles), [`probe`](/reference/reference/cli/probe) (verifies audit / eBPF execve probes are healthy) * Related Concepts: [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) (SUDO Policies analysis), [Zero Trust Expansion](/concepts/concepts/console/zero-trust-expansion) (SUDO executions surface and policy violations), [Baselines](/concepts/concepts/console/baselines) (SUDO rules / aliases / defaults baselines), [Compliance Expansion](/concepts/concepts/console/compliance-expansion) (audit evidence in compliance reporting) * Related How-to: [Configure](/configure/configure) (enabling Linux Audit integration) *** **Related**: [Console](/concepts/concepts/console) | [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) | [Zero Trust Expansion](/concepts/concepts/console/zero-trust-expansion) | [Baselines](/concepts/concepts/console/baselines) | [Glossary](/reference/reference/glossary) # Compliance Expansion Compliance Expansion pillar — frameworks browser, evidence collection, compliance history, reports, suppressions, and evidence location reference. The Compliance Expansion pillar provides the deeper compliance surface beyond the v3.0 Compliance & Audit pillar's framework score view. Where Compliance & Audit answers "what is our score?", Compliance Expansion answers "what evidence supports that score, where is it stored, how has it moved over time, and what is suppressed?" This is the surface auditors, internal control owners, and compliance program managers spend most of their time inside. > **Note**: The LinuxGuard Console is the canonical reference for screen-by-screen layout. This page describes the conceptual scope and integration points. The pillar is organized around the auditor workflow: select a framework (frameworks browser), examine the controls and how LinuxGuard satisfies / supports / does not cover them (evidence collection), track the trend over the audit period (compliance history), produce auditor-shareable evidence packages (reports), and document the controls that have been intentionally accepted out of scope (suppressions). ## Frameworks browser The Frameworks browser is the entry point. It lists every compliance framework enabled on the tenant — PCI-DSS, HIPAA, SOC 2, NIS2, DORA, GDPR, NIST CSF, ISO 27001, CIS Controls, CIS Benchmarks, FedRAMP, HITRUST / FFIEC — with the framework version pin, last-verified date, and current pass / fail / not-applicable counts. Selecting a framework opens a control-level view. For each control LinuxGuard exposes a three-tier coverage indicator (Satisfies / Supports / Out of scope), the per-server pass / fail breakdown, and the evidence pointer set (see [Evidence Location](#evidence-location) below). Framework views support search and filter on control ID, status, and per-server scope. The frameworks browser is read-only at the framework definition level — control definitions and framework versions are managed by LinuxGuard, not by tenants. What the tenant configures is the framework's enablement, which servers are in scope, and which controls are intentionally suppressed. ## Evidence collection Evidence collection is the systematic gathering of the artifacts an auditor needs to verify each control. LinuxGuard packages evidence per control and per server, with cryptographic integrity verification (SHA-256 over each file) so the evidence chain is tamper-evident. Evidence categories collected: | Category | Examples | | ---------------------- | --------------------------------------------------------------------------------------------- | | Configuration state | sshd\_config, sudoers content, account / group inventory, file permissions on sensitive paths | | Behavioral evidence | Signal logs, drift event history, authorization audit trail, sudo execution audit trail | | Operational evidence | Log retention validation, support-bundle history, console audit log entries | | Cryptographic evidence | SHA-256 of each artifact, manifest signing where enabled | Evidence is collected continuously as agent telemetry arrives. The console assembles per-control evidence views on demand. There is no separate "scan now" step for evidence — every framework check is a query against the existing telemetry surface. ## Evidence Location Phases 23-25 per-framework pages reference this section for the canonical evidence pointer set. Every framework control mapping cites at least one evidence source from this list, and the per-framework pages link back here rather than duplicating the table. | Evidence type | Source location | How to retrieve | Retention | | ---------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------- | | Agent log (raw events) | `/var/log/linuxguard/agent.log` and rotated segments | Direct read on host, or via support bundle | 14 days default, configurable via `logging.max_age_days` | | Agent configuration (redacted) | `/etc/linuxguard/agent.config` | Direct read on host, or via support bundle (`config.redacted.json`) | Until next config change | | Support bundle | Default path: `/var/lib/linuxguard/support/.tar.zst` (overridable with `--out`) | `support-bundle collect` on host; console Evidence tab on the support-bundles page | Per tenant retention policy | | Console Evidence tab (per server) | Server detail page → Evidence tab | Console UI; CSV / JSON export | Per tenant retention policy | | Console Evidence tab (per control) | Compliance Expansion → framework → control detail → Evidence tab | Console UI; CSV / JSON export | Per tenant retention policy | | Signals (security events) | Agent log + console Zero Trust Enforcement → Signals | Direct via agent log; console UI; CSV / JSON export | Per tenant retention policy | | Config Drift events | Console Zero Trust Enforcement → Config Drift | Console UI; CSV / JSON export | Per tenant retention policy | | SUDO execution audit | Console Audit pillar → SUDO execution audit | Console UI; CSV / JSON export | Per tenant retention policy | | Compliance history | Console Compliance Expansion → History | Console UI; CSV / JSON export | Per tenant retention policy | | Compliance reports | Console Compliance Expansion → Reports | Console UI; PDF / CSV / JSON export | Per export | | Manifest of bundle contents | `BUNDLE-MANIFEST.json` inside any support bundle | Extract from bundle archive | Lifetime of bundle | When a per-framework mapping page (e.g., `audit-comply/pci-dss.md`) cites evidence, it points to a row of this table by name. The convention keeps per-framework pages concise and ensures the evidence-pointer set stays consistent across all 12 frameworks. > **Security Note**: Support bundles and agent.log files include attribute-key redaction only — they do not redact PII (hostnames, IPs, usernames, paths, command args). Review and approve every evidence package before sharing externally. See [Support Bundles](/operate/operate/support-bundles) for the per-file redaction status table. ## Compliance history Compliance history shows pass / fail / not-applicable trends per framework over configurable time windows. It supports the audit period question — "how did our compliance posture move over the last quarter / fiscal year?" — and provides the trend evidence many auditors require alongside point-in-time snapshots. The view includes annotation events: framework version bumps, control definition updates, server enrollment changes, and suppression changes. Annotations let the operator (and the auditor reviewing the history) distinguish between posture changes driven by remediation work and changes driven by definitional updates. ## Reports Reports produces compliance evidence packages for external sharing. Each report is a snapshot, dated and signed, including: * Framework version and last-verified date * Per-control coverage indicator and evidence pointers * Per-server pass / fail breakdown * Suppressions in effect during the report period, with each suppression's reason and expiration * Manifest of included evidence with SHA-256 verification Export formats: PDF (auditor-shareable presentation), CSV (machine-readable per-control table), JSON (full structured evidence including pointers). Reports are immutable once generated — they are evidence artifacts and need to be reproducible by reference. ## Suppressions Suppressions documents the controls that have been intentionally accepted as not in scope for a given audit period. Each suppression captures: | Field | Purpose | | ------------------- | ------------------------------------------------------------ | | Framework + control | Which control is suppressed | | Scope | Tenant-wide, environment-wide, server-set, or single server | | Reason | Free-text justification (required) | | Approver | Identity of the person who approved the suppression | | Effective date | When the suppression takes effect | | Expiration date | When the suppression auto-expires (optional but recommended) | Suppressions are first-class audit evidence — they appear in compliance reports, in the history view (as annotation events), and are subject to the tenant's audit log. A suppression is not "ignoring" a control; it is documenting the deliberate decision that the control does not apply to a specific scope for a specific time. Suppressions can be reversed (a control returns to active scope when its suppression expires or is explicitly removed) and reactivated. The suppressions page maintains the full history of every suppression event — when it was created, by whom, with what reason, when it expired, and when it was reactivated. ## Data sources Compliance Expansion draws on: * Agent telemetry — every signal, drift event, authorization, and execution event that LinuxGuard collects feeds compliance evidence * Framework definitions — managed by LinuxGuard, version-pinned, with last-verified dates on each control * Tenant configuration — framework enablement, scope (which servers / environments are in scope per framework), and suppressions No external evidence sources feed Compliance Expansion. All evidence cited in framework views and reports originates from LinuxGuard agent telemetry or tenant-configured scope decisions. ## Module gating The Compliance module gates Compliance Expansion. Subscription gating documented in console — the number of frameworks a tenant can enable, the retention window on compliance history, and reporting export cadence vary by tier. Suppressions, frameworks browser, and per-control evidence views are available wherever the Compliance module is present. ## Cross-references * Related CLI commands: [`support-bundle`](/reference/reference/cli/support-bundle) (evidence collection at the host level), [`config`](/reference/reference/cli/config) (agent retention configuration) * Related Concepts: [Compliance & Audit](/concepts/concepts/console/compliance-audit) (the v3.0 pillar this expansion builds on), [Audit](/concepts/concepts/console/audit) (authorizations and SUDO execution audit feed compliance evidence) * Related How-to: [Support Bundles](/operate/operate/support-bundles) (per-file redaction status table; pre-share PII warning), [Log Management](/operate/operate/log-management) (retention configuration) * Related Audit & Comply pages: see [Audit & Comply](/audit-and-comply/audit-comply) for the per-framework mapping pages (Phases 23-25) *** **Related**: [Console](/concepts/concepts/console) | [Compliance & Audit](/concepts/concepts/console/compliance-audit) | [Audit](/concepts/concepts/console/audit) | [Support Bundles](/operate/operate/support-bundles) | [Glossary](/reference/reference/glossary) # Integrations Integrations pillar — JIRA, Microsoft Teams, Slack, Syslog, SIEM, generic webhooks, and delivery tracking from the LinuxGuard console. The Integrations pillar manages outbound connections from LinuxGuard to the systems where alerts, findings, and operational events should land — issue trackers, chat platforms, log aggregators, SIEMs, and generic webhook receivers. It is used by detection engineers wiring LinuxGuard signals into the existing incident pipeline, operations leads routing findings to the right on-call rotations, and compliance teams ensuring evidence flows reach the audit log destination. > **Note**: The LinuxGuard Console is the canonical reference for screen-by-screen layout. This page describes the conceptual scope and integration points. Integrations is the console-managed half of LinuxGuard's outbound surface. The other half — file-based or CLI-configured forwarders (`/etc/linuxguard/agent.config` for syslog facility settings, for example) — lives outside the console and is documented under [Configure](/configure/configure) and the [Respond](/respond/respond) section's per-target pages. The console surface is for operator-friendly target management; the agent surface is for what the agent does locally. ## JIRA The JIRA integration creates issues in a target JIRA project when LinuxGuard generates a finding or signal that matches a configured rule. Each integration entry captures the JIRA base URL, the credentials used (API token recommended; basic auth supported for self-hosted instances), the project key, the default issue type, and field mappings for severity, summary, description, and labels. LinuxGuard does not poll JIRA — the integration is one-way (LinuxGuard → JIRA). Issue state changes inside JIRA do not flow back into the LinuxGuard console; status tracking remains in JIRA where the assigned engineer is already working. Typical use: route critical severity Zero Trust findings to a `SECURITY` project; route compliance suppressions to a `COMPLIANCE` project; route efficiency rightsizing recommendations to a `PLATFORM` project. The notification rule that fires the integration is configured under Notifications (see [Notifications](/concepts/concepts/console/notifications)). ## Microsoft Teams The Teams integration posts adaptive-card messages to a configured Teams channel via an incoming webhook URL. Cards include the finding summary, severity badge, originating server, MITRE technique (where applicable), and a deep link back to the LinuxGuard console for full detail. Teams is the channel surface most security and platform teams use for awareness-grade notifications — the kind of event that should appear in front of the on-call channel but does not need to open an issue. Teams cards are tuned for skimmability: a single line of summary, color-coded severity, and a clickable link. A single Teams integration entry holds the webhook URL and a default card template. Multiple channels can be wired by adding multiple integration entries, each with its own webhook URL and template overrides. ## Slack The Slack integration is functionally parallel to Teams. It posts block-kit messages to a Slack channel via an incoming webhook URL or a Slack Bot token where workspace-level installation is configured. Messages include severity color (Slack attachment color), finding summary, server, MITRE technique, and a deep link to the console. Many tenants run both Teams and Slack integrations — Teams for some teams (corporate IT, audit) and Slack for others (engineering, security). The notification rule layer is what decides which integration receives which signal; Integrations only configures the outbound endpoints. Threading: where Slack threading is enabled on the integration, identical signals collected within a deduplication window are appended as replies in the original thread rather than as new top-level messages, reducing channel noise. ## Syslog The Syslog integration forwards events to a syslog target over TCP, UDP, or TLS-encrypted TCP (RFC 5425). The integration captures the target host, port, transport, facility, severity floor (events below this severity are not forwarded), and optional client-certificate material for mutual TLS. Two message format options are supported: | Format | Use case | | -------- | --------------------------------------------------------------------- | | RFC 3164 | Legacy receivers; lower fidelity (limited structured data) | | RFC 5424 | Modern receivers; structured-data sections preserve metadata fidelity | Most aggregators (rsyslog, syslog-ng) prefer RFC 5424. The LinuxGuard console default is RFC 5424; legacy receivers can opt into RFC 3164 per integration entry. Note that syslog forwarding from individual agents (the agent forwarding its own log to a syslog target on the host) is configured at the agent level under [Configure → Log Level and Rotation](/configure/configure/log-level-rotation). The console Syslog integration is for forwarding LinuxGuard-generated events (signals, findings) from the LinuxGuard backend to a tenant-managed receiver, not for per-agent log forwarding. ## SIEM The SIEM integration is a typed wrapper around the underlying transport (HTTPS POST, Syslog over TLS, or HEC-style endpoint) with vendor-specific message shaping. The supported SIEM types include Splunk (via HEC), Microsoft Sentinel (via Log Analytics workspace ingestion), and Elastic (via Elastic Common Schema POST). Other receivers are wired through the generic webhook integration. Each SIEM integration captures the vendor type, target endpoint, authentication material (HEC token, workspace shared key, Elastic API key), index / table / data-stream target, and a field-mapping override allowing the operator to align LinuxGuard's event fields to the tenant's existing schema. SIEM-typed integrations differ from generic webhooks in that the message body is shaped to the SIEM's expected schema — Splunk events are wrapped in the HEC `{event: ..., source: ..., sourcetype: ...}` envelope; Sentinel events use the Log Analytics API JSON shape; Elastic events follow ECS field naming. The operator does not write the wrapper; the integration does. ## Generic webhooks The generic webhook integration posts a JSON body to an arbitrary HTTPS endpoint. It is the integration of choice for receivers that don't fit JIRA / Teams / Slack / Syslog / typed SIEM patterns: in-house alerting systems, custom automation runners, or third-party services not yet first-class integrations. Each webhook entry captures the URL, HTTP method (defaults to POST), authentication (none, bearer token, basic auth, or HMAC signing with shared secret), retry policy, and the JSON body template. The body template uses field substitution to insert event fields (`{{ severity }}`, `{{ summary }}`, `{{ server }}`, etc.); the substitution vocabulary is documented in the integration's template editor. Webhooks are the integration with the highest configuration surface and the lowest opinion. They are also the integration most likely to need debugging — see the Deliveries section for the canonical place to see what was sent, when, and what the receiver responded. ## Deliveries Deliveries is the per-integration delivery history. It records every outbound attempt to every integration: the timestamp, the integration entry, the originating event or rule, the request payload sent, the HTTP response code (or error class for syslog), the latency, and the retry count. Deliveries is the load-bearing surface for debugging an integration that is "not working." Before suspecting LinuxGuard, check the delivery record: * Was a delivery attempt made? (No → check the notification rule's match conditions) * What response did the receiver return? (Non-2xx → check the receiver's authentication and acceptance criteria) * Were retries attempted? (Yes but all failed → check connectivity and rate limits) * What did the request body actually contain? (For webhook / SIEM templates that may not render fields as expected) Each delivery row is inspectable — full request body, full response body, headers, and timing. This level of fidelity is what makes Deliveries the first place to look when an integration is silent or producing unexpected receiver behavior. ## Data sources Integrations is fed by: * Console-configured integration entries (endpoint, credentials, template) — operator-supplied * Notification rules that match events and route to integrations — see [Notifications](/concepts/concepts/console/notifications) * Events from across the LinuxGuard surface (signals, findings, compliance events, efficiency findings) — produced by the rest of the console pillars No external sources feed Integrations directly. The integration surface is outbound-only. ## Module gating Subscription gating documented in console. Some integration types (e.g., typed SIEM integrations beyond the most common vendors) may be tier-gated. Generic webhooks and Syslog are commonly available across tiers. Deliveries retention windows vary by tier. ## Cross-references * Related CLI commands: [`config`](/reference/reference/cli/config) (agent-level log forwarding settings) * Related Concepts: [Notifications](/concepts/concepts/console/notifications) (notification rules route events to integrations), [Compliance Expansion](/concepts/concepts/console/compliance-expansion) (compliance events are a common source of integration deliveries) * Related How-to: [Notification Rules](/respond/respond/notification-rules), [Webhook Integration](/respond/respond/webhook-integration), [Syslog Forwarding](/respond/respond/syslog-forwarding), [Splunk HEC Integration](/respond/respond/splunk-hec-integration) *** **Related**: [Console](/concepts/concepts/console) | [Notifications](/concepts/concepts/console/notifications) | [Respond](/respond/respond) | [Alerting & SIEM Integration](/concepts/concepts/alerting) | [Glossary](/reference/reference/glossary) # Zero Trust Expansion Zero Trust Expansion pillar — policies, findings, playbooks, active responses history, SUDO policies and executions, SELinux, and policy violations. Zero Trust Expansion provides the deeper Zero Trust surface beyond the v3.0 Zero Trust Enforcement pillar's signals / drift / SUDO / file-monitoring views. Where Zero Trust Enforcement is the day-to-day analyst surface (signals to triage, drift events to investigate, findings to clear), Zero Trust Expansion is the program-management surface — where policies are defined, playbooks are authored, response history is reconciled, and policy violations are reviewed across longer audit windows. > **Note**: The LinuxGuard Console is the canonical reference for screen-by-screen layout. This page describes the conceptual scope and integration points. The expansion pillar is used by detection engineers maintaining the rule library, incident-response leads reviewing playbook performance, and policy owners tracking compliance with the tenant's Zero Trust posture over time. It is the layer below the day-to-day analyst surface — a step closer to the program-level questions of "are our policies working?" rather than the per-event questions of "what should I do about this signal?" ## Policies The Policies page is the authoritative library of Zero Trust policies defined for the tenant. Each policy bundles a match expression (the signal types, drift categories, or behavioral patterns it applies to), a scope (which environments / tags / servers are in scope), and an action set (alert, suppress, escalate, or execute a playbook). Policies are versioned. Each edit produces a new version with a diff against the previous version, the editing identity, and the effective date. Older versions remain visible — operators can compare a current policy against the policy that was in effect at the time of a historical event. This versioning is what gives the Zero Trust expansion its program-management posture: policies are not just configuration, they are decisions over time. Per-policy fields: | Field | Purpose | | ---------------------- | ------------------------------------------------------------------------- | | Name | Operator-supplied, human-readable identifier | | Description | Free-text intent and rationale | | Match expression | Signal type, drift category, or behavioral pattern this policy applies to | | Scope | Environment / tag / server set the policy is in effect for | | Action | Alert, suppress, escalate, or playbook reference | | Approver | Identity that approved the policy edit | | Effective from / until | Optional time window for the policy | A policy that is suppressing every signal of a category for an extended window is, in practice, a documented decision to accept that category as out of scope. Suppressions are first-class evidence (visible in Compliance Expansion and in compliance reports). ## Findings Findings in Zero Trust Expansion is the aggregated, deduplicated view across signals, drift events, and behavioral anomalies. It is a meta-view: where Zero Trust Enforcement's Findings page is the analyst's queue (paginated, severity-filtered, focused on what needs work now), the Expansion Findings view is the program view — open / suppressed / acknowledged counts by category, week-over-week trend, and the per-policy effective rate. Operators use the Expansion Findings view to answer questions like: * Which categories of findings are growing or shrinking week over week? * What proportion of findings are being suppressed (and is that proportion changing)? * Which servers / environments produce the most findings per server (an indicator of a policy that may be too broad)? * Which findings have been open longest, and is there a pattern to those that don't get cleared? These are program-health questions, not per-event triage questions. The Findings view in this pillar is built around answering them. ## Playbooks Playbooks are scripted response actions defined for the tenant. Each playbook bundles a trigger (which signal type / severity / scope fires it), a sequence of containment actions (isolate host, kill process, disable account, revoke session, etc.), and a guardrail set (dry-run mode, maximum scope, required-approval threshold). Playbook execution is gated. A playbook that, if executed at full scope, would affect more than a configurable number of servers must be approved by a designated approver before running. A playbook configured in dry-run mode logs what it would have done without taking action. Both gates exist to prevent a playbook with too-broad scope from causing a fleet-wide outage as a containment side effect. Per-playbook fields: | Field | Purpose | | ----------------- | -------------------------------------------------------------------------- | | Trigger | Signal match condition + severity floor | | Action sequence | Ordered list of containment steps | | Scope cap | Maximum number of servers / accounts the playbook can affect per execution | | Dry-run | If on, log-only; no real action taken | | Required approver | Optional identity that must approve execution if scope cap is exceeded | | Cooldown | Minimum time between executions for the same trigger | Playbook configuration involves safety controls; review the [Active Response](/concepts/concepts/active-response) documentation before configuring playbooks in production environments. ## Active responses history Active responses history is the audit record of every playbook execution: when it ran, what triggered it, what action sequence was executed, which servers were affected, what response codes came back from the target hosts, and whether the run completed or aborted (and why). Each history entry is fully inspectable — full action sequence, full target list, full per-target outcome. This is the surface where an operator answers "did the playbook actually contain the threat?" and "did the playbook side-effect anything we did not intend?" Both are answers the program owner needs across a quarter, not just at the moment a single playbook fires. History entries are immutable and timestamped — they are evidence of response actions taken. ## SUDO policies SUDO policies is the program-level companion to the v3.0 Zero Trust Enforcement's SUDO Policies analysis page. The v3.0 page surfaces real-time analysis of SUDO rule patterns (shell escape vectors, wildcard abuse, privilege escalation paths). The Expansion SUDO Policies page is the policy-versioning and policy-coverage surface: which SUDO patterns are explicitly approved, which are flagged for review, and how the approved set has evolved. Operators use Expansion SUDO Policies to: * Document approved SUDO patterns at the tenant level (e.g., "rules of the form `%deploy ALL = NOPASSWD: /usr/bin/systemctl restart ` are explicitly approved") * Track exceptions — SUDO rules that match a flagged pattern but have an approved exception with a documented reason * Measure policy compliance — what percentage of SUDO rules across the fleet match an approved pattern, what percentage have documented exceptions, and what percentage are unreviewed ## SUDO executions SUDO executions in Zero Trust Expansion is the long-window execution view: aggregated and trend-analyzed SUDO execution events. The day-to-day per-event execution audit lives in the Audit pillar (see [Audit](/concepts/concepts/console/audit)). The Expansion SUDO executions view is the meta-view: rate of executions per server, per invoker, per command pattern; growth or decline over the audit period; outlier execution events that don't match an approved pattern. This is the surface a privileged-access program owner uses to answer "is the program working?" — meaning are sudo executions trending in the direction the policy expects, and are exceptions being documented as policy requires? ## SELinux SELinux in Zero Trust Expansion provides the policy-program view of SELinux posture across the fleet. The day-to-day SELinux status surface (which servers are enforcing, which are permissive, which are disabled) lives in Zero Trust Enforcement. The Expansion view tracks the program metrics: percentage of servers in enforcing mode, denial event rate per server (with abnormally high rates surfacing as candidates for policy refinement), policy-version drift, and the proportion of servers running the tenant's approved SELinux policy bundle. This view is most relevant for tenants where SELinux is a load-bearing control (e.g., FedRAMP environments, healthcare environments) and where the program owner needs to track policy adoption over time as part of the audit posture. ## Policy violations Policy violations is the catch-all for events that violate one or more defined policies. It deduplicates across the underlying surfaces — a single event might appear as a signal in Zero Trust Enforcement, a drift event in Config Drift, and a finding in Findings, but in Policy violations it is a single row tied to the policy or policies it violated. Each policy violation row carries: * The policy (or policies) violated * The originating event(s) * The scope (server / environment) where the violation occurred * The action taken (alert, escalation, playbook execution) * The status (open, acknowledged, resolved, suppressed) Policy violations is the most useful view for the program owner answering "are we enforcing our policies, and where are we not?" — and for the auditor asking "show me every violation of policy X in the audit period, with the response that was taken." It is the surface where Zero Trust as a program (rather than as a set of detection rules) becomes legible. ## Data sources Zero Trust Expansion draws on: * Policy definitions (operator-authored, versioned in the console) * Playbook definitions (operator-authored, with safety controls) * Active response execution history (produced by playbook runs) * Signal / drift / behavioral telemetry from the rest of the Zero Trust surface (Zero Trust Enforcement) * SUDO execution audit (shared with Audit pillar) * SELinux policy state (collected by the agent where SELinux is enabled) No external sources feed Zero Trust Expansion. All inputs originate either from agent telemetry or from operator-supplied policy / playbook definitions. ## Module gating Zero Trust Expansion is part of the Zero Trust module. Subscription gating documented in console — playbook execution, active response history retention, and policy versioning depth may vary by tier. Policies, Findings (aggregated), SUDO policies, SUDO executions, SELinux, and Policy violations are all available where the Zero Trust module is present. ## Cross-references * Related CLI commands: [`config`](/reference/reference/cli/config) (agent-level Zero Trust collection settings), [`probe`](/reference/reference/cli/probe) (verifies the Zero Trust probes are healthy) * Related Concepts: [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) (the v3.0 day-to-day surface this pillar expands), [Audit](/concepts/concepts/console/audit) (SUDO execution audit detail), [Active Response](/concepts/concepts/active-response) (playbook safety model) * Related How-to: [Respond](/respond/respond) (notification rules and integration targets for playbook outputs) *** **Related**: [Console](/concepts/concepts/console) | [Zero Trust Enforcement](/concepts/concepts/console/zero-trust-enforcement) | [Active Response](/concepts/concepts/active-response) | [Audit](/concepts/concepts/console/audit) | [Glossary](/reference/reference/glossary) # Posture Posture pillar — Compliance Posture, Configuration Posture, Health Posture and the rationale for consolidation under one navigation label. The Posture pillar is a unified navigation label that groups three distinct view families — Compliance Posture, Configuration Posture, and Health Posture — under one sidebar entry. It exists because the underlying data is correlated (a server with low compliance posture often has low configuration posture and degraded health posture), and grouping the views together makes that correlation legible. Posture is used by site reliability engineers tracking fleet health, security leads reviewing compliance posture, and platform owners watching configuration drift across environments. > **Note**: The LinuxGuard Console is the canonical reference for screen-by-screen layout. This page describes the conceptual scope and integration points. The Posture pillar is best understood as a navigation choice rather than a new data layer. The compliance data inside Compliance Posture is the same compliance data exposed by the Compliance Expansion pillar. The configuration data inside Configuration Posture is the same data exposed by Baselines. The health data inside Health Posture is the same operational telemetry exposed by Infrastructure. What Posture adds is the cross-cutting axis — the ability to ask "show me servers that are low on all three posture dimensions, ranked by total risk" — without navigating between three separate pillars to assemble the picture. ## Naming rationale A reasonable question for operators new to LinuxGuard is "why is there a Posture pillar at all, given Compliance Expansion, Baselines, and Infrastructure already exist?" The answer is consolidation versus separation: any sufficiently rich console either provides separate per-domain views (separation) or provides a cross-cutting summary view (consolidation). LinuxGuard provides both, deliberately. Separation is what the per-domain pillars give you. A compliance analyst working a specific framework wants the Compliance Expansion pillar, not a generic posture view — the analyst needs framework-specific control mapping, per-control evidence, and per-suppression rationale. A platform engineer triaging a server's configuration drift wants Baselines, not Posture — they need the per-component drift event, the attribution, and the diff. The per-domain pillars are optimized for these focused workflows. Consolidation is what Posture provides. A site reliability lead doing a fleet-wide review wants one view that shows compliance score, configuration drift, and health metrics side-by-side per server, not three separate views. A risk officer presenting fleet posture to leadership wants a single dashboard summarizing posture across all three dimensions. The Posture pillar is optimized for these cross-cutting workflows. The trade-off this design accepts: a small amount of data duplication between the per-domain pillars and the Posture pillar (each metric is visible from at least two sidebar paths). The benefit: workflows that need cross-cutting visibility don't have to assemble it manually from three places. ## Compliance Posture Compliance Posture provides the cross-framework, per-server view of compliance scores. Where Compliance Expansion's frameworks browser is "drill into framework X and see how every server scores against it," Compliance Posture is "pick a server (or server set) and see how it scores against every enabled framework." The Compliance Posture view is per-server-centric. Each row is one server; columns are framework scores (current, with a trend indicator vs the prior period). Servers with consistently low compliance posture across multiple frameworks surface at the top — these are the servers where compliance remediation effort has the highest cross-framework leverage. A server's compliance posture is not a single number. It is a vector of per-framework scores. Posture rolls them up to a server-level "low / medium / high" categorical for ranking purposes, but the underlying detail (which controls are failing on which frameworks) is always one click away. This view is the bridge between Compliance Expansion (framework-first) and Infrastructure (server-first). The compliance analyst lives in Compliance Expansion; the SRE lives in Infrastructure; the risk officer reviewing fleet posture lives in Compliance Posture. ## Configuration Posture Configuration Posture provides the cross-baseline, per-server view of configuration drift. Where Baselines is per-component (accounts, groups, SSH, SUDO categories each as their own surface), Configuration Posture is per-server: how many configurations on this server diverge from baseline, in which categories, and how recent are the deviations? A configuration posture row includes: | Metric | Source | | ------------------------ | ----------------------------------------------------------------------------- | | Server | Fleet inventory | | Baseline deviation count | Sum across all baseline categories enabled for this server | | Most recent deviation | Latest baseline-deviation drift event on this server | | Deviation categories | Which Baselines surfaces (accounts / groups / SSH / SUDO) the deviations span | | Trend | Week-over-week change in deviation count | Configuration posture is the surface where an SRE answers "which of my servers have the most outstanding configuration drift?" The answer drives the order of the SRE's remediation queue. Configuration posture is also the surface where the cross-correlation with compliance becomes visible. A server with high configuration deviation count typically also shows degraded compliance posture — because compliance frameworks include controls that are tightly coupled to the baselined configuration. Watching them move together (or, more usefully, watching when one moves and the other does not) is what makes consolidation useful here. ## Health Posture Health Posture provides the cross-cutting operational health view: agent connectivity, agent version drift, probe health, log volume anomalies, and resource utilization at the alarm thresholds. It overlaps with Infrastructure's per-server views — the data is largely the same — but the framing is "is this server's posture degraded operationally?" rather than "what is this server's inventory?" Per-row metrics: | Metric | Meaning | | ------------------ | --------------------------------------------------------------------------------------------- | | Agent connectivity | Has the agent reported in the expected cadence? | | Agent version | Is the agent at the tenant's approved version floor? | | Probe status | Are the eBPF / fanotify / netlink / audit / caps probes all healthy? (per `probe` CLI output) | | Resource alarms | CPU / memory / storage at or above the alarm threshold | | Log volume | Is the agent producing log volume in the expected band, or anomalously high / low? | Health posture is the SRE's fleet-monitoring surface. A server with degraded health posture is one that needs operational attention before it has a security or compliance impact. Catching health degradation early reduces the surface area on which compliance and configuration posture eventually degrade. ## Cross-correlation view A consolidated row across all three dimensions is the headline of Posture. Each server is ranked across compliance, configuration, and health, with a composite "total posture" indicator. Sorting by composite score surfaces the servers where the three dimensions agree on degradation — the strongest signal that focused remediation will have outsized impact. The cross-correlation view also surfaces interesting disagreements: a server with high compliance posture but degraded health posture (compliance still passing, but operationally drifting) is an early warning. A server with low compliance posture but healthy configuration posture and health posture suggests the compliance issue is framework-level (a control definition or scope issue) rather than a server-specific configuration issue. Disagreements between dimensions are diagnostic information that the per-domain pillars don't surface directly. ## Data sources Posture aggregates data already collected by other pillars: | Sub-view | Underlying source | | --------------------- | ---------------------------------------------------------------- | | Compliance Posture | Compliance Expansion (framework scoring engine) | | Configuration Posture | Baselines (per-component drift detection) | | Health Posture | Infrastructure (server inventory) + agent connectivity heartbeat | | Cross-correlation | Server-keyed join across the three sub-views | There are no Posture-specific data sources. Every metric Posture displays is sourced from a per-domain pillar; Posture is the navigation and cross-axis surface, not a new collection layer. ## Module gating Posture availability depends on which modules are present: * Compliance Posture requires the Compliance module. * Configuration Posture requires the Identity Intelligence module (which gates Baselines). * Health Posture is available across tiers (it draws on Infrastructure, which is the base inventory layer). Subscription gating documented in console — the cross-correlation view requires at least Health Posture and one of (Compliance Posture, Configuration Posture). Tenants with only Health Posture available see a simplified Posture view without the cross-correlation axis. ## Cross-references * Related CLI commands: [`probe`](/reference/reference/cli/probe) (per-server probe health feeds Health Posture) * Related Concepts: [Compliance Expansion](/concepts/concepts/console/compliance-expansion) (framework-first view of the same compliance data), [Baselines](/concepts/concepts/console/baselines) (per-component view of the same configuration data), [Infrastructure](/concepts/concepts/console/infrastructure) (server-first view of the same health data), [Dashboard](/concepts/concepts/console/dashboard) (fleet-level summary that draws on Posture) * Related How-to: [Configure](/configure/configure) (agent settings that affect health posture cadence) *** **Related**: [Console](/concepts/concepts/console) | [Compliance Expansion](/concepts/concepts/console/compliance-expansion) | [Baselines](/concepts/concepts/console/baselines) | [Infrastructure](/concepts/concepts/console/infrastructure) | [Glossary](/reference/reference/glossary) # Notifications Notifications pillar — notification rules, suppressions, and rule edit/new flows in the LinuxGuard console. The Notifications pillar manages how LinuxGuard events become outbound notifications. It is where operators define the rules that match events (signals, drift, compliance findings, efficiency findings), set the routing targets (which integration receives the notification), apply suppressions (which events explicitly do not produce notifications), and review the per-rule history of notifications produced. > **Note**: The LinuxGuard Console is the canonical reference for screen-by-screen layout. This page describes the conceptual scope and integration points. Notifications is the console-side companion to the file-based `respond/notification-rules.md` configuration surface. Both surfaces drive the same notification engine — a rule defined in the console and a rule defined in the agent-level `notification-rules.yaml` file are processed by the same pipeline. The distinction is operator-facing: the console surface is for tenant-wide rules managed by security / operations leads through the UI; the agent-side file surface is for per-host rule overrides managed by configuration management. Most tenants use the console surface as the primary; agent-side rules exist for specialized per-host policy. ## Notification rules A notification rule has four parts: a match expression, a scope, an action, and operational settings (cooldown, deduplication, throttle). The **match expression** selects which events the rule applies to. It can match on: | Match field | Example | | ------------------------- | --------------------------------------------------------------- | | Event source | Signals, Config Drift, Compliance, Efficiency, Audit, Baselines | | Event category | Within source — e.g., for Signals: MITRE technique, signal type | | Severity | Critical, High, Medium, Low | | Identity attribute | Specific user, group membership, NHI tier | | Server attribute | Environment, tag, hostname pattern | | Time of day / day of week | Business hours, after hours, weekends | Match expressions support AND / OR composition. A typical rule like "Critical signals on production servers during after-hours" is expressed as `(severity = Critical) AND (server.environment = production) AND (time = after-hours)`. The **scope** narrows the rule's reach to a subset of the fleet. Scope is independent of the match expression: a match on "Critical signals" can be scoped to "only production servers," to "only the `webapp-prod` tag," to "all servers," or to "a specific server set." Scope is the deployment lever that lets the same rule pattern roll out gradually (start scope-limited, expand as the rule proves reliable). The **action** is the routing target. Actions reference Integration entries (see [Integrations](/concepts/concepts/console/integrations)) — a notification rule with action `Slack:security-alerts` posts to the Slack integration entry named `security-alerts`. A single rule can have multiple actions; a rule firing produces one notification per action. **Operational settings:** | Setting | Purpose | | ------------- | ------------------------------------------------------------------------------------------------------------ | | Cooldown | Minimum time between successive notifications from this rule for the same source event | | Deduplication | Identical events within the deduplication window collapse into a single notification (with occurrence count) | | Throttle | Maximum notifications per period for this rule; excess events queue or drop per the rule's overflow policy | | Quiet hours | Time windows during which the rule does not fire | Operational settings are why notification rules feel reliable in production. Without cooldown / dedup / throttle, a single event source firing at high volume would saturate the integration target (and the on-call rotation). With them, the same rule produces an actionable notification stream regardless of underlying event volume. ## Suppressions Suppressions are documented decisions to not produce notifications for specific events. They are separate from notification rules: a suppression does not match-and-route; it match-and-silences. Per-suppression fields: | Field | Purpose | | ---------------- | ------------------------------------------------------------------- | | Match expression | Same vocabulary as notification rules — which events are suppressed | | Scope | Where the suppression is in effect | | Reason | Free-text justification (required) | | Approver | Identity that approved the suppression | | Effective date | When the suppression begins | | Expiration date | When the suppression auto-expires (strongly recommended) | Suppressions in Notifications are operational suppressions — "don't bother the on-call with this category of event for this maintenance window." They are distinct from policy-level suppressions in Zero Trust Expansion (which document that an event category is out of policy scope) and from compliance suppressions in Compliance Expansion (which document that a control is out of audit scope), though the same vocabulary is used everywhere. Suppressions are first-class audit evidence. Every suppression appears in the tenant audit log with creator, approver, scope, and expiration. A suppression that has been in effect for an extended period without expiration is a yellow flag — it suggests the suppression has become permanent in practice and should either be expired (the condition has been resolved) or formalized as a policy-level decision. ## Rule edit flow Editing an existing rule walks the operator through: 1. **Inspect current state** — the rule's match expression, scope, actions, and operational settings as currently in force. 2. **Modify** — change any of the above. The console highlights diffs from the current state as the edit proceeds. 3. **Preview** — the console shows a sample of recent events the modified rule would have matched (over a configurable look-back window, typically the last 24 hours). This is the load-bearing safety step: the operator can see whether the modified rule would have fired on too few events (rule is too narrow) or too many (rule is too broad). 4. **Save** — the rule is persisted with the editing identity and timestamp. The new version takes effect from save time. Edits do not affect historical notifications. A rule modified after an event fired does not retroactively suppress or re-route the notification that already went out. The rule edit log preserves prior versions; the operator can diff a current rule against any historical version. ## Rule new flow Creating a new rule walks the operator through: 1. **Pick the rule template (optional)** — the console offers templates for common rule patterns (e.g., "Critical signal on production server," "Compliance finding for in-scope framework," "Sudo execution outside business hours"). Templates are starting points; every field is editable. 2. **Define the match expression** — using the match-field vocabulary above. The console offers an expression builder with autocompletion over event sources, categories, and identity / server attributes. 3. **Set scope** — pick the scope by environment, tag, hostname pattern, or explicit server set. 4. **Set action(s)** — pick one or more Integration entries as routing targets. 5. **Configure operational settings** — cooldown, deduplication, throttle, quiet hours. 6. **Preview** — same preview surface as the edit flow: which recent events would the new rule have matched? 7. **Activate or stage** — stage the rule (configured but not firing — events that would have matched are visible in a "would have fired" view for review) or activate it (rule fires from creation forward). Staging is a quiet rollout mechanism. A new rule that is staged for a week before activation gives the operator a real history of "would the rule have fired correctly?" before any real notifications go out. Most teams adopt the pattern of stage-first / activate-after-review for any rule with broad scope. ## Data sources Notifications is fed by: * Events from across the LinuxGuard surface (signals, drift, compliance findings, efficiency findings, audit events, baseline deviations) * Operator-defined rule and suppression configurations * Integration entries (see [Integrations](/concepts/concepts/console/integrations)) — the routing targets that actions reference The notification engine evaluates every event against every active rule, applies operational settings (cooldown, dedup, throttle), checks suppressions, and dispatches matching events to the action's integration. Delivery outcomes are tracked in [Integrations → Deliveries](/concepts/concepts/console/integrations#deliveries). ## Module gating Notifications is available across tiers — every tenant has some notification surface. Subscription gating documented in console: the number of active rules per tenant, the operational settings available (cooldown granularity, throttle precision), and the depth of rule history retention may vary by tier. Per-tenant tier configuration documents the exact gating. ## Cross-references * Related CLI commands: [`config`](/reference/reference/cli/config) (agent-side notification-related settings) * Related Concepts: [Integrations](/concepts/concepts/console/integrations) (notification actions reference Integration entries), [Zero Trust Expansion](/concepts/concepts/console/zero-trust-expansion) (policy-level suppressions are a higher tier of decision than operational suppressions), [Compliance Expansion](/concepts/concepts/console/compliance-expansion) (compliance suppressions are framework-scoped) * Related How-to: [Notification Rules](/respond/respond/notification-rules) (agent-side rule file surface), [Respond](/respond/respond) (the integration target reference docs) *** **Related**: [Console](/concepts/concepts/console) | [Integrations](/concepts/concepts/console/integrations) | [Respond](/respond/respond) | [Alerting & SIEM Integration](/concepts/concepts/alerting) | [Glossary](/reference/reference/glossary) # Troubleshooting Diagnose and resolve common LinuxGuard agent issues — log inspection, enrollment errors, runtime problems, and integration failures. This guide helps you diagnose and resolve common issues with the LinuxGuard agent. ## Agent Logs The primary source of information for troubleshooting is the agent log file. The LinuxGuard agent writes detailed logs that can help identify issues. ### Log File Location The agent log file is located at: ``` /var/log/linuxguard/agent.log ``` ### Viewing Logs To view the agent logs: ```bash sudo tail -f /var/log/linuxguard/agent.log ``` To view the last 100 lines: ```bash sudo tail -n 100 /var/log/linuxguard/agent.log ``` To search for errors: ```bash sudo grep -i error /var/log/linuxguard/agent.log ``` ## Common Issues ### Enrollment Failures **Problem**: Agent fails to enroll with error messages. **Solutions**: 1. Verify your API key and Tenant ID are correct 2. Check network connectivity: ```bash curl -v https://api.linuxguard.io/v1/ ``` 3. Ensure the agent has proper permissions (run with `sudo`) 4. Check firewall rules allow outbound HTTPS connections 5. Review the agent log file for specific error messages ### Agent Not Sending Data **Problem**: Agent enrolled successfully but no data appears in the console. **Solutions**: 1. Verify the agent service is running: ```bash sudo systemctl status linuxguard-agent ``` 2. Check if the agent process is running: ```bash ps aux | grep linuxguard-agent ``` 3. Review agent logs for connection errors 4. Verify network connectivity to `api.linuxguard.io` 5. Check system time is synchronized (NTP) ### Installation Issues **Problem**: Unable to install the agent package. **Solutions**: 1. Ensure the repository was added successfully 2. Update your package manager cache: * Debian/Ubuntu: `sudo apt update` * RedHat/CentOS: `sudo dnf makecache` or `sudo yum makecache` * Alpine: `sudo apk update` 3. Verify repository signing keys are installed 4. Check for conflicting packages 5. Review system package manager logs ### Permission Errors **Problem**: Permission denied errors when running agent commands. **Solutions**: 1. Ensure you're using `sudo` for agent commands 2. Verify your user has sudo privileges 3. Check file permissions on agent binaries and configuration files 4. Review SELinux/AppArmor policies if applicable ### Network Connectivity Issues **Problem**: Agent cannot connect to LinuxGuard API. **Solutions**: 1. Test connectivity: ```bash curl -v https://api.linuxguard.io/v1/ ``` 2. Check firewall rules (allow outbound HTTPS on port 443) 3. Verify proxy settings if behind a corporate proxy 4. Check DNS resolution: ```bash nslookup api.linuxguard.io ``` 5. Review network security group rules (cloud environments) ## Getting Help If you're unable to resolve an issue using this guide: 1. **Check the logs**: Review `/var/log/linuxguard/agent.log` for detailed error messages 2. **Gather information**: Note the error messages, your distribution version, and any relevant system information 3. **Contact Support**: Reach out to with: * Description of the issue * Relevant log excerpts * Your distribution and version * Steps you've already tried Our support team is available 24/7 and will help you resolve any issues. *** **Related**: [Support](/support) | [Configuration](/configure/configure) # Support Contact information and help resources for LinuxGuard — 24/7 support channels, what to include in requests, and self-service routes. LinuxGuard provides comprehensive support to help you get the most out of the platform. ## 24/7 Support Our support team is available around the clock to assist you with any questions or issues. **Email**: When contacting support, please include: * Description of your issue or question * Your Tenant ID (if applicable) * Relevant log excerpts from `/var/log/linuxguard/agent.log` * Your Linux distribution and version * Any error messages you've encountered ## Sales Inquiries For sales inquiries, tenant setup, or account-related questions: **Email**: ## Documentation * [Getting Started Guide](/install/install) - Step-by-step setup instructions * [Troubleshooting Guide](/troubleshooting) - Common issues and solutions * [Supported Distributions](/reference/reference/supported-distributions) - Distribution compatibility information ## Response Times * **Critical Issues**: Response within 1 hour * **General Support**: Response within 4 hours * **Sales Inquiries**: Response within 1 business day *** **Related**: [Troubleshooting](/troubleshooting) | [Installation](/install/install) | [Configuration](/configure/configure) # Changelog Release notes and documentation change history for LinuxGuard, organized in Keep a Changelog format with semantic versioning. All notable changes to LinuxGuard will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [4.0.0](https://github.com/linuxguard/linuxguard/compare/v3.0.0...v4.0.0) - 2026-05-31 ### Added * Lifecycle-First Hybrid information architecture (9 top-level groups + 3 footer pages) replacing Diataxis 4-quadrant structure * Container deployment suite: hub + 7 spokes (distroless image, ephemeral mode, K8s DaemonSet, Downward API, TOTP enrollment tokens, docker-compose, Podman) plus OCI multi-arch manifest documentation * CLI reference (12 commands): start, config, probe, support-bundle, signals, environment variables, exit codes, enroll, unenroll, show-config, status, version * Multi-architecture support matrix (amd64, arm64, armv7, riscv64, s390x, ppc64le) with per-capability columns and ARMv7 Degraded mode callout * Log management documentation (LOG-04 precise redaction scope, log-level + rotation operational knobs, logrotate sample) * Support tools documentation (support-bundle collect/upload workflow, per-file redaction status table, pre-share PII warning) * Console expansion: 8 new pillar pages (Baselines, Efficiency, Audit, Compliance Expansion, Integrations, Zero Trust Expansion, Posture, Notifications) * Compliance index hub with three-tier vocabulary contract (Satisfies / Supports / Out of scope), framework version pin reference, per-framework template, shared-responsibility statement * 12 per-framework compliance pages: PCI-DSS v4.0.1, HIPAA, SOC 2 (TSC 2017 rev 2022), GDPR (with IP-as-PII gotcha), NIS2, DORA, FedRAMP/StateRAMP, HITRUST/FFIEC, NIST CSF 2.0, ISO/IEC 27001:2022, CIS Controls v8.1, CIS Benchmarks Linux * GitBook feature optimization: variables (agent\_version, paths), card grids on 9 hubs, per-content-type guidance, page metadata on all published pages ### Changed * Information architecture restructured from Diataxis (Tutorials / How-to / Reference / Explanation) to Lifecycle-First Hybrid (Get Started / Install / Configure / Operate / Deploy at Scale / Respond / Audit & Comply / Reference / Concepts) * 31 pages migrated via `git mv` with 100% rename detection * SUMMARY.md rewritten for new IA * `.gitbook.yaml` redirect block added for v3.0 → v4.0 URL preservation (31 entries) * `CLAUDE.md` updated to reflect new IA structure ### Documentation * Link-check CI gate via lychee (QA-07) — fails PR merge on broken internal links * Hidden-CLI CI gate (CLI-10) — fails PR merge if internal-only CLI surface (commands and flags marked hidden in the agent source code) appears in user-facing docs; the canonical manifest of hidden surface lives in `.planning/codebase/hidden-cli.json` * Compliance-tone CI gate (COMP-16) — fails PR merge on forbidden marketing words in `audit-comply/` * 42 source-file:line citations recorded in CLI reference plan SUMMARY documents * Glossary expanded with v4.0 terminology (containers, multi-arch, compliance vocabulary, support) ## [3.0.0](https://github.com/linuxguard/linuxguard/compare/v2.2.2...v3.0.0) - 2026-03-02 ### Added * Console redesigned with 5-pillar navigation: Dashboard, Identity Intelligence, Zero Trust Enforcement, Compliance & Audit, and Infrastructure * Identity Intelligence: cross-server identity aggregation, risk scoring, and SSH key algorithm strength and age analysis * NHI Inventory with three-tier classification (System Default, Application Service, Custom Service) and credential age tracking * Access Patterns: behavioral baseline learning, observation/shadow/active mode state machine, activity heatmaps, and behavioral feed * What Changed guide mapping pre-redesign section names to new pillar locations * Active Response: playbooks with trigger conditions, four containment actions (lock account, kill sessions, disable SSH key, revoke sudo), and automatic timeout-based rollback * Triple opt-in safety model documentation with blast radius system properties and Active Responses audit page * Notification Rules configuration with severity filters, throttle windows, quiet hours, and scope filters * Webhook integration with HMAC-SHA256 payload signature verification (examples in Python, Node.js, Go) * Syslog forwarding to SIEM platforms using RFC 3164 and RFC 5424 over UDP, TCP, and TLS * Splunk HEC integration with sourcetype configuration, index routing, and JSON event field reference * Automated Deployment overview with idempotency patterns and six-tool comparison * Ansible role and inline playbook with Ansible Vault secrets integration and service verification * AWS EC2 user-data script with IAM role and Secrets Manager credential retrieval (no hardcoded secrets) * GCP startup script with every-boot idempotency guard and Secret Manager credential retrieval * Azure cloud-init and Custom Script Extension with Managed Identity and Key Vault integration * Chef cookbook with chef-vault secrets management and idempotency guard * Puppet module with Hiera eyaml secrets management and idempotency guard ### Changed * Security Architecture updated with response executor privilege model and updated "What LinuxGuard Does NOT Do" section reflecting conditional active response capability * RPM package GPG signature verification documented in Security Architecture ## [2.2.2](https://github.com/linuxguard/linuxguard/compare/v2.2.1...v2.2.2) - 2026-02-08 ### Added * Authentication event collection from syslog, journald, and utmp/wtmp/btmp logs * Brute force detection for repeated failed login attempts using sliding window analysis * GeoIP enrichment for authentication events using MaxMind GeoLite2 database * Real-time file system monitoring using eBPF-based access tracing * File monitoring configuration from Settings > File Monitoring in console * Exfiltration detection alerts for suspicious data access patterns * User Behavior Analytics (UBA) with statistical baseline learning for authentication patterns * Anomaly detection for unusual login behavior (time, location, frequency) * Per-server compliance scoring with evaluators for SSHD configuration, accounts, groups, sudo policies, and SSH keys * Account Access Graph showing direct and group-mediated sudo rules with privilege highlighting * Identity page with unified directory of all user and service accounts across the fleet * GeoIP weekly updates with automated MaxMind GeoLite2 database downloads and hot-reload ### Changed * Config drift tracking expanded to six component types: Accounts, Groups, Sudo, SSH, SSHD, SSH Keys * Config drift event lifecycle enhanced with a multi-stage workflow from detection through resolution * Config drift events now display field-level configuration diffs in event detail panel * Drift Trends chart now supports 7D/30D/90D time range views * Resolution history includes audit trail and notes * Server Detail Dashboard redesigned with bento grid layout featuring hero card, posture score gauge, compliance score, and efficiency status * Server detail tabs expanded to 11 tabs: Overview, Accounts, Groups, Sudo, SSHD Config, SSH Keys, SSH Client, Efficiency, Drift, Auth, File Monitoring * Posture and compliance score cards now show trend arrows (up/down/stable) * Dashboard time range tabs (7D/30D/90D) added for infrastructure utilization chart * Security findings page enhanced with severity filtering and breakdown dashboard ### Documentation * Quality review: validated all internal links, resolved orphaned pages, standardized footer navigation and formatting, updated project instructions (CLAUDE.md) for Diataxis structure * Added Auth Tab subsection to Console Overview * Added File Monitoring Tab subsection to Console Overview * Added NHI Automation section to Console Overview * Added Posture Score, Compliance Score, and Config Drift concepts to Glossary ## [2.2.1](https://github.com/linuxguard/linuxguard/compare/v2.2.0...v2.2.1) - 2026-02-05 ### Added * CPU/Memory Rightsizing analysis identifying over-provisioned and under-utilized resources * Rightsizing recommendation classifications: downsize, maintain, or upsize * Fleet-wide rightsizing list page with filter bar and waste metrics * Per-server rightsizing detail page with utilization trend charts and threshold zones * Network I/O Analysis with dedicated network utilization endpoint and console page ### Changed * Efficiency page reorganized into 4-card grid layout * Baseline creation dialogs enhanced for accounts, groups, and sudo policies ### Documentation * Added Efficiency page subsections (CPU/Memory Rightsizing, Network I/O) to Console Overview ## [2.2.0](https://github.com/linuxguard/linuxguard/compare/v2.1.1...v2.2.0) - 2026-02-04 ### Added * Storage Recommendations with mount-point-level storage analysis and growth forecasting via linear regression * Storage resize recommendations with step alignment * Tenant-configurable storage thresholds and policies * Fleet-wide storage recommendations page grouped by server * Per-server storage detail page with forecast charts * Automatic filtering of loop devices and virtual filesystems * 5GB minimum threshold for storage opportunity reporting * Per-mount-point metrics tracking with device and mount point fields ### Changed * Queue-based aggregation jobs implemented for metrics, utilization, and efficiency scoring * Hourly resource metrics aggregation with cleanup service ### Documentation * Added Storage Recommendations subsection to Console Overview ## [2.1.1](https://github.com/linuxguard/linuxguard/releases/tag/v2.1.1) - 2026-02-02 ### Added * Security posture scoring system across five object types: Accounts (15 detractors, 10 mitigators), Groups (8 detractors, 5 mitigators), Sudo Policies, SSHD Configuration, and SSH Keys (11 detractors, 11 mitigators) * Configurable score bands, factor weights (127 total), and fleet aggregation methods * Daily posture recalculation with snapshot history * Posture retention configuration with admin-enforced maximums * Console pages for fleet overview, per-server scores, and per-object detail views with radar charts, detractor/mitigator lists, and remediation guidance * API endpoints for posture data collection and querying * SSH key encryption detection for private keys ### Changed * Agent installer now includes `sysstat` package on all distributions for iostat/mpstat system metrics support ### Documentation * Initial documentation published (v1.0 milestone) * Added Quick Start guide * Added Agent Commands reference * Added Security Architecture documentation * Added Console Overview *** **Related**: [Console Overview](/concepts/concepts/console) | [Security Architecture](/concepts/concepts/security-architecture)