Allowlists
Create an allowlist
Create a new allowlist named
my_test_allowlist
- cURL
- Python
curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \
https://admin.api.crowdsec.net/v1/allowlists \
-d '{ "name":"my_test_allowlist", "description": "testing allowlists feature" }'
import os
KEY = os.getenv('KEY')
from crowdsec_service_api import (
Allowlists,
Server,
ApiKeyAuth,
)
from crowdsec_service_api.models import AllowlistCreateRequest
auth = ApiKeyAuth(api_key=KEY)
client = Allowlists(base_url=Server.production_server.value, auth=auth)
request = AllowlistCreateRequest(
name="test_allowlist_1",
description="my test allowlist",
)
response = allowlists_client.create_allowlist(request=request)
print(response.model_dump_json())
answer on success
{
"id": "1234MYALLOWLISTID",
"organization_id": "MY-ORG-ID-abcdef1234",
"name": "test_allowlist_1",
"description": "my test allowlist",
"created_at": "2025-03-26T14:55:24.582124Z",
"updated_at": null,
"from_cti_query": null,
"since": null,
"total_items": 0
}
List all allowlists
- cURL
- Python
curl -i -H "x-api-key: ${KEY}" -H "Content-Type: application/json" \
https://admin.api.crowdsec.net/v1/allowlists
import os
KEY = os.getenv('KEY')
from crowdsec_service_api import (
Allowlists,
Server,
ApiKeyAuth,
)
auth = ApiKeyAuth(api_key=KEY)
client = Allowlists(base_url=Server.production_server.value, auth=auth)
response = client.get_allowlists()
print(response.model_dump_json())
answer on success
{
"items": [
{
"id": "1234MYALLOWLISTID",
"organization_id": "MY-ORG-ID-abcdef1234",
"name": "test_allowlist_1",
"description": "",
"created_at": "2025-03-26T14:55:24.582124Z",
"updated_at": null,
"from_cti_query": null,
"since": null,
"total_items": 2,
"subscribers": []
}
],
"total": 1,
"page": 1,
"size": 50,
"pages": 1,
"links": {
"first": "/v1/allowlists?size=50&page=1",
"last": "/v1/allowlists?size=50&page=1",
"self": "/v1/allowlists?page=1&size=50",
"next": null,
"prev": null
}
}
Add some IPs to the allowlist
Add IPs
1.2.3.4
and5.6.7.8
to allowlist
- cURL
- Python
curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \
https://admin.api.crowdsec.net/v1/allowlists/1234MYALLOWLISTID/items \
-d '{ "items": ["1.2.3.4", "5.6.7.8"], "description": "allow my office ips"}'
import os
from datetime import datetime, UTC, timedelta
KEY = os.getenv('KEY')
EXPIRATION = datetime.now(UTC) + timedelta(days=1)
from crowdsec_service_api import (
Allowlists,
Server,
ApiKeyAuth,
)
from crowdsec_service_api.models import AllowlistItemsCreateRequest
auth = ApiKeyAuth(api_key=KEY)
client = Allowlists(base_url=Server.production_server.value, auth=auth)
request = AllowlistItemsCreateRequest(
items=[
"1.2.3.4",
"5.6.7.8",
],
description="allow my office ips",
)
response = client.create_allowlist_items(
allowlist_id="1234MYALLOWLISTID", request=request
)
print(response)
List all items in the allowlist
- cURL
- Python
curl -i -H "x-api-key: ${KEY}" -H "Content-Type: application/json" \
https://admin.api.crowdsec.net/v1/allowlists/1234MYALLOWLISTID/items
import os
KEY = os.getenv('KEY')
from crowdsec_service_api import (
Allowlists,
Server,
ApiKeyAuth,
)
auth = ApiKeyAuth(api_key=KEY)
client = Allowlists(base_url=Server.production_server.value, auth=auth)
response = client.get_allowlist_items(
allowlist_id='1234MYALLOWLISTID',
)
print(response.model_dump_json())
answer on success
{
"items": [
{
"id": "67e418019f43fb6d0b985e26",
"allowlist_id": "67e4155c52f3aa0a4f6c8d93",
"description": "allow my office ips",
"scope": "ip",
"value": "1.2.3.4",
"created_at": "2025-03-26T15:06:41.719000Z",
"updated_at": null,
"created_by": {
"source_type": "apikey",
"identifier": "test-key-for-monitoring"
},
"updated_by": null,
"expiration": null
},
{
"id": "67e418019f43fb6d0b985e27",
"allowlist_id": "67e4155c52f3aa0a4f6c8d93",
"description": "allow my office ips",
"scope": "ip",
"value": "5.6.7.8",
"created_at": "2025-03-26T15:06:41.719000Z",
"updated_at": null,
"created_by": {
"source_type": "apikey",
"identifier": "test-key-for-monitoring"
},
"updated_by": null,
"expiration": null
}
],
"total": 2,
"page": 1,
"size": 50,
"pages": 1,
"links": {
"first": "/v1/allowlists/67e4155c52f3aa0a4f6c8d93/items?size=50&page=1",
"last": "/v1/allowlists/67e4155c52f3aa0a4f6c8d93/items?size=50&page=1",
"self": "/v1/allowlists/67e4155c52f3aa0a4f6c8d93/items?page=1&size=50",
"next": null,
"prev": null
}
}
Update an item in the allowlist
can be used to update the description or add an expiration date to the item
- cURL
- Python
curl -i -H "x-api-key: ${KEY}" -H "Content-Type: application/json" \
https://admin.api.crowdsec.net/v1/allowlists/1234MYALLOWLISTID/items/67e418019f43fb6d0b985e26 \
-X PATCH -d '{ "description": "allow my office ips for 1 day", "expiration": "2025-03-27T16:45:53" }'
import os
import datetime
KEY = os.getenv('KEY')
from crowdsec_service_api import (
Allowlists,
Server,
ApiKeyAuth,
)
from crowdsec_service_api.models import AllowlistItemUpdateRequest
auth = ApiKeyAuth(api_key=KEY)
client = Allowlists(base_url=Server.production_server.value, auth=auth)
request = AllowlistItemUpdateRequest(
description="allow my office ips for 1 day",
expiration=datetime.datetime.now() + datetime.timedelta(days=1),
)
response = client.update_allowlist_item(
allowlist_id='1234MYALLOWLISTID',
item_id='67e418019f43fb6d0b985e26',
request=request,
)
print(response)
answer on success
{
"id": "67e418019f43fb6d0b985e26",
"allowlist_id": "1234MYALLOWLISTID",
"description": "allow my office ips for 1 day",
"scope": "ip",
"value": "1.2.3.4",
"created_at": "2025-03-26T15:06:41.719000Z",
"updated_at": "2025-03-26T15:45:53.373141Z",
"created_by": {
"source_type": "apikey",
"identifier": "test-key-for-monitoring"
},
"updated_by": {
"source_type": "apikey",
"identifier": "test-key-for-monitoring"
},
"expiration": "2025-03-27T16:45:53.238842"
}
Subscribe to an allowlist
Allowlist subscription mechanism
When subscribing to allowlists, you can use various entity_type
:
- A Security Engine (entity_type
engine
). Remediation Components (Bouncers) connected to it will benefit of the allowlist. - A Firewall Integration (entity_type
firewall_integration
). This allows to use benefit from allowlists directly on your existing Firewall Appliances (CISCO, F5, Palo Alto etc.) without having to install a Security Engine or "Bouncer". - A Remediation Component (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_typetag
). This means that future Security Engines associated to this tag will automatically be subscribed to the allowlist. - You can also subscribe via an
org
directly. This means that future Security Engines enrolled in this org will automatically be subscribed to the allowlist.
- cURL
- Python
curl -i -H "x-api-key: ${KEY}" -X POST -H "Content-Type: application/json" \
https://admin.api.crowdsec.net/v1/allowlists/1234MYBLOCKLISTID/subscribers \
-d '{ "ids": ["SECENGINEID5678"], "entity_type": "engine" }'
import os
KEY = os.getenv('KEY')
from crowdsec_service_api import (
Allowlists,
Server,
ApiKeyAuth,
)
from crowdsec_service_api.models import AllowlistSubscriptionRequest
auth = ApiKeyAuth(api_key=KEY)
client = Allowlists(base_url=Server.production_server.value, auth=auth)
request = AllowlistSubscriptionRequest(
ids=['SECENGINEID5678'],
entity_type='engine',
)
response = client.subscribe_allowlist(
request=request,
allowlist_id='1234MYALLOWLISTID',
)
print(response)
answer on success
{"updated":["SECENGINEID5678"],"errors":[]}