Drive the allowlist from your own tooling

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

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

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

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

Policy curation in your central systems

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

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

Two seed mechanisms (do not conflate)

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

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

Recommended order (dense / fleet — seed first)

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

Cold path (first reference only)

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

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

Applying policy from automation

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

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

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

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

Examples for the primary integration patterns follow.

1. Ansible — playbooks for seeding and applying policy

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

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

Official Ansible role: heartsecurity.root_lock

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

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

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

Requirements:

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

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

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

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

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

Minimal example playbook:

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

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

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

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

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

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

Shell + register alternative

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4. ServiceNow or ITSM platforms — change-driven policy

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

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

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

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

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

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

Consuming data for central visibility, auditing, and harvesting

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

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

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

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

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

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

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

Relationship to the Dashboard and Lockdown

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

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

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

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

Next steps and related documentation

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

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