diff --git a/crowdsec-docs/sidebarsUnversioned.ts b/crowdsec-docs/sidebarsUnversioned.ts index c8fec84c3..cc48cc26c 100644 --- a/crowdsec-docs/sidebarsUnversioned.ts +++ b/crowdsec-docs/sidebarsUnversioned.ts @@ -105,28 +105,96 @@ const sidebarsUnversionedConfig: SidebarConfig = { trackerApiSidebar: [ { type: "doc", - label: "Getting Started", - id: "tracker_api/intro", + label: "Overview", + id: "tracker_api/overview", }, { - type: "doc", - label: "Prioritize", - id: "tracker_api/prioritize", + type: "category", + label: "Understanding the Data", + items: [ + { + type: "doc", + label: "Scores & Ratings", + id: "tracker_api/scores", + }, + { + type: "doc", + label: "Exploitation Phases", + id: "tracker_api/exploitation_phases", + }, + { + type: "doc", + label: "CrowdSec Analysis", + id: "tracker_api/crowdsec_analysis", + }, + { + type: "doc", + label: "Reconnaissance Rules vs CVEs", + id: "tracker_api/fingerprints_vs_cves", + }, + ], }, { type: "doc", - label: "Mitigate", - id: "tracker_api/mitigate", + label: "Web Interface", + id: "tracker_api/web_interface", }, { - type: "doc", - label: "API Reference", - id: "tracker_api/api_reference", + type: "category", + label: "API", + items: [ + { + type: "doc", + label: "Authentication & Setup", + id: "tracker_api/api_authentication", + }, + { + type: "doc", + label: "CVEs", + id: "tracker_api/api_cves", + }, + { + type: "doc", + label: "Reconnaissance / Fingerprints", + id: "tracker_api/api_fingerprints", + }, + { + type: "doc", + label: "Vendors, Products & Tags", + id: "tracker_api/api_lookups", + }, + { + type: "doc", + label: "Integrations & Blocklists", + id: "tracker_api/api_integrations", + }, + { + type: "doc", + label: "SDKs & Libraries", + id: "tracker_api/api_sdks", + }, + { + type: "doc", + label: "API Reference", + id: "tracker_api/api_reference", + }, + ], }, { - type: "doc", - label: "Web Interface", - id: "tracker_api/web_interface", + type: "category", + label: "Guides", + items: [ + { + type: "doc", + label: "Triage Workflow", + id: "tracker_api/guide_triage", + }, + { + type: "doc", + label: "Proactive Monitoring", + id: "tracker_api/guide_proactive", + }, + ], }, ], consoleSidebar: [ diff --git a/crowdsec-docs/static/img/exploit-tracker/attacker_insights.png b/crowdsec-docs/static/img/exploit-tracker/attacker_insights.png new file mode 100644 index 000000000..604b05c6c Binary files /dev/null and b/crowdsec-docs/static/img/exploit-tracker/attacker_insights.png differ diff --git a/crowdsec-docs/static/img/exploit-tracker/cve_detail_bottom.png b/crowdsec-docs/static/img/exploit-tracker/cve_detail_bottom.png new file mode 100644 index 000000000..3935fb03b Binary files /dev/null and b/crowdsec-docs/static/img/exploit-tracker/cve_detail_bottom.png differ diff --git a/crowdsec-docs/static/img/exploit-tracker/cve_detail_top.png b/crowdsec-docs/static/img/exploit-tracker/cve_detail_top.png new file mode 100644 index 000000000..12fa0a113 Binary files /dev/null and b/crowdsec-docs/static/img/exploit-tracker/cve_detail_top.png differ diff --git a/crowdsec-docs/static/img/exploit-tracker/explore_cves.png b/crowdsec-docs/static/img/exploit-tracker/explore_cves.png new file mode 100644 index 000000000..62dcadd7d Binary files /dev/null and b/crowdsec-docs/static/img/exploit-tracker/explore_cves.png differ diff --git a/crowdsec-docs/static/img/exploit-tracker/explore_recon.png b/crowdsec-docs/static/img/exploit-tracker/explore_recon.png new file mode 100644 index 000000000..53221bf47 Binary files /dev/null and b/crowdsec-docs/static/img/exploit-tracker/explore_recon.png differ diff --git a/crowdsec-docs/static/img/exploit-tracker/home.png b/crowdsec-docs/static/img/exploit-tracker/home.png new file mode 100644 index 000000000..a34204aeb Binary files /dev/null and b/crowdsec-docs/static/img/exploit-tracker/home.png differ diff --git a/crowdsec-docs/static/img/exploit-tracker/integrations.png b/crowdsec-docs/static/img/exploit-tracker/integrations.png new file mode 100644 index 000000000..7f0303cb4 Binary files /dev/null and b/crowdsec-docs/static/img/exploit-tracker/integrations.png differ diff --git a/crowdsec-docs/static/img/exploit-tracker/vendors.png b/crowdsec-docs/static/img/exploit-tracker/vendors.png new file mode 100644 index 000000000..e05e905fb Binary files /dev/null and b/crowdsec-docs/static/img/exploit-tracker/vendors.png differ diff --git a/crowdsec-docs/unversioned/tracker_api/api_authentication.mdx b/crowdsec-docs/unversioned/tracker_api/api_authentication.mdx new file mode 100644 index 000000000..6974f3641 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/api_authentication.mdx @@ -0,0 +1,74 @@ +--- +id: api_authentication +title: Authentication & Setup +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +## Prerequisites + +To use the Live Exploit Tracker API, you need an **API key**. Contact the CrowdSec team to obtain yours if you haven't already. + +The same API key works for both the [web interface](./web_interface) and the REST API. + +## Base URL + +All API endpoints are available at: + +``` +https://admin.api.crowdsec.net/v1/ +``` + +## Authentication + +Every API request must include your API key in the `x-api-key` header: + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/cves?page=1&size=10' \ + -H 'accept: application/json' \ + -H 'x-api-key: YOUR_API_KEY' +``` + +## SDKs + +CrowdSec provides official SDKs for convenient API access with typed models, authentication handling, and a better developer experience. See the [SDKs & Libraries](./api_sdks) page for installation instructions, examples, and the full list of available SDKs. + +**Quick start with the Python SDK:** + +```bash +pip install crowdsec-tracker-api +``` + +```python +import os +from crowdsec_tracker_api import Cves, ApiKeyAuth + +auth = ApiKeyAuth(api_key=os.getenv("CROWDSEC_TRACKER_API_KEY")) +cve = Cves(auth=auth).get_cve("CVE-2024-25600") +print(f"{cve.title}: Score {cve.crowdsec_score}, Phase: {cve.exploitation_phase.label}") +``` + +## Error Handling + +The API returns standard HTTP status codes: + +| Status Code | Meaning | +|---|---| +| `200` | Success | +| `201` | Resource created successfully | +| `204` | Success with no content (e.g., after deletion) | +| `401` | Invalid or missing API key | +| `404` | Resource not found | +| `422` | Validation error (check request parameters) | +| `429` | Rate limit exceeded | + +## Next Steps + +- [Explore CVEs](./api_cves) — List, search, and get detailed intelligence +- [Fingerprint Rules](./api_fingerprints) — Monitor product-level probing activity +- [Integrations & Blocklists](./api_integrations) — Create firewall integrations and subscribe to CVEs +- [Browse by Vendor, Product, or Tag](./api_lookups) — Explore the coverage landscape +- [SDKs & Libraries](./api_sdks) — Official SDKs for Python and more +- [API Reference (Swagger)](./api_reference) — Full interactive API documentation diff --git a/crowdsec-docs/unversioned/tracker_api/api_cves.mdx b/crowdsec-docs/unversioned/tracker_api/api_cves.mdx new file mode 100644 index 000000000..ee7cb7e69 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/api_cves.mdx @@ -0,0 +1,350 @@ +--- +id: api_cves +title: CVEs +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +This page covers the API endpoints for listing, searching, and retrieving detailed intelligence about CVEs tracked by the Live Exploit Tracker. + +:::info +For an introduction to what the scores and phases mean, see [Scores & Ratings](./scores) and [Exploitation Phases](./exploitation_phases). This page focuses on API usage. +::: + +## List Tracked CVEs + +Retrieve a paginated list of all CVEs that CrowdSec is currently tracking. + +``` +GET /v1/cves +``` + +### Parameters + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `page` | integer | 1 | Page number | +| `size` | integer | 50 | Items per page (max 100) | +| `sort_by` | string | `rule_release_date` | Sort field: `rule_release_date`, `trending`, `nb_ips`, `name`, `first_seen` | +| `sort_order` | string | `desc` | Sort direction: `asc`, `desc` | +| `filter_by` | string | — | Filter: `is_public` (only CVEs with public exploits) | + + + + +```bash +# List CVEs sorted by trending (highest CrowdSec Score first) +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/cves?page=1&size=10&sort_by=trending&sort_order=desc' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + + + + +```python +import os +from crowdsec_tracker_api import Cves, ApiKeyAuth +from httpx import HTTPStatusError + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +auth = ApiKeyAuth(api_key=KEY) +cves_service = Cves(auth=auth) + +try: + response = cves_service.get_cves(page=1, size=10) + for cve in response.items: + print(f"{cve.name}: CrowdSec Score={cve.crowdsec_score}, " + f"Phase={cve.exploitation_phase.label}, " + f"IPs={cve.nb_ips}") +except HTTPStatusError as e: + print(f"Error: {e.response.status_code} - {e.response.text}") +``` + + + + +### Response Fields + +Each CVE in the list includes: + +| Field | Type | Description | +|---|---|---| +| `id` | string | CVE identifier (e.g., `CVE-2024-25600`) | +| `title` | string | Human-readable title (e.g., "Bricks Builder - RCE") | +| `affected_components` | array | Vendor and product names | +| `crowdsec_score` | integer | Composite severity score (0–10) | +| `opportunity_score` | integer | Attack targeting score (0–5) | +| `momentum_score` | integer | Trend direction score (0–5) | +| `exploitation_phase` | object | Current phase: `name`, `label`, `description` | +| `nb_ips` | integer | Number of IPs currently exploiting this CVE | +| `cvss_score` | float | Standard CVSS severity score | +| `has_public_exploit` | boolean | Whether a public exploit exists | +| `first_seen` | datetime | When CrowdSec first observed exploitation | +| `last_seen` | datetime | Most recent observed exploitation | +| `published_date` | datetime | CVE publication date in NVD | +| `rule_release_date` | datetime | When CrowdSec released the detection rule | +| `adjustment_score` | object | Score adjustments: `total`, `recency` | +| `threat_context` | object | Contextual threat intelligence: `attacker_countries`, `defender_countries`, `industry_types`, `industry_risk_profiles`, `attacker_objectives` (may be empty for low-activity CVEs) | + +## Get CVE Details + +Retrieve full intelligence for a specific CVE, including the CrowdSec Analysis narrative, CWE classifications, references, events timeline, and tags. + +``` +GET /v1/cves/{cve_id} +``` + + + + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + + + + +```python +import os +from crowdsec_tracker_api import Cves, ApiKeyAuth +from httpx import HTTPStatusError + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +auth = ApiKeyAuth(api_key=KEY) +cves_service = Cves(auth=auth) + +try: + cve = cves_service.get_cve("CVE-2024-25600") + print(f"Title: {cve.title}") + print(f"CrowdSec Score: {cve.crowdsec_score}") + print(f"Phase: {cve.exploitation_phase.label}") + print(f"Analysis: {cve.crowdsec_analysis[:200]}...") +except HTTPStatusError as e: + print(f"Error: {e.response.status_code} - {e.response.text}") +``` + + + + +### Additional Fields (Detail Only) + +In addition to all the list fields, the detail response includes: + +| Field | Type | Description | +|---|---|---| +| `description` | string | Official CVE description | +| `crowdsec_analysis` | string | Human-readable intelligence narrative (Markdown) | +| `cwes` | array | CWE classifications with name, label, description | +| `references` | array | External reference URLs (advisories, exploits, nuclei templates) | +| `events` | array | Key events: CVE published, rule released, first seen, CISA KEV, etc. | +| `tags` | array | Category tags (e.g., `wordpress`, `cms`, `enterprise_software`) | + +## Get CVE Timeline + +Retrieve exploitation activity over time for a specific CVE. This powers the activity chart in the web interface. + +``` +GET /v1/cves/{cve_id}/timeline +``` + +### Parameters + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `interval` | string | `day` | Time bucket size: `hour`, `day`, `week` | + + + + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600/timeline?interval=week' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + + + + +```python +# Timeline data is returned as an array of {timestamp, count} objects +# Use your preferred charting library to visualize +``` + + + + +The response is an array of timeline items: + +| Field | Type | Description | +|---|---|---| +| `timestamp` | datetime | Start of the time bucket | +| `count` | integer | Number of exploitation events in this bucket | + +## Get IPs Exploiting a CVE + +Retrieve the list of IP addresses observed exploiting a specific CVE, enriched with CTI data. + +``` +GET /v1/cves/{cve_id}/ips-details +``` + +### Parameters + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `page` | integer | 1 | Page number | +| `size` | integer | 50 | Items per page | +| `since` | integer | — | Only IPs seen in the last N days: `1`, `7`, or `30` | + + + + +```bash +# Get IPs seen exploiting CVE-2024-25600 in the last 7 days +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600/ips-details?page=1&size=10&since=7' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + + + + +```python +import os +from crowdsec_tracker_api import Cves, ApiKeyAuth +from httpx import HTTPStatusError + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +auth = ApiKeyAuth(api_key=KEY) +cves_service = Cves(auth=auth) + +try: + response = cves_service.get_cve_ips("CVE-2024-25600", page=1, size=10) + for ip_item in response.items: + print(ip_item.model_dump_json(indent=2)) +except HTTPStatusError as e: + print(f"Error: {e.response.status_code} - {e.response.text}") +``` + + + + +### IP Response Fields + +Each IP item includes [CTI data](https://doc.crowdsec.net/u/cti_api/taxonomy/cti_object): + +| Field | Type | Description | +|---|---|---| +| `ip` | string | The IP address | +| `reputation` | string | Overall reputation: `malicious`, `suspicious`, `known`, `safe` | +| `ip_range` | string | The IP's network range (e.g., `70.35.192.0/20`) | +| `ip_range_score` | integer | Reputation score for the IP range | +| `ip_range_24` | string | The /24 subnet (null if not applicable) | +| `ip_range_24_reputation` | string | Reputation of the /24 subnet | +| `ip_range_24_score` | integer | Score for the /24 subnet | +| `as_name` | string | Autonomous System name (e.g., `IONOS SE`) | +| `as_num` | integer | Autonomous System Number | +| `background_noise` | string | Background noise level: `none`, `low`, `medium`, `high` | +| `background_noise_score` | integer | Numeric background noise score | +| `confidence` | string | Confidence level of the intelligence: `low`, `medium`, `high` | +| `location` | object | `country`, `city`, `latitude`, `longitude` | +| `reverse_dns` | string | Reverse DNS hostname (null if unavailable) | +| `scores` | object | CTI scores broken down by timeframe (`overall`, `last_day`, `last_week`, `last_month`), each containing `aggressiveness`, `threat`, `trust`, `anomaly`, `total` | +| `classifications` | object | `classifications` (actor categories) and `false_positives` arrays | +| `behaviors` | array | Observed behaviors with `name`, `label`, `description` | +| `attack_details` | array | Specific attacks observed from this IP with `name`, `label`, `description` | +| `mitre_techniques` | array | MITRE ATT&CK techniques with `name`, `label`, `description` | +| `cves` | array | List of CVE IDs this IP has been observed exploiting | +| `target_countries` | object | Countries targeted by this IP (country code → percentage) | +| `references` | array | External references | +| `history` | object | `first_seen`, `last_seen`, `full_age`, `days_age` | + +## Download IPs (Raw) + +Download a raw list of IP addresses exploiting a CVE, suitable for direct import into security tools. + +``` +GET /v1/cves/{cve_id}/ips-download +``` + +This returns a plain text list of IP addresses, one per line — useful for scripting and bulk import into SIEMs or blocklists. + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600/ips-download' \ + -H 'x-api-key: ${KEY}' +``` + +## Manage CVE Integration Subscriptions + +You can subscribe and unsubscribe firewall integrations to specific CVEs via the API. See [Integrations & Blocklists](./api_integrations) for full details on creating and managing integrations. + +### Subscribe an Integration to a CVE + +``` +POST /v1/cves/{cve_id}/integrations +``` + +```bash +curl -X 'POST' \ + 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600/integrations' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' \ + -H 'Content-Type: application/json' \ + -d '{"name": "my_firewall_integration"}' +``` + +### List Subscribed Integrations for a CVE + +``` +GET /v1/cves/{cve_id}/integrations +``` + +### Unsubscribe an Integration from a CVE + +``` +DELETE /v1/cves/{cve_id}/integrations/{integration_name} +``` + +```bash +curl -X 'DELETE' \ + 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600/integrations/my_firewall_integration' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` diff --git a/crowdsec-docs/unversioned/tracker_api/api_fingerprints.mdx b/crowdsec-docs/unversioned/tracker_api/api_fingerprints.mdx new file mode 100644 index 000000000..84ebe0615 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/api_fingerprints.mdx @@ -0,0 +1,231 @@ +--- +id: api_fingerprints +title: Reconnaissance / Fingerprint Rules +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +This page covers the API endpoints for **Reconnaissance rules** (called "fingerprint rules" or "fingerprints" in the API) — detection patterns for product-level probing activity. See [Reconnaissance Rules vs CVEs](./fingerprints_vs_cves) for an explanation of the concept. + +:::info Terminology +The web interface calls these **Reconnaissance rules** (or "Recon Rules"). The API uses **fingerprints** in all endpoint paths and field names. They are the same thing. +::: + +Fingerprint endpoints mirror the CVE endpoints: list, detail, timeline, IPs, and integration subscriptions. + +## List Fingerprint Rules + +Retrieve a paginated list of all fingerprint rules. + +``` +GET /v1/fingerprints +``` + +### Parameters + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `page` | integer | 1 | Page number | +| `size` | integer | 50 | Items per page | +| `sort_by` | string | `rule_release_date` | Sort field: `rule_release_date`, `trending`, `nb_ips`, `name`, `first_seen` | +| `sort_order` | string | `desc` | Sort direction: `asc`, `desc` | + + + + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/fingerprints?page=1&size=10' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + + + + +```python +import os +import httpx + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +headers = {"x-api-key": KEY, "accept": "application/json"} + +response = httpx.get( + "https://admin.api.crowdsec.net/v1/fingerprints", + params={"page": 1, "size": 10}, + headers=headers, +) +response.raise_for_status() +data = response.json() + +for rule in data["items"]: + print(f"{rule['title']}: CrowdSec Score={rule['crowdsec_score']}, IPs={rule['nb_ips']}") +``` + + + + +### Response Fields + +| Field | Type | Description | +|---|---|---| +| `id` | string | Fingerprint rule identifier (e.g., `microsoft-exchange`) | +| `name` | string | Rule name | +| `title` | string | Human-readable title (e.g., "Microsoft Exchange Probing") | +| `affected_components` | array | Products and vendors covered by this rule | +| `crowdsec_score` | integer | Composite severity score (0–10) | +| `opportunity_score` | integer | Attack targeting score (0–5) | +| `momentum_score` | integer | Trend direction score (0–5) | +| `exploitation_phase` | object | Current phase: `name`, `label`, `description` | +| `nb_ips` | integer | Number of IPs matching this fingerprint | +| `first_seen` | datetime | First observation | +| `last_seen` | datetime | Most recent observation | +| `rule_release_date` | datetime | When the detection rule was released | +| `adjustment_score` | object | Score adjustments: `total`, `recency` | + +## Get Fingerprint Rule Details + +Returns the full detail for a fingerprint rule. The response includes the same list fields plus: `description`, `crowdsec_analysis`, `events`, `tags`, `references`, and `threat_context`. + +:::info +Unlike CVE details, fingerprint details do **not** include `cvss_score`, `published_date`, `has_public_exploit`, or `cwes` — these are CVE-specific fields. +::: + +``` +GET /v1/fingerprints/{fingerprint} +``` + + + + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/fingerprints/microsoft-exchange' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + + + + +```python +import os +import httpx + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +headers = {"x-api-key": KEY, "accept": "application/json"} + +response = httpx.get( + "https://admin.api.crowdsec.net/v1/fingerprints/microsoft-exchange", + headers=headers, +) +response.raise_for_status() +print(response.json()) +``` + + + + +## Get Fingerprint Timeline + +Retrieve probing activity over time for a fingerprint rule. + +``` +GET /v1/fingerprints/{fingerprint}/timeline +``` + +### Parameters + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `interval` | string | `day` | Time bucket: `hour`, `day`, `week` | + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/fingerprints/microsoft-exchange/timeline?interval=week' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +## Get IPs Matching a Fingerprint + +Retrieve IPs observed probing targets matching this fingerprint rule, enriched with CTI data. + +``` +GET /v1/fingerprints/{fingerprint}/ips-details +``` + +### Parameters + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `page` | integer | 1 | Page number | +| `size` | integer | 50 | Items per page | +| `since` | integer | — | Only IPs seen in the last N days: `1`, `7`, or `30` | + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/fingerprints/microsoft-exchange/ips-details?page=1&size=10&since=7' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +The response format is identical to [CVE IP details](./api_cves#ip-response-fields). + +## Download IPs (Raw) + +``` +GET /v1/fingerprints/{fingerprint}/ips-download +``` + +Returns a plain text list of IPs, one per line. + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/fingerprints/microsoft-exchange/ips-download' \ + -H 'x-api-key: ${KEY}' +``` + +## Manage Fingerprint Integration Subscriptions + +### Subscribe an Integration + +``` +POST /v1/fingerprints/{fingerprint}/integrations +``` + +```bash +curl -X 'POST' \ + 'https://admin.api.crowdsec.net/v1/fingerprints/microsoft-exchange/integrations' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' \ + -H 'Content-Type: application/json' \ + -d '{"name": "my_firewall_integration"}' +``` + +### List Subscribed Integrations + +``` +GET /v1/fingerprints/{fingerprint}/integrations +``` + +### Unsubscribe an Integration + +``` +DELETE /v1/fingerprints/{fingerprint}/integrations/{integration_name} +``` diff --git a/crowdsec-docs/unversioned/tracker_api/api_integrations.mdx b/crowdsec-docs/unversioned/tracker_api/api_integrations.mdx new file mode 100644 index 000000000..582e2d71d --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/api_integrations.mdx @@ -0,0 +1,351 @@ +--- +id: api_integrations +title: Integrations & Blocklists +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +Integrations are the bridge between CrowdSec's threat intelligence and your security infrastructure. An integration generates a blocklist of attacker IPs that your firewall can consume. You subscribe integrations to specific CVEs or fingerprint rules, and the blocklist automatically updates as new attacker IPs are observed. + +## Supported Output Formats + +When creating an integration, you choose an output format matching your firewall: + +| Format | Value | Description | +|---|---|---| +| Plain Text | `plain_text` | One IP per line. Universal format supported by most tools. | +| F5 | `f5` | F5 BIG-IP compatible format | +| FortiGate | `fortigate` | FortiGate compatible format | +| Palo Alto | `paloalto` | PAN-OS compatible format | +| Checkpoint | `checkpoint` | Check Point compatible format | +| Cisco | `cisco` | Cisco compatible format | +| Juniper | `juniper` | Juniper compatible format | +| MikroTik | `mikrotik` | MikroTik compatible format | +| pfSense | `pfsense` | pfSense compatible format | +| OPNsense | `opnsense` | OPNsense compatible format | +| Sophos | `sophos` | Sophos compatible format | +| Remediation Component | `remediation_component` | CrowdSec's own remediation components | + +## Create an Integration + +``` +POST /v1/integrations +``` + + + + +```bash +curl -X 'POST' \ + 'https://admin.api.crowdsec.net/v1/integrations' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' \ + -H 'Content-Type: application/json' \ + -d '{ + "name": "paloalto_production", + "description": "Production Palo Alto firewall - CVE blocklist", + "entity_type": "firewall_integration", + "output_format": "paloalto" + }' +``` + + + + +```python +import os +from crowdsec_tracker_api import ( + Integrations, IntegrationCreateRequest, + IntegrationType, OutputFormat, ApiKeyAuth, +) +from httpx import HTTPStatusError + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +auth = ApiKeyAuth(api_key=KEY) +integrations_service = Integrations(auth=auth) + +request = IntegrationCreateRequest( + name="paloalto_production", + description="Production Palo Alto firewall - CVE blocklist", + entity_type=IntegrationType.FIREWALL_INTEGRATION.value, + output_format=OutputFormat.PALOALTO.value, +) + +try: + response = integrations_service.create_integration(request=request) + print(f"Integration ID: {response.id}") + print(f"Credentials: {response.credentials}") + # IMPORTANT: Save the credentials securely — they are only shown once! +except HTTPStatusError as e: + print(f"Error: {e.response.status_code} - {e.response.text}") +``` + + + + +:::warning +The integration credentials (API key or username/password depending on type) are **only shown once** in the creation response. Store them securely. If you lose them, you'll need to regenerate them by updating the integration. +::: + +### Integration Types + +| Type | Value | Description | +|---|---|---| +| Firewall Integration | `firewall_integration` | For direct firewall consumption via blocklist URL | +| Remediation Component | `remediation_component_integration` | For CrowdSec remediation components | + +### Integration Response Fields + +| Field | Type | Description | +|---|---|---| +| `id` | string | Unique integration identifier | +| `name` | string | Integration name | +| `description` | string | Human-readable description | +| `organization_id` | string | Owning organization ID | +| `entity_type` | string | `firewall_integration` or `remediation_component_integration` | +| `output_format` | string | Blocklist format (see table above) | +| `cves` | array | CVE subscriptions (each with `id`) | +| `fingerprints` | array | Fingerprint rule subscriptions | +| `blocklists` | array | Blocklist subscriptions | +| `endpoint` | string | URL for fetching the integration's blocklist content | +| `stats` | object | Statistics including `count` (number of IPs in the blocklist) | +| `tags` | array | Tags attached to the integration | +| `enable_ip_aggregation` | boolean | When enabled, CrowdSec automatically aggregates adjacent IPs into network ranges where possible, reducing blocklist size | +| `created_at` | datetime | Creation timestamp | +| `updated_at` | datetime | Last update timestamp | + +## List Integrations + +``` +GET /v1/integrations +``` + + + + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/integrations' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + + + + +```python +import os +from crowdsec_tracker_api import Integrations, ApiKeyAuth +from httpx import HTTPStatusError + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +auth = ApiKeyAuth(api_key=KEY) +integrations_service = Integrations(auth=auth) + +try: + response = integrations_service.get_integrations() + for integration in response.items: + print(f"{integration.name}: {integration.entity_type}, " + f"subscriptions: {len(integration.blocklist_subscriptions or [])}") +except HTTPStatusError as e: + print(f"Error: {e.response.status_code} - {e.response.text}") +``` + + + + +## Get Integration Details + +``` +GET /v1/integrations/{integration_id} +``` + +## Update an Integration + +Update the name, description, output format, or regenerate credentials. + +``` +PATCH /v1/integrations/{integration_id} +``` + + + + +```bash +curl -X 'PATCH' \ + 'https://admin.api.crowdsec.net/v1/integrations/YOUR_INTEGRATION_ID' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' \ + -H 'Content-Type: application/json' \ + -d '{ + "name": "paloalto_production_v2", + "description": "Updated description", + "regenerate_credentials": true + }' +``` + + + + +```python +import os +from crowdsec_tracker_api import ( + Integrations, IntegrationUpdateRequest, ApiKeyAuth, +) +from httpx import HTTPStatusError + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +auth = ApiKeyAuth(api_key=KEY) +integrations_service = Integrations(auth=auth) + +request = IntegrationUpdateRequest( + name="paloalto_production_v2", + regenerate_credentials=True, + description="Updated description", +) + +try: + response = integrations_service.update_integration( + integration_id="YOUR_INTEGRATION_ID", + request=request, + ) + print(f"Updated: {response.name}") + if response.credentials: + print(f"New credentials: {response.credentials}") +except HTTPStatusError as e: + print(f"Error: {e.response.status_code} - {e.response.text}") +``` + + + + +:::tip +Use `regenerate_credentials: true` if you need to rotate the integration's credentials. The new credentials will be returned in the response. +::: + +## Delete an Integration + +``` +DELETE /v1/integrations/{integration_id} +``` + + + + +```bash +# Force delete even if integration has active subscriptions +curl -X 'DELETE' \ + 'https://admin.api.crowdsec.net/v1/integrations/YOUR_INTEGRATION_ID?force=true' \ + -H 'accept: */*' \ + -H 'x-api-key: ${KEY}' +``` + + + + +```python +import os +from crowdsec_tracker_api import Integrations, ApiKeyAuth +from httpx import HTTPStatusError + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +auth = ApiKeyAuth(api_key=KEY) +integrations_service = Integrations(auth=auth) + +try: + integrations_service.delete_integration(integration_id="YOUR_INTEGRATION_ID") + print("Integration deleted.") +except HTTPStatusError as e: + print(f"Error: {e.response.status_code} - {e.response.text}") +``` + + + + +Use the `force=true` query parameter to delete an integration even if it has active CVE or fingerprint subscriptions. + +## Get Integration Content (Blocklist) + +Retrieve the actual blocklist content that a firewall would consume. + +``` +GET /v1/integrations/{integration_id}/content +``` + +This returns the blocklist in the format specified when the integration was created (plain text, PAN-OS format, etc.). + +You can also check if an integration has content without downloading it: + +``` +HEAD /v1/integrations/{integration_id}/content +``` + +Returns `200` if content is available, `204` if the integration has no subscriptions or no content. + +## Streaming Content (Remediation Components) + +For CrowdSec remediation components, a streaming endpoint is available: + +``` +GET /v1/integrations/{integration_id}/v1/decisions/stream +``` + +This is compatible with CrowdSec's remediation component protocol. + +## End-to-End Workflow + +Here's a complete example: create an integration, subscribe it to a CVE and a fingerprint rule, and verify the blocklist. + +```bash +# 1. Create a plain text integration +curl -X 'POST' 'https://admin.api.crowdsec.net/v1/integrations' \ + -H 'x-api-key: ${KEY}' -H 'Content-Type: application/json' \ + -d '{"name": "demo_blocklist", "description": "Demo", "entity_type": "firewall_integration", "output_format": "plain_text"}' + +# 2. Subscribe to a CVE +curl -X 'POST' 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600/integrations' \ + -H 'x-api-key: ${KEY}' -H 'Content-Type: application/json' \ + -d '{"name": "demo_blocklist"}' + +# 3. Subscribe to a fingerprint rule +curl -X 'POST' 'https://admin.api.crowdsec.net/v1/fingerprints/microsoft-exchange/integrations' \ + -H 'x-api-key: ${KEY}' -H 'Content-Type: application/json' \ + -d '{"name": "demo_blocklist"}' + +# 4. Fetch the blocklist (using integration credentials) +curl 'https://admin.api.crowdsec.net/v1/integrations/INTEGRATION_ID/content' \ + -H 'x-api-key: INTEGRATION_API_KEY' +``` + +## Next Steps + +Once your integration is created and subscribed, configure your firewall to fetch the blocklist URL at regular intervals. See the [CrowdSec Integrations documentation](https://docs.crowdsec.net/u/integrations/intro) for vendor-specific setup guides. diff --git a/crowdsec-docs/unversioned/tracker_api/api_lookups.mdx b/crowdsec-docs/unversioned/tracker_api/api_lookups.mdx new file mode 100644 index 000000000..a4f709f19 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/api_lookups.mdx @@ -0,0 +1,158 @@ +--- +id: api_lookups +title: Vendors, Products & Tags +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +The Live Exploit Tracker provides lookup endpoints to explore the coverage landscape. These help answer questions like "what WordPress vulnerabilities are being tracked?", "which Citrix products are covered?", or "what enterprise software threats should I monitor?" + +## Tags + +Tags are technology categories applied to CVEs and fingerprint rules (e.g., `wordpress`, `cms`, `enterprise_software`, `file_sharing`). + +### List All Tags + +``` +GET /v1/tags +``` + + + + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/tags' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + + + + +```python +import os +import httpx + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +headers = {"x-api-key": KEY, "accept": "application/json"} + +response = httpx.get("https://admin.api.crowdsec.net/v1/tags", headers=headers) +response.raise_for_status() + +for tag in response.json()["items"]: + print(f"{tag['value']}: {tag['nb_cves']} CVEs, {tag['nb_fingerprints']} fingerprints, " + f"{tag['nb_ips_cves'] + tag['nb_ips_fingerprints']} total IPs") +``` + + + + +Each tag includes: + +| Field | Type | Description | +|---|---|---| +| `value` | string | Tag name | +| `nb_cves` | integer | Number of CVEs with this tag | +| `nb_fingerprints` | integer | Number of fingerprint rules with this tag | +| `nb_ips_cves` | integer | Total attacker IPs across CVEs with this tag | +| `nb_ips_fingerprints` | integer | Total attacker IPs across fingerprint rules with this tag | +| `latest_rule_release` | datetime | Most recent detection rule release for this tag | + +### Get Tag Impact + +View all CVEs and fingerprint rules associated with a specific tag: + +``` +GET /v1/tags/{tag} +``` + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/tags/wordpress' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +## Vendors + +Vendors are the organizations responsible for the affected software (e.g., Microsoft, Citrix, WordPress). + +### List All Vendors + +``` +GET /v1/vendors +``` + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/vendors?page=1&size=20' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +Each vendor includes the same statistics as tags: number of CVEs, fingerprint rules, and attacker IPs. + +### Get Vendor Impact + +View all CVEs and fingerprint rules affecting a specific vendor's products: + +``` +GET /v1/vendors/{vendor} +``` + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/vendors/Microsoft' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +## Products + +Products are specific software applications (e.g., Exchange Server, BIG-IP, WordPress). + +### List All Products + +``` +GET /v1/products +``` + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/products?page=1&size=20' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +### Get Product Impact + +View all CVEs and fingerprint rules affecting a specific product: + +``` +GET /v1/products/{product} +``` + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/products/Exchange%20Server' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +## Use Cases + +These lookup endpoints are particularly useful for: + +- **Asset-based monitoring**: "Show me all tracked threats for the products in my technology stack." +- **Coverage assessment**: "How many vulnerabilities affecting WordPress does CrowdSec track?" +- **Reporting**: "What's the overall threat landscape for enterprise software this month?" +- **Automation**: Build scripts that automatically subscribe integrations to all new CVEs for your vendor ecosystem. diff --git a/crowdsec-docs/unversioned/tracker_api/api_sdks.mdx b/crowdsec-docs/unversioned/tracker_api/api_sdks.mdx new file mode 100644 index 000000000..64b864f93 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/api_sdks.mdx @@ -0,0 +1,124 @@ +--- +id: api_sdks +title: SDKs & Libraries +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +CrowdSec provides official SDKs to simplify integration with the Live Exploit Tracker API. These libraries handle authentication, request construction, response parsing, and provide typed models for a better developer experience. + +## Python SDK + +The official Python SDK is the recommended way to interact with the API from Python applications, scripts, and automation pipelines. + +### Installation + +```bash +pip install crowdsec-tracker-api +``` + +**Requirements**: Python 3.8+ + +**Source**: [github.com/crowdsecurity/crowdsec-tracker-api-sdk-python](https://github.com/crowdsecurity/crowdsec-tracker-api-sdk-python) + +### Authentication + +```python +import os +from crowdsec_tracker_api import ApiKeyAuth, Server + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") + +# Configure authentication +auth = ApiKeyAuth(api_key=KEY) + +# The SDK automatically uses the production server URL +# You can also set it explicitly: +# base_url = Server.production_server.value +``` + +### Service Classes + +The SDK provides typed service classes for each API domain: + +| Service Class | Purpose | Key Methods | +|---|---|---| +| `Cves` | CVE intelligence | `get_cves()`, `get_cve()`, `get_cve_ips()` | +| `Integrations` | Firewall integration management | `get_integrations()`, `create_integration()`, `update_integration()`, `delete_integration()` | + +### Examples + +#### List trending CVEs + +```python +import os +from crowdsec_tracker_api import Cves, ApiKeyAuth +from httpx import HTTPStatusError + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +auth = ApiKeyAuth(api_key=KEY) +cves_service = Cves(auth=auth) + +try: + response = cves_service.get_cves(page=1, size=10) + for cve in response.items: + print(f"{cve.name}: CrowdSec Score={cve.crowdsec_score}, " + f"Phase={cve.exploitation_phase.label}, " + f"IPs={cve.nb_ips}") +except HTTPStatusError as e: + print(f"Error: {e.response.status_code} - {e.response.text}") +``` + +#### Get detailed CVE intelligence + +```python +try: + cve = cves_service.get_cve("CVE-2024-25600") + print(f"Title: {cve.title}") + print(f"CrowdSec Score: {cve.crowdsec_score}") + print(f"Phase: {cve.exploitation_phase.label}") + print(f"Analysis: {cve.crowdsec_analysis[:200]}...") +except HTTPStatusError as e: + print(f"Error: {e.response.status_code} - {e.response.text}") +``` + +#### Retrieve attacker IPs for a CVE + +```python +try: + response = cves_service.get_cve_ips("CVE-2024-25600", page=1, size=10) + for ip_item in response.items: + print(f"{ip_item.ip}: reputation={ip_item.reputation}, " + f"country={ip_item.location.country}") +except HTTPStatusError as e: + print(f"Error: {e.response.status_code} - {e.response.text}") +``` + +#### Create and manage a firewall integration + +```python +from crowdsec_tracker_api import ( + Integrations, IntegrationCreateRequest, + IntegrationType, OutputFormat, ApiKeyAuth, +) + +integrations_service = Integrations(auth=auth) + +# Create +request = IntegrationCreateRequest( + name="paloalto_production", + description="Production Palo Alto firewall - CVE blocklist", + entity_type=IntegrationType.FIREWALL_INTEGRATION.value, + output_format=OutputFormat.PALOALTO.value, +) +response = integrations_service.create_integration(request=request) +print(f"Integration ID: {response.id}") +# IMPORTANT: Save the credentials — they are only shown once! +``` + +## Other Languages + +Need the API in another language? The REST API is straightforward to call from any HTTP client — see [Authentication & Setup](./api_authentication) for the base URL and authentication details, and the [API Reference (Swagger)](./api_reference) for the full OpenAPI specification. + +If you'd like to see an official SDK for your language, let us know on [GitHub](https://github.com/crowdsecurity) or [Discord](https://discord.gg/crowdsec). diff --git a/crowdsec-docs/unversioned/tracker_api/crowdsec_analysis.mdx b/crowdsec-docs/unversioned/tracker_api/crowdsec_analysis.mdx new file mode 100644 index 000000000..923c14755 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/crowdsec_analysis.mdx @@ -0,0 +1,77 @@ +--- +id: crowdsec_analysis +title: CrowdSec Analysis +--- + +## What is the CrowdSec Analysis + +Every tracked CVE with sufficient data includes a **CrowdSec Analysis** — a human-readable intelligence narrative that synthesizes what CrowdSec has observed about the vulnerability and its exploitation in the wild. + +Unlike raw scores or static CVE descriptions, the analysis tells a story: what the vulnerability does, how attackers are using it, what patterns have been observed, and what specific indicators to watch for. + +## What the Analysis Contains + +A typical CrowdSec Analysis covers four areas: + +### 1. Vulnerability Summary + +A concise explanation of the vulnerability itself — what it allows an attacker to do and why it matters. This goes beyond the standard CVE description by focusing on practical impact rather than technical classification. + +### 2. Tracking Timeline + +When CrowdSec started tracking this vulnerability, which provides context for how mature the telemetry data is. A CVE tracked for months will have richer behavioral data than one added last week. + +### 3. Exploitation Patterns + +The most operationally valuable part. Based on CrowdSec Network telemetry, this section describes: + +- **Attack sophistication**: Are attackers conducting reconnaissance first, or blindly spraying exploits? Are campaigns tailored to specific environments? +- **Trend analysis**: Is exploitation activity increasing, decreasing, or steady? How does current volume compare to historical averages? +- **Attacker behavior**: What does the typical attack campaign look like? Is it a single coordinated group or many independent actors? + +### 4. Technical Indicators + +Specific, actionable details about what the exploitation looks like on the wire. This typically includes: + +- Targeted URLs or endpoints (e.g., `/wp-json/bricks/v1/render_element`) +- HTTP methods and payload characteristics +- Request patterns that distinguish exploitation from legitimate traffic + +These indicators can be used to write detection rules, validate alerts, or understand what your WAF logs should show during an exploitation attempt. + +## How to Use It + +### In Triage + +When investigating an alert, the CrowdSec Analysis tells you whether the attack pattern you're seeing matches what's being observed globally. If your logs show requests to the exact endpoint described in the analysis, that's strong confirmation of an exploitation attempt — not a false positive. + +### In Reporting + +The analysis provides ready-to-use language for security briefings. Instead of presenting raw scores to stakeholders, you can reference the narrative: "CrowdSec observes that attackers are performing focused reconnaissance before exploiting this vulnerability, and activity has been growing week-over-week." + +### In Threat Hunting + +The technical indicators section points you to exactly where to look in your logs. Search for the specific URLs, parameters, or request patterns described in the analysis to identify exploitation attempts — both successful and blocked. + +## Accessing the Analysis + +### Web Interface + +The CrowdSec Analysis is displayed prominently on each CVE's detail page in the [web interface](https://tracker.crowdsec.net). + +### API + +The analysis is returned in the `crowdsec_analysis` field of the CVE detail endpoint: + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +The response includes the full analysis text in the `crowdsec_analysis` field, formatted as Markdown with links to external references. + +:::info +The CrowdSec Analysis is not available for CVEs in the *Insufficient Data* phase, as there isn't enough telemetry to generate meaningful intelligence. +::: diff --git a/crowdsec-docs/unversioned/tracker_api/exploitation_phases.mdx b/crowdsec-docs/unversioned/tracker_api/exploitation_phases.mdx new file mode 100644 index 000000000..0d5cf4239 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/exploitation_phases.mdx @@ -0,0 +1,83 @@ +--- +id: exploitation_phases +title: Exploitation Phases +--- + +## Overview + +Every tracked CVE and fingerprint rule is assigned an **exploitation phase** that describes where it sits in its lifecycle. While the [scores](./scores) give you numerical ratings, the exploitation phase gives you a qualitative label that's immediately understandable in conversations, reports, and dashboards. + +The phases are determined by analyzing exploitation telemetry from the CrowdSec Network over time — they reflect real attacker behavior, not theoretical risk. + +## The Five Phases + +### Insufficient Data + +> *"Not enough CrowdSec telemetry data is available to confidently assess how this vulnerability is exploited in the wild."* + +This is the starting state for newly tracked CVEs or those affecting products with limited representation in the CrowdSec Network. It does **not** mean the CVE isn't being exploited — only that CrowdSec doesn't have enough observations to characterize the exploitation pattern with confidence. + +**What to do**: Fall back to traditional risk indicators (CVSS score, public exploit availability, vendor advisory severity) until CrowdSec telemetry matures for this CVE. Check back periodically as the phase will update when sufficient data is collected. + +### Unpopular + +> *"The vulnerability is known but shows very limited attacker interest or exploitation activity."* + +CrowdSec has data for this CVE but observes minimal exploitation. Attackers are either unaware of it, unable to exploit it at scale, or have moved on to more productive targets. + +**What to do**: Patch within your standard maintenance cycle. This is low on the priority list unless your specific environment makes it unusually exploitable. + +### Background Noise + +> *"Continuous low-level scanning or exploitation attempts are observed, mostly opportunistic and automated."* + +This is the "internet weather" phase. The CVE is being hit by automated scanners and botnets as part of broad, indiscriminate campaigns. It's persistent but generally not dangerous to well-maintained infrastructure. + +Think of it like port-scanning on port 22: it happens constantly, to everyone, and by itself it's not cause for alarm. + +**What to do**: Ensure patches are applied. Consider blocklists if you want to reduce noise in your logs. Individual alerts are low-signal — don't let them dominate your SOC's attention. + +### Targeted Exploitation + +> *"Exploitation is observed against specific targets or environments, suggesting focused and intentional attack campaigns."* + +This is where things get serious. Attackers are performing reconnaissance, selecting targets based on exposure and configuration, and launching deliberate campaigns. An alert for a CVE in this phase is much more likely to represent a real attack on your organization. + +**What to do**: Prioritize patching urgently. Deploy blocklists via firewall integrations. If you see alerts on your infrastructure for CVEs in this phase, investigate them as potential incidents — not just noise. + +### Mass Exploitation + +> *"The vulnerability is actively exploited at scale across the internet, often via automated tools and large attack campaigns."* + +The vulnerability has been weaponized at scale. Multiple threat actor groups are exploiting it, exploit code is widely available, and attack volume is high. This typically happens with high-impact vulnerabilities in widely deployed software. + +**What to do**: Treat this as an emergency if you haven't patched yet. Verify patch status across your entire estate. Deploy blocklists immediately. Monitor for signs of compromise, as exploitation may have occurred before you acted. + +## Phase Transitions + +CVEs don't always move linearly through these phases. Common patterns include: + +- **Newly published CVE with public exploit**: May jump directly from *Insufficient Data* to *Targeted Exploitation* or *Mass Exploitation* if attackers weaponize it quickly. +- **Old CVE with new exploit toolkit**: A CVE that was *Background Noise* for years can escalate to *Mass Exploitation* when it gets added to a popular exploit framework. +- **Campaign ends**: A CVE in *Mass Exploitation* can settle back to *Background Noise* once the initial campaign runs its course and most targets are patched. +- **Steady state**: Many CVEs stabilize in *Background Noise* indefinitely — they remain part of automated scanning toolkits long after the initial threat subsides. + +## Phases and Scores Together + +The exploitation phase and numerical scores provide **complementary but independent** signals. Phases are determined by analyzing exploitation patterns over time, while scores reflect the current snapshot. This means a CVE can have a high CrowdSec Score while still in the Insufficient Data phase (for example, a newly tracked CVE with intense but recent activity that hasn't been observed long enough to classify). + +:::caution +Do not assume phases predict score ranges. A Background Noise CVE can have a CrowdSec Score of 6 if it has surging volume (high Momentum), while a Mass Exploitation CVE can have a score of 3 if the campaign is winding down. Use both signals together for a complete picture. +::: + +Typical ranges observed in practice: + +| Phase | Typical CrowdSec Score | Typical Opportunity Score | Typical Momentum Score | +|-------|----------------------|--------------------------|----------------------| +| Insufficient Data | 0–9 | 0–5 | 0–5 | +| Unpopular | 1–7 | 1–2 | 0–5 | +| Background Noise | 1–6 | 1–2 | 0–5 | +| Targeted Exploitation | 7–8 | 4–5 | 2–4 | +| Mass Exploitation | 3–7 | 1–5 | 0–4 | + +Targeted Exploitation is the most predictable: it consistently shows high Opportunity scores (4–5) and elevated CrowdSec Scores. Other phases are more loosely correlated — Background Noise and Unpopular overlap significantly in score ranges, and Mass Exploitation spans a wide range depending on whether the campaign is ramping up or fading. diff --git a/crowdsec-docs/unversioned/tracker_api/fingerprints_vs_cves.mdx b/crowdsec-docs/unversioned/tracker_api/fingerprints_vs_cves.mdx new file mode 100644 index 000000000..271ded719 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/fingerprints_vs_cves.mdx @@ -0,0 +1,82 @@ +--- +id: fingerprints_vs_cves +title: Reconnaissance Rules vs CVEs +--- + +:::info Terminology +Reconnaissance rules are called **"Reconnaissance"** or **"Recon Rules"** in the web interface, and **"fingerprint rules"** or **"fingerprints"** in the API. This documentation uses both terms interchangeably — they refer to the same thing. +::: + +## Two Types of Tracking + +The Live Exploit Tracker monitors threats at two levels: + +- **CVEs**: Specific, named vulnerabilities (e.g., CVE-2024-25600 — a code injection flaw in Bricks Builder for WordPress). +- **Reconnaissance Rules** (API: fingerprint rules): Product-level probing patterns that detect reconnaissance or exploitation activity targeting a product family, regardless of which specific CVE the attacker intends to exploit. + +Both share the same scoring system ([CrowdSec Score, Opportunity/Targeted Score, Momentum Score](./scores)), the same [exploitation phases](./exploitation_phases), and the same integration/blocklist capabilities. The difference is in what they track and why. + +## CVE Tracking + +A CVE entry in the tracker focuses on a **single, identified vulnerability**. The detection rule is built around the specific exploit technique — the URL, the payload structure, the HTTP method — that attackers use to exploit that particular flaw. + +CVE tracking is ideal when: + +- You know which specific vulnerabilities affect your environment +- You want to monitor exploitation of a known flaw you haven't patched yet +- You need to assess the urgency of a specific patch + +Each CVE entry includes a description, CVSS score, CWE classification, references, a CrowdSec Analysis, and a timeline of key events (CVE published, detection rule released, first exploitation observed). + +## Fingerprint Rule Tracking + +A fingerprint rule detects **product-level probing and reconnaissance activity** that doesn't map to a single CVE. Instead, it catches patterns like: + +- Scanning for the presence of a specific product (e.g., probing known Microsoft Exchange endpoints to determine if a server is running Exchange) +- Enumeration of product versions or configurations +- Broad reconnaissance that could precede exploitation of any of several CVEs affecting that product + +### Examples + +| Fingerprint Rule | What It Detects | +|---|---| +| **Microsoft Exchange Probing** | Reconnaissance targeting Exchange servers, including version detection and endpoint enumeration across Exchange Server, OWA, and EWS. | +| **F5 Probing** | Scanning activity targeting F5 BIG-IP and TMUI interfaces. | +| **WordPress Probing** | Broad WordPress discovery and enumeration activity. | + +### Why Fingerprints Matter + +Fingerprint rules fill a critical gap: + +1. **Early warning**: Reconnaissance typically precedes exploitation. Seeing fingerprint activity targeting a product you run suggests an attacker is mapping your attack surface — even if they haven't launched an exploit yet. + +2. **Zero-day coverage**: When a new vulnerability is disclosed for a product, attackers who were already probing that product may exploit it immediately. If you're tracking the fingerprint rule, you already have visibility into who has been scanning your infrastructure. + +3. **Multi-CVE protection**: A single product may have dozens of CVEs. Rather than subscribing to each one individually, a fingerprint rule covers reconnaissance activity that could lead to any of them. + +## Feature Comparison + +| Capability | CVEs | Fingerprints | +|---|---|---| +| Scores (CrowdSec, Opportunity, Momentum) | ✅ | ✅ | +| Exploitation phases | ✅ | ✅ | +| IP intelligence (attacker IPs with CTI) | ✅ | ✅ | +| Timeline (activity over time) | ✅ | ✅ | +| Firewall integration subscriptions | ✅ | ✅ | +| CVSS score | ✅ | — | +| CWE classification | ✅ | — | +| CrowdSec Analysis narrative | ✅ | — | +| CVE events timeline | ✅ | — | + +## Using Them Together + +The most comprehensive monitoring strategy combines both: + +1. **Subscribe fingerprint rules** for all products in your technology stack (Exchange, WordPress, F5, etc.). This gives you broad reconnaissance visibility. +2. **Monitor specific CVEs** for unpatched vulnerabilities in your environment. This gives you targeted exploitation intelligence. +3. **Create firewall integrations** subscribed to both CVEs and fingerprint rules to build layered blocklists. + +For example, if you run WordPress: +- Subscribe to the **WordPress Probing** fingerprint rule to catch general reconnaissance +- Subscribe to specific CVEs like **CVE-2024-25600** (Bricks Builder RCE) if you run affected plugins +- Create a firewall integration subscribed to both, so your blocklist captures both scanners and active exploiters diff --git a/crowdsec-docs/unversioned/tracker_api/guide_proactive.mdx b/crowdsec-docs/unversioned/tracker_api/guide_proactive.mdx new file mode 100644 index 000000000..e8a7b8f50 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/guide_proactive.mdx @@ -0,0 +1,142 @@ +--- +id: guide_proactive +title: "Guide: Proactive Monitoring" +--- + +## Scenario + +Rather than reacting to alerts one at a time, you want to **proactively monitor** the threat landscape for vulnerabilities relevant to your technology stack. This guide shows how to set up ongoing monitoring using the Live Exploit Tracker. + +## Step 1: Identify Your Technology Stack + +Start by identifying the vendors, products, and technology categories you care about. Common examples: + +| If you run... | Monitor these tags/vendors | +|---|---| +| WordPress sites | Tag: `wordpress`, `cms` | +| Microsoft infrastructure | Vendor: `Microsoft`, Tags: `enterprise_software` | +| Network appliances | Vendors: `F5`, `Cisco`, `Palo Alto`, `Fortinet` | +| Java applications | Tag: `web_application`, specific product names | + +## Step 2: Explore Coverage + +Use the lookup endpoints to see what CrowdSec tracks for your stack. + +### Via Web Interface + +Browse the CVE and fingerprint rule lists, filtering by tag or searching by product name. + +### Via API + +```bash +# What WordPress vulnerabilities does CrowdSec track? +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/tags/wordpress' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' + +# What Microsoft products are covered? +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/vendors/Microsoft' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' + +# What fingerprint rules exist for Exchange? +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/fingerprints?page=1&size=50' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +## Step 3: Set Up Fingerprint Monitoring + +[Fingerprint rules](./fingerprints_vs_cves) give you broad coverage for product families. Even if a new CVE drops tomorrow for Exchange, the "Microsoft Exchange Probing" fingerprint rule already captures reconnaissance activity. + +1. Identify fingerprint rules matching your products +2. Create a firewall integration (if you don't have one) +3. Subscribe the integration to relevant fingerprint rules + +```bash +# Subscribe to Microsoft Exchange probing detection +curl -X 'POST' \ + 'https://admin.api.crowdsec.net/v1/fingerprints/microsoft-exchange/integrations' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' \ + -H 'Content-Type: application/json' \ + -d '{"name": "production_firewall"}' +``` + +## Step 4: Monitor New and Trending CVEs + +Check the tracker regularly (or automate it) for new CVEs affecting your stack: + +```bash +# Get the latest detection rules, sorted by release date +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/cves?sort_by=rule_release_date&sort_order=desc&size=20' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' + +# Get the most actively exploited CVEs right now +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/cves?sort_by=trending&sort_order=desc&size=20' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +For each new CVE that affects your products: + +1. Check the **CrowdSec Score** and **Exploitation Phase** +2. Read the **CrowdSec Analysis** for exploitation context +3. Subscribe your integration if the threat warrants immediate blocklist protection +4. Open a patching ticket with the appropriate priority + +## Step 5: Build a Monitoring Script + +Here's a template for a daily check that surfaces new and trending threats for your stack: + +```python +import os +from crowdsec_tracker_api import Cves, ApiKeyAuth + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +auth = ApiKeyAuth(api_key=KEY) +cves_service = Cves(auth=auth) + +# Define your technology stack tags +MY_TAGS = {"wordpress", "cms", "enterprise_software"} + +# Get trending CVEs +response = cves_service.get_cves(page=1, size=50) + +alerts = [] +for cve in response.items: + # Filter for CVEs relevant to your stack + cve_tags = set(getattr(cve, 'tags', []) or []) + if not cve_tags.intersection(MY_TAGS): + continue + + # Flag anything with a meaningful CrowdSec Score + if cve.crowdsec_score >= 4: + alerts.append({ + "cve": cve.name, + "title": cve.title, + "score": cve.crowdsec_score, + "phase": cve.exploitation_phase.label, + "ips": cve.nb_ips, + }) + +# Output alerts (integrate with your notification system) +for alert in sorted(alerts, key=lambda x: x["score"], reverse=True): + print(f"[Score {alert['score']}] {alert['cve']}: {alert['title']}") + print(f" Phase: {alert['phase']}, Active IPs: {alert['ips']}") +``` + +## Step 6: Integrate with Your Security Stack + +The Live Exploit Tracker API can feed data into: + +- **SIEM**: Enrich alerts with CrowdSec Scores and exploitation context. When your SIEM fires an alert for a CVE, automatically look up the CrowdSec intelligence to assign priority. +- **SOAR**: Build playbooks that automatically create blocklist subscriptions when a new high-severity CVE is detected for your products. +- **Vulnerability Management**: Correlate your vulnerability scanner findings with real-world exploitation data to reorder your patch queue. +- **Reporting Dashboards**: Pull scores and phase data into your security dashboard to give leadership a real-time view of the threat landscape. diff --git a/crowdsec-docs/unversioned/tracker_api/guide_triage.mdx b/crowdsec-docs/unversioned/tracker_api/guide_triage.mdx new file mode 100644 index 000000000..4115f97c4 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/guide_triage.mdx @@ -0,0 +1,132 @@ +--- +id: guide_triage +title: "Guide: Triage Workflow" +--- + +## Scenario + +You've received a security alert — your vulnerability scanner flagged a CVE, a vendor published a critical advisory, or your SIEM correlated an event with a known vulnerability. You need to decide: **how urgently should I act?** + +This guide walks through using the Live Exploit Tracker to turn a CVE identifier into an informed triage decision. + +## Step 1: Look Up the CVE + +Navigate to the CVE in the [web interface](https://tracker.crowdsec.net) by searching for its ID (e.g., `CVE-2024-25600`), or query the API: + +```bash +curl -X 'GET' \ + 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600' \ + -H 'accept: application/json' \ + -H 'x-api-key: ${KEY}' +``` + +## Step 2: Read the CrowdSec Score + +The **CrowdSec Score** is your first signal. Think of it as a traffic light: + +| Score | Action | +|-------|--------| +| **0–3** | 🟢 Standard priority. Patch in your normal maintenance window. | +| **4–6** | 🟡 Elevated priority. Move it up in the patch queue. Consider a blocklist. | +| **7–10** | 🔴 Urgent. Escalate immediately. Deploy mitigations now. | + +## Step 3: Understand the Context + +The score alone doesn't tell the full story. Check these fields to understand *why* the score is what it is: + +### Opportunity Score + +- **High (4–5)**: Attackers are deliberately targeting victims. If you see an alert on your systems, take it seriously — someone likely chose to attack you. +- **Low (0–1)**: Mass scanning. You're one of millions being probed. The alert is real but low-signal. + +### Momentum Score + +- **High (4–5)**: Exploitation is surging. A new campaign is underway. Act fast — the threat is getting worse. +- **Low (0–1)**: Activity is declining. The threat is fading, though you should still patch. + +### Exploitation Phase + +- **Mass Exploitation** or **Targeted Exploitation**: The threat is active and real. Treat as urgent. +- **Background Noise**: Ongoing but low-level. Standard patching is appropriate. +- **Unpopular** or **Insufficient Data**: Limited attacker interest. Low urgency. + +## Step 4: Read the CrowdSec Analysis + +The `crowdsec_analysis` field provides a narrative that puts everything in context. It covers: + +- How the vulnerability is being exploited +- Whether attacks are targeted or opportunistic +- How activity is trending +- Specific indicators (URLs, endpoints, payload patterns) + +This is the section you want to include in your incident report or escalation email. + +## Step 5: Check the Attacker IPs + +If you've seen suspicious traffic on your network, check whether the source IPs appear in the tracker: + +1. Go to the CVE detail page and view the **Attacker IPs** section +2. Check whether the IPs hitting your infrastructure match known exploiters +3. Review the CTI data for those IPs: are they known botnets, legitimate scanners, or fresh infrastructure? + +If your attacker IP matches a known exploiter with a `malicious` reputation and attack history, that's strong confirmation of an exploitation attempt. + +## Step 6: Decide and Act + +Based on what you've found: + +| Finding | Recommended Action | +|---------|-------------------| +| High CrowdSec Score + Targeted + Growing | **Emergency patch.** Deploy blocklist immediately. Investigate for compromise. | +| High CrowdSec Score + Mass exploitation | **Urgent patch.** Deploy blocklist. Check all instances of affected software. | +| Moderate score + Background noise | **Prioritize patch** within days, not weeks. Blocklist optional. | +| Low score + Unpopular | **Standard patch** cycle. Monitor for phase changes. | +| Insufficient data | **Fall back to CVSS** and vendor advisory. Check back for updates. | + +## Step 7: Deploy Mitigation (If Needed) + +If the situation calls for immediate mitigation: + +1. **Create a firewall integration** (if you don't have one) — see [Integrations & Blocklists](./api_integrations) +2. **Subscribe it to the CVE** — either via the web interface or API +3. Your firewall will start blocking known attacker IPs automatically + +This buys you time while you schedule and deploy the patch. + +## Automating Triage + +For teams handling many alerts, consider automating the lookup: + +```python +import os +from crowdsec_tracker_api import Cves, ApiKeyAuth + +KEY = os.getenv("CROWDSEC_TRACKER_API_KEY") +auth = ApiKeyAuth(api_key=KEY) +cves_service = Cves(auth=auth) + +def triage_cve(cve_id: str) -> str: + """Return a triage priority based on CrowdSec intelligence.""" + try: + cve = cves_service.get_cve(cve_id) + except Exception: + return "UNKNOWN — CVE not tracked by CrowdSec" + + score = cve.crowdsec_score + phase = cve.exploitation_phase.name + + if score >= 7 or phase in ("mass_exploitation", "targeted_exploitation"): + return f"CRITICAL — Score {score}, Phase: {phase}" + elif score >= 4: + return f"HIGH — Score {score}, Phase: {phase}" + elif score >= 1: + return f"MEDIUM — Score {score}, Phase: {phase}" + else: + return f"LOW — Score {score}, Phase: {phase}" + +# Example usage in a SIEM integration +print(triage_cve("CVE-2024-25600")) +# Output: "CRITICAL — Score 7, Phase: insufficient_data" +``` + +This function can be integrated into your SIEM or SOAR playbook to automatically enrich alerts with CrowdSec intelligence and assign initial priority. diff --git a/crowdsec-docs/unversioned/tracker_api/intro.mdx b/crowdsec-docs/unversioned/tracker_api/intro.mdx deleted file mode 100644 index 0fa84f87a..000000000 --- a/crowdsec-docs/unversioned/tracker_api/intro.mdx +++ /dev/null @@ -1,164 +0,0 @@ ---- -id: intro -title: Introduction ---- - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; - -## What is the Live Exploit Tracker - -The **Live Exploit Tracker** allows you to interact with CrowdSec's Threat Intelligence data, specifically focusing on CVEs and the IPs that exploit them. This enables you to prioritize vulnerabilities based on real-world exploitation data and mitigate threats by integrating IOCs with your existing security infrastructure: firewalls, SIEM, SOAR etc. - -:::info -Live Exploit Tracker can be used via a web interface, or via the RESTful API. -::: - -## What to expect - -The Exploit Tracker API and Web applications allows you to: - - Get information related to specific CVE(s) as observed by the CrowdSec Network, helping you to **prioritize**. - - Get CTI data and IPs actively exploiting a specific CVE(s) for **mitigation** or threat hunting. - - Create and maintain **blocklists** of IPs exploiting specific vulnerabilities that can be easily integrated into most **firewalls**. - -### Prioritize - -For a CVE, get: - - **General CVE information**: Name, Title, Affected Components, CWEs, References, CVSS score, Presence of known public exploit etc. - - Number of IPs actively exploiting the vulnerability. - - **CrowdSec Analysis**: A human readable text covering the most important information about the vulnerability: - - Technical description of the vulnerability - - Relevant information about payload such as targeted URI - - Description of exploitation patterns, from targeted to large-scale opportunistic attacks - - **CrowdSec Scores**: - - CrowdSec Score: A one-size-fits-all score that indicates how a SOC could prioritize a security alert for a given CVE. Generally CVEs where CrowdSec observes strong increases in targeted attacks have a higher score than vulnerabilities which are mainly used by automated mass-scanners in non-sophisticated global campaigns. - - Opportunity Score: A score from 0 to 5 indicating how opportunistic the attackers for a given CVE operate. A score of 0 is given to CVEs where attackers essentially target IPs at random in an automated fashion while a score of 5 is given to CVEs which see precisely targeted exploitation making alerts much more indicative of a dangerous attack campaign targeting your organization. - - Momentum Score: A score from 0 to 5 indicating the how current exploitation volume compares to historical averages for a given CVE. CVEs where we observe below average attack volume (decreasing trend) are given a low score, while CVEs where we see rapidly growing attack volume (increasing trend) are given a high score. - - Exploitation Status: The current exploitation status of the vulnerability, from "early exploitation" to "background noise". - - **Timeline information**: - - First and Last exploitation observed - - CVE Publication date, Detection rule Publication date, CISA KEV addition etc. - - List of general events related to the CVE and its exploitation status. - -### Mitigate - -From a CVE, get related IPs for different usecases: - -**CTI Information** - - List of IPs exploiting the vulnerability over a given period, with [their associated information](https://doc.crowdsec.net/u/cti_api/taxonomy/cti_object), from reputation to known classifications. Allows to differentiate legitimate scanning actors (ie. shodan etc.), well-known attackers and newly deployed infrastructures. - -**Blocklists** - - Create *integrations* allowing blocklist consumption from various firewall vendors. - - Subscribe *integrations* to CVEs, effectively blocking suspicious and malicious IPs known to actively exploit the vulnerability. - -## Web interface - -### Prerequisites - -To access the Exploit Tracker API, you need an API key. Please contact the CrowdSec team to obtain your API key if you haven't already. - -### Access - -Connect to https://let-demo.dev.crowdsec.net/ and put your provided API key in the top right field. - -![Live Exploit Tracker API Key Configuration](/img/exploit-tracker/web-api-key.png) - -## API - -### Prerequisites - -To access the Exploit Tracker API, you need an API key. Please contact the CrowdSec team to obtain your API key if you haven't already. - -:::info -You can use our python SDK: `pip install crowdsec-tracker-api` -::: - -### Authentication - -To interact with the API, you need to configure the authentication using your API key. - -```python -import os -from crowdsec_tracker_api import ApiKeyAuth, Server - -KEY = os.getenv("KEY") - -# Configure Authentication -auth = ApiKeyAuth(api_key=KEY) - -# Define the Server URL -base_url = Server.production_server.value -``` - -## Quick Example: Get CVE Information - -Here is a simple example of how to retrieve information about a specific CVE using the SDK. - - - - -```bash -curl -i -H "x-api-key: ${KEY}" -X GET -H "Content-Type: application/json" \ -https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600 -``` - - - - -```python -import os -from crowdsec_tracker_api import Cves, ApiKeyAuth, Server -from httpx import HTTPStatusError - -KEY = os.getenv("KEY") - -# Configure Authentication -auth = ApiKeyAuth(api_key=KEY) - -# Initialize the Cves service -cves_service = Cves(auth=auth) - -# Get CVE Details -cve_id = "CVE-2024-25600" -try: - cve_details = cves_service.get_cve(cve_id) - print(f"CVE: {cve_details.model_dump_json(indent=2)}") -except HTTPStatusError as e: - print(f"An error occurred: {e.response.status_code} - {e.response.text}") -``` - - - - -
- answer on success - -```json -{ - "cve_id": "CVE-2024-25600", - "description": "Description of the CVE...", - "severity": "High", - "exploit_count": 42, - "first_seen": "2024-01-15T12:34:56Z", - "last_seen": "2024-06-10T08:22:33Z" - ... other fields ... -} -``` - -
- -## Next Steps - -Now you can: - -- Explore the [API Reference](./api_reference) for detailed information on all available endpoints. -- Learn how to use [Prioritize CVEs](./prioritize) based on real-world exploitation -- Discover how to [Mitigate Threats](./mitigate) by integrating with your security appliances. -- Explore the SDK documentation on [GitHub](https://github.com/crowdsecurity/crowdsec-tracker-api-sdk-python) diff --git a/crowdsec-docs/unversioned/tracker_api/mitigate.mdx b/crowdsec-docs/unversioned/tracker_api/mitigate.mdx deleted file mode 100644 index 63ff2e689..000000000 --- a/crowdsec-docs/unversioned/tracker_api/mitigate.mdx +++ /dev/null @@ -1,381 +0,0 @@ ---- -id: mitigate -title: Mitigate ---- - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; - -The **Mitigate** features allow you to take action on the threat intelligence you've gathered. You can create integrations with your security infrastructure (like firewalls) and subscribe them to receive updates about specific CVEs. - -:::info -This page focuses on the API usage, you can also view information from the [web interface](./web_interface) -::: - -## Manage Integrations - -Integrations are the bridge between CrowdSec's data and your security systems. You can create integrations that output data in various formats suitable for different firewalls and remediation components. - -### Create an Integration - -To create an integration, you need to specify its name, type, and output format. - - - - -```bash -curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ -https://admin.api.crowdsec.net/v1/integrations \ --d '{ "name": "test_integration_1", "description": "my test integration", "entity_type": "firewall_integration", "output_format": "plain_text" }' -``` - - - - -```python -import os -from crowdsec_tracker_api import ( - Integrations, - IntegrationCreateRequest, - IntegrationType, - OutputFormat, - Server, - ApiKeyAuth, -) -from httpx import HTTPStatusError - -KEY = os.getenv("KEY") - -# Configure Authentication -auth = ApiKeyAuth(api_key=KEY) - -# Initialize the Integrations service -integrations_service = Integrations(auth=auth) - -# Create the request -request = IntegrationCreateRequest( - name="My Firewall Integration", - description="fetch cves ips lists", - entity_type=IntegrationType.FIREWALL_INTEGRATION.value, - output_format=OutputFormat.PLAIN_TEXT.value, -) - -# Create the integration -try: - response = integrations_service.create_integration(request=request) - print(f"Integration Created: {response.model_dump_json(indent=2)}") -except HTTPStatusError as e: - print(f"An error occurred: {e.response.status_code} - {e.response.text}") -# IMPORTANT: Save the Client Secret securely, it is only shown once! -``` - - - - -### List Integrations - -You can list all your existing integrations to manage them. - - - - -```bash -curl -X 'GET' https://admin.api.crowdsec.net/v1/integrations \ - -H 'accept: application/json' \ - -H 'x-api-key: ${KEY}' -``` - - - - -```python -import os -from crowdsec_tracker_api import ( - Integrations, - Server, - ApiKeyAuth, -) -from httpx import HTTPStatusError - -KEY = os.getenv("KEY") - -# Configure Authentication -auth = ApiKeyAuth(api_key=KEY) - -# Initialize the Integrations service -integrations_service = Integrations(auth=auth) - -try: - response = integrations_service.get_integrations() - - for integration in response.items: - print(integration.model_dump_json(indent=2)) - print("-----") -except HTTPStatusError as e: - print(f"An error occurred: {e.response.status_code} - {e.response.text}") - -``` - - - - -### Update an Integration - -You can update the details of an existing integration, such as its name, description, or regenerate its client secret. - - - - -```bash -curl -X 'PATCH' \ - 'https://admin.api.crowdsec.net/v1/integrations/abcdefgh12345678' \ - -H 'accept: application/json' \ - -H 'x-api-key: ${KEY}' \ - -H 'Content-Type: application/json' \ - -d '{ - "name": "Updated Firewall Integration", - "description": "Updated description for the integration", - "output_format": "plain_text", - "regenerate_credentials": true -}' -``` - - - - -```python -import os -from httpx import HTTPStatusError -from crowdsec_tracker_api import ( - Integrations, - Server, - ApiKeyAuth, - IntegrationUpdateRequest, -) - -KEY = os.getenv("KEY") - -# Configure Authentication -auth = ApiKeyAuth(api_key=KEY) - -# Initialize the Integrations service -integrations_service = Integrations(auth=auth) - -integration_id = "abcdefgh12345678" # Replace with your integration ID -request = IntegrationUpdateRequest( - name="Updated Firewall Integration", - regenerate_credentials=True, - description="Updated description for the integration", -) -try: - response = integrations_service.update_integration( - integration_id=integration_id, - request=request, - ) - print(f"Integration Updated: {response.model_dump_json(indent=2)}") -except HTTPStatusError as e: - print(f"An error occurred: {e.response.status_code} - {e.response.text}") -``` - - - - -### Delete an Integration - -If an integration is no longer needed, you can delete it. - - - - -```bash -curl -X 'DELETE' \ - 'https://admin.api.crowdsec.net/v1/integrations/abcdefgh12345678' \ - -H 'accept: */*' \ - -H 'x-api-key: ${KEY}' -``` - - - - -```python -import os -from httpx import HTTPStatusError -from crowdsec_tracker_api import ( - Integrations, - Server, - ApiKeyAuth, -) - -KEY = os.getenv("KEY") - -# Configure Authentication -auth = ApiKeyAuth(api_key=KEY) - -# Initialize the Integrations service -integrations_service = Integrations(auth=auth) - -# Create the integration -try: - response = integrations_service.delete_integration( - integration_id="abcdefgh12345678" # Replace with your integration ID - ) - print("Integration deleted successfully.") -except HTTPStatusError as e: - print(f"An error occurred: {e.response.status_code} - {e.response.text}") - -``` - - - - -## Subscribe CVE to Integration - -Once you have an integration, you can subscribe it to a specific CVE. This means the integration will receive the list of IPs exploiting that CVE. - - - - -```bash -curl -X 'POST' \ - 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600/integrations' \ - -H 'accept: application/json' \ - -H 'x-api-key: ${KEY}' \ - -H 'Content-Type: application/json' \ - -d '{ - "name": "test_integration_1" -}' -``` - - - - -```python -import os -from crowdsec_tracker_api import ( - Cves, - Server, - ApiKeyAuth, - SubscribeCVEIntegrationRequest, -) -from httpx import HTTPStatusError - -KEY = os.getenv("KEY") - -# Initialize the service -auth = ApiKeyAuth(api_key=KEY) -cves_service = Cves(auth=auth) - -cve_id = "CVE-2024-25600" -integration_name = "My Firewall Integration" # The name of the integration you created - -# Create subscription request -request = SubscribeCVEIntegrationRequest(name=integration_name) - -# Subscribe -try: - response = cves_service.subscribe_integration_to_cve(request=request, cve_id=cve_id) - print(response) -except HTTPStatusError as e: - print(f"An error occurred: {e.response.status_code} - {e.response.text}") -``` - - - - -## Unsubscribe Integration from CVE - -If you no longer want an integration to receive updates for a CVE, you can unsubscribe it. - - - - -```bash -curl -X 'DELETE' \ - 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600/integrations/test_integration_1' \ - -H 'accept: application/json' \ - -H 'x-api-key: ${KEY}' -``` - - - - -```python -import os -from httpx import HTTPStatusError -from crowdsec_tracker_api import ( - Cves, - Server, - ApiKeyAuth, -) - -KEY = os.getenv("KEY") - -# Initialize the service -auth = ApiKeyAuth(api_key=KEY) -cves_service = Cves(auth=auth) - -cve_id = "CVE-2024-25600" -integration_name = "My Firewall Integration" # The name of the integration you created - -# Unsubscribe -try: - response = cves_service.unsubscribe_integration_from_cve( - cve_id=cve_id, integration_name=integration_name - ) - if response is None: - print( - f"Successfully unsubscribed integration '{integration_name}' from CVE '{cve_id}'." - ) -except HTTPStatusError as e: - print(f"An error occurred: {e.response.status_code} - {e.response.text}") - -``` - - - - -## Next Steps - -Now that you have set up integrations and subscribed them to CVEs, you can follow [this documentation guide](https://docs.crowdsec.net/u/integrations/intro) to configure your security appliance based on the integration you created. diff --git a/crowdsec-docs/unversioned/tracker_api/overview.mdx b/crowdsec-docs/unversioned/tracker_api/overview.mdx new file mode 100644 index 000000000..f374f54d6 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/overview.mdx @@ -0,0 +1,66 @@ +--- +id: overview +title: Overview +--- + +## What is the Live Exploit Tracker + +The **Live Exploit Tracker** gives security teams real-time visibility into which vulnerabilities are being actively exploited in the wild, who is exploiting them, and how urgently you need to act. + +Live Exploit Tracker answers the questions that matter during triage: + +- **Is this CVE actually being exploited right now?** Not just theoretically exploitable — are real attackers targeting it today? +- **How worried should I be?** Is this mass scanning noise, or are attackers carefully selecting targets? +- **Is the threat growing or fading?** Should I patch now, or is this yesterday's news? +- **Who is attacking?** What do we know about the IPs involved — are they known botnets, legitimate scanners, or fresh infrastructure? + +The tracker draws on telemetry from the CrowdSec Network — a global community of security practitioners sharing real-time attack signals — to provide exploitation intelligence that goes beyond what traditional vulnerability databases offer. + +## Key Capabilities + +### Prioritize + +Not all CVEs deserve the same urgency. The Live Exploit Tracker provides **three complementary scores** and an **exploitation phase** classification to help you decide where to focus: + +- **CrowdSec Score** (0–10): A composite severity rating that accounts for both attacker sophistication and current momentum. A score of 8 means "this is actively dangerous and demands attention." +- **Opportunity Score** (0–5): How targeted the attacks are. A high score means attackers are carefully selecting victims — an alert on your systems is a serious signal. +- **Momentum Score** (0–5): Whether exploitation is growing, steady, or declining. A high score means a new campaign is likely underway. +- **Exploitation Phase**: Where the CVE sits in its lifecycle — from *insufficient data* through *background noise* to *mass exploitation*. + +Each tracked CVE also includes a **CrowdSec Analysis** — a human-readable intelligence narrative describing the vulnerability, observed exploitation patterns, and specific indicators like targeted endpoints. + +→ [Learn more about Scores & Ratings](./scores) + +→ [Learn more about Exploitation Phases](./exploitation_phases) + +### Mitigate + +Once you've identified a threat, the tracker lets you act on it: + +- **IP Intelligence**: View every IP address observed exploiting a specific CVE or probing a specific product, enriched with CTI data including reputation, geolocation, known classifications, and behavioral history. +- **Firewall Integrations**: Create blocklists that automatically feed malicious IPs into your firewalls (Palo Alto, FortiGate, Cisco, pfSense, OPNsense, and more). Subscribe an integration to one or more CVEs, and the blocklist stays current as new attacker IPs are observed. + +### Beyond CVEs: Reconnaissance Rules + +Not all threats map to a single CVE. The tracker also monitors **Reconnaissance rules** (called "fingerprint rules" in the API) — detection patterns for product-level probing activity. For example, "Microsoft Exchange Probing" catches reconnaissance targeting Exchange servers regardless of which specific vulnerability the attacker intends to exploit. + +→ [Learn more about Reconnaissance Rules vs CVEs](./fingerprints_vs_cves) + +## How to Access + +The Live Exploit Tracker is available through two interfaces: + +- **[Web Interface](https://tracker.crowdsec.net)**: A dashboard for browsing CVEs, viewing timelines and attacker IPs, managing integrations, and reading CrowdSec Analysis reports. Ideal for SOC analysts and security managers. +- **[REST API](/tracker_api/api_authentication)**: Programmatic access for automation, SIEM/SOAR integration, and custom tooling. A [Python SDK](https://github.com/crowdsecurity/crowdsec-tracker-api-sdk-python) is also available. + +Both interfaces require an API key. Contact the CrowdSec team to obtain yours if you haven't already. + +## Next Steps + +| I want to... | Start here | +|---|---| +| Understand what the scores mean | [Scores & Ratings](./scores) | +| Browse CVEs and assess threats | [Web Interface Guide](./web_interface) | +| Automate with the API | [API Authentication & Setup](./api_authentication) | +| Block attacker IPs on my firewall | [Integrations & Blocklists](./api_integrations) | +| Investigate a specific alert | [Triage Workflow Guide](./guide_triage) | diff --git a/crowdsec-docs/unversioned/tracker_api/prioritize.mdx b/crowdsec-docs/unversioned/tracker_api/prioritize.mdx deleted file mode 100644 index dd6dcd264..000000000 --- a/crowdsec-docs/unversioned/tracker_api/prioritize.mdx +++ /dev/null @@ -1,165 +0,0 @@ ---- -id: prioritize -title: Prioritize ---- - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; - -The **Prioritize** features allow you to assess the threat level of vulnerabilities by providing visibility into which CVEs are actively being exploited and by whom. - -:::info -This page focuses on the API usage, you can also view information from the [web interface](./web_interface) -::: - -## List Tracked CVEs - -You can retrieve a paginated list of all CVEs that CrowdSec is currently tracking. This helps you identify which vulnerabilities in your environment might be under active exploitation. - - - - -```bash -curl -X 'GET' \ - 'https://admin.api.crowdsec.net/v1/cves?page=1&size=50' \ - -H 'accept: application/json' \ - -H 'x-api-key: ${KEY}' -``` - - - - -```python -import os -from crowdsec_tracker_api import Cves, Server, ApiKeyAuth -from httpx import HTTPStatusError - -KEY = os.getenv("KEY") - -# Initialize the service -auth = ApiKeyAuth(api_key=KEY) -cves_service = Cves(auth=auth) - -# Get list of CVEs -try: - response = cves_service.get_cves(page=1, size=50) - - for cve in response.items: - print(cve.model_dump_json(indent=2)) - print("-----") -except HTTPStatusError as e: - print(f"An error occurred: {e.response.status_code} - {e.response.text}") - -``` - - - - -## Get CVE Details - -Get detailed information about a specific CVE, including its description and CVSS score. - - - - -```bash -curl -X 'GET' \ - 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600' \ - -H 'accept: application/json' \ - -H 'x-api-key: ${KEY}' -``` - - - - -```python -import os -from crowdsec_tracker_api import Cves, ApiKeyAuth, Server -from httpx import HTTPStatusError - -KEY = os.getenv("KEY") - -# Configure Authentication -auth = ApiKeyAuth(api_key=KEY) - -# Initialize the Cves service -cves_service = Cves(auth=auth) - -# Get CVE Details -cve_id = "CVE-2024-25600" -try: - cve_details = cves_service.get_cve(cve_id) - print(f"CVE: {cve_details.model_dump_json(indent=2)}") -except HTTPStatusError as e: - print(f"An error occurred: {e.response.status_code} - {e.response.text}") -``` - - - - -## Get IPs Targeting a CVE - -One of the most powerful features is the ability to see the IP addresses that are actively exploiting a specific CVE. This information allows you to block these IPs immediately. - - - - -```bash -curl -X 'GET' \ - 'https://admin.api.crowdsec.net/v1/cves/CVE-2024-25600/ips?page=1&size=50' \ - -H 'accept: application/json' \ - -H 'x-api-key: ${KEY}' -``` - - - - -```python -import os -from crowdsec_tracker_api import Cves, ApiKeyAuth, Server -from httpx import HTTPStatusError - -KEY = os.getenv("KEY") - -# Configure Authentication -auth = ApiKeyAuth(api_key=KEY) - -# Initialize the Cves service -cves_service = Cves(auth=auth) - -# Get CVE Details -cve_id = "CVE-2024-25600" -try: - response = cves_service.get_cve_ips(cve_id, page=1, size=10) -except HTTPStatusError as e: - print(f"An error occurred: {e.response.status_code} - {e.response.text}") - -for ip in response.items: - print(ip.model_dump_json(indent=2)) - print("-----") - -``` - - - diff --git a/crowdsec-docs/unversioned/tracker_api/scores.mdx b/crowdsec-docs/unversioned/tracker_api/scores.mdx new file mode 100644 index 000000000..6960af4d3 --- /dev/null +++ b/crowdsec-docs/unversioned/tracker_api/scores.mdx @@ -0,0 +1,103 @@ +--- +id: scores +title: Scores & Ratings +--- + +## Overview + +The Live Exploit Tracker assigns multiple scores to each tracked CVE and fingerprint rule. These scores are derived from real-world exploitation telemetry observed across the CrowdSec Network — they reflect what attackers are *actually doing*, not what's theoretically possible. + +Three scores work together to give you a complete picture: + +- **CrowdSec Score**: The headline number — how urgently should you care? +- **Opportunity Score**: Are attacks targeted or opportunistic? +- **Momentum Score**: Is exploitation growing or fading? + +These are complemented by an **Exploitation Phase** (covered in [its own page](./exploitation_phases)) and supplementary scores described below. + +## CrowdSec Score (0–10) + +The CrowdSec Score is a composite rating designed to answer one question: **how should a SOC prioritize a security alert for this CVE?** + +It combines the Opportunity and Momentum scores along with additional signals. Generally, CVEs where CrowdSec observes targeted attacks with increasing volume score higher than vulnerabilities used only by automated mass-scanners. + +| Score | Interpretation | Recommended Action | +|-------|---------------|-------------------| +| **0** | No observed exploitation or insufficient data | Monitor. Low priority for immediate action. | +| **1–3** | Background noise — opportunistic, automated scanning | Patch within your standard maintenance window. Alerts are likely low-signal. | +| **4–6** | Active exploitation with moderate targeting or momentum | Prioritize patching. Consider deploying a blocklist for affected CVEs. | +| **7–8** | Significant targeted exploitation, often with growing trend | Urgent patching recommended. Deploy blocklists. Investigate any alerts on your infrastructure. | +| **9–10** | Critical active campaign — highly targeted and rapidly growing | Emergency response. Immediate mitigation required. Treat alerts as confirmed incidents. | + +:::tip Practical example +At the time of writing, CVE-2026-1731 (BeyondTrust Remote Support RCE) has a CrowdSec Score of **9**, with an Opportunity Score of 5 and Momentum Score of 3. This tells you: attackers are deliberately targeting this vulnerability with high precision (not just scanning randomly), activity is above average, and any alert on your systems should be treated as a confirmed incident requiring immediate response. + +Compare with CVE-2021-44228 (Log4Shell), which currently has a CrowdSec Score of **3** with Opportunity 1 and Momentum 2. Despite its legendary CVSS 10.0, it has settled into background noise — opportunistic scanning at average volume. Patch it, but it doesn't need to jump the queue anymore. + +*Scores are computed from live telemetry and change over time. The values shown here may differ from what you see today.* +::: + +## Opportunity Score / Targeted (0–5) + +The Opportunity Score measures **how targeted the exploitation is**. It answers: "If I see an alert for this CVE on my network, does that mean someone picked *me* specifically, or am I just caught in a spray-and-pray campaign?" + +:::info Terminology +This score is called **Targeted** in the web interface (with the subtitle "Low = mass scanning, High = targeted") and **opportunity_score** in the API. They represent the same metric. +::: + +| Score | Label | What It Means | Alert Significance | +|-------|-------|--------------|-------------------| +| **0** | Mass scanning | Attackers are hitting IPs at random in automated sweeps. | Low — you're one of millions being scanned. | +| **1** | Mostly opportunistic | Largely automated, with minimal target selection. | Low to moderate. | +| **2** | Opportunistic with some targeting | Mix of automated campaigns and light reconnaissance. | Moderate — worth investigating. | +| **3** | Mixed | Significant portion of attacks show target selection. | Moderate to high. | +| **4** | Targeted | Attackers are performing reconnaissance before exploitation. Campaigns are tailored. | High — an alert likely means deliberate targeting. | +| **5** | Highly targeted | Precisely targeted exploitation. Attackers select specific victims based on exposure and configuration. | Very high — treat as a deliberate attack on your organization. | + +:::info Why this matters +A CVSS 10.0 vulnerability with an Opportunity Score of 0 might generate thousands of alerts across the internet but pose less real danger to any specific organization than a CVSS 7.5 vulnerability with an Opportunity Score of 5, where every alert represents a deliberate attack campaign. +::: + +## Momentum Score (0–5) + +The Momentum Score tracks **how current exploitation volume compares to historical averages**. It answers: "Is this threat growing, stable, or fading?" + +| Score | Label | What It Means | Implication | +|-------|-------|--------------|------------| +| **0** | Declining / dormant | Exploitation is well below historical levels or has stopped entirely. | Patch at normal cadence. Threat is receding. | +| **1** | Below average | Activity is lower than typical. | Reduced urgency. | +| **2** | Average | Consistent with long-term trends. | Steady-state — no special urgency beyond the base score. | +| **3** | Above average | Noticeable uptick in exploitation activity. | Increased urgency. May indicate renewed attacker interest. | +| **4** | Growing rapidly | Significant increase in volume week-over-week. | High urgency. A new campaign is likely underway. | +| **5** | Surging | Explosive growth in exploitation activity. | Critical. Active mass campaign or newly weaponized exploit. | + +:::tip Reading Momentum alongside Opportunity +The combination tells you different stories: + +- **High Momentum + Low Opportunity** = A new automated scanning campaign has launched. Lots of noise, but individual alerts are low-signal. +- **High Momentum + High Opportunity** = A targeted attack campaign is ramping up. This is the most dangerous combination. +- **Low Momentum + High Opportunity** = Persistent, targeted attacks at steady volume. The threat is real but stable — no immediate spike to react to. +- **Low Momentum + Low Opportunity** = Background noise is fading. Lowest priority. +::: + +## Adjustment Score + +The Adjustment Score provides **transparent corrections** applied to the composite CrowdSec Score. + +| Component | Description | +|-----------|------------| +| **recency** | A bonus applied when vulnerability release is very recent. A CVE gets a small boost to its total score shortly after release to account for uncertainty in the scores due to a lack of historic data. | +| **total** | The net adjustment applied to the score. | + +These adjustments are surfaced so you can understand *why* a score is what it is. For example, if a CVE has a CrowdSec Score of 6 with an adjustment_score.recency of +1, you know that 1 point of that score comes from very recent CVE release rather than long-term exploitation data. + +## CVSS Score + +The Live Exploit Tracker also surfaces the standard **CVSS score** from the National Vulnerability Database. This measures the *theoretical* severity of a vulnerability based on its technical characteristics (attack vector, complexity, impact, etc.). + +The CrowdSec Score and CVSS score often diverge, and that's the point: + +- A CVSS 10.0 vulnerability that nobody is actually exploiting might have a CrowdSec Score of 0. +- A CVSS 5.4 vulnerability that sophisticated attackers are actively targeting might have a CrowdSec Score of 6 or higher. + +**Use CVSS for understanding the vulnerability's potential impact. Use the CrowdSec Score for prioritizing your response based on what's happening in the real world.** diff --git a/crowdsec-docs/unversioned/tracker_api/web_interface.mdx b/crowdsec-docs/unversioned/tracker_api/web_interface.mdx index 3aaf7916d..ba96e2b61 100644 --- a/crowdsec-docs/unversioned/tracker_api/web_interface.mdx +++ b/crowdsec-docs/unversioned/tracker_api/web_interface.mdx @@ -3,32 +3,234 @@ id: web_interface title: Web Interface --- -## Objective +## Overview -The [Web Interface of Live Exploit Tracker](https://let-demo.dev.crowdsec.net/) allows you to consume the API in a more human friendly way, and exposes the same features. +The [Live Exploit Tracker web interface](https://tracker.crowdsec.net) provides a dashboard for browsing tracked vulnerabilities, assessing their severity, viewing attacker IPs, and managing firewall integrations — all without writing a line of code. - - View CVEs information: timeline, activity trends, related IPs. - - Mitigate exploitation attempts by preemptively blocking IPs known to exploit given vulnerabilitilies. +It exposes the same data as the [API](./api_authentication) in a visual format designed for SOC analysts and security managers. -## Prioritize +### Getting Access -The prioritize feature allows you to list or search tracked CVEs, and view detailed CVEs information: +To access the web interface, you need an API key. Contact the CrowdSec team to obtain yours if you haven't already. -![Live Exploit Tracker API Key Configuration](/img/exploit-tracker/prioritize_web.png) +Once you have your key, navigate to [https://tracker.crowdsec.net](https://tracker.crowdsec.net) and open **Settings** from the left sidebar to enter your API key. -## Mitigate +## Navigation -From a CVE page, you are able to view IPs exploiting the vulnerability: +The web interface is organized around a left sidebar with six sections: -![Mitigate CVE IP List](/img/exploit-tracker/prioritize_iplist.png) +| Section | Purpose | +|---|---| +| **Home** | Landing page with key stats, trending threats, and most active CVEs | +| **Explore** | Browse and search all tracked CVEs and Reconnaissance rules | +| **Vendors** | Browse affected vendors and their exposure across the threat landscape | +| **Integrations** | Create and manage firewall integrations for automated IP blocking | +| **Activity** | View recent exploitation activity | +| **Bookmarks** | Quick access to CVEs, Reconnaissance rules, and vendors you've bookmarked | -You can subscribe a firewall integration to a CVE, blocking IPs exploiting that vulnerability: +## Home -![Subscribe to CVE](/img/exploit-tracker/mitigate_subscribe_web.png) +The home page provides an at-a-glance overview of the threat landscape: -## Firewall Integrations +- **Key statistics**: Total CVEs tracked, Reconnaissance rules active, and vendors monitored +- **Search**: Search across CVEs, products, or reconnaissance patterns from a single search bar +- **Trending Threats**: CVEs with the highest activity in the last 24 hours, shown as cards with exploitation phase badges, CrowdSec Scores, first-seen dates, IP counts, and sparkline activity charts +- **Most Active**: CVEs with the highest overall volume of attack traffic -The firewall integration page lets you view and create integrations: +Each threat card shows the exploitation phase as a colored badge (e.g., "TARGETED EXPLOITATION", "MASS EXPLOITATION", "BACKGROUND NOISE"), the CrowdSec Score, and a miniature activity chart so you can quickly spot trends. -![Integrations page](/img/exploit-tracker/firewall_integration_web.png) +![Live Exploit Tracker Home Page](/img/exploit-tracker/home.png) +## Explore + +The Explore page is the main interface for browsing and searching all tracked threats. It has two tabs: + +### CVEs Tab + +Displays all tracked CVEs as a grid of cards. Each card shows: + +- **CVE badge and ID** (e.g., `CVE-2022-38840`) +- **Title** (e.g., "Gucralp - XXE") +- **Product** affected +- **Last seen** date +- **CrowdSec Score** (0–10) +- **Active IPs** count +- **Activity sparkline** showing recent exploitation trend +- **Bookmark** icon to save for quick access + +Use the **search bar** to find CVEs by ID, name, product, or vendor. Use the **Sort by** dropdown to order results by Trending (highest CrowdSec Score), Most IPs, newest, or alphabetically. + +![Explore CVEs](/img/exploit-tracker/explore_cves.png) + +### Reconnaissance Tab + +Displays all Reconnaissance rules — detection patterns for product-level probing activity. See [Fingerprints vs CVEs](./fingerprints_vs_cves) for the difference between CVEs and Reconnaissance rules. + +Cards use the same layout as CVEs but with a "RECON" badge and a rule ID (e.g., `microsoft-exchange`). Titles follow the pattern "[Product] Probing" (e.g., "Matomo Panel Probing", "Oracle Enterprise Manager Console Probing"). + +:::info +Reconnaissance rules are called "fingerprint rules" in the API. The web interface and API expose the same data — only the terminology differs. +::: + +![Explore Reconnaissance Rules](/img/exploit-tracker/explore_recon.png) + +## CVE Detail Page + +Clicking on a CVE card opens its full detail page. + +![CVE Detail Page — Header, Scores, Analysis and Timeline](/img/exploit-tracker/cve_detail_top.png) + +### Header + +The top of the page shows: + +- **Phase badge**: The current exploitation phase as a colored label (e.g., "TARGETED EXPLOITATION") +- **CVE ID badge** and **PUBLIC EXPLOIT** indicator (if a public exploit exists) +- **Title**: Human-readable vulnerability name +- **Key dates**: Published, First Seen, Last Seen +- **Reported IPs**: Total count of attacker IPs (linked to the Active Attackers section) +- **CVSS score** +- **Affected product and vendor** +- **Tags**: Technology categories (e.g., `iot`, `cms`, `enterprise_software`) +- **Bookmark** and **Subscribe to Firewall** buttons in the top right + +### Scores Panel + +A dedicated panel on the right side of the header displays: + +- **CrowdSec Score** (0–10) with a severity label (e.g., "CRITICAL", "HIGH") +- **Momentum** (0–5): How fast attacks are growing. Shown with a progress bar. +- **Targeted** (0–5): How targeted vs. opportunistic the attacks are ("Low = mass scanning, High = targeted"). Shown with a progress bar. + +See [Scores & Ratings](./scores) for detailed interpretation of these values. + +:::info Terminology note +The **Targeted** score in the web interface corresponds to the **Opportunity Score** in the API. They measure the same thing — how deliberately attackers are selecting their targets. +::: + +### Description and CrowdSec Analysis + +Displayed side by side below the header: + +- **Description**: The official CVE description from the NVD +- **CrowdSec Analysis**: A human-readable intelligence narrative covering the vulnerability's nature, observed exploitation patterns, trend analysis, and specific technical indicators. Click "Show more" to expand the full analysis. + +See [CrowdSec Analysis](./crowdsec_analysis) for how to use this in triage and reporting. + +### Exploit Timeline + +An interactive chart showing exploitation activity over time. Toggle between **7D** (last 7 days) and **30D** (last 30 days) views. The Y-axis shows the number of distinct IPs observed, and the X-axis shows time. + +Use this to spot: +- Sudden spikes indicating a new campaign launching +- Sustained plateaus indicating persistent attacker interest +- Declining trends indicating the threat is fading + +![CVE Detail Page — Events, Active Attackers and Remediation](/img/exploit-tracker/cve_detail_bottom.png) + +### Key Events + +A table of significant events in the CVE's lifecycle: + +| Event | Description | +|---|---| +| **CVE Published** | When the vulnerability was disclosed in the NVD | +| **Rule Released** | When CrowdSec deployed a detection rule for this CVE | +| **CrowdSec First Seen** | When CrowdSec first observed real-world exploitation | + +### Active Attackers + +A list of IP addresses observed exploiting this CVE over the last 3 months. Each IP card shows: + +- **IP address** +- **Reputation badge**: "MALICIOUS", "SUSPICIOUS", etc. +- **Country flag and code** +- **ASN** (Autonomous System Number) and network name + +Click "Show more" to expand the full list. + +#### Attacker Insights + +Click the Attacker Insights icon to open a detailed analytics modal that provides aggregate intelligence across all IPs exploiting this CVE: + +![Attacker Insights Modal](/img/exploit-tracker/attacker_insights.png) + +- **Reputation breakdown**: Donut chart showing the proportion of Malicious vs. Suspicious IPs +- **Top Countries**: Pie chart of the most common source countries +- **Top Networks**: Bar chart of the most common hosting providers and ASNs +- **Classifications**: Radar chart showing attacker categories (e.g., "Data Center IP", "HTTP Exploit Activity", "High Background Noise", "CrowdSec Intelligence") +- **Also Targeted By These IPs**: A cross-correlation showing which other CVEs are being exploited by the same set of attackers — useful for identifying broader campaigns + +### Related Weaknesses + +The CWE (Common Weakness Enumeration) classifications associated with this CVE, with descriptions. Click through for more information about the weakness class. + +### Remediation & Protection + +Three action cards at the bottom of the detail page: + +| Action | Description | +|---|---| +| **IP Blocklist** — Download | Download a plain text list of attacker IPs (one per line) for manual import into security tools | +| **Firewall Integration** — Subscribe | Subscribe a firewall integration to this CVE for automatic, ongoing IP blocking | +| **IPs Intelligence** — Download JSON | Download full CTI details for all attacker IPs as a JSON file for analysis or SIEM import | + +## Vendors + +The Vendors page lets you browse and compare vendor exposure across the global exploit landscape. + +Each vendor card displays: + +- **Vendor name and logo** +- **CVE count**: Number of tracked CVEs affecting this vendor's products +- **Recon count**: Number of Reconnaissance rules detecting probing of this vendor's products +- **IPs**: Total number of attacker IPs observed targeting this vendor +- **Bookmark** icon + +Use the **search bar** to find a specific vendor and the **Sort by** dropdown to order by Most IPs, Most CVEs, or alphabetically. + +Clicking a vendor card shows all CVEs and Reconnaissance rules affecting their products. + +![Vendors Page](/img/exploit-tracker/vendors.png) + +## Integrations + +The Integrations page is where you create and manage connections to your firewall infrastructure for automated IP blocking. + +Each integration card shows: + +- **Name** and **type** (e.g., "Firewall · Check Point", "Firewall · FortiGate", "Firewall · Palo Alto") +- **Vendor icon** matching the firewall type +- **Subscription counts**: How many CVEs and Recon rules are subscribed +- **IPs**: How many IPs the integration's blocklist currently contains +- **Subscription count** and **last pulled** status + +### Creating an Integration + +1. Click **+ NEW INTEGRATION** in the top right +2. Choose a name and select the output format matching your firewall vendor +3. Save the integration and **securely store the generated credentials** — they are only shown once + +### Subscribing to CVEs and Reconnaissance Rules + +There are two ways to subscribe: + +**From the CVE/Recon detail page**: Click the **SUBSCRIBE TO FIREWALL** button in the top right of any CVE or Reconnaissance rule detail page, then select the integration to subscribe. + +**From the Remediation & Protection section**: Scroll to the bottom of a CVE detail page and click **Subscribe** under the Firewall Integration card. + +The integration's blocklist will now include all IPs observed exploiting that CVE or matching that Reconnaissance rule. As new IPs are observed, they are automatically added. + +### Consuming the Blocklist + +Your firewall fetches the blocklist from the integration's unique URL at regular intervals. See the [CrowdSec Integrations documentation](https://docs.crowdsec.net/u/integrations/intro) for vendor-specific setup guides. + +![Integrations Page](/img/exploit-tracker/integrations.png) + +## Bookmarks + +The Bookmarks page provides quick access to CVEs, Reconnaissance rules, and vendors you've bookmarked. Click the bookmark icon on any card throughout the interface to save it here. + +## Activity + +The Activity page shows recent exploitation activity across all tracked threats, providing a feed of notable events and changes.