projectmoon
/
fediblockhole-misskey
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update readme

This commit is contained in:
projectmoon 2023-11-30 12:10:16 +01:00
parent 28004d3c0b
commit 89c088d4c5
1 changed files with 36 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
README.md
View File

@ -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 <configfile>
```
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 = '<the_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 = '<domain_name>', token = '<BearerToken>', 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.
fields, if you want them.