Skip to content

Commit 98f0497

Browse files
SamuelHassineSamuelHassine
authored
[all] Improve docs (#5552)
1 parent a4ad978 commit 98f0497

File tree

53 files changed

+10256
-1981
lines changed

Some content is hidden

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

53 files changed

+10256
-1981
lines changed

‎internal-enrichment/abuseipdb/README.md‎

Lines changed: 212 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,226 @@
1-
# OpenCTI Internal Enrichment Connector AbuseIPDB
1+
# OpenCTI AbuseIPDB Connector
22

3-
## Status Filigran
3+
The AbuseIPDB connector enriches IP address observables in OpenCTI with abuse reports, confidence scores, and category labels from AbuseIPDB's community-driven database.
44

55
| Status | Date | Comment |
66
|-------------------|------|---------|
77
| Filigran Verified | - | - |
88

9-
## Introduction
9+
## Table of Contents
10+
11+
- [OpenCTI AbuseIPDB Connector](#opencti-abuseipdb-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)
1027

11-
**Introducing AbuseIPDB**
28+
## Introduction
1229

1330
AbuseIPDB is a robust platform that collects and shares data on malicious IP addresses reported by users around the world. It serves as a valuable tool for cybersecurity teams looking to identify and block IP addresses associated with abusive activities, such as spam, hacking attempts, and other malicious acts. By providing a community-driven database, AbuseIPDB helps organizations strengthen their defenses against network-based threats.
1431

15-
The integration of AbuseIPDB with OpenCTI allows for the seamless importation of malicious IP address data into the threat intelligence platform. This integration enriches threat intelligence by providing real-time context on potentially harmful IPs, enabling security teams to implement more effective blocking and monitoring strategies. By utilizing this data, organizations can enhance their ability to preemptively identify and mitigate threats from malicious IP sources.
32+
The integration of AbuseIPDB with OpenCTI allows for the seamless enrichment of IP address observables with real-time context on potentially harmful IPs. This enrichment provides abuse confidence scores, category labels, and geographic sighting information, enabling security teams to implement more effective blocking and monitoring strategies.
33+
34+
## Installation
35+
36+
### Requirements
37+
38+
- OpenCTI Platform >= 6.5.1
39+
- AbuseIPDB API key (registration at [abuseipdb.com](https://www.abuseipdb.com))
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` | IPv4-Addr,IPv6-Addr | Yes | The scope of observables the connector will enrich. |
59+
| Connector Type | type | `CONNECTOR_TYPE` | INTERNAL_ENRICHMENT | Yes | Should always be `INTERNAL_ENRICHMENT` for this connector. |
60+
| Log Level | log_level | `CONNECTOR_LOG_LEVEL` | error | No | Determines the verbosity of the logs: `debug`, `info`, `warn`, or `error`. |
61+
| Auto Mode | auto | `CONNECTOR_AUTO` | true | No | Enables or disables automatic enrichment of observables. |
62+
63+
### Connector extra parameters environment variables
64+
65+
| Parameter | config.yml | Docker environment variable | Default | Mandatory | Description |
66+
|-----------|------------------|-----------------------------|-----------| ----------|-------------------------------------------------------------------------------------------------------|
67+
| API Key | abuseipdb.api_key | `ABUSEIPDB_API_KEY` | | Yes | API key used to authenticate requests to the AbuseIPDB service. |
68+
| Max TLP | abuseipdb.max_tlp | `ABUSEIPDB_MAX_TLP` | TLP:AMBER | No | Maximum TLP level for observables to be enriched. Observables with higher TLP will not be processed. |
69+
70+
## Deployment
71+
72+
### Docker Deployment
73+
74+
Build the Docker image:
75+
76+
```bash
77+
docker build -t opencti/connector-abuseipdb:latest .
78+
```
79+
80+
Configure the connector in `docker-compose.yml`:
81+
82+
```yaml
83+
connector-abuseipdb:
84+
image: opencti/connector-abuseipdb:latest
85+
environment:
86+
- OPENCTI_URL=http://localhost
87+
- OPENCTI_TOKEN=ChangeMe
88+
- CONNECTOR_ID=ChangeMe_UUID4
89+
- CONNECTOR_NAME=AbuseIPDB
90+
- CONNECTOR_SCOPE=IPv4-Addr,IPv6-Addr
91+
- CONNECTOR_TYPE=INTERNAL_ENRICHMENT
92+
- CONNECTOR_LOG_LEVEL=error
93+
- CONNECTOR_AUTO=true
94+
- ABUSEIPDB_API_KEY=ChangeMe
95+
- ABUSEIPDB_MAX_TLP=TLP:AMBER
96+
restart: always
97+
```
98+
99+
Start the connector:
100+
101+
```bash
102+
docker compose up -d
103+
```
104+
105+
### Manual Deployment
106+
107+
1. Copy and configure `config.yml` from the provided `config.yml.sample`.
108+
109+
2. Install dependencies:
110+
111+
```bash
112+
pip3 install -r requirements.txt
113+
```
114+
115+
3. Start the connector from the `src` directory:
116+
117+
```bash
118+
python3 -m connector
119+
```
120+
121+
## Usage
122+
123+
The connector enriches IP address observables either automatically (when `CONNECTOR_AUTO=true`) or manually via:
124+
125+
**Observations → Observables**
126+
127+
Select an IPv4 or IPv6 address observable, then click the enrichment button and choose AbuseIPDB.
128+
129+
## Behavior
130+
131+
The connector queries the AbuseIPDB API to retrieve abuse reports for IP addresses and enriches the observable with the results.
132+
133+
### Data Flow
134+
135+
```mermaid
136+
graph LR
137+
subgraph OpenCTI Input
138+
IPObs[IPv4-Addr / IPv6-Addr Observable]
139+
end
140+
141+
subgraph AbuseIPDB API
142+
API[Check Endpoint]
143+
end
144+
145+
subgraph OpenCTI Output
146+
EnrichedIP[Enriched IP Observable]
147+
Labels[Category Labels]
148+
Country[Country Locations]
149+
Sightings[Sightings]
150+
end
151+
152+
IPObs --> API
153+
API --> EnrichedIP
154+
EnrichedIP --> Labels
155+
EnrichedIP --> Country
156+
Country --> Sightings
157+
```
158+
159+
### Enrichment Mapping
160+
161+
| AbuseIPDB Data | OpenCTI Entity/Property | Description |
162+
|--------------------------|-----------------------------|-------------------------------------------------------------------|
163+
| abuseConfidenceScore | Observable Score | Confidence score (0-100) indicating likelihood of malicious use |
164+
| isWhitelisted | Label "whitelist" | Applied when IP is in AbuseIPDB whitelist |
165+
| reports[].categories | Labels | Abuse category labels (e.g., "Brute Force", "Port Scan") |
166+
| reports[].reporterCountryCode | Country Location | Country where the abuse was reported from |
167+
| Report aggregation | Sighting | Sighting relationship linking IP to reporting countries |
168+
169+
### Abuse Categories
170+
171+
The connector maps AbuseIPDB category codes to human-readable labels:
172+
173+
| Code | Category | Code | Category |
174+
|------|-------------------|------|-------------------|
175+
| 3 | Fraud Orders | 14 | Port Scan |
176+
| 4 | DDOS Attack | 15 | Hacking |
177+
| 5 | FTP Brute-Force | 16 | SQL Injection |
178+
| 6 | Ping of Death | 17 | Spoofing |
179+
| 7 | Phishing | 18 | Brute Force |
180+
| 8 | Fraud VOIP | 19 | Bad Web Bot |
181+
| 9 | Open Proxy | 20 | Exploited Host |
182+
| 10 | Web Spam | 21 | Web App Attack |
183+
| 11 | Email Spam | 22 | SSH |
184+
| 12 | Blog Spam | 23 | IoT Targeted |
185+
| 13 | VPN IP | | |
186+
187+
### Processing Details
188+
189+
1. **TLP Check**: Validates observable TLP against `max_tlp` setting; skips if TLP exceeds maximum
190+
2. **API Query**: Queries AbuseIPDB for reports in the last 365 days
191+
3. **Whitelist Check**: If IP is whitelisted, adds "whitelist" label and external reference
192+
4. **Report Processing**: If reports exist:
193+
- Sets abuse confidence score
194+
- Adds category labels for each unique abuse type
195+
- Aggregates reports by country
196+
- Creates Country Location entities
197+
- Creates Sighting relationships to countries with first/last seen dates and count
198+
199+
### Generated STIX Objects
200+
201+
| STIX Object Type | Description |
202+
|------------------|----------------------------------------------------|
203+
| IPv4-Addr/IPv6-Addr (updated) | Original observable enriched with score and labels |
204+
| Location (Country) | Countries from which abuse reports originated |
205+
| Sighting | Links IP observable to country with report metadata |
206+
207+
## Debugging
208+
209+
Enable verbose logging by setting:
16210

17-
## Requirements
211+
```env
212+
CONNECTOR_LOG_LEVEL=debug
213+
```
18214

19-
- python-dateutil==2.9.0.post0
20-
- pydantic-settings==2.10.1
21-
- pycti==6.7.15
215+
Log output includes:
216+
- API request/response details
217+
- Report processing progress
218+
- STIX bundle creation and sending status
22219

23-
## Configuration variables environment
220+
## Additional information
24221

25-
Find all the configuration variables available (default/required) here: [Connector Configurations](./__metadata__)
222+
- **API Rate Limits**: AbuseIPDB has rate limits based on subscription tier; free accounts have limited daily queries
223+
- **Report Age**: The connector retrieves reports from the last 365 days
224+
- **External Reference**: A link to the AbuseIPDB check page is added for whitelisted IPs
225+
- **Automatic Enrichment**: When `CONNECTOR_AUTO=true`, all new IP observables matching the connector scope are automatically enriched
226+
- **Playbook Support**: This connector supports OpenCTI playbook automation

0 commit comments

Comments
 (0)