bin/djbdns-logparse.py: use f-strings for regex patterns; add comments.

[djbdns-logparse.git] / bin / djbdns-logparse.py

diff --git a/bin/djbdns-logparse.py b/bin/djbdns-logparse.py
index bfb29135d0fcd6d7a0a769b31f9f4f2f5bd4b02b..838012445c32027f80f1661929b991cbe28cd185 100755 (executable)
--- a/bin/djbdns-logparse.py
+++ b/bin/djbdns-logparse.py
@@ -9,17 +9,41 @@ from time import strftime, gmtime
 from subprocess import Popen, PIPE
 
 
-# common components of line-matching regexes
-timestamp_pat = r'[\d-]+ [\d:\.]+'      # output of tai64nlocal
+## Regular expressions for matching tinydns/dnscache log lines. We
+## compile these once here rather than within the corresponding
+## matching functions, because the latter get executed repeatedly.
+
+# This first pattern is used to match the timestamp format that the
+# tai64nlocal program produces. It appears in both dnscache and
+# tinydns lines, after they've been piped through tai64nlocal, of
+# course.
+timestamp_pat = r'[\d-]+ [\d:\.]+'
+
+# The regex to match dnscache log lines.
+dnscache_log_re = re.compile(fr'({timestamp_pat}) (\w+)(.*)')
+
+# The "hex4" pattern matches a string of four hexadecimal digits. This
+# is used, for example, by tinydns to encode the query type
+# identifier.
 hex4_pat = r'[0-9a-f]{4}'
-ip_pat = r'[0-9a-f]{8,32}'              # IPv4 or IPv6 addresses in hex
 
-# discriminate between dnscache and tinydns log lines
-tinydns_log_re = re.compile(
-    r'(%s) (%s):(%s):(%s) ([\+\-IC/]) (%s) (.*)'
-    % (timestamp_pat, ip_pat, hex4_pat, hex4_pat, hex4_pat))
-dnscache_log_re = re.compile(r'(%s) (\w+)(.*)' % timestamp_pat)
+# The IP pattern matches a string of either 8 or 32 hexadecimal
+# characters, which correspond to IPv4 and IPv6 addresses,
+# respectively, in tinydns logs.
+ip_pat = r'[0-9a-f]{8,32}'
 
+# The regex to match tinydns log lines.
+tinydns_log_re = re.compile(
+    rf'({timestamp_pat}) ({ip_pat}):({hex4_pat}):({hex4_pat}) ([\+\-IC/]) ({hex4_pat}) (.*)'
+)
+
+# A dictionary mapping query type identifiers, in decimal, to their
+# friendly names for tinydns. Reference:
+#
+#   https://en.wikipedia.org/wiki/List_of_DNS_record_types
+#
+# Note that mapping here is non-exhaustive, and that tinydns will
+# log responses for record types that it does not know about.
 query_type = {
       1: "a",
       2: "ns",
@@ -44,12 +68,14 @@ query_type = {
     257: "caa"
 }
 
-# for tinydns only
+# tinydns can drop a query for one of three reasons; this dictionary
+# maps the symbol that gets logged in each case to a human-readable
+# reason.
 query_drop_reason = {
     "-": "no authority",
     "I": "invalid query",
     "C": "invalid class",
-    }
+}
 
 
 def convert_ip(ip : str):
@@ -68,12 +94,10 @@ def convert_ip(ip : str):
 
     """
     if len(ip) == 8:
-        # IPv4, eg. "7f000001" -> "127.0.0.1"
+        # IPv4, eg. "7f000001" -> "7f 00 00 01" -> "127.0.0.1"
         return "%d.%d.%d.%d" % tuple(pack(">L", int(ip, 16)))
     elif len(ip) == 32:
-        # IPv6 is actually simpler -- it's just a string-slicing operation,
-        # eg. "00000000000000000000ffff7f000001" ->
-        # "0000:0000:0000:0000:0000:ffff:7f00:0001"
+        # IPv6 is actually simpler -- it's just a string-slicing operation.
         return ":".join([ip[(4*i) : (4*i+4)] for i in range(8)])
 
 
@@ -178,11 +202,37 @@ def handle_dnscache_log(line, match):
     print(timestamp, event, " ".join(words))
 
 
-def handle_tinydns_log(line, match):
+def handle_tinydns_log(line : str, match: re.Match):
+    """
+    Handle a line that matched the ``tinydns_log_re`` regex.
+
+    Parameters
+    ----------
+
+    line : string
+        The tinydns log line that matched ``tinydns_log_re``.
+
+    match : re.Match
+        The match object that was returned when ``line`` was
+        tested against ``tinydns_log_re``.
+
+    Examples
+    --------
+
+        >>> line = "2022-09-14 21:04:40.206516500 7f000001:9d61:be69 - 0001 www.example.com"
+        >>> match = tinydns_log_re.match(line)
+        >>> handle_tinydns_log(line, match)
+        2022-09-14 21:04:40.206516500 dropped query (no authority) from 127.0.0.1:40289 (id 48745): a www.example.com
+
+    """
     (timestamp, ip, port, id, code, type, name) = match.groups()
     ip = convert_ip(ip)
     port = int(port, 16)
     id = int(id, 16)
+
+    # Convert the "type" field to a human-readable record type name
+    # using the query_type dictionary. If the right name isn't present
+    # in the dictionary, we use the (decimal) type id instead.
     type = int(type, 16)                # "001c" -> 28
     type = query_type.get(type, type)   # 28 -> "aaaa"