{"id":13453794,"url":"https://github.com/tenzir/threatbus","last_synced_at":"2025-12-30T08:14:35.873Z","repository":{"id":40272839,"uuid":"168499203","full_name":"tenzir/threatbus","owner":"tenzir","description":"🚌 Threat Bus – A threat intelligence dissemination layer for open-source security tools.","archived":true,"fork":false,"pushed_at":"2023-03-17T13:44:28.000Z","size":910,"stargazers_count":262,"open_issues_count":1,"forks_count":16,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-03-01T07:26:00.766Z","etag":null,"topics":["cif","cif3","ids","misp","opencti","opencti-connector","sightings","threat-bus","threat-hunting","threat-intelligence","threat-intelligence-data","threatintel","zeek"],"latest_commit_sha":null,"homepage":"https://docs.tenzir.com/threatbus","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tenzir.png","metadata":{"funding":{"github":["tenzir"]},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-01-31T09:33:49.000Z","updated_at":"2025-01-31T22:58:21.000Z","dependencies_parsed_at":"2024-01-03T04:13:28.687Z","dependency_job_id":"912ce731-132c-4909-a0cb-45d95d0d46f5","html_url":"https://github.com/tenzir/threatbus","commit_stats":{"total_commits":683,"total_committers":12,"mean_commits":"56.916666666666664","dds":"0.37188872620790625","last_synced_commit":"0eeff55fb390916a817d7172ad8a9a89de0007e0"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tenzir%2Fthreatbus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tenzir%2Fthreatbus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tenzir%2Fthreatbus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tenzir%2Fthreatbus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tenzir","download_url":"https://codeload.github.com/tenzir/threatbus/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245194304,"owners_count":20575738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cif","cif3","ids","misp","opencti","opencti-connector","sightings","threat-bus","threat-hunting","threat-intelligence","threat-intelligence-data","threatintel","zeek"],"created_at":"2024-07-31T08:00:47.486Z","updated_at":"2025-12-14T04:03:06.216Z","avatar_url":"https://github.com/tenzir.png","language":"Python","funding_links":["https://github.com/sponsors/tenzir"],"categories":["Threat Detection and Hunting","Threat intelligence"],"sub_categories":["Tools","Threat hunting"],"readme":"\n\u003ch1 align=\"center\"\u003e\n  Threat Bus\n\u003c/h1\u003e\n\u003ch4 align=\"center\"\u003e\n\nA threat intelligence dissemination layer for open-source security tools.\n\n[![PyPI Status][pypi-badge]][pypi-url]\n[![Build Status][ci-badge]][ci-url]\n[![Total alerts][lgtm-alerts-badge]][lgtm-alerts-url]\n[![Language grade: Python][lgtm-quality-badge]][lgtm-quality-url]\n[![Development Status][beta-badge]][latest-release-url]\n[![Latest Release][latest-release-badge]][latest-release-url]\n[![License][license-badge]][license-url]\n\n[_Getting Started_](#getting-started) \u0026mdash;\n[_Contributing Guidelines_][contributing-url] \u0026mdash;\n[_Writing Plugins_](#plugin-development) \u0026mdash;\n[_License_](#license) \u0026mdash;\n[_Documentation_][docs]\n\u003c/h4\u003e\n\u003cdiv align=\"center\"\u003e\n\n[![Chat][chat-badge]][chat-url]\n\u003c/div\u003e\n\n## Key Features\n\n- **Connect Open-Source Security Tools**: Threat Bus is a pub-sub broker for\n  threat intelligence data. With *Threat Bus* you can seamlessly integrate\n  threat intel platforms like [OpenCTI][opencti] or [MISP][misp] with detection\n  tools and databases like [Zeek][zeek] or [VAST][vast].\n\n- **Native STIX-2**: Threat Bus transports indicators and sightings encoded as\n  per the [STIX-2](https://oasis-open.github.io/cti-documentation/stix/intro)\n  open format specification.\n\n- **Plugin-based Architecture**: The project is plugin-based and can be extended\n  easily. Read about the different [plugin types][plugin-types] and\n  [how to write your own][plugin-development].\n  We welcome contributions to adopt new open source tools!\n\n- **Official Plugins**: We maintain many plugins right in the official Threat\n  Bus repository. Check out our integrations for [MISP][misp], [Zeek][zeek],\n  [CIFv3][cif], and generally apps that connect via [ZeroMQ][zmq], like\n  [vast-threatbus][vast-threatbus] and our\n  [OpenCTI connector][opencti-connector].\n\n- **Snapshotting**: The snapshot feature allows subscribers to directly request\n  threat intelligence data for a certain time range from other applications.\n  Threat Bus handles the point-to-point communication of all involved apps.\n\n\n## Getting Started\n\nThe `config.yaml.example` file provides a working configuration for Threat Bus\nwith all existing application plugins enabled together with the RabbitMQ\nbackbone.\n\nThe following example shows how to connect [Zeek][zeek] via Threat Bus. There\nare more integrations available, so make sure to check out all\n[Threat Bus projects on PyPI](https://pypi.org/search/?q=threatbus).\n\nThe example assumes that `threatbus` is available in your PATH. See the\nsection on [Installation](#installation) below for more information on how to\nget there.\n\n*Start Threat Bus*\n\n```sh\nthreatbus\n```\n\n*Start with a specially named config file*\n\nThe `config.yaml.example` file in this directory gives an overview of\nthe available config keys and their default values.\n\n```sh\nthreatbus -c /path/to/your/special-config.yaml\n```\n\n*Environment variables take precedence over config file values. Prefix\neverything with `THREATBUS_`*\n\n```sh\nexport THREATBUS_LOGGING__CONSOLE=true\nthreatbus -c /path/to/your/special-config.yaml\n```\n\nNote that you must use a double underscores `__` in your env to refer to nested\nconfig variables.\n\n*Start Zeek as Threat Bus app*\n\n```sh\nzeek -i \u003cINTERFACE\u003e -C ./apps/zeek/threatbus.zeek\n```\n\n*Start Zeek and request a snapshot*\n\n```sh\nzeek -i \u003cINTERFACE\u003e -C ./apps/zeek/threatbus.zeek \"Tenzir::snapshot_intel=30 days\"\n```\n\nThreat Bus also ships as pre-built Docker image and is available on\n[Docker Hub](https://hub.docker.com/r/tenzir/threatbus).\n\n*Use the Threat Bus Docker container*\n\n```sh\ndocker run tenzir/threatbus:latest --help\n```\n\n*Start Threat Bus container with a custom config file*\n\n```sh\ndocker run -p 47661:47661 -v $PWD/my-custom-config.yaml:/opt/tenzir/threatbus/my-custom-config.yaml tenzir/threatbus:latest -c my-custom-config.yaml\n```\n\nTip: Threat Bus checks for config files with default names. If you mount your\nconfig file to `/opt/tenzir/threatbus/config.yaml`, you can start the\napplication without specifying the config file location with the `-c` parameter.\n\n## Installation\n\nInstall `threatbus` and all plugins that you require. Optionally, use a virtual\nenvironment.\n\nNote that Threat Bus requires at least Python 3.7+, earlier versions are not supported.\n\n```\nvirtualenv venv                       # optional\nsource venv/bin/activate              # optional\npip install threatbus\npip install threatbus-inmem           # inmemory backbone plugin\npip install threatbus-rabbitmq        # RabbitMQ backbone plugin\npip install threatbus-misp[zmq]       # MISP application plugin\npip install threatbus-zeek            # Zeek application plugin\npip install threatbus-zmq             # ZeroMQ application plugin\npip install threatbus-\u003cplugin_name\u003e\n```\n\n### Testing\n\nUse the `Makefile` to run unit and integration tests.\n\n```\nmake unit-tests\nmake integration-tests\n```\n\nThe integration tests require a local [Zeek][zeek] and\n[Docker](https://www.docker.com/) installation.\n\n\n## Development\n\nSetup a virtual environment and install `threatbus` and some plugins with the\nin development mode:\n\n```\nvirtualenv venv\nsource venv/bin/activate\nmake dev-mode\n```\n\n### Configuration \u0026 Extension\n\nA plugin must define a `setup.py`. Whenever a plugin is installed, you have to\nadd a corresponding configuration section to `threatbus`' `config.yaml`. That\nsection has to be named after the `name` in the entrypoint declaration of the\nplugin's `setup.py` file.\n\nPlease adhere to the [plugin naming conventions](https://pluggy.readthedocs.io/en/latest/#a-complete-example)\nand always prefix your plugin name with `threatbus-`.\n\nPlugins can either be *apps* or *backbones*. Application plugins (apps) add new\nfunctionality to Threat Bus and allow communication to a specific app and/or\nvia a specific protocol (e.g., ZeroMQ or Zeek/broker). Backbone plugins add a\nnew storage and distribution backend to Threat Bus (e.g., in-memory or\nRabbitMQ).\n\nExample:\n\n- plugin folder structure:\n  ```sh\n  plugins\n  ├── apps\n  |   └── threatbus-myapp\n  │       ├── setup.py\n  |       └── threatbus_myapp.py\n  └── backbones\n      └── threatbus-inmem\n          ├── setup.py\n          └── threatbus_inmem.py\n  ```\n- `setup.py`\n  ```py\n  from setuptools import setup\n  setup(\n    name=\"threatbus-myapp\",\n    install_requires=\"threatbus\",\n    entry_points={\"threatbus.app\": [\"myapp = threatbus_myapp\"]},\n    py_modules=[\"threatbus_myapp\"],\n  )\n  ```\n- `config.yaml` entry for `threatbus`\n  ```yaml\n  ...\n  plugins:\n    apps:\n      myapp:\n      ...\n  ```\n\n### Threat Bus API\n\nPlugins specifications are available in `threatbus/appspecs.py` and\n`threatbus/backbonespecs.py`, respectively. For any plugin, you should at least\nimplement the `run` function.\n\nApp plugins are provided two callback functions to use for subscription\nmanagement. Internally, Threat Bus will propagate subscription requests to all\ninstalled backbone plugins.\n\nThe subscription callback allows applications to request an optional snapshot\ntime delta. Threat Bus will forward snapshot requests to all those apps that\nhave implemented the snapshot feature (see `threatbus/appspecs.py`).\n\n### Implementation\n\nPlease use the\n[StoppableWorker](https://github.com/tenzir/threatbus/blob/master/threatbus/stoppable_worker.py)\nbase class to model your plugin's busy work. Plugins should never block the main\nthread of the application. Implementing that class also facilitates a graceful\nshutdown.\n\nAll officially maintained Threat Bus plugins implement `StoppableWorker`. Refer\nto any of the existing plugins for an example.\n\n## License\n\nThreat Bus comes with a [3-clause BSD license][license-url].\n\n\n[opencti]: https://www.opencti.io/\n[opencti-connector]: https://github.com/OpenCTI-Platform/connectors/tree/master/stream/threatbus\n[misp]: https://github.com/misp/misp\n[vast]: https://github.com/tenzir/vast\n[docs]: https://docs.tenzir.com/threatbus\n[zeek]: https://www.zeek.org\n[cif]: https://github.com/csirtgadgets/bearded-avenger\n[zmq]: https://zeromq.org/\n[misp-zmq-config]: https://github.com/MISP/misp-book/tree/master/misp-zmq#misp-zeromq-configuration\n[plugin-types]: https://docs.tenzir.com/threatbus/plugins/overview\n[plugin-development]: https://docs.tenzir.com/threatbus/plugins/plugin-development\n[vast-threatbus]: https://github.com/tenzir/threatbus/tree/master/apps/vast\n\n[pypi-badge]: https://img.shields.io/pypi/v/threatbus.svg\n[pypi-url]: https://pypi.org/project/threatbus\n[contributing-url]: https://github.com/tenzir/.github/blob/master/contributing.md\n[latest-release-badge]: https://img.shields.io/github/commits-since/tenzir/threatbus/latest.svg?color=green\n[latest-release-url]: https://github.com/tenzir/threatbus/releases\n[ci-url]: https://github.com/tenzir/threatbus/actions?query=branch%3Amaster\n[ci-badge]: https://github.com/tenzir/threatbus/workflows/Python%20Egg/badge.svg?branch=master\n[chat-badge]: https://img.shields.io/badge/Slack-Tenzir%20Community%20Chat-brightgreen?logo=slack\u0026color=purple\u0026style=flat\n[chat-url]: http://slack.tenzir.com\n[license-badge]: https://img.shields.io/badge/license-BSD-blue.svg\n[license-url]: https://github.com/tenzir/threatbus/blob/master/COPYING\n[beta-badge]: https://img.shields.io/badge/stage-beta-blue\n[lgtm-alerts-badge]: https://img.shields.io/lgtm/alerts/g/tenzir/threatbus.svg?logo=lgtm\u0026logoWidth=18\n[lgtm-alerts-url]: https://lgtm.com/projects/g/tenzir/threatbus/alerts/\n[lgtm-quality-badge]: https://img.shields.io/lgtm/grade/python/g/tenzir/threatbus.svg?logo=lgtm\u0026logoWidth=18\n[lgtm-quality-url]: https://lgtm.com/projects/g/tenzir/threatbus/context:python\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftenzir%2Fthreatbus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftenzir%2Fthreatbus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftenzir%2Fthreatbus/lists"}