Skip to content

Getting Started

Jump to bottom
Cursor Agent edited this page Oct 5, 2026 · 2 revisions

Getting started

Requirements

  • Linux or Ubuntu WSL.
  • Python 3.11 or newer. CI covers Python 3.11, 3.12, and 3.13.
  • uv and Git.

Dependency installation can require internet access. Watchpost itself runs offline and does not require Nmap, an account, or an API key.

Install from PyPI

To use Watchpost with your own saved scans, install the published package into a virtual environment: python3 -m venv .venv && .venv/bin/python -m pip install 'watchpost-cli==0.0.1'

The PyPI package is named watchpost-cli. The package named watchpost belongs to an unrelated project. The installed command is .venv/bin/watchpost. Only Python is required for this method. The package does not include the synthetic example files, so the demo below uses the repository.

Install from the repository

git clone https://github.com/ejames-dev/watchpost.git
cd watchpost
uv sync --locked --dev --python 3.11

For an existing checkout, enter its root directory and run the sync command. The --dev option also installs the test and lint tools.

Inspect the synthetic baseline

uv run --offline watchpost inspect examples/baseline.xml

The command lists explicit IPv4 addresses and TCP port states in numerical order. It does not expand grouped port counts into individual observations. All bundled addresses and states are fictional.

Compare two snapshots

uv run --offline watchpost compare examples/baseline.xml examples/after.xml \
  --confirm-same-context

Expected finding:

STATE CHANGE 192.0.2.10 3000/tcp: closed -> open

The flag records your confirmation of matching scan context. For real inputs, confirm the location, intended targets, and remaining settings before you use it. The flag does not override failed validation.

Save a report

mkdir -p reports
uv run --offline watchpost compare examples/baseline.xml examples/after.xml \
  --confirm-same-context --output reports/wiki-demo.md

Open reports/wiki-demo.md in a text editor or Markdown viewer. If the file already exists, choose a new filename. There is no force-overwrite option.

Compare the result with the synthetic sample report. The supplied input paths and contents determine the report content, not the output filename.

Verify the installation

uv run --offline python -m unittest discover -s tests -v

Continue with Reading reports. For the full command reference, see the README.

Watchpost

Project

Clone this wiki locally