Skip to content

About

The Malware & Phishing URL Scanner API helps developers, security platforms, and email providers detect unsafe, suspicious, or malicious URLs. It combines VirusTotal threat intelligence with local heuristics (WHOIS, SSL validity, domain age, suspicious keywords) to give reliable results.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 

Repository files navigation

Malware & Phishing URL Scanner API

Malware & Phishing URL Scanner API

Version: v0.0.2 · Release Date: Aug 28, 2026

🚀 Overview

The Malware & Phishing URL Scanner API helps developers, security platforms, and email providers detect unsafe, suspicious, or malicious URLs, domains, IPs, and file hashes.

It combines VirusTotal threat intelligence (Bring Your Own Key) with local heuristics (WHOIS, SSL validity, domain age, suspicious keywords) to give reliable results — plus dedicated domain-intelligence endpoints for deeper investigations.


🔑 Authentication

RapidAPI key (required for all requests)

All requests must include your RapidAPI key in the header:

"x-rapidapi-key": "YOUR_RAPIDAPI_KEY"
"x-rapidapi-host": "malware-scanner-api.p.rapidapi.com"

BYOK — Bring Your Own Key (for VirusTotal endpoints)

This API does not store any third-party keys. Endpoints backed by VirusTotal require your own VirusTotal API key in the x-apikey header:

"x-apikey": "YOUR_VIRUSTOTAL_KEY"
Header Required for
x-apikey (alias x-virustotal-apikey) /vt/url, /vt/hash, /vt/ip, /vt/domain — required; /scan, /scan/bulk — optional

Get a free VirusTotal key at https://www.virustotal.com.


📡 Endpoints

1. Scan a URL

Endpoint:

GET /scan
POST /scan

Description: Analyze a URL using local heuristics (WHOIS domain age, SSL certificate, suspicious patterns) plus optional VirusTotal when an x-apikey header is provided. Returns a verdict: safe, suspicious, malicious, pending, or error.

Request Parameters:

Parameter Type Required Description
url string Yes The URL to analyze (scheme auto-added if missing, e.g. example.com)
x-apikey header No Your VirusTotal API key (BYOK) — enables VirusTotal intelligence

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/scan?url=example.com" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com"

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/scan" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -d '{"url": "https://suspicious-login.com"}' \
  -H "x-apikey: YOUR_VIRUSTOTAL_KEY"

Example Response (Safe URL)

{
  "success": true,
  "input": "https://example.com",
  "vt_key_used": false,
  "analysis": {
    "status": "safe",
    "reason": "No suspicious indicators found",
    "checks": {
      "whois": {
        "domain": "example.com",
        "registrar": "IANA",
        "creation_date": "1995-08-14T00:00:00",
        "expiration_date": "2026-08-14T00:00:00",
        "age_days": 11340,
        "is_new_domain": false
      },
      "ssl": {
        "valid": true,
        "details": {
          "subject": "www.example.org",
          "issuer": "DigiCert Inc",
          "expires_in_days": 215,
          "expired": false,
          "expiring_soon": false
        }
      },
      "patterns": {
        "findings": [],
        "details": {
          "domain": "example.com",
          "tld": "com",
          "keyword_matches": [],
          "long_domain": false,
          "excessive_subdomains": false,
          "punycode": false,
          "hyphen_cluster": false,
          "suspicious_tld": false
        }
      }
    }
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

Example Response (Suspicious / Malicious URL)

{
  "success": true,
  "input": "https://secure-login-bank.example",
  "vt_key_used": true,
  "analysis": {
    "status": "suspicious",
    "reason": "Contains suspicious keyword(s): secure, login, bank",
    "checks": {
      "whois": { "domain": "secure-login-bank.example", "age_days": 12, "is_new_domain": true },
      "ssl": { "valid": false, "details": { "error": "SSL handshake failed" } },
      "patterns": {
        "findings": ["Contains suspicious keyword(s): secure, login, bank"],
        "details": { "domain": "secure-login-bank.example", "keyword_matches": ["secure", "login", "bank"] }
      },
      "virustotal": {
        "provider": "virustotal",
        "status": "malicious",
        "reason": "Flagged by 5 engines",
        "detection_stats": { "malicious": 5, "suspicious": 2, "harmless": 60, "undetected": 13, "timeout": 0, "total_engines": 80 }
      }
    }
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

2. Batch Scan URLs

Endpoint:

POST /scan/bulk

Description: Scan up to 50 URLs in a single request, processed concurrently. Invalid entries are returned separately in invalid_urls.

Request Parameters:

Parameter Type Required Description
urls array Yes JSON array of 1–50 URLs to scan
x-apikey header No Your VirusTotal API key (BYOK) — optional

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/scan/bulk" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -d '{"urls": ["example.com", "secure-login-bank.example", "google.com"]}'

Example Response

{
  "success": true,
  "scanned": 2,
  "invalid_urls": ["bad url"],
  "vt_key_used": false,
  "results": [
    { "url": "https://example.com", "analysis": { "status": "safe", "reason": "No suspicious indicators found" } },
    { "url": "https://secure-login-bank.example", "analysis": { "status": "suspicious", "reason": "Contains suspicious keyword(s): secure, login, bank" } }
  ],
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

3. Retrieve Cached Scan Report

Endpoint:

GET /scan/report
POST /scan/report

Description: Return the previously cached /scan result for a URL, including its cached_at timestamp. Reports expire after 90 days.

Request Parameters:

Parameter Type Required Description
url string Yes The URL whose cached report to retrieve

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/scan/report?url=example.com" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com"

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/scan/report" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -d '{"url": "example.com"}'

4. VirusTotal URL Analysis

Endpoint:

GET /vt/url
POST /vt/url

Description: Full VirusTotal analysis of a URL — detection stats, reputation, and per-engine results. Requires BYOK.

Request Parameters:

Parameter Type Required Description
url string Yes URL to analyze (scheme auto-added)
x-apikey header Yes Your VirusTotal API key (BYOK)

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/vt/url?url=example.com" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -H "x-apikey: YOUR_VIRUSTOTAL_KEY"

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/vt/url" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -H "x-apikey: YOUR_VIRUSTOTAL_KEY" \
  -d '{"url": "example.com"}'

Example Response

{
  "success": true,
  "input": "https://example.com",
  "analysis": {
    "provider": "virustotal",
    "url": "https://example.com",
    "status": "safe",
    "reason": "No engines flagged",
    "detection_stats": { "malicious": 0, "suspicious": 0, "harmless": 70, "undetected": 10, "timeout": 0, "total_engines": 80 },
    "reputation": 100,
    "last_modification_date": 1735689600,
    "engines": [ { "engine": "Fortinet", "category": "harmless", "result": "clean", "method": "blacklist" } ]
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

Note: if the URL is not yet in VirusTotal's database, it is auto-submitted and returns "status": "pending".


5. VirusTotal File Hash Analysis

Endpoint:

GET /vt/hash
POST /vt/hash

Description: Check the reputation of a file by its MD5, SHA-1, or SHA-256 hash — detection stats and per-engine verdicts. Requires BYOK.

Request Parameters:

Parameter Type Required Description
hash string Yes File hash (MD5 32-hex / SHA-1 40-hex / SHA-256 64-hex)
x-apikey header Yes Your VirusTotal API key (BYOK)

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/vt/hash?hash=44d88612fea8a8f36de82e1278abb02f" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -H "x-apikey: YOUR_VIRUSTOTAL_KEY"

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/vt/hash" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -H "x-apikey: YOUR_VIRUSTOTAL_KEY" \
  -d '{"hash": "44d88612fea8a8f36de82e1278abb02f"}'

Example Response

{
  "success": true,
  "input": "44d88612fea8a8f36de82e1278abb02f",
  "hash_type": "md5",
  "analysis": {
    "provider": "virustotal",
    "hash": "44d88612fea8a8f36de82e1278abb02f",
    "status": "malicious",
    "reason": "Flagged by 57 engines",
    "detection_stats": { "malicious": 57, "suspicious": 0, "harmless": 0, "undetected": 13, "timeout": 0, "total_engines": 70 },
    "file_type": "exe",
    "magic": "PE32 executable",
    "known_names": ["evil.exe"],
    "reputation": -800,
    "engines": [ { "engine": "McAfee", "category": "malicious", "result": "EICAR", "method": "blacklist" } ]
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

6. VirusTotal IP Reputation

Endpoint:

GET /vt/ip
POST /vt/ip

Description: Reputation check for an IPv4 or IPv6 address — detection stats, ASN, country, and network ownership. Requires BYOK.

Request Parameters:

Parameter Type Required Description
ip string Yes IP address to check (IPv4 or IPv6)
x-apikey header Yes Your VirusTotal API key (BYOK)

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/vt/ip?ip=8.8.8.8" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -H "x-apikey: YOUR_VIRUSTOTAL_KEY"

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/vt/ip" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -H "x-apikey: YOUR_VIRUSTOTAL_KEY" \
  -d '{"ip": "8.8.8.8"}'

Example Response

{
  "success": true,
  "input": "8.8.8.8",
  "analysis": {
    "provider": "virustotal",
    "ip": "8.8.8.8",
    "status": "safe",
    "reason": "No engines flagged",
    "detection_stats": { "malicious": 0, "suspicious": 0, "harmless": 20, "undetected": 60, "timeout": 0, "total_engines": 80 },
    "country": "US",
    "asn": 15169,
    "as_owner": "GOOGLE",
    "network": "8.8.8.0/24",
    "regional_internet_registry": "ARIN",
    "reputation": 300
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

7. VirusTotal Domain Reputation

Endpoint:

GET /vt/domain
POST /vt/domain

Description: Domain reputation analysis — detection stats, registrar, creation date, popularity rank, and recent DNS records. Requires BYOK.

Request Parameters:

Parameter Type Required Description
domain string Yes Registered domain to analyze
x-apikey header Yes Your VirusTotal API key (BYOK)

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/vt/domain?domain=example.com" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -H "x-apikey: YOUR_VIRUSTOTAL_KEY"

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/vt/domain" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -H "x-apikey: YOUR_VIRUSTOTAL_KEY" \
  -d '{"domain": "example.com"}'

Example Response

{
  "success": true,
  "input": "example.com",
  "analysis": {
    "provider": "virustotal",
    "domain": "example.com",
    "status": "safe",
    "reason": "No engines flagged",
    "detection_stats": { "malicious": 0, "suspicious": 0, "harmless": 10, "undetected": 70, "timeout": 0, "total_engines": 80 },
    "registrar": "IANA",
    "creation_date": 808963200,
    "reputation": 100,
    "popularity": { "source": "alexa", "rank": 1 },
    "last_dns_records": []
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

8. WHOIS Registration Lookup

Endpoint:

GET /whois
POST /whois

Description: Registration intelligence for a domain — registrar, creation/expiration dates, domain age, nameservers, and a new-domain flag (age < 30 days, a common phishing signal).

Request Parameters:

Parameter Type Required Description
domain string Yes Domain to look up

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/whois?domain=example.com" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com"

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/whois" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -d '{"domain": "example.com"}'

Example Response

{
  "success": true,
  "input": "example.com",
  "whois": {
    "domain": "example.com",
    "registrar": "IANA",
    "creation_date": "1995-08-14T00:00:00",
    "expiration_date": "2026-08-14T00:00:00",
    "status": ["clientDeleteProhibited"],
    "name_servers": ["a.iana-servers.net"],
    "age_days": 11340,
    "is_new_domain": false
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

9. SSL Certificate Inspection

Endpoint:

GET /ssl
POST /ssl

Description: Live TLS certificate inspection for a domain — issuer, subject, validity window, days until expiry, and expired/expiring-soon flags.

Request Parameters:

Parameter Type Required Description
domain string Yes Domain whose live TLS certificate to inspect

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/ssl?domain=google.com" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com"

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/ssl" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -d '{"domain": "google.com"}'

Example Response

{
  "success": true,
  "input": "google.com",
  "ssl": {
    "valid": true,
    "details": {
      "subject": "www.google.com",
      "issuer": "GTS CA 1C3",
      "valid_until": "Aug 25 23:59:59 2026 GMT",
      "expires_in_days": 66,
      "expired": false,
      "expiring_soon": false
    }
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

10. Suspicious Domain Pattern Scan

Endpoint:

GET /patterns
POST /patterns

Description: Heuristic scan of a domain name for phishing signals: suspicious keywords, long names, punycode, hyphen clusters, abuse-prone TLDs, excessive subdomains, and all-numeric domains.

Request Parameters:

Parameter Type Required Description
domain string Yes Domain to inspect

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/patterns?domain=secure-login-bank.example" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com"

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/patterns" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -d '{"domain": "secure-login-bank.example"}'

Example Response

{
  "success": true,
  "input": "secure-login-bank.example",
  "suspicious": true,
  "findings": ["Contains suspicious keyword(s): secure, login, bank"],
  "details": {
    "domain": "secure-login-bank.example",
    "tld": "example",
    "keyword_matches": ["secure", "login", "bank"],
    "long_domain": false,
    "excessive_subdomains": false,
    "punycode": false,
    "hyphen_cluster": false,
    "suspicious_tld": false,
    "all_numeric": false
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

11. URL Validation & Normalization

Endpoint:

GET /validate
POST /validate

Description: Validate a URL and return its normalized form plus parsed components (scheme, host, port, path, query, credentials). Useful as a pre-flight check before scanning.

Request Parameters:

Parameter Type Required Description
url string Yes URL to validate / normalize

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/validate?url=example.com" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com"

POST Example

curl -X POST "https://malware-scanner-api.p.rapidapi.com/validate" \
  -H "Content-Type: application/json" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com" \
  -d '{"url": "example.com"}'

Example Response

{
  "success": true,
  "input": "example.com",
  "normalized": "https://example.com",
  "valid": true,
  "parts": {
    "scheme": "https",
    "netloc": "example.com",
    "hostname": "example.com",
    "port": null,
    "path": "",
    "query": "",
    "fragment": "",
    "has_credentials": false
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

12. Health Check & API Meta

Endpoint:

GET /status
POST /status

Description: Verify the API is online and return the current API metadata, version, and a full list of available endpoints.

Request Parameters:

Parameter Type Required Description
(none) — — No parameters

GET Example

curl -X GET "https://malware-scanner-api.p.rapidapi.com/status" \
  -H "x-rapidapi-key: YOUR_RAPIDAPI_KEY" \
  -H "x-rapidapi-host: malware-scanner-api.p.rapidapi.com"

Example Response

{
  "success": true,
  "status": "API is online",
  "api": {
    "name": "Malware Scanner API",
    "version": "v0.0.2",
    "byok": "External provider keys (e.g. VirusTotal) are supplied per-request in the 'x-apikey' header.",
    "subscriptions": "Managed via the RapidAPI dashboard."
  },
  "endpoints": [
    { "method": "GET/POST", "path": "/scan", "version": "v0.0.1", "description": "Composite URL scan" },
    { "method": "POST", "path": "/scan/bulk", "version": "v0.0.2", "description": "Batch-scan up to 50 URLs" },
    { "method": "GET/POST", "path": "/vt/url", "version": "v0.0.2", "description": "VirusTotal URL analysis (BYOK)" }
  ],
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

⚠️ Error Responses

Status Reason
400 Missing or invalid URL / domain / IP / hash parameter
401 Missing x-apikey header on a VirusTotal endpoint
404 No cached report found for the requested URL
405 Unsupported HTTP method
500 Internal server error

Example Error

{
  "success": false,
  "error": "Invalid URL format",
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

Provider-level failures (invalid VirusTotal key, quota exceeded, timeouts) do not produce HTTP errors — they are returned inside the analysis object:

{
  "success": true,
  "input": "https://example.com",
  "analysis": {
    "provider": "virustotal",
    "status": "error",
    "reason": "VirusTotal API key invalid or unauthorized."
  },
  "meta": { "name": "Malware Scanner API", "version": "v0.0.2" }
}

🛡️ Features

  • VirusTotal Threat Intel → Real-time analysis against 70+ AV engines (URL, file hash, IP, domain) — Bring Your Own Key
  • WHOIS Check → Detect newly registered domains often used in phishing
  • SSL Certificate Check → Identifies invalid, missing, or expiring SSL
  • Suspicious Keyword Detection → Flags URLs containing risky words (login, bank, secure, verify, account)
  • Batch Scanning → Scan up to 50 URLs in one request
  • Domain Pattern Heuristics → Punycode, hyphen clusters, abuse-prone TLDs, long/numeric domains
  • Result Caching → 90-day SQLite cache for instant repeat lookups
  • URL Validation → Normalize and parse any URL before scanning

📌 Verdict Values

Status Meaning
safe No indicators found
suspicious Local heuristics or engine flags, no confirmed malware
malicious Confirmed by VirusTotal engines
pending Submitted to VirusTotal, awaiting analysis
unknown Not found in the VirusTotal database
error Provider / key / network failure

🗓️ Changelog

v0.0.2 — Aug 28, 2026

  • Added 10 new endpoints: /scan/bulk, /scan/report, /vt/url, /vt/hash, /vt/ip, /vt/domain, /whois, /ssl, /patterns, /validate
  • BYOK — removed the hardcoded VirusTotal key; consumers now supply their own key via the x-apikey header
  • Enhanced /scan — structured checks object, richer SSL/WHOIS/pattern analysis, URL normalization
  • Enhanced /status — API meta (version: v0.0.2) and full endpoint listing
  • 90-day SQLite caching with a generic JSON cache schema

v0.0.1 (baseline)

  • GET/POST /scan — composite URL scan (VirusTotal + WHOIS + SSL + patterns)
  • GET/POST /status — health check

About

The Malware & Phishing URL Scanner API helps developers, security platforms, and email providers detect unsafe, suspicious, or malicious URLs. It combines VirusTotal threat intelligence with local heuristics (WHOIS, SSL validity, domain age, suspicious keywords) to give reliable results.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors