diff --git a/RFCs/2021-04-16-77-module-reflection.md b/RFCs/2021-04-16-77-module-reflection.md index 7468ba901..9bde8fc68 100644 --- a/RFCs/2021-04-16-77-module-reflection.md +++ b/RFCs/2021-04-16-77-module-reflection.md @@ -7,104 +7,216 @@ metrics schema. All interfaces and schemas are versioned. -``` -/api/v1/inputs +`GET /api/v1/inputs` + +```json { - pcap: "1.0", - "dnstap": "1.0" - } -/api/v1/inputs/pcap/interface + "pcap": { + "version": "1.0" + }, + "dnstap": { + "version": "1.0" + } +} +``` + +`GET /api/v1/inputs/pcap/features` + +```json { - version: "1.0", + "version": "1.0", "info": { - "interfaces": { - "eth0": {} + "available_iface": { + "eth0": {}, + "eth1": {} } }, - "defaults": { - "interface": eth0 - }, - config: { - iface: { - type: "string", - description: "the ethernet interface to capture on" - } - } - filters: { - bpf: { - type: "string", - description: "tcpdump compatible bpf filter expression" + "config": { + "iface": { + "required": true, + "type": "string", + "name": "Interface", + "description": "The ethernet interface to capture on" + }, + "bpf": { + "required": false, + "type": "string", + "name": "Filter Expression", + "description": "tcpdump compatible filter expression for limiting the traffic examined (with BPF). Example: \"port 53\"" + }, + "host_spec": { + "required": false, + "type": "string", + "name": "Host Specification", + "description": "Subnets (comma separated) to consider this HOST, in CIDR form. Example: \"10.0.1.0/24,10.0.2.1/32,2001:db8::/64\"" + }, + "pcap_source": { + "required": false, + "type": "string", + "name": "pcap Engine", + "description": "pcap backend engine to use. Defaults to best for platform." } - }, - metric_groups: { } - } -/api/v1/inputs/dnstap/interface +} +``` + +`GET /api/v1/handlers` + +```json { - version: "1.0", - config: { - socket: { - type: "string", - description: "the dnstap socket to listen to" - } + "dns": { + "version": "1.0" + }, + "net": { + "version": "1.0" + }, + "pcap": { + "version": "1.0" } - filters: { - qname_suffix: { - type: "string", - description: "match the DNS qname sufix given", - regex: "..." +} +``` + +`GET /api/v1/handlers/dns/features` + +```json +{ + "version": "1.0", + "config": { + "filter_exclude_noerror": { + "name": "Filter: Exclude NOERROR", + "type": "bool", + "description": "Filter out all NOERROR responses" + }, + "filter_only_rcode": { + "name": "Filter: Include Only RCode", + "type": "integer", + "description": "Filter out any queries which are not the given RCODE" + }, + "filter_only_qname_suffix": { + "name": "Filter: Include Only QName With Suffix", + "type": "array[string]", + "description": "Filter out any queries whose QName does not end in a suffix on the list" } }, - metric_groups: { - } - } -/api/v1/handlers - { dns: { version: "1.0" }, - net: { version: "1.0" } } -/api/v1/handlers/dns/interface - { - version: "1.0", - config: { - periods: { - type: "int", - description: "number of metric periods to keep" + "metrics": { + "cardinality.qname": { + "type": "cardinality", + "description": "..." + }, + "in": { + "type": "counter", + "description": "..." + }, + "xact.counts.timed_out": { + "type": "integer", + "description": "..." + }, + "xact.counts.total": { + "type": "integer", + "description": "..." + }, + "xact.in.top_slow": { + "type": "top_n", + "description": "..." + } + }, + "metric_groups": { + "cardinality": { + "name": "Cardinality", + "description": "Metrics counting the unique number of items in the stream", + "metrics": [ + "cardinality.qname" + ] + }, + "dns_transactions": { + "name": "DNS Transactions (Query/Reply pairs)", + "description": "Metrics based on tracking queries and their associated replies", + "metrics": [ + "xact.counts.timed_out", + "xact.counts.total", + "xact.in.top_slow" + ] + }, + "top_dns_wire": { + "name": "Top N Metrics (Various)", + "description": "Top N metrics across various details from the DNS wire packets", + "metrics": [ + "..." + ] + }, + "top_qnames": { + "name": "Top N QNames (All)", + "description": "Top QNames across all DNS queries in stream", + "metrics": [ + "..." + ] + }, + "top_qnames_by_rcode": { + "name": "Top N QNames (Failing RCodes) ", + "description": "Top QNames across failing result codes", + "metrics": [ + "..." + ] } } - filters: { - qname_suffix: { - type: "string", - description: "match the DNS qname sufix given", - regex: "..." +} +``` + +`GET /api/v1/handlers/net/features` + +```json +{ + "version": "1.0", + "config": { + }, + "metrics": { + "cardinality.dst_ips_out": { + "type": "cardinality", + "description": "..." + }, + "cardinality.src_ips_in": { + "type": "cardinality", + "description": "..." + }, + "in": { + "type": "counter", + "description": "..." + }, + "rates.pps_in": { + "type": "rate", + "description": "..." + }, + "top_ASN": { + "type": "top_k", + "description": "..." } }, - metric_groups: { - top_error_qnames: { - description: "top N qnames with error result codes", - metrics: {, - top_refused: { - "type": "top_n", - "description": "..." - }, - top_srvfail: { - "type": "top_n", - "description": "..." - }, - top_nxdomain: { - "type": "top_n", - "description": "..." - }, - } - }, - transactions: { - description: "information on query/reply pairs", - metrics: { - ... - } + "metric_groups": { + "ip_cardinality": { + "name": "IP Address Cardinality", + "description": "Unique IP addresses seen in the stream", + "metrics": [ + "cardinality.dst_ips_out", + "cardinality.src_ips_in" + ] + }, + "top_geo": { + "name": "Top Geo", + "description": "Top Geo IP and ASN in the stream", + "metrics": [ + "top_ASN", + "top_geoLoc" + ] + }, + "top_ips": { + "name": "Top IPs", + "description": "Top IP addresses in the stream", + "metrics": [ + "top_ipv4", + "top_ipv6" + ] } } - } -/api/v1/handlers/net/interface - { - } +} ```