watchpost-cli 0.0.1__tar.gz

watchpost_cli-0.0.1/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.0.1
+
+Initial version for local-first review of saved Nmap XML.
+Delivers the scope of the [v0.1 project brief](docs/brief-v0.1.md).
+See [GitHub Releases](https://github.com/ejames-dev/watchpost/releases) for publication dates and assets.
+This changelog entry alone does not establish tag or registry publication.
+
+### Included
+
+- Inspect explicit IPv4/TCP observations in one saved scan.
+- Compare completed TCP connect or SYN scans with matching Nmap versions and declared port coverage.
+- Require human confirmation of scan location, intended targets, and remaining settings.
+- Preserve missing observations as `not observed`, never assumed closed.
+- Generate deterministic Markdown reports with evidence, limitations, suggested checks, and blank review fields.
+- Protect existing report files and notes with non-replacing output.
+- Reject unsafe XML, unsupported inputs, incompatible scans, and reported host timeouts.
+- Provide three synthetic walkthroughs and a [user wiki](https://github.com/ejames-dev/watchpost/wiki).
+- Distribute Watchpost under the MIT license.
+- Use `watchpost-cli` as the distribution name, retaining the `watchpost` command and module.
+- Provide a manual, environment-approved Trusted Publishing workflow for TestPyPI and PyPI.
+
+### Boundaries
+
+Python 3.11+ on Linux or Ubuntu WSL. CI covers Python 3.11, 3.12, and 3.13.
+Inputs are limited to 10 MiB per snapshot. Report output requires a trusted directory with hard-link support.
+Watchpost does not scan, upload data, or make runtime network calls.
+It does not infer device/application identity or declare a network secure or compromised.
+
+No live scanning, scheduling, dashboard, packet capture, UDP/IPv6 support, AI verdicts, or automatic remediation.
+
+### Verification
+
+See [the release-readiness checklist](docs/release-v0.0.1.md).
+The package version alone does not prove publication.
+Published releases, when available, appear on [GitHub Releases](https://github.com/ejames-dev/watchpost/releases).

watchpost_cli-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Evan Newman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

watchpost_cli-0.0.1/MANIFEST.in

@@ -0,0 +1,13 @@
+include LICENSE
+include CHANGELOG.md
+include uv.lock
+include examples/baseline.xml
+include examples/after.xml
+include examples/incomplete.xml
+include examples/report.md
+include docs/brief-v0.1.md
+include docs/compare-milestone.md
+include docs/reporting-milestone.md
+include docs/scenarios.md
+include docs/release-v0.0.1.md
+include docs/publishing.md

watchpost_cli-0.0.1/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: watchpost-cli
+Version: 0.0.1
+Summary: Local-first, evidence-backed reviews of changes between saved Nmap scans.
+License-Expression: MIT
+Project-URL: Repository, https://github.com/ejames-dev/watchpost
+Project-URL: Documentation, https://github.com/ejames-dev/watchpost/wiki
+Project-URL: Issues, https://github.com/ejames-dev/watchpost/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: defusedxml<0.8,>=0.7.1
+Dynamic: license-file
+
+# Watchpost
+
+Local-first, evidence-backed reviews of changes between saved Nmap scans.
+
+**Status: inspection, comparison, Markdown reporting, and synthetic walkthroughs implemented.**
+Two saved XML files can produce a change-review report. The [three walkthroughs](docs/scenarios.md)
+cover expected deployment, unintended backend exposure, and an incomplete scan.
+[Published releases](https://github.com/ejames-dev/watchpost/releases) are listed on GitHub.
+A source checkout can contain unreleased changes.
+See the [release notes](CHANGELOG.md) and [release-readiness checklist](docs/release-v0.0.1.md).
+
+**[User wiki](https://github.com/ejames-dev/watchpost/wiki)** — setup, report interpretation,
+scenarios, troubleshooting, and safety.
+
+## Package name
+
+The distribution name for PyPI and TestPyPI is **`watchpost-cli`**.
+The command and Python module remain `watchpost`. The GitHub repository remains `ejames-dev/watchpost`.
+The registry package named `watchpost` belongs to an unrelated project. Do not install it for this tool.
+Until registry publication is confirmed, use the source-checkout instructions below.
+See [publishing setup](docs/publishing.md) for the maintainer workflow.
+
+## Scope
+
+Watchpost is for students and home-lab operators working on authorized networks.
+Inspect a saved Nmap XML file or compare two snapshots of explicit IPv4/TCP observations.
+Watchpost does not launch Nmap, discover devices, or make network requests.
+
+The approved target is in [the v0.1 project brief](docs/brief-v0.1.md).
+
+## Try the synthetic demo
+
+With Python 3.11+ and [uv](https://docs.astral.sh/uv/) installed:
+
+```bash
+git clone https://github.com/ejames-dev/watchpost.git
+cd watchpost
+uv sync --locked --dev --python 3.11
+uv run --offline watchpost inspect examples/baseline.xml
+```
+
+```text
+IPv4/TCP observations (not a security verdict)
+192.0.2.10
+  22/tcp  open
+  80/tcp  closed
+  443/tcp  open
+  3000/tcp  closed
+192.0.2.20
+  22/tcp  open
+Only explicit port observations are listed; missing ports are not classified.
+```
+
+Nmap is not required. These addresses and states are fictional.
+For an existing checkout, run the final two commands from its root directory.
+
+## Compare two snapshots
+
+```bash
+uv run --offline watchpost compare examples/baseline.xml examples/after.xml \
+  --confirm-same-context
+```
+
+The synthetic second scan is one minute later. Its only explicit state change is:
+
+```text
+STATE CHANGE 192.0.2.10 3000/tcp: closed -> open
+```
+
+The output includes both source paths, UTC scan windows, Nmap version, scan method,
+declared port count, differences, and limitations. Without `--output`, the command prints
+only to the terminal.
+
+**Before using real inputs, confirm the same scan location, intended targets, and remaining
+Nmap settings.** The flag records your confirmation. It does not let Watchpost verify the
+network location, reconstruct the full command line, or override failed metadata checks.
+Do not use it to force a comparison you know is incompatible.
+
+Comparison currently requires:
+
+- One TCP connect or SYN scan per snapshot, with the same method and Nmap version.
+- Identical declared TCP port coverage. Equivalent lists and ranges are normalized.
+- A declared port count that matches that coverage, with all explicit ports inside it.
+- Successful scan completion and valid start/end timestamps.
+- Earlier and later scan windows that do not overlap. Equal windows with identical supported
+  observations are allowed, so comparing a snapshot with itself produces no observed changes.
+
+| Evidence | Output |
+|---|---|
+| Explicit states differ | `STATE CHANGE ... closed -> open` |
+| A port has no earlier explicit record | `PORT OBSERVATION ... not observed -> open` |
+| A port has no later explicit record | `PORT OBSERVATION ... open -> not observed` |
+| An address appears in only one snapshot | `ADDRESS OBSERVATION`, not a device addition/removal claim |
+| Supported explicit observations match | `No observed changes in explicit IPv4/TCP records.` |
+
+A newly observed port is not proof that a service just started. A missing port is not proof of
+closure. Grouped records and uncertain states do not become guessed open/closed results.
+See the [comparison milestone](docs/compare-milestone.md) for boundaries and verification.
+
+## Save a Markdown report
+
+Create the output directory, then generate a report:
+
+```bash
+mkdir -p reports
+uv run --offline watchpost compare examples/baseline.xml examples/after.xml \
+  --confirm-same-context --output reports/review.md
+```
+
+Open `reports/review.md` in a text editor or Markdown viewer.
+See [the synthetic sample report](examples/report.md) for the expected result.
+
+Each report includes:
+
+- Source paths, UTC scan windows, scan metadata, and user-confirmed assumptions.
+- Separate counts for changed states, newly observed records, and records not observed later.
+- Each finding's address, numeric TCP port ID where applicable, and earlier/later source evidence.
+- Fixed-rule explanations and suggested checks. No AI verdicts or vulnerability scores.
+- Evidence limitations and blank fields for investigation notes and conclusions.
+
+**Existing files and notes are never overwritten.** If `reports/review.md` exists, choose a
+new filename, such as `reports/review-02.md`. There is no force-overwrite option.
+The same input paths and contents produce the same report content.
+
+Validation finishes before any report is created. Watchpost writes a private temporary file,
+then publishes the complete report with a non-replacing hard link. This also protects a destination
+created by another writer. The output directory must exist and its filesystem must support hard links.
+If it does not, the command fails instead of using an unsafe overwrite fallback.
+This workflow targets Linux and Ubuntu WSL. Use a trusted output directory.
+
+Keep the original XML files with your report. Reports reference the supplied files but do not embed
+or authenticate them. Paths appear as escaped literals so filename markup stays plain text.
+Review real reports before sharing: they contain network details and are not anonymous.
+See [the reporting milestone](docs/reporting-milestone.md) for the safety checks and boundaries.
+
+## Practice the three scenarios
+
+Follow the [synthetic review walkthroughs](docs/scenarios.md). No live scan is required.
+
+1. **Expected deployment:** compare an observed change with an approved lab deployment plan.
+2. **Unintended backend exposure:** interpret the same evidence against a different access policy.
+3. **Incomplete scan:** confirm that a reported host timeout prevents report creation.
+
+The first two scenarios use the same XML pair deliberately. Watchpost reports evidence, not intent.
+The walkthroughs supply fictional context and clearly labeled example review notes.
+
+## How inspection works
+
+1. Read the selected local file and reject inputs larger than 10 MiB.
+2. Parse XML with entity expansion and external entities disabled.
+3. Check the Nmap root, completion marker, TCP scan metadata, and explicit IPv4/TCP records.
+4. Print addresses and ports in numerical order.
+
+The command rejects malformed XML, unsupported encodings, failed scans, reported host timeouts,
+UDP/IPv6 data, invalid addresses or ports, and duplicate observations.
+Errors exit with code 2, without partial inventory output.
+
+Only explicit `<port>` records are listed. This milestone does not expand grouped
+`<extraports>` records, even when additional metadata is present. Hostnames, service names,
+script output, and other free-text scan fields are not printed.
+
+This is not full Nmap schema validation. `inspect` focuses on individual records;
+`compare` adds the stronger metadata checks described above. Host status, service names,
+script output, and grouped states are not compared. Matching metadata does not prove identical
+scan conditions, and no-change output is not a safety verdict.
+
+## Development
+
+Python 3.11+ and [uv](https://docs.astral.sh/uv/) are required for these commands.
+Dependency installation can need internet access. The application and tests run offline afterward.
+
+```bash
+uv sync --dev --python 3.11
+uv run python -m unittest discover -s tests -v
+uv run ruff format --check .
+uv run ruff check .
+```
+
+The runtime uses `defusedxml` to reject XML entities instead of maintaining a custom XML parser.
+The tests use the standard library's `unittest`. Pytest is an optional development runner.
+
+## Data handling
+
+- Only inspect data from networks you own or have permission to assess.
+- All bundled XML examples and the sample report are synthetic and use documentation-only IP addresses.
+- Keep real inputs in `scans/` and reports in `reports/`. Both directories are ignored by Git.
+- Reports are not automatically anonymous. Review files before publishing them.
+- Missing observations do not prove closed ports or removed devices.
+- IP addresses are not device identities. Port numbers are not application identities.
+- An observed change does not prove vulnerability or compromise.
+
+## License
+
+Watchpost is licensed under the [MIT License](LICENSE).
+Third-party dependencies retain their own licenses.
+
+## Roadmap
+
+- [x] Safely inspect one saved IPv4/TCP scan.
+- [x] Validate and compare two snapshots without inventing missing evidence.
+- [x] Produce Markdown reports with evidence, limitations, and human review notes.
+- [x] Document the three scenarios in the brief.
+
+No dashboard, live scanning, scheduling, AI verdicts, or automatic remediation is planned in the v0.1 brief.

watchpost_cli-0.0.1/README.md

@@ -0,0 +1,204 @@
+# Watchpost
+
+Local-first, evidence-backed reviews of changes between saved Nmap scans.
+
+**Status: inspection, comparison, Markdown reporting, and synthetic walkthroughs implemented.**
+Two saved XML files can produce a change-review report. The [three walkthroughs](docs/scenarios.md)
+cover expected deployment, unintended backend exposure, and an incomplete scan.
+[Published releases](https://github.com/ejames-dev/watchpost/releases) are listed on GitHub.
+A source checkout can contain unreleased changes.
+See the [release notes](CHANGELOG.md) and [release-readiness checklist](docs/release-v0.0.1.md).
+
+**[User wiki](https://github.com/ejames-dev/watchpost/wiki)** — setup, report interpretation,
+scenarios, troubleshooting, and safety.
+
+## Package name
+
+The distribution name for PyPI and TestPyPI is **`watchpost-cli`**.
+The command and Python module remain `watchpost`. The GitHub repository remains `ejames-dev/watchpost`.
+The registry package named `watchpost` belongs to an unrelated project. Do not install it for this tool.
+Until registry publication is confirmed, use the source-checkout instructions below.
+See [publishing setup](docs/publishing.md) for the maintainer workflow.
+
+## Scope
+
+Watchpost is for students and home-lab operators working on authorized networks.
+Inspect a saved Nmap XML file or compare two snapshots of explicit IPv4/TCP observations.
+Watchpost does not launch Nmap, discover devices, or make network requests.
+
+The approved target is in [the v0.1 project brief](docs/brief-v0.1.md).
+
+## Try the synthetic demo
+
+With Python 3.11+ and [uv](https://docs.astral.sh/uv/) installed:
+
+```bash
+git clone https://github.com/ejames-dev/watchpost.git
+cd watchpost
+uv sync --locked --dev --python 3.11
+uv run --offline watchpost inspect examples/baseline.xml
+```
+
+```text
+IPv4/TCP observations (not a security verdict)
+192.0.2.10
+  22/tcp  open
+  80/tcp  closed
+  443/tcp  open
+  3000/tcp  closed
+192.0.2.20
+  22/tcp  open
+Only explicit port observations are listed; missing ports are not classified.
+```
+
+Nmap is not required. These addresses and states are fictional.
+For an existing checkout, run the final two commands from its root directory.
+
+## Compare two snapshots
+
+```bash
+uv run --offline watchpost compare examples/baseline.xml examples/after.xml \
+  --confirm-same-context
+```
+
+The synthetic second scan is one minute later. Its only explicit state change is:
+
+```text
+STATE CHANGE 192.0.2.10 3000/tcp: closed -> open
+```
+
+The output includes both source paths, UTC scan windows, Nmap version, scan method,
+declared port count, differences, and limitations. Without `--output`, the command prints
+only to the terminal.
+
+**Before using real inputs, confirm the same scan location, intended targets, and remaining
+Nmap settings.** The flag records your confirmation. It does not let Watchpost verify the
+network location, reconstruct the full command line, or override failed metadata checks.
+Do not use it to force a comparison you know is incompatible.
+
+Comparison currently requires:
+
+- One TCP connect or SYN scan per snapshot, with the same method and Nmap version.
+- Identical declared TCP port coverage. Equivalent lists and ranges are normalized.
+- A declared port count that matches that coverage, with all explicit ports inside it.
+- Successful scan completion and valid start/end timestamps.
+- Earlier and later scan windows that do not overlap. Equal windows with identical supported
+  observations are allowed, so comparing a snapshot with itself produces no observed changes.
+
+| Evidence | Output |
+|---|---|
+| Explicit states differ | `STATE CHANGE ... closed -> open` |
+| A port has no earlier explicit record | `PORT OBSERVATION ... not observed -> open` |
+| A port has no later explicit record | `PORT OBSERVATION ... open -> not observed` |
+| An address appears in only one snapshot | `ADDRESS OBSERVATION`, not a device addition/removal claim |
+| Supported explicit observations match | `No observed changes in explicit IPv4/TCP records.` |
+
+A newly observed port is not proof that a service just started. A missing port is not proof of
+closure. Grouped records and uncertain states do not become guessed open/closed results.
+See the [comparison milestone](docs/compare-milestone.md) for boundaries and verification.
+
+## Save a Markdown report
+
+Create the output directory, then generate a report:
+
+```bash
+mkdir -p reports
+uv run --offline watchpost compare examples/baseline.xml examples/after.xml \
+  --confirm-same-context --output reports/review.md
+```
+
+Open `reports/review.md` in a text editor or Markdown viewer.
+See [the synthetic sample report](examples/report.md) for the expected result.
+
+Each report includes:
+
+- Source paths, UTC scan windows, scan metadata, and user-confirmed assumptions.
+- Separate counts for changed states, newly observed records, and records not observed later.
+- Each finding's address, numeric TCP port ID where applicable, and earlier/later source evidence.
+- Fixed-rule explanations and suggested checks. No AI verdicts or vulnerability scores.
+- Evidence limitations and blank fields for investigation notes and conclusions.
+
+**Existing files and notes are never overwritten.** If `reports/review.md` exists, choose a
+new filename, such as `reports/review-02.md`. There is no force-overwrite option.
+The same input paths and contents produce the same report content.
+
+Validation finishes before any report is created. Watchpost writes a private temporary file,
+then publishes the complete report with a non-replacing hard link. This also protects a destination
+created by another writer. The output directory must exist and its filesystem must support hard links.
+If it does not, the command fails instead of using an unsafe overwrite fallback.
+This workflow targets Linux and Ubuntu WSL. Use a trusted output directory.
+
+Keep the original XML files with your report. Reports reference the supplied files but do not embed
+or authenticate them. Paths appear as escaped literals so filename markup stays plain text.
+Review real reports before sharing: they contain network details and are not anonymous.
+See [the reporting milestone](docs/reporting-milestone.md) for the safety checks and boundaries.
+
+## Practice the three scenarios
+
+Follow the [synthetic review walkthroughs](docs/scenarios.md). No live scan is required.
+
+1. **Expected deployment:** compare an observed change with an approved lab deployment plan.
+2. **Unintended backend exposure:** interpret the same evidence against a different access policy.
+3. **Incomplete scan:** confirm that a reported host timeout prevents report creation.
+
+The first two scenarios use the same XML pair deliberately. Watchpost reports evidence, not intent.
+The walkthroughs supply fictional context and clearly labeled example review notes.
+
+## How inspection works
+
+1. Read the selected local file and reject inputs larger than 10 MiB.
+2. Parse XML with entity expansion and external entities disabled.
+3. Check the Nmap root, completion marker, TCP scan metadata, and explicit IPv4/TCP records.
+4. Print addresses and ports in numerical order.
+
+The command rejects malformed XML, unsupported encodings, failed scans, reported host timeouts,
+UDP/IPv6 data, invalid addresses or ports, and duplicate observations.
+Errors exit with code 2, without partial inventory output.
+
+Only explicit `<port>` records are listed. This milestone does not expand grouped
+`<extraports>` records, even when additional metadata is present. Hostnames, service names,
+script output, and other free-text scan fields are not printed.
+
+This is not full Nmap schema validation. `inspect` focuses on individual records;
+`compare` adds the stronger metadata checks described above. Host status, service names,
+script output, and grouped states are not compared. Matching metadata does not prove identical
+scan conditions, and no-change output is not a safety verdict.
+
+## Development
+
+Python 3.11+ and [uv](https://docs.astral.sh/uv/) are required for these commands.
+Dependency installation can need internet access. The application and tests run offline afterward.
+
+```bash
+uv sync --dev --python 3.11
+uv run python -m unittest discover -s tests -v
+uv run ruff format --check .
+uv run ruff check .
+```
+
+The runtime uses `defusedxml` to reject XML entities instead of maintaining a custom XML parser.
+The tests use the standard library's `unittest`. Pytest is an optional development runner.
+
+## Data handling
+
+- Only inspect data from networks you own or have permission to assess.
+- All bundled XML examples and the sample report are synthetic and use documentation-only IP addresses.
+- Keep real inputs in `scans/` and reports in `reports/`. Both directories are ignored by Git.
+- Reports are not automatically anonymous. Review files before publishing them.
+- Missing observations do not prove closed ports or removed devices.
+- IP addresses are not device identities. Port numbers are not application identities.
+- An observed change does not prove vulnerability or compromise.
+
+## License
+
+Watchpost is licensed under the [MIT License](LICENSE).
+Third-party dependencies retain their own licenses.
+
+## Roadmap
+
+- [x] Safely inspect one saved IPv4/TCP scan.
+- [x] Validate and compare two snapshots without inventing missing evidence.
+- [x] Produce Markdown reports with evidence, limitations, and human review notes.
+- [x] Document the three scenarios in the brief.
+
+No dashboard, live scanning, scheduling, AI verdicts, or automatic remediation is planned in the v0.1 brief.

watchpost_cli-0.0.1/docs/brief-v0.1.md

@@ -0,0 +1,74 @@
+# Watchpost v0.1 project brief
+
+Status: approved scope. Implementation starts with single-snapshot inspection.
+Watchpost is the working name. This document describes the target, not completed features.
+
+## Purpose
+
+Turn two saved network scans into one clear, evidence-backed change report.
+Serve students and home-lab operators working on networks they own or have permission to assess.
+Explain what changed, what evidence supports the finding, and what to check next.
+Do not decide that a network is secure or compromised.
+
+## Target workflow
+
+Earlier Nmap XML + later Nmap XML → validate → compare → Markdown report → human review.
+Use Python 3.11+ on Linux or Ubuntu WSL. Support IPv4 addresses and TCP ports first.
+No account, API key, or cloud service is required at runtime.
+
+## Inputs
+
+Accept two saved Nmap XML files with results and scan metadata.
+Validate completion status and relevant settings, including port coverage.
+Reject malformed, failed, incomplete, or incompatible inputs with an actionable explanation.
+If required comparison metadata is missing, do not claim a reliable comparison.
+The user confirms the same scan location and intended target scope.
+XML alone cannot establish these facts.
+Use synthetic bundled files so the demo does not need Nmap installed.
+
+## Report
+
+- Source files, scan times, and comparison assumptions.
+- Counts of observed changes and missing observations.
+- Address, TCP port, earlier state, later state, and source evidence per finding.
+- Fixed-rule explanations and suggested checks, not AI verdicts.
+- Limitations of the available evidence.
+- Blank fields for human investigation notes and conclusions.
+
+## Non-negotiable rules
+
+- Missing observations stay unknown or not observed, not confirmed closed or removed.
+- An IP address is not proof of a device identity.
+- Changes are not proof of vulnerability or compromise.
+- Port numbers alone do not identify applications.
+- Input stays local. No scans, uploads, telemetry, or external XML requests.
+- Reports are not automatically anonymous. Public examples must be synthetic.
+- Never silently overwrite existing reports or investigation notes.
+
+## Completion criteria
+
+- A documented command generates a report from example files entirely offline after installation.
+- Identical snapshots produce "no observed changes", not a safety verdict.
+- Tests cover newly observed ports and explicit, supported port-state changes.
+- Missing observations never become invented closures.
+- Unsuitable inputs fail with clear explanations.
+- Three scenarios document an expected deployment, unintended backend exposure, and an incomplete scan.
+- The same inputs produce repeatable findings.
+
+Planned and current test command: `python -m unittest discover -s tests -v`.
+This command alone does not prove all target features exist. Check the README milestone status.
+
+## Outside v0.1
+
+Dashboard, live scans, scheduling, packet capture, database, AI analysis, vulnerability scoring,
+automatic fixes, UDP, and IPv6.
+
+## First milestone
+
+1. Safely read one synthetic XML file.
+2. Validate that it is a completed IPv4/TCP Nmap scan.
+3. List explicit address and port-state observations in a stable order.
+4. Test normal input, unsafe XML, unsupported input, and incomplete scans.
+5. Document an offline demo and limitations before publishing.
+
+Comparison and Markdown reporting follow this milestone.

watchpost_cli-0.0.1/docs/compare-milestone.md

@@ -0,0 +1,57 @@
+# Snapshot comparison milestone
+
+## Goal
+
+Add `watchpost compare BEFORE AFTER --confirm-same-context` without changing the existing inspect output.
+Print a deterministic, evidence-linked terminal comparison.
+The later [reporting milestone](reporting-milestone.md) adds optional Markdown output.
+
+## Impact and implementation
+
+- Reuse the existing safe XML parser and inventory validation in `watchpost.py`.
+- Preserve `read_inventory(Path)` for its existing CLI and test callers.
+- Add typed snapshot metadata and change records with standard-library dataclasses.
+- Add a second synthetic example and comparison tests. No new dependencies or network calls.
+- Extend the current CI demo and source archive to include the second example.
+
+## Comparison gate
+
+- Require explicit confirmation of the same scan location, intended target scope, and remaining Nmap settings.
+- Support one TCP connect or SYN scan per snapshot for this milestone.
+- Require matching Nmap versions, scan methods, and normalized TCP port sets.
+- Require a valid declared port count and explicit observations within the declared coverage.
+- Require valid UTC start/end times with start <= end.
+- Reject reversed or overlapping scan windows. Equal windows with identical supported observations are allowed for repeat-input checks.
+- Retain the existing failures for malformed XML, unsafe entities, unsupported addresses/protocols, timeouts, duplicates, and unsuccessful scans.
+
+## Difference semantics
+
+- Compare addresses by IP, not by claimed device identity.
+- Report addresses appearing in only one snapshot as newly observed or not observed.
+- Compare the union of explicit TCP port records for each address.
+- Report an explicit state change only when both snapshots contain a state for that port.
+- Missing or grouped records remain not observed. Never infer a closure from absence.
+- Preserve uncertain states such as open|filtered without relabeling them as open.
+- Sort addresses and ports numerically. Display source paths safely and scan times in UTC.
+- For identical supported observations, say "No observed changes in explicit IPv4/TCP records", not "safe".
+
+## Verification
+
+`uv run --offline python -m unittest discover -s tests -v`
+
+Cover metadata parsing and rejection, port ranges/counts, chronological ordering, identical inputs,
+explicit state changes, missing ports/addresses, newly observed ports/addresses, uncertain states,
+mandatory confirmation, deterministic output, safe source-path display, and no partial output on failure.
+Run the existing suite, Ruff, package checks, and Python 3.11/3.12/3.13 CI.
+
+## Limits and prior art
+
+This milestone does not parse or compare the entire Nmap command line. Human confirmation covers
+settings and environment that the automated checks do not establish. Equal metadata is not proof
+of an equivalent measurement. Hostnames, application identities, grouped port states, and script
+output remain outside the diff. No automatic scans or security verdicts.
+Comparison writes only to the terminal unless `--output` selects a new report file.
+
+Nmap already provides scanning and Ndiff provides raw comparisons. This project adds conservative
+validation, explicit limitations, and a review workflow rather than a replacement scanner.
+Reference: https://nmap.org/book/output-formats-xml-output.html