Document packaging and release artifacts
This commit is contained in:
Luna
parent
aee984d862
commit
e0e5cd62d9
14 changed files with 470 additions and 13 deletions
|
|
@ -15,6 +15,7 @@ same patch as any command, schema, or behavior documentation changes.
|
|||
| [COMMAND_REFERENCE.md](COMMAND_REFERENCE.md) | Manpage-style CLI and service command contract. |
|
||||
| [SCHEMAS.md](SCHEMAS.md) | Stable JSON schema IDs and required v1 fields. |
|
||||
| [OPERATIONS.md](OPERATIONS.md) | Install checks, health checks, alert workflow, baseline hygiene, and evidence export. |
|
||||
| [PACKAGING.md](PACKAGING.md) | Arch package layout and Debian/RPM source-install paths. |
|
||||
| [RUNBOOKS.md](RUNBOOKS.md) | Incident response playbooks for common Sentinel findings. |
|
||||
| [RULES.md](RULES.md) | Generated built-in event-rule reference by SID. |
|
||||
|
||||
|
|
|
|||
153
docs/PACKAGING.md
Normal file
153
docs/PACKAGING.md
Normal file
|
|
@ -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
|
||||
```
|
||||
|
|
@ -93,8 +93,8 @@ Purpose: define a stable single-host product.
|
|||
audits.
|
||||
- ✅ Add compatibility tests for schema evolution.
|
||||
- ✅ Add documentation versioning and manpage-style command reference.
|
||||
- Harden packaging for Arch first, then document Debian/RPM install paths.
|
||||
- Add signed release artifacts and checksums.
|
||||
- ✅ Harden packaging for Arch first, then document Debian/RPM install paths.
|
||||
- ✅ Add signed release artifacts and checksums.
|
||||
- Improve dashboard from alert browser to local console:
|
||||
incidents, posture, integrity state, response plans, and watchdog status.
|
||||
- ✅ Add a local dashboard Settings menu with persistent themes for dark
|
||||
|
|
|
|||
|
|
@ -4,5 +4,7 @@
|
|||
"docs_version": "0.7",
|
||||
"schema_generation": "v1",
|
||||
"command_reference": "docs/COMMAND_REFERENCE.md",
|
||||
"schema_reference": "docs/SCHEMAS.md"
|
||||
"schema_reference": "docs/SCHEMAS.md",
|
||||
"packaging_reference": "docs/PACKAGING.md",
|
||||
"release_artifact_target": "make release-artifacts"
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue