Skip to content

Commit bde208d

Browse files
SamuelHassineCTIBurn0ut
SamuelHassine
authored and
CTIBurn0ut
committed
[all] Enhance docs (#5550)
1 parent 04bd4d5 commit bde208d

File tree

117 files changed

+13097
-3007
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

117 files changed

+13097
-3007
lines changed

‎external-import/abuse-ssl/README.md‎

Lines changed: 180 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,193 @@
1-
# OpenCTI Abuse-SSL Connector
1+
# OpenCTI Abuse.ch SSL Blacklist Connector
22

3-
The connector uses the Abuse.ch SSL csv file that lists botnet IPs detected based on certain SSL signatures.
3+
The Abuse.ch SSL connector imports botnet C&C server IP addresses detected based on SSL certificate signatures from the SSLBL blacklist into OpenCTI.
44

5-
An SSL certificate can be associated with one or more servers (IP address:port combination). SSLBL collects IP addresses that are running with an SSL certificate blacklisted on SSLBL. These are usually botnet Command&Control servers (C&C). SSLBL hence publishes a blacklist containing these IPs which can be used to detect botnet C2 traffic from infected machines towards the internet, leaving your network. The CSV format is useful if you want to process the blacklisted IP addresses further, e.g. loading them into your SIEM or CTI (or both, don't be shy).
5+
| Status | Date | Comment |
6+
|-------------------|------|---------|
7+
| Filigran Verified | - | - |
8+
9+
## Table of Contents
10+
11+
- [OpenCTI Abuse.ch SSL Blacklist Connector](#opencti-abusech-ssl-blacklist-connector)
12+
- [Table of Contents](#table-of-contents)
13+
- [Introduction](#introduction)
14+
- [Installation](#installation)
15+
- [Requirements](#requirements)
16+
- [Configuration variables](#configuration-variables)
17+
- [OpenCTI environment variables](#opencti-environment-variables)
18+
- [Base connector environment variables](#base-connector-environment-variables)
19+
- [Connector extra parameters environment variables](#connector-extra-parameters-environment-variables)
20+
- [Deployment](#deployment)
21+
- [Docker Deployment](#docker-deployment)
22+
- [Manual Deployment](#manual-deployment)
23+
- [Usage](#usage)
24+
- [Behavior](#behavior)
25+
- [Debugging](#debugging)
26+
- [Additional information](#additional-information)
27+
28+
## Introduction
29+
30+
The Abuse.ch SSLBL (SSL Blacklist) identifies and lists IP addresses associated with botnet Command & Control (C&C) servers based on SSL certificate fingerprints. An SSL certificate can be associated with one or more servers (IP address:port combination). SSLBL collects IP addresses running with blacklisted SSL certificates.
31+
32+
This connector fetches the CSV-formatted blacklist from Abuse.ch SSLBL and converts the IP addresses into STIX 2.1 objects for import into OpenCTI.
633

734
## Installation
835

936
### Requirements
1037

11-
- OpenCTI Platform >= 6.9.5
38+
- OpenCTI Platform >= 6.x
39+
- Access to Abuse.ch SSLBL CSV feed (publicly available)
40+
41+
## Configuration variables
42+
43+
There are a number of configuration options, which are set either in `docker-compose.yml` (for Docker) or in `config.yml` (for manual deployment).
44+
45+
### OpenCTI environment variables
46+
47+
| Parameter | config.yml | Docker environment variable | Mandatory | Description |
48+
|---------------|------------|-----------------------------|-----------|------------------------------------------------------|
49+
| OpenCTI URL | url | `OPENCTI_URL` | Yes | The URL of the OpenCTI platform. |
50+
| OpenCTI Token | token | `OPENCTI_TOKEN` | Yes | The default admin token set in the OpenCTI platform. |
51+
52+
### Base connector environment variables
53+
54+
| Parameter | config.yml | Docker environment variable | Default | Mandatory | Description |
55+
|------------------|------------|-----------------------------|----------|-----------|--------------------------------------------------------------------------|
56+
| Connector ID | id | `CONNECTOR_ID` | | Yes | A unique `UUIDv4` identifier for this connector instance. |
57+
| Connector Name | name | `CONNECTOR_NAME` | | Yes | Name of the connector. |
58+
| Connector Scope | scope | `CONNECTOR_SCOPE` | abusessl | Yes | The scope or type of data the connector is importing. |
59+
| Log Level | log_level | `CONNECTOR_LOG_LEVEL` | error | No | Determines the verbosity of logs: `debug`, `info`, `warn`, or `error`. |
60+
61+
### Connector extra parameters environment variables
62+
63+
| Parameter | config.yml | Docker environment variable | Default | Mandatory | Description |
64+
|---------------|---------------|-----------------------------|---------------------------------------------------------|-----------|----------------------------------------------------------------|
65+
| SSLBL URL | abusessl.url | `ABUSESSL_URL` | https://sslbl.abuse.ch/blacklist/sslipblacklist.csv | Yes | The Abuse.ch SSLBL CSV feed URL. |
66+
| Interval | abusessl.interval | `ABUSESSL_INTERVAL` | 360 | Yes | Interval in minutes between collections. |
67+
68+
## Deployment
69+
70+
### Docker Deployment
71+
72+
Build the Docker image:
73+
74+
```bash
75+
docker build -t opencti/connector-abuse-ssl:latest .
76+
```
77+
78+
Configure the connector in `docker-compose.yml`:
79+
80+
```yaml
81+
connector-abuse-ssl:
82+
image: opencti/connector-abuse-ssl:latest
83+
environment:
84+
- OPENCTI_URL=http://localhost
85+
- OPENCTI_TOKEN=ChangeMe
86+
- CONNECTOR_ID=ChangeMe_UUID4
87+
- CONNECTOR_NAME=Abuse.ch SSL Blacklist
88+
- CONNECTOR_SCOPE=abusessl
89+
- CONNECTOR_LOG_LEVEL=error
90+
- ABUSESSL_URL=https://sslbl.abuse.ch/blacklist/sslipblacklist.csv
91+
- ABUSESSL_INTERVAL=360
92+
restart: always
93+
```
94+
95+
Start the connector:
96+
97+
```bash
98+
docker compose up -d
99+
```
100+
101+
### Manual Deployment
102+
103+
1. Copy and configure `config.yml` from the provided `config.yml.sample`.
104+
105+
2. Install dependencies:
106+
107+
```bash
108+
pip3 install -r requirements.txt
109+
```
110+
111+
3. Start the connector:
112+
113+
```bash
114+
python3 abuse_ssl.py
115+
```
116+
117+
## Usage
118+
119+
The connector runs automatically at the interval set by `ABUSESSL_INTERVAL`. You can also manually trigger it from:
120+
121+
**Data Management → Ingestion → Connectors**
122+
123+
Find the connector and click on the refresh button to reset the connector's state and force a new download of data.
124+
125+
## Behavior
126+
127+
The connector fetches the SSLBL CSV feed containing IP addresses of botnet C&C servers and converts them to STIX 2.1 objects.
128+
129+
### Data Flow
130+
131+
```mermaid
132+
graph LR
133+
subgraph Abuse.ch SSLBL
134+
direction TB
135+
CSV[CSV Feed]
136+
end
137+
138+
subgraph OpenCTI
139+
direction LR
140+
Identity[Identity - Connector Name]
141+
Observable[IPv4-Addr Observable]
142+
Indicator[Indicator]
143+
Relationship[Relationship]
144+
end
145+
146+
CSV --> Identity
147+
CSV --> Observable
148+
Observable --> Indicator
149+
Indicator -- based-on --> Observable
150+
```
151+
152+
### Entity Mapping
153+
154+
| Abuse.ch SSLBL Data | OpenCTI Entity | Description |
155+
|----------------------|---------------------|--------------------------------------------------|
156+
| IP Address | IPv4-Addr | Observable with labels `osint`, `ssl-blacklist` |
157+
| IP Address | Indicator | STIX pattern `[ipv4-addr:value = '<ip>']` |
158+
| - | Relationship | `based-on` from Indicator to Observable |
159+
160+
### Processing Details
161+
162+
For each IP address in the SSLBL feed, the connector creates:
163+
164+
1. **Identity**: Organization identity based on connector name
165+
2. **IPv4-Addr Observable**: With custom properties:
166+
- `x_opencti_description`: "Malicious SSL connections"
167+
- `x_opencti_labels`: `["osint", "ssl-blacklist"]`
168+
3. **Indicator**: STIX 2.1 indicator with:
169+
- Pattern: `[ipv4-addr:value = '<ip>']`
170+
- `x_opencti_main_observable_type`: "IPv4-Addr"
171+
4. **Relationship**: `based-on` linking Indicator to Observable
172+
173+
All objects are marked with **TLP:WHITE**.
12174

13-
### Configuration
175+
## Debugging
14176

15-
| Parameter | Docker envvar | Mandatory | Description |
16-
| ---------------------------- | ---------------------------- | --------- | --------------------------------------------------------------------------------------------- |
17-
| `opencti_url` | `OPENCTI_URL` | Yes | The URL of the OpenCTI platform. |
18-
| `opencti_token` | `OPENCTI_TOKEN` | Yes | The default admin token configured in the OpenCTI platform parameters file. |
19-
| `connector_id` | `CONNECTOR_ID` | Yes | A valid arbitrary `UUIDv4` that must be unique for this connector. |
20-
| `connector_name` | `CONNECTOR_NAME` | Yes | |
21-
| `connector_scope` | `CONNECTOR_SCOPE` | Yes | |
22-
| `connector_log_level` | `CONNECTOR_LOG_LEVEL` | Yes | The log level for this connector, could be `debug`, `info`, `warn` or `error` (less verbose). |
23-
| `abusessl_url` | `ABUSESSL_URL` | Yes | the abuse-ssl csv URL |
24-
| `abusessl_interval` | `ABUSESSL_INTERVAL` | Yes | Interval in minutes between 2 collections (don't go below 5 minutes). |
177+
Enable verbose logging by setting:
25178

26-
### Debugging
179+
```env
180+
CONNECTOR_LOG_LEVEL=debug
181+
```
27182

28-
<!-- Any additional information to help future users debug and report detailed issues concerning this connector -->
183+
Log output includes:
184+
- IPv4 address enumeration progress
185+
- STIX observable, indicator, and relationship creation
186+
- Bundle sending status
29187

30-
### Additional information
188+
## Additional information
31189

32-
<!--
33-
Any additional information about this connector
34-
* What information is ingested/updated/changed
35-
* What should the user take into account when using this connector
36-
* ...
37-
-->
190+
- All imported data is marked as **TLP:WHITE**
191+
- The SSLBL feed is updated frequently; default interval is 360 minutes (6 hours)
192+
- Each run fetches the complete current blacklist
193+
- Duplicate detection is handled by OpenCTI based on STIX IDs

0 commit comments

Comments
 (0)