OpenCTI Integration Guide

Vysion provides three Docker Compose connectors for OpenCTI:

Connector	OpenCTI type	Purpose
Vysion Ransomware Feed	External import	Imports ransomware incidents, victims, threat actors, countries, and sectors.
Vysion Enrichment	Internal enrichment	Adds cited evidence notes to supported observables on demand.
Vysion Wallet Detections	External import	Imports reported cryptocurrency wallets and evidence notes.

The connectors create evidence and context. A Vysion match is not, by itself, an assertion that an observable is malicious or owned by an entity. Generated objects identify Vysion as their intelligence provider.

Prerequisites

Before starting, ensure that you have:

• Docker Engine and Docker Compose v2.
• A running OpenCTI platform, RabbitMQ, and OpenCTI workers.
• An OpenCTI API token with connector and import permissions.
• A Vysion API key.
• The Docker network used by the OpenCTI platform.

The connectors were tested with OpenCTI 7.261008.0.

Installation

Clone the connector repository into a directory separate from the OpenCTI deployment:

git clone https://github.com/ByronLabs/vysion-cti.git
cd vysion-cti/opencti
cp env.example .env
chmod 600 .env

Identify the OpenCTI Docker network

Find the OpenCTI platform container, then inspect its network. Replace opencti-opencti-1 if your container has a different name.

docker ps --format '{{.Names}}\t{{.Image}}' | grep 'opencti/platform'
docker inspect opencti-opencti-1 --format '{{range $k, $_ := .NetworkSettings.Networks}}{{$k}}{{"\n"}}{{end}}'

Use that network name as OPENCTI_DOCKER_NETWORK. On a standard Compose deployment it is commonly opencti_default.

Configure .env

Edit .env and set the values below. Do not commit this file or share its values.

# Use the OpenCTI service name and port reachable inside the shared Docker network.
OPENCTI_URL=http://opencti:8080
OPENCTI_TOKEN=replace_with_an_opencti_api_token
OPENCTI_DOCKER_NETWORK=opencti_default

VYSION_API_URL=https://api.vysion.ai
VYSION_API_KEY=replace_with_your_vysion_api_key

VYSION_EXTERNAL_CONNECTOR_ID=replace_with_uuid_1
VYSION_ENRICHMENT_CONNECTOR_ID=replace_with_uuid_2
VYSION_WALLET_CONNECTOR_ID=replace_with_uuid_3

# Optional enrichment sources and controls
VYSION_ENABLE_IM=true
VYSION_ENABLE_LEAKS=false
VYSION_MAX_TLP=TLP:GREEN

VYSION_ENABLE_LEAKS is disabled by default. Enable it only when external leak-content searches are allowed by your policy.

Start the connectors

Start ransomware import and manual enrichment:

docker compose --profile vysion up -d --build

Start the independent wallet feed:

docker compose --profile vysion-wallets up -d --build connector-vysion-wallets

Verify registration and inspect logs:

docker compose --profile vysion --profile vysion-wallets ps
docker compose --profile vysion --profile vysion-wallets logs --tail=50

In OpenCTI, open Data → Ingestion → Connectors. The connectors should appear as active.

Enrichment

Open a supported observable, choose Enrichment, then select Vysion Enrichment. Results are attached as notes; execution details are available in the connector’s Works tab.

Observable	Sources
URL, Domain-Name, Hostname	Documents
Email-Addr, Cryptocurrency-Wallet	Documents, instant messaging, leaks*
User-Account	Instant messaging, leaks*
IPv4-Addr, IPv6-Addr, File hashes	Leaks*

* Requires VYSION_ENABLE_LEAKS=true.

Wallet chain labels

Wallet enrichment requires explicit chain labels. Add one or more of the following OpenCTI labels to a Cryptocurrency Wallet observable:

chain:BTC
chain:ETH
chain:XMR
chain:XRP
chain:ZEC
chain:DOT
chain:BNB
chain:DASH

The connector queries every explicitly labelled chain. It does not infer a chain from the address format.

Evidence handling

• The whitelist label prevents Vysion enrichment.
• Observable TLP markings are checked before querying Vysion; the default maximum is TLP:GREEN.
• Markings are propagated to generated notes.
• Document notes retain a visible table of captures, hashes, and individual Vysion links.
• Leak notes state that a match was found in content indexed by Vysion. Credentials and leak content are not imported into OpenCTI.
• Enrichment does not change the analyst score or the input observable’s author.

Feeds

Ransomware Feed

The ransomware connector runs hourly by default. It imports deterministic STIX objects for ransomware incidents and includes:

• Incident type: ransomware
• Source: Vysion
• First-seen time: Vysion detection time
• Threat actor, victim organization, and optional country and sector context

Configure the schedule with:

CONNECTOR_RUN_EVERY=1h
VYSION_LOOKBACK_HOURS=24

The interval must not exceed the lookback window, and the lookback is limited to 24 hours. The connector catches up in bounded daily windows for up to 30 days. It preserves state until an OpenCTI worker confirms the import; failed worker jobs replay deterministic bundles.

Wallet Detections

The wallet feed polls hourly by default. Configure the source and interval with:

VYSION_WALLET_PLATFORM=darknet
VYSION_WALLET_INTERVAL_SECONDS=3600

Supported platforms are darknet, telegram, discord, and all. Wallet labels retain each chain reported by Vysion. The feed also uses durable, deterministic imports and bounded catch-up.

Feed safety

Both feeds use bounded chunks and preserve their cursor until worker completion. Invalid source records are quarantined by ID and batch for later retry while valid records continue. Do not run multiple instances using the same connector ID.

Operations

Update

Keep connector IDs and .env when upgrading, then rebuild and restart:

cd vysion-cti
git pull --ff-only
cd opencti
docker compose --profile vysion --profile vysion-wallets up -d --build

Legacy ransomware incidents created before deterministic IDs are not migrated automatically.

Stop and remove

To stop the connectors without changing their OpenCTI state:

docker compose --profile vysion --profile vysion-wallets stop

Do not remove OpenCTI volumes unless you intend to erase platform data and connector state.

Troubleshooting

Symptom	Check
Connector does not register	Check OPENCTI_URL, token permissions, and that OPENCTI_DOCKER_NETWORK matches the platform network.
Authentication or connection error	Review docker compose logs --tail=100; verify Vysion API key and outbound HTTPS access.
Enrichment has no results	Confirm the observable type, source opt-in settings, wallet chain labels, and maximum TLP.
Feed is pending or failed	Open the connector’s Works tab. Do not clear connector state before investigating.
No wallet connector in OpenCTI	Start the optional vysion-wallets profile.

For implementation details and live validation commands, see the OpenCTI connector README.