# FediVuln
A client to gather vulnerability-related information from the Fediverse.
The collected data is then sent to the
[Vulnerability-Lookup](https://github.com/cve-search/vulnerability-lookup) API as sightings.
## Installation
[pipx](https://github.com/pypa/pipx) is an easy way to install and run Python applications in isolated environments.
It's easy to [install](https://github.com/pypa/pipx?tab=readme-ov-file#on-linux).
```bash
$ 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](https://github.com/CIRCL/FediVuln/blob/main/fedivuln/conf_sample.py) of configuration.
## Usage
### Register your application
```bash
$ 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.
```bash
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:
```bash
$ FediVuln-Stream --user --push-sighting
```
If you want to get the stream of public events (local server + connected servers):
```bash
$ FediVuln-Stream --public --push-sighting
```
Using the ``--push-sighting`` argument, detected vulnerability IDs will be recorded in
[Vulnerability Lookup](https://github.com/cve-search/vulnerability-lookup) as
[sightings](https://vulnerability-lookup.readthedocs.io/en/latest/sightings.html).
### Publishing
``FediVuln-Publish`` subscribes to an HTTP or Redis event stream and publishes the incoming data to the Fediverse.
```bash
$ 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
```bash
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](https://github.com/CIRCL/FediVuln) is licensed under
[GNU General Public License version 3](https://www.gnu.org/licenses/gpl-3.0.html)
~~~
Copyright (c) 2024-2025 Computer Incident Response Center Luxembourg (CIRCL)
Copyright (C) 2024-2025 Cédric Bonhomme - https://github.com/cedricbonhomme
~~~
Raw data
{
"_id": null,
"home_page": "https://github.com/CIRCL/FediVuln",
"name": "FediVuln",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "Vulnerability-Lookup, Vulnerability, CVE, Fediverse, Mastodon",
"author": "C\u00e9dric Bonhomme",
"author_email": "cedric.bonhomme@circl.lu",
"download_url": "https://files.pythonhosted.org/packages/2f/da/481672fd5177c75d0a5a7fe3766b665661568ecf0162517ba63ed8872e72/fedivuln-0.7.0.tar.gz",
"platform": null,
"description": "# FediVuln\n\nA client to gather vulnerability-related information from the Fediverse.\nThe collected data is then sent to the\n[Vulnerability-Lookup](https://github.com/cve-search/vulnerability-lookup) API as sightings.\n\n\n## Installation\n\n[pipx](https://github.com/pypa/pipx) is an easy way to install and run Python applications in isolated environments.\nIt's easy to [install](https://github.com/pypa/pipx?tab=readme-ov-file#on-linux).\n\n```bash\n$ pipx install FediVuln\n$ export FEDIVULN_CONFIG=~/.FediVuln/conf.py\n```\n\nThe configuration for FediVuln should be defined in a Python file (e.g., ``~/.FediVuln/conf.py``).\nYou must then set an environment variable (``FEDIVULN_CONFIG``) with the full path to this file.\n\nYou can have a look at [this example](https://github.com/CIRCL/FediVuln/blob/main/fedivuln/conf_sample.py) of configuration.\n\n\n## Usage\n\n### Register your application\n\n```bash\n$ FediVuln-Register\n```\n\nThis script uses OAuth in order to retrieve the access token. This is achieved in several steps.\n\n- Register the application with Mastodon instance, a including all necessary scopes\n- Instantiate Mastodon client with client credentials\n- Log in - Generate authorization URL with the exact same scopes\n- Once the user authorizes, prompt for the authorization code\n- Use the authorization code to retrieve the access token, with the same scopes\n\nYou only have to execute it once.\n\n\n### Streaming\n\n``FediVuln-Stream`` streams data from the Fediverse and uses PyVulnerabilityLookup to create sightings in Vulnerability-Lookup.\n\n```bash\nusage: FediVuln-Stream [-h] [--user] [--public] [--push-sighting] [--push-status]\n\nAllows access to the streaming API.\n\noptions:\n -h, --help show this help message and exit\n --user Streams events that are relevant to the authorized user, i.e. home timeline and notifications.\n --public Streams public events.\n --push-sighting Push the sightings to Vulnerability Lookup.\n --push-status Push the status to Vulnerability Lookup.\n```\n\n#### Examples\n\nStreams events that are relevant to the authorized user, i.e. home timeline and notifications:\n\n```bash\n$ FediVuln-Stream --user --push-sighting\n```\n\nIf you want to get the stream of public events (local server + connected servers):\n\n```bash\n$ FediVuln-Stream --public --push-sighting\n```\n\nUsing the ``--push-sighting`` argument, detected vulnerability IDs will be recorded in\n[Vulnerability Lookup](https://github.com/cve-search/vulnerability-lookup) as\n[sightings](https://vulnerability-lookup.readthedocs.io/en/latest/sightings.html).\n\n\n### Publishing\n\n``FediVuln-Publish`` subscribes to an HTTP or Redis event stream and publishes the incoming data to the Fediverse.\n\n```bash\n$ FediVuln-Publish --help\nusage: FediVuln-Publish [-h] [-t {vulnerability,comment,bundle,sighting}]\n\noptions:\n -h, --help show this help message and exit\n -t, --topic {vulnerability,comment,bundle,sighting}\n The topic to subscribe to.\n```\n\nThe authentication to the HTTP event stream is automatically handled by PyVulnerabilityLookup.\n\nFor each incoming event, a status will be posted using the configured Mastodon account.\nThe format of the status is dynamically tailored to the specific event topic.\nFor instance, executing the command ``FediVuln-Publish -t comment`` will capture all\nnew comments and share a human-readable summary on the Fediverse, including a link to the\noriginal comment on the Vulnerability-Lookup instance.\n\n\n\n### Search\n\n```bash\nusage: FediVuln-Search [-h] --query QUERY\n\nAllows you to search for users, tags and, when enabled, full text, by default within your own posts and those you have interacted with.\n\noptions:\n -h, --help show this help message and exit\n --query QUERY Query of the search.\n```\n\n\n\n## License\n\n[FediVuln](https://github.com/CIRCL/FediVuln) is licensed under\n[GNU General Public License version 3](https://www.gnu.org/licenses/gpl-3.0.html)\n\n~~~\nCopyright (c) 2024-2025 Computer Incident Response Center Luxembourg (CIRCL)\nCopyright (C) 2024-2025 C\u00e9dric Bonhomme - https://github.com/cedricbonhomme\n~~~\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "A client to gather vulnerability-related information from the Fediverse.",
"version": "0.7.0",
"project_urls": {
"Homepage": "https://github.com/CIRCL/FediVuln",
"Repository": "https://github.com/CIRCL/FediVuln"
},
"split_keywords": [
"vulnerability-lookup",
" vulnerability",
" cve",
" fediverse",
" mastodon"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d610fb350fe9f0f5bca1cfe53be3a5850c00655e4c64f9ea693d3578eead792e",
"md5": "34e65fcdc6f1aadbcf4080ca8e593077",
"sha256": "9583737eb28bef2c2c7e2329f6caf8b6008fbfc6b83c6f33914855a573b82bfc"
},
"downloads": -1,
"filename": "fedivuln-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34e65fcdc6f1aadbcf4080ca8e593077",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 36689,
"upload_time": "2025-01-14T19:50:27",
"upload_time_iso_8601": "2025-01-14T19:50:27.157072Z",
"url": "https://files.pythonhosted.org/packages/d6/10/fb350fe9f0f5bca1cfe53be3a5850c00655e4c64f9ea693d3578eead792e/fedivuln-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2fda481672fd5177c75d0a5a7fe3766b665661568ecf0162517ba63ed8872e72",
"md5": "9f424a67d7d8100e4a5f749785ce9e66",
"sha256": "45a454fa02ff1110f5a64c6fbe0073c77e8a4e0131b735fbca7236d5dd8bdcf3"
},
"downloads": -1,
"filename": "fedivuln-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "9f424a67d7d8100e4a5f749785ce9e66",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 21311,
"upload_time": "2025-01-14T19:50:30",
"upload_time_iso_8601": "2025-01-14T19:50:30.185217Z",
"url": "https://files.pythonhosted.org/packages/2f/da/481672fd5177c75d0a5a7fe3766b665661568ecf0162517ba63ed8872e72/fedivuln-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-14 19:50:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CIRCL",
"github_project": "FediVuln",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fedivuln"
}
JSON
