Skip to content

splitfireai-hue/sentinelx402

BranchesTags

Repository files navigation

SentinelX402

Free threat intelligence API for AI agents. The only API with built-in CERT-In India advisories.

Real-time phishing detection, CVE risk analysis, IP reputation, and Indian government threat advisories — all free. 1,000 requests, no signup, no API key.

Live API: https://sentinelx402-production.up.railway.app/info

Part of the Sentinel Series:

  • SentinelX402 (this) — Threat intelligence (phishing, CVE, IP reputation, CERT-In)
  • SentinelCorp — India company risk (GSTIN/CIN/PAN validation, SEBI debarred entities)

Use both together for complete India due-diligence coverage for AI agents.

What Makes This Different

Most threat intel APIs cover global threats. SentinelX402 is the only agent-native API that includes:

  • CERT-In India advisories — Official Indian government threat intel (CIAD/CIVN)
  • CSK malware alerts — Cyber Swachhta Kendra active threat monitoring
  • UPI fraud detection — Paytm, PhonePe, GPay spoofing domains
  • Indian bank phishing — SBI, HDFC, ICICI, Axis, Kotak impersonation
  • Aadhaar/PAN scams — Government impersonation phishing

Plus standard coverage:

  • OpenPhish live phishing URLs
  • Feodo Tracker C2 botnet IPs
  • URLhaus malware distribution
  • NVD CVE data with exploit probability

Use Cases

1. Phishing Detection Agent

Your agent scans URLs from emails, chat messages, or web scraping. Before opening any link, it checks SentinelX402:

from sentinelx import SentinelX

client = SentinelX(base_url="https://sentinelx402-production.up.railway.app")
risk = client.domain_lookup("login-secure-paypal.com")

if risk.is_malicious:
    print(f"BLOCKED: {risk.domain} — {risk.threat_type} (score: {risk.risk_score})")
    # → BLOCKED: login-secure-paypal.com — phishing (score: 94.0)
else:
    print("Safe to proceed")

Value: One API call prevents a phishing incident worth thousands.

2. SOC Automation / SIEM Enrichment

Your security operations pipeline processes thousands of alerts daily. Enrich each IOC automatically:

# Enrich IP from firewall alert
ip = client.ip_lookup("185.220.101.42")
if ip.is_malicious:
    trigger_alert(f"C2 server detected: {ip.threat_types}")
    # → C2 server detected: ['c2'] — tags: cobalt-strike

# Bulk domain scanning
suspicious_domains = ["amaz0n-verify.com", "google.com", "hdfc-netbanking-secure.xyz"]
for domain in suspicious_domains:
    risk = client.domain_lookup(domain)
    print(f"{domain}: {risk.risk_score} ({risk.threat_type})")

Value: Replaces hours of analyst triage with sub-second automated scoring.

3. Vulnerability Prioritization Agent

Your agent monitors new CVEs and decides which ones need immediate patching:

# Check a specific CVE
cve = client.cve_lookup("CVE-2024-3400")
print(f"CVSS: {cve.cvss}, Exploit probability: {cve.exploit_probability}")
print(f"Patch urgency: {cve.patch_urgency}, Ransomware risk: {cve.ransomware_risk}")
# → CVSS: 10.0, Exploit probability: 1.0
# → Patch urgency: critical, Ransomware risk: False

# Get this week's critical vulnerabilities
recent = client.recent_cves(limit=5)
for cve in recent.cves:
    if cve.is_critical:
        create_jira_ticket(cve.cve_id, cve.description, priority="P0")

Value: Goes beyond raw CVSS with exploit probability and ransomware risk scoring.

4. Indian Fintech Fraud Detection

Detect UPI fraud domains, Indian bank phishing, and Aadhaar/PAN scams:

risk = client.domain_lookup("sbi-online-banking-verify.com")
# → score: 96.0, type: phishing, tags: [india, banking, sbi, credential-theft]

risk = client.domain_lookup("upi-paytm-cashback-claim.com")
# → score: 97.0, type: phishing, tags: [india, upi, paytm, cashback-scam]

risk = client.domain_lookup("aadhaar-ekyc-verification.in")
# → score: 98.0, type: phishing, tags: [india, government, aadhaar, identity-theft]

Value: India-specific threat coverage that global APIs don't have.

Quickstart

1. Configure environment

cp .env.example .env
# Edit .env with your settings (defaults work out of the box)

2. Install dependencies

pip install -e .

3. Seed threat data & start

python -m app.data.seed_threats
uvicorn app.main:app --reload

Visit http://localhost:8000/docs for interactive API docs.

Production Deployment

Docker (recommended)

docker compose up -d

This starts the API server with PostgreSQL, Redis, gunicorn (4 workers), health checks, and auto-restart.

Manual

pip install ".[production]"
# Set DATABASE_URL, REDIS_URL, ENVIRONMENT=production in .env
gunicorn app.main:app \
    --worker-class uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    --workers 4

API Reference

Endpoint Method Description
/api/v1/threats/lookup?domain= GET Domain threat risk lookup — real-time phishing detection
/api/v1/threats/ip?ip= GET IP reputation check — C2 and botnet detection
/api/v1/threats/feed GET Latest threat indicators feed
/api/v1/cves/{cve_id} GET CVE risk analysis with exploit probability
/api/v1/cves/recent GET Recent critical CVEs from NVD
/api/v1/cves/search?keyword= GET Search CVEs by keyword
/api/v1/india/advisories/list GET CERT-In + CSK India advisories (proprietary)
/api/v1/india/advisories/{code} GET Specific CERT-In advisory by code
/health GET Health check
/info GET API info and endpoints

All endpoints are free for the first 1,000 requests. No signup required.

Usage Examples

Python

import httpx

client = httpx.Client(base_url="http://localhost:8000")

# Domain risk lookup
resp = client.get("/api/v1/threats/lookup", params={"domain": "login-secure-paypal.com"})
print(resp.json())
# {
#   "domain": "login-secure-paypal.com",
#   "risk_score": 94.0,
#   "threat_type": "phishing",
#   "confidence": 0.95,
#   "related_domains": ["secure-paypa1-login.com", "paypal-auth-secure.net"]
# }

# CVE risk analysis
resp = client.get("/api/v1/cves/CVE-2024-3400")
print(resp.json())
# {
#   "cve_id": "CVE-2024-3400",
#   "cvss": 10.0,
#   "exploit_probability": 1.0,
#   "risk": "critical",
#   "patch_urgency": "critical",
#   "ransomware_risk": false
# }

curl

# Global threat detection
curl "https://sentinelx402-production.up.railway.app/api/v1/threats/lookup?domain=suspicious-site.xyz"
curl "https://sentinelx402-production.up.railway.app/api/v1/threats/ip?ip=185.220.101.42"
curl "https://sentinelx402-production.up.railway.app/api/v1/threats/feed?page=1&page_size=10"

# CVE intelligence
curl "https://sentinelx402-production.up.railway.app/api/v1/cves/CVE-2024-3400"
curl "https://sentinelx402-production.up.railway.app/api/v1/cves/recent?limit=5"

# INDIA-SPECIFIC (proprietary — only here)
curl "https://sentinelx402-production.up.railway.app/api/v1/india/advisories/list?limit=5"
curl "https://sentinelx402-production.up.railway.app/api/v1/india/advisories/CIAD-2026-0014"
curl "http://localhost:8000/api/v1/cves/search?keyword=apache"

x402 Payment Flow

When X402_ENABLED=true, intelligence endpoints require payment:

Agent sends GET /api/v1/threats/lookup?domain=example.com
       |
Server returns HTTP 402 + payment requirements (USDC amount, wallet, network)
       |
Agent wallet signs USDC payment via EIP-3009
       |
Agent retries request with PAYMENT-SIGNATURE header
       |
Server verifies payment via facilitator, returns intelligence response

Set X402_ENABLED=false for development/testing without payments.

Production Features

  • Input validation — domain format, IP address format, CVE ID format validation
  • Rate limiting — configurable per-endpoint via THREAT_RATE_LIMIT / CVE_RATE_LIMIT
  • Security headers — X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, Cache-Control
  • CORS — configurable via ALLOWED_ORIGINS
  • Structured logging — request method, path, status, duration (ms)
  • Error handling — graceful 400/404/502/504 responses, no stack traces exposed
  • NVD timeout — configurable via NVD_TIMEOUT_SECONDS (default 15s)
  • Cache resilience — cache failures are logged but don't block requests
  • Health checks — deep health check verifies database connectivity
  • Docker — multi-stage build, non-root user, health checks, gunicorn with 4 workers

Architecture

sentinelx402/
├── app/
│   ├── main.py           # FastAPI app + middleware stack
│   ├── config.py          # Environment configuration
│   ├── database.py        # Async SQLAlchemy engine
│   ├── cache.py           # Redis / in-memory cache layer
│   ├── x402_setup.py      # Payment route configuration
│   ├── models/            # SQLAlchemy ORM models
│   ├── schemas/           # Pydantic request/response models
│   ├── routers/           # API route handlers + validation
│   ├── services/          # Business logic + scoring + NVD integration
│   └── data/              # Mock threat data + seed scripts
├── tests/                 # 31 tests (unit + integration)
├── docker-compose.yml     # Production: API + PostgreSQL + Redis
├── docker-compose.dev.yml # Dev: just PostgreSQL + Redis
├── Dockerfile             # Multi-stage, non-root, health checks
└── mcp.json               # Agent discovery metadata

Configuration

All settings via environment variables (or .env file):

Variable Default Description
DATABASE_URL sqlite+aiosqlite:///./sentinelx402.db Database connection string
REDIS_URL (empty) Redis URL, empty = in-memory cache
X402_ENABLED false Enable x402 payment middleware
WALLET_ADDRESS — Your USDC receiving wallet
FACILITATOR_URL https://x402.org/facilitator x402 facilitator endpoint
NETWORK_ID eip155:84532 Base Sepolia (testnet)
NVD_API_KEY (empty) NVD API key for higher rate limits
ENVIRONMENT development development / production
LOG_LEVEL INFO Logging level
ALLOWED_ORIGINS (empty) CORS origins, comma-separated
THREAT_RATE_LIMIT 60/minute Rate limit for threat endpoints
CVE_RATE_LIMIT 30/minute Rate limit for CVE endpoints
NVD_TIMEOUT_SECONDS 15 NVD API request timeout

Testing

pip install ".[dev]"
pytest -v

31 tests covering scoring algorithms, input validation, API endpoints, security headers, and error handling.

Tech Stack

  • Backend: FastAPI + Uvicorn (dev) / Gunicorn (prod)
  • Database: SQLite (dev) / PostgreSQL 16 (prod)
  • Cache: In-memory (dev) / Redis 7 (prod)
  • Payments: x402 protocol (USDC on Base)
  • CVE Data: NVD API via nvdlib
  • Rate Limiting: slowapi

License

AGPL-3.0 — You can use and modify this code, but if you deploy a modified version as a network service, you must publish your source code.

The proprietary scoring algorithms, extended brand datasets, multi-source feed integrations, and India-focused threat data used by the hosted SentinelX402 service are not included in this repository.

Want the full production version? Use the hosted API at https://sentinelx402-production.up.railway.app — first 1,000 requests free.

About

Free threat intelligence API for AI agents. CERT-In India advisories, UPI fraud detection, phishing/IP/CVE analysis. Part of Sentinel Series with SentinelCorp (company risk).

sentinelx402-production.up.railway.app/info

Topics

osint mcp cybersecurity micropayments cve security-automation threat-intelligence ai-agents phishing-detection fastapi usdc cert-in upi-fraud mcp-server x402 india-security

Resources

Readme

License

View license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages