portmantool

Port scanning and monitoring tool

Components

runner

while true
do
	run.sh <nmap args...> &
	sleep <scan interval>
	wait $!
done

scanalyzer

This program receives scan reports from the runner and imports them into a
database.

The API provides endpoints for retrieving scan results as well as updating the
expected state. A Prometheus /metrics endpoint provides metrics useful for
alerting.

v1 Endpoints

Path (excl. /v1) Method Description
/diff GET Compute difference between current and expected state
/diff/{id1}[/{id2}] GET Compute difference between scans {id1} and {id2}, if it is given, or the expected state, otherwise
/expected GET Get expected state
/expected PATCH Update expected state
/hello * hello
/run[/{id}] POST (NYI) Run scanner {id} or, in case {id} is not given, all scanners immediately
/scans GET Get list of scan timestamps
/scans[/{keep}] DELETE Delete entries that do not contribute to the current state and, optionally, are older than {keep} (UNIX timestamp)
/scan POST Upload a new scan report
/scan/{id} GET Get result of scan at timestamp {id}

Metrics

Name Description
portmantool_last_import (NYI) Timestamp of last successful import
portmantool_ports Number of unique host/protocol/port combinations in database (labels: host, protocol, state)
portmantool_ports_rogue Number of ports with a state different from the expected (labels: host, protocol)
portmantool_imports_failed_total Total number of failed imports since server was running
portmantool_
Labels
  • host (e.g. “10.23.42.127”, “host42.bitsbeats.io”)
  • protocol (e.g. “tcp”, “udp”)
  • state (e.g. “open”, “closed”)

web

  • Show diff between expected and current state, updated every 5 seconds
  • Show expected state, add and update independent of diff
  • Show (list of) scan results, prune obsolete

Planned

  • Compare scan(s) to current state (backend currently compares to expected state)/each other
  • Show “no diff found” if no entries are returned
  • Show date-time of last successful import
  • Filter tables

Backlog

  • Edit expected state
    • Delete (needs implementation in backend)

Database

see db/types.sql, db/schema.sql

License

Copyright 2020-2022 Thomann Bits & Beats GmbH

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

GitHub

View Github