BonPapa — Light & Easy Monitoring

Quickstart

Pull the repo:

git clone https://forgejo.high.statisfaction.rocks/statisfaction_public/bonpapa.git
cd bonpapa

Installing a client agent in the host to monitor

Client installation (agent on monitored host):

cp ./client/config.toml.example ./client/config.toml

Edit the ./client/config.toml with credentials from the server and an alias for the server to monitor

chmod +x ./client/install.sh
sudo ./client/install.sh

Installing server via Docker Compose

This repo runs the frontend/backend from prebuilt images. Build/push images first, or set BACKEND_IMAGE and FRONTEND_IMAGE in .env (after cp .env.sample .env), then:

docker compose up -d

Smoke test

An isolated Docker smoke test is available in scripts/run_smoke_test.sh.

Run it from the repo root:

./scripts/run_smoke_test.sh

It generates SECURITY_SMOKE_TEST_REPORT_AAAAMMJJ_HHMMSS.md automatically.

Usage details and options are documented in scripts/README.md.

License

BonPapa is released under the MIT License. See LICENSE.

Citation / Attribution

If you use BonPapa’s source code in research, documentation, or derived projects, please cite:

Robin Cohen-Selmon. BonPapa. (2026). Source code available at: https://forgejo.high.statisfaction.rocks/statisfaction_public/BonPapa

Please retain this notice in any substantial redistribution of the source.

Exports

CSV metric exports include a client_id column for easy correlation.

API Notes

• GET /clients lists visible clients. Use ?all_clients=true for admins.
• GET /clients/{client_id} returns client details.
• GET /clients/{client_id}/export returns CSV metrics for a client.

Frontend configuration

The frontend supports these optional Vite env vars:

• VITE_SESSION_HINT_TTL_SECONDS (default: 300) — how long the login page keeps the session-expired hint.
• VITE_SESSION_HINT_AUTO_HIDE_SECONDS (default: 6) — auto-dismiss delay for the hint. Set to 0 to disable.

CSV schema:

client_id,timestamp,cpu,memory,disk,load1,load5,load15,net_rx,net_tx

Risk Scoring

Clients are ranked using EWMA-smoothed metrics (exponential smoothing) to emphasize recent behavior, combined with a sigmoid scale around the threshold and a deviation term based on recent variance.

Metrics used:

• cpu, memory, disk
• load1, load5, load15
• net_rx, net_tx

Default risk alert threshold: 80% (aligned with common 80% CPU utilization alarm thresholds).

Algorithm details

1. EWMA smoothing (recent emphasis)
   Each metric is smoothed with an EWMA over ~10 samples to reduce noise while staying responsive.

2. Threshold ratio (normalization)
   ratio = EWMA / threshold so each metric is evaluated relative to its configured limit.

3. Sigmoid ramp near threshold
   A sigmoid centered at ratio = 1.0 makes risk increase smoothly around the threshold and avoid linear spikes.

4. Deviation term (z‑score)
   We add a smaller contribution based on how many standard deviations the latest value is from the recent mean.

5. Weighted aggregation
   Metrics are combined with weights:

• cpu/memory/disk: 0.2 each

• load1/load5/load15: 0.1 each

• net_rx/net_tx: 0.05 each

6. Network log scaling
   net_rx/net_tx are log1p‑scaled before thresholding to reduce heavy‑tail bursts.