HeartSuite Core Secure Documentation

• 1: Getting Started
• 1.1: Before You Begin
• 2: Introduction and Overview
• 2.1: HeartSuite Core Secure Overview
• 2.2: Setup Overview
• 2.3: System Requirements
• 3: Obtaining and Installing HeartSuite Core Secure
• 3.1: Obtaining HeartSuite Core Secure
• 3.2: VM Preparation
• 3.3: Installing HeartSuite Core Secure – Part 1
• 3.4: Installing HeartSuite Core Secure – Part 2
• 4: Verifying Installation and Basic Setup
• 5: Allowlisting Programs
• 5.1: Allowlisting Basics
• 5.2: Using HeartSuite Core Secure Log
• 5.3: Using the Kernel Log
• 5.4: Batch Allowlisting Tools
• 6: Network and Remote Access
• 7: Script Launchers and Python Setup
• 7.1: How Script Launchers Work
• 7.2: Configuring Script Launchers
• 7.3: Included Script Launchers
• 8: Alert Configuration
• 9: Licensing and Subscription
• 10: Mode Switching and Lockdown
• 11: Advanced Configuration and Maintenance
• 11.1: Avoiding Configuration Gaps
• 11.2: Protecting During Maintenance
• 11.3: Adjusting the Cache Size
• 11.4: File Backup and Versioning
• 12: Troubleshooting and Logs
• 13: FAQs
• 14: Appendices

1 - Getting Started

Overview: This guide covers both the Cloud Path and the Local Path for getting HeartSuite Core Secure running, verified, and ready for allowlisting.

The 7-Phase Model

HeartSuite Core Secure guides you through seven phases:

1. System Verification — confirm HeartSuite Core Secure is active and in Setup Mode
2. Program Allowlisting — approve the programs your system needs
3. Script Launchers (if applicable) — configure Secure Script Launchers for interpreted scripts
4. File Access Allowlisting — approve file read and write access
5. Internet Access Allowlisting — approve internet destinations
6. Alert Configuration — set up at least one notification channel
7. Secure Mode — locked until phases 2-6 are complete

The Dashboard displays your current phase, pending event counts, and a Suggested Next Step at all times.

Cloud Path Quick Start

Users launching a pre-installed HeartSuite Core Secure cloud instance (AWS AMI, GCP image) boot directly into Setup Mode.

1. Launch your cloud instance and log in.

2. The Dashboard appears automatically on first login with a welcome message:

   HeartSuite Core Secure is active.
   Current mode: Setup Mode — events are logged, nothing is blocked.
   Suggested: Review 1 pending program event → [p] Programs
   

3. Phase 1 (System Verification) completes automatically — no manual steps required.

4. Follow the Suggested Next Step on the Dashboard to begin Phase 2: Program Allowlisting.

Local Path Quick Start

Users installing HeartSuite Core Secure on bare-metal or custom VMs follow a longer installation sequence before reaching the Dashboard.

Download and Install

1. Download the tar file from heartsecsuite.com.

2. Extract and run the installer (as root):

   tar xvf 6.18-HeartSuite-1.6.4.tar -m
   sudo bash heartsuite-install-bundle.sh
   

3. Reboot, then select the HeartSuite Core Secure kernel from the GRUB menu:

   reboot
   

   At GRUB: Advanced options for Debian GNU/Linux → Linux 5.19.6-HeartSuite-1.0

   If the GRUB menu does not show the HeartSuite Core Secure kernel, run update-grub and reboot again. See Installation for details.

OS Boot Setup

4. After booting into the HeartSuite Core Secure kernel, the management UI appears on the console automatically. The System Setup screen opens.

   Press [a] to run the setup step. The UI reboots the system when the step completes — select the HeartSuite Core Secure kernel from GRUB each time and repeat until the setup screen shows Setup Complete (usually 3–5 cycles). This builds the initial allowlist for startup programs, preventing boot issues when Secure Mode is activated later.

Verify and Proceed

5. Once the Installation screen confirms completion, the Dashboard shows your current phase. From here, the Cloud Path and Local Path merge — follow the Suggested Next Step to begin allowlisting.

The Dashboard

The Dashboard is your orientation point throughout the entire HeartSuite Core Secure journey. It displays:

• Safety Banner — current protection state (Setup Mode, Secure Mode, or Non-HS kernel)
• Phase Progress — which of the 7 phases are complete, in progress, or not started
• Pending/Denied counts — events grouped by category (Programs, File reads, File writes, Network)
• Suggested Next Step — one clear, actionable recommendation
• System Info Strip — kernel type, current mode, time in mode, lockdown status

The Suggested Next Step is always the recommended action. Follow it to proceed through each phase.

The Review Queues

The Dashboard organizes allowlisting into three review queues, each presented as a screen within the Dashboard:

• Programs queue ([p]) — review pending program execution events (Phase 2)
• File Access queue ([f]) — review pending file read and write events (Phase 4)
• Internet Access queue ([i]) — review pending network connection events (Phase 5)

The Suggested Next Step directs you to the queue that needs attention. Select it to navigate directly to the review screen. For browsing or editing existing allowlist entries, use the Allowlist screen ([a]).

Switching to Secure Mode

When phases 2-6 are complete, the Dashboard unlocks Phase 7 and shows Secure Mode activation as the Suggested Next Step. Activation requires typing YES (case-sensitive) to confirm. After confirmation, the Dashboard offers two reboot options:

• [r] Reboot — enforcement active, configuration remains editable
• [l] Reboot + Lockdown — enforcement active, configuration sealed with filesystem immutability

Both are valid configurations depending on your threat model. If the system does not boot correctly, reboot into the Non-HS kernel — the Dashboard resumes there and guides you through recovery.

Next Steps

• For full allowlisting guidance: Allowlisting
• For alert configuration (Phase 6): Alert Configuration
• For Lockdown after Secure Mode: Mode Switching
• For troubleshooting: Troubleshooting

1.1 - Before You Begin

Overview: Review system requirements and prerequisites before installing HeartSuite Core Secure, whether using a Cloud Path or Local Path.

System Requirements

• Operating System: Debian 11, 12, or 13; Ubuntu-derived; Alpine Linux; or RPM-based (RHEL, Fedora, CentOS, Rocky Linux, AlmaLinux, SUSE) — on x86 architecture.
• Access Level: Root access (sudo privileges).
• Skills: Basic familiarity with the Linux command line.

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

Cloud Path vs Local Path

• Cloud Path: Launch a pre-installed HeartSuite Core Secure cloud instance (AWS AMI, GCP image). No download or kernel installation required — you boot directly into Setup Mode and the Dashboard appears on first login.
• Local Path: Download the installation package from heartsecsuite.com, extract, install the HeartSuite Core Secure kernel, and complete the Installation screen setup through multiple reboot cycles before reaching the Dashboard.

Both paths merge at the Dashboard after Phase 1 (System Verification) is complete.

2 - Introduction and Overview

Overview: HeartSuite Core Secure enforces a default-deny policy — only explicitly approved programs can execute, access files, or make network connections. Any program not on the allowlist, including malware, is blocked at the kernel level before it can execute. The Dashboard guides you through a 7-phase journey from installation to Secure Mode, always showing your current progress and the suggested next step.

Key Topics

• HeartSuite Core Secure Overview — Core features, how it protects against malware, and the 7-phase model.
• Setup Overview — The setup process, modes (Setup vs. Secure), and how the Dashboard guides you.
• System Requirements — Compatible systems, kernel versions, and prerequisites.

For detailed installation steps, see Installation. HeartSuite Core Secure supports both Cloud (pre-installed) and Local (manual install) paths — both converge at the Dashboard after Phase 1 (System Verification).

2.1 - HeartSuite Core Secure Overview

Overview: HeartSuite Core Secure enforces a default-deny policy at the kernel level — only explicitly approved programs can execute, access files, or make network connections. Any program not on the allowlist is blocked before it can execute, including malware and zero-day attacks that detection-based tools might miss.

How HeartSuite Core Secure Works

HeartSuite Core Secure uses a modified Linux kernel that enforces an allowlist-based security model. No program can execute, access files, or make network connections unless explicitly approved by an administrator. Even if malware is downloaded to a HeartSuite Core Secure server, the kernel prevents it from running or causing damage.

The Dashboard is the central interface. It tracks your progress through a 7-phase setup journey, shows pending events that need review, and always suggests the next step.

The 7-Phase Model

Core Features

1. Program Allowlist

An allowlist entry defines what a program is permitted to do: which files it can access, which directories it can read or write, and which network connections it can make. The HeartSuite Core Secure kernel requires every program to have an allowlist entry before it is permitted to run.

The Dashboard review queues present pending events for approval:

• Programs queue ([p]) — programs attempting to execute
• File Access queue ([f]) — programs attempting to read or write files
• Internet Access queue ([i]) — programs attempting outbound connections

Each queue uses a tiered review model to manage volume efficiently:

• Tier 1: Individual events shown one at a time with full metadata (package name, description, category, maintainer, install date)
• Tier 2: Grouped events (e.g., “847 file reads from /usr/lib/python3/”) with a representative sample shown
• Tier 3: Informational summary of what is ahead before reviewing

File access is divided into read access and write access. Write access always includes read access. These are approved separately — approving a file read event grants read access; approving a file write event upgrades to write access.

The caching mechanism loads only a single allowlist entry into memory for a running program, even with thousands of concurrent instances, minimising impact on kernel memory.

2. Setup Mode and Secure Mode

HeartSuite Core Secure operates in two modes:

• Setup Mode: The kernel logs all denied actions without blocking them. Use this mode to build the allowlist by reviewing queues and approving legitimate programs and access patterns. The Dashboard guides this process.
• Secure Mode: The kernel enforces the allowlist. Programs without an allowlist entry are blocked. Programs that exceed their permissions are blocked.

Activating Secure Mode requires all review queues to be empty, alerts to be configured, and an active subscription. The Dashboard presents a precondition checklist and requires typing YES (case-sensitive) to confirm.

3. Lockdown

Lockdown protects the integrity of allowlist entries by making them immutable. Once applied, no changes can be made to the allowlist while the server is running — preventing attackers from modifying the security configuration, even with root access.

After activating Secure Mode, the Dashboard offers two reboot options: [r] Reboot (enforcement active, configuration remains editable) or [l] Reboot + Lockdown (enforcement active, configuration sealed with filesystem immutability). Lockdown cannot be reversed at runtime. To make changes, the Dashboard’s Maintenance screen ([t]) guides you through the correct maintenance path — including a guided 3-step process when Lockdown requires booting the Non-HS kernel.

Because access permissions are enforced inside the HeartSuite Core Secure kernel itself, HeartSuite Core Secure cannot be circumvented by any program or user, including root.

4. File Backup and Versioning

HeartSuite Core Secure automatically backs up files in designated directories and prevents all programs from accessing the backups — only HeartSuite Core Secure itself can reach them. The version manager can restore any version of a backed-up file, regardless of whether it was encrypted, deleted, or modified.

5. Secure Script Launchers

Allowlist entries can be created for interpreted code such as Python, PHP, and Perl. HeartSuite Core Secure provides Secure Script Launchers that identify the specific script being run when an interpreter is launched, enabling per-script access control with the same granularity as compiled programs.

Two Setup Paths

Cloud Path: Launch a pre-installed cloud instance. The Dashboard appears immediately. Phase 1 (System Verification) auto-completes. Proceed directly to the review queues.

Local Path: Download from heartsecsuite.com, extract, install, and boot the HeartSuite Core Secure kernel. Run hs-os-boot-setup through multiple reboots (the Dashboard shows a step counter). After Phase 1 completes, the Dashboard appears and both paths merge.

2.2 - Setup Overview

Overview: HeartSuite Core Secure must complete a guided setup journey in Setup Mode before it can enforce security in Secure Mode. This page explains why Setup Mode exists, what happens during each phase, and how to reach Secure Mode safely.

Why Setup Mode Is Necessary

HeartSuite Core Secure enforces a default-deny policy: every program, file access, and network connection must be explicitly approved before the system permits it. Immediately after installation, the allowlist is empty. If the system entered Secure Mode at this point, it would block the programs required for boot and shutdown, rendering the system inoperable.

Setup Mode solves this problem. In Setup Mode, HeartSuite Core Secure logs all activity without blocking anything. The administrator reviews events through the Dashboard queues, approves legitimate activity, and builds an allowlist that reflects the system’s actual workload. Once the allowlist is complete, the administrator transitions to Secure Mode with confidence that approved operations will continue uninterrupted.

Setup Mode is the default after installation. HeartSuite Core Secure’s automated backup system also operates during Setup Mode, providing an additional layer of protection even before enforcement begins.

The 7 Phases

HeartSuite Core Secure organizes the setup journey into seven phases. The Dashboard tracks progress through each phase and always displays a Suggested Next Step.

Cloud vs. Local Path

Cloud Path

Users who launch a pre-installed HeartSuite Core Secure cloud instance (AWS AMI, GCP image) boot directly into Setup Mode. Phase 1 completes automatically. The Dashboard appears on first login with the current system state and a Suggested Next Step. No manual verification is required.

Local Path

Users who install HeartSuite Core Secure on bare-metal or custom VMs follow a longer path:

1. Download and extract the installation package.
2. Prepare GRUB and install the HeartSuite Core Secure kernel.
3. Run hs-os-boot-setup, which handles multiple reboots with a step counter.
4. After Phase 1 completes, the Dashboard appears and the journey merges with the Cloud path.

Both paths converge at the Dashboard after Phase 1. From that point forward, the workflow is identical.

Setup Workflow

The following diagram shows the primary path through the Dashboard and the advanced CLI alternative.

graph TD
    A[Install HeartSuite Core Secure] --> B{Cloud or Local?}
    B -- Cloud --> C[Boot instance — Phase 1 auto-completes]
    B -- Local --> D["Run hs-os-boot-setup — multiple reboots"]
    D --> C
    C --> E[Dashboard appears — Suggested Next Step]
    E --> F["Phase 2: Programs queue — approve programs"]
    F --> G["Phase 3: Script Launchers — if applicable"]
    G --> H["Phase 4: File Access queue — approve file access"]
    H --> I["Phase 5: Internet Access queue — approve connections"]
    I --> J["Phase 6: Configure alerts"]
    J --> K["Phase 7: Activate Secure Mode"]
    K --> L["Lockdown: [r] Reboot or [l] Reboot + Lockdown"]
    L --> M{Maintenance needed?}
    M -- Yes --> N["Dashboard Maintenance wizard guides through steps"]
    N --> K
    M -- No --> O[System secured]

Switching to Secure Mode

When phases 2 through 6 are complete, Phase 7 unlocks on the Dashboard. The Suggested Next Step will prompt you to activate Secure Mode. The mode switch requires typing YES (case-sensitive) to confirm and displays an allowlist summary and pre-condition checklist before proceeding.

After activating Secure Mode, the Dashboard offers two reboot options: [r] Reboot (enforcement active, configuration remains editable) or [l] Reboot + Lockdown (enforcement active, configuration sealed with filesystem immutability). Both are valid configurations depending on your threat model. Lockdown can also be applied later from the Dashboard’s Mode Switch screen ([m]).

Maintenance in Secure Mode

To perform system maintenance after entering Secure Mode, select the Maintenance screen ([t]) from the Dashboard. The Dashboard detects whether Lockdown is active and guides you through the correct path:

• Without Lockdown: The Maintenance screen walks you through a safety checklist, switches to Setup Mode, and reboots. The HeartSuite Core Secure kernel stays active with logging and backups running. Make your changes, then return to Secure Mode from the Dashboard.
• With Lockdown: The Maintenance screen guides you through a 3-step process across two reboots — removing immutable flags on the Non-HS kernel, making changes, then returning to the HeartSuite Core Secure kernel to review new activity. The Dashboard resumes at the correct step after each reboot.

For full details, see Protecting During Maintenance.

2.3 - System Requirements

Overview: HeartSuite Core Secure requires an x86 Linux system running a supported distribution — Debian/Ubuntu-derived, Alpine, or RPM-based (RHEL, Fedora, CentOS, Rocky Linux, AlmaLinux, SUSE). It ships with two HeartSuite Core Secure kernels (5.19 and 6.18) and a set of tools that enforce allowlist-based security at the kernel level.

Supported Platforms

HeartSuite Core Secure supports Debian/Ubuntu-derived, Alpine, and RPM-based distributions (RHEL, Fedora, CentOS, Rocky Linux, AlmaLinux, SUSE, openSUSE) on x86.

Kernel

HeartSuite Core Secure is distributed with two HeartSuite Core Secure kernels based on mainline Linux: 5.19 and 6.18. One of these kernels must be booted for HeartSuite Core Secure to function. The Dashboard verifies kernel activation as part of Phase 1 (System Verification) and provides orientation on every boot.

3 - Obtaining and Installing HeartSuite Core Secure

Overview: HeartSuite Core Secure installation follows one of two paths depending on your deployment method. Both paths end at the Dashboard, where Phase 1 (System Verification) confirms that the system is ready for allowlisting.

Cloud Path

Launch a pre-configured cloud instance (e.g., AWS AMI, GCP image). The HeartSuite Core Secure kernel is already installed and Phase 1 (System Verification) auto-completes on first boot. The Dashboard appears immediately — skip ahead to the allowlisting queues.

Local Path

Download the HeartSuite Core Secure installer, run it, and reboot multiple times to build the initial allowlist of startup and shutdown programs. This path involves:

1. Obtaining HeartSuite Core Secure — Download the installer from the website.
2. VM Preparation — Configure GRUB settings for virtual machines on clouds.
3. Installation Part 1 — Run the installer and reboot to load the kernel.
4. Installation Part 2 — Auto-allowlist startup programs with hs-os-boot-setup.

After the final reboot cycle, the Dashboard appears and displays the Suggested Next Step to guide you into Phase 2 (Program Allowlisting).

3.1 - Obtaining HeartSuite Core Secure

Overview: HeartSuite Core Secure is distributed as a single tar file. Download it from the HeartSuite Core Secure website at heartsecsuite.com.

Access to the tar file via wget is disabled by the hosting provider. Use the download form on the website to obtain the file.

3.2 - VM Preparation

Overview: This step applies to the Local Path only. Cloud VMs provisioned from a pre-configured image do not require GRUB changes.

Installation of HeartSuite Core Secure requires rebooting several times. The installation procedure uses the GRUB boot loader, which can reference disks by labels or UUIDs. Using labels on cloud deployments can result in boot failures. Edit the GRUB settings for VMs provisioned in the cloud before proceeding.

Configuring GRUB Settings

Comment out the following line in /etc/default/grub:

GRUB_DISABLE_LINUX_UUID=true

by preceding it with a # symbol:

#GRUB_DISABLE_LINUX_UUID=true

Then rebuild GRUB:

# /sbin/update-grub

3.3 - Installing HeartSuite Core Secure – Part 1

Overview: Run the installer bundle and reboot to load the HeartSuite Core Secure kernel. This is the first step of Phase 1 (System Verification) on the Local Path.

Extract the Distribution

Untar the distribution tar file:

tar xvf 6.18-HeartSuite-1.6.4.tar -m

Run the Installer

Run the installer from the extracted directory (as root):

sudo bash heartsuite-install-bundle.sh

The installer sets up the HeartSuite Core Secure kernel, tools, and management UI. When it finishes, it displays === Bundle Installation Complete ===.

Reboot into the HeartSuite Core Secure Kernel

Reboot the system:

reboot

When the GRUB menu appears, select the HeartSuite Core Secure kernel:

1. Select Advanced options for Debian GNU/Linux
2. Select Debian GNU/Linux, with Linux 5.19.6-HeartSuite-1.0

After boot, the HeartSuite Core Secure management UI appears on the console. The Setup Wizard starts automatically — proceed to Installation Part 2.

If the Reboot Fails

If the system does not reboot or hangs, try these steps:

1. Verify the installer completed without errors before rebooting.
2. Check GRUB configuration for VMs (uncomment GRUB_DISABLE_LINUX_UUID if needed and run update-grub).
3. Boot into recovery mode and run fsck to check file systems.
4. After a successful boot, the Dashboard confirms the HeartSuite Core Secure kernel is loaded. The Safety Banner shows the current mode and the System Info Strip shows “Kernel: HS”.

3.4 - Installing HeartSuite Core Secure – Part 2

Overview: After rebooting into the HeartSuite Core Secure kernel, build the initial allowlist of startup and shutdown programs. This completes Phase 1 (System Verification) on the Local Path. The Dashboard then appears and guides you into Phase 2 (Program Allowlisting).

Building the Initial Allowlist

After booting into the HeartSuite Core Secure kernel, the management UI appears on the console automatically. The System Setup screen opens on first boot.

Each cycle follows the same pattern:

1. Press [a] to run the setup step — the UI scans startup and shutdown logs and adds the programs it finds to the allowlist.
2. When the step completes, the UI reboots the system automatically (5-second countdown — press any key to cancel if needed).
3. At the GRUB menu, select the HeartSuite Core Secure kernel again.
4. The System Setup screen resumes at the next step automatically.

Repeat until the setup screen shows Setup Complete in green — no manual commands are needed between cycles.

After three to five cycles (depending on the distribution), the setup screen confirms that all startup and shutdown programs have been allowlisted.

After Phase 1 Completes

When the setup screen shows the completion message, press [q] to return to the Dashboard. The Dashboard displays your current progress and the Suggested Next Step guides you into Phase 2 (Program Allowlisting).

If the UI Does Not Appear After Boot

If the management UI does not appear on the console after booting into the HeartSuite Core Secure kernel:

1. Switch to TTY2 (Ctrl+Alt+F2), log in as root, and check the service:

   systemctl status heartsuite-ui.service
   

2. Verify the HeartSuite Core Secure kernel is loaded:

   uname -r
   

   Expected output: 5.19.6-HeartSuite-1.0
3. If the wrong kernel booted, reboot and select the correct entry from the GRUB menu.

If the Setup Screen Does Not Progress

If after several cycles the setup screen does not show the completion message:

1. Check the Dashboard’s Programs review queue ([p]) for any pending events and approve missing programs.
2. Verify the HeartSuite Core Secure kernel is loaded (the Dashboard System Info Strip shows “Kernel: HS”).

4 - Verifying Installation and Basic Setup

Overview: Phase 1 (System Verification) confirms that HeartSuite Core Secure is active and the system is ready for allowlisting. On most paths, this phase completes automatically.

What Phase 1 Checks

System Verification validates the following conditions:

• The HeartSuite Core Secure kernel is loaded and active
• The system is in Setup Mode (logging only, nothing blocked)
• Core HeartSuite Core Secure services are running
• The allowlist database is accessible

These checks confirm that the system is ready. No user action is required — Phase 1 completes automatically when all conditions are met.

Cloud vs Local Verification

Cloud Path: When you launch a pre-installed HeartSuite Core Secure cloud instance, Phase 1 completes automatically on first boot. The Dashboard appears with a welcome message confirming HeartSuite Core Secure is active and suggesting the next step.

Local Path: After completing the local installation process (download, GRUB preparation, kernel install, hs-os-boot-setup with its multiple reboots), the Dashboard appears once Phase 1 conditions are met. Both paths merge at the Dashboard after Phase 1.

Verifying via the Dashboard

The Dashboard provides immediate verification of activation, current mode, and phase status. It shows:

• Safety Banner: Displays current system state at the top of the screen
• Phase Progress: Shows Phase 1 as Complete, In Progress, or Not Started
• System Info Strip: Displays kernel type, current mode, time in mode, and lockdown status
• Suggested Next Step: Directs you to begin allowlisting once verification is complete

No manual verification command is required. The Dashboard surfaces HeartSuite Core Secure state automatically.

Safety Banner States

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

System Info Strip

Below the Safety Banner, the System Info Strip provides orientation at a glance:

Kernel: HS    Mode: Setup — active for 3d 7h    Lockdown: —

• Kernel: HS (HeartSuite Core Secure kernel) or Non-HS (standard kernel)
• Mode: Setup or Secure, with time in current mode
• Lockdown: — (Setup Mode), Not applied (Secure Mode without Lockdown), or Applied (Secure Mode with Lockdown)

What to Do if Verification Fails

If Phase 1 does not complete, or the Safety Banner shows a state you did not expect (for example, “NON-HS KERNEL” when you intended to boot HeartSuite Core Secure):

1. Check the Dashboard’s System Info Strip — it shows the kernel type (HS or Non-HS). If it shows Non-HS, reboot and select the HeartSuite Core Secure kernel from the GRUB menu.

2. Check that the HeartSuite Core Secure systemd service is running:

   systemctl status heartsuite
   

3. For local installations, verify that all hs-os-boot-setup steps completed. hs-os-boot-setup uses a step counter across reboots — run it again and check the output.

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, we’re happy to help — contact support at support@heartsecsuite.com.

dmesg | grep HEARTSUITE

5 - Allowlisting Programs

Overview: Allowlisting defines which programs can run, which files they can access, and which network destinations they can reach. The Dashboard guides you through each allowlisting phase and tracks your progress.

graph TD
    A[Dashboard] --> B[Phase 2: Programs queue]
    A --> C[Phase 4: File Access queue]
    A --> D[Phase 5: Internet Access queue]
    B --> E[Approve or skip each event]
    C --> E
    D --> E
    E --> F[Dashboard updates pending counts]

Allowlisting spans three phases of the HeartSuite Core Secure setup process:

• Phase 2 – Program Allowlisting ([p]): Approve which programs are permitted to execute.
• Phase 4 – File Access Allowlisting ([f]): Approve which files and directories each program can read or write.
• Phase 5 – Internet Access Allowlisting ([i]): Approve which outbound internet destinations each program can reach.

The Dashboard is the entry point for all three phases. It shows pending event counts for each queue and provides a Suggested Next Step that directs you to the queue that needs attention. Each review queue is a screen within the Dashboard that uses a tiered model: individual events with full metadata (Tier 1), grouped events with samples (Tier 2), and informational summaries (Tier 3).

Key Guides

• Allowlisting Basics – Core procedures for reviewing and approving programs, file access, and network connections.
• Using the HeartSuite Core Secure Log – Advanced troubleshooting with the HeartSuite Core Secure activity log.
• Using the Kernel Log – Fallback log access for events not captured in the HeartSuite Core Secure log.
• Batch Allowlisting Tools – Legacy scripts and advanced utilities for bulk allowlisting.

5.1 - Allowlisting Basics

Overview: HeartSuite Core Secure requires you to allowlist programs before they can execute, access files, or make network connections. The Dashboard and its review queues walk you through this process with full metadata and tiered grouping.

How Allowlisting Works

In Setup Mode, HeartSuite Core Secure logs every program execution, file access attempt, and outbound network connection without blocking anything. These logged events populate three review queues visible from the Dashboard:

• Programs queue ([p]) – programs that attempted to execute
• File Access queue ([f]) – programs that attempted to read or write files
• Internet Access queue ([i]) – programs that attempted outbound connections

The Dashboard shows pending event counts for each queue and provides a Suggested Next Step directing you to the queue that needs attention first.

The Review Process

Starting a Review

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

Single-Key Actions

The footer shows the primary actions available at any point:

Two additional keys appear contextually, not in the footer:

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, HeartSuite Core Secure 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.

Sort Cohort Labels

Within each queue, programs are grouped under cohort headers in the sidebar. These groups determine the order you encounter events, 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.

Tiered Review Model

The review queues use a tiered model to handle large numbers of events without requiring blind bulk approval. Volume is managed through intelligent grouping, not through approving things you cannot see.

Tier 1 – Individual Review

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

Program attempted to execute:
/usr/bin/nano
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?

Tier 2 – Grouped Review

Related events are grouped together (e.g., “847 file reads from /usr/lib/python3/”). HeartSuite Core Secure shows a sample of the grouped events so you can confirm the grouping makes sense before approving. The [v] View all option is shown inline on the grouped prompt for users who want complete visibility before approving.

Tier 3 – Informational Summary

When the volume of remaining events is large, HeartSuite Core Secure 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 (Phase 2)

When a program executes without an allowlist entry, HeartSuite Core Secure logs it. The Programs queue presents these events for review. Example log entry:

[Setup Notice - Add program to Allowlist?] Not Whitelisted: /usr/bin/nano

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.

File Access Queue (Phase 4)

After a program is allowlisted, HeartSuite Core Secure begins logging every file it accesses. Programs typically access shared libraries, configuration files, and data files. The File Access queue presents these events with two distinct permission levels:

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

Example review prompt for a file read event:

/usr/bin/python3 attempted to read:
/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 event:

/usr/bin/journald attempted to write:
/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]).

Internet Access Queue (Phase 5)

Programs that attempt 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:

/usr/bin/curl attempted an outbound connection:
Destination: 93.184.216.34 -- example.com (Edgecast, US)
Program:     curl 7.88.1-10 -- command line tool for transferring data with URL syntax
Attempts:    7

This destination has not been allowlisted for this program.

[a] Approve this connection for /usr/bin/curl
[s] Skip for now

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 program events resolved.
Returning to Dashboard…

The Dashboard automatically updates pending counts as you work. Allow several days to a week of observation in Setup Mode to capture events from systemd timers, cron jobs, and infrequent services before proceeding to Secure Mode.

Review Queues in Secure Mode

In Secure Mode the review queues are read-only. [a] and [s] do nothing — you cannot approve events while enforcement is active. The queues show denied events (actions HeartSuite Core Secure blocked), not pending events awaiting review.

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

Advanced: Manual Allowlist Management

For users who prefer direct CLI manipulation, hs-manage-allowlist provides a browser and editor for existing allowlist entries. See its built-in help:

# hs-manage-allowlist --help

5.2 - Using HeartSuite Core Secure Log

Overview: The Dashboard and its review queues are the primary way to review and resolve permission events. The HeartSuite Core Secure activity log (/.hs/sys/hs-activity-log.txt) is available for advanced troubleshooting and for understanding what the review queues process behind the scenes.

Dashboard Review Tools (Primary)

The Dashboard shows pending event counts for each queue and provides a Suggested Next Step. Select a queue to begin reviewing.

The three review queues — Programs ([p]), File Access ([f]), and Internet Access ([i]) — parse log data automatically, enrich it with package metadata, and present events through the tiered review model. You do not need to read raw log files to complete allowlisting.

For details on the review process, single-key actions, and the tiered model, see Allowlisting Basics.

The HeartSuite Core Secure Activity Log (Advanced)

The activity log at /.hs/sys/hs-activity-log.txt records all permission events in text format. It is useful for:

• Confirming that a specific program or file access was logged
• Troubleshooting when the Dashboard shows zero pending events but a program still fails
• Scripting and automation workflows that need raw event data

Log Message Formats

Program execution events:

[Setup Notice - Add program to Allowlist?] Not Whitelisted: /usr/bin/nano

File access events:

[Setup Notice - Add to Allowlist?] File Access Attempt Logged: Program: /usr/bin/nano; File: /etc/ld.so.cache

Network connection events:

[Setup Notice - Add to Network Allowlist?] Network Connection Attempt Logged by /usr/bin/wget; IP: 45.60.22.168

Viewing the Log

The log requires root access to read:

# cat /.hs/sys/hs-activity-log.txt

To filter for specific programs:

# grep nano /.hs/sys/hs-activity-log.txt

When to Use the Raw Log

5.3 - Using the Kernel Log

Overview: The Dashboard and its review queues automatically process kernel log events alongside HeartSuite Core Secure log events. The kernel log (dmesg) serves as a fallback for advanced troubleshooting when events do not appear in the HeartSuite Core Secure activity log.

Dashboard Handles Kernel Events Automatically

The Dashboard’s review queues (Programs [p], File Access [f], Internet Access [i]) collect events from both the HeartSuite Core Secure activity log and the kernel log. There is no need to read dmesg output manually during routine allowlisting — all events appear in the appropriate review queue with full metadata.

For details on the review process, see Allowlisting Basics.

When to Use the Kernel Log Directly

Depending on the distribution, some permission events may appear only in the kernel log rather than in /.hs/sys/hs-activity-log.txt. The kernel log is useful as a fallback when:

• A program fails but no corresponding event appears in the HeartSuite Core Secure activity log
• The HeartSuite Core Secure activity log has been cleared or rotated
• Troubleshooting requires correlating HeartSuite Core Secure events with other kernel messages

Reading HeartSuite Core Secure Messages from dmesg

To extract only HeartSuite Core Secure-related messages from the kernel log:

# dmesg | grep HEARTSUITE

The output format matches the HeartSuite Core Secure activity log entries. For example:

[Setup Notice - Add program to Allowlist?] Not Whitelisted: /usr/bin/nano
[Setup Notice - Add to Allowlist?] File Access Attempt Logged: Program: /usr/bin/nano; File: /etc/ld.so.cache
[Setup Notice - Add to Network Allowlist?] Network Connection Attempt Logged by /usr/bin/wget; IP: 45.60.22.168

Recommended Approach

Allow several days to a week of observation in Setup Mode. Systemd timers, cron jobs, and infrequent services may not generate events until they run. The review queues accumulate these events automatically as they occur.

5.4 - Batch Allowlisting Tools

Overview: The Dashboard review queues handle high-volume allowlisting through Tier 2 grouped review, which is the modern equivalent of batch processing. Legacy batch scripts remain available for advanced users and automation workflows.

Tier 2 Grouped Review (Primary)

The review queues group related events automatically. For example, when a program generates hundreds of file read events from the same directory tree, Tier 2 presents them as a single group with a sample of the individual entries. This allows directory-level approval without reviewing each file individually – and without blind bulk approval, because a sample is always shown.

To start a grouped review session, select the queue with pending events from the Dashboard. The [v] View all action is always available within a grouped review for users who want complete visibility before approving.

For details on the tiered model and single-key actions, see Allowlisting Basics.

batch_record_add.py (Advanced / Legacy)

For automation workflows or environments where scripted allowlisting is preferred, the batch_record_add.py utility creates allowlist entries from the HeartSuite Core Secure activity log in bulk. This tool is located in /.hs/sys/.

# /.hs/sys/batch_record_add.py

hs-manage-allowlist (Advanced)

The hs-manage-allowlist command provides a browser and editor for existing allowlist entries. It is not a review tool – it operates on entries that have already been created. Use it to inspect, modify, or remove existing entries:

# hs-manage-allowlist --help

Root Access Considerations

The /.hs/sys directory is owned by root. When working with batch tools or direct allowlist management, start a root shell to avoid permission issues:

# sudo -s

Exit the root shell by pressing Ctrl-D when finished.

Choosing the Right Approach

6 - Network and Remote Access

Overview: HeartSuite Core Secure blocks all outbound network connections by default. No program can connect to any destination unless you have explicitly approved it. The Dashboard’s Internet Access queue ([i]) guides you through reviewing and approving destinations for each program as part of Phase 5.

How Network Allowlisting Works

In Setup Mode, HeartSuite Core Secure logs every outbound connection attempt without blocking it. These events appear in the Dashboard’s Internet Access queue. In Secure Mode, 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.

Using the Internet Access Queue

Select the Internet Access queue from the Dashboard ([i]). Each event shows:

• Program — the full path and package metadata (name, version, description, maintainer)
• Destination — the IP address with reverse DNS hostname (e.g., 93.184.216.34 — example.com (Edgecast, US))
• Attempts — how many times this connection was attempted

Example review prompt:

/usr/bin/curl attempted an outbound connection:
Destination: 93.184.216.34 — example.com (Edgecast, US)
Program:     curl 7.88.1-10 — command line tool for transferring data with URL syntax
Attempts:    7

This destination has not been allowlisted for this program.

[a] Approve this connection for /usr/bin/curl
[s] Skip for now

Press [a] to approve the destination for that program, or [s] to skip it for later. The Dashboard updates the pending count as you work.

When the Internet Access queue is empty, the Dashboard marks Phase 5 as complete and updates the Suggested Next Step.

Walkthrough: Allowlisting wget

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

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

produces a log event:

[Setup Notice - Add to Network Allowlist?] Network Connection Attempt Logged by /usr/bin/wget; IP: 45.60.22.168

This event appears in the Internet Access queue with the destination 45.60.22.168 — example.com. After you approve it, the same wget command completes without generating a new event for that IP address.

Reviewing Existing Network Permissions

To browse or edit network destinations that have already been approved, use the Allowlist screen ([a]) from the Dashboard. Existing entries are grouped by category — Programs, File Access, and Internet Access — so you can quickly find and modify network permissions.

Advanced: Direct Allowlist Management

For automation workflows or bulk changes, hs-manage-allowlist provides direct CLI access:

# hs-manage-allowlist add -x /usr/bin/wget -n 45.60.22.168

Or look up the entry number first:

# hs-manage-allowlist list | grep wget
277
/usr/bin/wget
# hs-manage-allowlist add -r 277 -n 192.142.166.196

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

7 - Script Launchers and Python Setup

Overview: Without Secure Script Launchers, every Python or Perl 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 as Phase 3 when script interpreters are detected on the system.

Key Guides

Dive into specific setup and reference areas:

• How Script Launchers Work - Security rationale and how Secure Script Launchers enforce script permissions.
• Configuring Script Launchers - Direct use for testing and permanent symbolic link setups.
• Included Script Launchers - List of available launchers for Python, Perl, PHP, etc.

7.1 - How Script Launchers Work

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.

The Problem

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.

The Solution

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

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

Using Launchers

HeartSuite Core Secure provides Secure Script Launchers for each supported interpreter (e.g., hs-python-launcher). Once activated via the Dashboard’s Launchers screen ([l]), 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.

7.2 - Configuring Script Launchers

Overview: When the Dashboard detects script interpreters (Python, Perl, PHP) in use without launcher configuration, it presents Phase 3 as the Suggested Next Step. The Launchers screen ([l]) shows detected interpreters and activates launchers in one step.

Dashboard-Guided Setup

From the Dashboard, select the Launchers screen ([l]). The screen shows two panels:

• 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 status panel 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. HeartSuite Core Secure 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 result panel 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. Phase 3 is marked complete automatically.

If No Script Events Are Detected

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

No script interpreter log events detected.
You may proceed to the next phase without activating any launchers.

Phase 3 is not required if your system does not use script interpreters. The Dashboard updates the Suggested Next Step to proceed to Phase 4.

Skipping Launcher Setup

Press [s] to skip without activating. HeartSuite Core Secure notifies you:

Script launcher activation skipped.
Interpreters will remain blocked in Secure Mode until approved.

You can return to the Launchers screen ([l]) at any time to activate launchers before switching to Secure Mode.

Advanced: Testing a Launcher Directly

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

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

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

7.3 - Included Script Launchers

Overview: HeartSuite Core Secure ships with Secure Script Launchers for common interpreters. The Dashboard presents these during Phase 3 (if applicable) 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 us at support@heartsecsuite.com — we’re happy to help.

8 - Alert Configuration

Overview: Phase 6 requires at least one push alert channel to be configured before Secure Mode can be activated. Alerts notify you of security-relevant events when no one is connected to the Dashboard. On a stable system in Secure Mode, expect roughly 1–5 email alerts per week — alert volume is intentionally low.

How Alerts Work

Alerts are a push channel for events that warrant immediate attention. They are not a secondary log stream and not a replacement for the Dashboard.

Alerts are suppressed entirely in Setup Mode. Setup Mode is a high-volume observation phase — logging everything without blocking. Alerting during this phase would produce constant noise before the allowlist is complete. Alerts become active only when Secure Mode is enabled.

Configuring Alerts

From the Dashboard, select the Alert Settings screen ([e]). The screen has two tabs: Email and Fleet.

Email Tab

Configure SMTP credentials to receive email alerts directly. Required fields:

• Node ID — defaults to the system hostname; set a recognisable identifier (e.g., prod-web-03) so email subjects immediately identify the source machine when managing multiple servers
• SMTP server and Port (default 587)
• Sender and Recipient addresses
• Password (masked on entry; never displayed after saving)

Select Save to store the configuration. HeartSuite Core Secure validates all fields but does not attempt a live connection at save time. Select Test to send a test email — this is the only moment where SMTP connectivity is verified. If the test fails, the exact SMTP error code is shown:

Test email failed: [535 Authentication credentials invalid]

Check your credentials and try again. No alerts have been sent.

Once configured, the tab shows current settings with the password displayed as (set). Select Edit to modify — the password field is always blank when editing. You must re-enter the password to prevent credentials from appearing in the terminal scroll buffer.

Fleet Tab

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

Syslog — A toggle (Enabled/Disabled). When enabled, HeartSuite Core Secure writes all alert events to the system log via /dev/log, using the heartsuite-alert ident, LOG_AUTH facility, and LOG_WARNING severity. No additional configuration is needed on the HeartSuite Core Secure node. After enabling, the Alert Settings screen provides an rsyslog forwarding rule example for your SIEM.

Verify syslog delivery with:

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

To forward to a SIEM, configure an rsyslog output rule in /etc/rsyslog.d/heartsuite.conf. 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

Webhook — Enter an HTTPS URL. HeartSuite Core Secure POSTs a JSON payload to this URL on every alert event. HTTP (non-TLS) URLs are rejected. Example payload:

{
  "node_id":    "prod-web-03",
  "event_type": "new_program_blocked",
  "timestamp":  "2026-03-31T14:22:00Z",
  "mode":       "Secure Mode",
  "lockdown":   false,
  "paths":      ["/tmp/dropper", "/tmp/payload"],
  "count":      2
}

To receive this payload, create an integration in your incident management tool and paste the endpoint URL into the Webhook field:

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

Status JSON — A passive monitoring surface at /.hs/sys/hs-status.json, updated every 60 seconds. Ansible, Nagios, and Zabbix can read this file via SSH pull. No configuration required — always active when the alert daemon is running. This is read-only; it does not push notifications.

When Phase 6 is complete — at least one push channel configured — the Dashboard marks Phase 6 as complete and unlocks Phase 7 (Secure Mode).

What Triggers an Alert

Tier 1 — Administrative State Changes

These events fire immediately on every configured channel, regardless of accumulation windows or digest mode:

Tier 2 — Anomalous Activity in Secure Mode

These events apply a threshold filter and are active in Secure Mode only:

Never alerted under any circumstances:

• Any event in Setup Mode
• 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

How Alerts Are Delivered

Email — 5-Minute Accumulation Window

Tier 2 events are grouped before delivery. A dropper that installs 40 payloads in 90 seconds produces one email — “40 previously unseen programs blocked in 90 seconds” — 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 Tier 2 event of a given type
• Additional events of the same type within that window are added to the pending bundle
• At window close, one email is dispatched covering all accumulated events
• Events of different types accumulate independently — a network burst does not delay a file modification alert

Digest mode: If more than 3 Tier 2 emails are dispatched within a single hour, HeartSuite Core Secure switches to digest mode for the remainder of that hour. All further Tier 2 events are queued and delivered as one digest email at the hour’s end. Tier 1 events are never held — mode switches and lockdown changes are always delivered immediately.

The 5-minute window and hourly cap are fixed, not user-configurable.

Syslog and Webhook — Immediate

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

9 - Licensing and Subscription

Overview: A subscription is required to activate Secure Mode (Phase 7). The Dashboard shows your current subscription status alongside phase progress and alerts.

Subscription

A subscription is required before you can switch from Setup Mode to Secure Mode. Phase 7 (Secure Mode) is locked until phases 2-6 are complete and a valid subscription is activated.

The subscription is a simple text file. One subscription can cover up to 9999 servers – at the time of purchase, you specify how many servers the subscription covers. You can purchase additional subscriptions if needed.

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. For example:

# sudo cp MyCompany_HS_subscription_3-10-26.txt /.hs/sys/HS_license.txt

After copying the subscription file, activate it using hs-activate-subscription. The command requires the IP address of the HeartSuite Core Secure Activation Server and the port number (6121). At the time of this writing, the IP is 172.232.3.4. Check the HeartSuite Core Secure website for current connection details.

# sudo /.hs/sys/hs-activate-subscription 172.232.3.4 6121

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

Dashboard Subscription Status

The Dashboard shows subscription status when it requires attention — an expired subscription appears as a warning in the reference panel with a direct link to the upgrade page. A valid, active subscription is not displayed separately; the absence of a warning confirms that the subscription is in good standing. Phase 7 (Secure Mode) unlocks when phases 2-6 are complete.

10 - Mode Switching and Lockdown

Overview: HeartSuite Core Secure guides you through mode switching via the Dashboard. The system state depends on which kernel is booted and whether Lockdown is applied — the Dashboard shows you the current state and suggests the appropriate next action.

System States

HeartSuite Core Secure has two modes: Setup Mode and Secure Mode. Both run on the HeartSuite Core Secure kernel. Lockdown is a separate decision you make after activating Secure Mode — it seals the configuration with filesystem immutability. Both running Secure Mode without Lockdown and running Secure Mode with Lockdown are valid configurations depending on your threat model. Lockdown can only be applied within Secure Mode; it is not a separate mode. Booting the original non-HS kernel is not a HeartSuite Core Secure mode at all; it is the system running without HeartSuite Core Secure.

In Setup Mode and Secure Mode, HeartSuite Core Secure’s kernel module is active. Backups, logging, and the Dashboard all function normally in both. Booting the non-HS kernel means HeartSuite Core Secure is completely absent — the module is not loaded, no enforcement or logging takes place, and backups do not run.

The Dashboard provides orientation for these states. The Safety Banner displays the current state, and the Suggested Next Step guides you toward the appropriate action.

Safety Banner States

The Dashboard displays a Safety Banner reflecting the current system state:

Setup vs Secure Mode

At some point, you need to switch to Secure Mode to prevent malicious programs from starting, or to restrict the files and remote computers such programs may access. Secure Mode activation (Phase 7) is locked until all prior phases (2 through 6) are finished. The Dashboard tracks your progress through these phases and will indicate when Secure Mode activation is available as the Suggested Next Step.

If you have not added the necessary access permissions or network address permissions to allowlist entries, HeartSuite Core Secure will actively block programs from accessing those files and network addresses when you switch to Secure Mode.

Once HeartSuite Core Secure has been configured, consider continuing in Setup Mode for several days. During that time, the review queues will capture additional file and network access activity. This information is valuable for further allowlist configuration before activating Secure Mode.

When installing new software, you must return to Setup Mode. For example, the Debian package manager dpkg creates temporary directories during installation. In Secure Mode, this generates a permission error and the installation halts. The temporary directory is removed before it can be added to an allowlist entry. Switch to Setup Mode before using dpkg, add any additional access permissions needed, then return to Secure Mode.

graph TD
    A["Dashboard: Phase Progress complete"] --> B["Review queues empty — ready for Secure Mode"];
    B --> C["Dashboard Mode Switch screen — type YES to confirm"];
    C --> D{"Choose reboot option"};
    D --> |"[r] Reboot"| E["Secure Mode active\nConfiguration remains editable"];
    D --> |"[l] Reboot + Lockdown"| F["Secure Mode + Lockdown active\nConfiguration sealed"];
    E --> G{Maintenance needed?};
    F --> G;
    G --> |"No Lockdown"| H["Maintenance [t] → safety checklist → switch to Setup Mode\nHeartSuite Core Secure still active — logs, backups, Dashboard all run"];
    G --> |"Lockdown active"| I["Maintenance [t] → guided 3-step process\nStep 1: Boot Non-HS kernel, [u] remove flags\nStep 2: Make changes\nStep 3: Boot HS kernel, review new activity"];
    H --> J["Make changes, update allowlist from Dashboard"];
    I --> J;
    J --> N["Return to Secure Mode from Dashboard"];
    N --> D;

Switching Between Modes

Dashboard-First Mode Switch

The Dashboard is the primary interface for mode switching. When all preconditions are met, the Suggested Next Step will offer Secure Mode activation. The precondition checklist includes:

• All review queues are empty (Programs [p], File Access [f], Internet Access [i])
• Boot configuration is complete (hs-os-boot-setup)
• Phase 7 is unlocked (phases 2 through 6 complete)

When preconditions are satisfied, the Dashboard presents the activation option.

Activating Secure Mode

From the Dashboard, select the Mode Switch screen ([m]). The screen displays a precondition checklist, an observation period summary, and a review of your allowlist. When all preconditions are met, type YES (case-sensitive) to confirm activation.

After confirming, the Dashboard offers two reboot options:

• [r] Reboot — enforcement active, configuration remains editable
• [l] Reboot + Lockdown — enforcement active, configuration sealed with filesystem immutability

Both are valid configurations depending on your threat model. HeartSuite Core Secure will boot in Secure Mode from that point forward until you switch back to Setup Mode.

Returning to Setup Mode

From the Dashboard, use the Mode Switch screen ([m]) to return to Setup Mode for maintenance. You must return to Setup Mode before installing packages or making configuration changes that Secure Mode would block.

Advanced: CLI Mode Switch

When booted into a Non-HS kernel (where the Dashboard’s mode switch is not available), use the CLI to pre-configure the mode for the next HeartSuite Core Secure kernel boot:

# sudo hs-mode-switch setup

Lockdown: Securing Your System in Secure Mode

Overview: Lockdown seals HeartSuite Core Secure’s configuration with filesystem immutability, preventing tampering during production operation. The Dashboard displays the current lockdown status and provides the Suggested Next Step for managing it.

Lockdown is a separate decision you make after activating Secure Mode. Both running Secure Mode without Lockdown and running Secure Mode with Lockdown are valid configurations — the choice depends on your threat model. The table below summarises what changes when you apply Lockdown.

What Lockdown Does

Once Lockdown is engaged, HeartSuite Core Secure prevents any changes to the allowlist entries and other settings. Lockdown makes HeartSuite Core Secure configuration files and directories immutable using chattr +i. For additional hardening, the lockdown script can optionally be configured to make tools like rm non-executable — see Avoiding Configuration Gaps.

Once Lockdown is engaged, the HeartSuite Core Secure kernel disables chattr entirely — no user or program, including root, can change the immutability flags. This means no allowlist entries, configuration files, or protected directories can be modified, deleted, or added while Lockdown is active.

Lockdown lasts until the next time your server is booted; there is no direct way to turn Lockdown off. Lockdown cannot be engaged in Setup Mode; if you attempt to do so, an error message is written to the kernel log. The filesystem immutability applied by Lockdown via chattr +i is a filesystem-level attribute, not a kernel-module state. This means that immutable flags set during Lockdown persist across reboots, including reboots into the Non-HS kernel. If you boot the Non-HS kernel for maintenance after Lockdown was active, you must run hs-unlock before attempting to modify any files that were made immutable.

Automatic Lockdown on Boot

Lockdown can be configured to re-engage automatically on every HeartSuite Core Secure kernel boot. When you choose [l] Reboot + Lockdown from the Mode Switch screen, the startup script applies Lockdown each time the HeartSuite Core Secure kernel starts. Once enabled, rebooting will always engage Lockdown before you can prevent it.

The Dashboard’s Maintenance screen ([t]) detects automatic re-engagement and presents a guided choice: [d] Disable automatic Lockdown re-engagement or [k] Keep it. You do not need to edit any scripts manually. To disengage Lockdown when automatic re-engagement is active, boot to the Non-HS kernel; this procedure is discussed in Protecting During Maintenance.

Restoring Mutability After Lockdown

Files and directories may be made mutable again once Lockdown is no longer active. The Dashboard’s Maintenance screen ([t]) handles this automatically during the guided maintenance process — Step 1 of 3 offers [u] Remove immutable flags. For manual recovery outside the maintenance wizard, run hs-unlock from the CLI.

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

You must have either physical or serial port access to your server to reboot to the Non-HS kernel — attackers cannot remotely reboot to bypass HeartSuite Core Secure, providing another layer of defense.

Advanced: Lockdown CLI Tools

The underlying CLI tools are available for advanced configuration and automation:

• hs-activate-lockdown — makes files and directories immutable, then engages the lockdown program. Strongly recommended over running hs-lockdown directly.
• hs-lockdown — engages lockdown without setting immutability flags. Use hs-activate-lockdown instead for complete protection.
• hs-unlock — reverses all immutability set by Lockdown so you can make configuration changes.
• hs-unlock-progs — restores mutability for HeartSuite Core Secure files only (subset of what hs-unlock does).

11 - Advanced Configuration and Maintenance

Overview: Use these procedures to configure advanced settings and perform maintenance safely, avoiding security gaps and protecting against attacks. The Dashboard displays the current system state — including lockdown status — and provides the Suggested Next Step throughout maintenance.

Maintenance is a time period during which you temporarily reduce HeartSuite Core Secure’s protection to make changes. It is not a separate mode. HeartSuite Core Secure has two modes: Setup Mode and Secure Mode. During maintenance, you either switch to Setup Mode or boot the Non-HS kernel depending on whether Lockdown is active — the Dashboard’s Maintenance screen ([t]) detects this automatically and guides you through the correct path.

The Maintenance screen appears only when the system is in Secure Mode, Secure Mode + Lockdown, or on the Non-HS kernel. It is not shown in Setup Mode — because in Setup Mode, you are already in the maintenance-ready state and the Dashboard’s review queues and Suggested Next Step are the workflow.

Key Maintenance Areas

Explore detailed guides for specific tasks:

• Avoiding Configuration Gaps - Handling maintenance tools and broad permissions.
• Protecting During Maintenance - Secure practices for updates, backups, and access control.
• File Backup and Versioning - Automatic backups for designated directories and version restoration to protect against malware.
• Cache Adjustment - Tuning the allowlist cache for performance.

11.1 - Avoiding Configuration Gaps

Overview: This is an advanced hardening guide. Lockdown seals HeartSuite Core Secure’s configuration with filesystem immutability, but programs like file editors and rm remain executable by default. For high-security environments, you can optionally restrict these tools during Lockdown to close additional attack surfaces. The Dashboard’s Maintenance screen ([t]) guides you through maintenance workflows, and the Mode Switch screen ([m]) manages Lockdown status.

Locking Down Maintenance Tools

• Programs like rm often need broad write access for maintenance.
• In production (lockdown), disable or restrict them to block misuse via vulnerabilities.

Example: Remove execution privileges from rm and make it immutable when Lockdown is applied. Restore access with hs-unlock for maintenance. The Dashboard displays the current lockdown status and guides you through unlocking when maintenance is needed.

Handling Programs Needing Write Access in Lockdown

• Database servers need write permissions to their data files/directories.
• Limit to specific paths—do not allow universal writes.
• Note: Database security is handled by the program itself, not HeartSuite Core Secure.

Optional Hardening: Programs Requiring Broad Access During Lockdown

Some programs (e.g., shutdown routines) need rm during operation, but you may want to restrict the full rm binary.

• Solution: Create a limited copy (limited_rm) with restricted permissions.
• Configure scripts to use the copy during Lockdown.

Setup steps:

1. Copy rm to limited_rm and rename original to rm-orig:

   # sudo cp /usr/bin/rm /usr/bin/limited_rm
   # sudo mv /usr/bin/rm /usr/bin/rm-orig
   # sudo ln -sf /usr/bin/limited_rm /usr/bin/rm
   

2. Reboot and allowlist limited_rm from the Dashboard’s Programs queue ([p]).
3. Update the Lockdown configuration to disable rm-orig and make both immutable.
4. Update hs-unlock configuration to restore access.

Restore full rm for maintenance:

# sudo mv /usr/bin/rm-orig /usr/bin/rm

Now, scripts call limited_rm with restricted access during lockdown.

11.2 - Protecting During Maintenance

Overview: Maintenance — such as installing packages, editing files, or applying updates — is the period during which you temporarily reduce HeartSuite Core Secure’s protection to make changes. The Dashboard’s Maintenance screen ([t]) guides you through the entire process, from safety preparation to returning to Secure Mode. The Maintenance screen appears only when the system is in Secure Mode, Secure Mode + Lockdown, or on the Non-HS kernel — it is not shown in Setup Mode, because in Setup Mode you are already in the maintenance-ready state.

Starting Maintenance

From the Dashboard in Secure Mode, select the Maintenance screen ([t]). The Dashboard automatically detects whether Lockdown is active and presents the correct path — you do not need to determine this yourself.

Safety Checklist

Before any mode change, the Maintenance screen 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 return to Secure Mode.

Option 1: Switch to Setup Mode (No Lockdown)

This is the standard maintenance path. The HeartSuite Core Secure kernel stays active. Logging and backups remain fully operational.

After completing the safety checklist, the Maintenance screen explains what will change:

• Enforcement changes from blocking to logging only
• The HeartSuite Core Secure 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 return to Secure Mode

Type YES (case-sensitive) to confirm the switch. The Dashboard reboots to apply the mode change.

After rebooting, the Dashboard shows Setup Mode is active with a Suggested Next Step. If the safety checklist was skipped, a persistent reminder appears. Make your changes — install packages, edit configuration, update software. HeartSuite Core Secure logs all new activity silently.

When finished, return to Secure Mode from the Dashboard. New events from the maintenance period appear in the review queues. Review and approve them through the standard allowlisting flow before enforcement resumes.

Option 2: Boot the Non-HS Kernel (Lockdown Active)

When Lockdown is active, the Maintenance screen does not offer the Setup Mode switch. Instead, it explains the situation and guides you through a 3-step process. This is the most complex journey in the product — it involves two reboots, a kernel selection at GRUB where the Dashboard cannot guide you, and a period where HeartSuite Core Secure is completely absent.

Step 1 of 3: Boot Non-HS Kernel and Remove Immutable Flags

After the safety checklist and typing YES to confirm, the Dashboard prepares you for the GRUB boot menu — the one moment where it cannot provide guidance. It shows the exact Non-HS kernel name to select and warns you not to select the HeartSuite Core Secure kernel. Press [r] to reboot.

The Dashboard saves your maintenance session state before rebooting. This state persists across reboots and kernel changes — the step counter (“Step X of 3”) follows you throughout the process.

After selecting the Non-HS kernel from GRUB, the Dashboard resumes automatically on login. It detects the absence of the HeartSuite Core Secure kernel module and adjusts its interface — actions that require the HeartSuite Core Secure kernel are hidden entirely, not greyed out. The Dashboard shows:

• “Non-HS kernel active. HeartSuite Core Secure is not loaded.”
• “No enforcement. No logging. No backups.”
• “Maintenance step 1 of 3: Remove immutable flags.”

Press [u] to remove the immutable flags set by Lockdown. After the flags are removed, the Dashboard presents the automatic Lockdown re-engagement choice:

• [d] Disable automatic Lockdown re-engagement — the startup script will no longer apply Lockdown on boot. You can re-enable this later. This simplifies future maintenance.
• [k] Keep automatic re-engagement — Lockdown will re-apply on every HeartSuite Core Secure kernel boot. Future maintenance will require this same process.

Both options carry equal weight — neither is recommended over the other. The choice depends on your operational needs.

Step 2 of 3: Make Your Changes

The Dashboard transitions to the maintenance workspace:

• “Maintenance step 2 of 3: Make your changes.”
• “You are on the Non-HS kernel. HeartSuite Core Secure is not active. Changes made now will not be logged.”

Make your changes — install software, update packages, modify configuration files. When finished, press [f] to prepare the return to the HeartSuite Core Secure kernel. The Dashboard pre-configures Setup Mode for the next boot.

Step 3 of 3: Boot HeartSuite Core Secure Kernel and Review

Select the HeartSuite Core Secure kernel from GRUB. The Dashboard appears automatically, showing Setup Mode is active and displaying the maintenance step counter. Software installed during maintenance may generate new log events — these appear in the review queues. Review and approve them, then return to Secure Mode from the Dashboard. If Lockdown was previously active and you kept automatic re-engagement, Lockdown will re-apply on the next reboot.

Lockdown and Filesystem Immutability

When Lockdown makes files immutable using chattr +i, those flags are stored at the filesystem level and persist across reboots — including reboots to the Non-HS kernel. If you attempt to modify a file that was made immutable during a previous Lockdown session, you will encounter an error such as “could not open file; errno:1.” The Maintenance screen’s [u] Remove immutable flags handles this automatically during Step 1 of the Lockdown path. For manual recovery outside the maintenance wizard, run hs-unlock.

11.3 - Adjusting the Cache Size

Overview: HeartSuite Core Secure caches allowlist entries in kernel memory for performance. Each cache slot holds one unique program or script. The default size works for most systems; adjust it only if you have an unusually large number of concurrent programs.

This is an advanced CLI tool — no Dashboard equivalent exists.

# hs-cache-size --help

• Range: 10-255 entries.
• Tune based on your server’s needs (more entries for varied workloads).

11.4 - File Backup and Versioning

Overview: Every time a file in a protected directory is modified, HeartSuite Core Secure automatically creates a versioned backup with a timestamp and file size. Only HeartSuite Core Secure can access the backups — no other program, including malware running as root, can read or destroy them. Versions are never automatically deleted.

How Backup Works

HeartSuite Core Secure monitors a list of protected directories. When any file in those directories (including subdirectories) is written, HeartSuite Core Secure silently creates a new versioned backup before the write completes. This runs automatically in both Setup Mode and Secure Mode — protection begins from first boot, before you have reviewed a single event.

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

Configuring Protected Directories

From the Dashboard, select the Backup screen ([b]). The screen shows your current backup configuration — which directories are protected and when they were last backed up.

From this screen you can:

• Add directories ([n]) — protect additional directories (e.g., /var/www, /etc, /usr/lib)
• Remove directories ([r]) — stop backing up a directory (removing a directory does not delete existing backups; existing versions are retained)

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.

Restoring File Versions

If a file is compromised — for example, encrypted by ransomware — the Dashboard’s Backup screen lets you browse version history and restore any previous version of any file in a protected directory. The Backup screen offers two browse modes:

• 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 the Timeline view ([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).

Advanced: CLI Backup Management

For automation workflows, the underlying CLI tools are available:

# hs-backup-config-manager add /var/www
# hs-backup-config-manager remove /home
# hs-backup-config-manager list
# hs-version-manager list /home/user/document.txt
# hs-version-manager restore /home/user/document.txt --version 2023-11-01

12 - Troubleshooting and Logs

Overview: If issues arise, start with the Dashboard — the Safety Banner shows the current system state, and the Suggested Next Step tells you what to do. The kernel log is available for advanced diagnostics when needed.

graph TD;
    A[System issue occurs] --> B{System fails to boot?};
    B -->|Yes| C[Boot into recovery mode or Non-HS kernel];
    C --> D["Dashboard resumes — follow Maintenance wizard steps"];
    D --> E[Boot HeartSuite Core Secure kernel — Dashboard shows pending events];
    B -->|No| F[Check the Dashboard];
    F --> G{Safety Banner shows wrong mode or Non-HS kernel?};
    G -->|Yes| H[Check System Info Strip for mode, kernel, lockdown];
    H --> I[Follow the Suggested Next Step];
    G -->|No| J{Review queues show pending or denied events?};
    J -->|Yes| K[Approve missing items from the review queues];
    J -->|No| L["Check dmesg | grep HEARTSUITE for raw kernel events"];
    E --> K;
    K --> M[Test operation];
    I --> M;
    L --> M;

Dashboard-First Diagnostics

The Dashboard is the primary diagnostic tool. Before checking log files, review:

• Safety Banner: Confirms the current system state. If it shows “SETUP MODE”, “SECURE MODE – Lockdown not applied”, or “NON-HS KERNEL”, you immediately know what protection level is active.
• System Info Strip: Shows kernel type (HS or Non-HS), current mode with uptime, and lockdown status.
• Pending/Denied counts: In Setup Mode, these are pending events awaiting review. In Secure Mode, these are denied actions that may need allowlisting.
• Suggested Next Step: Provides a single, actionable recommendation based on the current system state.

Log Management

HeartSuite Core Secure captures all permission events and presents them through the Dashboard’s three review queues: Programs ([p]), File Access ([f]), and Internet Access ([i]). The Dashboard shows pending event counts for each queue and groups events by category, so you always know what needs attention. The Maintenance screen ([t]) provides guided workflows for common maintenance tasks.

The review queues are the primary way to see and resolve events. The underlying activity log is a temporary buffer — once all three review queues are empty, the Dashboard automatically clears the log on its next refresh. No manual action is required.

Allow several days to a week of observation in Setup Mode. Systemd timers, cron jobs, and infrequent services generate events only when they run — the review queues accumulate these automatically.

Kernel Log (Advanced)

The Dashboard’s review queues automatically collect events from both the HeartSuite Core Secure 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 — for example, confirming kernel-level activation or correlating HeartSuite Core Secure events with other kernel messages:

dmesg | grep HEARTSUITE

The Dashboard presents the same event data with metadata enrichment and grouping. The Dashboard is accessible on both the HeartSuite Core Secure kernel and the Non-HS kernel — on the Non-HS kernel, the Safety Banner shows “NON-HS KERNEL” and enforcement is inactive.

Reporting Issues

If you encounter a bug, open an issue on GitHub using the Bug Report template. Include your HeartSuite Core Secure version, kernel version, the Safety Banner state, and steps to reproduce. For security vulnerabilities, email support@heartsecsuite.com — we’re happy to help.

13 - FAQs

General

Installation

Allowlisting

Modes and Security

Troubleshooting

For support, visit heartsecsuite.com or email support@heartsecsuite.com.

14 - Appendices

Overview: HeartSuite Core Secure includes a set of tools for system management, allowlisting, and security enforcement. The Dashboard is the primary interface for most users; the tools listed below are available for advanced use or specific cases.

With exception of the Secure Script Launchers, all tools are located in the /.hs/sys directory. The HeartSuite Core Secure installation routine does NOT add this directory to the PATH environment variable. The Secure Script Launchers are located in /usr/bin because it is in the default PATH. Programs and scripts that write data to HeartSuite Core Secure databases must be run as root.

Primary Tools

These are the tools most users interact with, organized by phase.

Dashboard and Review (Phases 1-5)

• Dashboard – the primary interface for HeartSuite Core Secure. Displays phase progress, pending/denied event counts, Safety Banner, System Info Strip, and Suggested Next Step. Appears automatically on login. Launch manually with sudo python3 main.py.
• Programs queue ([p]) – Dashboard screen to review and approve pending program execution events (Phase 2). Presents events with full metadata, grouped intelligently.
• File Access queue ([f]) – Dashboard screen to review and approve pending file access events (Phase 4). Handles read access and write access approvals separately.
• Internet Access queue ([i]) – Dashboard screen to review and approve pending internet access events (Phase 5). Allows allowlisting specific IPs per program.
• Allowlist screen ([a]) – Dashboard screen to browse and edit existing allowlist entries.
• Browser View ([w]) – Dashboard screen to enable or disable browser-based access to HeartSuite Core Secure via SSH tunnel.
• Launchers ([l]) – Dashboard screen to configure Secure Script Launchers (Phase 3).

Alert Configuration (Phase 6)

• Alert Settings ([e]) – Dashboard screen to configure alert channels (email, syslog, or webhook). At least one channel must be configured before Secure Mode activation. See Alert Configuration.

Mode Switching and Security (Phase 7)

• Mode Switch ([m]) – Dashboard screen for Secure Mode activation. Shows precondition checklist, observation period, and review summary. After activation, offers [r] Reboot or [l] Reboot + Lockdown.
• hs-activate-lockdown – makes HeartSuite Core Secure configuration files and directories immutable using chattr +i, then engages the lockdown program. Requires Secure Mode to be active. Requires typing YES to confirm.
• hs-unlock – reverses Lockdown by making HeartSuite Core Secure files mutable again. This is the counterpart to hs-activate-lockdown.
• hs-mode-switch – change whether HeartSuite Core Secure starts in Setup or Secure Mode on next boot. Used from a Non-HS kernel during recovery. View --help for details.

Maintenance and Backup

• Maintenance ([t]) – Dashboard screen for guided maintenance workflows. Detects Lockdown status automatically, presents a safety checklist ([c]/[s]), and guides through mode switching or the 3-step Lockdown maintenance process ([u]/[d]/[k]/[f]). Appears only in Secure Mode, Secure+Lockdown, and Non-HS kernel states — hidden in Setup Mode by design.
• Backup ([b]) – Dashboard screen to manage file backup and versioning. Offers File-first ([f]) and Timeline ([t]) browse modes, date filtering ([d]), batch restore ([b]), directory management ([n] add, [r] remove), and [tab] to switch panels.
• hs-manage-allowlist – CLI tool to browse and edit allowlist entries directly. For advanced workflows and automation. View --help for details.

Additional Executable Tools

• activate_HS – turns HeartSuite Core Secure service on. The installation routine adds a systemd service that runs this automatically at startup.
• hs-cache-size – change the maximum number of allowlist entries cached simultaneously. View --help for details.
• hs-backup-config-manager – specify directories for automatic file backup (e.g., /home). Only files in designated directories are backed up when modified. Prefer the Dashboard’s Backup screen ([b]) for directory management.
• hs-curfew – stops HeartSuite Core Secure from backing up files before shutdown. A systemd service executes this automatically before shutdown or reboot.
• hs-secure-script-launcher-manager – configures interpreter names for Secure Script Launchers. View --help for details.
• hs-activate-subscription – activates the server using your HeartSuite Core Secure subscription. Required before Secure Mode can be enabled.
• hs-version-manager – restore prior versions of backed-up files. Prefer the Dashboard’s Backup screen ([b]) for version browsing and restoration. View --help for details.
• hs-unlock-progs – switches all HeartSuite Core Secure files back to mutable state (after Lockdown).

Secure Script Launchers (Phase 3)

Located in /usr/bin (in the default PATH):

• hs-python-launcher – Secure Script Launcher for Python 3
• hs-python2-launcher – Secure Script Launcher for Python 2
• hs-perl-launcher – Secure Script Launcher for Perl
• hs-php-launcher – Secure Script Launcher for PHP

Python Scripts

Each script displays help information when started without arguments.

• hs-os-boot-setup.py – used internally by the Installation screen during local installation to scan logs and build allowlist entries for startup programs. Not for direct user invocation.
• batch_record_add.py – (legacy/advanced) adds programs listed in a file to allowlist entries with basic directory access. Prefer the Dashboard review tools for standard workflows.
• batch_record_add_read_all.py – (legacy/advanced) adds programs listed in a file to allowlist entries with read access to all files. Use with caution. Prefer the Dashboard review tools.
• batch_record_add_write_all.py – (legacy/advanced) adds programs listed in a file to allowlist entries with write access to all files. Use with extreme caution. Prefer the Dashboard review tools.

Shell Scripts

These scripts do not include help information but are simple to read.

• hs-clear-logs – manually clears the HeartSuite Core Secure activity log. In normal operation, the Dashboard auto-clears the log when all review queues are empty, so manual clearing is rarely needed.
• init_base_records.sh – used by the installation script to add Linux Standard Base (LSB) programs to allowlist entries. Used only once during Part 1 of installation.
• HS_startup.sh – called by the systemd heartsuite.service unit immediately after booting. Activates HeartSuite Core Secure automatically. The Dashboard’s Maintenance screen ([t]) manages Lockdown re-engagement settings in this script.