Skip to content

Commit 18bd9fe

Browse files
authored
Merge pull request #685 from crowdsecurity/improve_cti_taxonomy_doc
Improve CTI Taxonomy documentation
2 parents f05a14f + 24f9a6c commit 18bd9fe

File tree

8 files changed

+109
-35
lines changed

8 files changed

+109
-35
lines changed

crowdsec-docs/sidebarsUnversioned.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,9 +18,10 @@ module.exports = {
1818
"cti_api/taxonomy/cti_object",
1919
"cti_api/taxonomy/scores",
2020
"cti_api/taxonomy/scenarios",
21-
"cti_api/taxonomy/classifications",
2221
"cti_api/taxonomy/behaviors",
22+
"cti_api/taxonomy/classifications",
2323
"cti_api/taxonomy/false_positives",
24+
"cti_api/taxonomy/benign",
2425
],
2526
},
2627
{

crowdsec-docs/src/components/tableRender.js

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import BrowserOnly from '@docusaurus/BrowserOnly';
55
import {useColorMode} from '@docusaurus/theme-common';
66

77

8-
const TableRender = ({ columns, url }) => {
8+
const TableRender = ({ columns, url, include=[], exclude=[] }) => {
99
const [jsonContent, setJsonContent] = useState()
1010
const {colorMode} = useColorMode();
1111

@@ -38,7 +38,16 @@ const TableRender = ({ columns, url }) => {
3838
// filter duplicate names
3939
const item = data[key];
4040
const name = item["name"];
41-
41+
for (let i = 0; i < exclude.length; i++) {
42+
if (name.includes(exclude[i])) {
43+
return
44+
}
45+
}
46+
for (let i = 0; i < include.length; i++) {
47+
if (!name.includes(include[i])) {
48+
return
49+
}
50+
}
4251
if (names.includes(name)) {
4352
return
4453
}
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
id: benign
3+
title: Benign Classifications
4+
sidebar_position: 7
5+
---
6+
7+
import TableRender from "@site/src/components/tableRender"
8+
import GithubIconRender from "@site/src/components/githubIconRender"
9+
10+
export const classificationsURL =
11+
"https://hub-cdn.crowdsec.net/master/taxonomy/classifications.json"
12+
export const columns = [
13+
{
14+
header: "Name",
15+
accessorKey: "name",
16+
},
17+
{
18+
header: "Description",
19+
accessorKey: "description",
20+
},
21+
]
22+
export const include = ["scanner:"]
23+
24+
<GithubIconRender url={classificationsURL}></GithubIconRender>
25+
26+
IPs in this category may raise alerts, but they are not inherently dangerous. These IPs often belong to organizations that perform legitimate activities, such as internet-wide scanning or security research.
27+
28+
IPs belonging to those categories will have the `benign` [reputation](/u/cti_api/taxonomy/cti_object#reputation).
29+
30+
:::note
31+
32+
Blocking these IPs may not be necessary unless their behavior directly impacts your operations.
33+
34+
:::
35+
36+
<TableRender
37+
columns={columns}
38+
url={classificationsURL}
39+
include={include}
40+
></TableRender>

crowdsec-docs/unversioned/cti_api/taxonomy/classifications.mdx

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,11 @@ title: Classifications
44
sidebar_position: 5
55
---
66

7-
import TableRender from '@site/src/components/tableRender';
8-
import GithubIconRender from '@site/src/components/githubIconRender';
7+
import TableRender from "@site/src/components/tableRender"
8+
import GithubIconRender from "@site/src/components/githubIconRender"
99

10-
export const classificationsURL = "https://hub-cdn.crowdsec.net/master/taxonomy/classifications.json";
10+
export const classificationsURL =
11+
"https://hub-cdn.crowdsec.net/master/taxonomy/classifications.json"
1112
export const columns = [
1213
{
1314
header: "Name",
@@ -17,9 +18,15 @@ export const columns = [
1718
header: "Description",
1819
accessorKey: "description",
1920
},
20-
];
21+
]
22+
export const exclude = ["scanner:"]
2123

2224
<GithubIconRender url={classificationsURL}></GithubIconRender>
2325

26+
This classification page provides a taxonomy of IP addresses that exhibit potentially suspicious behaviors. These classifications are designed to help you identify and respond to various threat actors and malicious activities.
2427

25-
<TableRender columns={columns} url={classificationsURL}></TableRender>
28+
<TableRender
29+
columns={columns}
30+
url={classificationsURL}
31+
exclude={exclude}
32+
></TableRender>

crowdsec-docs/unversioned/cti_api/taxonomy/cti_fields.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: cti_object
3-
title: CTI Format
3+
title: Format
44
sidebar_position: 2
55
---
66

@@ -199,6 +199,7 @@ The possible values are:
199199
- `suspicious` : Many CrowdSec users have reported the IP, but it is not aggressive enough to be considered malicious
200200
- `known` : At this time, the CrowdSec network has identified the IP, but we still require additional information to make a decision
201201
- `safe` : The IP address is safe and can be trusted (ex: Google DNS, Cloudflare DNS ...)
202+
- `benign` : The IP address belong to a known entity and is not dangerous (eg. Public Internet Scanners)
202203
- `unknown`: The IP address is either unknown or its last report is from more than three months ago
203204

204205
## `ip_range_24`
@@ -400,6 +401,7 @@ Longitude of the IP, when available.
400401
"days_age" : 40,
401402
}
402403
```
404+
403405
Historical information we have collected about the IP.
404406

405407
### `first_seen`

crowdsec-docs/unversioned/cti_api/taxonomy/false_positives.mdx

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
id: false_positives
3-
title: False Positives
3+
title: Safe Classifications
44
sidebar_position: 7
55
---
66

@@ -22,11 +22,15 @@ export const columns = [
2222

2323
<GithubIconRender url={fpURL}></GithubIconRender>
2424

25+
IPs in this category are considered completely safe and trusted. Alerts triggered by these IPs are likely due to misconfiguration or overly sensitive alerting rules.
26+
27+
IPs belonging to those categories will have the `safe` [reputation](/u/cti_api/taxonomy/cti_object#reputation).
28+
2529
<TableRender columns={columns} url={fpURL}></TableRender>
2630

27-
## How to Get Tagged as a False Positive
31+
## How to Get Tagged as Safe
2832

29-
To be able to be classified as a false positive, you need a proper technical justification of why your IP might be misclassified as a threat. This part is to be reviewed and validated by crowdsec.
33+
To be able to be classified as a safe IP, you need a proper technical justification of why your IP might be misclassified as a threat. This part is to be reviewed and validated by crowdsec.
3034

3135
You also need public documentation stating the IP, ranges, and/or reverse DNS associated with the assets in question. This data must be machine-readable (no HTML, no PDF, etc.).
3236

crowdsec-docs/unversioned/cti_api/taxonomy/intro.md

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,18 +4,19 @@ title: Introduction
44
sidebar_position: 1
55
---
66

7+
## CrowdSec CTI Taxonomy
78

8-
CrowdSec CTI Taxonomy aim to help users to understand and to anticipate what is and can be returned by the CrowdSec CTI API.
9+
The CrowdSec CTI Taxonomy is designed to help users fully understand and effectively utilize the data returned by the CrowdSec CTI API.
910

10-
In this section, you will see the documentations about:
11+
By organizing threat intelligence into structured and actionable categories, it enables better anticipation of potential threats.
1112

12-
- the fields: Those are the fields returned by the CrowdSec API when requesting an IP address (or the fire database)
13+
### Key Aspects
1314

14-
- the scores: CrowdSec compute some scores for a given IP address. Those scores are computed for the last day, the last week, the last month and overall.
15-
16-
- the behaviors: The behaviors associated to an IP address
17-
18-
- the scenarios: The scenarios for which an IP address has been reported for
19-
20-
- the false positives: The possible false positives values associateed to an IP address
15+
This section covers the following key aspects:
2116

17+
- [**CTI Format**](/u/cti_api/taxonomy/cti_object): The complete structure and fields returned by the CrowdSec API, providing a detailed view of the data for each queried IP address.
18+
- [**CTI Scores**](/u/cti_api/taxonomy/scores): Detailed assessments computed for an IP address over different periods (daily, weekly, monthly, and overall).
19+
- [**Behaviors**](/u/cti_api/taxonomy/behaviors): List of defined behaviors linked to an IP address, providing context for its activity.
20+
- [**Classifications**](/u/cti_api/taxonomy/classifications): Category of an IP address, helping to identify whether an IP is part of a known group, network or other defined role, providing important context to understand its potential behavior.
21+
- [**False Positives**](/u/cti_api/taxonomy/false_positives): Categories of potential false positives, ensuring accurate analysis and interpretation of API results.
22+
- [**Scenarios**](/u/cti_api/taxonomy/scenarios): A detailed view of the scenarios that triggered reports for an IP address, helping to identify patterns or threats.
Lines changed: 23 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,33 @@
11
---
22
id: scores
3-
title: CTI Scores
3+
title: Scores
44
sidebar_position: 3
55
---
66

7+
## Understanding CrowdSec CTI Scores
78

9+
While CrowdSec provides general scores for common use cases, this section offers a deeper breakdown of IP-related data.
810

9-
While CrowdSec already provides ready-made scores for common usecases such as background noise score, the scores in this section offer a more in-depth breakdown of the information we have collected about an IP. They can be used both to help categorize alerts and to build internal products for your organizations needs. These scores are indicators of malevolence associated with an IP address, computed over several periods of time : 1 day, 1 week, 1 month and overall.
10-
11-
For a given period, each indicator is provided with a value ranging from **0** (lowest value) to **5** (highest value). The following table describes the indicators in more detail.
11+
These scores help categorize alerts and can be used to build internal products tailored to your organization's needs.
1212

13-
| indicator | explaination |
14-
|-----------|--------------|
15-
|Aggressiveness | _What is the intensity of the attack?_ <br /> This component measures the number of attacks reported over a period of time. |
16-
|Threat | _How dangerous are the attacks?_ <br /> This component measures how dangerous an IP is based on the type of attacks we usually see it attempt. An IP known for crawling and scanning will have a lower threat level than an IP reported for brute-force and exploits. This score ranges from 1 (mainly crawling) to 5 (exploit). 0 is the default for unknown scenarios |
17-
|Trust| _What is the level of confidence in the actors which reported the IP address?_ <br /> This component measures the degree of trust we have in the reports that we received about this IP. It is based on the reputation (age, number of reports) and the diversity (number of IP ranges, AS Numbers) of all security engines reporting the IP. |
18-
| Anomaly | _Are there any red flags associated with the device behind this IP address?_ <br /> This score is based on static properties of the machine behind the IP. For instance a machine exposing old and vulnerable software will have a high anomaly score. |
19-
| Total | Aggregation of the 4 components above. |
13+
They serve as indicators of malevolent activity associated with an IP address, computed over several periods: 1 day, 1 week, 1 month, and overall.
2014

21-
For a more in-depth explanation on how we compute these scores, refer to our [blog article](https://www.crowdsec.net/blog/crowdsec-cti-scoring-system).
15+
Each score is measured on a scale from **0** (lowest) to **5** (highest). Below is an overview of the main score components:
2216

23-
The `ip_range_score` is the score of malevolence associated with an IP range, ranging from *0* (No IP reported) to *5* (massively reported). It is calculated based on the number of IPs belonging to this range that were reported by the community as malicious
17+
| Indicator | Explanation |
18+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
19+
| **Aggressiveness** | _How intense is the attack?_ <br /> Measures the frequency of attacks within a given time period. A higher score indicates a greater number of attack attempts, signaling aggressive behavior or persistent targeting over time. |
20+
| **Threat** | _How dangerous are the attacks?_ <br /> Reflects the severity of the attacks, ranging from low-risk activities like scanning to high-risk behaviors like exploiting vulnerabilities. A higher score means the IP is associated with more dangerous tactics. |
21+
| **Trust** | _How reliable is the information about the IP?_ <br /> Based on the credibility of the reporting sources. This score considers factors like the age of the reports, how many different security engines flagged the IP, and the diversity of the reports. A higher score indicates more trust in the accuracy and reliability of the data. |
22+
| **Anomaly** | _Are there any suspicious behaviors associated with the device behind this IP?_ <br /> Evaluates red flags like outdated software, unusual configurations, or other traits that could indicate a compromised or malicious device. A higher score suggests more alarming anomalies linked to the IP. |
23+
| **Total** | Combines the scores of the above four components to give an overall malevolence score. The higher the total, the more likely the IP is associated with malicious activity indicators. |
24+
25+
For a more detailed explanation on how we calculate these scores, read our [blog article](https://www.crowdsec.net/blog/crowdsec-cti-scoring-system).
26+
27+
### IP Range Score
28+
29+
The `ip_range_score` reflects the malevolence of an entire IP range, ranging from _0_ (no reports) to _5_ (highly reported).
30+
31+
It is based on the number of IPs in the range that have been flagged as malicious by the CrowdSec community.
32+
33+
The more IPs from the same range are reported, the higher the score, indicating a greater likelihood that the range is associated with malicious activity.

0 commit comments

Comments
 (0)