From 89c088d4c54dec793b7de9171fa90cf3ccfc9110 Mon Sep 17 00:00:00 2001 From: projectmoon Date: Thu, 30 Nov 2023 12:10:16 +0100 Subject: [PATCH] update readme --- README.md | 100 ++++++++++++++++++++---------------------------------- 1 file changed, 36 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 1fdec29..3c21fb9 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,23 @@ -# FediBlockHole +# FediBlockHole (Misskey Edition) -A tool for keeping a Mastodon instance blocklist synchronised with remote lists. +A tool for keeping a Misskey instance blocklist synchronised with +remote lists. This version of the software has been modified to work +with Misskey and its related forks (Sharkey, Firefish, Iceshrimp, +etc). The software supports pulling down existing block lists from +Mastodon and Misskey-type instances, and supports updating the block +list of Misskey-type instances. + +It does NOT support updating block lists of Mastodon instances. + +Original readme follows (modified where appropriate). + +----------- The broad design goal for FediBlockHole is to support pulling in a list of blocklists from a set of trusted sources, merge them into a combined blocklist, and then push that merged list to a set of managed instances. -Mastodon admins can choose who they think maintain quality lists and subscribe +Misskey admins can choose who they think maintain quality lists and subscribe to them, helping to distribute the load for maintaining blocklists among a community of people. Control ultimately rests with the admins themselves so they can outsource as much, or as little, of the effort to others as they deem @@ -23,7 +34,7 @@ cost. ### Blocklist Sources - - Read domain block lists from other instances via the Mastodon API. + - Read domain block lists from other instances via the Mastodon/Misskey API. - Supports both public lists (no auth required) and 'admin' lists requiring authentication to an instance. - Read domain block lists from arbitrary URLs, including local files. @@ -32,7 +43,7 @@ cost. ### Blocklist Export/Push - - Push a merged blocklist to a set of Mastodon instances. + - Push a merged blocklist to a set of Misskey instances. - Export per-source, unmerged block lists to local files, in CSV format. - Export merged blocklists to local files, in CSV format. - Read block lists from multiple remote instances @@ -50,12 +61,6 @@ cost. ## Installing -Installable using `pip`. - -``` -python3 -m pip install fediblockhole -``` - Install from source by cloning the repo, `cd fediblockhole` and run: ``` @@ -70,7 +75,12 @@ authorize the tool to create and update domain blocks with an OAuth token. More on authorization by token below. -### Reading remote instance blocklists +### Reading remote instance blocklists (Misskey) + +You will need an admin API token to read the instance block lists of a +Misskey instance. + +### Reading remote instance blocklists (Mastodon) If a remote instance makes its domain blocks public, you don't need a token to read them. @@ -116,47 +126,7 @@ as explained below. ### Writing instance blocklists -To write domain blocks into an instance requires both the `admin:read` and -`admin:write:domain_blocks` OAuth scopes. - -The tool needs `admin:read:domain_blocks` scope to read the current list of -domain blocks so we update ones that already exist, rather than trying to add -all new ones and clutter up the instance. - -`admin:read` access is needed to check if the instance has any accounts that -follow accounts on a domain that is about to get `suspend`ed and automatically -drop the block severity to `silence` level so people have time to migrate -accounts before a full defederation takes effect. Unfortunately, the statistics -measure used to learn this information requires `admin:read` scope. - -You can add `admin:read` scope in the application admin screen. Please be aware -that this grants full read access to all information in the instance to the -application token, so make sure you keep it a secret. At least remove -world-readable permission to any config file you put it in, e.g.: - -``` -chmod o-r -``` - -You can also grant full `admin:write` scope to the application, but if you'd -prefer to keep things more tightly secured, limit the scope to -`admin:read:domain_blocks`. - -Again, this scope is only available in the application config screen as of -Mastodon v4.1.0. If your instance is on an earlier version, you'll need to use -SQL to set the scopes in the database and then regenerate the token: - -``` -UPDATE oauth_applications as app - SET scopes = 'admin:read admin:write:domain_blocks' - FROM oauth_access_tokens as tok - WHERE app.id = tok.application_id - AND app.name = '' -; -``` - -When that's done, FediBlockHole should be able to use its token to authorise -adding or updating domain blocks via the API. +To write domain blocks into an instance requires an admin API key. ## Using the tool @@ -185,10 +155,10 @@ Or you can use the default location of `/etc/default/fediblockhole.conf.toml`. As the filename suggests, FediBlockHole uses TOML syntax. There are 4 key sections: - + 1. `blocklist_urls_sources`: A list of URLs to read blocklists from - 1. `blocklist_instance_sources`: A list of Mastodon instances to read blocklists from via API - 1. `blocklist_instance_destinations`: A list of Mastodon instances to write blocklists to via API + 1. `blocklist_instance_sources`: A list of Mastodon or Misskey instances to read blocklists from via API + 1. `blocklist_instance_destinations`: A list of Misskey instances to write blocklists to via API 1. `allowlist_url_sources`: A list of URLs to read allowlists from More detail on configuring the tool is provided below. @@ -259,7 +229,10 @@ All comments are public, by virtue of the public nature of RapidBlock. ### Instance sources -The tool can also read domain_blocks from instances directly. +The tool can also read domain_blocks from instances directly. Both +Mastodon and Misskey instances are supported. Any instance that +exposes a fully-compliant Mastodon admin API is also theoretically +supported, but untested. The configuration is a list of dictionaries of the form: ``` @@ -267,7 +240,7 @@ The configuration is a list of dictionaries of the form: ``` The `domain` is the fully-qualified domain name of the API host for an instance -you want to read domain blocks from. +you want to read domain blocks from. The `token` is an optional OAuth token for the application that's configured in the instance to allow you to read domain blocks, as discussed above. @@ -288,13 +261,12 @@ Configure the list of instances you want to push your blocklist to in the { domain = '', token = '', import_fields = ['public_comment'], max_severity = 'suspend', max_followed_severity = 'suspend' } ``` -The fields `domain` and `token` are required. +The fields `domain` and `token` are required. The fields `max_followed_severity` and `import_fields` are optional. The `domain` is the hostname of the instance you want to push to. The `token` is -an application token with both `admin:read:domain_blocks` and -`admin:write:domain_blocks` authorization. +an admin API token. The optional `import_fields` setting allows you to restrict which fields are imported from each instance. If you want to import the `reject_reports` settings @@ -365,7 +337,7 @@ Sets where to save intermediate blocklist files. Defaults to `/tmp`. ### blocklist_auditfile -If provided, will save an audit file of counts and percentages by domain. Useful for debugging +If provided, will save an audit file of counts and percentages by domain. Useful for debugging thresholds. Defaults to None. ### no_push_instance @@ -390,7 +362,7 @@ Skip the fetching of blocklists from any remote instances that are configured. Defaults to None. -Stamp all *new* blocks pushed to a remote server with this comment or code. +Stamp all *new* blocks pushed to a remote server with this comment or code. Helps to identify blocks you've created on a server via Fediblockhole versus ones that already existed. @@ -451,4 +423,4 @@ detail in a file, but only push `public_comment` to instances. file, if you export one. The fields `domain` and `severity` are always included, so only define extra -fields, if you want them. \ No newline at end of file +fields, if you want them.