How to write Snort alerts as JSON

Structured alert records matter when Snort events leave the sensor for a log shipper, parser, or security information and event management (SIEM) pipeline. The alert_json logger writes each event as a JSON object so downstream tools can read named fields instead of scraping the alert_fast text format.

Snort 3 selects the logger with -A alert_json, while the alert_json Lua table controls file output, field order, rollover limit, and separator. Setting file = true writes /var/log/snort/alert_json.txt when the run command also points -l at /var/log/snort.

Start with the fields the receiver actually uses, then expand the field string when a parser, dashboard, or incident workflow needs more context. The sample run uses a local rule and a PCAP that produce one UDP alert; replace them with traffic and rules that match the alert stream being sent to the pipeline.

1. Confirm that the alert_json logger is available.

   $ snort --help-module alert_json
   alert_json
    
   Help: output event in json format
   ##### snipped #####
   bool alert_json.file = false: output to alert_json.txt instead of stdout
   multi alert_json.fields = 'timestamp pkt_num proto pkt_gen pkt_len dir src_ap dst_ap rule action': selected fields will be output in given order left to right
   ##### snipped #####
   string alert_json.separator = ', ': separate fields with this character sequence

2. Create the Snort log directory.

   $ sudo install -d -m 0755 /var/log/snort

   If the service runs as a dedicated user, set ownership so that user can write /var/log/snort.

3. Open the active Snort Lua configuration.

   $ sudoedit /usr/local/etc/snort/snort.lua

4. Add the alert_json logger settings.

   alert_json =
   {
       file = true,
       fields = 'timestamp pkt_num proto src_ap dst_ap rule action msg'
   }

   Field order controls JSON key order. Common additions include sid, gid, rev, class, priority, service, src_addr, src_port, dst_addr, and dst_port.

5. Test the Snort configuration before running the logger.

   $ sudo snort -c /usr/local/etc/snort/snort.lua -T
   --------------------------------------------------
   o")~   Snort++ 3.12.2.0
   --------------------------------------------------
   Loading /usr/local/etc/snort/snort.lua:
   ##### snipped #####
       alert_json
   ##### snipped #####
   Snort successfully validated the configuration (with 0 warnings).
   o")~   Snort exiting

   Related: How to test Snort configuration

6. Run Snort with the JSON logger against a capture that triggers a rule.

   $ sudo snort -q -c /usr/local/etc/snort/snort.lua \
       -R /usr/local/etc/snort/rules/local.rules \
       -r udp-test.pcap -k none -A alert_json \
       -l /var/log/snort

   Use -A alert_json for the logger selection and -l /var/log/snort for the output directory. The alert_json table in /usr/local/etc/snort/snort.lua controls the file name and fields.

7. Read the JSON alert file.

   $ sudo cat /var/log/snort/alert_json.txt
   { "timestamp" : "06/25-00:26:20.486018", "pkt_num" : 1, "proto" : "UDP", "src_ap" : "127.0.0.1:36965", "dst_ap" : "127.0.0.1:31337", "rule" : "1:1000001:1", "action" : "allow", "msg" : "LOCAL UDP test" }

   Tool: JSON Validator

8. Put the tested logger flags in the service command when alerts should be written continuously.

   ExecStart=/usr/local/bin/snort -q -c /usr/local/etc/snort/snort.lua -i eth0 -A alert_json -l /var/log/snort

   Related: How to create a Snort systemd service