OpenTAXII

OpenTAXII is a Python implementation of the TAXII (Trusted Automated eXchange of Indicator Information) services specification (versions 1.0 and 1.1). It provides a framework for sharing cyber threat intelligence information between parties.

Key features include:

• Full implementation of TAXII 1.0 and 1.1 specifications.
• Customizable APIs.
• Authentication mechanisms.
• Flexible logging.
• An extendable architecture based on TTA (TAXII transport agent) and TMH (TAXII message handler) components.

Understanding the project structure:

• docker/: Docker configuration files.
• docs/: Source files for building the documentation.
• examples/: Configuration and code examples.
• opentaxii/: The core OpenTAXII source code.
• tests/: The OpenTAXII test suite.

OpenTAXII is designed to be modular by separating the implementation of different layers. Developers can extend the system by interacting with the following layers:

• Transport layer: A web application based on Flask.
• TAXII logic layer: Contains the TAXII server, services, and message handlers (TMH).
• Persistence layer: An extendable Persistence API for data storage.
• Authentication layer: An extendable Authentication API for managing access control.

OpenTAXII is designed to be extensible through two primary mechanisms:

1. API Implementations: Users can swap out core logic (Persistence and Authentication) by providing custom classes that inherit from the base API classes (opentaxii.persistence.api.OpenTAXIIPersistenceAPI or opentaxii.auth.api.OpenTAXIIAuthAPI). These are configured via the OpenTAXII config file and loaded at startup.

2. Signals (Hooks): This is an asynchronous notification system. Instead of replacing core logic, you attach 'listeners' to specific events. You register these by adding the module name to the hooks field in the configuration. This allows your code to react to events like CONTENT_BLOCK_CREATED without modifying the core server code.

For custom requirements like installing additional Python packages (e.g., mysql-python) or using a different database driver, you should extend the base image using a Dockerfile.

Example Dockerfile to add custom packages and a custom configuration:

FROM eclecticiq/opentaxii:latest
MAINTAINER EclecticIQ <opentaxii@eclecticiq.com>

RUN pip install mysql-python \
    && pip install custom-package

COPY opentaxii.yml /input/opentaxii.yml

Build your custom image using:

$ docker build -t eclecticiq/opentaxii-mysql .

To replace the default SQL-based storage, you can implement a custom Persistence API. Your custom class must inherit from opentaxii.persistence.api.OpenTAXIIPersistenceAPI and implement all its defined methods.

To activate your custom implementation:

1. Ensure the module containing your class is in the PYTHONPATH.
2. In the OpenTAXII configuration file, set the full class name and any required constructor parameters for the persistence API.

OpenTAXII will load the class and instantiate it during the server startup procedure.

# Example conceptual implementation
from opentaxii.persistence.api import OpenTAXIIPersistenceAPI

class MyCustomPersistence(OpenTAXIIPersistenceAPI):
    def __init__(self, custom_param):
        self.param = custom_param
    # ... implement required methods ...

The OpenTAXII container exposes specific volumes that can be mounted to customize the instance behavior:

• /data: Contains the SQLite databases used by the default instance.
• /input/data-configuration.yml: Used to preload the instance with services, collections, and accounts. The file must be named exactly data-configuration.yml to be executed.
• /input/opentaxii.yml: Used to overwrite the default OpenTAXII configuration. The file must be named exactly opentaxii.yml to be recognized.

To mount local configuration or data files, map them to the /input directory inside the container:

$ docker run -d -p 9000:9000 -v /some/path/examples:/input eclecticiq/opentaxii

You can verify if the OpenTAXII service is running and healthy by querying the /management/health endpoint. This endpoint returns a JSON object indicating the service status.

$ curl http://localhost:9000/management/health
{
  "alive": true
}

To install OpenTAXII from the cloned repository, use the setup.py script within a Python virtual environment.

(venv) $ python setup.py install

OpenTAXII emits asynchronous notifications (signals) that allow users to trigger custom code in response to specific events.

To attach custom listeners:

1. Create a module containing your listener functions.
2. Ensure this module is in the PYTHONPATH.
3. In the OpenTAXII configuration file, specify the full module name in the hooks field.

Supported signals include:

• CONTENT_BLOCK_CREATED: Emitted when a new content block is created.
• INBOX_MESSAGE_CREATED: Emitted when a new inbox message is created.
• SUBSCRIPTION_CREATED: Emitted when a new subscription is created.

# Example of a hook module (e.g., hooks.py)
from opentaxii.signals import CONTENT_BLOCK_CREATED

def my_listener(signal, *args, **kwargs):
    print("New content block detected!")

# The configuration would then point to this module
# hooks = 'path.to.your.hooks_module'

You can use Docker Compose to manage a TAXII 2 instance.

1. Start the stack using the provided configuration:

   docker compose -f examples/docker-compose-taxii2.yml up

2. Add dummy data to the running instance:

   docker exec -i examples-opentaxii-1 bash < examples/taxii2/data-setup.sh

# Start
docker compose -f examples/docker-compose-taxii2.yml up

# To add dummy data, run this while the compose project is running
docker exec -i examples-opentaxii-1 bash < examples/taxii2/data-setup.sh