This article guides you through the integration process of OPNsense with Lumu for automated response procedures. This is one of our featured Out-of-the-Box Response Integrations.

Requirements

• OPNsense version 21.1 or above.
• An active Lumu Defender subscription

Integration setup - Lumu Portal

The following are the steps that must be completed on the Lumu Portal to properly set up the OPNsense integration.

1. Log into your Lumu account through the Lumu portal.

2. Go to the Integrations drop-down menu (1) on the left side panel, and click on Apps (2). Then, go to the Response tab (3) on the right to filter the available integrations accordingly.

3. Locate the OPNsense integration in the Response tab and click on the Add button (1) to view its details.

4. Familiarize yourself with the integration details provided in the app description, and then click on Activate (1) to continue with the integration.

5. Add a descriptive Name; and under Threat Types, choose the specific threat mappings you want to push to OPNsense. If needed, you can also generate a list of compromised IPs by selecting the checkbox (1). Once you finish this configuration, click on Activate (2) to generate the integration URL.

Please note that you cannot modify the information on this screen. Exercise caution when selecting Threat Types, as changes cannot be made later.

6.Once you create the integration, you will be provided with the integration URLs.

Keep the integration URLs at hand. They will be needed in the following steps.

Configure OPNsense

Having finished the initial integration of OPNsense on the Lumu Portal, you will need to use the provided URLs to configure OPNsense.

Add Lumu’s DNS threat feed to Unbound DNS

Unbound DNS is OPNsense’s standard DNS service. You must reference the Domains Blocklist integration URL in OPNsense by following these steps:

1. Log in to the OPNsense management console.

2. Head to the left navigation menu and expand the Services section (1). Then, expand the Unbound DNS section (2) and click on Blocklist (3).

3. Activate the Unbound DNS advanced mode by clicking on the advanced mode toggle (1) in the top of the form. Then, activate the Blocklist feature by clicking on the Enable checkbox (2).

4. After activating the advanced mode, the URLs of Blocklists field will appear. Copy and paste Lumu’s Domains Blocklist integration URL in that field.

5. When finished, click on the Apply button.

You must add a cron task to update the list periodically. To do so, follow the instructions in the Create cron jobs to update Lumu's lists section.

Add IP alias

To use the IP Addresses integration URL (only available if selected during the setup in the Lumu Portal), you must create an IP alias and reference it in a Firewall rule in your OPNsense admin console. Follow these instructions to add the IP alias:

1. Log in to the OPNsense management console.

2. Head to the left navigation menu and expand the Firewall section (1). Then, click on Aliases (2).

3. Click on the + button (1) button in the Firewall: Aliases window.

4. Fill in your new Alias data by following these guidelines:

1.  Give your alias a distinctive Name (1).
   
2. Set the Type to URL (IPs) (2).
   
3. Paste your Lumu IP Addresses integration URL in the Content field (3).
   
4. Click on the Save button (4) when finished.
   

5. Once you finish the configurations, click on Apply (1) in the Firewall: Aliases window.

After setting up your alias, you must use it in a Firewall rule. Refer to the OPNsense Using Aliases in Firewall Rules document for further details.

You must add a cron task to update the list periodically. To do so, follow the instructions in the Create cron jobs to update Lumu's lists section.

Create cron jobs to update Lumu’s lists

To automatically update Lumu’s lists on a timed interval, you must add cron jobs. To do so, follow these steps in the OPNsense Web console.

1. Head to the left navigation menu and expand the System section (1). Look for the Settings section (2) and click on Cron (3).

2. Click on the + button (1) to create a new cron job.

3. Set up the cron job following these guidelines:

a. Select the Command (1) based on the following:

1. Update Unbound DNSBLs: This will update the Unbound DNS blocklists.
   
2. Update and reload firewall aliases: This will update the Firewall aliases.
   

b. Set the time of execution according to the cron job definition (2), we recommend you schedule your update job to run every 10 minutes (*/10). You can use external resources like crontab guru to calculate your cron signature.

c. Add a Description (3) to identify the task.

d. When finished, click on the Save (4).

4. Click on Apply (1) to finish the cron job configurations.

You must create a cron task for each configured list. This means that if you created both the Domains Blocklist and IP Addresses lists, you will need to configure each list separately.

Validate list synchronization

To validate that everything works as expected, you can check the Unbound DNS logs for the Domains Blocklist URL and the Firewall logs for the IP Addresses URL.

Validate Unbound DNS logs

Log in to the OPNsense management console and follow these steps:

1. Head to the left navigation menu and expand the Services > Unbound DNS section. Then, click on Log File (1).

2. Set the logging level to Informational (1) and type blocklist in the search bar (2). You will obtain the collection process results.

Validate Firewall logs

Log in to the OPNsense management console and follow these steps:

1. Head to the left navigation menu and expand the Firewall > Log Files section. Then, click on the General (1).

2. Set the logging level to Informational (1) and type alias url in the search bar (2). You will obtain the collection process results.