felicia

web service for sharing lists of bad actors. originally made for the fediverse, but flexible enough to use in other contexts.

config

felicia is configured via environment variables:

• PORT: service port, 8090 by default
• LOCAL_LIST_PATH: path to a local list file, see below
• SOURCES_PATH: path to a sources file, see below
• SOURCES_LIFETIME: list cache lifetime, 10 minutes by default

you must provide at least LOCAL_SOURCES or SOURCES_PATH. you can of course also set both.

felicia automatically invalidates cached lists (either local or remote ones) on a set interval and will re-fetch them when necessary, so restarting the service is not necessary for changes to be reflected.

note that the local source list itself is not automatically refreshed at the moment, so if you add a new source you do need to restart.

models

List

list of domains and acompanying information.

{
  "domains": [
    {
      "domain": "example.org",
      "level": "low|medium|high"
      "reason": "<...>",
      "notes": "<...>",
      "source": "<source where this domain entry originates from>"
    }
  ]
}

Source

sources to fetch more lists from.

{
  "sources": [
    "http://example.org/list.json"
  ]
}

api

GET /list/all

fetch all entries available, local and/or remote.

request

• Query params
  • dedup -- if present and set to true, return de-duplicated entries

response

• type: application/json
• model: List

GET /list/all/mastodonCsv

fetch all entries available, local and/or remote, as a Mastodon-compatible domain blocklist.

response

• type: text/csv

GET /list/search

filter all entries available for a specific domain and/or the amount of times it appears in different sources.

request

• Query params
  • domain -- if present, filter domain names by the given substring
  • threshold -- if present and given an integer n, filter domains that appear in at least n distinct sources
  • source -- if present, filter domain sources by the given substring
  • level -- if present, filter by entry severity level (low, medium or severe)
  • dedup -- if present and set to true, return de-duplicated entries

response

• type: application/json
• model: List

caveats

felicia is meant to facilitate aggregating and sharing potentially decentralized lists of bad actors. it doesn't, by itself, solve issues related to trust in the source themselves.

you must still verify your sources, including transitive ones, and make sure you can trust them.

license

(C) ariela wenner, 2023

unless otherwise specified, all code is licensed under the AGPL 3.0.