Improve CTI Taxonomy documentation

crowdsec-docs/sidebarsUnversioned.js

@@ -18,9 +18,10 @@ module.exports = {
                 "cti_api/taxonomy/cti_object",
                 "cti_api/taxonomy/scores",
                 "cti_api/taxonomy/scenarios",
-                "cti_api/taxonomy/classifications",
                 "cti_api/taxonomy/behaviors",
+                "cti_api/taxonomy/classifications",
                 "cti_api/taxonomy/false_positives",
+                "cti_api/taxonomy/benign",
             ],
         },
         {

crowdsec-docs/src/components/tableRender.js

@@ -5,7 +5,7 @@ import BrowserOnly from '@docusaurus/BrowserOnly';
 import {useColorMode} from '@docusaurus/theme-common';
 
 
-const TableRender = ({ columns, url }) => {
+const TableRender = ({ columns, url, include=[], exclude=[] }) => {
     const [jsonContent, setJsonContent] = useState()
     const {colorMode} = useColorMode();
 
@@ -38,7 +38,16 @@ const TableRender = ({ columns, url }) => {
                     // filter duplicate names
                     const item = data[key];
                     const name = item["name"];
-
+                    for (let i = 0; i < exclude.length; i++) {
+                        if (name.includes(exclude[i])) {
+                            return
+                        }
+                    }
+                    for (let i = 0; i < include.length; i++) {
+                        if (!name.includes(include[i])) {
+                            return
+                        }
+                    }
                     if (names.includes(name)) {
                         return
                     }

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

@@ -0,0 +1,40 @@
+---
+id: benign
+title: Benign Classifications
+sidebar_position: 7
+---
+
+import TableRender from "@site/src/components/tableRender"
+import GithubIconRender from "@site/src/components/githubIconRender"
+
+export const classificationsURL =
+    "https://hub-cdn.crowdsec.net/master/taxonomy/classifications.json"
+export const columns = [
+    {
+        header: "Name",
+        accessorKey: "name",
+    },
+    {
+        header: "Description",
+        accessorKey: "description",
+    },
+]
+export const include = ["scanner:"]
+
+<GithubIconRender url={classificationsURL}></GithubIconRender>
+
+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.
+
+IPs belonging to those categories will have the `benign` [reputation](/u/cti_api/taxonomy/cti_object#reputation).
+
+:::note
+
+Blocking these IPs may not be necessary unless their behavior directly impacts your operations.
+
+:::
+
+<TableRender
+    columns={columns}
+    url={classificationsURL}
+    include={include}
+></TableRender>

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

@@ -4,10 +4,11 @@ title: Classifications
 sidebar_position: 5
 ---
 
-import TableRender from '@site/src/components/tableRender';
-import GithubIconRender from '@site/src/components/githubIconRender';
+import TableRender from "@site/src/components/tableRender"
+import GithubIconRender from "@site/src/components/githubIconRender"
 
-export const classificationsURL = "https://hub-cdn.crowdsec.net/master/taxonomy/classifications.json";
+export const classificationsURL =
+    "https://hub-cdn.crowdsec.net/master/taxonomy/classifications.json"
 export const columns = [
     {
         header: "Name",
@@ -17,9 +18,15 @@ export const columns = [
         header: "Description",
         accessorKey: "description",
     },
-];
+]
+export const exclude = ["scanner:"]
 
 <GithubIconRender url={classificationsURL}></GithubIconRender>
 
+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.
 
-<TableRender columns={columns} url={classificationsURL}></TableRender>
+<TableRender
+    columns={columns}
+    url={classificationsURL}
+    exclude={exclude}
+></TableRender>

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

@@ -1,6 +1,6 @@
 ---
 id: cti_object
-title: CTI Format
+title: Format
 sidebar_position: 2
 ---
 
@@ -199,6 +199,7 @@ The possible values are:
 -   `suspicious` : Many CrowdSec users have reported the IP, but it is not aggressive enough to be considered malicious
 -   `known` : At this time, the CrowdSec network has identified the IP, but we still require additional information to make a decision
 -   `safe` : The IP address is safe and can be trusted (ex: Google DNS, Cloudflare DNS ...)
+-   `benign` : The IP address belong to a known entity and is not dangerous (eg. Public Internet Scanners)
 -   `unknown`: The IP address is either unknown or its last report is from more than three months ago
 
 ## `ip_range_24`
@@ -400,6 +401,7 @@ Longitude of the IP, when available.
   "days_age" : 40,
 }
 ```
+
 Historical information we have collected about the IP.
 
 ### `first_seen`

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

@@ -1,6 +1,6 @@
 ---
 id: false_positives
-title: False Positives
+title: Safe Classifications
 sidebar_position: 7
 ---
 
@@ -22,11 +22,15 @@ export const columns = [
 
 <GithubIconRender url={fpURL}></GithubIconRender>
 
+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.
+
+IPs belonging to those categories will have the `safe` [reputation](/u/cti_api/taxonomy/cti_object#reputation).
+
 <TableRender columns={columns} url={fpURL}></TableRender>
 
-## How to Get Tagged as a False Positive
+## How to Get Tagged as Safe
 
-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.
+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.
 
 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.).
 

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

@@ -4,18 +4,19 @@ title: Introduction
 sidebar_position: 1
 ---
 
+## CrowdSec CTI Taxonomy
 
-CrowdSec CTI Taxonomy aim to help users to understand and to anticipate what is and can be returned by the CrowdSec CTI API.
+The CrowdSec CTI Taxonomy is designed to help users fully understand and effectively utilize the data returned by the CrowdSec CTI API.
 
-In this section, you will see the documentations about:
+By organizing threat intelligence into structured and actionable categories, it enables better anticipation of potential threats.
 
- - the fields: Those are the fields returned by the CrowdSec API when requesting an IP address (or the fire database)
+### Key Aspects
 
- - 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.
-
- - the behaviors: The behaviors associated to an IP address
-
- - the scenarios: The scenarios for which an IP address has been reported for
-
- - the false positives: The possible false positives values associateed to an IP address
+This section covers the following key aspects:
 
+-   [**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.
+-   [**CTI Scores**](/u/cti_api/taxonomy/scores): Detailed assessments computed for an IP address over different periods (daily, weekly, monthly, and overall).
+-   [**Behaviors**](/u/cti_api/taxonomy/behaviors): List of defined behaviors linked to an IP address, providing context for its activity.
+-   [**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.
+-   [**False Positives**](/u/cti_api/taxonomy/false_positives): Categories of potential false positives, ensuring accurate analysis and interpretation of API results.
+-   [**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.

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

@@ -1,23 +1,33 @@
 ---
 id: scores
-title: CTI Scores
+title: Scores
 sidebar_position: 3
 ---
 
+## Understanding CrowdSec CTI Scores
 
+While CrowdSec provides general scores for common use cases, this section offers a deeper breakdown of IP-related data.
 
-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. 
-
-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.
+These scores help categorize alerts and can be used to build internal products tailored to your organization's needs.
 
-| indicator | explaination |
-|-----------|--------------|
-|Aggressiveness | _What is the intensity of the attack?_ <br /> This component measures the number of attacks reported over a period of time. |
-|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 |
-|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. |
-| 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. |
-| Total | Aggregation of the 4 components above. |
+They serve as indicators of malevolent activity associated with an IP address, computed over several periods: 1 day, 1 week, 1 month, and overall.
 
-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).
+Each score is measured on a scale from **0** (lowest) to **5** (highest). Below is an overview of the main score components:
 
-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
+| Indicator          | Explanation                                                                                                                                                                                                                                                                                                                                |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **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.                                                                                                           |
+| **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.                                                                                |
+| **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. |
+| **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.                                        |
+| **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.                                                                                                                                                      |
+
+For a more detailed explanation on how we calculate these scores, read our [blog article](https://www.crowdsec.net/blog/crowdsec-cti-scoring-system).
+
+### IP Range Score
+
+The `ip_range_score` reflects the malevolence of an entire IP range, ranging from _0_ (no reports) to _5_ (highly reported).
+
+It is based on the number of IPs in the range that have been flagged as malicious by the CrowdSec community.
+
+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.