Skip to content

Installation

Jump to bottom
Darren Spruell edited this page Sep 3, 2020 · 7 revisions

Requirements

ampt-generator currently requires Python 3 and has been tested on Python 3.5.2 and 3.6.2.

Scapy support

A key dependency of ampt-generator is the Scapy packet crafting library. The package previously relied on the scapy3k fork for compatibility with Python 3 and other improvements, but now uses secdev/scapy. Scapy has library dependencies that should be available before proceeding with ampt-generator installation. On many platforms, it is easiest (and recommended) to first install the Scapy package from your target OS to correctly install dependencies properly. The Scapy Python module will then be installed during ampt-generator installation.

Environment

It is recommended to install ampt-generator into a Python virtual environment (virtualenv). In Python 3, the following example works (place the virtual environment where desired, in this example we use ~/venv.d/ampt-generator):

mkdir -p ~/venv.d
python3 -m venv ~/venv.d/ampt-generator

Setup

The preferred installation method is to use Pip. ampt-generator uses Flask and a few other libraries; all of these will be installed automatically.

Install ampt-generator from PyPI:

~/venv.d/ampt-generator/bin/pip install ampt-generator

Or, install from a Git checkout:

git clone https://github.com/nids-io/ampt-generator.git
cd ampt-generator
~/venv.d/ampt-generator/bin/pip install .

This installs ampt-generator into the virtualenv.

Running AMPT Probe Generator

ampt-generator may be run as a privileged user (root on most platforms), which is convenient for launching at startup. However ampt-generator does not require superuser privileges and maybe run as a lower-privileged user as long as some requirements are met:

  • On UNIX-like platforms, the listening port for the API server must be >= 1024. The default port is 5000, so this is probably not an issue.
  • The unprivileged user must be have read/write access to the log file (if one is specified) and to the counter database file.
  • The unprivileged user must be able to read the configuration file.

If ampt-generator is started as the superuser, it will drop privileges for the API server process and run as a unprivileged user/group. This user must be able to access the counter database (the file is created automatically at runtime if not found, and ownership/permissions set appropriately).

Configuration

ampt-generator is preconfigured with reasonable default values for most configuration options. Most important options can be provided on the command line or read from a config file; command line options override configuration file values. A configuration file must be present to provide at a minimum the HMAC key (auth key) for the instance. Additional configuration options may be present to override default values.

A sample configuration file is available in the conf/ directory at the root of the source distribution (conf/ampt-generator.conf.sample). This can be copied into the desired path as ampt-generator.conf and edited to taste. Permissions on the configuration file should be restricted to limit disclosure of the auth key. If running a simple "local" instance on the same system as ampt-manager, very little configuration is required.

A minimal configuration file can be created using the following command as an example (requires Python 3.6+):

$ python3 -c "import secrets; print(\"HMAC_KEY='{}'\".format(secrets.token_hex()))" | sudo tee /etc/ampt-generator.conf

Options that may be useful in configuration files:

  • LISTEN_ADDRESS: Listen address for the API server. The default configuration binds the server to localhost, so this option may be set to 0.0.0.0 and used to allow ampt-generator's API service to be accessed by remote managers.
  • LISTEN_PORT: Listen port for the API server.
  • DB_PATH: Path to the counter database file. This file is required to store and read the last seen counter value to provide replay protection for manager auth.
  • USER: User name to run as when dropping privileges of the API server when run as the superuser.
  • GROUP: Group name to run as when dropping privileges.
  • HMAC_KEY: Shared key used to authenticate messages from ampt-manager instances to the ampt-generator. Like any shared secret, should be strong and kept secret.
  • LOGLEVEL: Logging level. Sets log level of running instance. May be set to any value in debug, info, warning, error or critical. The default value is warning.
  • LOGFILE: Path to desired log file. Enables logging to a specified file on disk. If not specified, no logging occurs. (The program always logs to standard error, depending on the logging level; this setting controls whether similar output is logged to a file).

AMPT manager

The listening address (DNS hostname or IP address) and port and auth key (HMAC key) of the generator should be set in the respective Probe Generator configuration in the AMPT Manager.

Starting server

After the configuration file is in place, the server may be started. ampt-generator is designed to enable one-command startup, with no requirement to deploy the instance behind a standard web server like Apache or Nginx.

$ sudo ampt-generator
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

By default the server binds to the loopback address, which is useful for testing or for use as a local probe generator on an AMPT Manager. When the AMPT Manager is a remote client, AMPT Generator should be configured to listen on an address reachable over the network.

It is sometimes useful to enable debug logging to see detailed operation and handling of inbound requests from the AMPT Manager:

$ sudo ~/venv.d/ampt-generator/bin/ampt-generator -l debug
2017-09-26 00:37:43,365: MainProcess (pid: 33457) - ampt-generator running on Python 3.6.2 using Scapy 3.0.0
2017-09-26 00:37:43,366: MainProcess (pid: 33457) - loaded configuration from file /etc/ampt-generator.conf
2017-09-26 00:37:43,366: MainProcess (pid: 33457) - configured logging at level: DEBUG
2017-09-26 00:37:43,366: MainProcess (pid: 33457) - using counter database path /var/ampt/ampt-generator.db
2017-09-26 00:37:43,366: MainProcess (pid: 33457) - starting ampt-manager API and packet dispatch services...
2017-09-26 00:37:43,371: AppServer (pid: 33463) - dropping privileges...
2017-09-26 00:37:43,371: TaskRunner (pid: 33462) - initialized as user root, group wheel
2017-09-26 00:37:43,371: TaskRunner (pid: 33462) - starting probe packet dispatcher using message queue at tcp://127.0.0.1:9959...
2017-09-26 00:37:43,372: AppServer (pid: 33463) - initialized as user nobody, group nobody
2017-09-26 00:37:43,372: AppServer (pid: 33463) - loading application on address localhost, port 5000...
 * Running on http://localhost:5000/ (Press CTRL+C to quit)
2017-09-26 00:37:50,827: AppServer (pid: 33463) - authenticated dispatch request from 127.0.0.1 with valid HMAC
2017-09-26 00:37:50,827: AppServer (pid: 33463) - stored new value 1506411470.815049 in counter database
2017-09-26 00:37:50,828: AppServer (pid: 33463) - passed dispatch request parameters to message queue
2017-09-26 00:37:50,828: TaskRunner (pid: 33462) - received dispatch workload: {'dest_addr': '10.0.1.1', 'dest_port': 5471, 'src_port': 36023, 'proto': 'tcp'}
2017-09-26 00:37:50,830: TaskRunner (pid: 33462) - generated probe packet with Scapy: IP / TCP 10.0.6.23:36023 > 10.0.1.1:5471 S / Raw
2017-09-26 00:37:50,843: TaskRunner (pid: 33462) - finished sending crafted probe packet

IDS rule output

Use the ampt-rulegen command to output an rule that can be used on NIDS sensors (Suricata, Snort) to alert on healthcheck packets for monitored segments.

$ ampt-rulegen
alert ip any any -> any any (msg:"NIDS HEALTH MONITORING"; content:"|30633536663939622d636636362d343637392d396265322d3362363338346332373538362e4e4944535f4845414c54485f434845434b|"; fast_pattern:only; reference:url,github.com/nids-io/ampt-generator; sid:3900001; rev:1;)

Add this IDS rule to any Snort or Suricata sensors that are inspecting traffic for AMPT Monitored Segments.

Clone this wiki locally