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.
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 restarting Malcolm by running the following command from the Malcolm installation directory:
docker compose exec supervisorctl suricata-live 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.
Suricata uses the YAML format for configuration, and the main suricata.yaml file is generated by Malcolm [dynamically at runtime]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/shared/bin/suricata_config_populate.py).
The contents of the suricata.yaml file can be adjusted via environment variables found in [suricata.env]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/config/suricata.env.example).
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
Some aspects of Malcolm's instance of Zeek's [local site policy]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/zeek/config/local.zeek) can be adjusted via environment variables found in [zeek.env]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/config/zeek.env.example).
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 supervisorctl zeek-live restart live-zeek
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.
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.
- Building your own visualizations and dashboards
- Customizing event severity scoring
- Zeek Intelligence Framework
- Populating the NetBox inventory Manually or through Preloading
- Modifying or Contributing to Malcolm