FediVuln

A client to gather vulnerability-related information from the Fediverse. The gathered data is subsequently transmitted to the Vulnerability-Lookup API.

Installation

pipx is an easy way to install and run Python applications in isolated environments. It's easy to install.

$ pipx install FediVuln
$ export FEDIVULN_CONFIG=~/.FediVuln/conf.py

The configuration for FediVuln should be defined in a Python file (e.g., ~/.FediVuln/conf.py). You must then set an environment variable (FEDIVULN_CONFIG) with the full path to this file.

You can have a look at this example of configuration.

Usage

Register your application

$ FediVuln-Register

This script uses OAuth in order to retrieve the access token. This is achieved in several steps.

Register the application with Mastodon instance, a including all necessary scopes
Instantiate Mastodon client with client credentials
Log in - Generate authorization URL with the exact same scopes
Once the user authorizes, prompt for the authorization code
Use the authorization code to retrieve the access token, with the same scopes

You only have to execute it once.

Streaming

FediVuln-Stream streams data from the Fediverse and uses PyVulnerabilityLookup to create sightings in Vulnerability-Lookup.

usage: FediVuln-Stream [-h] [--user] [--public] [--push-sighting] [--push-status]

Allows access to the streaming API.

options:
  -h, --help       show this help message and exit
  --user           Streams events that are relevant to the authorized user, i.e. home timeline and notifications.
  --public         Streams public events.
  --push-sighting  Push the sightings to Vulnerability Lookup.
  --push-status    Push the status to Vulnerability Lookup.

Examples

Streams events that are relevant to the authorized user, i.e. home timeline and notifications:

$ FediVuln-Stream --user --push-sighting

If you want to get the stream of public events (local server + connected servers):

$ FediVuln-Stream --public --push-sighting

Using the --push-sighting argument, detected vulnerability IDs will be recorded in Vulnerability Lookup as sightings.

Publishing

FediVuln-Publish subscribes to an HTTP or Redis event stream and publishes the incoming data to the Fediverse.

$ FediVuln-Publish --help
usage: FediVuln-Publish [-h] [-t {vulnerability,comment,bundle,sighting}]

options:
  -h, --help            show this help message and exit
  -t, --topic {vulnerability,comment,bundle,sighting}
                        The topic to subscribe to.

The authentication to the HTTP event stream is automatically handled by PyVulnerabilityLookup.

For each incoming event, a status will be posted using the configured Mastodon account. The format of the status is dynamically tailored to the specific event topic. For instance, executing the command FediVuln-Publish -t comment will capture all new comments and share a human-readable summary on the Fediverse, including a link to the original comment on the Vulnerability-Lookup instance.

Search

usage: FediVuln-Search [-h] --query QUERY

Allows you to search for users, tags and, when enabled, full text, by default within your own posts and those you have interacted with.

options:
  -h, --help     show this help message and exit
  --query QUERY  Query of the search.

License

FediVuln is licensed under GNU General Public License version 3

Copyright (c) 2024 Computer Incident Response Center Luxembourg (CIRCL)
Copyright (C) 2024 Cédric Bonhomme - https://github.com/cedricbonhomme

CIRCL/FediVuln