fediverse-blocklist-tool/README.md

100 lines
3.6 KiB
Markdown
Raw Permalink Normal View History

2023-07-26 10:43:34 +00:00
# fediverse-blocklist-deploy
2023-01-05 14:21:59 +00:00
2023-07-26 10:43:34 +00:00
A small tool to deploy blocklist updates to a fediverse server using its API.
2023-01-05 14:33:38 +00:00
## Concept
2023-01-09 07:40:28 +00:00
The idea is to maintain a blocklist in a simple structured file in this repository. All changes need to be deployed to
2023-07-26 10:43:34 +00:00
the fediverse server, this is supposed to be automated with Drone CI.
2023-01-05 14:33:38 +00:00
2023-01-09 07:40:28 +00:00
In order to compare the list entries, we can read the whole blocklist
using [the get endpoint](https://docs.joinmastodon.org/methods/admin/domain_blocks/#get). At the same time we read the
2023-05-03 09:48:20 +00:00
whole file in the repository, make a comparison
2023-01-09 07:40:28 +00:00
and [remove](https://docs.joinmastodon.org/methods/admin/domain_blocks/#delete) unblocked domains from the blocklist
and [add](https://docs.joinmastodon.org/methods/admin/domain_blocks/#create) newly added.
2023-01-05 14:33:38 +00:00
2023-05-03 09:48:20 +00:00
Since we have several attributes for a domain block, a simple `.txt` file might not be sufficient. We probably want to
2023-01-12 07:40:25 +00:00
set the severity, reject_media, reject_reports and comments. This means we need a human-readable, easily python-readable
2023-01-09 07:40:28 +00:00
and structured file format. Since Python 3.11 got native support for [toml](https://toml.io/) and it
supports [Array of Tables](https://toml.io/en/v1.0.0#array-of-tables), I'd prefer to use this.
2023-01-12 07:40:25 +00:00
2023-07-26 10:43:34 +00:00
# Supported server types
- [x] Mastodon
- [X] GoToSocial
2023-01-12 07:40:25 +00:00
# Basic usage
##
```
2023-07-26 10:43:34 +00:00
usage: fediverse_blocklist_deploy [-h] [-s SERVER] [-t TOKEN] [-i INPUT_FILE] [-r REMOTE_BLOCKLIST] [-o OUTPUT] [-v] [-n]
2023-05-03 13:11:56 +00:00
[--format FORMAT] [--private]
2023-05-03 09:53:41 +00:00
{diff,deploy,export}
2023-01-12 07:40:25 +00:00
2023-07-26 10:43:34 +00:00
Deploy blocklist updates to a fediverse server
2023-01-12 07:40:25 +00:00
positional arguments:
2023-05-03 13:11:56 +00:00
{diff,deploy,export} Either use 'diff' to check the difference between local blockĺist and the blocklist on the server, 'deploy'
to apply the current local blocklist or 'export' to export the remote blocklist into a local file.
2023-01-12 07:40:25 +00:00
options:
-h, --help show this help message and exit
-s SERVER, --server SERVER
The address of the server where you want to deploy (e.g. mastodon.social)
-t TOKEN, --token TOKEN
Authorization token
-i INPUT_FILE, --input-file INPUT_FILE
The blocklist to use
-r REMOTE_BLOCKLIST, --remote-blocklist REMOTE_BLOCKLIST
The remote blocklist as json for debugging reasons
-o OUTPUT, --output OUTPUT
Filename where to export the blocklist
-v, --verbose
-n, --no-delete Do not delete existing blocks
2023-05-03 13:40:27 +00:00
--format FORMAT Export format: toml|markdown|csv|json
2023-05-03 13:11:56 +00:00
--private When the flag is set, private comment will also be exported.
2023-01-12 07:40:25 +00:00
```
## Obtain a server token
1. Be an admin on the server.
2. Add an application in the Mastodon Web Client (https://yourdomain.org/settings/applications/new. Make sure to select the permissions `admin:read` and `admin:write`.
3. Copy the Token (last value in the table) ![](assets/obtain_token.png)
# Typical workflow
1. **Export the current blocklist from the server**
```
2023-07-26 10:43:34 +00:00
fediverse_blocklist_deploy export -s yourserver -t yourtoken -o blocklist.toml
2023-01-12 07:40:25 +00:00
```
2. **Manually add something to the blocklist**
```toml
[[instances]]
name = "instance-to-block.com"
domain = "instance-to-block.com"
severity = "suspend"
reject_media = true
reject_reports = true
public_comment = "X, Y and Z"
private_comment = "We discussed this after X and Y and now that Z happend we decided to block"
```
3. **Check the difference between the local and remote blocklist**
```
2023-07-26 10:43:34 +00:00
fediverse_blocklist_deploy diff -s yourserver -t yourtoken -i blocklist.toml
2023-01-12 07:40:25 +00:00
```
4. **Apply the local blocklist to the server**
```
2023-07-26 10:43:34 +00:00
fediverse_blocklist_deploy apply -s yourserver -t yourtoken -i blocklist.toml
2023-05-03 13:14:23 +00:00
```