Document packaging and release artifacts

docs/PACKAGING.md

@@ -0,0 +1,153 @@
+# 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:
+
+```bash
+packaging/build-package.sh
+```
+
+Install the generated package:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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.
+
+## 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:
+
+```bash
+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:
+
+```bash
+RELEASE_SIGN=1 make release-artifacts
+```
+
+To select a specific GPG key:
+
+```bash
+RELEASE_SIGN=1 RELEASE_SIGNING_KEY=<key-id-or-fingerprint> make release-artifacts
+```
+
+Verification flow for operators:
+
+```bash
+gpg --verify SHA256SUMS.asc SHA256SUMS
+sha256sum -c SHA256SUMS
+```