Getting Started

Quick Start

SAM can be installed through python's pip package manager as follows:

pip install samapper

From there it can be run immediately via the command:

samapper --local

This starts a webserver on localhost at port 8080. Initially, though, there is no network data to display, so we must begin collecting. tcpdump works well for this and can be piped into sam.

sudo tcpdump -i any -f --immediate-mode -l -n -Q inout -tt | samapper --local --whois --format=tcpdump

sudo is required for tcpdump in order to allow the software to intercept and count network traffic.

After this has been running for a little while you should begin to see your network traffic at http://localhost:8080


SAM can be installed via pip or by cloning the github project. Depending on which you choose, you start up SAM differently.

Via pip:


Or via github:

python -m sam.launcher

There are a number of different options for starting up SAM:

--local A simplified way to run SAM with a temp local database and collector / aggregator subprograms for collecting live data from the local machine.





Webserver: serves the html pages.

Collector: listens to port 514 for network log data.

Aggregator: accepts normalized network data and inserts into the database.

Import: runs an importer with the given log file to insert the log data into the database.

--wsgi Used with webserver and aggregator for deployment.
--port Specify which port to listen on.
--dest Used with import. The data source to import into. Defaults to first data source.
--sub Used with import. The account to import into. Can be left blank to use default account.
--whois Used with --local, enables whois lookup on hosts.
--format Used with --local and import, clarifies what log format to expect.

Most of SAM can be configured through environment variables. A list of config variables and their defaults is available here.

Lastly, some additional options are available on the settings page of the web portal.

Manual Log Importing

Can be done via command line (more efficient) or through the web portal on the settings page. To add a log via command line, use the following options:

--target=import --format=<format> --dest=<destination> <log_file>

Where <format> is the log format, such as paloalto,

and <destination> is the data source to insert into, such as default,

and <log_file> is the path to your log file.

Alternatively, you can upload log files through the settings page in the web portal. Select your datasource and click the upload button. Follow the dialog box instructions to upload.

Live Mode

Live mode requires a few extra steps and technical ability. You need to have a locally running program called the Collector, and route your log files into a socket it opens.

First step, is to create a data source to use for live updates. Once you have your data source, scroll down to the Live Updates section:

Choose your data source to stream into and click Generate to create an access key. This key is used to give permission for your collector to submit log data to the aggregator.

With that in place, the next step is to run a collector locally to do the uploading. The Collector program must be configured by editing default.cfg. Ensure that you have entered the access key you generated earlier, as well as the format of your log files.

When you have the program configured, start up the collector. The collector program must be configured by environment variables. Ensure that you have entered the access key you generated earlier, as well as the format of your log files.

Time to start your programs. Start the webserver:


Start the aggregator:


Start the collector:


With that you're ready to direct the syslog output of your gateway or router to the collector, which listens by default on port 514.


There are three main views into your data

Map View

The map view shows your network visually, broken down by subnets /8 /16 and /24. It is great for an overview, and can be filtered to show specific protocols and ports.

Click and drag to move around and scroll to zoom in and out.

Table View

The table view shows a spreadsheet version of the map view. It allows you to build filters that describe a subset of your data and displays aggregate information about those parts.

Use the filters section up top to apply and remove filters, or the download button to move this into your preferred spreadsheet application.

Metadata View

This view shows you information about a specific host in your network. It lets you know the protocols used, all the incoming and outgoing connections, and how much traffic passes through.

Type the IP address in the search bar at the top of the page


Get in touch! We would be happy to answer any questions you have about SAM, how it can help you, and to find the best solution for your needs.


: GitHub project

Thank you for reading.