App

Sceptive’s bl0ck API provides access to the Sceptive://bl0ck cyberdefense grid signals, combining sensors and verified threat sources. It includes endpoints for managing IP blocklists and viewing analytics.

Authentication

All endpoints require authentication via a token header.

Header Parameters:

token (required): API access token that must match the ROOT_TOKEN configured in the environment settings.

Endpoints

Get All Block IP Lists - GET /v1/block-ip-list/lists

Returns a list of all configured IP blocklists and IP ranges currently monitored by the system. This is useful for bulk importing block rules or syncing firewall configurations.

Response:

A JSON array containing blocklist information including ID, name, description, and details like total IP count, top tags, and top IPs.

Get IP Info by IPv4 - GET /v1/block-ip-list/get/ipv4/{ip}

Retrieves risk insights and metadata for a given IPv4 address to help identify suspicious activity.

Path Parameters:

ip (string): The IPv4 address to get information for.

Response:

{
  "ip": "192.168.1.1",
  "tags": ["wordpress", "http"],
  "priority": 10,
  "insert_date": "2025-04-01"
}

Get System Time - GET /v1/al1v3

Returns the current system time to check if the API is alive.

Response:

{
  "system_time": "2025-04-09 14:30:00"
}

Get Analytics by Period - GET /v1/analytics/{reference_key}?period={period}

Retrieve analytics data for a specific service by reference key. It groups request statistics by day, week, or month over the past year, helping analyze request patterns over time.

Path Parameters:

reference_key (string): The unique identifier for the service to retrieve analytics for.

Query Parameters:

period (string): Time aggregation period. Must be one of: "day", "week", or "month".

Response:

[
  {
    "period_start": "2025-03-01",
    "total_requests": 1250
  },
  {
    "period_start": "2025-03-08",
    "total_requests": 987
  }
]

Clear Block IP List Cache - GET /v1/block-ip-list/clear_cache

Clears the cache for block IP list data.

Response:

{
  "message": "OK"
}

Get Top IPs by Priority - GET /v1/block-ip-list/get/top/{amount}

Returns the top N IP addresses from the block list, sorted by priority. Output format can be customized.

Path Parameters:

amount (integer): Number of top IPs to return.

Query Parameters:

format (string, optional): Output format. Defaults to "plain". Available formats: "plain", "f5", "checkpoint", "cisco", "mikrotik", "sophos", "fortinet", "paloalto".

Response:

A formatted text output of IPs according to the specified format.

Decrease IP Priority - POST /v1/block-ip-list/decrease-priority

Decreases the priority of a specified range of IP addresses.

Request Body:

{
  "ip": "192.168.1.0/24"
}

Response:

{
  "message": "OK"
}

Add IP to Block List - POST /v1/block-ip-list/add

Adds a new IP or IP range to the block list with optional tags and priority.

Request Body:

{
  "ip": "192.168.1.0/24",
  "priority": "5",
  "tags": ["wordpress", "bruteforce"]
}

Response:

{
  "message": "Inserted 256 records"
}

Add Reference IP Range - POST /v1/block-ip-list/reference/add

Adds a reference range of IPs to the system, helps analyze overlaps with block list tags.

Request Body:

{
  "start_ip": "192.168.1.1",
  "end_ip": "192.168.1.10",
  "tags": ["tor", "proxy"]
}

Response:

{
  "message": "Inserted 1 records"
}

Error Responses

All endpoints may return the following error responses:

400 Bad Request: When the request is malformed or contains invalid parameters.
500 Internal Server Error: When an unexpected error occurs during request processing.

Error responses include a detail message:

{
  "detail": "Error message"
}

Technical Implementation Notes

The API uses FastAPI with Uvicorn workers and Gunicorn for ASGI handling.
Database operations are performed using asyncpg with connection pooling.
The system includes an AnalyticsMiddleware that automatically logs service usage.
IP addresses are managed efficiently using CIDR notation with a maximum of 1024 IPs per CIDR range.
All data is cached for performance, with configurable cache lifetimes.