Skip to content

Configure Enrichment

Optional Step

Mapping interfaces to their names can help in being able to quickly identify them in Splunk (i.e. vmx0 -> LAN). This step can be skipped if enrichment is not required.

The steps to setup enrichment for this add-on utilize Splunk Lookups. For more information on lookups see Splunk Docs: About lookups.

Steps to configure enrichment:

  1. Create a CSV Lookup.
  2. Create a Lookup Definition.
  3. Create an Automatic Lookup
Tip

To get a full list of interfaces being used in OPNsense:

From the OPNsense UI, navigate to Interfaces > Assignments.

Create a CSV Lookup

Method 1 - Use the Lookup Editor

Recommended

The lookup editor may be the easiest way to create and mange lookups in Splunk. You can download and install the Lookup Editor from Splunkbase: Lookup Editor.

Once installed, the lookup editor can be used to create a new CSV lookup.

  1. Open the Lookup Editor in Splunk Web.
  2. Click "Create a New Lookup" > CSV lookup.
  3. Give the lookup a descriptive name (i.e. opn_interfaces.csv).
  4. Choose which App context this lookup will be stored in (i.e. Search & Reporting).
  5. Leave the "User-only" box uncheked. This will give the lookup the global scope permissions it needs.
  6. Create column headers (row 1). These headers will be referenced later.
  7. Populate the remaing rows with the interface name mappings.

    Example
    host interface interface_name
    opnsense-01 em0 LAN
    opnsense-01 em1 WAN
    opnsense-01 vmx1 IOT
    opnsense-01 wg0 WIREGUARD
    opnsense-02 vmx1 LAN
    opnsense-02 vmx2 WAN
  8. After saving, move to Create a Lookup Definition.

Method 2 - Create and Upload a new CSV file

A lookup file can be created outside of Splunk and then uploaded via the web interface.

  1. Use an editor to create a file in CSV format.
  2. Create column headers (row 1). These headers will be referenced later.
  3. Populate the remaing rows with the interface name mappings.

    Example
    opn_interfaces.csv
    host,interface,interface_name
    opnsense-01,em0,LAN
    opnsense-01,em1,WAN
    opnsense-01,vmx1,IOT
    opnsense-01,wg0,WIREGUARD
    opnsense-02,vmx1,LAN
    opnsense-02,vmx2,WAN
    
  4. Be sure to save the file with a .csv extension.

  5. Open Splunk Web.
  6. Navigate to Settings > Lookups > Lookup table files (click "+ Add new")
  7. Select the Destination App (i.e. Search & Reporting).
  8. Upload the file.
  9. Provide the Destination filename. This can be the same name as the one created (i.e. opn_interfaces.csv).
  10. Once saved, Navigate back to Settings > Lookups > Lookup table files, if you are not already there.
  11. Search for the name of the file you just uploaded.
  12. Modify the permissions for the file by clicking "Permissions."
  13. Select "All apps (system)" from the two radio options.
  14. Check "Read" permissions for Everyone. Write permissions can be given as needed (typically set to admin & power).
  15. After saving, move to Create a Lookup Definition.

Create a Lookup Definition

After the CSV lookup has been created, a lookup definition needs to be created.

  1. In Splunk Web, Navigate to Settings > Lookups > Lookup definitions (click "+ Add new").
  2. Choose a destination app, or leave as default.
  3. Give the lookup a name (i.e. opn_interfaces)
  4. Select the previously created CSV lookup from the dropdown.
  5. Click the "Advanced" checkbox.
  6. Click the "Case Sensitive Match" checkbox to disable case sensitive matching.
  7. Once saved, Navigate back to Settings > Lookups > Lookup definitions.
  8. Search for the name of the lookup definition you just created.
  9. Modify the permissions for the file by clicking "Permissions."
  10. Select "All apps (system)" from the two radio options.
  11. Check "Read" permissions for Everyone. Write permissions can be given as needed (typically set to admin & power).
  12. After saving, move on to Create Automatic Lookup

Create an Automatic Lookup

After the Lookup definition has been created, an automatic lookup has to be configured for automatic enrichment.

  1. In Splunk Web, Navigate to Settings > Lookups > Automatic lookups (click "+ Add new").
  2. Choose a destination app, or leave as default.
  3. Give the lookup a name (i.e. opn_interfaces_auto_lookup)
  4. Select the previously created lookup definition from the dropdown.
  5. For the "Apply to" field, select sourcetype and type opnsense:filterlog.
  6. For the input fields, first specify the interface field from the created lookup. Then type dest_int for the second field.

    Example

    field_from_lookup = dest_int

    interface = dest_int
    
  7. For the next input field, set host equal to a blank field. There is no need to rename this field.

    Example

    host =

  8. For the output fields, first specify the interface name field from the created lookup. Then type dest_int_name for the second field.

    Example

    field_from_lookup = dest_int_name

    interface_name = dest_int_name
    
    1. Once saved, Navigate back to Settings > Lookups > Automatic lookups.
    2. Search for the name of the automatic lookup you just created.
    3. Modify the permissions for the file by clicking "Permissions."
    4. Select "All apps (system)" from the two radio options.
    5. Check "Read" permissions for Everyone. Write permissions can be given as needed (typically set to admin & power).
    6. Click Save.