Skip to content

Commit b78c1dd

Browse files
moin-loginsoftCTIBurn0ut
moin-loginsoft
authored and
CTIBurn0ut
committed
VMRay-Platform new integration (#5427)
1 parent 4c5e66a commit b78c1dd

File tree

15 files changed

+2738
-0
lines changed

15 files changed

+2738
-0
lines changed

‎external-import/vmray-platform/Dockerfile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
FROM python:3.12-alpine
2+
ENV CONNECTOR_TYPE=EXTERNAL_IMPORT
3+
4+
# Copy the connector
5+
COPY src /opt/opencti-connector-vmray-platform
6+
7+
# Install Python modules
8+
# hadolint ignore=DL3003
9+
RUN apk update && apk upgrade && \
10+
apk --no-cache add git build-base libmagic libffi-dev libxml2-dev libxslt-dev
11+
12+
RUN cd /opt/opencti-connector-vmray-platform && \
13+
pip3 install --no-cache-dir -r requirements.txt && \
14+
apk del git build-base && \
15+
rm -rf /var/cache/apk/*
16+
17+
# Expose and entrypoint
18+
COPY entrypoint.sh /
19+
RUN chmod +x /entrypoint.sh
20+
ENTRYPOINT ["/entrypoint.sh"]

‎external-import/vmray-platform/README.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# OpenCTI VMRay Platform Connector
2+
3+
Table of Contents
4+
5+
- [OpenCTI VMRay Platform Connector](#opencti-vmray-platform-connector)
6+
- [Introduction](#introduction)
7+
- [Installation](#installation)
8+
- [Requirements](#requirements)
9+
- [Configuration variables](#configuration-variables)
10+
- [OpenCTI environment variables](#opencti-environment-variables)
11+
- [Base connector environment variables](#base-connector-environment-variables)
12+
- [VMRay Platform environment variables](#vmray-platform-environment-variables)
13+
- [Deployment](#deployment)
14+
- [Docker Deployment](#docker-deployment)
15+
- [Manual Deployment](#manual-deployment)
16+
- [Usage](#usage)
17+
- [Behavior](#behavior)
18+
- [Debugging](#debugging)
19+
20+
21+
## Introduction
22+
VMRay is an advanced malware sandbox and threat analysis platform used by hundreds of leading security teams worldwide, including Fortune 100 enterprises, government agencies, financial institutions, and MSSPs. By combining dynamic, evasion-resistant sandboxing with rich, reusable output, VMRay enables security teams to investigate unknown, advanced, and targeted threats, reduce analysis time, and build reliable, independent threat intelligence on the attacks that actually target their environment.
23+
24+
This connector continuously ingests high-quality IOCs and analysis context from VMRay Platform into OpenCTI, including classifications, threat names, and other enriched observables derived from in-depth malware and phishing analysis. By bringing VMRay’s definitive verdicts and noise-free data into OpenCTI, security, IR, and threat intel teams can better correlate suspicious activity, prioritize investigations, and strengthen their overall detection and response workflows.
25+
26+
## Installation
27+
28+
### Requirements
29+
30+
- OpenCTI Platform >= 6.9.0
31+
32+
## Configuration variables
33+
34+
There are a number of configuration options, which are set either in `docker-compose.yml` (for Docker) or
35+
in `config.yml` (for manual deployment).
36+
37+
### OpenCTI environment variables
38+
39+
Below are the parameters you'll need to set for OpenCTI:
40+
41+
| Parameter | config.yml | Docker environment variable | Mandatory | Description |
42+
|---------------|------------|-----------------------------|-----------|------------------------------------------------------|
43+
| OpenCTI URL | url | `OPENCTI_URL` | Yes | The URL of the OpenCTI platform. |
44+
| OpenCTI Token | token | `OPENCTI_TOKEN` | Yes | The default admin token set in the OpenCTI platform. |
45+
46+
### Base connector environment variables
47+
48+
Below are the parameters you'll need to set for running the connector properly:
49+
50+
| Parameter | config.yml | Docker environment variable | Default | Mandatory | Description |
51+
|-------------------|-----------------|-----------------------------|-----------------|-----------|---------------------------------------------------------------------------------------------|
52+
| Connector ID | id | `CONNECTOR_ID` | / | Yes | A unique `UUIDv4` identifier for this connector instance. | |
53+
| Connector Name | name | `CONNECTOR_NAME` | | Yes | Name of the connector. |
54+
| Connector Scope | scope | `CONNECTOR_SCOPE` | | Yes | The scope or type of data the connector is importing, either a MIME type or Stix Object. |
55+
| Log Level | log_level | `CONNECTOR_LOG_LEVEL` | info | Yes | Determines the verbosity of the logs. Options are `debug`, `info`, `warn`, or `error`. |
56+
| Duration Period | duration_period | `CONNECTOR_DURATION_PERIOD` | PT1D | No | Determines the time interval between each launch of the connector in ISO 8601, ex: `PT30M`. |
57+
58+
### VMRay Platform environment variables
59+
60+
Below are the parameters you'll need to set for the connector:
61+
62+
| Parameter | config.yml | Docker environment variable | Default | Mandatory | Description |
63+
|----------------------------|----------------------------|---------------------------------------------|---------|-----------|---------------------------------------------------------------------------------------------------------------|
64+
| VMRay Server | server | `VMRAY_SERVER` | https://cloud.vmray.com | Yes | VMRay Server URL |
65+
| VMRay API Key | api_key | `VMRAY_API_KEY` | / | Yes | VMRay API Key |
66+
| Inititla Fetch Date | initial_fetch_date | `VMRAY_INITIAL_FETCH_DATE` | YYYY-MM-DD | Yes | Fetch feeds from date (ex: 2025-09-09) |
67+
| VMRay Sample Verdict | sample_verdict | `VMRAY_SAMPLE_VERDICT` | malicious | Yes | Samples can be pulled based on verdict. Supported values include malicious, suspicious
68+
| VMRay IOCs Verdict | iocs_verdict | `VMRAY_IOCS_VERDICT` | malicious | Yes | IOCs can be pulled based on their verdict. Supported values include malicious, suspicious |
69+
| VMRay Default TLP | default_tlp | `VMRAY_DEFAULT_TLP` | TLP:AMBER | Yes | TLP markings can be assigned in OpenCTI platform. Supported values include TLP:AMBER, TLP:RED, TLP:WHITE, TLP:GREEN |
70+
| VMRay Threat Names color | threat_names_color | `VMRAY_THREAT_NAMES_COLOR` | #d60904 | Yes | Configurable color for threat names labels
71+
| VMRay Classifications color | classifications_color | `VMRAY_CLASSIFICATIONS_COLOR` | #fa560a | Yes | Configurable color for family classifications labels
72+
| VMRay VTI color | vti_color | `VMRAY_VTI_COLOR` | #40f5ef | Yes | Configurable color for VMRay Threat Identifier labels
73+
| VMRay MITRE color | mitre_color | `VMRAY_MITRE_COLOR` | #a9f723 | Yes | Configurable color for MITRE Technique ID labels
74+
75+
## Deployment
76+
77+
### Docker Deployment
78+
79+
Before building the Docker container, you need to set the version of pycti in `requirements.txt` equal to whatever
80+
version of OpenCTI you're running. Example, `pycti==6.9.0`. If you don't, it will take the latest version, but
81+
sometimes the OpenCTI SDK fails to initialize.
82+
83+
Build a Docker Image using the provided `Dockerfile`.
84+
85+
Example:
86+
87+
```shell
88+
# Replace the IMAGE NAME with the appropriate value
89+
docker build . -t [IMAGE NAME]:latest
90+
```
91+
92+
Make sure to replace the environment variables in `docker-compose.yml` with the appropriate configurations for your
93+
environment. Then, start the docker container with the provided docker-compose.yml
94+
95+
```shell
96+
docker compose up -d
97+
# -d for detached
98+
```
99+
100+
### Manual Deployment
101+
102+
Create a file `config.yml` based on the provided `config.yml.sample`.
103+
104+
Replace the configuration variables (especially the "**ChangeMe**" variables) with the appropriate configurations for
105+
you environment.
106+
107+
Install the required python dependencies (preferably in a virtual environment):
108+
109+
```shell
110+
pip3 install -r requirements.txt
111+
```
112+
113+
Then, start the connector from vmray-platform/src:
114+
115+
```shell
116+
python3 main.py
117+
```
118+
119+
## Usage
120+
121+
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`.
122+
123+
However, if you would like to force an immediate download of a new batch of entities, navigate to:
124+
125+
`Data management` -> `Ingestion` -> `Connectors` in the OpenCTI platform.
126+
127+
Find the connector, and click on the refresh button to reset the connector's state and force a new
128+
download of data by re-running the connector.
129+
130+
## Behavior
131+
132+
The connector pulls feeds from VMRay Platform and ingests into OpenCTI.
133+
134+
135+
## Debugging
136+
137+
The connector can be debugged by setting the appropriate log level.
138+
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")`.

‎external-import/vmray-platform/__metadata__/connector_manifest.json‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
"title": "VMRay Platform",
3+
"slug": "vmray-platform",
4+
"description": "VMRay provides advanced threat analysis and detection by integrating its unique agentless hypervisor-based sandbox with a real-time analysis. \n\nThis connector enables the ingestion and correlation of VMRay analysis data including IOCs, VTIs, and MITRE ATT&CK techniques for faster detection and response.",
5+
"short_description": "VMRay provides advanced threat analysis and detection by integrating its unique agentless hypervisor-based sandbox with a real-time analysis.",
6+
"logo": "external-import/vmray-platform/__metadata__/logo.png",
7+
"use_cases": [
8+
"Commercial Threat Intel"
9+
],
10+
"verified": false,
11+
"last_verified_date": null,
12+
"playbook_supported": false,
13+
"max_confidence_level": 100,
14+
"support_version": ">= 6.9.0",
15+
"subscription_link": "https://www.vmray.com/vmray-platform/",
16+
"source_code": "https://github.com/OpenCTI-Platform/connectors/tree/master/external-import/vmray-platform",
17+
"manager_supported": false,
18+
"container_version": "rolling",
19+
"container_image": "opencti/connector-vmray-platform",
20+
"container_type": "EXTERNAL_IMPORT"
21+
}

‎external-import/vmray-platform/__metadata__/logo.png‎

24.6 KB
Loading

‎external-import/vmray-platform/docker-compose.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
version: "3"
2+
3+
services:
4+
connector-vmray-platform:
5+
image: opencti/connector-vmray-platform:latest
6+
environment:
7+
- OPENCTI_URL=http://opencti:8080
8+
- OPENCTI_TOKEN=ChangeMe(UUIDv4 token)
9+
- CONNECTOR_ID=VMRay
10+
- CONNECTOR_NAME=VMRay Platform
11+
- CONNECTOR_SCOPE=VMRay
12+
- CONNECTOR_LOG_LEVEL=info
13+
- CONNECTOR_DURATION_PERIOD=P1D
14+
- VMRAY_SERVER=https://cloud.vmray.com
15+
- VMRAY_API_KEY=ChangeMe
16+
- VMRAY_INITIAL_FETCH_DATE=2025-09-09
17+
- VMRAY_SAMPLE_VERDICT='malicious'
18+
- VMRAY_IOCS_VERDICT='malicious'
19+
- VMRAY_DEFAULT_TLP=TLP:AMBER
20+
- VMRAY_THREAT_NAMES_COLOR=#d60904
21+
- VMRAY_CLASSIFICATIONS_COLOR=#fa560a
22+
- VMRAY_VTI_COLOR=#40f5ef
23+
- VMRAY_MITRE_COLOR=#a9f723
24+
restart: always

‎external-import/vmray-platform/entrypoint.sh‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
#!/bin/sh
2+
3+
# Correct working directory
4+
cd /opt/opencti-connector-vmray-platform
5+
6+
# Start the connector
7+
python3 main.py

‎external-import/vmray-platform/src/config.yml.sample‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
opencti:
2+
url: 'http://localhost:8080'
3+
token: 'ChangeMe'
4+
5+
connector:
6+
id: 'VMRay'
7+
type: 'EXTERNAL_IMPORT'
8+
name: 'VMRay Platform'
9+
scope: 'report, malware, indicator, attack-pattern, location'
10+
log_level: 'info'
11+
duration_period: 'P1D' # Interval given for scheduler process in ISO-8601 format
12+
13+
vmray:
14+
server: 'https://cloud.vmray.com'
15+
api_key: 'ChangeMe'
16+
sample_verdict: 'malicious'
17+
iocs_verdict: 'malicious'
18+
threat_names_color: '#d60904'
19+
classifications_color: '#f76928'
20+
vti_color: '#40f5ef'
21+
mitre_color: '#a9f723'
22+
default_tlp: 'TLP:AMBER'
23+
initial_fetch_date: '2025-09-09'

‎external-import/vmray-platform/src/main.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
"""
2+
Main entry point for the VMRay connector script.
3+
Initializes the connector and runs it.
4+
"""
5+
6+
from sys import exit
7+
from traceback import print_exc
8+
9+
from vmray_connector import VMRayConnector
10+
11+
if __name__ == "__main__":
12+
# Entry point of the script
13+
# print_exc(): Prints the exception traceback to stderr
14+
# exit(1): Signals an error to the operating system
15+
try:
16+
connector = VMRayConnector()
17+
connector.run()
18+
except Exception:
19+
print_exc()
20+
exit(1)

‎external-import/vmray-platform/src/requirements.txt‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
pycti==6.9.0
2+
urllib3==2.5.0
3+
vmray-rest-api==6.0.0

‎external-import/vmray-platform/src/vmray_connector/__init__.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
"""
2+
VMRay Connector package.
3+
4+
Exports the main `VMRayConnector` class for use by external modules.
5+
"""
6+
7+
from .connector import VMRayConnector
8+
9+
__all__ = ["VMRayConnector"]

0 commit comments

Comments
 (0)