safebrowsing-rs/sbserver/README.md

sbserver

A Safe Browsing proxy server that provides a local HTTP API for Safe Browsing URL lookups and includes a URL redirector with interstitial warning pages.

Installation

From the workspace root:

cargo build --bin sbserver

Usage

Basic Usage

Start the server with your API key:

sbserver --api-key YOUR_API_KEY

Start the server on a specific address:

sbserver --api-key YOUR_API_KEY --bind-addr 0.0.0.0:8080

Options

• --api-key <API_KEY>: Google Safe Browsing API key (required)
• --bind-addr <BIND_ADDR>: Server bind address (default: 127.0.0.1:8080)
• -v, --verbose: Enable verbose logging
• --update-period <SECONDS>: Update period in seconds for threat lists (default: 1800)
• --client-id <ID>: Client ID for API requests
• --client-version <VERSION>: Client version for API requests

Environment Variables

You can set the API key via environment variable:

export SAFEBROWSING_API_KEY=your_api_key_here
sbserver --bind-addr 0.0.0.0:8080

API Endpoints

1. Health Check

GET / - Returns a simple HTML page confirming the server is running.

2. Safe Browsing API Proxy

POST /v4/threatMatches:find - Compatible with Google Safe Browsing API format.

Request body:

{
  "threatInfo": {
    "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes": ["ANY_PLATFORM"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"url": "http://example.com"},
      {"url": "https://malware.example.com"}
    ]
  }
}

Response:

{
  "matches": [
    {
      "threatType": "MALWARE",
      "platformType": "ANY_PLATFORM",
      "threatEntryType": "URL",
      "threat": {"url": "https://malware.example.com"},
      "cacheDuration": "300s"
    }
  ]
}

3. URL Redirector with Warnings

GET /r?url= - Checks URL safety and either redirects or shows warning page.

Examples:

• GET /r?url=http%3A//example.com - Safe URL, redirects immediately
• GET /r?url=http%3A//malware.example.com - Unsafe URL, shows warning page

Examples

Start Server

# Start on default address (127.0.0.1:8080)
sbserver --api-key YOUR_API_KEY

# Start on all interfaces
sbserver --api-key YOUR_API_KEY --bind-addr 0.0.0.0:8080

# Start with verbose logging
sbserver --api-key YOUR_API_KEY --verbose

Test API Endpoint

curl -X POST http://localhost:8080/v4/threatMatches:find \
  -H "Content-Type: application/json" \
  -d '{
    "threatInfo": {
      "threatTypes": ["MALWARE"],
      "platformTypes": ["ANY_PLATFORM"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [{"url": "http://example.com"}]
    }
  }'

Test URL Redirector

# Safe URL - will redirect
curl -i "http://localhost:8080/r?url=http%3A//example.com"

# Unsafe URL - will show warning page
curl -i "http://localhost:8080/r?url=http%3A//malware.example.com"

Use Cases

1. Proxy for Applications

Use as a local proxy to reduce direct API calls to Google Safe Browsing:

import requests

response = requests.post('http://localhost:8080/v4/threatMatches:find', json={
    'threatInfo': {
        'threatTypes': ['MALWARE', 'SOCIAL_ENGINEERING'],
        'platformTypes': ['ANY_PLATFORM'],
        'threatEntryTypes': ['URL'],
        'threatEntries': [{'url': 'http://example.com'}]
    }
})

matches = response.json().get('matches', [])
if matches:
    print("⚠️  Unsafe URL detected!")
else:
    print("✅ URL is safe")

2. Browser Integration

Use the redirector endpoint to add Safe Browsing protection to web browsers or proxies:

<!-- Replace direct links with redirector -->
<a href="http://localhost:8080/r?url=http%3A//example.com">Visit Example</a>

3. Network Gateway

Deploy as a network gateway service to check URLs before allowing access.

Security Considerations

• The server performs no authentication - secure it appropriately for your environment
• Consider running behind a reverse proxy (nginx, Caddy, etc.) for production use

Performance

• The server maintains an in-memory threat database that updates every 30 minutes by default
• Adjust --update-period to control update frequency vs. API usage
• The server handles concurrent requests efficiently
• Consider horizontal scaling for high-traffic scenarios

API Key

You need a Google Safe Browsing API key to use this server. You can get one from the Google Cloud Console by enabling the Safe Browsing API.