OPNsense Update Notify

An update notification script for OPNsense.

About

This is a script that makes an API connection to OPNsense and checks if there is any pending updates and if there are, it sends a message with details.

Idea is based on the script from Bryce Torcello, forked from https://github.com/losuler/opnsense-update-notify.

This script has been tested on running on OPNsense 22.1.X code base and greater from the firewall itself.

TODO

• TBD

Setup

OPNsense API access

It's recommended to create a user with access restricted to the API endpoints required to retrieve update information needed by the script. The steps to do this are as follows:

1. Add a new group under System>Access>Groups. All that is required here is Group name.

2. After creating the group, click on Edit for the newly created group. Under Assigned Privileges click Edit.

3. Scroll down to or search for System: Firmware. Tick to add the priviledges to the group (click the i to view the endpoints).

4. Add a new user under System>Access>Users.

   1. Provide a Username.

   2. Under Password tick Generate a scrambled password to prevent local database logins for this user..

   3. Then under Group Memberships click the previously created group and click Add groups (->).

5. After creating the new user, click on Edit. Under API keys click Create API key (+). Your browser will prompt you to download or open a text file. This file will have the api_key and api_secret values used in the config (see the Config below).

OPNsense scheduling

It is recommended to run this script shortly after running one of OPNsense's firmware checks via a scheduled job. You can perform this task using the following steps:

1. Login to the firewall as root/superuser via the WEBUI
2. Under System>Settings>Cron you can add a new cronjob for firmware checks.
3. Setup the new cronjob based on your preference for frequency and then for the Command make sure you select the Firmware update check in the drop down.
4. Save this job and your firewall will now on a regular basis go out and determine if updates are available.

OPNsense installation

Login via SSH to your OPNsense firewall and clone the code base into the /root directory using git clone https://github.com/pyrodex/opnsense-update-notify.git into any directory you desire. Make sure you create your configuraiton file as referenced below and feel free to test the process using /root/opnsense-update-notify/main.py -c /root/opnsense-update-notify/config.ini -v and ensure access works.

NOTE: If you decide to change the path in which you've downloaded the code to besides /root/opnsense-update-notify you will need to edit the dist/actions_firmware_notification.conf file to reflect the new path to the python script and also the configuration file before proceeding to the next steps.

Now that the code is downloaded and tested with a working confgiuration the actions.d configuraiton file needs to be installed for scheduling in OPNsense to run the script via cron. To do this copy the dist/actions_firmware_notification.conf file from the directory the code was downloaded and place this file in the /usr/local/opnsense/service/conf/actions.d directory. Once the file has been copied you need to issue the serivce configd restart command for OPNsense to see the new file and allow for it to be referenced in the next step below.

Script scheduling

Now that OPNsense is configured to check for regular firmware updates the script needs to be configured as well to run shortly after the firmware check cronjob previously setup. I suggest running the update notification script maybe 30 minutes AFTER the last firmware cronjob to ensure all things are done and ready to report.

You can setup the notification script to run via cron using the following steps:

1. Login to the firewall as root/superuser via the WEBUI
2. Under System>Settings>Cron you can add a new cronjob for firmware notifications.
3. Setup the new cronjob based on your preference for frequency, preferably 30 minutes after the update check, and then for the Command make sure you select the Firmware update notification in the drop down.
4. Save this job and your firewall will now on notify if updates are available.

Now all should be setup for the next time an update/upgrade is released!

Config

The configuration file config.ini has three main sections (see config.ini.example). The already filled in values in the example config are the defaults.

OPNsense

[opnsense]
url:
self_signed: true
api_key:
api_secret:

REQUIRED url is the full url (https:///api/core/firmware/status) to the OPNsense web api interface.

REQUIRED self_signed refers to whether the TLS certificate is self signed or not, it maybe be either true or false. Since OPNsense creates it's own self signed cert by default, the default for this value is true.

REQUIRED api_key and api_secret refers to the values provided in step 5 of the Setup section above.

Emitters

[emitter] 
emitter: [pushover or telegram]

REQUIRED The emitter refers to one of the message services listed in the subsections below (only Telegram or Pushover for now, request more via issues). To use more than one supported emitter just create a new line after emitter: and indent for each desired emitter to be used.

Pushover

[pushover]
app_token:
user_token: 

app_token is the custom application created for Pushover.

user_token is the user token for your Pushover account.

Telegram

[telegram]
token:
chatid:

token is the token for the Telegram bot, which is provided by creating a bot by following the steps provided in the Telegram bot API documentation.

chatid is the unique identifier for the target chat. It can be obtained by messaging the bot and executing the following command (replace $BOT_TOKEN). The ID may be found at "chat": {"id": 12345678},:

curl https://api.telegram.org/bot$BOT_TOKEN/getUpdates | python -m json.tool