Custom Scripts

This section provides detailed information on how to create and test custom scripts for Flowmon ADS and IDS events. Custom scripts allow you to define your own logic for event processing and export.

The executables can be uploaded by the admin user, in the Settings → System Settings → Custom scripts view. Events are provided as the standard input of the script.

Additional parameters

It is possible to define additional command line parameters for the custom scripts. These parameters are used for handing over the supplementary information. The parameters are optional and must be supported by the script.

The name of the parameter must be nonempty. It may consist of alphanumeric characters, dash or underscore. The parameters are always handed over in the same order. Therefore, it is possible to reference them by a position number. Parameters are passed to the script in the following order:

/script_name.sh PARAM_1 ’VAL_1’ PARAM_2 ’VAL_2’ ... PARAM_n ’VAL_n’

Demo script

The demo script is created after installation or after application of the configuration template. This script is used for sending event reports by email. The script can be generated manually on the Settings → System Settings → Custom scripts page and can also be downloaded. The script supports reporting both ADS and IDS events and is written in Bash. The script is using three parameters for passing the email address, the email body, and the email subject. The parameters are parsed using the standard getopt function. Email reports are sent by Flowmon PHP CLI, the SMTP configuration is obtained from the configuration of the application.

Supported Formats

Custom scripts can process events in two formats:

• Tab-separated format: Fields are separated by tab characters, which is ideal for simple bash scripts. Empty fields are replaced with single spaces.
• JSON format: Events are provided as structured JSON objects, which is ideal for more complex scripts and programming languages like Python.

ADS event

The tab-separated format includes the following fields in this order:

• ID
• event detection time
• timestamp of the first flow
• event type
• event subtype - only if extended options is selected
• MITRE ATT&CK - only if extended options is selected
• type description
• perspective
• priority
• event detail
• port numbers
• protocol
• event source
• captured source name
• event targets
• data feed
• user identity

The JSON format example:

{
   "id": 123456,
   "timestamp": "2025-05-14 15:10:28",
   "firstFlow": "2025-05-14 14:58:55",
   "type": "HIGHTRANSF",
   "typeDesc": "High volume of transferred data",
   "subtype": "General",
   "mitreAttack": [
      {
         "tactic": {
            "code": "TA0008",
            "name": "Lateral Movement",
            "techniques": [
               {
                  "code": "T1570",
                  "name": "Lateral Tool Transfer"
               }
            ]
         },
         "version": 15
      }
   ],
   "perspective": "",
   "severity": "",
   "detail": "Transferred: 213.93 MiB, top peer transfer: 179.49 MiB.",
   "port": "",
   "protocol": "",
   "source": "10.10.10.10",
   "capturedSource": "",
   "targets": "10.20.20.20",
   "netFlowSource": "Default",
   "userIdentity": ""
}

IDS event

Custom scripts can be used for reporting IDS events manually from event detail. IDS events have a different set of attributes than ADS events. The attributes are the same for both the tab-separated format and the JSON format. The attributes are as follows:

• ID
• firstSeen
• lastSeen
• srcIp
• srcPort
• dstIp
• dstPort
• protocol
• signatureId
• signatureName
• logSourceIp
• logSourceInterface
• category
• severity

The JSON format example:

{
   "id": 123456,
   "firstSeen": "2025-05-15 06:45:56",
   "lastSeen": "2025-05-15 06:45:56",
   "srcIp": "10.20.20.20",
   "srcPort": 65432,
   "dstIp": "10.10.10.10",
   "dstPort": 53,
   "protocol": "UDP",
   "signatureId": 2027865,
   "signatureName": "ET INFO Observed DNS Query to .cloud TLD",
   "logSourceIp": "10.1.1.1",
   "logSourceInterface": "idsp_eth2_out",
   "category": "Potentially Bad Traffic",
   "severity": "2"
}

Creating Scripts for ADS and IDS Events

To create a script that processes both ADS and IDS events:

1. Detect the event type:
   • For JSON format, check for specific attributes:
     • ADS events include attributes like type, perspective, and severity.
     • IDS events include attributes like srcIp, dstIp, and signatureName.
   • For tab-separated format, check the number of fields in each row:
     • ADS events have more fields than IDS events.
2. Implement separate logic for processing ADS and IDS events based on the detected type.

Example Bash Script

#!/bin/bash

# Read input
while IFS=
#39;\t' read -r line; do
  # Check the number of fields
  field_count=$(echo "$line" | awk -F'\t' '{print NF}')
  
  if [ "$field_count" -eq 16 ]; then
    echo "Processing ADS event..."
    # Add ADS-specific logic here
  else
    echo "Processing IDS event..."
    # Add IDS-specific logic here
  fi
done

Testing Custom Scripts

You can manually initiate a response for testing purposes:

1. Go to the event detail page in the Flowmon ADS interface.
2. Use the Initiate response option to execute the script with sample data.
3. Verify the script's output and behavior.

Additional Notes

• Ensure your script is optimized for performance to avoid delays in flow data processing.
• Only the admin user can upload and manage custom scripts.