Behavioral Evaluation of Application Metrics (BEAM) is a Python library for detecting supply chain compromises by analyzing network traffic.
The fastest way to see BEAM in action:
# Clone the repository
git clone git@github.com:netskopeoss/beam.git
cd beam
# Install with uv (recommended)
uv sync
uv pip install -e .
# Run the interactive demo (one command!)
uv run python -m beam demoThis will:
- Automatically start required Docker services in the background
- Run the supply chain compromise detection demo
- Show you how BEAM detects malicious behavior in network traffic
- Complete in ~30 seconds
What you'll see: A real-world example of the Box cloud storage app infected with malware, and how BEAM's AI detects the hidden malicious communication.
Results from the Demo: Check the data/demo_temp directory for the artifacts containing the results.
- Python 3.12+ and uv (recommended) or pip
- An app for running containers - Docker Desktop or an alternative for running Zeek, TensorFlow, and Ollama
BEAM uses a hybrid architecture: Python runs natively for performance while Docker handles infrastructure services automatically.
# Run detection on a specific file and only use the pre-packaged models
uv run python -m beam -i /path/to/traffic.har
# Run detection on a specific file with custom trained models
uv run python -m beam --use_custom_models -i /path/to/traffic.harBEAM automatically discovers applications in your traffic and trains models for any with sufficient data:
# Train from a specific file (auto-discovers all apps)
uv run python -m beam --train -i /path/to/traffic.har
By default, BEAM will use the local Llama container for mapping.
# Use Google Gemini for mapping
export GEMINI_API_KEY="your_api_key_here"
For detailed instructions, data requirements, troubleshooting, and advanced configuration options, see the complete guide in models/custom_models/README.md.
BEAM generates multiple files and provides the following output:
-
The conclusion made from the provided PCAP or HAR files will be shown in the console with an associated probability of compromise.
-
For additional information, check the directories for each session under
beam/predictionsfor SHAP Waterfall plots. Each session has its own SHAP Waterfall image file, which show what features were used to determine BEAM's conclusion about the session.
We included one sample HAR file in this repo so you can try BEAM immediately without adding any of your own data.
Below is an example of the output generated from our sample HAR file:
In the screenshot above, you can see that the HAR file primarily contained traffic from Chrome and Box. The traffic from Box was compared against BEAM’s models. For the first two observations, the traffic was as expected, however for the last session, BEAM flagged it as “Potential supply chain compromise found”.
BEAM determined that there was a 99% probability of a compromise here because the traffic in the HAR file showed communication from this Box application to an unusual endpoint (xqpt5z.dagmawi.io). It did this by flagging patterns in the traffic that did not match how a typical Box application communicates.
BEAM provides a SHAP Waterfall plot for each session analyzed, as shown above. The plot shows the reasoning behind the prediction via an impact breakdown of the evidence provided by each feature on the model’s output. In this particular case, the plot above shows the following reasons that this session was indicative of a compromise:
- not using the content type ‘application/json’
- not reaching out to Box’s servers
- the time taken for the requests
- the amount of data being received
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.