Blacklist & Whitelist API

Base URL: http://localhost:8011/api (via UI proxy) or http://localhost:5001/api (direct backend).

All endpoints require Basic Auth.

---

IP Blacklist

List entries

GET /api/ip-blacklist

Response:

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "ip": "203.0.113.5",
      "description": "known malicious",
      "added_date": "2026-03-01T12:00:00"
    }
  ]
}

Add entry

POST /api/ip-blacklist

Request body:

{
  "ip": "203.0.113.0/24",
  "description": "optional description"
}

Delete entry

DELETE /api/ip-blacklist/{id}

Bulk delete entries

POST /api/ip-blacklist/bulk-delete

Request body:

{
  "ids": [1, 2, 3]
}

Clear all entries

DELETE /api/ip-blacklist/clear-all

---

Domain Blacklist

List entries

GET /api/domain-blacklist

Response:

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "domain": "malicious.com",
      "description": "",
      "added_date": "2026-03-01T12:00:00"
    }
  ]
}

Add entry

POST /api/domain-blacklist

Request body:

{
  "domain": "*.ads.example.com",
  "description": "optional description"
}

Delete entry

DELETE /api/domain-blacklist/{id}

Bulk delete entries

POST /api/domain-blacklist/bulk-delete

Request body:

{
  "ids": [1, 2, 3]
}

Clear all entries

DELETE /api/domain-blacklist/clear-all

---

Import

Import multiple entries from a URL or inline content.

POST /api/blacklists/import

Request body — from URL:

{
  "type": "domain",
  "url": "https://example.com/domains.txt"
}

Request body — inline content:

{
  "type": "ip",
  "content": "192.0.2.1\n198.51.100.0/24\n203.0.113.5"
}

type must be "domain" or "ip".

Response:

{
  "status": "success",
  "message": "Import completed",
  "data": {
    "added": 150,
    "skipped": 3,
    "errors": ["Invalid format: not-an-ip"]
  }
}

Supported file formats:

• Plain text, one entry per line
• JSON array: ["entry1", "entry2"]
• JSON objects: [{"domain": "example.com"}]
• Lines starting with # are ignored

SSRF protection

Import URLs are validated against SSRF rules. Private IP ranges, loopback, and link-local addresses are rejected.

---

Geo Import

Import IP ranges for one or more countries.

POST /api/blacklists/import-geo

Request body:

{
  "countries": ["RU", "CN", "KP"]
}

---

IP Whitelist

Whitelisted destination IPs bypass the direct-IP block rule in Squid.

List entries

GET /api/ip-whitelist

Response:

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "ip": "192.168.1.50",
      "description": "Home NAS",
      "added_date": "2026-03-01T12:00:00"
    }
  ]
}

Add entry

POST /api/ip-whitelist

Request body:

{
  "ip": "192.168.1.0/24",
  "description": "LAN subnet"
}

Delete entry

DELETE /api/ip-whitelist/{id}

---

Domain Whitelist

Whitelisted domains bypass the DNS blackhole (dnsmasq). Domains in this list are excluded from the dnsmasq blocklist so they resolve normally even if they appear in the domain blacklist. Useful for essential services that need DNS resolution.

List entries

GET /api/domain-whitelist

Response:

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "domain": "github.com",
      "type": "fqdn",
      "description": "Essential - code hosting",
      "added_date": "2026-03-01T12:00:00"
    }
  ]
}

Add entry

POST /api/domain-whitelist

Request body:

{
  "domain": "github.com",
  "description": "Essential - code hosting"
}

Delete entry

DELETE /api/domain-whitelist/{id}