Merge pull request #657 from crowdsecurity/ese-improve-cti-docs

Improve cti docs

Author: seemanne

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

@@ -400,8 +400,7 @@ Longitude of the IP, when available.
   "days_age" : 40,
 }
 ```
-
-The geo location information about the IP address.
+Historical information we have collected about the IP.
 
 ### `first_seen`
 
@@ -411,7 +410,7 @@ The geo location information about the IP address.
 "first_seen" : "2022-01-01T00:00:00+00:00"
 ```
 
-Date of the first time this IP was reported. Please note that due to "progressive data degradation" this date might be later than the first time the IP was actually seen.
+Date of the first time this IP was reported. Please note that due to our progressive data degradation mechanism this date might be later than the first time the IP was actually seen.
 
 ### `last_seen`
 
@@ -450,7 +449,7 @@ Delta in days between first and last seen timestamps.
 ```json
 "behaviors" : [
   {
-    "name" : "protocol:protocol:behavior",
+    "name" : "protocol:behavior",
     "label" : "Protocol Behavior",
     "description" : "Protocol Behavior description"
   }
@@ -527,7 +526,7 @@ The possible false positives and classifications attributed to this IP address.
 ]
 ```
 
-A list of false positives tags associated with the IP. Any IP with `false_positives` tags shouldn't be considered as malicious.
+A list of false positive tags associated with the IP. Any IP with `false_positives` tags shouldn't be considered as malicious.
 
 #### `name`
 
@@ -566,14 +565,14 @@ Human-friendly description of the false positive.
 ```json
 "classifications" : [
   {
-    "name" : "classifications",
+    "name" : "classification",
     "label" : "Classification",
     "description" : "Classification description"
   }
 ]
 ```
 
-A list of `classifications` tags associated with the IP.
+A list of `classification` tags associated with the IP.
 
 #### `name`
 
@@ -666,7 +665,7 @@ Human-friendly description of the scenario.
 ]
 ```
 
-A list of Mitre techniques associated with the IP.
+A list of Mitre techniques associated with the IP. More detail on the Mitre Att&ck can be found [here](https://attack.mitre.org/techniques/enterprise/).
 
 ### `name`
 
@@ -725,7 +724,7 @@ A list of CVEs for which the IP has been reported for.
 },
 ```
 
-The top 10 reports repartition by country about the IP, as a percentage
+The top 10 countries targeted by the IP. The numbers represent the percentage of the total number of attacks.
 
 ## `scores`
 
@@ -764,9 +763,9 @@ The top 10 reports repartition by country about the IP, as a percentage
 }
 ```
 
-Indicators of Malevolence computed on different time periods.
+Indicators of Malevolence computed over different time periods.
 
-:warning: All scores are from a scall of 0 to 5.
+:warning: All scores are on a scale from 0 to 5.
 
 ### `overall`
 
@@ -1101,4 +1100,4 @@ Only present for the `fire` route.
 
 Only present for the `fire` route.
 
-Date at which the IP address expire from the community blocklist.
+Date at which the IP address expires from the community blocklist.

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

@@ -6,19 +6,18 @@ sidebar_position: 3
 
 
 
-The scores are indicators of malevolence associated with an IP address, computed over several periods of time : 1 day, 1 week, 1 month and overall. 
+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, the indicator of malevolence is summarized under the `total` key with a value ranging from **0** (no reports) to **5** (high malevolence). 
- 
-This value is a summary based on 4 components (see below) also ranging from **0** (Not Applicable/ Missing) to **5** (High), comparing to all the the signals reported by the community.
+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.
 
 | indicator | explaination |
 |-----------|--------------|
-|Aggressiveness | _What is the intensity of the attack?_ This component measures the number of attacks reported over a period of time. |
-|Threat Level | _How serious is the type of threats reported?_ The category of attacks reported by the community defines the danger induced by the attacks. 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?_ This component is based on the reputation (age, number of reports) and the diversity (number of IP ranges, AS Numbers) of all the actors reporting the IP. It ranges from **0** (low\_confidence) to **5** (high confidence). |
-| Anomaly |  _What are the red flags associated with this IP address?_ It analyses the static description of the reported IP address and checks for red flags which can be linked to evidence of malicious activities |
-| Total | Aggregation of 4 component calculated on threats reported by the community and described below. |
+|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. |
 
+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).
 
 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