IP Quality

IP Quality lets each agent assess its VPS egress IP and report the results back to the server. It does two things:

1. Service unlock detection — the agent issues HTTP requests from its egress IP to determine the unlock status of popular streaming, AI, and social services.
2. IP metadata and risk signals — the server derives country and region from its local GeoIP database, then uses the configured third-party provider for supported network-type flags and, when available, a fraud risk score.

Results appear on a dedicated IP Quality sidebar route (global overview), a per-server detail tab, and — when enabled per status page — on the public status page.

Requirements

• CAP_IP_QUALITY (bit 1024) must be enabled on the agent. It is on by default (part of CAP_DEFAULT).
• A usable GeoIP MMDB is required for local baseline metadata. If no database is loaded, those fields remain unavailable; third-party enrichment can still provide supported risk and network-type fields. See Configuration for geoip.mmdb_path.

Capability (agent-owned)

CAP_IP_QUALITY is owned by the agent host, like every capability — the server cannot turn it on or off. It is enabled by default, so no action is needed to use IP Quality. To disable it on a specific host, add ip_quality to the agent's [capabilities] deny list (or pass --deny-cap ip_quality) and restart the agent:

[capabilities]
deny = ["ip_quality"]

# Or via the command line
./serverbee-agent --deny-cap ip_quality

If the agent does not report ip_quality, the agent runs no checks and the UI shows the standard disabled placeholder. See Capabilities.

Built-In Services

Nine services are seeded at startup. Each ships with a hardcoded detector that issues an HTTP request from the agent's egress IP and interprets the response to determine unlock status.

Each service can be individually enabled or disabled in Settings → IP Quality → Service Catalog. Built-in services cannot be deleted; their detection logic is immutable.

Custom Services

In addition to the built-in set, administrators can define custom services in Settings → IP Quality → Service Catalog → Add service.

Each custom service consists of:

• URL — the endpoint to probe. Must use https:// or http:// on port 80 or 443. Private / loopback addresses are rejected at creation time and re-validated by the agent on each request and redirect hop (SSRF guard).
• Method — HTTP method (GET, HEAD, etc.) and optional request headers.
• Match rules — an ordered list of rules evaluated against the response. The first matching rule wins. Each rule matches on one of:
  • HTTP status code (exact or range)
  • Response body regex
  • Redirect target URL pattern

The possible results are unlocked, restricted, blocked, failed, or unsupported.

Check Cadence

The agent runs checks:

• On schedule — every 12 hours by default, configurable in Settings → IP Quality → Settings → Check interval.
• When the egress IP changes — the agent automatically reruns on detected IP changes.
• On demand — click Check now on any server's IP Quality tab.

Check schedules are agent-side. The server only pushes the service catalog and forwards manual triggers.

IP Metadata and Risk Scoring

After receiving unlock results from an agent, the server:

1. Derives available baseline metadata from a loaded local GeoIP MMDB, without an external request. The downloadable DB-IP Lite Country database provides country and region. If the MMDB is missing, unreadable, or does not cover the address, local baseline fields remain empty.
2. Runs the configured third-party provider unless risk_provider is none. Anonymous ipapi.is supplies proxy, VPN, datacenter, Tor, and abuse flags, which ServerBee also uses to derive IP type, but its minimal response does not contain the nested score fields. A numeric 0–100 score and risk level (low / medium / high) require an ipapi.is API key and its full response. Results are cached by IP for 24 hours, so repeated checks of the same IP do not generate repeated API calls.

If no provider returns a numeric score, risk_score and risk_level are null / unknown. Local metadata appears only when a usable MMDB is loaded.

Configuring a Risk Provider

Set ip_quality.risk_provider in server.toml (or SERVERBEE_IP_QUALITY__RISK_PROVIDER) to one of:

Default behavior (no configuration needed): the Server calls ipapi.is anonymously. Anonymous access is limited to 100 requests per client IP per UTC day and returns flags that ServerBee uses for risk signals and a derived IP type, but no numeric risk score. Only a failed primary request, including an HTTP 429 after quota exhaustion, triggers the ip-api fallback; a successful response without a score does not. The fallback can supply proxy/hosting flags and a derived IP type, but not a numeric risk score. See the official ipapi.is developer limits and pricing.

Create a free ipapi.is account and configure its API key for 1,000 requests per day and the full response required for the 0–100 score:

[ip_quality]
risk_provider = "ipapi_is"
risk_provider_fallback = "ip-api"  # default; set to "none" to disable

[ip_quality.ipapi_is]
api_key = "your_api_key"
# endpoint = "https://api.ipapi.is"  # optional; override for self-hosted instances

To disable risk scoring entirely:

[ip_quality]
risk_provider = "none"

Full configuration reference: Configuration → IP Quality.

Viewing Results

Unlock status updates appear in real time over WebSocket — no page refresh required.

Unlock Status Values

Public Status Page Exposure

IP Quality is off by default on all public status pages. To enable it for a specific page:

1. Go to Settings → Status Pages, edit the page.
2. Toggle on Show IP Quality.

For unauthenticated visitors, the egress IP is masked as *.*.*.*. Authenticated viewers see the full IP.

Retention

Status-change history events (the unlock_event log) are retained for 90 days by default. Tune with retention.ip_quality_event_days (env: SERVERBEE_RETENTION__IP_QUALITY_EVENT_DAYS). The hourly cleanup task purges expired rows automatically.

The latest unlock result and IP quality snapshot per server are kept indefinitely (they are replaced on each run, not accumulated).

Data Flow

Agent
  │  (CAP_IP_QUALITY effective)
  ├─ runs unlock checks every interval_hours / on IP change / on RunNow
  │   AgentMessage::UnlockResults  (WebSocket)
  ▼
Server
  ├─ upserts unlock_result + appends unlock_event on status change
  ├─ broadcasts BrowserMessage::IpQualityUpdate (unlock results, ip_quality: null)
  ├─ background task: ip_risk scoring (GeoIP + optional third-party provider, cache-first)
  ├─ upserts ip_quality_snapshot
  └─ broadcasts BrowserMessage::IpQualityUpdate (ip_quality: full data)
                    │
                    ▼
             /ip-quality  +  IP Quality tab  +  public status page