diff --git a/crowdsec-docs/docusaurus.config.ts b/crowdsec-docs/docusaurus.config.ts index fb3c0a9a8..e5dbc3234 100644 --- a/crowdsec-docs/docusaurus.config.ts +++ b/crowdsec-docs/docusaurus.config.ts @@ -187,6 +187,13 @@ const redirects = [ { from: "/docs/next/troubleshooting", to: "/u/troubleshooting/intro" }, { from: "/docs/faq", to: "/u/troubleshooting/intro" }, { from: "/docs/next/faq", to: "/u/troubleshooting/intro" }, + // Service API docs flattened: quickstart/ -> + { from: "/u/console/service_api/quickstart/authentication", to: "/u/console/service_api/authentication" }, + { from: "/u/console/service_api/quickstart/blocklists", to: "/u/console/service_api/blocklists" }, + { from: "/u/console/service_api/quickstart/allowlists", to: "/u/console/service_api/allowlists" }, + { from: "/u/console/service_api/quickstart/integrations", to: "/u/console/service_api/integrations" }, + { from: "/u/console/service_api/quickstart/decisions", to: "/u/console/service_api/decisions" }, + { from: "/u/console/service_api/quickstart/metrics", to: "/u/console/service_api/metrics" }, { from: "/docs/next/getting_started/install_crowdsec", to: "/u/getting_started/installation/linux", diff --git a/crowdsec-docs/sidebarsUnversioned.ts b/crowdsec-docs/sidebarsUnversioned.ts index cd7bd4838..9607eb175 100644 --- a/crowdsec-docs/sidebarsUnversioned.ts +++ b/crowdsec-docs/sidebarsUnversioned.ts @@ -550,27 +550,12 @@ const sidebarsUnversionedConfig: SidebarConfig = { tag: "premium", }, items: [ - { - type: "category", - label: "Quickstart", - items: [ - "console/service_api/quickstart/authentication", - "console/service_api/quickstart/blocklists", - "console/service_api/quickstart/integrations", - "console/service_api/quickstart/allowlists", - "console/service_api/quickstart/metrics", - ], - }, - { - type: "doc", - label: "Blocklists", - id: "console/service_api/blocklists", - }, - { - type: "doc", - label: "Integrations", - id: "console/service_api/integrations", - }, + "console/service_api/authentication", + "console/service_api/blocklists", + "console/service_api/allowlists", + "console/service_api/integrations", + "console/service_api/decisions", + "console/service_api/metrics", { type: "category", label: "SDKs", diff --git a/crowdsec-docs/unversioned/console/service_api/quickstart/allowlists.mdx b/crowdsec-docs/unversioned/console/service_api/allowlists.mdx similarity index 99% rename from crowdsec-docs/unversioned/console/service_api/quickstart/allowlists.mdx rename to crowdsec-docs/unversioned/console/service_api/allowlists.mdx index 39b9334c4..cea4c2720 100644 --- a/crowdsec-docs/unversioned/console/service_api/quickstart/allowlists.mdx +++ b/crowdsec-docs/unversioned/console/service_api/allowlists.mdx @@ -223,7 +223,7 @@ print(response) - - [Redoc method link](https://admin.api.dev.crowdsec.net/v1/docs#tag/Allowlists/operation/createAllowlistItems) + - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Allowlists/operation/createAllowlistItems) :::note diff --git a/crowdsec-docs/unversioned/console/service_api/quickstart/authentication.mdx b/crowdsec-docs/unversioned/console/service_api/authentication.mdx similarity index 100% rename from crowdsec-docs/unversioned/console/service_api/quickstart/authentication.mdx rename to crowdsec-docs/unversioned/console/service_api/authentication.mdx diff --git a/crowdsec-docs/unversioned/console/service_api/blocklists.md b/crowdsec-docs/unversioned/console/service_api/blocklists.md deleted file mode 100644 index 902768448..000000000 --- a/crowdsec-docs/unversioned/console/service_api/blocklists.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -id: blocklists -title: Blocklists ---- - -## Introduction - -the `blocklists` feature of the service API allows you to create, populate, subscribe to and share blocklists. - -## Populating blocklists - -When populating blocklists, two strategies are currently available: - - [`/upload`](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/uploadBlocklistContent) allows you to replace the existing content of the blocklist. - - [`/ips`](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/addIpsToBlocklist) and [`/ips/delete`](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/deleteIpsFromBlocklist) allow you to perform incremental changes on the blocklist by adding or removing IPs by batches. - -## Blocklist subscription mechanism - -When [subscribing to blocklists](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/subscribeBlocklist), you can use various `entity_type` : - - - A [Security Engine](https://doc.crowdsec.net/docs/next/intro) (entity_type `engine`). [Remediation Components (Bouncers)](https://doc.crowdsec.net/u/bouncers/intro) connected to it will benefit of the blocklist - - A [Firewall Integration](/u/integrations/intro) (entity_type `firewall_integration`). This allows to use blocklists directly on your existing Firewall Appliances (CISCO, F5, Palo Alto etc.) without having to install a Security Engine or "Bouncer". - - A [Remediation Component](https://doc.crowdsec.net/u/bouncers/intro) (entity_type `remediation_component_integration`). This allows to use a "Bouncer" directly without having to deploy a Security Engine. - - You can as well subscribe via a `tag` (entity_type `tag`). This means that future Security Engines associated to this tag will **automatically** be subscribed to the blocklist. - - You can also subscribe via an `org` directly. This means that future Security Engines enrolled in this org will **automatically** be subscribed to the blocklist. - -## Sharing private blocklists with other organizations - -The [`/blocklists/{blocklist_id}/shares`](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/shareBlocklist) endpoint allows you to share a private blocklist with other organizations. - -When sharing your blocklist with another organization, decide the `permission` you give them on your blocklist: - - `read` : they can subscribe to the blocklist, download its content and view the blocklist(s) statistics. - - `write` : they can add and remove IPs - -## Statistics Explained - -The statistics provided when you query the [`GET /blocklists/{blocklist_id}`](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/getBlocklist) endpoint are divided into two sections. The `stats` section contains basic information about the blocklists itself, like how many IPs it contains and how this count changes over time. The `content_stats` section contains detailed stats about the IPs currently in the blocklist, such as the top AS represented and so on. - - `stats.content_stats.total_seen`: Number of IPs that were seen by the Crowdsec network - - `stats.content_stats.total_fire`: Number of IPs that are currently in the Crowdsec Community Blocklist - - `stats.content_stats.total_seen_1m`: Number of IPs that were seen by the Crowdsec network in the past 30 days - - `stats.content_stats.total_in_other_lists`: Number of IPs that are also present in other public blocklists - - `stats.content_stats.total_false_positive`: Number of false positives (cdns, scanners etc.) identified by Crowdsec in the blocklist. Note that we automatically remove false positives in blocklists provided by Crowdsec, so this field will only be non-zero for custom blocklists. - - `stats.content_stats.false_positive_removed_by_crowdsec`: Number of false positives our system removed from the blocklist - - `stats.content_stats.most_present_behaviors`: Array containing the top 10 most seen behaviors (`http:exploit`, `ssh:bruteforce` etc.) for IPs in the blocklist - - `stats.content_stats.most_present_categories`: Array containing the top 10 most seen categories (insecure_services etc.) for IPs in the blocklist - - `stats.content_stats.most_present_scenarios`: Array containing the top 10 scenarios which IPs in the blocklist were reported for. This only displays scenarios that are publicly available in our hub. - - `stats.content_stats.top_as`: Array containing the top 10 autonomous systems (AS) for IPs in the blocklist - - `stats.content_stats.top_attacking_countries`: Array containing the top 10 countries of origin for IPs in the blocklist - - `stats.content_stats.top_ips`: Array containing the top 10 most reported IPs in the blocklist - - `stats.addition_2days`: Number of IPs added to the blocklist over the last 2 days - - `stats.addition_month`: Number of IPs added to the blocklist over the last 30 days - - `stats.suppression_2days`: Number of IPs removed (by expiration) over the last 2 days - - `stats.suppression_month`: Number of IPs removed (by expiration) over the last 30 days - - `stats.change_2days_percentage`: Percentage of IPs in blocklist that were changed (added or deleted) in the last 2 days - - `stats.change_month_percentage`: Percentage of IPs in blocklist that were changed (added or deleted) in the past month - - `stats.count`: Number of IPs in the blocklist - - `stats.updated_at`: When these stats were last computed diff --git a/crowdsec-docs/unversioned/console/service_api/blocklists.mdx b/crowdsec-docs/unversioned/console/service_api/blocklists.mdx new file mode 100644 index 000000000..0d7ac9747 --- /dev/null +++ b/crowdsec-docs/unversioned/console/service_api/blocklists.mdx @@ -0,0 +1,362 @@ +--- +id: blocklists +title: Blocklists +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +:::info + - We're assuming your API key is set in the environment variable `$KEY` with the necessary permissions. +::: + +The `blocklists` feature of the Service API lets you create, populate, subscribe to and share blocklists. + +## Create a blocklist + +> Create a new private blocklist named `my_test_blocklist`. + + + + +```bash +curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ +https://admin.api.crowdsec.net/v1/blocklists \ +-d '{ "name":"my_test_blocklist", "description": "testing blocklists feature" }' +``` + + + + +```python +import os + +KEY = os.getenv('KEY') + +from crowdsec_service_api import ( + Blocklists, + Server, + ApiKeyAuth, +) +from crowdsec_service_api.models import BlocklistCreateRequest + +auth = ApiKeyAuth(api_key=KEY) +client = Blocklists(base_url=Server.production_server.value, auth=auth) +request = BlocklistCreateRequest( + name='my_test_blocklist', + description='testing blocklists feature', +) +response = client.create_blocklist(request=request) +print(response) +``` + + + + + - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/createBlocklist) + +:::info +The `id` element of the response payload is the identifier used by all future operations targeting this blocklist. +::: + +## Populate the blocklist + +Two strategies are available to fill a blocklist: + +- [`/ips`](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/addIpsToBlocklist) and + [`/ips/delete`](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/deleteIpsFromBlocklist) + perform incremental changes by adding or removing IPs in batches. +- [`/upload`](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/uploadBlocklistContent) + replaces the entire content of the blocklist in one call. + +> Add IPs `1.2.3.4` and `5.6.7.8` to the blocklist for the next 24h. + + + + +```bash +curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ +https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID/ips \ +-d '{ "ips": ["1.2.3.4", "5.6.7.8"], "expiration": "'`date --date='tomorrow' '+%FT%T'`'"}' +``` + + + + +```python +import os +from datetime import datetime, UTC, timedelta + +KEY = os.getenv('KEY') +EXPIRATION = datetime.now(UTC) + timedelta(days=1) + +from crowdsec_service_api import ( + Blocklists, + Server, + ApiKeyAuth, +) +from crowdsec_service_api.models import BlocklistAddIPsRequest + +auth = ApiKeyAuth(api_key=KEY) +client = Blocklists(base_url=Server.production_server.value, auth=auth) +request = BlocklistAddIPsRequest( + ips=["1.2.3.4", "5.6.7.8"], + expiration=EXPIRATION, +) +response = client.add_ips_to_blocklist(request=request, blocklist_id='1234MYBLOCKLISTID') +print(response) +``` + + + + + - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/addIpsToBlocklist) + +:::note +The `expiration` field is mandatory and indicates when the IP should be removed from the blocklist. +::: + +### Download blocklist content + + + + +```bash +curl -i -H "x-api-key: ${KEY}" https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID/download +``` + + + + +```python +import os + +KEY = os.getenv('KEY') + +from crowdsec_service_api import ( + Blocklists, + Server, + ApiKeyAuth, +) +auth = ApiKeyAuth(api_key=KEY) +client = Blocklists(base_url=Server.production_server.value, auth=auth) +response = client.download_blocklist_content(blocklist_id='1234MYBLOCKLISTID') +print(response) +``` + + + + +
+ answer on success +```text +1.2.3.4 +5.6.7.8 +``` +
+ +## Subscribe to a blocklist + +Subscribing an entity to a blocklist makes that entity pull and enforce the list. The `entity_type` +field selects what you target: + +- A [Security Engine](https://doc.crowdsec.net/docs/next/intro) (`engine`). [Remediation Components (Bouncers)](https://doc.crowdsec.net/u/bouncers/intro) connected to it enforce the blocklist. +- A [Firewall Integration](/u/integrations/intro) (`firewall_integration`): use blocklists directly on existing firewall appliances (Cisco, F5, Palo Alto…) without a Security Engine or bouncer. +- A [Remediation Component](https://doc.crowdsec.net/u/bouncers/intro) (`remediation_component_integration`): use a bouncer directly without a Security Engine. +- A `tag`: every Security Engine carrying that tag is subscribed **automatically**, including future ones. +- An `org`: every Security Engine enrolled in the org is subscribed **automatically**, including future ones. + +Every subscription sets an `entity_type` and a `remediation` (the action subscribers apply, e.g. +`ban`). Whether you pass `ids` depends on the `entity_type`: + +| Target | Request body | `ids` | +|---|---|---| +| Whole org | `{ "entity_type": "org", "remediation": "ban" }` | must be omitted | +| Specific engine(s) | `{ "entity_type": "engine", "ids": ["", …], "remediation": "ban" }` | required | +| A set of tag(s) | `{ "entity_type": "tag", "ids": ["", …], "remediation": "ban" }` | required | + + + + +```bash +# Whole org — every engine enrolled in the org, now and in the future (no ids) +curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ +https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID/subscribers \ +-d '{ "entity_type": "org", "remediation": "ban" }' + +# One or several specific Security Engines +curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ +https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID/subscribers \ +-d '{ "entity_type": "engine", "ids": ["SECENGINEID5678"], "remediation": "ban" }' + +# A set of tags — every engine carrying one of these tags (now and in the future) +curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ +https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID/subscribers \ +-d '{ "entity_type": "tag", "ids": ["env:prod", "region:eu"], "remediation": "ban" }' +``` + + + + +```python +import os + +KEY = os.getenv('KEY') + +from crowdsec_service_api import ( + Blocklists, + Server, + ApiKeyAuth, +) +from crowdsec_service_api.models import BlocklistSubscriptionRequest + +auth = ApiKeyAuth(api_key=KEY) +client = Blocklists(base_url=Server.production_server.value, auth=auth) +request = BlocklistSubscriptionRequest( + ids=['SECENGINEID5678'], + entity_type='engine', + remediation="ban", +) +response = client.subscribe_blocklist(request=request, blocklist_id='1234MYBLOCKLISTID') +print(response) +``` + + + + + - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/subscribeBlocklist) + +Each id is validated independently; the response reports which subscribed and which failed: + +```json +{ "updated": ["SECENGINEID5678"], "errors": [ { "BADID": "Entity not found" } ] } +``` + +:::info Where do engine and tag ids come from? +The Service API does not enumerate your engines or tags. + +- An **engine** id is the engine's machine id (shown on the Security Engines page). +- A **tag** id is simply the [tag string](/u/console/security_engines/name_and_tags) you assigned to + your engines (e.g. `env:prod`), at enrollment with `cscli console enroll --tags …` or from the + Console. +- An `org` subscription needs no id. +::: + +:::note Subscription alone is not enough +A targeted engine only starts enforcing the blocklist once it is enrolled in the org, +subscribed (directly or through its org/tag), and has `console_management` enabled locally +(`cscli console enable console_management`). See +[enrolling your engine in the Console](/u/getting_started/post_installation/console). +::: + +## Share private blocklists with other organizations + +The [`/blocklists/{blocklist_id}/shares`](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/shareBlocklist) +endpoint shares a private blocklist with other organizations. Choose the `permission` you grant: + +- `read`: they can subscribe to the blocklist, download its content and view its statistics. +- `write`: they can also add and remove IPs. + +## Delete a blocklist + +```bash +curl -i -H "x-api-key: ${KEY}" -X DELETE https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID +``` + +Deleting a blocklist that still has subscribers returns `409 Conflict`. Either unsubscribe everyone +first, or force it with `?force=true` (which drops the list and all of its subscriptions): + +```bash +curl -i -H "x-api-key: ${KEY}" -X DELETE "https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID?force=true" +``` + +## Statistics + +Querying [`GET /blocklists/{blocklist_id}`](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/getBlocklist) +returns a `stats` block. Statistics are computed on list modification and refreshed every 6 hours. + + + + +```bash +curl -i -H "x-api-key: ${KEY}" https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID +``` + + + + +```python +import os + +KEY = os.getenv('KEY') + +from crowdsec_service_api import ( + Blocklists, + Server, + ApiKeyAuth, +) +auth = ApiKeyAuth(api_key=KEY) +client = Blocklists(base_url=Server.production_server.value, auth=auth) +response = client.get_blocklist(blocklist_id='1234MYBLOCKLISTID') +print(response) +``` + + + + +The `stats` block has two parts. `content_stats` describes the IPs currently in the list (how they +are known to the CrowdSec CTI); the top-level fields describe the list itself and how it changes over +time. + +- `stats.content_stats.total_seen`: number of IPs that were seen by the CrowdSec network. +- `stats.content_stats.total_fire`: number of IPs currently in the CrowdSec Community Blocklist. +- `stats.content_stats.total_seen_1m`: number of IPs seen by the CrowdSec network in the past 30 days. +- `stats.content_stats.total_in_other_lists`: number of IPs also present in other public blocklists. +- `stats.content_stats.total_false_positive`: number of false positives (CDNs, scanners…) identified in the blocklist. CrowdSec-provided blocklists have these removed automatically, so this is non-zero only for custom blocklists. +- `stats.content_stats.false_positive_removed_by_crowdsec`: number of false positives our system removed from the blocklist. +- `stats.content_stats.most_present_behaviors`: top 10 behaviors (`http:exploit`, `ssh:bruteforce`…) for IPs in the blocklist. +- `stats.content_stats.most_present_categories`: top 10 categories (`insecure_services`…) for IPs in the blocklist. +- `stats.content_stats.most_present_scenarios`: top 10 scenarios the IPs were reported for (publicly available hub scenarios only). +- `stats.content_stats.top_as`: top 10 autonomous systems (AS) for IPs in the blocklist. +- `stats.content_stats.top_attacking_countries`: top 10 countries of origin for IPs in the blocklist. +- `stats.content_stats.top_ips`: top 10 most reported IPs in the blocklist. +- `stats.addition_2days` / `stats.addition_month`: IPs added over the last 2 / 30 days. +- `stats.suppression_2days` / `stats.suppression_month`: IPs removed (by expiration) over the last 2 / 30 days. +- `stats.change_2days_percentage` / `stats.change_month_percentage`: percentage of IPs changed (added or deleted) over the last 2 days / month. +- `stats.count`: number of IPs in the blocklist. +- `stats.updated_at`: when these stats were last computed. diff --git a/crowdsec-docs/unversioned/console/service_api/decisions.mdx b/crowdsec-docs/unversioned/console/service_api/decisions.mdx new file mode 100644 index 000000000..caf7f0c73 --- /dev/null +++ b/crowdsec-docs/unversioned/console/service_api/decisions.mdx @@ -0,0 +1,103 @@ +--- +id: decisions +title: Decisions +--- + +:::info + - We're assuming your API key is set in the environment variable `$KEY` with the necessary permissions. + - The `decisions` endpoints require a key with **decision** scope; a blocklist-only key returns `403 Forbidden`. +::: + +An org-level **decision** is a single remediation (e.g. a `ban`) on one value, applied to a scope you +choose with the `target` field. Use it for targeted, one-off actions; for maintained IP feeds prefer +[blocklists](/u/console/service_api/blocklists). + +### Create a decision + +A decision requires `duration`, `origin`, `scenario`, `scope`, `type`, `value` and a `target`. The +`target` decides **who enforces it**: + +| Target | `target` object | +|---|---| +| Whole org | `{ "type": "org", "value": "" }` | +| A specific engine | `{ "type": "entity", "value": "" }` | +| A tag | `{ "type": "tag", "value": "" }` (one call per tag) | + +Your `` is returned by [`/info`](/u/console/service_api/authentication). An +`` is the engine's machine id (Security Engines page); a `` is simply the tag string +you assigned to your engines (e.g. `env:prod`). The Service API does not enumerate them. + +```bash +# Ban 1.2.3.4 for 4h across the whole organization +curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ +https://admin.api.crowdsec.net/v1/decisions \ +-d '{ + "duration": "4h", "origin": "cscli", "scenario": "manual", + "scope": "Ip", "type": "ban", "value": "1.2.3.4", + "target": { "type": "org", "value": "MY-ORG-ID-abcdef1234" } +}' + +# Same ban, but only on one specific Security Engine +curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ +https://admin.api.crowdsec.net/v1/decisions \ +-d '{ + "duration": "4h", "origin": "cscli", "scenario": "manual", + "scope": "Ip", "type": "ban", "value": "1.2.3.4", + "target": { "type": "entity", "value": "SECENGINEID5678" } +}' + +# Same ban, applied to every engine carrying a tag +curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ +https://admin.api.crowdsec.net/v1/decisions \ +-d '{ + "duration": "4h", "origin": "cscli", "scenario": "manual", + "scope": "Ip", "type": "ban", "value": "1.2.3.4", + "target": { "type": "tag", "value": "env:prod" } +}' +``` + + - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Decisions/operation/createDecision) + +
+ answer on success + +```json +{ "uuid": "65b6a73e-f32e-49dd-a78b-85c7466c1bd4" } +``` + +
+ +:::note Enforcement is a closed loop +A Security Engine enforces a decision targeted at it (via `entity`, a `tag`, or the `org`) once it is +enrolled in the org and has `console_management` enabled locally +(`cscli console enable console_management`). The decision is then pushed over PAPI and applied within +seconds. See [enrolling your engine in the Console](/u/getting_started/post_installation/console). +Reach for a [blocklist](/u/console/service_api/blocklists) instead when you want a maintained IP feed +rather than one-off decisions. +::: + +### List decisions + +```bash +# All org decisions +curl -i -H "x-api-key: ${KEY}" -H "Content-Type: application/json" \ +https://admin.api.crowdsec.net/v1/decisions?page=1&size=50 + +# Decisions for one IP +curl -i -H "x-api-key: ${KEY}" -H "Content-Type: application/json" \ +"https://admin.api.crowdsec.net/v1/decisions?ips=1.2.3.4" +``` + + - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Decisions/operation/getDecisions) + +Results are paginated as `{ "items": [...], "total": N, "page": 1, "size": 50, "links": {...} }`; each +item carries `uuid`, `origin`, `scenario`, `scope`, `type`, `value`, `duration` and `target`. + +### View aggregated decisions + +```bash +curl -i -H "x-api-key: ${KEY}" -H "Content-Type: application/json" \ +https://admin.api.crowdsec.net/v1/decisions/aggregated +``` + + - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Decisions/operation/getAggregatedDecisions) diff --git a/crowdsec-docs/unversioned/console/service_api/getting_started.mdx b/crowdsec-docs/unversioned/console/service_api/getting_started.mdx index cc41514a4..c2b2f638e 100644 --- a/crowdsec-docs/unversioned/console/service_api/getting_started.mdx +++ b/crowdsec-docs/unversioned/console/service_api/getting_started.mdx @@ -17,14 +17,6 @@ import { Badge } from "@site/src/ui/badge"; The **Service API**, **SAPI** for short, provides access to selected **CrowdSec SaaS features**. New SaaS features will usually appear on **SAPI** first before getting their UI counterpart. -The current capabilities of this API are: - -- **Blocklist** creation & management - - Allowing you to create private blocklists and share them - - As well as subscribing to any of the blocklists available to your organization -- **Integrations** endpoints creation & management - - An Essential part of the **Blocklist as a Service** feature. - - Manage endpoints for your [**Firewalls**](/u/integrations/intro) or [**Remediation Components**](/u/bouncers/intro) to connect directly to. ## Getting your API keys diff --git a/crowdsec-docs/unversioned/console/service_api/integrations.md b/crowdsec-docs/unversioned/console/service_api/integrations.mdx similarity index 60% rename from crowdsec-docs/unversioned/console/service_api/integrations.md rename to crowdsec-docs/unversioned/console/service_api/integrations.mdx index 3bb3674c6..4248e31c3 100644 --- a/crowdsec-docs/unversioned/console/service_api/integrations.md +++ b/crowdsec-docs/unversioned/console/service_api/integrations.mdx @@ -3,21 +3,105 @@ id: integrations title: Integrations --- -## Integration supported formats +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +:::info + - We're assuming your API key is set in the environment variable `$KEY` with the necessary permissions. +::: + +An **integration** exposes the content of the blocklists subscribed to it as a pull endpoint, +rendered in a firewall/appliance vendor's format. A device polls that endpoint on a schedule. + +## Creating an integration + + + + +```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" }' +``` -For some constructors, the integrations can generate vendor-specific format, see table below: + + + +```python +import os + +KEY = os.getenv('KEY') + +from crowdsec_service_api import ( + Integrations, + Server, + ApiKeyAuth, +) +from crowdsec_service_api.models import IntegrationCreateRequest + +auth = ApiKeyAuth(api_key=KEY) +client = Integrations(base_url=Server.production_server.value, auth=auth) +request = IntegrationCreateRequest( + name='test_integration_1', + description='my test integration', + entity_type='firewall_integration', + output_format='plain_text', +) +response = client.create_integration(request=request) +print(response) +``` -| Constructor | Authentication | Multiple URLs | Constructor Doc | Format | -| ----------- | -------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -| CheckPoint | Basic Auth | Yes | [CheckPoint doc](https://support.checkpoint.com/results/sk/sk132193) | `checkpoint` | -| Cisco | Basic Auth | Yes | [Cisco doc](https://www.cisco.com/c/en/us/td/docs/security/secure-firewall/management-center/device-config/710/management-center-device-config-71/objects-object-mgmt.html#ID-2243-00000291) | `cisco` | -| F5 | Basic Auth | Yes | [F5 doc](https://techdocs.f5.com/kb/en-us/products/big-ip-afm/manuals/product/big-ip-network-firewall-policies-and-implementations-14-0-0/07.html ) | `f5` | -| Fortinet | Basic Auth | Yes | [Fortinet doc](https://docs.fortinet.com/document/fortigate/6.4.5/administration-guide/891236/external-blocklist-policy) | `fortigate` | -| Palo alto | Basic Auth | Yes | [PaloAlto doc](https://docs.paloaltonetworks.com/pan-os/11-1/pan-os-admin/policy/use-an-external-dynamic-list-in-policy/configure-the-firewall-to-access-an-external-dynamic-list) | `paloalto` | -| Sophos | Basic Auth | Yes | [Sophos doc](https://docs.sophos.com/nsg/sophos-firewall/latest/Help/en-us/webhelp/onlinehelp/AdministratorHelp/ActiveThreatResponse/ConfigureFeeds/ThirdPartyThreatFeeds/index.html) | `sophos` | + + + +:::warning +The `username` and `password` are only shown at creation time, so write them down. If you lose them, +regenerate them with the [`update`](https://admin.api.crowdsec.net/v1/docs#tag/Integrations/operation/updateIntegration) method. +::: + + - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Integrations/operation/createIntegration) + +
+ answer on success +```json +{ + "id": "INTEGRATIONID12345", + "name": "test_integration_1", + "organization_id": "MY-ORG-ID-abcdef1234", + "description": "my test integration", + "created_at": "2024-06-07T14:00:31.645929Z", + "updated_at": "2024-06-07T14:00:31.645943Z", + "entity_type": "firewall_integration", + "output_format": "plain_text", + "last_pull": null, + "blocklists": [], + "endpoint": "https://admin.api.crowdsec.net/v1/integrations/INTEGRATIONID12345/content", + "stats": { + "count": 0 + }, + "credentials": { + "username": "", + "password": "" + } +} +``` +
+ +## Fetch integration content +The content endpoint previews the list of IPs returned to your firewall (or whatever consumes the +integration). It authenticates with **HTTP Basic auth** using the credentials minted at creation: -For all the other providers, the `plain_text` format consists of one ip per line, and should be supported by most devices. If a specific format is missing, reach out to us and we'll help you support it! +```bash +curl -i -u ':' https://admin.api.crowdsec.net/v1/integrations/INTEGRATIONID12345/content +``` ## Managing integrations size limits with pagination @@ -62,7 +146,6 @@ A Palo Alto firewall may limit external dynamic lists between 50,000 and 150,000 3. Increment the `page` parameter and add the new dynamic list. 4. Repeat until all IPs are processed. - ### Pro Tip When you know the maximum number of entries your device can handle, and you want to calculate the number of pages needed, you will also need to know the total number of IPs in your integration. You can get this information from the [integration details page](https://app.crowdsec.net/blocklists/integrations), where you can find the "Total IPs" count. Then, use the following formula: @@ -70,3 +153,18 @@ When you know the maximum number of entries your device can handle, and you want ``` number_of_pages = ceil(total_ips / page_size) ``` + +## Integration supported formats + +For some constructors, the integration can generate a vendor-specific format, see the table below: + +| Constructor | Authentication | Multiple URLs | Constructor Doc | Format | +| ----------- | -------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | +| CheckPoint | Basic Auth | Yes | [CheckPoint doc](https://support.checkpoint.com/results/sk/sk132193) | `checkpoint` | +| Cisco | Basic Auth | Yes | [Cisco doc](https://www.cisco.com/c/en/us/td/docs/security/secure-firewall/management-center/device-config/710/management-center-device-config-71/objects-object-mgmt.html#ID-2243-00000291) | `cisco` | +| F5 | Basic Auth | Yes | [F5 doc](https://techdocs.f5.com/kb/en-us/products/big-ip-afm/manuals/product/big-ip-network-firewall-policies-and-implementations-14-0-0/07.html ) | `f5` | +| Fortinet | Basic Auth | Yes | [Fortinet doc](https://docs.fortinet.com/document/fortigate/6.4.5/administration-guide/891236/external-blocklist-policy) | `fortigate` | +| Palo alto | Basic Auth | Yes | [PaloAlto doc](https://docs.paloaltonetworks.com/pan-os/11-1/pan-os-admin/policy/use-an-external-dynamic-list-in-policy/configure-the-firewall-to-access-an-external-dynamic-list) | `paloalto` | +| Sophos | Basic Auth | Yes | [Sophos doc](https://docs.sophos.com/nsg/sophos-firewall/latest/Help/en-us/webhelp/onlinehelp/AdministratorHelp/ActiveThreatResponse/ConfigureFeeds/ThirdPartyThreatFeeds/index.html) | `sophos` | + +For all the other providers, the `plain_text` format consists of one IP per line, and should be supported by most devices. If a specific format is missing, reach out to us and we'll help you support it! diff --git a/crowdsec-docs/unversioned/console/service_api/quickstart/metrics.mdx b/crowdsec-docs/unversioned/console/service_api/metrics.mdx similarity index 76% rename from crowdsec-docs/unversioned/console/service_api/quickstart/metrics.mdx rename to crowdsec-docs/unversioned/console/service_api/metrics.mdx index c1f9be591..21efb209f 100644 --- a/crowdsec-docs/unversioned/console/service_api/quickstart/metrics.mdx +++ b/crowdsec-docs/unversioned/console/service_api/metrics.mdx @@ -85,6 +85,36 @@ print(response.model_dump_json()) +### Scope the metrics (engine, tag, or integration) + +By default the metrics cover your whole organization. Narrow them with these repeatable query +parameters; they filter server-side: + +| Parameter | Scopes the metrics to… | +|---|---| +| `engine_ids` | one or more Security Engines (an engine id is its machine id) | +| `tags` | Security Engines carrying the given tag(s) | +| `integration_ids` | one or more firewall/appliance integrations | + +```bash +# Only the drops attributed to two specific engines +curl -i -H "x-api-key: ${KEY}" -X GET \ +"https://admin.api.crowdsec.net/v1/metrics/remediation?start_date=2025-03-19T00:00:00Z&end_date=2025-03-27T00:00:00Z&engine_ids=ENGINEID1&engine_ids=ENGINEID2" + +# Everything on engines tagged env:prod +curl -i -H "x-api-key: ${KEY}" -X GET \ +"https://admin.api.crowdsec.net/v1/metrics/remediation?start_date=2025-03-19T00:00:00Z&end_date=2025-03-27T00:00:00Z&tags=env:prod" +``` + +Repeat a parameter to pass several values (they combine as a union); the filter applies to both the +`raw` and `computed` sections. + +:::note The breakdown is by origin, not by engine +Each metric's `data` is grouped by origin: `CAPI`, `crowdsec`, `ipset`, `unknown`, or a blocklist +object (with its `label`/`id`). It is never split per engine. To get one engine's numbers, ask for +that engine's `engine_ids`. +::: + ### Metrics definitions - `raw`: Raw metrics are the metrics that are directly collected from the crowdsec engine. diff --git a/crowdsec-docs/unversioned/console/service_api/quickstart/blocklists.mdx b/crowdsec-docs/unversioned/console/service_api/quickstart/blocklists.mdx deleted file mode 100644 index 28b4770c3..000000000 --- a/crowdsec-docs/unversioned/console/service_api/quickstart/blocklists.mdx +++ /dev/null @@ -1,548 +0,0 @@ ---- -id: blocklists -title: Blocklists ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -:::info - - We're assuming your API key is set in the environment variable `$KEY` with the necessary permissions. -::: - -### Create a blocklist - -> Create a new private blocklist named `my_test_blocklist` - - - - -```bash -curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ -https://admin.api.crowdsec.net/v1/blocklists \ --d '{ "name":"my_test_blocklist", "description": "testing blocklists feature" }' -``` - - - - -```python -import os - -KEY = os.getenv('KEY') - -from crowdsec_service_api import ( - Blocklists, - Server, - ApiKeyAuth, -) -from crowdsec_service_api.models import BlocklistCreateRequest - -auth = ApiKeyAuth(api_key=KEY) -client = Blocklists(base_url=Server.production_server.value, auth=auth) -request = BlocklistCreateRequest( - name='my_test_blocklist', - description='testing blocklists feature', -) -response = client.create_blocklist( - request=request, -) -print(response) -``` - - - - - - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/createBlocklist) - -:::info -The `id` element of the response payload is going to be used as the future identifier operations targeting this blocklist. -::: - -
- answer on success - -```json -{ - "id": "1234MYBLOCKLISTID", - "created_at": "2024-06-06T07:33:38.509837Z", - "updated_at": "2024-06-06T07:33:38.509839Z", - "name": "my_test_blocklist", - "label": "my_test_blocklist", - "description": "testing blocklists feature", - "references": [], - "is_private": true, - "tags": [], - "pricing_tier": "free", - "source": "custom", - "stats": { - "content_stats": { - "total_seen": 0, - "total_fire": 0, - "total_seen_1m": 0, - "total_in_other_lists": 0, - "total_false_positive": 0, - "false_positive_removed_by_crowdsec": 0, - "most_present_behaviors": [], - "most_present_categories": [], - "most_present_scenarios": [], - "top_as": [], - "top_attacking_countries": [], - "top_ips": [], - "updated_at": null - }, - "usage_stats": { - "engines_subscribed_directly": 0, - "engines_subscribed_through_org": 0, - "engines_subscribed_through_tag": 0, - "total_subscribed_engines": 0, - "updated_at": null - }, - "addition_2days": 0, - "addition_month": 0, - "suppression_2days": 0, - "suppression_month": 0, - "change_2days_percentage": 0, - "change_month_percentage": 0, - "count": 0, - "updated_at": null - }, - "from_cti_query": null, - "since": null, - "shared_with": [], - "organization_id": "MY-ORG-ID-abcdef1234", - "subscribers": [] -} - -``` - -
- - -### Add some IPs to blocklist - -> Add IPs `1.2.3.4` and `5.6.7.8` to blocklist for the next 24h - - - - -```bash -curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ -https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID/ips \ --d '{ "ips": ["1.2.3.4", "5.6.7.8"], "expiration": "'`date --date='tomorrow' '+%FT%T'`'"}' -``` - - - - -```python -import os -from datetime import datetime, UTC, timedelta - -KEY = os.getenv('KEY') -EXPIRATION = datetime.now(UTC) + timedelta(days=1) - -from crowdsec_service_api import ( - Blocklists, - Server, - ApiKeyAuth, -) -from crowdsec_service_api.models import BlocklistAddIPsRequest - -auth = ApiKeyAuth(api_key=KEY) -client = Blocklists(base_url=Server.production_server.value, auth=auth) -request = BlocklistAddIPsRequest( - ips=["1.2.3.4", "5.6.7.8"], - expiration=EXPIRATION, -) -response = client.add_ips_to_blocklist( - request=request, - blocklist_id='sample-blocklist-id', -) -print(response) -``` - - - - - - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/addIpsToBlocklist) - - -:::note - -The `expiration` field is mandatory and indicates when the IP should be deleted from the blocklist. - -::: - - -### View blocklist stats - -:::info -When querying stats about a blocklist, you will also get information about how the IPs are known in the CTI. -However, keep in mind that those statistics are computed upon list modification, and then refreshed every 6 hours. -::: - - - - -```bash -curl -i -H "x-api-key: ${KEY}" -H "Content-Type: application/json" \ -https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID -``` - - - - -```python -import os - -KEY = os.getenv('KEY') - -from crowdsec_service_api import ( - Blocklists, - Server, - ApiKeyAuth, -) -auth = ApiKeyAuth(api_key=KEY) -client = Blocklists(base_url=Server.production_server.value, auth=auth) -response = client.get_blocklist( - blocklist_id='1234MYBLOCKLISTID', -) -print(response) -``` - - - - - - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/getBlocklist) - - -
- answer on success -```json -{ - "id": "1234MYBLOCKLISTID", - "created_at": "2024-06-06T07:33:38.509000Z", - "updated_at": "2024-06-06T07:33:38.509000Z", - "name": "my_test_blocklist", - "label": "my_test_blocklist", - "description": "testing blocklists feature", - "references": [], - "is_private": true, - "tags": [], - "pricing_tier": "free", - "source": "custom", - "stats": { - "content_stats": { - "total_seen": 1, - "total_fire": 0, - "total_seen_1m": 0, - "total_in_other_lists": 1, - "total_false_positive": 0, - "false_positive_removed_by_crowdsec": 0, - "most_present_behaviors": [ - { - "name": "ssh:bruteforce", - "label": "SSH Bruteforce", - "description": "IP has been reported for performing brute force on ssh services.", - "references": [], - "total_ips": 1 - }, - { - "name": "http:dos", - "label": "HTTP DoS", - "description": "IP has been reported trying to perform denial of service attacks.", - "references": [], - "total_ips": 1 - }, - { - "name": "tcp:scan", - "label": "TCP Scan", - "description": "IP has been reported for performing TCP port scanning.", - "references": [], - "total_ips": 1 - }, - { - "name": "http:scan", - "label": "HTTP Scan", - "description": "IP has been reported for performing actions related to HTTP vulnerability scanning and discovery.", - "references": [], - "total_ips": 1 - }, - { - "name": "http:exploit", - "label": "HTTP Exploit", - "description": "IP has been reported for attempting to exploit a vulnerability in a web application.", - "references": [], - "total_ips": 1 - }, - { - "name": "http:bruteforce", - "label": "HTTP Bruteforce", - "description": "IP has been reported for performing a HTTP brute force attack (either generic HTTP probing or applicative related brute force).", - "references": [], - "total_ips": 1 - } - ], - "most_present_categories": [ - { - "name": "proxy:vpn", - "label": "VPN", - "description": "IP exposes a VPN service or is being flagged as one.", - "total_ips": 1 - } - ], - "most_present_scenarios": [ - { - "name": "crowdsecurity/nginx-req-limit-exceeded", - "label": "Nginx request limit exceeded", - "description": "Detects IPs which violate nginx's user set request limit.", - "references": [], - "total_ips": 1 - }, - { - "name": "crowdsecurity/jira_cve-2021-26086", - "label": "Jira CVE-2021-26086 exploitation", - "description": "Detect Atlassian Jira CVE-2021-26086 exploitation attemps", - "references": [], - "total_ips": 1 - }, - { - "name": "crowdsecurity/http-bad-user-agent", - "label": "Bad User Agent", - "description": "Detect usage of bad User Agent", - "references": [], - "total_ips": 1 - }, - { - "name": "crowdsecurity/ssh-bf", - "label": "SSH Bruteforce", - "description": "Detect ssh bruteforce", - "references": [], - "total_ips": 1 - }, - { - "name": "crowdsecurity/CVE-2017-9841", - "label": "PHP Unit Test Framework CVE-2017-9841", - "description": "Detect CVE-2017-9841 exploits", - "references": [], - "total_ips": 1 - }, - { - "name": "crowdsecurity/vpatch-env-access", - "label": "Access to .env file", - "description": "Detect access to .env files", - "references": [], - "total_ips": 1 - }, - { - "name": "firewallservices/pf-scan-multi_ports", - "label": "PF Scan Multi Ports", - "description": "ban IPs that are scanning us", - "references": [], - "total_ips": 1 - }, - { - "name": "crowdsecurity/ssh-slow-bf", - "label": "SSH Slow Bruteforce", - "description": "Detect slow ssh bruteforce", - "references": [], - "total_ips": 1 - }, - { - "name": "crowdsecurity/http-bf-wordpress_bf_xmlrpc", - "label": "WP XMLRPC bruteforce", - "description": "detect wordpress bruteforce on xmlrpc", - "references": [], - "total_ips": 1 - }, - { - "name": "crowdsecurity/http-probing", - "label": "HTTP Probing", - "description": "Detect site scanning/probing from a single ip", - "references": [], - "total_ips": 1 - } - ], - "top_as": [ - { - "as_num": "0", - "as_name": "AS0", - "total_ips": 1 - } - ], - "top_attacking_countries": [ - { - "country_short": "AU", - "total_ips": 1 - } - ], - "top_ips": [ - { - "ip": "1.2.3.4", - "total_signals_1m": 4, - "reputation": "suspicious" - } - ], - "updated_at": "2024-06-06T10:31:28.724000Z" - }, - "usage_stats": { - "engines_subscribed_directly": 0, - "engines_subscribed_through_org": 0, - "engines_subscribed_through_tag": 0, - "total_subscribed_engines": 0, - "updated_at": "2024-06-06T10:31:28.727000Z" - }, - "addition_2days": 2, - "addition_month": 2, - "suppression_2days": 0, - "suppression_month": 0, - "change_2days_percentage": 100, - "change_month_percentage": 100, - "count": 2, - "updated_at": "2024-06-06T10:31:28.727000Z" - }, - "from_cti_query": null, - "since": null, - "shared_with": [], - "organization_id": "MY-ORG-ID-abcdef1234", - "subscribers": [] -} - -``` -
- - -### Subscribe to a blocklist - -You can see details about the [subscriber's logic here](/console/service_api/blocklists.md#blocklist-subscription-mechanism). - - - - -```bash -curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \ -https://admin.api.crowdsec.net/v1//blocklists/1234MYBLOCKLISTID/subscribers \ --d '{ "ids": ["SECENGINEID5678"], "entity_type": "engine", "remediation": "ban" }' -``` - - - - -```python -import os - -KEY = os.getenv('KEY') - -from crowdsec_service_api import ( - Blocklists, - Server, - ApiKeyAuth, -) -from crowdsec_service_api.models import BlocklistSubscriptionRequest - -auth = ApiKeyAuth(api_key=KEY) -client = Blocklists(base_url=Server.production_server.value, auth=auth) -request = BlocklistSubscriptionRequest( - ids=['SECENGINEID5678'], - entity_type='engine', - remediation="ban", -) -response = client.subscribe_blocklist( - request=request, - blocklist_id='1234MYBLOCKLISTID', -) -print(response) -``` - - - - - - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Blocklists/operation/subscribeBlocklist) - -
- answer on success -```json -{"updated":["SECENGINEID5678"],"errors":[]} -``` -
- - -### Download blocklist content - - - - -```bash -GET -H "x-api-key: ${KEY}" https://admin.api.crowdsec.net/v1/blocklists/1234MYBLOCKLISTID/download -``` - - - - -```python -import os - -KEY = os.getenv('KEY') - -from crowdsec_service_api import ( - Blocklists, - Server, - ApiKeyAuth, -) -auth = ApiKeyAuth(api_key=KEY) -client = Blocklists(base_url=Server.production_server.value, auth=auth) -response = client.download_blocklist_content( - blocklist_id='1234MYBLOCKLISTID', - if_modified_since=None, - if_none_match=None, -) -print(response) -``` - - - - -
- answer on success -```text -1.2.3.4 -5.6.7.8 -``` -
diff --git a/crowdsec-docs/unversioned/console/service_api/quickstart/integrations.mdx b/crowdsec-docs/unversioned/console/service_api/quickstart/integrations.mdx deleted file mode 100644 index 98fd9ab3c..000000000 --- a/crowdsec-docs/unversioned/console/service_api/quickstart/integrations.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -id: integrations -title: Integrations ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import useBaseUrl from '@docusaurus/useBaseUrl'; - -:::info - - We're assuming your API key is set in the environment variable `$KEY` with the necessary permissions. -::: - -### Creating integration - - - - -```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 - -KEY = os.getenv('KEY') - -from crowdsec_service_api import ( - Integrations, - Server, - ApiKeyAuth, -) -from crowdsec_service_api.models import IntegrationCreateRequest - -auth = ApiKeyAuth(api_key=KEY) -client = Integrations(base_url=Server.production_server.value, auth=auth) -request = IntegrationCreateRequest( - name='test_integration_1', - description='my test integration', - entity_type='firewall_integration', - output_format='plain_text', -) -response = client.create_integration( - request=request, -) -print(response) -``` - - - - -:::warning -The `username` and `password` will only be displayed at creation time, be sure to write them down. If you lose them, you can always regenerate them with the [`update`](https://admin.api.crowdsec.net/v1/docs#tag/Integrations/operation/updateIntegration) method. -::: - - - [Redoc method link](https://admin.api.crowdsec.net/v1/docs#tag/Integrations/operation/createIntegration) - -
- answer on success -```json -{ - "id": "INTEGRATIONID12345", - "name": "test_integration_1", - "organization_id": "MY-ORG-ID-abcdef1234", - "description": "my test integration", - "created_at": "2024-06-07T14:00:31.645929Z", - "updated_at": "2024-06-07T14:00:31.645943Z", - "entity_type": "firewall_integration", - "output_format": "plain_text", - "last_pull": null, - "blocklists": [], - "endpoint": "https://admin.api.crowdsec.net/v1/integrations/INTEGRATIONID12345/content", - "stats": { - "count": 0 - }, - "credentials": { - "username": "", - "password": "" - } -} - -``` -
- -### View integration content - -View integration content allows you to preview the list of IPs that are returned to your firewall (or whatever is going to consume the integration). - -```bash -curl -i -u ':' https://admin.api.crowdsec.net/v1/integrations/INTEGRATIONID12345/content -``` diff --git a/crowdsec-docs/unversioned/integrations/checkpoint.mdx b/crowdsec-docs/unversioned/integrations/checkpoint.mdx index 3a28d35c6..599c13f2f 100644 --- a/crowdsec-docs/unversioned/integrations/checkpoint.mdx +++ b/crowdsec-docs/unversioned/integrations/checkpoint.mdx @@ -81,7 +81,7 @@ Format: `UNIQ-NAME, VALUE, TYPE, CONFIDENCE, SEVERITY, PRODUCT, COMMENT` ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. The Checkpoint format is verbose. When pulling **without compression**, keep `page_size` at or below **~60,000** entries to stay under the ~5 MB response limit; larger pages return an error. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/integrations/cisco.mdx b/crowdsec-docs/unversioned/integrations/cisco.mdx index ba28519eb..3b1bea941 100644 --- a/crowdsec-docs/unversioned/integrations/cisco.mdx +++ b/crowdsec-docs/unversioned/integrations/cisco.mdx @@ -36,7 +36,7 @@ The vendor documentation is available in the [References](#references) section b ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. This integration uses the plain text format. When pulling **without compression**, keep `page_size` at or below **~300,000** entries to stay under the ~5 MB response limit; beyond that the response is truncated. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/integrations/f5.mdx b/crowdsec-docs/unversioned/integrations/f5.mdx index b3f81a884..0aaa0ecdd 100644 --- a/crowdsec-docs/unversioned/integrations/f5.mdx +++ b/crowdsec-docs/unversioned/integrations/f5.mdx @@ -49,7 +49,7 @@ Format: `IP, Mask, WL/BL, Category` ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. The F5 format produces larger entries. When pulling **without compression**, keep `page_size` at or below **~90,000** entries to stay under the ~5 MB response limit; beyond that the response is truncated. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/integrations/fortinet.mdx b/crowdsec-docs/unversioned/integrations/fortinet.mdx index 0bf3eb5cd..abb803050 100644 --- a/crowdsec-docs/unversioned/integrations/fortinet.mdx +++ b/crowdsec-docs/unversioned/integrations/fortinet.mdx @@ -37,7 +37,7 @@ The vendor documentation is available in the [References](#references) section b ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. This integration uses the plain text format. When pulling **without compression**, keep `page_size` at or below **~300,000** entries to stay under the ~5 MB response limit; beyond that the response is truncated. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/integrations/intro.mdx b/crowdsec-docs/unversioned/integrations/intro.mdx index 4e156cae6..8432d1f45 100644 --- a/crowdsec-docs/unversioned/integrations/intro.mdx +++ b/crowdsec-docs/unversioned/integrations/intro.mdx @@ -276,7 +276,7 @@ If you are not receiving the full list, you have two options: Many devices support compression natively. For instance, the [Mikrotik integration](integrations/mikrotik.mdx) sets `http-header-field="Accept-Encoding:gzip"`. -- **Use pagination.** If your client cannot handle compression, fetch the list in smaller chunks using the `page` and `page_size` query parameters. See [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination). +- **Use pagination.** If your client cannot handle compression, fetch the list in smaller chunks using the `page` and `page_size` query parameters. See [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination). When pulling **without compression**, keep each page under the ~5 MB limit by capping `page_size` (or by setting a `pull_limit` on the integration so every pull stays bounded). The safe value depends on your format, because each format produces a different number of bytes per entry. As a reference point, the plain text format truncates at roughly **350,000 IPv4 entries** at the 5 MB limit: diff --git a/crowdsec-docs/unversioned/integrations/juniper.mdx b/crowdsec-docs/unversioned/integrations/juniper.mdx index e12f7afc5..c98f65aff 100644 --- a/crowdsec-docs/unversioned/integrations/juniper.mdx +++ b/crowdsec-docs/unversioned/integrations/juniper.mdx @@ -86,7 +86,7 @@ address-name crowdsec-feed { ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. This integration uses the plain text format. When pulling **without compression**, keep `page_size` at or below **~300,000** entries to stay under the ~5 MB response limit; beyond that the response is truncated. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/integrations/mikrotik.mdx b/crowdsec-docs/unversioned/integrations/mikrotik.mdx index de02c890c..c628472ea 100644 --- a/crowdsec-docs/unversioned/integrations/mikrotik.mdx +++ b/crowdsec-docs/unversioned/integrations/mikrotik.mdx @@ -94,7 +94,7 @@ The CrowdSec blocklist is served in Mikrotik format, with one entry per line: ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. The MikroTik format emits a full command per entry, so entries are large. When pulling **without compression**, keep `page_size` at or below **~35,000** entries to stay under the ~5 MB response limit; beyond that the response is truncated. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/integrations/opnsense.mdx b/crowdsec-docs/unversioned/integrations/opnsense.mdx index 685c278dc..fa0f2e4a2 100644 --- a/crowdsec-docs/unversioned/integrations/opnsense.mdx +++ b/crowdsec-docs/unversioned/integrations/opnsense.mdx @@ -51,7 +51,7 @@ Here is a walkthrough of the full OPNsense configuration: ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. This integration uses the plain text format. When pulling **without compression**, keep `page_size` at or below **~300,000** entries to stay under the ~5 MB response limit; beyond that the response is truncated. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/integrations/paloalto.mdx b/crowdsec-docs/unversioned/integrations/paloalto.mdx index 9479e4464..25377132c 100644 --- a/crowdsec-docs/unversioned/integrations/paloalto.mdx +++ b/crowdsec-docs/unversioned/integrations/paloalto.mdx @@ -79,7 +79,7 @@ Click **Commit** to apply the configuration. ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. This integration uses the plain text format. When pulling **without compression**, keep `page_size` at or below **~300,000** entries to stay under the ~5 MB response limit; beyond that the response is truncated. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/integrations/pfsense.mdx b/crowdsec-docs/unversioned/integrations/pfsense.mdx index 0d791b4c4..482033e3d 100644 --- a/crowdsec-docs/unversioned/integrations/pfsense.mdx +++ b/crowdsec-docs/unversioned/integrations/pfsense.mdx @@ -51,7 +51,7 @@ Here is a walkthrough of the full pfSense configuration: ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. This integration uses the plain text format. When pulling **without compression**, keep `page_size` at or below **~300,000** entries to stay under the ~5 MB response limit; beyond that the response is truncated. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/integrations/rawiplist.mdx b/crowdsec-docs/unversioned/integrations/rawiplist.mdx index e128e5949..8de92d120 100644 --- a/crowdsec-docs/unversioned/integrations/rawiplist.mdx +++ b/crowdsec-docs/unversioned/integrations/rawiplist.mdx @@ -172,7 +172,7 @@ The blocklist name(s) will appear in the integration tile once subscribed. ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. This integration uses the plain text format. When pulling **without compression**, keep `page_size` at or below **~300,000** entries to stay under the ~5 MB response limit; beyond that the response is truncated. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/integrations/sophos.mdx b/crowdsec-docs/unversioned/integrations/sophos.mdx index 2c38bf7bd..01aebe06d 100644 --- a/crowdsec-docs/unversioned/integrations/sophos.mdx +++ b/crowdsec-docs/unversioned/integrations/sophos.mdx @@ -37,7 +37,7 @@ The vendor documentation is available in the [References](#references) section b ## Manage integration size limits with pagination -If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](console/service_api/integrations.md#managing-integrations-size-limits-with-pagination) section. +If you want to learn how to manage integration size limits with pagination, please refer to the [Managing integrations size limits with pagination](/u/console/service_api/integrations#managing-integrations-size-limits-with-pagination) section. This integration uses the plain text format. When pulling **without compression**, keep `page_size` at or below **~300,000** entries to stay under the ~5 MB response limit; beyond that the response is truncated. Enabling compression avoids this limit entirely. diff --git a/crowdsec-docs/unversioned/troubleshooting/usecases.mdx b/crowdsec-docs/unversioned/troubleshooting/usecases.mdx index 31a63b96e..4b42902cf 100644 --- a/crowdsec-docs/unversioned/troubleshooting/usecases.mdx +++ b/crowdsec-docs/unversioned/troubleshooting/usecases.mdx @@ -39,7 +39,7 @@ Good option if you are not using a Security Engine and want your CDN or WAF to b - [Blocklist integration Getting started guide](/u/integrations/intro) - [Subscribing to blocklists](/u/console/blocklists/subscription/) - [List of integrations format](/u/integrations/intro#current-integrations) -- [API management & creating your own blocklists](/u/console/service_api/quickstart/blocklists) +- [API management & creating your own blocklists](/u/console/service_api/blocklists) - [Remediation Component BLaaS integration](/u/integrations/remediationcomponent) - [AWS WAF remediation component](/u/bouncers/aws_waf) - [Cloudflare Workers remediation component](/u/bouncers/cloudflare-workers) @@ -344,7 +344,7 @@ Quickly choose among qualified malicious actors regrouped by industry, behaviors - [IP reputation lists / Blocklists Catalog doc ↗️](https://app.crowdsec.net/blocklists/search) - [Retrieving merged lists via HTTPS endpoints](/u/integrations/intro) -- [Retrieving Blocklists via API](/u/console/service_api/quickstart/blocklists#download-blocklist-content) +- [Retrieving Blocklists via API](/u/console/service_api/blocklists#download-blocklist-content) - [MISP Feed from Security Engine's alerts](https://doc.crowdsec.net/u/bouncers/misp-feed-generator) - [Upcoming CrowdSec MISP Feeds ↗️](https://roadmap.crowdsec.net/c/48-misp-feed) - [Contact Us for custom requests ↗️](https://www.crowdsec.net/business-requests?interest=CTI%20subscription))