Sync external ban lists with heliana Ban Sources

heliana can pull bans from an outside source instead of you entering every entry by hand. That’s a Ban Source, a standalone entity on its own page, not a kind of list. Open Bans in the org sidebar and switch to its Sources tab (/bans/sources) to manage them.

Your organization keeps Access lists (/access-lists) and Tags (Settings → Tags): access grants and player labels. Bans, manual or synced, live entirely outside them, as records of their own. A Ban Source writes bans directly and never touches an access list or a tag.

Create a Ban Source

In Bans → Sources, click New source and name it. Something like “CBL sync” is enough to tell it apart on the list.
Pick a Provider. Two ship with heliana, both pull-based:
- BattleMetrics needs a BM organization ID and an API token (the token is write-only: heliana stores it but never displays it again).
- Remote Ban File needs a Ban list URL, a plain-text file of steamID64:expiresAtUnix // reason lines, one ban per line. A Community Ban List export is this format — see Community Ban List below.
Fill in the fields the provider asks for. The provider itself can’t be changed after you save; delete the source and create a new one if you need a different one.

There’s no schedule field — a source syncs only when you click Sync now; scheduled runs haven’t shipped yet.

What the BattleMetrics source needs

The BM organization ID is the number of the organization whose bans you want to pull. The API token needs read access to Bans for that organization, and the View RCON information permission. Without that second permission BattleMetrics still returns the bans, but it hides the player IDs: some it drops, others it replaces with a hash (miHash:…) that never matches a player. heliana can’t enforce a ban without a real ID, so it skips those entries. The sync still finishes green, but Last sync shows almost every entry as Skipped, split into ID hidden by provider and No identity.

heliana only ever reads GET /bans filtered by your org, so no write scope is needed.
If the token is limited to specific organizations, the one whose ID you pasted has to be among them. A token that can’t reach the org gets 401/403 from BattleMetrics, and heliana shows that refusal in Last sync without importing anything.
A token that reaches the org but returns an empty list is the one to watch: a sync that reads the source to the end is treated as the source’s whole truth, so bans it imported earlier and no longer sees are lifted. Getting the org ID right matters as much as the token.

A revoked or expired token turns the next sync red, with the refusal shown in Last sync. Bans already imported stay where they are; open the source, paste a fresh token, and sync again.

Community Ban List

The Community Ban List has no provider of its own: its export ban list already is a remote ban file.

Paste the export URL, https://communitybanlist.com/export/<id>, as the Ban list URL of a Remote Ban File source.

A player who leaves the export is no longer in the file, and the next sync lifts that ban.

Run a sync

Click Sync now on the source’s row. heliana queues the pull; the result shows up in the Last sync column, and a failed sync’s refusal is shown inline there too. If a sync is already running for that source, or one just finished, you’ll get a message telling you to try again in a moment instead of a duplicate run.

Every past run stays on record. Click History on the source’s row to list every sync attempt for that source, newest first, each with its outcome and timestamp.

Imported bans land as bans of your organization, tied to that source, matched against each identity type the provider can emit (BattleMetrics: eos and steam; Remote Ban File: steam only). The identities on each entry are all the ban is enforced against: heliana adds nothing from its own observations, and a later sync refreshes the reason and expiry without rewriting them. They show up with no human operator (see Who issued it); a synced ban is identified by the source it came in through.

Deleting a source

Deleting a Ban Source deletes every ban it synced along with it. Bans you or another admin added manually are not touched, only the ones that came in through that source.

To drop a source’s bans without losing the source itself — its name, provider and credentials — click Clear bans in the edit dialog instead of deleting. The source stays connected, and the next sync brings back the bans the source still lists.

Who can do what

Action	What it needs
Create, edit, or delete a Ban Source	Ban lists: Manage (`banList:manage`)
Clear a source’s synced bans	Ban lists: Manage (`banList:manage`)
Run a sync	Ban lists: Manage (`banList:manage`)
Read a source’s sync runs	Ban lists: Manage (`banList:manage`)

All four gates use the same key.

A Ban Source syncs to your whole organization — there’s no per-server scope to narrow it to. Every Ban Source action follows that: a member whose access is limited to specific servers is refused on all of them, including the ones that only read. That limit is on Ban Sources, not on the key — the same banList:manage also covers ban exceptions, and there a server-limited member is allowed as long as the exception stays inside their own access.

See Roles & permissions to set who holds banList:manage.