{ "openapi": "3.1.1", "info": { "title": "Security Configuration Scanner API", "version": "1.0.0", "summary": "Passive, graded check of a domain's TLS, security headers, DNS security and security.txt.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://securityconfigurationscanner.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Passive, graded check of a domain's TLS, security headers, DNS security and security.txt.", "description": "For a domain you are authorised to test, checks the live TLS certificate, HTTP security headers, HTTP→HTTPS redirect, DNSSEC (validated via Google Public DNS), CAA, SPF and DMARC, and /.well-known/security.txt (RFC 9116 Contact and Expires), then grades the result and lists concrete fixes. Passive single requests only. You can also paste headers, DNS records and a certificate summary for an offline review, including cookie flags.\n\nMethodology:\n- Only scan systems you own or are authorised to test. This scanner is passive: a handful of ordinary single requests (the home page over HTTPS and HTTP, /.well-known/security.txt, public DNS and one TLS handshake) and no probing, fuzzing or port scanning.\n- TLS + DNS: the DNS + Certificate Explorer is called once (resolver lookups of TXT/CAA/_dmarc and one TLS handshake on port 443, no CT search). Certificate findings: trust, hostname match, expiry (<14 days = warning), RSA key size, TLS 1.0/1.1.\n- DNSSEC: one query to the Google Public DNS JSON API (dns.google/resolve, do=1); AD=true means the answer was DNSSEC-validated.\n- Headers: one GET of https:/// analysed with HeaderLens rules (HSTS, CSP, X-Content-Type-Options, framing, Referrer-Policy, Permissions-Policy, version disclosure). Redirect: one GET of http:///; pass if it ends on https://.\n- security.txt (RFC 9116): Contact and Expires are required; Expires must be in the future, ideally less than a year ahead; served as text/plain.\n- Cookies: only checked from pasted headers (the live fetcher strips Set-Cookie). Only cookie names and flags are reported, never values.\n- Score: 100 minus 20 per high, 8 per medium, 3 per low finding; A ≥ 90, B ≥ 75, C ≥ 60, D ≥ 40, else F; any high finding caps the grade at C.\n\nOnly scan systems you own or are authorised to test. This scanner is passive: a handful of ordinary single requests (the home page over HTTPS and HTTP, /.well-known/security.txt, public DNS and one TLS handshake) and no probing, fuzzing or port scanning.", "tags": [ "security" ], "x-mcp-tool": "security_configuration_scanner", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityConfigurationScannerInput" }, "examples": { "example1": { "summary": "Offline review of pasted findings", "value": { "domain": "shop.example.net", "mode": "pasted", "headers": "HTTP/2 200\ncontent-type: text/html\nstrict-transport-security: max-age=300\nx-content-type-options: nosniff\nserver: nginx/1.18.0\nset-cookie: session=abc; Path=/; HttpOnly\nset-cookie: __Host-csrf=x; Path=/; Secure; HttpOnly; SameSite=Strict", "dnsRecords": "CAA 0 issue \"letsencrypt.org\"\nTXT v=spf1 include:_spf.example.net ~all\nDMARC v=DMARC1; p=none\nDNSSEC no", "certificate": "issuer: CN=R11, O=Let's Encrypt, C=US\nvalidTo: 2026-10-20T12:00:00Z\nprotocol: TLSv1.3\nkeyType: ec\nhostnameMatches: yes\nauthorized: yes", "securityTxt": "Contact: mailto:security@example.net\nExpires: 2026-03-01T00:00:00Z\nPreferred-Languages: en", "httpsRedirect": "yes" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityConfigurationScannerResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "SecurityConfigurationScannerInput": { "type": "object", "additionalProperties": false, "properties": { "domain": { "title": "Domain", "type": "string", "maxLength": 253 }, "mode": { "title": "Mode", "type": "string", "enum": [ "live", "pasted" ], "default": "live" }, "authorized": { "title": "I own this domain or am authorised to test it", "description": "Required for live scans.", "type": "boolean", "default": false }, "headers": { "title": "Pasted: HTTP response headers", "type": "string", "maxLength": 50000 }, "dnsRecords": { "title": "Pasted: DNS records", "type": "string", "maxLength": 20000 }, "certificate": { "title": "Pasted: certificate summary", "type": "string", "maxLength": 5000 }, "securityTxt": { "title": "Pasted: security.txt content", "type": "string", "maxLength": 20000 }, "httpsRedirect": { "title": "Pasted: does http:// redirect to https://?", "type": "string", "enum": [ "unknown", "yes", "no" ], "default": "unknown" } }, "required": [ "domain" ] }, "SecurityConfigurationScannerResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "domain", "mode", "grade", "score", "counts", "findings", "certificate", "dnssec", "httpsRedirect", "securityTxt", "cookies", "notice" ], "properties": { "domain": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "pasted" ] }, "grade": { "type": "string", "enum": [ "A", "B", "C", "D", "F" ] }, "score": { "type": "integer" }, "counts": { "type": "object", "additionalProperties": false, "required": [ "high", "medium", "low", "info" ], "properties": { "high": { "type": "integer" }, "medium": { "type": "integer" }, "low": { "type": "integer" }, "info": { "type": "integer" } } }, "findings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "severity", "area", "finding", "fix" ], "properties": { "severity": { "type": "string", "enum": [ "high", "medium", "low", "info" ] }, "area": { "type": "string" }, "finding": { "type": "string" }, "fix": { "type": [ "string", "null" ] } } } }, "certificate": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "issuer", "validTo", "daysLeft", "protocol", "trusted" ], "properties": { "issuer": { "type": [ "string", "null" ] }, "validTo": { "type": [ "string", "null" ] }, "daysLeft": { "type": [ "integer", "null" ] }, "protocol": { "type": [ "string", "null" ] }, "trusted": { "type": [ "boolean", "null" ] } } }, "dnssec": { "type": [ "boolean", "null" ] }, "httpsRedirect": { "type": [ "boolean", "null" ] }, "securityTxt": { "type": "object", "additionalProperties": false, "required": [ "present", "contact", "expires", "expired", "signed", "fields" ], "properties": { "present": { "type": "boolean" }, "contact": { "type": "array", "items": { "type": "string" } }, "expires": { "type": [ "string", "null" ] }, "expired": { "type": [ "boolean", "null" ] }, "signed": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "string" } } } }, "cookies": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "secure", "httpOnly", "sameSite" ], "properties": { "name": { "type": "string" }, "secure": { "type": "boolean" }, "httpOnly": { "type": "boolean" }, "sameSite": { "type": [ "string", "null" ] } } } }, "notice": { "type": "string" } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }