-
Notifications
You must be signed in to change notification settings - Fork 0
Installation
ampt-manager currently requires Python 3 and has been tested on Python 3.5.2. Support for Python 2.7 is planned for the future.
It is recommended to install ampt-manager into a Python virtual environment
(virtualenv). In Python 3.5, the following example works (place the virtual
environment where desired, in this example we use ~/venv.d/ampt-manager):
mkdir -p ~/venv.d
python3 -m venv ~/venv.d/ampt-manager
The preferred installation method is to use Pip. ampt-manager uses Flask, the peewee ORM, and a number of other libraries; all of these will be installed automatically. To avoid problems installing the Python cryptography library, a current version of pip should be installed within the virtualenv prior to installing ampt-manager. This can be done as follows:
pip install --upgrade pip
Install ampt-manager from PyPI:
~/venv.d/ampt-manager/bin/pip install ampt-manager
Or, install from a Git checkout:
git clone https://github.com/nids-io/ampt-manager.git
cd ampt-manager
~/venv.d/ampt-manager/bin/pip install .
This installs ampt-manager into the virtualenv.
ampt-manager is designed to be run as an instance from a self-contained configuration directory. The application may be run as an unprivileged user and the config directory may be placed anywhere the user has access to write on the filesystem. To install a new configuration instance in the home directory:
ampt-manager init ~/ampt
The command creates a default admin user with unique password and generates a unique self-signed certificate and private key for the new instance. The command returns output resembling the following:
$ ampt-manager init ~/ampt
The setup of a new config instance for AMPT is complete. The specified
configuration directory contains default files for the instance as
well as the SQLite database. Configure `ampt_manager.conf` to your
preference and start the server.
Default admin credentials:
Username: admin
Password: idgCIGn0Tp
A self-signed certificate and private key are also installed. These
can be replaced with a new key and properly signed certificate (or
deleted and the configuration file updated to point to new files, etc.).
The new config directory contains the following files:
ampt_manager.conf
ampt_manager.crt
ampt_manager.db
ampt_manager.key
ampt_manager.log
ampt-manager is designed to enable one-command startup, with no requirement to deploy the instance behind a standard web server like Apache or Nginx. The server supports HTTPS via an embedded Gunicorn web server.
After running the init command, the AMPT manager may be started using the
run command:
$ ampt-manager run -l info ~/ampt/ampt_manager.conf
2020-09-05 00:29:55,782 [INFO] runserver - starting AMPT Manager 0.4.3
2020-09-05 00:29:55,782 [INFO] runserver - configuring server for TLS using PROTOCOL_TLS (OpenSSL 1.1.1g 21 Apr 2020)
2020-09-05 00:29:55,789 [INFO] glogging - Starting gunicorn 20.0.4
2020-09-05 00:29:55,789 [INFO] glogging - Listening at: https://127.0.0.1:8443 (12614)
2020-09-05 00:29:55,789 [INFO] glogging - Using worker: sync
2020-09-05 00:29:55,795 [INFO] glogging - Booting worker with pid: 12617
2020-09-05 00:29:55,890 [INFO] glogging - Booting worker with pid: 12618
2020-09-05 00:29:55,991 [INFO] glogging - Booting worker with pid: 12619
2020-09-05 00:29:56,056 [INFO] glogging - Booting worker with pid: 12620
2020-09-05 00:29:56,134 [INFO] glogging - Booting worker with pid: 12621
The default logging level for ampt-manager is warning, so for more details a log level of info helps.
By default the server binds to the loopback address, which is useful for
testing. When run in production, the bind address may be set in the
configuration file. For convenience, the bind address and listening port may
be also passed as command line arguments. See the output of ampt-manager run -h.
To set up AMPT, configure the necessary components as follows:
- Deploy an ampt-generator instance. The AMPT manager
is configured with a disabled Probe Generator on localhost by default, so
either install and start an ampt-generator on the same host as the manager
and then enable it in the manager, or deploy ampt-generator on a remote host
and add a new Probe Generator for that host in the manager.
On the deployed ampt-generator, run the command
ampt-rulegen. Add the IDS rule it outputs to the active ruleset of configured Suricata or Snort NIDS sensors. - Add at least one Monitored Segment. Adding a segment to monitor requires a small amount of planning and understanding of network topology and IP address space/routing in the target environment. In order to monitor a given network segment/link, the deployed probe generator must be able to send probe packets to a configured destination IP address on a TCP or UDP port such that the probe packets are forwarded across a link that is monitored by one or more sensors.
- Deploy an ampt-monitor instance. The monitor watches event logs for a given sensor and identifies and forwards alerts to the manager. The Event Monitor should ideally be installed on a node that has real-time or near real-time access to the logs for an NIDS sensor that is inspecting traffic on the Monitored Segment.
Assuming that the above configuration is complete, AMPT has at least one active monitored network segment, a listening probe generator, and an event monitor on a functional NIDS sensor. AMPT may now be used to complete the monitoring workflow:
- On a scheduled basis, the AMPT manager determines active Monitored Segments, dispatches probe requests to the AMPT generator, and logs probe dispatch
- The AMPT generator(s) crafts probe packets and sends them to specified destinations
- Functional NIDS sensors with visibility to the monitored segment alert on probe packets triggering the healthcheck rule
- The AMPT monitor(s) catches the healthcheck alerts and send an event to the AMPT manager to log probe receipt
- On a scheduled basis, the AMPT manager verifies events received for active monitored segments and alerts when events are not received within the configured time period
In order to configure the dispatch and verification of probe events for monitored segments, the AMPT offline processing commands should be set up.
Dispatch probe requests for active Monitored Segments:
ampt-manager dispatch -l info ~/ampt/ampt_manager.conf
Example output:
$ ampt-manager dispatch -l info ~/ampt/ampt_manager.conf
2016-11-21 16:08:15,383: [INFO] preparing to dispatch probe requests for 1 monitored segments
2016-11-21 16:08:15,404: [INFO] <ProbeGenerator: 'Local (localhost:5000)'> (id=1) accepted probe submission for <MonitoredSegment: 'Intranet (10.8.42.3/80/tcp)'> (detail: {'proto': 'tcp', 'dest_addr': '10.8.42.3', 'src_port': 12276, 'dest_port': 80})
To schedule periodic probe dispatches, configure a cronjob. Typically this can
be done as the unprivileged user running AMPT. The full path to the
ampt-manager command in the virtual environment should be specified. Below,
probes are dispatched every 30 minutes (on the hour and on the half-hour):
0,30 * * * * $HOME/venv.d/ampt/bin/ampt-manager dispatch ~/ampt/ampt_manager.conf
Visibility on monitored segments is verified when AMPT checks to see if probe events have been received from Event Monitors within a user-specified timeframe. Typically, this timeframe matches the time period at which probe requests are dispatched in cron.
Verify receipt of probe packet events from AMPT monitors within the last 30 minutes:
ampt-manager verify -p 30 -l info ~/ampt/ampt_manager.conf
Example output (successful segment verification):
$ ampt-manager verify -l info ~/ampt/ampt_manager.conf
2016-11-21 16:37:07,435: [INFO] Verifying 1 monitored segment(s) for alerts over previous 30 minutes
2016-11-21 16:37:07,436: [INFO] 1 probe logs received for <MonitoredSegment: 'Intranet (10.8.42.3/80/tcp)'> within previous 30 minute period
When verification of a segment fails, a warning is logged:
$ ampt-manager verify -p 30 ~/ampt/ampt_manager.conf
2016-11-21 16:08:30,036: [WARNING] No probe logs received for <MonitoredSegment: 'Intranet (10.8.42.3/80/tcp)'> within previous 30 minute period
Periodic verifications should be configured as a cronjob. It is useful in many cases to offset the verification cronjob by a few minutes from the dispatch cronjob, to give the event delivery process or workflow at the sensor and AMPT monitor time to pick up the alert and send it to the AMPT manager for logging. Sometimes this process is nearly instantaneous, but in some environments this could carry a delay. Below, verification is scheduled every 30 minutes, but offset 10 minutes after probe dispatches:
10,40 * * * * $HOME/venv.d/ampt/bin/ampt-manager verify -p 30 ~/ampt/ampt_manager.conf
During operation at the default log level (WARNING), dispatch and verification functions that run without failures generate no output. If an error occurs in either of these processes, error messages are output, allowing cron(8) and the application log files to alert the administrator. This, incidentally, is ampt-manager's current built-in alerting; the output warning or error logs from these commands can be emailed to an administrator by the cron daemon. Supported cron implementations allow the MAILTO environment variable to be set to an email recipient that should receive cronjob output.
MAILTO="ids-admin@example.com"
0,30 * * * * $HOME/venv.d/ampt/bin/ampt-manager dispatch ~/ampt/ampt_manager.conf
10,40 * * * * $HOME/venv.d/ampt/bin/ampt-manager verify -p 30 ~/ampt/ampt_manager.conf