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

88
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 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, 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. 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 to them, helping to distribute the load for maintaining blocklists among a
community of people. Control ultimately rests with the admins themselves so they 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 can outsource as much, or as little, of the effort to others as they deem
@ -23,7 +34,7 @@ cost.
### Blocklist Sources ### 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 - Supports both public lists (no auth required) and 'admin' lists requiring
authentication to an instance. authentication to an instance.
- Read domain block lists from arbitrary URLs, including local files. - Read domain block lists from arbitrary URLs, including local files.
@ -32,7 +43,7 @@ cost.
### Blocklist Export/Push ### 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 per-source, unmerged block lists to local files, in CSV format.
- Export merged blocklists to local files, in CSV format. - Export merged blocklists to local files, in CSV format.
- Read block lists from multiple remote instances - Read block lists from multiple remote instances
@ -50,12 +61,6 @@ cost.
## Installing ## Installing
Installable using `pip`.
```
python3 -m pip install fediblockhole
```
Install from source by cloning the repo, `cd fediblockhole` and run: 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. 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 If a remote instance makes its domain blocks public, you don't need
a token to read them. a token to read them.
@ -116,47 +126,7 @@ as explained below.
### Writing instance blocklists ### Writing instance blocklists
To write domain blocks into an instance requires both the `admin:read` and To write domain blocks into an instance requires an admin API key.
`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.
## Using the tool ## Using the tool
@ -187,8 +157,8 @@ As the filename suggests, FediBlockHole uses TOML syntax.
There are 4 key sections: There are 4 key sections:
1. `blocklist_urls_sources`: A list of URLs to read blocklists from 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_sources`: A list of Mastodon or Misskey 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_destinations`: A list of Misskey instances to write blocklists to via API
1. `allowlist_url_sources`: A list of URLs to read allowlists from 1. `allowlist_url_sources`: A list of URLs to read allowlists from
More detail on configuring the tool is provided below. 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 ### 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: The configuration is a list of dictionaries of the form:
``` ```
@ -293,8 +266,7 @@ The fields `domain` and `token` are required.
The fields `max_followed_severity` and `import_fields` are optional. 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 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 an admin API token.
`admin:write:domain_blocks` authorization.
The optional `import_fields` setting allows you to restrict which fields are 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 imported from each instance. If you want to import the `reject_reports` settings