OpenCTI External Ingestion Connector Template

Table of Contents

• OpenCTI External Ingestion Connector Template
  • Introduction
  • Installation
    • Requirements
  • Configuration variables
    • OpenCTI environment variables
    • Base connector environment variables
    • Connector extra parameters environment variables
  • Deployment
    • Docker Deployment
    • Manual Deployment
  • Usage
  • Behavior
  • Debugging
  • Additional information

Introduction

Installation

Requirements

• OpenCTI Platform >= 6...

Configuration variables

There are a number of configuration options, which are set either in docker-compose.yml (for Docker) or in config.yml (for manual deployment).

OpenCTI environment variables

Below are the parameters you'll need to set for OpenCTI:

Parameter	config.yml	Docker environment variable	Mandatory	Description
OpenCTI URL	url	OPENCTI_URL	Yes	The URL of the OpenCTI platform.
OpenCTI Token	token	OPENCTI_TOKEN	Yes	The default admin token set in the OpenCTI platform.

Base connector environment variables

Below are the parameters you'll need to set for running the connector properly:

Parameter	config.yml	Docker environment variable	Default	Mandatory	Description
Connector ID	id	CONNECTOR_ID	/	Yes	A unique UUIDv4 identifier for this connector instance.
Connector Type	type	CONNECTOR_TYPE	EXTERNAL_IMPORT	Yes	Should always be set to EXTERNAL_IMPORT for this connector.
Connector Name	name	CONNECTOR_NAME		Yes	Name of the connector.
Connector Scope	scope	CONNECTOR_SCOPE		Yes	The scope or type of data the connector is importing, either a MIME type or Stix Object.
Log Level	log_level	CONNECTOR_LOG_LEVEL	info	Yes	Determines the verbosity of the logs. Options are debug, info, warn, or error.

Connector extra parameters environment variables

Below are the parameters you'll need to set for the connector:

Parameter	config.yml	Docker environment variable	Default	Mandatory	Description
API base URL	api_base_url			Yes
API key	api_key			Yes

Deployment

Docker Deployment

Before building the Docker container, you need to set the version of pycti in requirements.txt equal to whatever version of OpenCTI you're running. Example, pycti==5.12.20. If you don't, it will take the latest version, but sometimes the OpenCTI SDK fails to initialize.

Build a Docker Image using the provided Dockerfile.

Example:

# Replace the IMAGE NAME with the appropriate value
docker build . -t [IMAGE NAME]:latest

Make sure to replace the environment variables in docker-compose.yml with the appropriate configurations for your environment. Then, start the docker container with the provided docker-compose.yml

docker compose up -d
# -d for detached

Manual Deployment

Create a file config.yml based on the provided config.yml.sample.

Replace the configuration variables (especially the "ChangeMe" variables) with the appropriate configurations for you environment.

Install the required python dependencies (preferably in a virtual environment):

pip3 install -r requirements.txt

Then, start the connector from recorded-future/src:

python3 main.py

Usage

After Installation, the connector should require minimal interaction to use, and should update automatically at a regular interval specified in your docker-compose.yml or config.yml in duration_period.

However, if you would like to force an immediate download of a new batch of entities, navigate to:

Data management -> Ingestion -> Connectors in the OpenCTI platform.

Find the connector, and click on the refresh button to reset the connector's state and force a new download of data by re-running the connector.

Behavior

Debugging

The connector can be debugged by setting the appropiate log level. Note that logging messages can be added using self.helper.connector_logger,{LOG_LEVEL}("Sample message"), i. e., self.helper.connector_logger.error("An error message").

Additional information