{ "openapi": "3.0.0", "info": { "title": "HYAS Protect API", "description": "# Endpoint\n\nThe base endpoint is `https://apps.hyas.com/api/protect/ext`, which all of the following REST routes will follow.\n\n\n# Authentication\n\nAuthentication is performed using X-API-Key header with provided PSK API key on each request\n\n# cURL Example\n\n```curl --header \"X-API-Key: \" https://apps.hyas.com/api/protect/ext/reports```\n", "contact": {}, "version": "1.0.0" }, "servers": [ { "url": "https://apps.hyas.com/api/protect/ext", "variables": {} } ], "paths": { "/aggregates": { "post": { "tags": [ "Overview" ], "summary": "newcastle.protect.top_charts.aggregates", "description": "Get count aggregates for the top charts", "operationId": "newcastle.protect.top_charts.aggregates", "parameters": [], "requestBody": { "description": "The filter used to perform aggregate queries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aggregate_params" }, { "description": "The filter used to perform aggregate queries" } ] } } }, "required": true }, "responses": { "200": { "description": "Top Charts", "headers": {}, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/aggregate_response" }, { "description": "Aggregate response" } ] } } } } }, "deprecated": false } }, "/bar": { "post": { "tags": [ "Overview" ], "summary": "newcastle.protect.bar_charts.bar", "description": "Get bar chart data", "operationId": "newcastle.protect.bar_charts.bar", "parameters": [], "requestBody": { "description": "The filter used to perform bar chart queries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bar_params" }, { "description": "The filter used to perform bar chart queries" } ] } } }, "required": true }, "responses": { "200": { "description": "Bar Chart", "headers": {}, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/bar_response" }, { "description": "Bar chart response" } ] } } } } }, "deprecated": false } }, "/histogram": { "post": { "tags": [ "Overview" ], "summary": "newcastle.protect.histograms.histogram", "description": "Get histogram data for the real time charts", "operationId": "newcastle.protect.histograms.histogram", "parameters": [], "requestBody": { "description": "The filter used to perform histogram queries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/histogram_params" }, { "description": "The filter used to perform histogram queries" } ] } } }, "required": true }, "responses": { "200": { "description": "Historgram", "headers": {}, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/histogram_response" }, { "description": "Histogram response" } ] } } } } }, "deprecated": false } }, "/summary": { "post": { "tags": [ "Overview" ], "summary": "newcastle.protect.summaries.summary", "description": "Get request summaries", "operationId": "newcastle.protect.summaries.summary", "parameters": [], "requestBody": { "description": "The filter used to perform summary queries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/summary_params" }, { "description": "The filter used to perform summary queries" } ] } } }, "required": true }, "responses": { "200": { "description": "Summary", "headers": {}, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/summary_response" }, { "description": "Summary response" } ] } } } } }, "deprecated": false } }, "/histogram/artifact": { "post": { "tags": [ "Logs" ], "summary": "newcastle.protect.histograms.histogram_artifact", "description": "Get histogram data for the pop out panel timeline chart", "operationId": "newcastle.protect.histograms.histogram_artifact", "parameters": [], "requestBody": { "description": "The filter used to perform histogram queries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/histogram_artifact_params" }, { "description": "The filter used to perform histogram queries" } ] } } }, "required": true }, "responses": { "200": { "description": "Flyout Panel Artifact Historgram", "headers": {}, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/histogram_artifact_response" }, { "description": "Histogram response" } ] } } } } }, "deprecated": false } }, "/logs": { "post": { "tags": [ "Logs" ], "summary": "newcastle.protect.logs.logs", "description": "Get logs", "operationId": "newcastle.protect.logs.logs", "parameters": [], "requestBody": { "description": "The filter used to perform log queries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/log_params" }, { "description": "The filter used to perform log queries" } ] } } }, "required": true }, "responses": { "200": { "description": "Logs", "headers": {}, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/log_response" }, { "description": "Summary response" } ] } } } } }, "deprecated": false } }, "/passthrough": { "post": { "tags": [ "Passthrough" ], "summary": "newcastle.protect.passthrough.passthrough", "description": "Get passthrough records", "operationId": "newcastle.protect.passthrough.passthrough", "parameters": [], "requestBody": { "description": "The filter used to perform passthrough queries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/passthrough_params" }, { "description": "The filter used to perform passthrough queries" } ] } } }, "required": true }, "responses": { "200": { "description": "Logs", "headers": {}, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/passthrough_response" }, { "description": "Passthrough response" } ] } } } } }, "deprecated": false } }, "/report": { "post": { "tags": [ "Reports" ], "summary": "newcastle.protect.reports.get_report", "description": "Get executive report", "operationId": "newcastle.protect.reports.get_report", "parameters": [], "requestBody": { "description": "The filter used to generate the report", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/report_params" }, { "description": "The filter used to generate the report" } ] } } }, "required": true }, "responses": { "200": { "description": "A report in pdf format", "headers": {}, "content": { "application/pdf": { "schema": {} } } } }, "deprecated": false } }, "/reports": { "post": { "tags": [ "Reports" ], "summary": "newcastle.protect.reports.get_reports", "description": "Get list of executive reports", "operationId": "newcastle.protect.reports.get_reports", "parameters": [], "responses": { "200": { "description": "Bar Chart", "headers": {}, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/reports_response" }, { "description": "List of reports and count" } ] } } } } }, "deprecated": false } } }, "components": { "schemas": { "aggregate_params": { "title": "aggregate_params", "type": "object", "properties": { "applied_filters": { "allOf": [ { "$ref": "#/components/schemas/AppliedFilters" }, { "description": "A filter object specific to the query endpoint." } ] } } }, "aggregate_response": { "title": "aggregate_response", "type": "object", "properties": { "query_type": { "type": "string", "description": "The query type that the aggregate is for", "example": "fqdn" }, "top_items": { "type": "array", "items": { "$ref": "#/components/schemas/TopItem" }, "description": "Top items" } }, "description": "Aggregate response" }, "bar_params": { "title": "bar_params", "type": "object", "properties": { "applied_filters": { "allOf": [ { "$ref": "#/components/schemas/AppliedFilters1" }, { "description": "A filter object specific to the query endpoint." } ] } } }, "bar_response": { "title": "bar_response", "type": "object", "properties": { "query_type": { "type": "string", "description": "The query type that the aggregate is for", "example": "no_answer_queries" }, "top_items": { "type": "array", "items": { "$ref": "#/components/schemas/TopItem1" }, "description": "Top items" } }, "description": "Bar chart response" }, "histogram_artifact_params": { "title": "histogram_artifact_params", "type": "object", "properties": { "applied_filters": { "allOf": [ { "$ref": "#/components/schemas/AppliedFilters2" }, { "description": "A filter object specific to the query endpoint." } ] } } }, "histogram_artifact_response": { "title": "histogram_artifact_response", "type": "object", "properties": { "days": { "type": "integer", "description": "The number of days the histogram is for", "format": "int32" }, "query_type": { "type": "string", "description": "The query type that the histogram is for" } }, "description": "Histogram response" }, "histogram_params": { "title": "histogram_params", "type": "object", "properties": { "applied_filters": { "allOf": [ { "$ref": "#/components/schemas/AppliedFilters3" }, { "description": "A filter object specific to the query endpoint." } ] } } }, "histogram_response": { "title": "histogram_response", "type": "object", "properties": { "query_type": { "type": "string", "description": "The query type that the aggregate is for", "example": "queries" }, "top_items": { "type": "array", "items": { "$ref": "#/components/schemas/TopItem" }, "description": "Top items" } }, "description": "Histogram response" }, "log_params": { "title": "log_params", "type": "object", "properties": { "applied_filters": { "type": "array", "items": { "$ref": "#/components/schemas/AppliedFilters4" }, "description": "" } } }, "log_params_query_type_values": { "title": "log_params_query_type_values", "enum": [ "A", "A6", "AAAA", "AFSDB", "AMTRELAY", "ANY", "APL", "ATMA", "AVC", "AXFR", "CAA", "CDS", "CDNSKEY", "CERT", "CNAME", "CSYNC", "DHCID", "DLV", "DNAME", "DNSKEY", "DOA", "DS", "EID", "EUI48", "EUI64", "GID", "GPOS", "HINFO", "HIP", "HTTPS", "IPSECKEY", "ISDN", "IXFR", "KEY", "KX", "L32", "L64", "LP", "LOC", "MAILA", "MAILB", "MB", "MD", "MF", "MG", "MINFO", "MR", "MX", "NAPTR", "NID", "NIMLOC", "NINFO", "NS", "NSAP", "NSAP-PTR", "NSEC", "NSEC3", "NSEC3PARAM", "NXT", "OPENPGPKEY", "OPT", "PTR", "PX", "RKEY", "RP", "RRSIG", "RT", "RV", "SIG", "SINK", "SMIMEA", "SOA", "SPF", "SSHFP", "SVCB", "TA", "TALINK", "TKEY", "TLSA", "TSIG", "TXT", "UID", "UINFO", "Unassigned", "UNSPEC", "URI", "WKS", "X25", "ZONEMD" ], "type": "string" }, "log_params_reputation_values": { "title": "log_params_reputation_values", "enum": [ "blocked", "malicious", "suspicious", "permitted" ], "type": "string" }, "log_response": { "title": "log_response", "type": "object", "properties": { "aggregates": { "allOf": [ { "$ref": "#/components/schemas/Aggregates" }, { "description": "Aggregates for the filter drop downs" } ] }, "total_count": { "type": "integer", "description": "total count of records without pagination", "format": "int32", "example": 197 } }, "description": "Summary response" }, "passthrough_params": { "title": "passthrough_params", "type": "object", "properties": { "applied_filters": { "type": "array", "items": { "$ref": "#/components/schemas/AppliedFilters5" }, "description": "" } } }, "passthrough_response": { "title": "passthrough_response", "type": "object", "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/Log" }, "description": "Collection of passthrough records" }, "total_count": { "type": "integer", "description": "total count of records without pagination", "format": "int32", "example": 197 } }, "description": "Passthrough response" }, "query": { "title": "query", "type": "object", "properties": { "applied_filters": { "type": "object", "description": "A filter object specific to the query endpoint." } } }, "report_params": { "title": "report_params", "type": "object", "properties": { "applied_filters": { "allOf": [ { "$ref": "#/components/schemas/AppliedFilters6" }, { "description": "A filter object specific to the query endpoint." } ] } } }, "reports_response": { "title": "reports_response", "type": "object", "properties": { "reports": { "type": "array", "items": { "$ref": "#/components/schemas/Report" }, "description": "Collection of reports" }, "total_count": { "type": "integer", "description": "The total report count", "format": "int32" } }, "description": "List of reports and count" }, "summary_params": { "title": "summary_params", "type": "object", "properties": { "applied_filters": { "allOf": [ { "$ref": "#/components/schemas/AppliedFilters7" }, { "description": "A filter object specific to the query endpoint." } ] } } }, "summary_response": { "title": "summary_response", "type": "object", "properties": { "day_count": { "type": "integer", "format": "int32", "example": 1 }, "query_type": { "type": "string", "description": "The query type that the aggregate is for", "example": "blocked" }, "total_count": { "type": "integer", "format": "int32", "example": 0 } }, "description": "Summary response" }, "Aggregates": { "title": "Aggregates", "type": "object", "properties": { "queries": { "type": "array", "items": { "$ref": "#/components/schemas/Query2" }, "description": "Collection of query type codes and counts" }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/Response" }, "description": "Collection of response codes and counts" } }, "description": "Aggregates for the filter drop downs" }, "AppliedFilters": { "title": "AppliedFilters", "type": "object", "properties": { "query_type": { "allOf": [ { "$ref": "#/components/schemas/QueryType" }, { "description": "The type of aggregate query to perform" } ] }, "top_count": { "type": "integer", "description": "How many aggregate values to get", "format": "int32", "example": 25 } }, "description": "A filter object specific to the query endpoint." }, "AppliedFilters1": { "title": "AppliedFilters1", "type": "object", "properties": { "query_type": { "allOf": [ { "$ref": "#/components/schemas/QueryType1" }, { "description": "The type of bar chart query to perform" } ] } }, "description": "A filter object specific to the query endpoint." }, "AppliedFilters2": { "title": "AppliedFilters2", "type": "object", "properties": { "artifact": { "type": "string", "description": "The artifact", "example": "google.com" }, "artifact_type": { "allOf": [ { "$ref": "#/components/schemas/ArtifactType" }, { "description": "The artifact type", "example": "domain.keyword" } ] }, "end_date": { "type": "string", "description": "The end window", "example": "2021-09-29" }, "interval": { "type": "string", "description": "The optional interval for the aggregate", "example": "1d" }, "query_type": { "allOf": [ { "$ref": "#/components/schemas/QueryType2" }, { "description": "The type of query", "example": "queries" } ] }, "start_date": { "type": "string", "description": "The start window", "example": "2021-09-22" } }, "description": "A filter object specific to the query endpoint." }, "AppliedFilters3": { "title": "AppliedFilters3", "type": "object", "properties": { "query_type": { "allOf": [ { "$ref": "#/components/schemas/QueryType3" }, { "description": "The type of histogram query to perform" } ] } }, "description": "A filter object specific to the query endpoint." }, "AppliedFilters4": { "title": "AppliedFilters4", "type": "object", "properties": { "exclude": { "type": "boolean", "description": "Flag to indicate if the filter value should be excluded", "example": false }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id" }, { "description": "The filter id", "example": "domain" } ] }, "isRange": { "type": "boolean", "description": "Flag to indicate if the filter value is a range", "example": false }, "partial": { "type": "boolean", "description": "If the filter should do partial matching", "example": true }, "rangeValue": { "allOf": [ { "oneOf": [ { "nullable": true }, { "$ref": "#/components/schemas/RangeValue" } ] }, {} ] }, "value": { "type": "string", "description": "The filter value", "nullable": true, "example": "google" } } }, "AppliedFilters5": { "title": "AppliedFilters5", "type": "object", "properties": { "exclude": { "type": "boolean", "description": "Flag to indicate if the filter value should be excluded", "example": false }, "id": { "allOf": [ { "$ref": "#/components/schemas/Id1" }, { "description": "The filter id", "example": "last_seen" } ] }, "isRange": { "type": "boolean", "description": "Flag to indicate if the filter value is a range", "example": true }, "partial": { "type": "boolean", "description": "If the filter should do partial matching", "example": false }, "rangeValue": { "allOf": [ { "oneOf": [ { "nullable": true }, { "$ref": "#/components/schemas/RangeValue" } ] }, {} ] }, "value": { "type": "string", "description": "The filter value", "nullable": true } } }, "AppliedFilters6": { "title": "AppliedFilters6", "type": "object", "properties": { "report_id": { "type": "string", "description": "ID (uuid) of the report", "example": "00000000-00000000-00000000-00000000" } }, "description": "A filter object specific to the query endpoint." }, "AppliedFilters7": { "title": "AppliedFilters7", "type": "object", "properties": { "query_type": { "allOf": [ { "$ref": "#/components/schemas/QueryType4" }, { "description": "The type of summary query to perform" } ] } }, "description": "A filter object specific to the query endpoint." }, "ArtifactType": { "title": "ArtifactType", "enum": [ "domain.keyword", "domain_2tld.keyword", "nameserver_tld.keyword", "nameserver.keyword", "nameserver_ip.keyword", "response.a.keyword", "response.aaaa.keyword", "response.cname.keyword", "response.cname_2tld.keyword" ], "type": "string", "description": "The artifact type", "example": "domain.keyword" }, "Id": { "title": "Id", "enum": [ "domain", "domain_2tld", "domain_tld", "domain_age", "query_type", "response_code", "ttl", "nameserver", "nameserver_2tld", "nameserver_tld", "nameserver_ip", "a_record", "aaaa_record", "c_name", "c_name_2tld", "c_name_tld", "registrar", "reputation", "datetime" ], "type": "string", "description": "The filter id", "example": "domain" }, "Id1": { "title": "Id1", "enum": [ "last_seen", "artifact", "hyas_status", "alt_status", "query_count" ], "type": "string", "description": "The filter id", "example": "last_seen" }, "Log": { "title": "Log", "type": "object", "properties": { "alt_status": { "type": "string", "description": "The status of the request made through ALT [blocked, allow]", "example": "allow" }, "artifact": { "type": "string", "description": "The artifact looked up", "example": "google.com" }, "hyas_status": { "type": "string", "description": "The status of the request made through HYAS [blocked, allow]", "example": "blocked" }, "last_seen": { "type": "string", "description": "The most recent query for the artifact", "example": "2021-11-05T05:00:00" }, "query_count": { "type": "integer", "description": "The aggregated count of how many times the artifact was looked up, limited to the current params", "format": "int32", "example": 100 } } }, "Query2": { "title": "Query2", "type": "object", "properties": { "count": { "type": "integer", "description": "Query type count", "format": "int32", "example": 2058 }, "key": { "type": "string", "description": "Query type key", "example": "AAAA" }, "name": { "type": "string", "description": "Query type display name", "example": "AAAA" } }, "description": "Query type" }, "QueryType": { "title": "QueryType", "enum": [ "domain", "fqdn", "country", "tld", "registrar" ], "type": "string", "description": "The type of aggregate query to perform" }, "QueryType1": { "title": "QueryType1", "enum": [ "block_queries", "no_answer_queries", "tor_prox_vpn_queries", "suspicious_nameserver_queries" ], "type": "string", "description": "The type of bar chart query to perform" }, "QueryType2": { "title": "QueryType2", "enum": [ "queries", "queries_over_day", "queries_over_hour" ], "type": "string", "description": "The type of query", "example": "queries" }, "QueryType3": { "title": "QueryType3", "enum": [ "queries", "blocked_queries" ], "type": "string", "description": "The type of histogram query to perform" }, "QueryType4": { "title": "QueryType4", "enum": [ "total", "blocked", "indicators" ], "type": "string", "description": "The type of summary query to perform" }, "RangeValue": { "title": "RangeValue", "type": "object", "properties": { "end": { "type": "string", "description": "The range end value", "example": "2021-09-24T01:21:58.283Z" }, "start": { "type": "string", "description": "The range start value", "example": "2021-09-17T01:21:58.283Z" } } }, "Report": { "title": "Report", "type": "object", "properties": { "client_id": { "type": "string", "description": "Client ID" }, "datetime": { "type": "string", "description": "Report generation datetime" }, "datetime_end": { "type": "string", "description": "Report end date" }, "datetime_start": { "type": "string", "description": "Report start date" }, "report_id": { "type": "string", "description": "Report ID" } }, "description": "Report" }, "Response": { "title": "Response", "type": "object", "properties": { "count": { "type": "integer", "description": "Response code count", "format": "int32", "example": 8980 }, "key": { "type": "string", "description": "Response code key", "example": "NoError" }, "name": { "type": "string", "description": "Response code display name", "example": "NoError" } }, "description": "Response codes" }, "TopItem": { "title": "TopItem", "type": "object", "properties": { "current_doc_count": { "type": "integer", "format": "int32", "example": 9116 }, "key": { "type": "string", "example": "debug.opendns.com" }, "previous_doc_count": { "type": "integer", "format": "int32", "example": 7151 } } }, "TopItem1": { "title": "TopItem1", "type": "object", "properties": { "current_doc_count": { "type": "integer", "format": "int32", "example": 369 }, "key": { "type": "string", "example": "2021-09-20 00:00:00" }, "previous_doc_count": { "type": "integer", "format": "int32", "example": 303 }, "previous_key": { "type": "string", "example": "2021-09-13 00:00:00" } } } }, "securitySchemes": { "external_auth": { "type": "apiKey", "name": "X-API-Key", "in": "header" } } }, "security": [ { "external_auth": [] } ], "tags": [ { "name": "Overview" }, { "name": "Logs" }, { "name": "Passthrough" }, { "name": "Reports" } ] }