Firewall
Bu sayfa henüz Türkçeye çevrilmedi. İngilizce sürüm gösteriliyor.
GET /api/v1/accounts/{username}/firewall/blocked-ips
List IPs blocked from one account
The server-wide blocked list; there is no per-account scoping, so it is identical for every account. An unknown account answers 404 ACCOUNT_NOT_FOUND.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
username |
string | yes | pattern=^[a-z][a-z0-9]{2,15}$ |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_list_BlockedIPResponse__ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": [
{
"comment": "...",
"id": "...",
"ip": "..."
}
],
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/accounts/{username}/firewall/blocked-ips
POST /api/v1/accounts/{username}/firewall/blocked-ips
Block IP for one account
Blocks the address on the server firewall. There is no per-account scoping: the block affects every site on the server and the response says so in warnings. An unknown account answers 404 ACCOUNT_NOT_FOUND.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
username |
string | yes | pattern=^[a-z][a-z0-9]{2,15}$ |
Body fields:
| Field | Type | Required | Notes |
|---|---|---|---|
comment |
string | no | — |
ip |
string | yes | IP address or CIDR block to block |
Request body example:
{
"comment": "string",
"ip": "string"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_dict_str__Any__ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
-H "Content-Type: application/json" \
-d @body.json \
https://your-server:2000/api/v1/accounts/{username}/firewall/blocked-ips
DELETE /api/v1/accounts/{username}/firewall/blocked-ips/{ip}
Unblock IP for one account
Removes the block from the server firewall — the same rule the server-wide endpoint manages. An unknown account answers 404 ACCOUNT_NOT_FOUND, an address that is not blocked 404 NOT_FOUND.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
username |
string | yes | pattern=^[a-z][a-z0-9]{2,15}$ |
ip |
string | yes | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X DELETE \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/accounts/{username}/firewall/blocked-ips/{ip}
GET /api/v1/accounts/{username}/firewall/ip-blocks
List addresses blocked on one account's sites
The account's own block list. The block is written into every vhost of the account (nginx deny; Apache Require not ip when Apache faces visitors itself): it refuses the address on this account's sites only and never touches the server firewall. The address is the visitor's as the web server sees it (behind Cloudflare, the real visitor address). An unknown account answers 404 ACCOUNT_NOT_FOUND.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
username |
string | yes | pattern=^[a-z][a-z0-9]{2,15}$ |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_list_AccountIPBlockResponse__ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": [
{
"comment": "...",
"created_at": "...",
"id": "...",
"ip": "..."
}
],
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/accounts/{username}/firewall/ip-blocks
POST /api/v1/accounts/{username}/firewall/ip-blocks
Block an address on one account's sites
Adds one address or network (IPv4 up to /16, IPv6 up to /48) to the account's block list. The block is written into every vhost of the account (nginx deny; Apache Require not ip when Apache faces visitors itself): it refuses the address on this account's sites only and never touches the server firewall. The address is the visitor's as the web server sees it (behind Cloudflare, the real visitor address). An address already on the list answers 200 unchanged. At most 500 entries (422). OpenLiteSpeed / LiteSpeed hosts answer 409 FEATURE_DISABLED; a configuration the web server refuses keeps the previous list (500 VHOST_CONFIG_ERROR).
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
username |
string | yes | pattern=^[a-z][a-z0-9]{2,15}$ |
Body fields:
| Field | Type | Required | Notes |
|---|---|---|---|
comment |
string | no | — |
ip |
string | yes | IP address or CIDR block to block |
Request body example:
{
"comment": "string",
"ip": "string"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_AccountIPBlockResponse_ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {
"comment": "...",
"created_at": "...",
"id": "string",
"ip": "string"
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
-H "Content-Type: application/json" \
-d @body.json \
https://your-server:2000/api/v1/accounts/{username}/firewall/ip-blocks
DELETE /api/v1/accounts/{username}/firewall/ip-blocks/{ip}
Unblock an address on one account's sites
Removes the entry (ip URL-encoded, a network as listed, e.g. 203.0.113.0%2F24). An address that is not on the account's list answers 404 NOT_FOUND.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
username |
string | yes | pattern=^[a-z][a-z0-9]{2,15}$ |
ip |
string | yes | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X DELETE \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/accounts/{username}/firewall/ip-blocks/{ip}
GET /api/v1/firewall/attack-mode
Attack mode status
DDoS-mitigation mode state + the layers currently applied + auto-mode config.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_AttackModeStatusExtended_ |
Successful Response |
Response example (200):
{
"data": {
"active": false,
"auto_mode": "...",
"enabled_at": "...",
"optimizations": [
"..."
]
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/attack-mode
POST /api/v1/firewall/attack-mode/auto-disable
Disable auto-attack-mode
Stops the velocity watcher. Manually-enabled attack mode is preserved. Answers the auto-mode state.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_AutoModeStatus_ |
Successful Response |
Response example (200):
{
"data": {
"auto_enabled_at": "...",
"enabled": false,
"last_score": 0,
"last_triggered_at": "..."
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/attack-mode/auto-disable
POST /api/v1/firewall/attack-mode/auto-enable
Enable auto-attack-mode
Background watcher monitors blocked-IP velocity; attack mode triggers automatically above threshold. Answers the auto-mode state.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_AutoModeStatus_ |
Successful Response |
Response example (200):
{
"data": {
"auto_enabled_at": "...",
"enabled": false,
"last_score": 0,
"last_triggered_at": "..."
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/attack-mode/auto-enable
POST /api/v1/firewall/attack-mode/disable
Disable attack mode
Restores the values read before the mode was enabled and removes the applied layers. Existing bans are preserved. Not active answers 409 ATTACK_MODE_INACTIVE.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_AttackModeStatusExtended_ |
Successful Response |
Response example (200):
{
"data": {
"active": false,
"auto_mode": "...",
"enabled_at": "...",
"optimizations": [
"..."
]
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/attack-mode/disable
POST /api/v1/firewall/attack-mode/enable
Enable attack mode
Applies the hardening layers (kernel sysctl through systemd-sysctl, a SYN-flood / connlimit chain ahead of the firewall's own chains, the nginx rate-limit snippet, tighter fail2ban thresholds) and reports which ones took. Manual toggle — see auto-enable for automated. Already active answers 409 ATTACK_MODE_ACTIVE.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_AttackModeStatusExtended_ |
Successful Response |
Response example (200):
{
"data": {
"active": false,
"auto_mode": "...",
"enabled_at": "...",
"optimizations": [
"..."
]
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/attack-mode/enable
GET /api/v1/firewall/blocked-ips
List blocked IPs (server-wide)
The plain source denies the packet filter carries, each with the comment it was blocked with. Response data: a list of {id, ip, comment}.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_list_BlockedIPResponse__ |
Successful Response |
Response example (200):
{
"data": [
{
"comment": "...",
"id": "...",
"ip": "..."
}
],
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/blocked-ips
POST /api/v1/firewall/blocked-ips
Block IP (server-wide)
Add a manual block on a source IP / CIDR: a source deny in the packet filter plus an entry in the HTTP-layer ban list. A whitelisted address answers 409 IP_WHITELISTED; the caller's own address answers 422 SELF_LOCKOUT; a network wider than /16 (IPv4) or /48 (IPv6) answers 422 VALIDATION_ERROR.
Body fields:
| Field | Type | Required | Notes |
|---|---|---|---|
comment |
string | no | — |
ip |
string | yes | IP address or CIDR block to block |
Request body example:
{
"comment": "string",
"ip": "string"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_BlockedIPResponse_ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {
"comment": "...",
"id": "string",
"ip": "string"
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
-H "Content-Type: application/json" \
-d @body.json \
https://your-server:2000/api/v1/firewall/blocked-ips
POST /api/v1/firewall/blocked-ips/clear-all
Clear every blocked IP
Bulk unblock: every source deny in the packet filter (with or without a port scope), every HTTP-layer ban, every rate-limit ban set member and every fail2ban ban. The security log is not touched — see DELETE /firewall/logs.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_ClearAllResult_ |
Successful Response |
Response example (200):
{
"data": {
"fail2ban_jails": 0,
"http_bans": 0,
"rate_limit_bans": 0,
"removed": 0,
"ufw_rules": 0
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/blocked-ips/clear-all
DELETE /api/v1/firewall/blocked-ips/{ip}
Unblock IP
Removes the manual block for the specified IP / CIDR: the source deny and the firewall's own HTTP-layer entries (the block and a timed auto-ban entry). A fail2ban jail's ban of the same address stays on the HTTP-layer list until that jail lifts it. An address that is neither a source deny nor on the HTTP-layer list answers 404 NOT_FOUND; a whitelist rule of the same address is left alone.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
ip |
string | yes | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X DELETE \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/blocked-ips/{ip}
POST /api/v1/firewall/disable
Disable host firewall
Deactivates UFW / firewalld — all rules become inert.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/disable
POST /api/v1/firewall/enable
Enable host firewall
Activates UFW / firewalld. Existing rules are applied immediately.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/enable
DELETE /api/v1/firewall/logs
Clear the security log
Deletes every block and suspicious event record. Irreversible; the blocks themselves are not touched (see POST /firewall/blocked-ips/clear-all).
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_dict_str__int__ |
Successful Response |
Response example (200):
{
"data": {},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X DELETE \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/logs
GET /api/v1/firewall/logs/blocked
Blocked-request log
Block events grouped by address and type, newest first: {events: BlockedEvent[], total}. ip (exact, CIDR or a partial address), type (rate_limit / under_attack / manual / autoban / denied — a 403 answered before authentication: admin allowlist, missing panel bundle header), since / until (ISO-8601) narrow the page; a filter that cannot be a host, a type outside the list or a value that is not a timestamp answers 422.
Query parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
limit |
integer | no | minimum=1; maximum=1000 |
offset |
integer | no | minimum=0 |
ip |
string | no | — |
type |
string | no | — |
since |
string | no | — |
until |
string | no | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_dict_str__Any__ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/logs/blocked
GET /api/v1/firewall/logs/stats
Firewall log statistics
Counts over the last 24 hours (blocked, suspicious, top addresses, top endpoints), twenty-four hourly buckets (UTC, YYYY-MM-DDTHH:00), the threat score and the attack-mode flag. Powers the dashboard badge.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_dict_str__Any__ |
Successful Response |
Response example (200):
{
"data": {},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/logs/stats
GET /api/v1/firewall/logs/stream
SSE — live firewall log tail
Server-Sent Events stream of new block events as they are written (one data: [...] array per poll, a heartbeat with the threat score otherwise). Binary text/event-stream.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
— | Successful Response |
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/logs/stream
GET /api/v1/firewall/logs/suspicious
Suspicious-request log
Pre-block events flagged by heuristics (scan patterns, injection attempts, floods), grouped by address and category, newest first: {events: SuspiciousEvent[], total}. The same filters as the blocked log apply (category instead of type).
Query parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
limit |
integer | no | minimum=1; maximum=1000 |
offset |
integer | no | minimum=0 |
ip |
string | no | — |
category |
string | no | — |
since |
string | no | — |
until |
string | no | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_dict_str__Any__ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/logs/suspicious
GET /api/v1/firewall/notifications
Firewall-specific notifications
Sub-inbox for firewall events (attack mode triggered, high threat score); the same records the shared inbox holds under the firewall category.
Query parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
limit |
integer | no | minimum=1; maximum=200 |
unread_only |
boolean | no | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_list_PanelNotification__ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": [
{
"category": "...",
"id": "...",
"level": "...",
"message": "...",
"read": "...",
"target": "...",
"timestamp": "...",
"title": "...",
"username": "..."
}
],
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/notifications
POST /api/v1/firewall/notifications/read-all
Mark all firewall notifications as read
Bulk operation across the admin-scope inbox.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/notifications/read-all
POST /api/v1/firewall/notifications/{notif_id}/read
Mark firewall notification as read
Flip the read flag for one firewall-scope notification.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
notif_id |
string | yes | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/notifications/{notif_id}/read
GET /api/v1/firewall/rate-limits
List rate-limit rules
Port-based rate-limit rules ({id, name, port, protocol, threshold, window_seconds, ban_duration, enabled, created_at}); each enabled rule is a hashlimit rule plus a ban set in the packet filter. An unreadable rule store answers 500 SERVICE_ERROR rather than an empty list.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_list_RateLimitRuleResponse__ |
Successful Response |
Response example (200):
{
"data": [
{
"ban_duration": "...",
"created_at": "...",
"enabled": "...",
"id": "...",
"name": "...",
"port": "...",
"protocol": "...",
"threshold": "...",
"window_seconds": "..."
}
],
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/rate-limits
POST /api/v1/firewall/rate-limits
Create rate-limit rule
Define a new rate-limit rule (port / port list / range or any, protocol, max new connections per source address per window, ban duration). The rules run in their own chain ahead of the host firewall; loopback traffic and whitelisted addresses are never counted or banned. The rule is stored only after the packet filter accepted it; a refused rule answers 500 RATE_LIMIT_APPLY_FAILED.
Body fields:
| Field | Type | Required | Notes |
|---|---|---|---|
ban_duration |
integer | yes | Ban duration in seconds (0 = permanent); minimum=0.0; maximum=604800.0 |
name |
string | yes | minLength=1; maxLength=100 |
port |
string | no | Port, comma-separated ports, range (e.g. '80', '80,443', '8000:9000'), or 'any'; default any |
protocol |
string | no | default tcp; enum: tcp, udp, all |
threshold |
integer | yes | Max new connections one source address may open in the time window; minimum=1.0; maximum=100000.0 |
window_seconds |
integer | yes | Time window in seconds; minimum=1.0; maximum=86400.0 |
Request body example:
{
"ban_duration": 0,
"name": "string",
"port": "any",
"protocol": "tcp",
"threshold": 1.0,
"window_seconds": 1.0
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_RateLimitRuleResponse_ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {
"ban_duration": 0,
"created_at": "string",
"enabled": false,
"id": "string",
"name": "string",
"port": "string",
"protocol": "string",
"threshold": 0,
"window_seconds": 0
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
-H "Content-Type: application/json" \
-d @body.json \
https://your-server:2000/api/v1/firewall/rate-limits
GET /api/v1/firewall/rate-limits/banned
List IPs currently banned by rate-limit rules
Aggregated active bans across every rate-limit rule. Each entry is {ip, rule_id, rule_name}.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_list_dict_str__Any___ |
Successful Response |
Response example (200):
{
"data": [
{}
],
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/rate-limits/banned
DELETE /api/v1/firewall/rate-limits/banned/{ip}
Unban IP across every rate-limit rule
Lifts the IP's rate-limit ban on every rule; the message says how many ban sets carried it. A malformed address answers 422.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
ip |
string | yes | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X DELETE \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/rate-limits/banned/{ip}
DELETE /api/v1/firewall/rate-limits/{rule_id}
Delete rate-limit rule
Removes the rule + every active ban it produced. An unknown rule answers 404 NOT_FOUND.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
rule_id |
string | yes | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X DELETE \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/rate-limits/{rule_id}
PUT /api/v1/firewall/rate-limits/{rule_id}
Update rate-limit rule
Patch name, port, protocol, threshold, window, ban duration or enabled. The kernel objects are rebuilt; when the new shape is refused the old one is put back. An unknown rule answers 404 NOT_FOUND.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
rule_id |
string | yes | — |
Body fields:
| Field | Type | Required | Notes |
|---|---|---|---|
ban_duration |
integer | no | — |
enabled |
boolean | no | — |
name |
string | no | — |
port |
string | no | — |
protocol |
string | no | — |
threshold |
integer | no | — |
window_seconds |
integer | no | — |
Request body example:
{
"ban_duration": 0,
"enabled": false,
"name": "string",
"port": "string",
"protocol": "tcp",
"threshold": 1.0,
"window_seconds": 1.0
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_RateLimitRuleResponse_ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {
"ban_duration": 0,
"created_at": "string",
"enabled": false,
"id": "string",
"name": "string",
"port": "string",
"protocol": "string",
"threshold": 0,
"window_seconds": 0
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X PUT \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
-H "Content-Type: application/json" \
-d @body.json \
https://your-server:2000/api/v1/firewall/rate-limits/{rule_id}
POST /api/v1/firewall/rate-limits/{rule_id}/unban/{ip}
Unban IP from one rate-limit rule
Targeted unban — only the named rule is affected, other rules' bans remain. An unknown rule answers 404 NOT_FOUND.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
rule_id |
string | yes | — |
ip |
string | yes | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/rate-limits/{rule_id}/unban/{ip}
GET /api/v1/firewall/rules
List firewall rules
Every port rule the backend carries — global and source-scoped — with id ({port}-{protocol} or {port}-{protocol}--{source_ip}), action (allow/deny/limit/reject), port, protocol (any when the rule names none), source_ip and comment. Plain source allows (the whitelist) and plain source denies (the blocked list) are not port rules.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_list_FirewallRuleResponse__ |
Successful Response |
Response example (200):
{
"data": [
{
"action": "...",
"comment": "...",
"id": "...",
"port": "...",
"protocol": "...",
"source_ip": "..."
}
],
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/rules
POST /api/v1/firewall/rules
Create firewall rule
Add a new allow/deny rule. Triggers immediate ufw reload / firewall-cmd --reload.
Body fields:
| Field | Type | Required | Notes |
|---|---|---|---|
action |
string | no | default allow; enum: allow, deny |
port |
string | yes | Port number or range (e.g. '80', '8000:8080') |
protocol |
string | no | default tcp; enum: tcp, udp |
source_ip |
string | no | Restrict rule to a specific source IP or CIDR (optional) |
Request body example:
{
"action": "allow",
"port": "string",
"protocol": "tcp",
"source_ip": "string"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_FirewallRuleResponse_ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {
"action": "string",
"comment": "...",
"id": "string",
"port": "string",
"protocol": "string",
"source_ip": "..."
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
-H "Content-Type: application/json" \
-d @body.json \
https://your-server:2000/api/v1/firewall/rules
DELETE /api/v1/firewall/rules/{rule_id}
Delete firewall rule
Remove the rule and reload the firewall. A rule that does not exist answers 404 NOT_FOUND.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
rule_id |
string | yes | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X DELETE \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/rules/{rule_id}
PUT /api/v1/firewall/rules/{rule_id}
Update firewall rule
Replace an existing rule's action / source / port. A rule id that does not exist answers 404 NOT_FOUND; when the new rule is refused the old one is put back.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
rule_id |
string | yes | — |
Body fields:
| Field | Type | Required | Notes |
|---|---|---|---|
action |
string | no | default allow; enum: allow, deny |
port |
string | yes | Port number or range (e.g. '80', '8000:8080') |
protocol |
string | no | default tcp; enum: tcp, udp |
source_ip |
string | no | Restrict rule to a specific source IP or CIDR (optional) |
Request body example:
{
"action": "allow",
"port": "string",
"protocol": "tcp",
"source_ip": "string"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_FirewallRuleResponse_ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {
"action": "string",
"comment": "...",
"id": "string",
"port": "string",
"protocol": "string",
"source_ip": "..."
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X PUT \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
-H "Content-Type: application/json" \
-d @body.json \
https://your-server:2000/api/v1/firewall/rules/{rule_id}
GET /api/v1/firewall/status
UFW / firewalld status
Host firewall state: backend (UFW or firewalld), enabled flag, the number of port rules and of blocked addresses (plain source denies).
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_FirewallStatusResponse_ |
Successful Response |
Response example (200):
{
"data": {
"active": false,
"backend": "string",
"blocked_count": 0,
"output": "",
"rules_count": 0
},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/status
GET /api/v1/firewall/whitelist
Firewall whitelist
Addresses let through on every port and exempt from auto-bans. Response data: a list of {ip, comment, applied} — applied says whether the packet filter carries the allow rule right now.
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_list_WhitelistEntryResponse__ |
Successful Response |
Response example (200):
{
"data": [
{
"applied": "...",
"comment": "...",
"ip": "..."
}
],
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X GET \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/whitelist
POST /api/v1/firewall/whitelist
Add IP to firewall whitelist
Idempotent — an entry already present keeps its record, and its allow rule is re-installed when the firewall lost it. The address is taken off the HTTP-layer ban list whatever put it there (a block, an auto-ban, a fail2ban jail). A network wider than /16 (IPv4) or /48 (IPv6) answers 422 VALIDATION_ERROR.
Body fields:
| Field | Type | Required | Notes |
|---|---|---|---|
comment |
string | no | — |
ip |
string | yes | IP address or CIDR block to block |
Request body example:
{
"comment": "string",
"ip": "string"
}
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
ApiSuccess_dict_str__Any__ |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"data": {},
"message": "",
"status": "success",
"warnings": [
"string"
]
}
cURL example:
curl -X POST \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
-H "Content-Type: application/json" \
-d @body.json \
https://your-server:2000/api/v1/firewall/whitelist
DELETE /api/v1/firewall/whitelist/{ip}
Remove IP from whitelist
The IP returns to normal firewall enforcement.
Path parameters:
| Name | Type | Required | Notes |
|---|---|---|---|
ip |
string | yes | — |
Responses:
| Status | Schema | Description |
|---|---|---|
200 |
MessageResponse |
Successful Response |
422 |
HTTPValidationError |
Validation Error |
Response example (200):
{
"message": "string",
"status": "success"
}
cURL example:
curl -X DELETE \
-H "X-WHost-Key: $WHOST_API_KEY" \
-H "X-WHost-Timestamp: $(date +%s)" \
-H "X-WHost-Nonce: $(openssl rand -hex 16)" \
-H "X-WHost-Signature: $(compute_hmac)" \
https://your-server:2000/api/v1/firewall/whitelist/{ip}
Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.