{ "openapi": "3.1.0", "info": { "title": "isMalicious - Threat Intelligence API", "description": "Official isMalicious threat intelligence API for domain, IP, and URL reputation checking.\n\n**Base URL:** `https://api.ismalicious.com`\n\n**Documentation:** [ismalicious.com/api-docs](https://ismalicious.com/api-docs)\n\n---\n\n## Authentication\n\nGet your API keys from [ismalicious.com/app/account](https://ismalicious.com/app/account)\n\n**Header:** `X-API-KEY`\n**Value:** Base64 encode `apiKey:apiSecret`\n\n```javascript\n// Example in JavaScript\nconst apiKey = btoa(`${API_KEY}:${API_SECRET}`);\n```\n\n---\n\n## Rate Limits\n\n| Plan | Requests/min | Requests/day |\n|------|--------------|-------------|\n| FREE | 1/hour (burst) | 30/month |\n| BASIC | 60 | 5,000 |\n| PRO | 300 | 50,000 |\n| Custom | Contact sales | Contact sales |", "contact": { "name": "isMalicious Support", "url": "https://ismalicious.com/support", "email": "support@ismalicious.com" }, "license": { "name": "Proprietary", "url": "https://ismalicious.com/terms" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.ismalicious.com", "description": "Production server" } ], "paths": { "/action-center/overview": { "get": { "tags": [ "action-center" ], "operationId": "getActionCenterOverview", "responses": { "200": { "description": "Prioritized SOC action center overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionCenterOverview" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/alerts/trends": { "get": { "tags": [ "alerts" ], "operationId": "getAlertTrends", "parameters": [ { "name": "days", "in": "query", "description": "Window in days (7-90, default 30)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Opened/resolved per day plus MTTR percentiles for the signed-in scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataValueGenericResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/blocklist/download/{filename}": { "get": { "tags": [ "blocklist" ], "summary": "Download Blocklist", "description": "Download a specific blocklist file.\n\n**Plan Access:**\n- FREE: 10% sample (lite version)\n- BASIC+: Full blocklist\n\n**Available Blocklists:**\n- `blocklist-ips-critical.txt` - Critical severity IPs\n- `blocklist-ips-all.txt` - All malicious IPs\n- `blocklist-ips-c2.txt` - C2 server IPs\n- `blocklist-ips-botnet.txt` - Botnet IPs\n- `blocklist-domains-phishing.txt` - Phishing domains\n- `blocklist-domains-malware.txt` - Malware domains\n- `blocklist-domains-ransomware.txt` - Ransomware domains\n- `blocklist-domains-all.txt` - All malicious domains", "operationId": "downloadBlocklist", "parameters": [ { "name": "filename", "in": "path", "description": "Blocklist filename", "required": true, "schema": { "type": "string" }, "example": "blocklist-domains-phishing.txt" } ], "responses": { "200": { "description": "Blocklist file download" }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Plan restriction", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Blocklist not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/blocklist/stats": { "get": { "tags": [ "blocklist" ], "summary": "Get Blocklist Stats", "description": "Get entry counts and last updated timestamps for all available blocklists.\n\n**No authentication required.**", "operationId": "getBlocklistStats", "responses": { "200": { "description": "Blocklist statistics response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlocklistStatsResponse" } } } } }, "security": [ {} ] } }, "/bulk/check": { "get": { "tags": [ "check" ], "summary": "Bulk check limits and usage", "description": "Returns plan-specific batch limits and usage. Use **POST** `/bulk/check` to run batch lookups.", "operationId": "bulkCheckInfo", "responses": { "200": { "description": "Limits and documentation JSON" }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "check" ], "summary": "Bulk entity check", "description": "Check up to N entities per request (N depends on subscription plan). Each entity may be a domain, IP, or URL string.", "operationId": "bulkCheck", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCheckResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/cases": { "get": { "tags": [ "cases" ], "operationId": "listCases", "responses": { "200": { "description": "Case workspace list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ActionCase" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "cases" ], "operationId": "createCase", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateActionCaseRequest" } } }, "required": true }, "responses": { "201": { "description": "Created case", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionCase" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/cases/{id}": { "patch": { "tags": [ "cases" ], "operationId": "updateCase", "parameters": [ { "name": "id", "in": "path", "description": "Case id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateActionCaseRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated case", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionCase" } } } }, "404": { "description": "Case not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/cases/{id}/evidence": { "post": { "tags": [ "cases" ], "operationId": "addCaseEvidence", "parameters": [ { "name": "id", "in": "path", "description": "Case id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddCaseEvidenceRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated case with appended evidence", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActionCase" } } } }, "404": { "description": "Case not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/check": { "get": { "tags": [ "check" ], "summary": "Full Threat Analysis", "description": "Comprehensive threat intelligence check for IPs and domains.\n\n**Enrichment Levels:**\n- `basic` - Malicious status, reputation, geo, whois, certificates, vulnerabilities\n- `standard` - Basic + risk score, classification, confidence, MITRE mapping\n- `full` - Standard + detection timeline, related infrastructure, DNS analysis, tech stack", "operationId": "checkAll", "parameters": [ { "name": "query", "in": "path", "description": "IP address or domain to check", "required": true, "schema": { "type": "string" }, "example": "8.8.8.8" }, { "name": "enrichment", "in": "path", "description": "Enrichment level: basic, standard, or full", "required": true, "schema": { "type": [ "string", "null" ] }, "example": "standard" }, { "name": "track_reports", "in": "path", "description": "Track this check in reports history", "required": true, "schema": { "type": [ "boolean", "null" ], "default": false } } ], "responses": { "200": { "description": "Successful threat analysis response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/check/certificates": { "get": { "tags": [ "check" ], "summary": "Check Certificates", "description": "Get SSL/TLS certificate information including issuer, validity, and chain details.", "operationId": "checkCertificates", "parameters": [ { "name": "query", "in": "path", "description": "IP address or domain to check", "required": true, "schema": { "type": "string" }, "example": "8.8.8.8" }, { "name": "enrichment", "in": "path", "description": "Enrichment level: basic, standard, or full", "required": true, "schema": { "type": [ "string", "null" ] }, "example": "standard" }, { "name": "track_reports", "in": "path", "description": "Track this check in reports history", "required": true, "schema": { "type": [ "boolean", "null" ], "default": false } } ], "responses": { "200": { "description": "Certificate data response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificatesResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/check/location": { "get": { "tags": [ "check" ], "summary": "Check Geolocation", "description": "Get geographic location data including country, city, region, ISP, and coordinates.", "operationId": "checkLocation", "parameters": [ { "name": "query", "in": "path", "description": "IP address or domain to check", "required": true, "schema": { "type": "string" }, "example": "8.8.8.8" }, { "name": "enrichment", "in": "path", "description": "Enrichment level: basic, standard, or full", "required": true, "schema": { "type": [ "string", "null" ] }, "example": "standard" }, { "name": "track_reports", "in": "path", "description": "Track this check in reports history", "required": true, "schema": { "type": [ "boolean", "null" ], "default": false } } ], "responses": { "200": { "description": "Geolocation data response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeoResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/check/reputation": { "get": { "tags": [ "check" ], "summary": "Check Reputation", "description": "Get reputation data from aggregated threat intelligence sources including VirusTotal integration.", "operationId": "checkReputation", "parameters": [ { "name": "query", "in": "path", "description": "IP address or domain to check", "required": true, "schema": { "type": "string" }, "example": "8.8.8.8" }, { "name": "enrichment", "in": "path", "description": "Enrichment level: basic, standard, or full", "required": true, "schema": { "type": [ "string", "null" ] }, "example": "standard" }, { "name": "track_reports", "in": "path", "description": "Track this check in reports history", "required": true, "schema": { "type": [ "boolean", "null" ], "default": false } } ], "responses": { "200": { "description": "Reputation data response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReputationResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/check/vulnerabilities": { "get": { "tags": [ "check" ], "summary": "Check Vulnerabilities", "description": "Get known vulnerabilities associated with an IP address from CVE databases.", "operationId": "checkVulnerabilities", "parameters": [ { "name": "query", "in": "path", "description": "IP address or domain to check", "required": true, "schema": { "type": "string" }, "example": "8.8.8.8" }, { "name": "enrichment", "in": "path", "description": "Enrichment level: basic, standard, or full", "required": true, "schema": { "type": [ "string", "null" ] }, "example": "standard" }, { "name": "track_reports", "in": "path", "description": "Track this check in reports history", "required": true, "schema": { "type": [ "boolean", "null" ], "default": false } } ], "responses": { "200": { "description": "Vulnerabilities data response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VulnerabilitiesResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/check/whois": { "get": { "tags": [ "check" ], "summary": "Check WHOIS", "description": "Get WHOIS registration data including registrant, registrar, and registration dates.", "operationId": "checkWhois", "parameters": [ { "name": "query", "in": "path", "description": "IP address or domain to check", "required": true, "schema": { "type": "string" }, "example": "8.8.8.8" }, { "name": "enrichment", "in": "path", "description": "Enrichment level: basic, standard, or full", "required": true, "schema": { "type": [ "string", "null" ] }, "example": "standard" }, { "name": "track_reports", "in": "path", "description": "Track this check in reports history", "required": true, "schema": { "type": [ "boolean", "null" ], "default": false } } ], "responses": { "200": { "description": "WHOIS data response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhoisResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/platform/data-freshness": { "get": { "tags": [ "platform" ], "operationId": "getDataFreshness", "responses": { "200": { "description": "Dataset freshness, version, and SLA status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataFreshnessResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/platform/data-ops/pipeline": { "get": { "tags": [ "platform" ], "operationId": "getDataOpsPipeline", "responses": { "200": { "description": "Data operations pipeline phases and last recorded run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataOpsPipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/risk-brief/latest": { "get": { "tags": [ "briefs" ], "operationId": "getLatestRiskBrief", "responses": { "200": { "description": "Latest organization risk brief summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataValueGenericResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/search": { "post": { "tags": [ "search" ], "summary": "Search Keywords", "description": "Fuzzy search for similar malicious domains. Useful for finding typosquatting and phishing domains targeting a specific brand.", "operationId": "searchKeywords", "parameters": [ { "name": "keywords", "in": "path", "description": "Search keywords (e.g., 'paypal', 'microsoft')", "required": true, "schema": { "type": "string" }, "example": "paypal" } ], "responses": { "200": { "description": "Search results response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/submit": { "post": { "tags": [ "submit" ], "summary": "Submit Sources", "description": "Submit new threat intelligence sources to the community database.\n\n**Categories:** malware, phishing, spam, scam, fraud, botnet, ransomware, c2", "operationId": "submitSources", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitSourcesRequest" } } }, "required": true }, "responses": { "200": { "description": "Submission successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/trust/assessment/schema": { "get": { "tags": [ "trust" ], "operationId": "getTrustAssessmentContract", "responses": { "200": { "description": "Canonical trust assessment field contract", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataValueGenericResponse" } } } } } } }, "/user/webhooks/events": { "get": { "tags": [ "webhooks" ], "operationId": "getWebhookEventCatalog", "responses": { "200": { "description": "Supported webhook events and recommended payload fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataValueGenericResponse" } } } } } } } }, "components": { "schemas": { "ActionCase": { "type": "object", "required": [ "id", "userId", "title", "status", "priority", "evidence", "createdAt", "updatedAt" ], "properties": { "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "entityType": { "type": [ "string", "null" ] }, "entityValue": { "type": [ "string", "null" ] }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/ActionCaseEvidence" } }, "id": { "type": "string" }, "linkedAlertId": { "type": [ "string", "null" ] }, "linkedCveFindingId": { "type": [ "string", "null" ] }, "linkedReportId": { "type": [ "string", "null" ] }, "organizationId": { "type": [ "string", "null" ] }, "priority": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "type": "string" }, "userId": { "type": "string" } } }, "ActionCaseEvidence": { "type": "object", "required": [ "id", "kind", "title", "payload", "createdAt" ], "properties": { "createdAt": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "kind": { "type": "string" }, "payload": { "type": "object" }, "title": { "type": "string" } } }, "ActionCenterItem": { "type": "object", "required": [ "id", "source", "priority", "title", "status", "reason", "href", "primaryAction" ], "properties": { "createdAt": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "entityType": { "type": [ "string", "null" ] }, "entityValue": { "type": [ "string", "null" ] }, "href": { "type": "string" }, "id": { "type": "string" }, "primaryAction": { "type": "string" }, "priority": { "type": "string" }, "reason": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "title": { "type": "string" }, "updatedAt": { "type": [ "string", "null" ] } } }, "ActionCenterMetrics": { "type": "object", "required": [ "openCriticalAlerts", "openHighAlerts", "staleOpenAlerts", "acknowledgedAlerts", "activeExploitFindings", "kevFindings", "openCases" ], "properties": { "acknowledgedAlerts": { "type": "integer", "format": "int64" }, "activeExploitFindings": { "type": "integer", "format": "int64" }, "kevFindings": { "type": "integer", "format": "int64" }, "openCases": { "type": "integer", "format": "int64" }, "openCriticalAlerts": { "type": "integer", "format": "int64" }, "openHighAlerts": { "type": "integer", "format": "int64" }, "staleOpenAlerts": { "type": "integer", "format": "int64" } } }, "ActionCenterOverview": { "type": "object", "required": [ "generatedAt", "metrics", "priorityQueue", "socActions", "degraded" ], "properties": { "degraded": { "type": "boolean" }, "generatedAt": { "type": "string" }, "metrics": { "$ref": "#/components/schemas/ActionCenterMetrics" }, "priorityQueue": { "type": "array", "items": { "$ref": "#/components/schemas/ActionCenterItem" } }, "socActions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionCenterSocAction" } } } }, "ActionCenterSocAction": { "type": "object", "required": [ "id", "title", "source", "priority", "href" ], "properties": { "href": { "type": "string" }, "id": { "type": "string" }, "priority": { "type": "string" }, "source": { "type": "string" }, "title": { "type": "string" } } }, "AddCaseEvidenceRequest": { "type": "object", "required": [ "kind", "title", "payload" ], "properties": { "description": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "payload": { "type": "object" }, "title": { "type": "string" } } }, "BlocklistFilenameEnum": { "type": "string", "description": "Blocklist filename enum", "enum": [ "blocklist-ips-critical.txt", "blocklist-ips-all.txt", "blocklist-ips-c2.txt", "blocklist-ips-botnet.txt", "blocklist-domains-phishing.txt", "blocklist-domains-malware.txt", "blocklist-domains-ransomware.txt", "blocklist-domains-all.txt" ] }, "BlocklistStat": { "type": "object", "description": "Blocklist statistics entry", "required": [ "count", "last_updated" ], "properties": { "count": { "type": "integer", "format": "int32", "description": "Number of entries in the blocklist" }, "last_updated": { "type": "string", "description": "Last update timestamp", "example": "2024-12-28T07:00:00.000Z" } } }, "BlocklistStatsResponse": { "type": "object", "description": "Blocklist statistics response (dynamic keys based on blocklist names)", "required": [ "stats" ], "properties": { "stats": { "type": "object" } } }, "BulkCheckRequest": { "type": "object", "description": "Bulk check request body", "required": [ "entities" ], "properties": { "enrichment": { "type": [ "string", "null" ], "description": "Optional enrichment level (e.g. basic, standard, full)" }, "entities": { "type": "array", "items": { "type": "string" }, "description": "Domains, IPs, and/or URLs to check" }, "format": { "type": [ "string", "null" ], "description": "Optional response format (`json` or `csv`)" } } }, "BulkCheckResponse": { "type": "object", "description": "Bulk check response", "required": [ "success", "total", "processed", "results", "processing_time_ms" ], "properties": { "errors": { "type": [ "array", "null" ], "items": { "type": "string" } }, "processed": { "type": "integer", "format": "int32" }, "processing_time_ms": { "type": "integer", "format": "int32" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkEntityResult" } }, "success": { "type": "boolean" }, "total": { "type": "integer", "format": "int32" } } }, "BulkEntityResult": { "type": "object", "description": "Bulk entity result", "required": [ "entity", "type", "is_malicious", "confidence", "sources", "categories" ], "properties": { "analystStatus": { "type": [ "string", "null" ] }, "categories": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "number", "format": "double" }, "entity": { "type": "string" }, "error": { "type": [ "string", "null" ], "description": "Error message if the check failed" }, "evidence": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SocEvidence" } ] }, "is_malicious": { "type": "boolean" }, "observedAt": { "type": [ "string", "null" ] }, "recommendedAction": { "type": [ "string", "null" ] }, "riskLevel": { "type": [ "string", "null" ] }, "riskScore": { "type": [ "integer", "null" ], "format": "int32" }, "sources": { "type": "integer", "format": "int32" }, "type": { "type": "string", "description": "Entity type (domain, ip, url)", "example": "domain" } } }, "CertificateData": { "type": "object", "description": "SSL/TLS certificate information", "required": [ "issuer", "subject", "valid_from", "valid_to", "serial_number", "fingerprint" ], "properties": { "fingerprint": { "type": "string", "description": "Certificate fingerprint", "example": "a1:b2:c3:d4:e5:f6:..." }, "issuer": { "type": "string", "description": "Certificate issuer", "example": "DigiCert Inc" }, "serial_number": { "type": "string", "description": "Certificate serial number", "example": "00:ab:cd:ef:12:34:56:78" }, "subject": { "type": "string", "description": "Certificate subject", "example": "CN=example.com" }, "valid_from": { "type": "string", "description": "Certificate validity start date", "example": "2023-01-01T00:00:00Z" }, "valid_to": { "type": "string", "description": "Certificate validity end date", "example": "2024-01-01T00:00:00Z" } } }, "CertificatesResponse": { "type": "object", "description": "Certificates check response", "required": [ "certificates" ], "properties": { "certificates": { "$ref": "#/components/schemas/CertificateData" } } }, "CheckResponse": { "type": "object", "description": "Main threat analysis response", "required": [ "malicious", "reputation", "risk_score", "confidence", "classification", "api_version", "enrichment_level" ], "properties": { "api_version": { "type": "string", "description": "API version used", "example": "v2" }, "certificates": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CertificateData", "description": "SSL/TLS certificate information" } ] }, "classification": { "$ref": "#/components/schemas/Classification", "description": "Classification of the entity" }, "confidence": { "$ref": "#/components/schemas/Confidence", "description": "Confidence score and level" }, "dataTrust": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DataTrustProfile", "description": "Data quality, freshness, source reliability, and provider agreement profile" } ] }, "enrichment_level": { "type": "string", "description": "Enrichment level applied" }, "evidence": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SocEvidence", "description": "SOC verdict evidence, reasons, contradictions, and recommended action" } ] }, "geo": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeoData", "description": "Geographic location data" } ] }, "malicious": { "type": "boolean", "description": "Whether the entity is considered malicious" }, "reputation": { "$ref": "#/components/schemas/ReputationData", "description": "Reputation data from threat intelligence sources" }, "risk_score": { "$ref": "#/components/schemas/RiskScore", "description": "Risk score and level" }, "vulnerabilities": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/VulnerabilityData", "description": "Vulnerability data" } ] }, "whois": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WhoisData", "description": "WHOIS registration data" } ] } } }, "Classification": { "type": "object", "description": "Classification of the entity", "required": [ "primary", "secondary" ], "properties": { "primary": { "type": "string", "description": "Primary classification", "example": "safe" }, "secondary": { "type": "array", "items": { "type": "string" }, "description": "Secondary classifications" } } }, "Confidence": { "type": "object", "description": "Confidence score with level", "required": [ "score", "level" ], "properties": { "level": { "type": "string", "description": "Confidence level", "example": "high" }, "score": { "type": "integer", "format": "int32", "description": "Confidence score from 0-100", "maximum": 100, "minimum": 0 } } }, "ConfidenceLevel": { "type": "string", "description": "Confidence level enum", "enum": [ "low", "medium", "high" ] }, "CreateActionCaseRequest": { "type": "object", "required": [ "title" ], "properties": { "description": { "type": [ "string", "null" ] }, "entityType": { "type": [ "string", "null" ] }, "entityValue": { "type": [ "string", "null" ] }, "linkedAlertId": { "type": [ "string", "null" ] }, "linkedCveFindingId": { "type": [ "string", "null" ] }, "linkedReportId": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "title": { "type": "string" } } }, "Cve": { "type": "object", "description": "CVE vulnerability entry", "required": [ "id", "severity", "description" ], "properties": { "description": { "type": "string", "description": "CVE description", "example": "Buffer overflow vulnerability in..." }, "id": { "type": "string", "description": "CVE identifier", "example": "CVE-2023-1234" }, "score": { "type": [ "number", "null" ], "format": "double", "description": "CVSS score", "example": 7.5 }, "severity": { "type": "string", "description": "Severity level", "example": "HIGH" } } }, "DataCompleteness": { "type": "object", "description": "Data completeness across expected enrichment facets", "required": [ "score", "present", "missing" ], "properties": { "missing": { "type": "array", "items": { "type": "string" } }, "present": { "type": "array", "items": { "type": "string" } }, "score": { "type": "integer", "format": "int32" } } }, "DataFreshnessResponse": { "type": "object", "required": [ "generatedAt", "overallStatus", "datasets", "actions" ], "properties": { "actions": { "type": "array", "items": { "type": "string" } }, "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/DataValueDatasetStatus" } }, "generatedAt": { "type": "string" }, "overallStatus": { "type": "string" } } }, "DataOpsPipelinePhase": { "type": "object", "required": [ "id", "label", "command", "produces", "requiredForSla" ], "properties": { "command": { "type": "string" }, "id": { "type": "string" }, "label": { "type": "string" }, "produces": { "type": "array", "items": { "type": "string" } }, "requiredForSla": { "type": "boolean" } } }, "DataOpsPipelineResponse": { "type": "object", "required": [ "generatedAt", "phases", "lastRun", "freshnessApiPath", "backofficePath" ], "properties": { "backofficePath": { "type": "string" }, "freshnessApiPath": { "type": "string" }, "generatedAt": { "type": "string" }, "lastRun": { "type": "object" }, "phases": { "type": "array", "items": { "$ref": "#/components/schemas/DataOpsPipelinePhase" } } } }, "DataTrustProfile": { "type": "object", "description": "Data Trust profile attached to check responses", "required": [ "observedAt", "freshness", "sourceAgreement", "sources", "completeness", "providerAgreement" ], "properties": { "completeness": { "$ref": "#/components/schemas/DataCompleteness" }, "dataAgeHours": { "type": [ "number", "null" ], "format": "double" }, "firstSeen": { "type": [ "string", "null" ] }, "freshness": { "type": "string" }, "lastSeen": { "type": [ "string", "null" ] }, "lastUpdated": { "type": [ "string", "null" ] }, "observedAt": { "type": "string" }, "providerAgreement": { "$ref": "#/components/schemas/ProviderAgreement" }, "sourceAgreement": { "$ref": "#/components/schemas/SourceAgreement" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/DataTrustSource" } } } }, "DataTrustSource": { "type": "object", "description": "Source entry with reliability metadata", "required": [ "name", "type", "reliability", "reliabilityLevel", "noiseProfile" ], "properties": { "category": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "noiseProfile": { "$ref": "#/components/schemas/NoiseProfile" }, "reliability": { "type": "number", "format": "double" }, "reliabilityLevel": { "$ref": "#/components/schemas/ReliabilityLevel" }, "type": { "type": "string" }, "url": { "type": [ "string", "null" ] } } }, "DataValueDatasetStatus": { "type": "object", "required": [ "key", "label", "category", "status", "source", "details" ], "properties": { "ageHours": { "type": [ "number", "null" ], "format": "double" }, "apiPath": { "type": [ "string", "null" ] }, "backofficePath": { "type": [ "string", "null" ] }, "category": { "type": "string" }, "details": { "type": "object" }, "key": { "type": "string" }, "label": { "type": "string" }, "lastSuccessAt": { "type": [ "string", "null" ] }, "source": { "type": "string" }, "status": { "type": "string" }, "version": { "type": [ "string", "null" ] } } }, "DataValueGenericResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object" } } }, "EnrichmentLevel": { "type": "string", "description": "Enrichment level enum", "enum": [ "basic", "standard", "full" ] }, "ErrorResponse": { "type": "object", "description": "Error response", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Error type", "example": "Bad Request" }, "message": { "type": "string", "description": "Detailed error message", "example": "Missing required parameter: query" } } }, "EvidenceConfidence": { "type": "object", "description": "Confidence excerpt included in SOC evidence", "required": [ "score", "level" ], "properties": { "level": { "type": "string" }, "score": { "type": "integer", "format": "int32" } } }, "EvidenceSourceSummary": { "type": "object", "description": "Source summary included in SOC evidence", "required": [ "count", "weightedStrength", "highReliabilityCount", "noiseWarnings" ], "properties": { "count": { "type": "integer", "format": "int32" }, "highReliabilityCount": { "type": "integer", "format": "int32" }, "noiseWarnings": { "type": "array", "items": { "type": "string" } }, "weightedStrength": { "type": "number", "format": "double" } } }, "GeoData": { "type": "object", "description": "Geographic location data", "required": [ "country", "country_code", "city", "isp" ], "properties": { "city": { "type": "string", "description": "City name", "example": "Mountain View" }, "country": { "type": "string", "description": "Country name", "example": "United States" }, "country_code": { "type": "string", "description": "ISO country code", "example": "US" }, "isp": { "type": "string", "description": "Internet Service Provider", "example": "Google LLC" }, "lat": { "type": [ "number", "null" ], "format": "double", "description": "Latitude", "example": 37.386 }, "lon": { "type": [ "number", "null" ], "format": "double", "description": "Longitude", "example": -122.0838 }, "region": { "type": [ "string", "null" ], "description": "Region or state", "example": "California" } } }, "GeoResponse": { "type": "object", "description": "Geolocation check response", "required": [ "geo" ], "properties": { "geo": { "$ref": "#/components/schemas/GeoData" } } }, "NoiseProfile": { "type": "string", "description": "Operational noise profile for a source", "enum": [ "authoritative", "contextual", "noisy" ] }, "ProviderAgreement": { "type": "object", "description": "Provider agreement summary from cross-correlation signals", "required": [ "status", "summary", "contradictorySignals" ], "properties": { "contradictorySignals": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderContradictorySignal" } }, "status": { "type": "string" }, "summary": { "type": "string" } } }, "ProviderContradictorySignal": { "type": "object", "description": "Contradictory provider signal included in SOC evidence", "required": [ "type", "severity", "title", "description" ], "properties": { "description": { "type": "string" }, "severity": { "type": "string" }, "title": { "type": "string" }, "type": { "type": "string" } } }, "ReliabilityLevel": { "type": "string", "description": "Source reliability level used by Data Trust evidence", "enum": [ "high", "medium", "low" ] }, "ReputationData": { "type": "object", "description": "Reputation data from aggregated threat intelligence sources", "required": [ "malicious", "suspicious", "harmless", "undetected" ], "properties": { "harmless": { "type": "integer", "format": "int32", "description": "Number of sources flagging as harmless" }, "malicious": { "type": "integer", "format": "int32", "description": "Number of sources flagging as malicious" }, "suspicious": { "type": "integer", "format": "int32", "description": "Number of sources flagging as suspicious" }, "undetected": { "type": "integer", "format": "int32", "description": "Number of sources with no detection" } } }, "ReputationResponse": { "type": "object", "description": "Reputation check response", "required": [ "reputation" ], "properties": { "reputation": { "$ref": "#/components/schemas/ReputationData" } } }, "RiskLevel": { "type": "string", "description": "Risk level enum", "enum": [ "safe", "low", "medium", "high", "critical" ] }, "RiskScore": { "type": "object", "description": "Risk score with level and contributing factors", "required": [ "score", "level", "factors" ], "properties": { "factors": { "type": "array", "items": { "type": "string" }, "description": "Factors contributing to the risk score" }, "level": { "type": "string", "description": "Risk level category", "example": "safe" }, "score": { "type": "integer", "format": "int32", "description": "Risk score from 0-100", "maximum": 100, "minimum": 0 } } }, "SearchResponse": { "type": "object", "description": "Search response for similar domains", "required": [ "keywords", "hits", "total_hits" ], "properties": { "hits": { "type": "array", "items": { "type": "string" }, "description": "Matching domains" }, "keywords": { "type": "string", "description": "Search keywords used", "example": "paypal" }, "total_hits": { "type": "integer", "format": "int32", "description": "Total number of matches" } } }, "Severity": { "type": "string", "description": "Severity level enum", "enum": [ "CRITICAL", "HIGH", "MEDIUM", "LOW" ] }, "SocEvidence": { "type": "object", "description": "SOC-ready verdict evidence attached to check responses", "required": [ "verdict", "observedAt", "reasons", "contradictorySignals", "sourceSummary", "freshness", "recommendedAction", "analystStatus" ], "properties": { "analystStatus": { "type": "string" }, "confidence": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/EvidenceConfidence" } ] }, "contradictorySignals": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderContradictorySignal" } }, "dataAgeHours": { "type": [ "number", "null" ], "format": "double" }, "freshness": { "type": "string" }, "observedAt": { "type": "string" }, "reasons": { "type": "array", "items": { "type": "string" } }, "recommendedAction": { "type": "string" }, "score": { "type": [ "integer", "null" ], "format": "int32" }, "sourceSummary": { "$ref": "#/components/schemas/EvidenceSourceSummary" }, "verdict": { "type": "string" } } }, "SourceAgreement": { "type": "object", "description": "Source agreement summary across blocklists and scanners", "required": [ "count", "weightedStrength", "level", "scannerDetections", "scannerSuspicious", "scannerClean" ], "properties": { "count": { "type": "integer", "format": "int32" }, "level": { "type": "string" }, "scannerClean": { "type": "integer", "format": "int32" }, "scannerDetections": { "type": "integer", "format": "int32" }, "scannerSuspicious": { "type": "integer", "format": "int32" }, "weightedStrength": { "type": "number", "format": "double" } } }, "SubmitResponse": { "type": "object", "description": "Submit sources response", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Success message", "example": "Submitted successfully, thanks sharing new sources with us!" } } }, "SubmitSourcesRequest": { "type": "object", "description": "Submit sources request body", "required": [ "sources" ], "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ThreatSource" } } } }, "ThreatCategory": { "type": "string", "description": "Threat category enum", "enum": [ "malware", "phishing", "spam", "scam", "fraud", "botnet", "ransomware", "c2" ] }, "ThreatSource": { "type": "object", "description": "Threat source submission entry", "required": [ "name", "type", "url", "category" ], "properties": { "category": { "type": "string", "description": "Threat category" }, "name": { "type": "string", "description": "Name of the threat feed", "example": "Example Threat Feed" }, "type": { "type": "string", "description": "Type of entities in the feed" }, "url": { "type": "string", "description": "URL to the threat feed", "example": "https://example.com/threats-ips.txt" } } }, "ThreatSourceType": { "type": "string", "description": "Threat source type enum", "enum": [ "ip", "domain" ] }, "UpdateActionCaseRequest": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } } }, "VulnerabilitiesResponse": { "type": "object", "description": "Vulnerabilities check response", "required": [ "vulnerabilities" ], "properties": { "vulnerabilities": { "$ref": "#/components/schemas/VulnerabilityData" } } }, "VulnerabilityData": { "type": "object", "description": "Vulnerability data", "required": [ "total", "critical", "high", "medium", "low", "cves" ], "properties": { "critical": { "type": "integer", "format": "int32", "description": "Critical severity count" }, "cves": { "type": "array", "items": { "$ref": "#/components/schemas/Cve" }, "description": "List of CVEs" }, "high": { "type": "integer", "format": "int32", "description": "High severity count" }, "low": { "type": "integer", "format": "int32", "description": "Low severity count" }, "medium": { "type": "integer", "format": "int32", "description": "Medium severity count" }, "total": { "type": "integer", "format": "int32", "description": "Total vulnerabilities found" } } }, "WhoisData": { "type": "object", "description": "WHOIS registration data", "required": [ "name_servers" ], "properties": { "created_date": { "type": [ "string", "null" ], "description": "Domain creation date", "example": "2020-01-15T00:00:00Z" }, "expires_date": { "type": [ "string", "null" ], "description": "Domain expiration date", "example": "2025-01-15T00:00:00Z" }, "name_servers": { "type": "array", "items": { "type": "string" }, "description": "Name servers" }, "registrant": { "type": [ "string", "null" ], "description": "Registrant name or organization", "example": "Example Inc." }, "registrar": { "type": [ "string", "null" ], "description": "Domain registrar", "example": "GoDaddy.com, LLC" }, "updated_date": { "type": [ "string", "null" ], "description": "Last update date", "example": "2023-06-20T00:00:00Z" } } }, "WhoisResponse": { "type": "object", "description": "WHOIS check response", "required": [ "whois" ], "properties": { "whois": { "$ref": "#/components/schemas/WhoisData" } } } }, "responses": { "BadRequest": { "description": "Bad request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Too many requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized - Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY", "description": "Base64 encoded `apiKey:apiSecret`. Get your keys from https://ismalicious.com/app/account" } } }, "security": [ { "ApiKeyAuth": [] } ], "tags": [ { "name": "check", "description": "Threat intelligence check endpoints for IPs and domains" }, { "name": "search", "description": "Search for similar malicious domains" }, { "name": "blocklist", "description": "Download and manage blocklists" }, { "name": "submit", "description": "Submit new threat intelligence sources" } ] }