Allowlisting Programs

• 1: Allowlisting Basics
• 2: Using HeartSuite Core Secure Log
• 3: Using the Kernel Log
• 4: Batch Allowlisting Tools

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]

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

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

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.

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