{ "openapi": "3.1.0", "info": { "title": "ForenShield API", "version": "2026-09-30", "description": "API d’investigation cyber de ForenShield. Authentification par clé API personnelle (Bearer). Documentation : https://forenshield.com/developpeurs/api", "contact": { "name": "ForenShield", "url": "https://forenshield.com/contact", "email": "contact@forenshield.com" }, "termsOfService": "https://forenshield.com/mentions-legales" }, "servers": [ { "url": "https://api.forenshield.com", "description": "Production" } ], "externalDocs": { "url": "https://forenshield.com/developpeurs/api" }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Meta" }, { "name": "Email" }, { "name": "CVE" } ], "paths": { "/v1": { "get": { "tags": [ "Meta" ], "operationId": "getIndex", "summary": "API index", "security": [], "responses": { "200": { "description": "Index", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Index" } } } } } } }, "/v1/openapi.json": { "get": { "tags": [ "Meta" ], "operationId": "getOpenApi", "summary": "OpenAPI document", "security": [], "responses": { "200": { "description": "OpenAPI 3.1", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/me": { "get": { "tags": [ "Meta" ], "operationId": "getCurrentKey", "summary": "Current API key", "responses": { "200": { "description": "Key", "headers": { "X-Request-Id": { "description": "Identifiant unique de la requête (à communiquer au support).", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requêtes autorisées par minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requêtes restantes dans la minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Fin de la fenêtre (epoch, secondes).", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "Quota journalier.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Requêtes restantes aujourd’hui (UTC).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/eml/analyze": { "post": { "tags": [ "Email" ], "operationId": "analyzeEml", "summary": "Analyze an .eml email", "description": "Required scope: `eml:analyze`. Max 10 MB. Send the raw file (message/rfc822), a multipart form (field `file`) or JSON (`eml` or `eml_base64`).", "parameters": [ { "name": "include", "in": "query", "required": false, "description": "Optional sections, comma-separated: headers, body, report (also as a form or JSON field).", "schema": { "type": "string", "enum": [ "headers", "body", "report" ] } }, { "name": "lang", "in": "query", "required": false, "description": "Language of signal labels and report.", "schema": { "type": "string", "enum": [ "fr", "en" ], "default": "fr" } }, { "name": "filename", "in": "query", "required": false, "description": "File name, echoed in file.name.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "message/rfc822": { "schema": { "type": "string", "format": "binary" } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "include": { "type": "string", "description": "headers,body,report" }, "lang": { "type": "string", "enum": [ "fr", "en" ] } }, "required": [ "file" ] } }, "application/json": { "schema": { "type": "object", "properties": { "eml": { "type": "string", "description": "Raw .eml content (text)." }, "eml_base64": { "type": "string", "description": "Base64-encoded .eml file." }, "filename": { "type": "string" }, "include": { "oneOf": [ { "type": "array", "items": { "type": "string", "enum": [ "headers", "body", "report" ] } }, { "type": "string" } ] }, "lang": { "type": "string", "enum": [ "fr", "en" ] } } } } } }, "responses": { "200": { "description": "Analysis", "headers": { "X-Request-Id": { "description": "Identifiant unique de la requête (à communiquer au support).", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requêtes autorisées par minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requêtes restantes dans la minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Fin de la fenêtre (epoch, secondes).", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "Quota journalier.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Requêtes restantes aujourd’hui (UTC).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmlAnalysis" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error (scope, account)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Payload too large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Unsupported media type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Unreadable email", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or daily quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cve/search": { "get": { "tags": [ "CVE" ], "operationId": "searchCves", "summary": "Search CVEs", "description": "Required scope: `cve:read`. Full-text or identifier-prefix search with severity, KEV, ransomware, PoC and recency filters.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search text (e.g. “fortinet”, “log4j”) or identifier prefix (“CVE-2024-3”). Empty: most recent.", "schema": { "type": "string" } }, { "name": "severity", "in": "query", "required": false, "description": "One or more severities, comma-separated: critical, high, medium, low, unknown.", "schema": { "type": "string", "enum": [ "critical", "high", "medium", "low", "unknown" ] } }, { "name": "kev", "in": "query", "required": false, "description": "true: only exploited CVEs (CISA KEV catalog).", "schema": { "type": "boolean" } }, { "name": "ransomware", "in": "query", "required": false, "description": "true: only CVEs used by ransomware.", "schema": { "type": "boolean" } }, { "name": "poc", "in": "query", "required": false, "description": "true: with a public proof of concept; false: without.", "schema": { "type": "boolean" } }, { "name": "published_within_days", "in": "query", "required": false, "description": "Published within the last N days (1 to 3650).", "schema": { "type": "integer" } }, { "name": "sort", "in": "query", "required": false, "description": "recent (publication date) or severity (severity then CVSS score).", "schema": { "type": "string", "enum": [ "recent", "severity" ], "default": "recent" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results (1 to 100).", "schema": { "type": "integer", "default": 20 } }, { "name": "lang", "in": "query", "required": false, "description": "Language of severity labels.", "schema": { "type": "string", "enum": [ "fr", "en" ], "default": "fr" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "description": "Identifiant unique de la requête (à communiquer au support).", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requêtes autorisées par minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requêtes restantes dans la minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Fin de la fenêtre (epoch, secondes).", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "Quota journalier.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Requêtes restantes aujourd’hui (UTC).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CveList" } } } }, "400": { "description": "Invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error (scope cve:read)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or daily quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cve/stats": { "get": { "tags": [ "CVE" ], "operationId": "getCveStats", "summary": "CVE database statistics", "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "description": "Identifiant unique de la requête (à communiquer au support).", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requêtes autorisées par minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requêtes restantes dans la minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Fin de la fenêtre (epoch, secondes).", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "Quota journalier.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Requêtes restantes aujourd’hui (UTC).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CveStats" } } } }, "400": { "description": "Invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error (scope cve:read)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or daily quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/cve/{id}": { "get": { "tags": [ "CVE" ], "operationId": "getCve", "summary": "Get a CVE", "description": "Required scope: `cve:read`. Fetched live from CIRCL / NVD when not yet indexed.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "CVE identifier (e.g. CVE-2021-44228), case-insensitive.", "schema": { "type": "string" } }, { "name": "lang", "in": "query", "required": false, "description": "Language of labels (severity, CVSS metrics).", "schema": { "type": "string", "enum": [ "fr", "en" ], "default": "fr" } } ], "responses": { "200": { "description": "OK", "headers": { "X-Request-Id": { "description": "Identifiant unique de la requête (à communiquer au support).", "schema": { "type": "string" } }, "X-RateLimit-Limit": { "description": "Requêtes autorisées par minute.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requêtes restantes dans la minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Fin de la fenêtre (epoch, secondes).", "schema": { "type": "integer" } }, "X-Quota-Limit": { "description": "Quota journalier.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Requêtes restantes aujourd’hui (UTC).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cve" } } } }, "400": { "description": "Invalid parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error (scope cve:read)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "CVE not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit or daily quota", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Public CVE sources unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "fs_xxxxxxx.<64 hex>", "description": "Personal API key. `X-API-Key` header also accepted." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "authentication_error", "permission_error", "invalid_request_error", "not_found_error", "rate_limit_error", "api_error" ] }, "code": { "type": "string", "enum": [ "missing_api_key", "invalid_api_key", "revoked_api_key", "expired_api_key", "api_key_in_url", "account_disabled", "insufficient_scope", "rate_limited", "quota_exceeded", "route_not_found", "method_not_allowed", "unsupported_media_type", "payload_too_large", "empty_body", "invalid_json", "invalid_base64", "invalid_parameter", "invalid_eml", "cve_not_found", "cve_sources_unavailable", "internal_error" ] }, "message": { "type": "string" }, "param": { "type": [ "string", "null" ] }, "doc_url": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "request_id" ] } } }, "Index": { "type": "object", "properties": { "object": { "type": "string" }, "name": { "type": "string" }, "api_version": { "type": "string" }, "documentation": { "type": "string" }, "openapi": { "type": "string" }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "path": { "type": "string" }, "scope": { "type": [ "string", "null" ] }, "auth": { "type": "boolean" }, "summary": { "type": "string" } } } } } }, "Limit": { "type": "object", "properties": { "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "reset": { "type": "integer", "description": "Epoch seconds" } } }, "ApiKey": { "type": "object", "properties": { "object": { "const": "api_key" }, "prefix": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ] }, "rate_limits": { "type": "object", "properties": { "per_minute": { "$ref": "#/components/schemas/Limit" }, "per_day": { "$ref": "#/components/schemas/Limit" } } } } }, "Address": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "Signal": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "points": { "type": "integer" }, "severity": { "type": "string", "enum": [ "danger", "warning", "info" ] } } }, "Link": { "type": "object", "properties": { "url": { "type": "string" }, "url_defanged": { "type": "string" }, "host": { "type": "string" }, "base_domain": { "type": "string" }, "scheme": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string", "enum": [ "href", "text", "image", "form", "frame", "refresh", "css", "header" ] } }, "displayed_texts": { "type": "array", "items": { "type": "string" } }, "hidden_destination": { "type": [ "string", "null" ] }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "deceptive", "userinfo", "ip", "punycode", "form", "shortener", "redirect", "suspiciousTld", "port", "http", "tracking", "external" ] } }, "risk": { "type": "string", "enum": [ "danger", "warning", "info", "none" ] }, "occurrences": { "type": "integer" } } }, "Observable": { "type": "object", "properties": { "value": { "type": "string" }, "defanged": { "type": "string" }, "context": { "type": "array", "items": { "type": "string" } }, "risk": { "type": "string", "enum": [ "danger", "warning", "info", "none" ] } } }, "Hash": { "type": "object", "properties": { "value": { "type": "string" }, "algorithm": { "type": "string", "enum": [ "md5", "sha1", "sha256" ] }, "file": { "type": "string" }, "risk": { "type": "string", "enum": [ "danger", "warning", "info", "none" ] } } }, "Hop": { "type": "object", "properties": { "index": { "type": "integer" }, "from_host": { "type": [ "string", "null" ] }, "from_reverse_dns": { "type": [ "string", "null" ] }, "ip": { "type": [ "string", "null" ] }, "ip_public": { "type": "boolean" }, "by_host": { "type": [ "string", "null" ] }, "protocol": { "type": [ "string", "null" ] }, "tls": { "type": "boolean" }, "date": { "type": [ "string", "null" ] }, "delay_seconds": { "type": [ "integer", "null" ] }, "anomaly": { "type": [ "string", "null" ], "enum": [ "clock", "slow", null ] } } }, "Attachment": { "type": "object", "properties": { "filename": { "type": [ "string", "null" ] }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "inline": { "type": "boolean" }, "md5": { "type": [ "string", "null" ] }, "sha1": { "type": [ "string", "null" ] }, "sha256": { "type": [ "string", "null" ] }, "dangerous": { "type": "boolean" }, "double_extension": { "type": "boolean" } } }, "EmlAnalysis": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "eml.analysis" }, "api_version": { "type": "string" }, "created_at": { "type": "string" }, "lang": { "type": "string" }, "file": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "size": { "type": "integer" }, "md5": { "type": "string" }, "sha1": { "type": "string" }, "sha256": { "type": "string" } } }, "verdict": { "type": "object", "properties": { "score": { "type": "integer" }, "level": { "type": "string", "enum": [ "critical", "high", "moderate", "low" ] }, "label": { "type": "string" }, "signals": { "type": "array", "items": { "$ref": "#/components/schemas/Signal" } } } }, "message": { "type": "object", "properties": { "subject": { "type": "string" }, "date": { "type": [ "string", "null" ] }, "message_id": { "type": [ "string", "null" ] }, "mailer": { "type": [ "string", "null" ] }, "from": { "$ref": "#/components/schemas/Address" }, "reply_to": { "$ref": "#/components/schemas/Address" }, "return_path": { "type": [ "string", "null" ] }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/Address" } } } }, "authentication": { "type": "object", "properties": { "receiver": { "type": [ "string", "null" ] }, "arc": { "type": "boolean" }, "spf": { "type": "object", "properties": { "result": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "aligned": { "type": [ "boolean", "null" ] } } }, "dkim": { "type": "object", "properties": { "result": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "aligned": { "type": "boolean" }, "signatures": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": [ "string", "null" ] }, "selector": { "type": [ "string", "null" ] }, "algorithm": { "type": [ "string", "null" ] }, "aligned": { "type": "boolean" } } } } } }, "dmarc": { "type": "object", "properties": { "result": { "type": [ "string", "null" ] }, "policy": { "type": [ "string", "null" ] }, "header_from": { "type": [ "string", "null" ] } } }, "identities": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "aligned": { "type": [ "boolean", "null" ] } } } } } }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "observables": { "type": "object", "properties": { "urls": { "type": "array", "items": { "$ref": "#/components/schemas/Observable" } }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Observable" } }, "ips": { "type": "array", "items": { "$ref": "#/components/schemas/Observable" } }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/Observable" } }, "hashes": { "type": "array", "items": { "$ref": "#/components/schemas/Hash" } }, "total": { "type": "integer" } } }, "routing": { "type": "object", "properties": { "origin_ip": { "type": [ "string", "null" ] }, "hop_count": { "type": "integer" }, "total_seconds": { "type": [ "integer", "null" ] }, "anomalies": { "type": "integer" }, "hops": { "type": "array", "items": { "$ref": "#/components/schemas/Hop" } } } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "headers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "description": "Only with include=headers." }, "body": { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ] } }, "description": "Only with include=body. Raw HTML, never rendered by the API." }, "report": { "type": "object", "properties": { "markdown": { "type": "string" } }, "description": "Only with include=report. Defanged Markdown report." } } }, "CveSummary": { "type": "object", "properties": { "object": { "const": "cve" }, "id": { "type": "string" }, "url": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low", "unknown" ] }, "severity_label": { "type": "string" }, "cvss": { "type": "object", "properties": { "score": { "type": [ "number", "null" ] }, "vector": { "type": [ "string", "null" ] }, "version": { "type": [ "string", "null" ] } } }, "description": { "type": "object", "properties": { "en": { "type": [ "string", "null" ] }, "fr": { "type": [ "string", "null" ] } } }, "products": { "type": "array", "items": { "type": "string" } }, "cwe": { "type": "array", "items": { "type": "string" } }, "kev": { "type": "boolean" }, "ransomware": { "type": "boolean" }, "has_poc": { "type": "boolean" }, "published_at": { "type": [ "string", "null" ] }, "modified_at": { "type": [ "string", "null" ] } } }, "Cve": { "allOf": [ { "$ref": "#/components/schemas/CveSummary" }, { "type": "object", "properties": { "source": { "type": "string", "enum": [ "database", "live", "stale" ] }, "cvss_metrics": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "danger": { "type": "integer" } } } }, "mitigation": { "type": "object", "properties": { "en": { "type": [ "string", "null" ] }, "fr": { "type": [ "string", "null" ] } } }, "tags": { "type": "array", "items": { "type": "string" } }, "exploits": { "type": "object", "properties": { "has_poc": { "type": "boolean" }, "dedicated_poc": { "type": "boolean" }, "pocs": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "stars": { "type": [ "integer", "null" ] }, "description": { "type": [ "string", "null" ] } } } } } }, "references": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" } } } }, "updated_at": { "type": [ "string", "null" ] } } } ] }, "CveList": { "type": "object", "properties": { "object": { "const": "list" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "has_more": { "type": "boolean" }, "filters": { "type": "object" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CveSummary" } } } }, "CveStats": { "type": "object", "properties": { "object": { "const": "cve.stats" }, "total": { "type": "integer" }, "kev": { "type": "integer" }, "ransomware": { "type": "integer" }, "critical": { "type": "integer" }, "published_last_7_days": { "type": "integer" }, "refreshed_at": { "type": [ "string", "null" ] } } } } } }