pisentry reference

How it works

 journald / auth.log / kern.log ─┐
                                 ├─> auth detector ─────┐
                                 └─> port-scan detector ┤
 /proc (every 15s) ──> miner + reverse-shell detector ──┤
 /proc/1/net (30s) ──> listener detector ───────────────┤
 /etc, /home, cron, systemd (60s) ──> FIM ──────────────┼─> engine ─┬─> state.json (baselines, Top 10 history)
 /usr, /tmp, /home (6h) ──> SUID walk ──────────────────┤  dedupe   ├─> /metrics  (Prometheus)
 sshd_config, shadow, sysctl (6h) ──> posture audit ────┘  sanitize ├─> stdout JSON (journald / kubectl logs)
                                                                    └─> webhook (ntfy, Discord, Slack, generic)

• Learning period. For the first 10 minutes (15 in Kubernetes) pisentry records listeners and login sources without alerting. FIM and SUID baselines are taken on the first scan. Baselines persist in /var/lib/pisentry/state.json.
• Alert once, then adopt. A changed file alerts once and the new hash becomes the baseline. A new listener alerts once and stays counted in pisentry_unexpected_listeners until it goes away or you re-baseline.
• Cooldown. The same category and key will not re-fire for 15 minutes, so one brute-force campaign is one alert.
• Package manager awareness. If apt/dpkg/dnf is running when a watched file changes, severity drops one level and the event says so.
• One choke point for untrusted strings. Usernames, process names, paths and command lines come from the attacker. They pass through one sanitizer (control characters, terminal escapes, bidi overrides, invalid UTF-8, length) before they reach JSON, a webhook or your terminal.

Commands

pisentry run        [-config FILE]                  run the agent
pisentry report     [-since 24h] [-json]            ranked Top 10 from saved state
pisentry audit      [-json]                         one-shot posture audit, exit 2 on high/critical
pisentry baseline   reset                           re-learn baselines (the running agent picks it up)
pisentry check      [-rules PATH]                   validate rule bundles, exit 1 naming the file, rule and field
pisentry test-alert                                 send a test webhook
pisentry categories                                 print the Top 10 catalog

pisentry audit works without the agent running, which makes it handy for hardening a fresh Pi. pisentry report -json and pisentry audit -json are stable machine-readable output for evidence collection.

Configuration

Every key is optional. See deploy/config.example.json and internal/config/config.go for all of them. Unknown keys are rejected so typos fail loudly. The ones you are most likely to change:

Secrets (webhook URL and token) are read from the environment, never from config.json.

Outputs

Event JSON (Event Schema v1, OCSF / ECS mapping), one per line on stdout:

{"id":"c4f1d2e8-7a3b-4c91-8e2f-19a0b3c4d5e6","schema_version":1,"time":"2026-10-15T05:14:02Z","host":"kubepi",
 "category":"PS08","category_name":"Reverse shell","severity":"critical","mitre":["T1059.004"],"detector":"proc",
 "summary":"Reverse shell: bash (pid 5358) has fd 0 connected to 192.0.2.2:4445",
 "process":{"pid":5358,"ppid":1,"start_time":98112,"uid":0,"comm":"bash","exe":"/usr/bin/bash","cmdline":"bash -i"},
 "source":{"ip":"192.0.2.2","port":4445},"user":{"uid":0},
 "fields":{"pid":"5358","ppid":"1","comm":"bash","exe":"/usr/bin/bash","remote":"192.0.2.2:4445","fd":"0","uid":"0"}}

Prometheus on :9817/metrics:

HTTP API: GET /api/top10?window=24h and GET /api/events?limit=100 on the same listener.

Webhooks: ntfy (with priority mapping), Discord, Slack, or generic JSON. High and Critical by default. Alerts are rate limited to 30 per hour, and Critical alerts get their own budget so a flood of High events cannot hide a reverse shell.

Alerts

The most important alert is the one the agent cannot send itself: an attacker with root stops the agent first. Prometheus alert rules ship in two forms with the same content:

• deploy/prometheus/pisentry-rules.yaml for a plain Prometheus (rule_files:), with unit tests in pisentry-rules.test.yaml
• deploy/kubernetes/apps/base/pisentry/prometheusrule.yaml for the Prometheus Operator, plus a Kubernetes-only alert for a node with no running agent (needs kube-state-metrics)

Every alert carries a one-line runbook annotation. CI runs promtool check rules, promtool test rules and kubeconform against the CRD schema on every change.

pisentry and Falco

Falco sees a syscall the moment it happens. pisentry sees the things Falco does not try to cover.

Source: docs/reference.md