herodium - Herodium is a developer-oriented Linux security pr

项目说明

Herodium Security System (De)

> [!IMPORTANT]
> Herodium is a de Linux security framework for testing, research, and controlled deployments.
>
> It works with system-le such as ClamA, AppArmor, Fail2Ban, Maltrail, ZRAM, systemd, and iptables/ipset.
> Test it in a , or non-critical system before using it on a daily-driver or production machine.
>
> Herodium is a flexible foundation. Review and tune the configuration for your own system.

---

O

Herodium is a de Linux security project designed as a seed framework for building and testing broader defensi.

It runs as a pri background engine and combines multiple defensi into one modular system: real-time file monitoring, removable media scanning, process and command-line inspection, optional Falco-based runtime behavior monitoring, optional network response logic, optional AppArmor policy application, optional system hardening, scheduled antivirus scanning, and supporting operational tools.

This repository is not positioned as a polished enterprise security suite. Its purpose is to provide a practical, extensible foundation that de and security researchers can inspect, modify, and expand.

Current Scope

Herodium currently focuses on these areas:

Real-Time File Monitoring

Watches configured filesystem paths for file creation, modification, and mo.

Uses a queued scanning model to reduce duplicate scans during rapid file changes.

Supports optional filtering for noisy locations such as cache directories.

USB / External Media Monitoring

Detects newly mounted removable media under standard Linux mount locations.

Automatically attaches filesystem monitoring to new media.

Queues existing files on newly detected media for initial scanning.

Memory / Process Inspection

Iterates running processes and inspects:

- the executable path
- file-based command-line arguments, including relati resol the process working directory

Uses ClamA scanning logic to identify infected binaries or loaded files.

Terminates a process if an infected executable or related file is detected.

ClamA

Connects to the local clamd Unix socket.

Supports configurable actions for detected threats:

- quarantine
- delete
- alert

Enforces size-based prefiltering before stream scanning.

Binds remediation to the filesystem identity of the exact regular file opened

for ClamA scanning. Quarantine/delete refuse to act on a replacement
pathname when (device, inode) no longer matches the object that produced the
ClamA.

Falco Runtime Beha Monitoring

Optionally integrates Falco as a host runtime behavior sensor.

Uses Falco's modern eBPF driver to obser syscall activity without turning Falco into an enforcement engine.

Complements ClamA e file content, while Falco can identify high-se runtime behavior such as security-relevant state changes.

Runs in alert-only mode. Falco events ne kill a process, quarantine a file, or change firewall state.

Uses a high-signal ERROR+ policy: only ERROR, CRITICAL, ALERT, and EMERGENCY Falco rules are loaded and e. Lower-se WARNING, NOTICE, INFO, and DEBUG rules are intentionally excluded to avoid routine host activity becoming an alert flood.

Writes structured JSONL to /var/log/herodium/falco-events.jsonl; Herodium and consumes the stream through a persistent cursor, a bounded queue, and a rate-limited dispatcher.

Logs only bounded event context such as rule, priority, process path, parent, user, and target. The dispatcher does not persist the raw Falco output or raw command line.

Treats Falco as an optional health component: a Falco runtime failure degrades that component instead of con Falco into an automatic response mechanism.

Network Monitoring

Integrates with local Maltrail logs.

Can run in either:

- alert-only mode
- acti mode

In blocking mode, malicious IPs are added to IP sets and enforced with iptables / ip6tables.

Supports scheduled blacklist cleanup.

System Hardening and Host Controls

AppArmor profile handling with multiple levels, defaulting to OS behavior unless explicitly changed.

Optional sysctl hardening rules.

Optional ZRAM acti.

Dynamic ClamA throttling based on workload and thermal conditions.

Optional Fail2Ban acti for SSH brute-force protection.

Scheduled Tasks

Supports scheduled ClamA.

Supports optional Rkhunter checks and threat-data updates.

Ne the local Rkhunter file-properties baseline automatically.

The installer configures scheduled ClamA through systemd timer units.

Project Structure

Supported En

Herodium is designed for Debian-based Linux systems that use:

apt

systemd

AppArmor

ClamAV

The current installer flow is oriented toward:

Debian

Ubuntu

Linux Mint

Kali Linux

and similar Debian/Ubuntu-based distributions.

Root pri are required for installation and normal runtime operation.

Resource Expectations

The li is designed to be highly CPU-efficient and, under normal day-to-day activity, will usually consume only a small amount of processing power.

Actual CPU and memory usage can still increase during bursts of filesystem activity, removable media scans, manual scans, scheduled scans, or hea inspection workloads.

Plan for approximately 1500 MB of RAM for comfortable operation.

Minimum recommended hardware:

- 4 CPU cores
- 8 GB RAM

Optional Performance and Power Optimization

Herodium can optionally be used together with
auto-cpufreq on physical
systems.

Although auto-cpufreq was designed primarily for laptops, practical testing
with Herodium on a physical workstation showed impro and thermal
efficiency without a noticeable reduction in Herodium performance.

auto-cpufreq dynamically manages CPU frequency scaling, go, and turbo
boost according to system load, CPU temperature, and power state. This can
complement Herodium's own targeted ClamA controls, particularly on
laptops and workstations where lower power consumption, reduced heat, and
quieter operation are desirable.

This integration is optional and is not a Herodium dependency. Results may vary
depending on:

CPU model and scaling driver

CPU go configuration

cooling capacity

battery or AC power state

scan size and workload intensity

other power-management services

Avoid running multiple tools that manage the same CPU frequency or power
settings unless they have been configured specifically to coexist. In
particular, check for potential conflicts with tools or services such as TLP,
power-profiles-daemon, or other go utilities.

Install auto-cpufreq

Clone the official repository and run its installer:

Install and enable the persistent auto-cpufreq daemon:

Review the current CPU, temperature, go, and power-management status:

For production or long-running Herodium deployments, compare scan completion
times, CPU temperature, system responsi, and queue behavior before and
after enabling auto-cpufreq.

##
##
##

Installation

Prerequisites

A Debian-based Linux distribution

Root access (sudo)

Internet access for package installation and initial signatures / dependencies

A de or test en such as a VM, lab machine, or sandbox

Clone the repository

Run the installer

The main installer entrypoint, installer/install.sh, intentionally remains
non-executable. Invoke it through sudo bash so archi and
source-control mode changes cannot alter the documented installation path.

Installer flow

The interacti currently guides you through:

Timeshift snapshot creation

ZRAM setup

scheduled ClamAV scan preferences

li enable/disable

li action selection

Maltrail installation and mode

optional Falco runtime behavior monitoring in alert-only mode

Fail2Ban installation

AppArmor le

optional kernel hardening

optional Rkhunter setup

What the Installer Sets Up

Depending on your selections, the installer may configure:

application deployment under /opt/herodium

Python en under /opt/herodium/venv

main service:

- herodium.service

optional Maltrail services:

- maltrail-sensor.service
- herodium-maltrail-update.service
- herodium-maltrail-update.timer
- code pinned by installer/supply-chain-lock.json
- sensor-side downloads disabled (--offline)
- controlled IOC trail refresh performed daily through staging and rollback

optional Falco runtime sensor:

- exact package and repository trust pinned by installer/supply-chain-lock.json
- falco-modern-bpf.service with the modern eBPF driver
- high-signal ERROR+ rule policy and alert-only Herodium consumption
- Herodium configuration under /etc/falco/config.d/herodium.yaml
- Herodium rules under /etc/falco/rules.d/herodium-rules.yaml
- JSONL event stream under /var/log/herodium/falco-events.jsonl
- persistent reader state under /var/lib/herodium/falco
- log rotation through /etc/logrotate.d/herodium-falco

scheduled ClamAV scan service and timer:

- herodium-scheduled-scan.service
- herodium-scheduled-scan.timer

logs under:

- /var/log/herodium

scheduled scan config under:

- /etc/herodium/scheduled_scan.conf

Herodium Deployment and Dependency Policy

Herodium itself is built under /opt/herodium.stage while the currently active
service continues using /opt/herodium. The installer creates a stable source
manifest, copies only regular source files into the root-owned stage, and
that both the source and staged snapshot match before dependency work
begins.

The staged en is new for every installation. Packaging tools
are pinned with SHA-256 hashes in installer/python-tools.lock; runtime
packages are pinned with SHA-256 hashes in herodium/requirements.lock. Pip is
run in isolated mode with user and system configuration disabled,
--require-hashes, --no-deps, and the explicit PyPI simple index. The active
/opt/herodium/venv is ne in place.

Before acti, the installer the exact installed distribution
set, imports, Python syntax, YAML configuration, pip check, permissions, and
a content manifest. Existing root-owned configuration is preserved and updated
inside the stage. Mutable quarantine contents are copied only after the old
service has been stopped.

Acti rotates /opt/herodium to /opt/herodium.previous and renames the
fully stage into place. The new service must reach Herodium's
PROTECTED health state before the transaction can be committed. A failure or
interrupt before commit restores the previous deployment, service unit,
enabled state, and acti automatically. The deployment
manifest is retained under /var/lib/herodium/supply-chain for operator audit.

Falco Runtime Monitoring and Supply-Chain Policy

Falco provides the runtime-behavior layer that file-content scanning alone cannot
provide. Herodium uses ClamAV to inspect files and process-related file content;
Falco independently obser activity from the kernel and applies Falco
rules to security-relevant behavior. The integration is deliberately one-way:
Falco detects and emits events, while Herodium , correlates, logs, and
optionally notifies. Falco is ne to perform Herodium enforcement
actions such as killing processes, quarantining files, or blocking network
traffic.

The current supply-chain lock pins Falco 0.44.1, its official DEB repository,
the expected signing-key fingerprint, and the modern_ebpf driver. The
installer downloads the signing key as data, the exact trusted
fingerprint, installs the exact package non-interactively, applies an
APT hold, and disables the falcoctl automatic artifact-follow service. This
keeps executable/rule changes tied to an explicit Herodium source and lock-file
update instead of an unattended rules update. Falco's modern eBPF driver is
bundled with Falco and is the upstream default driver on supported systems.

Herodium intentionally configures Falco with:

Falco therefore loads and e only rules with a priority at least as
severe as ERROR: ERROR, CRITICAL, ALERT, and EMERGENCY. This is a
high-signal endpoint policy rather than a full Falco telemetry feed. Rules at
WARNING, NOTICE, INFO, and DEBUG are intentionally not active in this
integration because normal desktop and administrati can otherwise
produce excessi. Herodium applies an independent ERROR minimum in
its dispatcher as defense in depth.

Herodium also ships a small local Falco rules file. The current custom rule
detects writes below /etc/systemd/system and classifies them as ERROR, which
keeps persistence-relevant systemd changes under the high-signal
policy. Upstream Falco rules at ERROR or higher remain a as well.

Falco event pipeline

The JSON parser rejects malformed or o records, duplicate JSON keys,
unsupported nesting, invalid priorities, and other out-of-contract input. The
Falco JSONL file itself is root-owned and mode 0600; because it is Falco's
sensor stream, upstream rules may include fields such as command-line context
in that file. Herodium deliberately does not copy raw Falco output or raw
proc.cmdline into its processed herodium.log alert summaries. The reader
uses a root-owned persistent cursor at
/var/lib/herodium/falco/cursor.json, starts at end-of-file on a clean first
installation, handles rename rotation and copy/truncation safely, waits for
partial records, and bounds work per poll. The monitor queue is bounded, and the
dispatcher drains bounded batches with a bounded alert cache and cooldown.

The event log is rotated daily, retained for se, capped by a
25 MiB maxsize, and reopened by signalling Falco after rotation. The event
stream is intentionally preser normal upgrades, while the cursor is
preserved so old events are not replayed. During an in-place Herodium upgrade,
the installer temporarily quiesces a Herodium-managed Falco sensor after the
Herodium consumer stops and resumes/ Falco only after installer-managed
systemd writes are complete. This prevents the installer from generating its
own persistence alerts without adding a broad rule exception or discarding the
persistent cursor.

Falco ownership and uninstall safety

Herodium records Falco ownership in the private root-owned marker:

The marker distinguishes a Falco package/repository installed by Herodium from
a pre-existing Falco deployment. The installer refuses to silently claim or
reconfigure unowned Falco assets. On uninstall, Herodium purges Falco and its
repository only when the ownership marker is valid and explicitly states that
Herodium created them; otherwise external Falco state is preserved. Herodium's
own Falco config, rules, logrotate policy, cursor, and ownership state are
remo to that ownership contract.

Operational checks:

Maltrail Supply-Chain Policy

Herodium does not install Maltrail from a moving branch. The installer reads an
immutable upstream repository, full commit identifier, and expected license
SHA-256 from installer/supply-chain-lock.json. It fetches only that commit,
the fetched object database, checks the license hash, extracts a
content-only deployment, and activates it only after the service passes a
health check. The prior /opt/maltrail deployment is retained as
/opt/maltrail.previous for immediate rollback.

The sensor starts with --offline and uses an explicit root-owned configuration
at /etc/maltrail/maltrail.conf. This keeps packet capture isolated from network
retrieval and prevents the long-running sensor from modifying its own inputs.
Runtime trail state remains namespaced by the pinned code commit.

IOC trails are refreshed separately by herodium-maltrail-update.timer, once
per 24 hours with a randomized delay. The updater executes only the feed modules
from the pinned Maltrail code snapshot, disables feed modules that do not expose
an HTTPS URL, restores normal TLS certificate , and rejects custom
remote/update-ser for the automated path.

Each refresh is built under a private staging HOME. The resulting CSV must pass
strict UTF-8/CS, bounded row and file-size limits, and a
catastrophic-shrink guard relative to the currently active list. A valid
candidate is copied atomically into the acti directory. If the sensor
was running, it is restarted and must return with a non-zero MainPID; otherwise
the previous trails.csv is restored automatically. The last successful
metadata record is stored at:

Run an immediate controlled refresh and inspect its timer with:

Maltrail source code still changes only through an explicit
supply-chain-lock.json update and a new Herodium release. Trail data is
therefore current and mutable, while executable code remains re and
immutable.

Rkhunter Baseline Safety

Herodium runs scheduled Rkhunter checks and may update Rkhunter threat-data files,
but it never runs rkhunter --propupd automatically. The file-properties
baseline represents trusted local system state and must only be changed after an
operator has in the current warnings and that the changes are
authorized.

Review the current warnings without changing the baseline:

After in and all relevant changes, perform an explicit,
audited baseline update:

The update command requires root pri, an explicit acknowledgement, and a
non-empty reason. It serializes operations with scheduled Rkhunter work and
writes an audit record to:

Runtime Paths

Common paths used by the current implementation:

Usage

Start / Stop / Status

Check scheduled scan timer

Check optional Maltrail sensor

Check optional Falco runtime sensor

Falco's structured event stream can be inspected separately from Herodium's
processed alerts:

Real-Time Logs Monitoring

Real-time dashboard

Manual scan wrapper

Configuration

Main engine configuration

Primary runtime configuration is stored in:

Important keys include:

li.enable

directories.watch_paths

directories.ignore_prefixes

directories.ignore_user_cache

clama

clama

memory_scan.inter

memory_scan.whitelist

maltrail.enable

maltrail.block_traffic

maltrail.log_path

maltrail.clean_inter

falco.enable

falco.mode (alert_only only)

falco.e

falco.cursor_path

falco.start_position

falco.queue_max_size

falco.dispatch.minimum_priority

falco.dispatch.notification_minimum_priority

falco.dispatch.alert_cooldown_seconds

performance.enable_zram

performance.cpu_limit_percent

hardening.enable

ips.enable

apparmor.level

memory_scan.whitelist is an executable identity allowlist, not a process-name
allowlist. Entries must be absolute paths. At startup, Memory Hunter resolves each
existing entry and accepts it only when it is a root-owned regular executable with
no group/world write bits. Herodium pins the executable (device, inode) identity
and, before skipping a li, requires /proc/<pid>/exe to refer to that
same object. A copied or renamed binary such as /tmp/firefox is therefore not
trusted merely because its basename or process name resembles a legitimate tool.

After changing the YAML file:

Scheduled scan configuration

The installer writes scheduled scan settings to:

After changing scheduled scan service or timer behavior:

Default Behavior

Out of the box, the current default configuration includes:

li enabled

default watch paths:

- /home
- /tmp
- /etc
- /var/www

quarantine path:

- /opt/herodium/quarantine

ClamA:

- quarantine

Memory Hunter enabled with 1-second loop interval

optional network blocking controlled by configuration

Falco disabled in the base YAML unless selected by the installer

when Falco is enabled, mode is alert-only and both Falco and Herodium use an ERROR+ minimum

optional hardening controlled by configuration

AppArmor default level:

- 1 — OS default / no Herodium AppArmor changes

Logs

Main operational logs:

/var/log/herodium/herodium.log

/var/log/herodium/scheduled_scan.log

/var/log/herodium/falco-events.jsonl when Falco is enabled

herodium.log contains the bounded, processed Falco alert summary. The raw
Falco JSONL stream is kept separately for the reader contract and does not mean
that every Falco record will be surfaced as a Herodium alert; the dispatcher
still enforces its configured minimum priority and cooldown.

If Maltrail is installed, related logs are typically stored under:

/var/log/maltrail/

Uninstallation

To remo and clean up its installed files and service units:

The uninstaller removes:

Herodium service units

deployed application files

log directories

scheduled scan units

local helper scripts

optional Fail2Ban jail created by the installer

Herodium-specific Falco configuration, rules, logrotate policy, cursor, and ownership state

a Falco package/repository only when the ownership marker shows that Herodium installed them

Herodium-specific IP sets and firewall rules where applicable

It can also optionally remo packages installed by the project. A
pre-existing or unowned Falco installation is deliberately preser
than silently purged or reconfigured.

Important Notes

Herodium is intentionally opinionated and root-level.

It is meant for controlled de and research use.

It can modify host security posture in ways that are inappropriate for unmanaged en.

Test changes in a VM or disposable en before trusting them on a real system.

If you use higher AppArmor levels or other host-hardening features, a backup-first workflow is strongly recommended.

For De

This project is best understood as a starting point for:

Linux endpoint defense experiments

ClamA logic

high-signal Falco/eBPF runtime-behavior monitoring

removable media scanning workflows

AppArmor automation prototypes

host-le automation

security monitoring research on Debian-based systems

The codebase is intentionally modular so indi components can be replaced, extended, or stripped down depending on the use case.

Installer reliability and rollback testing

The installer preserves and restores the prior Herodium unit, CLI tools, scheduled-scan assets, deployment manifest, logrotate policy, ClamA and service/socket/updater state, the previous pinned Maltrail deployment, and Herodium-managed Falco transaction state until the acti transaction passes final health checks. During upgrades a managed Falco sensor is quiesced only for installer-owned systemd writes and is re before Herodium starts. Maltrail is stopped with SIGINT so its main process can terminate worker processes cleanly before the timeout. Mutable operator configuration is excluded from the immutable deployment manifest.

Timeshift snapshots are created as on-demand snapshots in a headless command en without desktop notification helpers and are by listing the resulting snapshot before installation continues. This avoids treating a successful snapshot as failed because of an asynchronous desktop-notification error.

A controlled rollback can be requested explicitly by running the installer with HERODIUM_INSTALLER_TEST_FAILPOINT=after_final_ and HERODIUM_INSTALLER_TEST_ACKNOWLEDGE=ROLLBACK-TEST. This test intentionally fails after all final service checks and must restore the previous deployment and service state; it is not enabled during normal installation. The rollback transaction covers deployed code and installer-managed acti assets. General dependency packages installed before acti are not automatically removed, while a Falco package created by the current uncommitted Falco transaction is purged during Falco rollback. A Timeshift snapshot created before acti is ne by rollback.

项目信息

开发语言：Python

Star 数：36

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Herodium is a developer-oriented Linux security project designed as a seed framework for building and testing broader defensive tooling.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。