pmop

Pmop (Perimeter Monitoring On-Prem) is a perimeter network monitoring tool designed to be deployed on-prem rather than a VPS/cloud provider. Pmop combines Gluetun for VPN connectivity, Argus-Scan for scanning & vulnerability assessment, and Caddy for displaying reports on a simple, local webserver.

Overview

Pmop uses Docker Compose to bundle the following services into a single stack:

• Gluetun
  • Purpose: Simulates a connection to the target server(s) from the Internet
• Argus-Scan
  • Purpose: Performs network scans using Nmap, Nuclei, and Nikto, and generates reports
• Ofelia
  • Purpose: Triggers scans & VPN rotation jobs according to schedule
• Caddy
  • Purpose: Webserver for reviewing scan reports

Features

• Perimeter network scanning hosted on-premises (i.e. from within the network you are testing). No remote server, VPS, or cloud provider required.
• Automatic scan scheduling for one or more targets
  • Identifies open ports and services via Nmap
  • Inspects HTTP security headers
  • Validates SSL/TLS certificates (on HTTPS servers)
  • Vulnerability scanning via Nuclei and Nikto
  • Generates HTML reports summarizing scan results
• Easily access scan reports via local webserver
  • Simple dashboard provides an overview of full scan history
  • Search for specific reports by target name or date

Project Structure

.
├── config/
│   └── Caddyfile             # Configuration for Caddy webserver
├── reports/                  # Generated reports are stored in YYYY/MM/DD subdirectories
│   └── index.html            # Scan reports dashboard
├── scripts/
│   ├── generate-manifest.py  # Generates JSON manifest used by scan reports dashboard
│   ├── scan-targets.sh       # Wrapper script for scanning specified targets and organizing reports
│   └── vpn-rotate.sh         # Rotates VPN connection
├── .env.example              # Example .env file used by Docker stack
├── compose.yml               # Docker Compose file
└── targets.txt.example       # Example targets.txt file specifying targets to be scanned

Installation

Prerequisites:

• Docker Compose
  • VM or bare metal installation is recommended
  • LXC installation is possible but requires passthrough of the host's /dev/net/tun device to the container
• VPN provider supported by Gluetun

Step 0: Create Directory for Pmop

You may choose any directory you like, but we recommend /opt/pmop.

mkdir /opt/pmop
cd /opt/pmop

Step 1: Clone GitHub Repository

git clone https://github.com/jark-dev/pmop.git

Step 2: Prepare Environment Variables

Copy .env.example to .env.

cp .env.example .env

Update the timezone code to reflect your setup using this format.

.env

TZ=America/New_York
...

Update the Gluetun environment variables to reflect your setup. The example provided is for Proton VPN. Refer to the Gluetun Docs for examples using other VPN providers.

.env

...
VPN_SERVICE_PROVIDER=protonvpn
VPN_TYPE=wireguard
WIREGUARD_PRIVATE_KEY=your_private_key_here
SERVER_COUNTRIES="United States"
...

Note that if using ProtonVPN, valid login credentials are required to trigger the server list update (see Gluetun Docs for more info). While server list updates are not strictly required, it is strongly recommended to avoid issues with Pmop's VPN rotation feature during long-term use. If using another provider, set the UPDATER_PROTONVPN_EMAIL and UPDATER_PROTONVPN_PASSWORD values to empty strings. Docker Compose will automatically remove the environment variables.

.env

...
UPDATER_PROTONVPN_EMAIL=your_email_here       # set to "" if not using proton
UPDATER_PROTONVPN_PASSWORD=your_password_here # set to "" if not using proton
...

The VPN rotation feature uses Gluetun's HTTP control server to cycle the VPN connection. While technically not required since control server access is isolated to the Gluetun container and not exposed over the Docker network, Pmop uses API key authentication for additional security. This must be pre-generated using Gluetun's genkey command.

docker run --rm qmcgaw/gluetun genkey # creates temporary gluetun container to generate API key

Add the generated API key to .env.

.env

...
GLUETUN_API_KEY="your_api_key_here"

Step 3: Specify Scanning Targets

Copy targets.txt.example to targets.txt.

cp targets.txt.example targets.txt

Replace the placeholders with your desired scanning targets. Valid targets include IP addresses and fully qualified domain names (FQDN) that are accessible via the internet. Each IP/FQDN may be optionally prefixed with the protocol that it serves (e.g. https://<IP_or_FQDN>).

Important

Only scan targets that you own or have explicit permission to scan. Unauthorized scans may violate cybersecurity laws. Be smart; don't break the law!

Each target must be on its own line. Pmop does not automatically detect subdomains, so list all subdomains that you want to scan. There is no limit to the number of targets you can specify, but each additional target will increase scan times linearly since Pmop scans all targets in series. Additionally, scanning multiple targets all operating on the same endpoint may trigger your network security policies (e.g. intrusion detection/prevention systems or web application firewalls) leading to incomplete scan results. This means your perimeter security is working as intended but is probably not the result you are hoping for.

Step 4: Adjust Scanning Schedule

Pmop performs two types of scans:

• Basic scan (port, HTTP security headers, and SSL/TLS checks)
• Full scan (Basic scan + Nuclei and Nikto)

By default, Pmop is configured to perform weekly full scans every Wednesday at 3am and daily basic scans every day but Wednesday at 3am. Additionally, the VPN connection is rotated daily at midnight. This schedule can be modified by configuring the Ofelia labels: entries ending in .schedule.

Ofelia accepts Go cron expressions, which can be specified as cron expressions (similar to Linux but with the addition of a leading seconds field) or as intervals (e.g. @every 6h).

compose.yml

services:
  ... # Other containers
  ofelia:
    ... # Other Ofelia configuration settings
    labels:
      # Daily Basic Scan
      ofelia.job-exec.daily-basic-scan.schedule: "0 0 3 * * 0-2,4-6" # basic scan every day at 3am except Wednesdays
      ofelia.job-exec.daily-basic-scan.container: "argus-scan"
      ofelia.job-exec.daily-basic-scan.command: "/bin/bash -c '/app/scan-targets.sh'"
      # Weekly Full Scan
      ofelia.job-exec.weekly-full-scan.schedule: "0 0 3 * * 3" # full scan every Wednesday at 3am
      ofelia.job-exec.weekly-full-scan.container: "argus-scan"
      ofelia.job-exec.weekly-full-scan.command: "/bin/bash -c '/app/scan-targets.sh --full'"
      # Daily VPN Rotation
      ofelia.job-exec.daily-vpn-rotation.schedule: "0 0 0 * * *" # rotate VPN server every day at midnight
      ofelia.job-exec.daily-vpn-rotation.container: "gluetun"
      ofelia.job-exec.daily-vpn-rotation.command: "/bin/sh -c '/app/vpn-rotate.sh'"
  ... # Other containers

Step 5: Start Pmop

Start Pmop using Docker Compose.

docker compose up -d

Usage

Pmop runs in the background and automatically perform scans per the configured schedule. Manual scans can be triggered using the following commands:

docker exec argus-scan /bin/bash -c '/app/scan-targets.sh'        # manual basic scan
docker exec argus-scan /bin/bash -c '/app/scan-targets.sh --full' # manual full scan

Scan reports can be accessed via the webserver on port 8080 of the host running Pmop. Scan reports can also be accessed on the host in the subdirectories of ./reports organized by scan date.

http://<pmop_IP_or_FQDN>:8080

Credits

• Gluetun
• Argus-Scan
• Ofelia
• Caddy (the Caddy name is a registered trademark of Stack Holdings GmbH)