Skip to content

Latest commit

 

History

History
12 lines (8 loc) · 2.85 KB

contributing-pcap.md

File metadata and controls

12 lines (8 loc) · 2.85 KB
Raw

PCAP processors

When a PCAP is uploaded (either through Malcolm's upload web interface or just copied manually into the ./pcap/upload directory), the pcap-monitor container has a script that picks up those PCAP files and publishes to a ZeroMQ topic that can be subscribed to by any other process that wants to analyze that PCAP. In Malcolm (at the time of the [v{{ site.malcolm.version }} release]({{ site.github.repository_url }}/releases/tag/v{{ site.malcolm.version }})), there are three such ZeroMQ topics: the zeek, suricata and arkime containers. These actually share the [same script]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/shared/bin/pcap_processor.py) to run the PCAP through Zeek, Suricata, and Arkime, respectively. For an example to follow, the zeek container is the less complicated of the two. To integrate a new PCAP processing tool into Malcolm (named cooltool for this example) the process would entail:

  1. Define the service as instructed in the Adding a new service section
    • Note how the existing zeek and arkime services use bind mounts to access the local ./pcap directory
  2. Write a script (modelled after [the one]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/shared/bin/pcap_processor.py) zeek, suricata, and arkime use) that subscribes to the PCAP topic port (30441 as defined in [pcap_utils.py]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/shared/bin/pcap_utils.py)) and handles the PCAP files published there, each PCAP file represented by a JSON dictionary with name, tags, size, type and mime keys (search for FILE_INFO_ in [pcap_utils.py]({{ site.github.repository_url }}/blob/{{ site.github.build_revision }}/shared/bin/pcap_utils.py)). This script should be added to and run by the cooltool.Dockerfile-generated container.
  3. Add whatever other logic needed to get cooltool's data into Malcolm, whether by writing it directly info OpenSearch or by sending log files for parsing and enrichment by Logstash (especially see the section on Parsing a new log data source)

While that might be a bit of hand-waving, these general steps take care of the PCAP processing piece: users shouldn't have to really edit any existing code to add a new PCAP processor, only create a new container to subscribe to ZeroMQ topic and handle the PCAPs it receives.

The PCAP_PIPELINE_VERBOSITY environment variables in ./config/upload-common.env can be set to -v, -vv, etc., to increase the verbosity of debug logging from the output of the containers involved in the PCAP processing pipeline.