Malcolm v25.03.0

Malcolm v25.03.0 adds authentication via Keycloak and includes a few component version updates.

v25.02.0...v25.03.0

Read Before Upgrading

• As described below, a number of changes were made to environment variables in this release. The Malcolm control script should automatically migrate environment variables between Malcolm versions (e.g., moving environment variables from one .env file to another, removing deprecated/unused environment variables from .env files, etc.) as these actions are specified in config/env-var-actions.yml. However, these actions should be taking when migrating from a previous version of Malcolm to v25.03.0:
  • Before upgrading, while Malcolm is up, execute ./scripts/netbox-backup to backup the NetBox database and save the resulting .gz file(s) in case something goes wrong with the migration of the location of the PostgreSQL database or the environment variables associated with it. Should this happen, ./scripts/netbox-restore could be executed afterwards to restore the contents of the NetBox database.
  • If you have not already upgraded to v25.02.0, read the notes for that release and manually update the redis-related environment variables as described there.
  • Once updating to v25.03.0, but before starting Malcolm, run ./scripts/status to automatically migrate the other environment variables as described above.

Release Notes

• ✨ Features and enhancements
  • Support authentication via Keycloak (#459)
    • In addition to local account management and LDAP authentication, Malcolm can now utilize Keycloak, an identity and access management (IAM) tool, to provide a more robust authentication and authorization experience, including single sign-on (SSO) functionality.
    • Malcolm can connect to an existing Keycloak server or it can use its own embedded Keycloak instance.
    • While this feature has been developed and tested with Keycloak in mind, the lua-resty-openidc library used to implement the OpenID connection functionality may work with other OpenID providers as well. If you find this does work, let us know on the discussions board; if not, please log an issue with details.
    • This feature will pave the way for fine-grained access controls to be implemented in a future Malcolm version.
    • To support this feature, the postgres container has been decoupled from NetBox and now runs independent of that service. This is similar to what was done with the redis container in v25.02.0.
    • To support this feature, the vanilla NGINX web server used internally has been replaced with OpenResty, a version of NGINX extended with Lua.
    • New functionality was added to the authentication setup tool.
    • Refer to the new documentation on this feature for details, including a known limitation when using this authentication method with Hedgehog Linux.
  • Change to ./wipe command behavior
    • Prior to this release, running ./wipe also cleared the contents of the directory of the PostgreSQL database containing the NetBox inventory. PostgreSQL is now used to store both the NetBox inventory and the embedded Keycloak instance data. For this reason, and because it was probably not users' intention to blow away their network inventory with ./wipe, that script no longer deletes this data.
• ✅ Component version updates
  • OpenSearch and OpenSearch Dashboards to v2.19.1
  • Jinja2 to v3.1.6 to fix "Jinja2 vulnerable to sandbox breakout through attr filter selecting format method" vulnerability (CVE-2025-27516)
  • Fluent Bit to v3.2.8
  • Capa to v9.1.0
• 📄 Configuration changes (in environment variables in ./config/) for Malcolm and in control_vars.conf for Hedgehog Linux
  • the following are all to support authentication via Keycloak (#459)
    • renamed NGINX_BASIC_AUTH with NGINX_AUTH_MODE in auth-commmon.env; the new code handling this variable should be backwards-compatible with the previously-accepted values
    • added keycloak.env
    • renamed nginx-postgres to postgres.env and completely overhauled the variables in that file
    • added several new environment variables to nginx.env (see the comments in that file for details)
    • removed NETBOX_POSTGRES_DISABLED from in netbox-common.env

Malcolm is a powerful, easily deployable network 🖧 traffic analysis tool suite for network security monitoring 🕵🏻‍♀️.

Malcolm operates as a cluster of containers 📦, isolated sandboxes which each serve a dedicated function of the system. This makes Malcolm deployable with frameworks like Docker 🐋, Podman 🦭, and Kubernetes ⎈. Check out the Quick Start guide for examples on how to get up and running.

Alternatively, dedicated official ISO installer images 💿 for Malcolm and Hedgehog Linux 🦔 can be downloaded from Malcolm's releases page on GitHub. Due to limits on individual files in GitHub releases, these ISO files have been split 🪓 into 2GB chunks and can be reassembled with scripts provided for both Bash 🐧 (release_cleaver.sh) and PowerShell 🪟 (release_cleaver.ps1). See Downloading Malcolm - Installer ISOs for instructions.

As always, join us on the Malcolm discussions board 💬 to engage with the community, or pop some corn 🍿 and watch a video 📼.