addedOutput schema / $defs
Added value: +{
+ "ErrorDetail": {
+ "description": "Structured failure body. Codes mirror app/exceptions.AppException\nsubclasses; agent retry / upgrade decisions key off `code`, not `message`.",
+ "properties": {
+ "code": {
+ "description": "Stable machine-readable failure category. Agents key retry/upgrade decisions off this.",
+ "enum": [
+ "invalid_argument",
+ "not_found",
+ "rate_limit_exceeded",
+ "auth_required",
+ "tier_limit",
+ "upstream_timeout",
+ "upstream_error",
+ "internal_error"
+ ],
+ "title": "Code",
+ "type": "string"
+ },
+ "docs_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Documentation pointer (e.g. tool input contract) when code='invalid_argument'.",
+ "title": "Docs Url"
+ },
+ "message": {
+ "description": "Human-readable detail. Free text — never parse. Capped at 500 chars to prevent oversized upstream errors from bloating responses.",
+ "maxLength": 500,
+ "title": "Message",
+ "type": "string"
+ },
+ "retry_after_seconds": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "When code='rate_limit_exceeded', the minimum seconds to wait before retrying.",
+ "title": "Retry After Seconds"
+ },
+ "upgrade_url": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Pricing/upgrade URL when code='tier_limit' or 'rate_limit_exceeded' on the Free tier.",
+ "title": "Upgrade Url"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "title": "ErrorDetail",
+ "type": "object"
+ },
+ "ErrorResponse": {
+ "description": "MCP error envelope. Tool return type is always\n`SpecificResponse | ErrorResponse` — Union flag tells the agent which arm\narrived without parsing the inner body.",
+ "properties": {
+ "error": {
+ "$ref": "#/$defs/ErrorDetail"
+ }
+ },
+ "required": [
+ "error"
+ ],
+ "title": "ErrorResponse",
+ "type": "object"
+ },
+ "FeodoSource": {
+ "description": "Feodo Tracker C2 blocklist entry inside IocResponse.sources.feodo (IP only).",
+ "properties": {
+ "first_seen": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "ISO timestamp of first Feodo observation. Null when found=False.",
+ "title": "First Seen"
+ },
+ "found": {
+ "description": "True when the IP appears on the Feodo Tracker C2 blocklist.",
+ "title": "Found",
+ "type": "boolean"
+ },
+ "last_online": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "ISO timestamp the C2 was last seen online. Null when found=False.",
+ "title": "Last Online"
+ },
+ "malware": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Malware family attributed by Feodo (e.g. 'Emotet'). Null when found=False.",
+ "title": "Malware"
+ },
+ "status": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "C2 lifecycle status per Feodo (e.g. 'online', 'offline'). Null when found=False.",
+ "title": "Status"
+ }
+ },
+ "required": [
+ "found"
+ ],
+ "title": "FeodoSource",
+ "type": "object"
+ },
+ "IocResponse": {
+ "properties": {
+ "indicator": {
+ "description": "Echoed input indicator (sanitized; control chars stripped).",
+ "title": "Indicator",
+ "type": "string"
+ },
+ "next_calls": {
+ "anyOf": [
+ {
+ "items": {
+ "$ref": "#/$defs/PivotHint"
+ },
+ "type": "array"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Suggested follow-up MCP tool calls. Ordered by relevance; agents should chain these without re-prompting the user.",
+ "title": "Next Calls"
+ },
+ "sources": {
+ "$ref": "#/$defs/IocSourcesInfo",
+ "description": "Per-source lookup results. See IocSourcesInfo for which sources apply per indicator type."
+ },
+ "summary": {
+ "default": "",
+ "description": "One-line human summary aggregating threat indicators across sources.",
+ "title": "Summary",
+ "type": "string"
+ },
+ "threat_level": {
+ "default": "none",
+ "description": "Heuristic threat tier from cross-source agreement. 'high' = >=2 sources flagged; 'medium' = 1 source flagged; 'none' = no source flagged. 'low' is a soft cap applied when the only flag came from a ThreatFox test/demo honeypot tag.",
+ "enum": [
+ "none",
+ "low",
+ "medium",
+ "high"
+ ],
+ "title": "Threat Level",
+ "type": "string"
+ },
+ "type": {
+ "description": "Auto-detected indicator type. 'unknown' is rejected at route level (400).",
+ "enum": [
+ "ip",
+ "domain",
+ "url",
+ "hash",
+ "unknown"
+ ],
+ "title": "Type",
+ "type": "string"
+ },
+ "verdict": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/Verdict"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Falsifiability metadata: sources_queried, sources_unavailable, completeness, deterministic flag. Lets agents distinguish 'no data' from 'source failed' without re-running the call."
+ }
+ },
+ "required": [
+ "indicator",
+ "type"
+ ],
+ "title": "IocResponse",
+ "type": "object"
+ },
+ "IocSourcesInfo": {
+ "description": "Per-source lookup results inside IocResponse. Keys present depend on indicator type.\n\n- hash → only `threatfox` (Feodo and URLhaus do not index hashes).\n- ip → `threatfox` + `feodo` + `urlhaus` + `tor`.\n- domain / url → `threatfox` + `urlhaus`.",
+ "properties": {
+ "feodo": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/FeodoSource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Feodo Tracker C2 blocklist lookup. IP indicators only."
+ },
+ "threatfox": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/ThreatFoxSource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "ThreatFox lookup result. Always queried."
+ },
+ "tor": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/TorSource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Tor exit list membership. IP indicators only."
+ },
+ "urlhaus": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/UrlhausSource"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "URLhaus URL/host match. IP/domain/URL indicators."
+ }
+ },
+ "title": "IocSourcesInfo",
+ "type": "object"
+ },
+ "PivotHint": {
+ "additionalProperties": true,
+ "description": "A suggested follow-up MCP tool call. Surfaced inside response.next_calls so\nLLM agents can chain related lookups without manual prompting. Each hint names\nthe tool, the input value to pass, and a short reason explaining why this\npivot adds value in the current context.",
+ "properties": {
+ "input": {
+ "description": "Suggested input value to pass to the tool — typically a CVE ID, CWE ID, domain, or IP. Pre-populated from the current response so the agent can call the next tool without re-deriving the argument.",
+ "title": "Input",
+ "type": "string"
+ },
+ "params": {
+ "anyOf": [
+ {
+ "additionalProperties": {
+ "type": "string"
+ },
+ "type": "object"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Optional extra kwargs to pass alongside `input`. Used by pivot generators when the next call benefits from a secondary parameter, e.g. {'exclude_id': 'AML.T0051'} to skip the originating technique from a sibling-tactic search. Omitted when no extra args are needed.",
+ "title": "Params"
+ },
+ "reason": {
+ "description": "Short rationale (one sentence) for why this follow-up call adds value, e.g. 'Federal patch deadline + ransomware association', 'Public exploits / PoC availability'.",
+ "title": "Reason",
+ "type": "string"
+ },
+ "tool": {
+ "description": "Canonical MCP tool name to call next. Constrained to known operation_ids in tools/list — adding a new tool here requires expanding the Literal.",
+ "enum": [
+ "cve_lookup",
+ "cve_search",
+ "cve_leading",
+ "bulk_cve_lookup",
+ "exploit_lookup",
+ "kev_detail",
+ "cwe_lookup",
+ "subdomain_enum",
+ "ssl_check",
+ "tech_fingerprint",
+ "asn_lookup",
+ "ip_lookup",
+ "ioc_lookup",
+ "bulk_ioc_lookup",
+ "hash_lookup",
+ "threat_intel",
+ "threat_report",
+ "audit_domain",
+ "domain_report",
+ "dns_lookup",
+ "whois_lookup",
+ "wayback_lookup",
+ "scan_headers",
+ "check_headers",
+ "check_secrets",
+ "check_injection",
+ "check_dependencies",
+ "email_mx",
+ "email_disposable",
+ "phone_lookup",
+ "username_lookup",
+ "password_check",
+ "phishing_check",
+ "atlas_technique_lookup",
+ "atlas_technique_search",
+ "bulk_atlas_technique_lookup",
+ "atlas_case_study_lookup",
+ "atlas_case_study_search",
+ "d3fend_defense_lookup",
+ "d3fend_defense_search",
+ "d3fend_defense_for_attack",
+ "d3fend_attack_coverage"
+ ],
+ "title": "Tool",
+ "type": "string"
+ }
+ },
+ "required": [
+ "tool",
+ "input",
+ "reason"
+ ],
+ "title": "PivotHint",
+ "type": "object"
+ },
+ "ThreatFoxSource": {
+ "description": "ThreatFox abuse.ch source entry inside IocResponse.sources.threatfox.",
+ "properties": {
+ "confidence": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "ThreatFox confidence score (0-100). Null when found=False or not provided upstream.",
+ "title": "Confidence"
+ },
+ "error": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "'upstream timeout' or 'upstream error' when ThreatFox query failed; absent on success.",
+ "title": "Error"
+ },
+ "first_seen": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "ISO timestamp of first ThreatFox observation. Null when found=False.",
+ "title": "First Seen"
+ },
+ "found": {
+ "description": "True when ThreatFox returned at least one IOC entry for the indicator.",
+ "title": "Found",
+ "type": "boolean"
+ },
+ "ioc_count": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Total ThreatFox IOC entries matching this indicator. Null when found=False.",
+ "title": "Ioc Count"
+ },
+ "malware": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Malware family name (e.g. 'Cobalt Strike'). Null when found=False.",
+ "title": "Malware"
+ },
+ "tags": {
+ "description": "ThreatFox tags. May include 'test'/'demo' for honeypot entries.",
+ "items": {
+ "type": "string"
+ },
+ "title": "Tags",
+ "type": "array"
+ },
+ "threat_type": {
+ "anyOf": [
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Threat classification (e.g. 'botnet_cc', 'payload_delivery'). Null when found=False.",
+ "title": "Threat Type"
+ }
+ },
+ "required": [
+ "found"
+ ],
+ "title": "ThreatFoxSource",
+ "type": "object"
+ },
+ "TorSource": {
+ "description": "Tor exit list entry inside IocResponse.sources.tor (IP only).",
+ "properties": {
+ "fetch_status": {
+ "description": "Cache state of the Tor exit list snapshot used for the lookup. 'initial' = no refresh has run yet; 'ok' = fresh fetch; 'failed' = upstream fetch failed (treat listed=False as 'unknown', not 'safe'); 'capped' = upstream response exceeded the size cap and was rejected.",
+ "enum": [
+ "initial",
+ "ok",
+ "failed",
+ "capped"
+ ],
+ "title": "Fetch Status",
+ "type": "string"
+ },
+ "listed": {
+ "description": "True when the IP appears in the Tor Project's bulk exit list.",
+ "title": "Listed",
+ "type": "boolean"
+ }
+ },
+ "required": [
+ "listed",
+ "fetch_status"
+ ],
+ "title": "TorSource",
+ "type": "object"
+ },
+ "UrlhausSource": {
+ "description": "URLhaus abuse.ch source entry inside IocResponse.sources.urlhaus.",
+ "properties": {
+ "found": {
+ "description": "True when URLhaus has at least one URL for the indicator.",
+ "title": "Found",
+ "type": "boolean"
+ },
+ "urls_online": {
+ "default": 0,
+ "description": "Subset of URLhaus URLs currently marked online.",
+ "title": "Urls Online",
+ "type": "integer"
+ }
+ },
+ "required": [
+ "found"
+ ],
+ "title": "UrlhausSource",
+ "type": "object"
+ },
+ "Verdict": {
+ "properties": {
+ "completeness": {
+ "default": "complete",
+ "description": "'complete' = every planned source returned data; 'partial' = at least one source in sources_unavailable failed or was skipped; 'minimal' = only the primary/required source returned, optional enrichment missing.",
+ "enum": [
+ "complete",
+ "partial",
+ "minimal"
+ ],
+ "title": "Completeness",
+ "type": "string"
+ },
+ "data_age_seconds": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Seconds elapsed since the oldest cached source was fetched, or null when every source was queried live for this request. Use to judge freshness.",
+ "title": "Data Age Seconds"
+ },
+ "deterministic": {
+ "description": "True when the response is fully reproducible from the listed sources for the same input at the same moment (no randomness, no model inference). False for endpoints that include probabilistic scoring or LLM output.",
+ "title": "Deterministic",
+ "type": "boolean"
+ },
+ "falsifiable_fields": {
+ "description": "Top-level response fields whose values a caller can independently re-derive from the named upstream sources (e.g. 'dns', 'ssl', 'whois'). Fields not in this list are derived/computed and cannot be directly re-verified.",
+ "items": {
+ "type": "string"
+ },
+ "title": "Falsifiable Fields",
+ "type": "array"
+ },
+ "sources_queried": {
+ "description": "Canonical source identifiers successfully consulted for this response (e.g. 'ripe_stat', 'shodan_internetdb', 'firehol'). Agent-readable list, order not significant.",
+ "items": {
+ "type": "string"
+ },
+ "title": "Sources Queried",
+ "type": "array"
+ },
+ "sources_unavailable": {
+ "description": "Sources that were expected but not returned — either intentionally skipped (lite mode, tier gating) or failed (quota, timeout, upstream down). Empty list means every planned source produced data.",
+ "items": {
+ "type": "string"
+ },
+ "title": "Sources Unavailable",
+ "type": "array"
+ }
+ },
+ "required": [
+ "deterministic"
+ ],
+ "title": "Verdict",
+ "type": "object"
+ }
+}
