Document and test for a more detailed format for listing sites

alerts/plugins/ip_source_enrichment.py

@@ -83,8 +83,7 @@ class message(object):
     This plugin will look for IP addresses in any of the values of an
     alert dictionary.  For each IP address found, it will append some
     text to the summary of the alert to provide more information
-    about where the IP originates from if it is recognized.  It will
+    about where the IP originates from if it is recognized.
-    also add a `details.site` value containing the value of `site`.
 
     The expected format of the configuration file,
     `ip_source_enrichment.json.conf`, is as follows:
@@ -109,6 +108,26 @@ class message(object):
     The format string can accept zero to two parameters.  The first
     will be the IP address found and the second will be the
     value of the corresponding 'site'.
+
+    The modified alert will have a `details.sites` field added to it,
+    with the following form:
+
+    ```json
+    {
+      "details": {
+        "sites": [
+          {
+            "ip": "1.2.3.4",
+            "site": "office1"
+          },
+          {
+            "ip": "1a2b:3c4d:123::",
+            "site": "office2"
+          }
+        ]
+      }
+    }
+    ```
     '''
 
     def __init__(self):

tests/alerts/plugins/test_ip_source_enrichment.py

@@ -67,25 +67,29 @@ class TestIPSourceEnrichment(object):
         enriched = enrich(alert_with_ipv4, known_ips)
 
         assert '{0} known'.format(good_ipv4) in enriched['summary']
-        assert enriched['details']['site'] == 'office1'
+        assert len(enriched['details']['sites']) == 1
+        assert enriched['details']['sites'][0]['site'] == 'office1'
 
     def test_ipv6_addrs_enriched(self):
         enriched = enrich(alert_with_ipv6, known_ips)
 
         assert '{0} known'.format(good_ipv6) in enriched['summary']
-        assert enriched['details']['site'] == 'office2'
+        assert len(enriched['details']['sites']) == 1
+        assert enriched['details']['sites'][0]['site'] == 'office2'
 
     def test_ipv4_addrs_in_summary_enriched(self):
         enriched = enrich(alert_with_ipv4_in_summary, known_ips)
 
         assert '{0} known'.format(good_ipv4) in enriched['summary']
-        assert enriched['details']['site'] == 'office1'
+        assert len(enriched['details']['sites']) == 1
+        assert enriched['details']['sites'][0]['site'] == 'office1'
 
     def test_ipv6_addrs_in_summary_enriched(self):
         enriched = enrich(alert_with_ipv6_in_summary, known_ips)
 
         assert '{0} known'.format(good_ipv6) in enriched['summary']
-        assert enriched['details']['site'] == 'office2'
+        assert len(enriched['details']['sites']) == 1
+        assert enriched['details']['sites'][0]['site'] == 'office2'
 
     def test_unrecognized_ipv4_addrs_not_enriched(self):
         enriched = enrich(alert_with_ipv4, known_ips)