fluxer-admin-alerts/README.md

Fluxer Admin Alerts

A small Python script that checks a Fluxer instance's Admin API for things an instance admin should look at, and sends an alert when something needs attention.

It is meant to run on a schedule (cron). Each run it remembers what it has already told you, so you only get alerts for new items, plus a reminder on a schedule until the item is cleared in the admin UI.

Alerts go to a Fluxer channel through a webhook. Other notifiers (for example Gotify) can be added later.

What it checks

Source (config name)	Admin API endpoint	Alerts when	Required ACL
pending_reports	GET /v1/admin/reports?status=pending	A report is waiting. Reminder if it is still open after stale_after_hours. Marked urgent when the reason is highest priority.	report:view
pending_registrations	GET /v1/admin/instance/pending-registrations	An account is waiting for approval.	registration:review
discovery_applications	GET /v1/admin/discovery/applications	A community is waiting for discovery approval.	discovery:review
enforcement_review	GET /v1/admin/enforcement-decisions?review_queue=true	An automated moderation decision needs a person to review it.	enforcement:view

Requirements

• Linux (tested on Debian)
• Python 3.11 or newer
• An Admin API key on your instance with the ACLs in the table above
• A Fluxer webhook URL for the channel that should receive alerts

Install

These steps use a virtual environment (.venv), which is the supported way to run this project.

sudo apt install python3 python3-venv

cd /path/to/fluxer-admin-alerts
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env
cp config.example.toml config.toml

Then edit .env and config.toml (see below).

To run the tests:

python -m unittest discover -s tests

Configure

There are two config files. Both are ignored by git, so your values stay on your machine.

.env: URLs and secrets

Variable	Description
FLUXER_API_URL	Base URL of the Fluxer API, including /v1.
FLUXER_ADMIN_API_KEY	Admin API key.
ADMIN_UI_URL	Base URL of your admin UI. Used to build links in alerts.
FLUXER_WEBHOOK_URL	Webhook URL for the alert channel. Required when the fluxer notifier is enabled.

config.toml: behaviour

Setting	Default	Description
general.realert_hours	12	Hours before an open item is alerted again. 0 turns repeats off.
general.notify_cleared	true	Send a message when an item is cleared.
general.request_timeout	15	Seconds to wait for each HTTP request.
general.state_file	state.db	Where the alert history is stored.
general.notifiers	["fluxer"]	Notifiers to use.
sources.<name>.enabled	true	Turn a source on or off.
sources.pending_reports.stale_after_hours	48	Hours a report can stay open before the reminder.

Admin API key

Create an Admin API key in the admin UI with these ACLs:

• report:view
• registration:review
• discovery:review
• enforcement:view

Fluxer only lets a key use ACLs that the account that owns it also has, so that account needs the same ACLs.

Give the key only what it needs. Remove a source from config.toml and drop its ACL if you do not want that check.

Run

Check what would be sent, without sending anything or saving state:

.venv/bin/python -m fluxer_admin_alerts --dry-run

Run for real:

.venv/bin/python -m fluxer_admin_alerts

Use -v for debug logging. Exit code 0 means success, 1 means at least one source or notifier failed, and 2 means the config is wrong.

Schedule with cron

Edit your crontab with crontab -e and add a line to run every hour:

0 * * * * cd /path/to/fluxer-admin-alerts && .venv/bin/python -m fluxer_admin_alerts >> alerts.log 2>&1

Replace /path/to/fluxer-admin-alerts with the folder you cloned into. alerts.log is ignored by git.

How alerts work

• New item: alerted once, the first time it is seen.
• Reports: after stale_after_hours (48 by default) a "Still open" reminder is sent if the report is still pending.
• Repeats: an item still open after realert_hours (12 by default) is alerted again, until it is cleared.
• Cleared: when an item is no longer returned by the API (for example it was resolved in the admin UI), a "Cleared" message is sent if notify_cleared is on.
• Failures: if the Fluxer API or the webhook is unreachable, nothing is recorded for that run, so the alerts are sent on the next run. If one source fails, the others still run, and items from the failed source are not marked as cleared.

Adding a notifier

Notifiers live in fluxer_admin_alerts/notifiers/. A notifier subclasses Notifier, implements send(messages), raises NotifierError on failure, and is registered in notifiers/__init__.py. Then add its name to KNOWN_NOTIFIERS in config.py and read any settings it needs from .env.

License

Beer-ware. See LICENSE.