Vendor Risk Calculator API

A FastAPI-based service that calculates vendor security risk scores based on breach data from Hudson Rock Cavalier API and lookalike domain detection using dnstwist.

Features

• Breach Data Analysis: Retrieves employee, user, and third-party breach information from Hudson Rock
• Password Strength Assessment: Analyzes password quality distribution (too weak, weak, medium, strong)
• Lookalike Domain Detection: Identifies typosquatting domains using dnstwist
• Risk Scoring: Calculates a 0-10 risk score based on multiple security factors
• Rate Limiting: Built-in rate limiter for Hudson Rock API (50 requests per 10 seconds)
• Docker Support: Fully containerized with Docker and Docker Compose

Architecture

┌─────────────┐
│   Client    │
└──────┬──────┘
       │ POST /analyze
       ▼
┌─────────────────────┐
│   FastAPI Server    │
│   (Port 80)         │
└──────┬──────────────┘
       │
       ├─► Hudson Rock API (breach data)
       │
       └─► dnstwist (lookalike domains)

Quick Start

Prerequisites

• Docker
• Docker Compose

Installation & Running

1. Clone or navigate to the project directory

   cd Risker

2. Build and start the service

   docker-compose up --build

3. Run in background

   docker-compose up -d

4. Stop the service

   docker-compose down

5. View logs

   docker-compose logs -f

API Usage

Endpoint

POST /analyze

Analyzes a vendor domain and returns comprehensive risk assessment.

Request

{
  "domain": "example.com"
}

Parameters:

• domain (string, required): Domain name or URL to analyze (e.g., "example.com" or "https://example.com")

Response Structure

{
  "capture": {
    "domain": "example.com",
    "breaches": {
      "employees": 10,
      "users": 250,
      "third_parties": 5,
      "total": 265
    },
    "passwords": {
      "total": 350,
      "weak_pct": 65.5,
      "strong_pct": 34.5
    },
    "last_breach_utc": "2024-11-25T00:00:00+00:00",
    "compromised_urls": 100,
    "total_stealers": 33000,
    "lookalikes": {
      "registered": 15,
      "with_mx": 3
    }
  },
  "risk": {
    "domain": "example.com",
    "risk_score": 7.85,
    "breaches": {
      "employees": 10,
      "users": 250,
      "third_parties": 5,
      "total": 265
    },
    "weak_password_pct": 65.5,
    "days_since_breach": 21,
    "compromised_urls": 100,
    "lookalikes_with_mx": 3
  }
}

Response Fields Explained

Capture Data:

• domain: Analyzed domain name
• breaches: Count of breached accounts by type
• passwords: Password strength distribution and percentages
• last_breach_utc: Most recent breach timestamp
• compromised_urls: Number of compromised URLs/subdomains
• total_stealers: Total stealer malware instances found
• lookalikes.registered: Number of registered typosquatting domains
• lookalikes.with_mx: Lookalike domains with MX records (email capability)

Risk Data:

• risk_score: Overall risk score (0-10, higher = riskier)
• weak_password_pct: Percentage of weak passwords
• days_since_breach: Days since most recent breach
• lookalikes_with_mx: High-risk lookalike domains

Risk Score Calculation

The risk score (0-10) is calculated based on:

• Breach Volume (up to 6 points): Employee, user, and third-party compromises
• Password Quality (up to 2.5 points): Percentage of weak passwords
• Breach Recency (up to 2 points): More recent = higher score
• Attack Surface (up to 1.5 points): Compromised subdomains and stealer diversity
• Lookalike Threats (up to 2 points): Typosquatting domains, especially with email capability

Examples

Using curl

curl -X POST "http://localhost/analyze" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

Using Python

import requests

response = requests.post(
    "http://localhost/analyze",
    json={"domain": "example.com"}
)

data = response.json()
print(f"Risk Score: {data['risk']['risk_score']}/10")
print(f"Total Breaches: {data['capture']['breaches']['total']}")

Using PowerShell

$body = @{
    domain = "example.com"
} | ConvertTo-Json

Invoke-RestMethod -Method Post -Uri "http://localhost/analyze" `
    -ContentType "application/json" -Body $body

Using JavaScript/Node.js

const response = await fetch('http://localhost/analyze', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ domain: 'example.com' })
});

const data = await response.json();
console.log(`Risk Score: ${data.risk.risk_score}/10`);

Interactive API Documentation

FastAPI automatically generates interactive documentation:

• Swagger UI: http://localhost/docs
• ReDoc: http://localhost/redoc

Project Structure

Risker/
├── main.py              # FastAPI application and risk calculation logic
├── requirements.txt     # Python dependencies
├── Dockerfile          # Docker container configuration
├── docker-compose.yml  # Docker Compose orchestration
├── .dockerignore       # Docker build exclusions
└── README.md          # This file

Dependencies

• FastAPI: Modern web framework for building APIs
• Uvicorn: ASGI server for running FastAPI
• Pydantic: Data validation using Python type hints
• requests: HTTP library for API calls
• tldextract: Domain name parsing
• python-dateutil: Date parsing utilities
• dnstwist: Domain typosquatting detection

Rate Limits

The application enforces Hudson Rock API rate limits:

• 50 requests per 10 seconds
• Automatic queuing and waiting when limit is reached
• Thread-safe implementation for concurrent requests

Error Handling

The API returns HTTP 500 with error details if:

• Hudson Rock API is unavailable
• Invalid domain format
• Network connectivity issues
• dnstwist execution fails

Security Considerations

• All API warnings are suppressed for cleaner logs
• No authentication required (add reverse proxy with auth if needed)
• CORS not configured (configure if frontend integration needed)
• Runs on port 80 (may require elevated privileges outside Docker)

Development

Running Locally Without Docker

1. Install Python 3.11+
2. Install dependencies:

   pip install -r requirements.txt

3. Run the application:

   python main.py

Environment Variables

None required. All configuration is hardcoded for simplicity.

Performance

• Average response time: 10-30 seconds (depends on dnstwist execution)
• Memory usage: ~100-200 MB per container
• Recommended for low-to-medium traffic (< 100 concurrent requests)

Troubleshooting

Service won't start on port 80:

• Ensure port 80 is not in use: netstat -ano | findstr :80
• Run with elevated privileges or change port in docker-compose.yml

Slow response times:

• dnstwist domain scanning can take 15-30 seconds
• Consider implementing caching for frequently queried domains

Hudson Rock API errors:

• Check rate limiting (50 req/10sec)
• Verify network connectivity to cavalier.hudsonrock.com

License

This project is provided as-is for security assessment purposes.

Credits

• Hudson Rock Cavalier API: Breach data provider
• dnstwist: Lookalike domain detection tool

Support

For issues or questions, please review the code or check the interactive API documentation at /docs.