Threatfox Censys

Threatfox Censys is a tool to query Censys Search for IP addresses and domains and then parses the JSON and submits the results to Threatfox.

Features

• Create dynamic fingerprints for various IoCs
  • Create a fingerprint using the create-fingerprint command
  • Fingerprint file: fingerprints.yaml
• Uses the Censys Search API
• Submit IoCs to ThreatFox
  • Submit IoCs using the scan command
  • Links Censys Search in ThreatFox IoC reference
  • Tags IoCs with censys and the autonomous system name
• Uses a PostgreSQL database to store the IoCs submitted to ThreatFox

Installation

Prerequisites

• Python 3.10
• A PostgreSQL 15+ Instance

You will need to install poetry on Python 3.10.

curl -sSL https://install.python-poetry.org | python3 -

Clone the repository.

git clone https://github.com/censys-workshop/threatfox-censys.git

Then install the dependencies.

poetry install

Then you will need to copy the .env.example file to .env and add your Censys API ID and Secret as well as your Threatfox API key (from https://auth.abuse.ch/). Also make sure to set the DATABASE_URL to your database.

cp .env.example .env

Then you will need to run the database migrations.

poetry run threatfox-censys database-migrations

Usage

Scan

Scan Censys Search for IoCs and submit them to ThreatFox.

poetry run threatfox-censys scan

Mastodon Posts

You can also post the results to Mastodon. Make sure to set the MASTODON_API_URL and MASTODON_ACCESS_TOKEN environment variables. It will post a toot for each IoC found. Simply create a Mastodon app and get the access token.

Create Fingerprint

Prompt the user to create a fingerprint for an IoC.

poetry run threatfox-censys create-fingerprint

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Testing

poetry run pytest

Linting

poetry run flake8

Formatting

poetry run black .
poetry run isort .
poetry run pyupgrade --py310-plus threatfox_censys/*.py scripts/*.py

License

Threatfox Censys is licensed under the MIT license.

Author

• Aidan Holland

Acknowledgements

• Censys
• Threatfox

TODO

• Add more fingerprint.
• Add more documentation.