Logo

A powerful, easily deployable network traffic analysis tool suite for network security monitoring

Quick Start

Documentation

Components

Supported Protocols

Configuring

Arkime

Dashboards

Hedgehog Linux

Contribution Guide

Custom Rules, Scripts and Plugins

Much of Malcolm’s behavior can be adjusted through environment variable files. However, some components allow further customization through the use of custom scripts, configuration files, and rules.

Arkime

Rules

Arkime rules “allow you to specify actions to perform when criteria are met with certain fields or state.”

Arkime rules files (with the *.yml or *.yaml extension) may be placed in the ./arkime/rules/ subdirectory in the Malcolm installation directory. These new rules files can applied by restarting Malcolm, or this can be done manually without completely restarting Malcolm by running the following command from the Malcolm installation directory:

./scripts/restart -s arkime arkime-live

Malcolm comes with a few Arkime rules included by default. More sample Arkime rules can be found on the Arkime web site.

On Hedgehog Linux, the Arkime rules directory is /opt/sensor/sensor_ctl/arkime/rules. New rules can be applied by restarting capture processes:

/opt/sensor/sensor_ctl/shutdown && sleep 30 && /opt/sensor/sensor_ctl/supervisor.sh

Lua Plugin

Arkime’s Lua plugin allows sessions to be modified via simple Lua scripts. See the Arkime Lua plugin documentation for more information and example scripts.

Lua files for the Arkime Lua plugin (with the *.lua extension) may be placed in the ./arkime/lua/ subdirectory in the Malcolm installation directory. These new scripts can applied by restarting Malcolm, or this can be done manually without completely restarting Malcolm by running the following command from the Malcolm installation directory:

./scripts/restart -s arkime arkime-live

On Hedgehog Linux, the Arkime Lua directory is /opt/sensor/sensor_ctl/arkime/lua. New scripts can be applied by restarting capture processes:

/opt/sensor/sensor_ctl/shutdown && sleep 30 && /opt/sensor/sensor_ctl/supervisor.sh

Suricata

Rules

In addition to the default Suricata ruleset and Emerging Threads Open ruleset, users may provide custom rules files for use by Suricata in Malcolm.

Suricata rules files (with the *.rules extension) may be placed in the ./suricata/rules/ subdirectory in the Malcolm installation directory. These new rules files will be picked up immediately for subsequent PCAP upload, and for live analysis will be applied by either restarting Malcolm or when the automatic rule update process runs (if automatic rule updates are enabled). This can also be done manually without completely restarting Malcolm by running the following commands from the Malcolm installation directory:

docker compose exec suricata-live supervisorctl restart live-suricata

If the SURICATA_CUSTOM_RULES_ONLY environment variable is set to true, Malcolm will bypass the default Suricata rulesets and use only the user-defined rules.

On Hedgehog Linux, the Suricata custom rules directory is /opt/sensor/sensor_ctl/suricata/rules/, and the SURICATA_CUSTOM_RULES_ONLY environment variable can be found in /opt/sensor/sensor_ctl/control_vars.conf. New rules can be applied by restarting capture processes:

/opt/sensor/sensor_ctl/shutdown && sleep 30 && /opt/sensor/sensor_ctl/supervisor.sh

Configuration

Suricata uses the YAML format for configuration, and the main suricata.yaml file is generated by Malcolm dynamically at runtime.

The contents of the suricata.yaml file can be adjusted via environment variables found in suricata.env.

For more control of the Suricata configuration, Suricata allows other configuration YAML files to be included, allowing the configuration to be broken into multiple files.

Malcolm users may place additional Suricata configuration files (with the .yaml file extension) in the ./suricata/include-configs/ subdirectory in the Malcolm installation directory. When Malcolm creates the suricata.yaml file these additional files will be added at the end in an include: section.

To apply new .yaml files immediately without restarting Malcolm’s Suricata containers, users may run the following commands from the Malcolm installation directory:

docker compose exec suricata /usr/local/bin/docker_entrypoint.sh true

docker compose exec suricata-live /usr/local/bin/docker_entrypoint.sh true

docker compose exec suricata-live supervisorctl restart live-suricata

On Hedgehog Linux, the Suricata custom configuration directory is /opt/sensor/sensor_ctl/suricata/include-configs/. New configuration can be applied by restarting capture processes:

/opt/sensor/sensor_ctl/shutdown && sleep 30 && /opt/sensor/sensor_ctl/supervisor.sh

Zeek

Some aspects of Malcolm’s instance of Zeek’s local site policy can be adjusted via environment variables found in zeek.env.

For more control of Zeek’s behavior, Malcolm’s users may place Zeek files in the ./zeek/custom/ subdirectory in the Malcolm installation directory. The organization of this directory is left entirely up to the user: in other words, users placing files there will also need to create a __load__.zeek file there to tell Zeek what to load from that directory.

These new files should be picked up immediately for subsequent PCAP upload, and for live analysis they will take effect upon restarting Malcolm, or without restarting Malcolm by running the following command from the Malcolm installation directory:

docker compose exec zeek-live supervisorctl restart live-zeek

On Hedgehog Linux, the Zeek custom scripts directory is /opt/sensor/sensor_ctl/zeek/custom/. New configuration can be applied by restarting capture processes:

/opt/sensor/sensor_ctl/shutdown && sleep 30 && /opt/sensor/sensor_ctl/supervisor.sh

YARA

Custom rules files for YARA (with either the *.yara or *.yar file extension) may be placed in the ./yara/rules/ subdirectory in the Malcolm installation directory.

New rules files will take effect by either restarting Malcolm (specifically the file-monitor container) or when the automatic rule update runs (if automatic rule updates are enabled). This can also be done manually without restarting Malcolm by running the following commands from the Malcolm installation directory:

docker compose exec file-monitor /usr/local/bin/yara_rules_setup.sh

docker compose exec file-monitor supervisorctl restart yara

If the EXTRACTED_FILE_YARA_CUSTOM_ONLY environment variable is set to true, Malcolm will bypass the default Yara rulesets (Neo23x0/signature-base, reversinglabs/reversinglabs-yara-rules, and bartblaze/Yara-rules) and use only user-defined rules in ./yara/rules.

On Hedgehog Linux, the Yara custom rules directory is /opt/yara-rules/, and the EXTRACTED_FILE_YARA_CUSTOM_ONLY environment variable can be found in /opt/sensor/sensor_ctl/control_vars.conf. New rules can be applied by restarting the Yara file scanning process:

/opt/sensor/sensor_ctl/restart zeek:yara

NetBox Plugins

NetBox’s functionality can be extended with plugins that can provide “new data models, integrations, and more” (see also the NetBox Wiki).

When Malcolm’s NetBox container starts up, it installs (using pip) any NetBox plugins that have cloned or downloaded and extracted into subdirectories in ./netbox/custom-plugins/ in the Malcolm installation directory. In instances where Malcolm is being run in an offline/airgapped configuration, the plugins’ additional dependencies must also be present under ./netbox/custom-plugins/requirements/, where they will be automatically installed first.

The following warning is quoted from the NetBox documentation:

Plugins extend NetBox by allowing external code to run with the same access and privileges as NetBox itself. Only install plugins from trusted sources. The NetBox maintainers make absolutely no guarantees about the integrity or security of your installation with plugins enabled.

Other Customizations

There are other areas of Malcolm that can be modified and customized to fit users’ needs. Please see these other sections of the documentation for more information.