Requirements

1. A MikroTik RouterOS firmware administrator user.
2. An active Lumu Defender Subscription or a Lumu MSP account
   
3. A Docker-enabled host with Internet visibility over Lumu and the MikroTik RouterOS Firewall

Create encryption keys

You can use an existing public key to configure the integration. Make sure you have access to the matching private key. Both are required to successfully complete the configuration process. If you already have a key with its corresponding private key, you can skip forward to the Preliminary Setup - Configure MikroTik RouterOS section.

Install OpenSSL

Most Unix-based systems already have openssl installed. If this is your case, you can jump forward to the Generate the encryption keys section.

Windows systems

If you already have OpenSSL installed in your Windows system, you can skip forward to the Generate the encryption keys section.

1. Open a Command Prompt with Administrator privileges. To do so, open your Start menu, and search for “cmd”. The Command Prompt app will appear. Choose Run as administrator from the panel on the right.

2. Once in the Command Prompt, run the following command and follow the on-screen instructions:

winget install -e --id ShiningLight.OpenSSL.Light

3. Open your system settings by opening your Start menu and search for System Settings. The View Advanced System Settings app will appear. Click on it.

4. A window with five tabs will appear. The Advanced tab should be currently active. If not, click on it. Then, once you’re on the Advanced tab, click on the Environment Variables button found on the lower right corner.

5. A window will appear with two fields. What you need for the following step is found in the field located on the lower half, System Variables. This field has two columns, Variable and Value. Using the Variable column, locate the Path variable and double click on it. The Edit environment variable window will appear

6. In the Edit Environment Variable window that just opened, click on the New button to add a new variable record. In the text field that requests your input, copy and paste the following value 

%PROGRAMFILES%\OpenSSL-Win64\bin

Finish by clicking the OK buttons until you reach the Settings window again.

7. To test the installation, open a new Command Prompt window and run the openssl command. You must get the following:

Unix-based systems

Generate the encryption keys

1. PRIVATE_KEY  is the name of the .pem file where the private key will be stored.

1. KEY_LENGTH is the length of the generated key. The recommended value is minimum 2048

1. PRIVATE_KEY is the name of the .pem file where the private key was stored. It is the same name as in the previous step.

1. PUBLIC_KEY is the name of the .pem file where the public key will be stored.

Store the keys in a safe place. Both keys are required to configure the integration and for its proper operation.

The .pem files can be opened in a text editor to access the key stored within.

Preliminary Setup - Configure MikroTik RouterOS

In order to set up the integration, you will need to prepare MikroTik through the RouterOS interface to communicate with the Lumu integration. To do this, you will need the following:

1. A RouterOS Firewall user with the write, read, rest-api, and api permissions. 

1. HTTPS Service enabled to push IOCs to the firewall. If you’re familiar with RouterOS, feel free to consult MikroTik’s documentation on the subject.

1. SSL enabled with its corresponding certification. If you’re familiar with RouterOS, feel free to consult MikroTik’s documentation on the subject.
   

To do so, you will need to create a custom User Group with the corresponding permissions, and then a User that will inherit these permissions. You will find how to do so in this document.

Creating a Group for the Lumu integration

1. Login into MikroTik Firewall console either via Web or Winbox.

2. On the left menu, unfold the System menu, and click on Users. Once in the Users window, click on the Groups tab, and then on the Add New button.

3. In the form that opens, make sure you do the following:

1. In the Comment(1) field, you can enter a descriptive note about the group you’re creating. This step is optional.
2. In the Name(2) field, enter a meaningful name. For this example, LumuGroup will be used.
3. Under Policies(3), tick the following checkboxes:

1. write
2. read
3. api
4. rest-api
   

Once done, click on Apply and Ok.

1. On the left menu, unfold the System menu, and click on Users. Once in the Users window, click on the Users tab and then on the Add New button.

2. In the following dialog, do the following:

1. In the Name(1) field, enter a descriptive name for this user.
2. In the Group(2) drop-down menu, select the Group you created in the Creating a Group for the Integration section.
3. In the Password field, enter a password for this user. Once done, you will need to write it again in the Confirm Password field.
4. Once done, click on Apply, and then on OK.
   

3. Now, you need to add the User you just created to the Group created earlier. To do so, return to the System -> Users menu. If you’ve done the steps correctly, you will find the user you just created listed here.

Enable SSL

We encourage you to manage your MikroTik device through SSL services. If you already are doing so, you can skip this step.

1. Head to the left side menu, unfold the IP menu, and click on Services. Here, you will see a list with all the services currently enabled. Double click on www-ssl.

2. The following dialog will open. On the Certificate drop-down menu, select your certificate. Then, click Apply and OK.

To activate this IP service, a Certificate must already exist. This Certificate can be self-signed, or by internal/public CA. Read MikroTik’s documentation to learn more.

Only change values in this dialog if required. We strongly recommend using the default values.

Integration Setup - Lumu Portal

This section of the article describes the steps that must be completed on the Lumu Portal to properly set up the MikroTIk RouterOS Firewall Integration. To start, log into your Lumu account through the Lumu Portal. 

Integrations are also available for Lumu MSP accounts. To access them, log into the Lumu MSP Portal.

1. In the Lumu Portal, head to the panel on the left and open the Integrations drop-down menu. Then, click on Apps. Click on the Response tab on the right to filter the available integrations accordingly.

2. Locate the MikroTik RouterOS integration. The list is organized in alphabetical order from A to Z. Click on the Add button.

3.  Familiarize yourself with the integration details in the app description and click the Activate button to activate the integration.

4. Provide a meaningful Name. Under Threat Types, choose the specific threat mappings you want to push MikroTik RouterOS Firewall. Select the option Include IP Indicators to include IP addresses in the information sent to your feed list. When done, click on the orange Next button.

Bear in mind that:

1. If you leave the Include IP Indicators option unselected, you won’t be able to change it later. You will need to remove the integration and repeat all the steps again.
   
2. Please note that you cannot modify the information on this screen. Exercise caution when selecting Threat Types, as changes cannot be made later.

5. In the next window you will need to enter the Public Key generated in Step 2 of the Generate the encryption keys section. You can do so in two different ways:

1. You can copy and paste the contents of the .pem file you generated by opening the file in a text editor and placing them in the text field that awaits your input.
2. You can upload it directly. To do so, click on the Upload from your device button under the text field. Head to the location where you stored the .pem file to do so.

This will be used by Lumu to safely store the secrets related to the integration. Click the orange Next button to continue.

This public key must match the private key you will use in later steps of the configuration process.

6. In the following dialog, fill in the information to connect to your MikroTik RouterOS Firewall as follows:

1. Username(1): This is the name of the User you created in the Creating a User for the Integration section. This user will be used by the integration to manage the IOCs in your Firewall.
2. Password(2): This is the password for the user above.
3. Hostname or IP(3): the IP address or the FQDN of the firewall.
4. API Port: Only input a port here if you changed the default port in Step 2 of the Enable SSL section. Otherwise, leave it empty.
5. List Name: Enter a descriptive name for this list. The integration will push the IOCs to this list, which you can then find in RouterOS.

Once you’re done, click on the orange Activate button.

7. The integration is now created and active. Now, the Lumu Portal will display the details of the created integration:

The Forwarding Rules - Networks > DYNAMICS > Custom External Object list in your MikroTik RouterOS Firewall will be updated with confirmed compromises detected since the integration is activated and the integration component is deployed and operative.

Deploy and configure the integration component

Now, it is time to deploy and configure the MikroTik Integration component. You can find detailed instructions on how to deploy it in our Dockerhub repository.

Final Steps - Validate the Integration on RouterOS

You can validate that the integration is functioning properly in RouterOS by following these instructions.

1. Head to the IP(1) -> Firewall(2) > Address List (3) in your MikroTik Firewall. You will find IOCs detected by the integration listed with the List Name you chose in Step 6e of the Integration Setup - Lumu Portal section.