enodia-sentinal/docs/PACKAGING.md

Enodia Sentinel Packaging

Applies to package version: 0.7.0 Docs version: 0.7 Schema generation: v1

Sentinel is a stdlib-only Python package installed as a plain source directory plus launcher wrapper. The service and package are designed around Linux hosts with systemd.

Arch Linux

Arch is the primary packaged target.

Build from the repository root:

packaging/build-package.sh

Install the generated package:

sudo pacman -U enodia-sentinel-*.pkg.tar.zst
sudo systemctl daemon-reload
sudo systemctl enable --now enodia-sentinel.service

The Arch package installs:

Path	Purpose
/usr/bin/enodia-sentinel	Launcher wrapper for the Python package.
/usr/bin/sentinel-redteam	Safe local red-team harness.
/usr/lib/enodia-sentinel/enodia_sentinel/	Stdlib-only Python package.
/etc/enodia-sentinel.toml	Operator configuration, preserved as a pacman backup file.
/usr/lib/systemd/system/enodia-sentinel.service	Hardened daemon unit.
/usr/lib/systemd/system/enodia-sentinel-web.service	Read-only dashboard unit.
/usr/share/libalpm/hooks/enodia-sentinel-fim.hook	Post-transaction FIM baseline refresh hook.
/usr/lib/tmpfiles.d/enodia-sentinel.conf	Runtime log directory definition.
/usr/share/doc/enodia-sentinel/	Versioned operator docs and examples.
/var/log/enodia-sentinel/	Alert snapshots, events, incidents, response plans, and audit logs.

The pacman hook calls /usr/bin/enodia-sentinel fim-update after package transactions so legitimate package changes refresh the FIM baseline. It does not silence unexplained non-package drift.

Optional Arch packages:

• python-bpfcc for eBPF exec/syscall telemetry.
• bpftrace for short-lived exec capture inside forensic snapshots.
• libnotify for local desktop notifications.
• libarchive for signed-cache-package .MTREE verification helpers.

The default service is hardened for polling mode. To enable eBPF, copy the packaged drop-in example and reload systemd:

sudo install -Dm644 /usr/share/doc/enodia-sentinel/examples/enodia-sentinel-ebpf.conf \
  /etc/systemd/system/enodia-sentinel.service.d/ebpf.conf
sudo systemctl daemon-reload
sudo systemctl restart enodia-sentinel.service

Debian and Ubuntu

There is no native .deb package yet. Use the source install path:

sudo apt install python3 iproute2 procps
sudo make install PREFIX=/usr/local
sudo systemctl daemon-reload
sudo systemctl enable --now enodia-sentinel.service

Notes:

• The installed launcher does not require pip or a virtualenv.
• fim-check --packages uses the available package-manager backend; Debian package verification support should be validated for the target host before relying on it operationally.
• The source install path includes the pacman hook file for parity with Arch source installs. On non-Arch systems it is inert unless pacman/libalpm is installed; Debian installs should manage FIM baseline refresh through operator procedure or a future dpkg trigger package.

RPM-family Linux

There is no native RPM package yet. Use the same source install path:

sudo dnf install python3 iproute procps-ng
sudo make install PREFIX=/usr/local
sudo systemctl daemon-reload
sudo systemctl enable --now enodia-sentinel.service

Notes:

• Native RPM packaging should eventually install systemd units under the distro unit path, preserve /etc/enodia-sentinel.toml, and create a package-manager trigger equivalent to the Arch FIM refresh hook.
• Validate package verification behavior on the target distro before enabling signed-package mismatch alerting.

Desktop Tray Applet (optional)

The [tray] optional extra (pip install 'enodia-sentinel[tray]') pulls in pystray and Pillow and provides the enodia-sentinel-tray console script. The extra is never required by the daemon; core runtime dependencies stay empty.

packaging/enodia-sentinel-tray.desktop is an opt-in autostart entry. It is not installed to a system autostart path by default — desktop users copy it to ~/.config/autostart/ themselves.

Terminal TUI and Completion

The terminal dashboard is stdlib-only and available through enodia-sentinel tui in source/wrapper installs. Python packaging metadata also declares enodia-sentinel-tui = enodia_sentinel.tui:main for pip-style script generation.

Shell completion has no runtime dependency: operators generate scripts with enodia-sentinel completion bash or enodia-sentinel completion zsh and install them in their normal shell completion path.

Package Hardening Checklist

• Package version matches pyproject.toml and enodia_sentinel.__version__.
• Config is preserved across upgrades.
• Log directory is created with mode 0750.
• Service units remain hardened and read-mostly by default.
• eBPF privilege relaxation is shipped only as an opt-in drop-in example.
• Package-manager hooks use absolute paths and do not depend on ambient PATH.
• Versioned operator docs are installed with the package.

Release Artifacts

Release artifacts are built with:

make release-artifacts

The release target writes to dist/ by default:

Artifact	Purpose
enodia-sentinel-<version>.tar.gz	Versioned source release.
SHA256SUMS	SHA-256 checksums for the source tarball and release manifest.
RELEASE_MANIFEST.json	Project/version/git metadata for the generated release.
SHA256SUMS.asc	Optional detached GPG signature over SHA256SUMS.

The script refuses a dirty git worktree by default so a release maps to a known commit. For local packaging smoke tests only, set RELEASE_ALLOW_DIRTY=1.

To sign checksum artifacts:

RELEASE_SIGN=1 make release-artifacts

To select a specific GPG key:

RELEASE_SIGN=1 RELEASE_SIGNING_KEY=<key-id-or-fingerprint> make release-artifacts

Verification flow for operators:

gpg --verify SHA256SUMS.asc SHA256SUMS
sha256sum -c SHA256SUMS