Threat Intelligence

Surface Security integrates with third-party threat intelligence services for enhanced domain reputation checking during phishing detection.

Supported Services

Service	Free Tier Limits	Features
URLScan.io	60 requests/min, 1,000/day	URL scanning, malicious page detection, brand targeting analysis
VirusTotal	4 requests/min, 500/day	70+ vendor reputation checks, malicious count, domain categories

Configuration

Admin Dashboard

1. Navigate to Settings > Threat Intelligence
2. Enable or disable each service independently
3. Enter your API key for each service
4. Click Test Connection to verify your API key is valid
5. View daily usage statistics on the settings page

API

Threat intelligence settings can also be managed via the Admin API:

• GET /api/v1/admin/threat-intel/settings -- Get current service status
• PUT /api/v1/admin/threat-intel/settings -- Enable/disable services
• PUT /api/v1/admin/threat-intel/api-key -- Save an API key
• POST /api/v1/admin/threat-intel/test -- Test API key connectivity

See the Admin API reference for full request/response details.

API Key Security

• API keys are stored encrypted in the database
• Keys are never exposed to the frontend after being saved
• The test endpoint validates connectivity without revealing the stored key

Domain Scan Tracking

The backend tracks domain scan history to optimize API usage:

• Domains are only re-scanned if the last scan is older than 7 days
• Scan results (malicious status, scores) are cached in PostgreSQL
• This prevents redundant API calls and helps stay within free tier limits

Domain Scan Data

For each scanned domain, the following data is tracked:

Field	Source	Description
urlscanLastScannedAt	URLScan.io	Timestamp of last URLScan scan
urlscanIsMalicious	URLScan.io	Whether URLScan flagged the domain as malicious
vtLastScannedAt	VirusTotal	Timestamp of last VirusTotal scan
vtMaliciousCount	VirusTotal	Number of vendors flagging the domain as malicious

How It Works

1. The browser extension detects a suspicious domain (via lookalike detection, perceptual hashing, or other phishing signals)
2. The extension checks with the backend whether the domain needs scanning (GET /api/v1/ext/domain-scans/{domain})
3. If a scan is needed, the extension calls the backend's domain reputation endpoint (POST /api/v1/ext/domain-scans/check), which performs the URLScan.io or VirusTotal lookup server-side — API keys never leave the backend
4. Scan results are cached by the backend
5. Results are cached and factored into the overall phishing risk assessment

Obtaining API Keys

URLScan.io

1. Create a free account at urlscan.io
2. Navigate to your profile settings
3. Generate an API key
4. Enter the key in Surface Security under Settings > Threat Intelligence

VirusTotal

1. Create a free account at virustotal.com
2. Navigate to your API key page
3. Copy your API key
4. Enter the key in Surface Security under Settings > Threat Intelligence