watchpost-cli 0.0.1__py3-none-any.whl

watchpost.py

@@ -0,0 +1,304 @@
+"""Inspect, compare, and report saved Nmap observations without network requests."""
+
+import argparse
+import re
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from ipaddress import IPv4Address
+from pathlib import Path
+from xml.etree.ElementTree import Element, ParseError
+
+from defusedxml import ElementTree
+from defusedxml.common import DefusedXmlException
+
+from watchpost_report import render_markdown, write_report
+
+# ponytail: cap snapshots at 10 MiB for small labs; stream if larger inputs are needed.
+MAX_XML_BYTES = 10 * 1024 * 1024
+PORT_STATES = {"open", "closed", "filtered", "unfiltered", "open|filtered", "closed|filtered"}
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    source: Path
+    started: datetime
+    finished: datetime
+    method: str
+    version: str
+    coverage: frozenset[int]
+    inventory: dict[str, dict[int, str]]
+
+
+@dataclass(frozen=True)
+class Change:
+    address: str
+    port: int | None
+    before: str | None
+    after: str | None
+
+
+def _read_root(path: Path) -> Element:
+    """Safely load a completed TCP Nmap export without resolving external content."""
+    if not path.is_file():
+        raise ValueError("Snapshot must be an existing regular file. Check the input path.")
+    with path.open("rb") as source:
+        data = source.read(MAX_XML_BYTES + 1)
+    if len(data) > MAX_XML_BYTES:
+        raise ValueError("Snapshot exceeds the 10 MiB limit. Use a smaller lab snapshot.")
+    try:
+        root = ElementTree.fromstring(data, forbid_entities=True, forbid_external=True)
+    except DefusedXmlException as exc:
+        raise ValueError(
+            "Unsafe XML. Entity declarations and external entities are not allowed."
+        ) from exc
+    except (ParseError, LookupError, ValueError) as exc:
+        raise ValueError(
+            "Malformed XML or unsupported encoding. Use a complete UTF-8 Nmap export."
+        ) from exc
+
+    if root.tag != "nmaprun" or root.get("scanner") != "nmap":
+        raise ValueError("Expected an Nmap XML export with an nmaprun root.")
+    finished = root.findall("runstats/finished")
+    if len(finished) != 1 or finished[0].get("exit") != "success":
+        raise ValueError("Scan is not confirmed complete. Use a successfully finished Nmap export.")
+    scan_info = root.findall("scaninfo")
+    if not scan_info or any(info.get("protocol") != "tcp" for info in scan_info):
+        raise ValueError("Only scans with TCP scaninfo are supported. Use a TCP-only export.")
+
+    return root
+
+
+def _inventory_from_xml(root: Element) -> dict[str, dict[int, str]]:
+    inventory = {}
+    for host in root.findall("host"):
+        if host.get("timedout") not in (None, "false", "0"):
+            raise ValueError("Host scan is incomplete (timeout). Use a completed snapshot.")
+        if host.find("address[@addrtype='ipv6']") is not None:
+            raise ValueError("Only IPv4 addresses are supported. Use an IPv4-only export.")
+        addresses = host.findall("address[@addrtype='ipv4']")
+        if len(addresses) != 1:
+            raise ValueError("Each host must have exactly one IPv4 address.")
+        try:
+            address = str(IPv4Address(addresses[0].get("addr", "")))
+        except ValueError as exc:
+            raise ValueError("Invalid IPv4 address. Check the host address in the export.") from exc
+        if address in inventory:
+            raise ValueError(f"Duplicate IPv4 host {address}. Use an unambiguous snapshot.")
+
+        ports = {}
+        for port in host.findall("ports/port"):
+            if port.get("protocol") != "tcp":
+                raise ValueError("Only TCP port observations are supported.")
+            port_id = port.get("portid", "")
+            if not port_id.isascii() or not port_id.isdecimal() or len(port_id) > 5:
+                raise ValueError("Invalid TCP port number. Expected a number from 0 to 65535.")
+            number = int(port_id)
+            if number > 65535:
+                raise ValueError("Invalid TCP port number. Expected a number from 0 to 65535.")
+            if number in ports:
+                raise ValueError(f"Duplicate TCP port {number} for {address}.")
+            states = port.findall("state")
+            if len(states) != 1 or states[0].get("state") not in PORT_STATES:
+                raise ValueError("Each explicit port must have one recognized Nmap port state.")
+            ports[number] = states[0].attrib["state"]
+        inventory[address] = ports
+    return inventory
+
+
+def read_inventory(path: Path) -> dict[str, dict[int, str]]:
+    """Read explicit IPv4/TCP observations. Do not expand aggregated port counts."""
+    return _inventory_from_xml(_read_root(path))
+
+
+def _scan_time(value: str) -> datetime:
+    if not re.fullmatch(r"[0-9]{1,12}", value):
+        raise ValueError("Comparison requires valid Unix start and finish timestamps.")
+    try:
+        return datetime.fromtimestamp(int(value), UTC)
+    except (ValueError, OverflowError, OSError) as exc:
+        raise ValueError("Scan timestamp is outside the supported calendar range.") from exc
+
+
+def _port_coverage(services: str) -> frozenset[int]:
+    ports: set[int] = set()
+    for token in services.split(","):
+        if not re.fullmatch(r"[0-9]{1,5}(?:-[0-9]{1,5})?", token):
+            raise ValueError(
+                "Invalid TCP coverage. Expected ports or ranges such as 22,80,443-445."
+            )
+        bounds = [int(value) for value in token.split("-")]
+        first, last = bounds[0], bounds[-1]
+        if first > last or last > 65535:
+            raise ValueError("Invalid TCP coverage range. Ports must be between 0 and 65535.")
+        for number in range(first, last + 1):
+            if number in ports:
+                raise ValueError("Duplicate or overlapping ports in declared TCP coverage.")
+            ports.add(number)
+    return frozenset(ports)
+
+
+def read_snapshot(path: Path) -> Snapshot:
+    """Read the stronger metadata needed for a conservative comparison."""
+    root = _read_root(path)
+    inventory = _inventory_from_xml(root)
+    scans = root.findall("scaninfo")
+    if len(scans) != 1 or scans[0].get("type") not in {"connect", "syn"}:
+        raise ValueError("Comparison supports exactly one TCP connect or SYN scan per snapshot.")
+    version = root.get("version", "")
+    if not re.fullmatch(r"[0-9][A-Za-z0-9._+-]{0,63}", version):
+        raise ValueError("Comparison requires a valid Nmap version in each snapshot.")
+    started = _scan_time(root.get("start", ""))
+    finished = _scan_time(root.findall("runstats/finished")[0].get("time", ""))
+    if finished < started:
+        raise ValueError(
+            "Scan finish time is before its start time. Check the snapshot timestamps."
+        )
+    coverage = _port_coverage(scans[0].get("services", ""))
+    count = scans[0].get("numservices", "")
+    if not re.fullmatch(r"[0-9]{1,5}", count) or int(count) != len(coverage):
+        raise ValueError("Declared TCP port count does not match the port coverage.")
+    for ports in inventory.values():
+        if not set(ports).issubset(coverage):
+            raise ValueError("Explicit port observations fall outside the declared TCP coverage.")
+    return Snapshot(path, started, finished, scans[0].attrib["type"], version, coverage, inventory)
+
+
+def compare_snapshots(
+    before: Snapshot, after: Snapshot, *, same_context_confirmed: bool = False
+) -> list[Change]:
+    """Compare supported observations; None means not observed, never closed."""
+    if not same_context_confirmed:
+        raise ValueError(
+            "Confirm the same scan location, intended targets, and other scan settings."
+        )
+    if before.method != after.method:
+        raise ValueError("Scan methods differ. Compare snapshots from the same scan method.")
+    if before.version != after.version:
+        raise ValueError("Nmap versions differ. Compare snapshots from the same Nmap version.")
+    if before.coverage != after.coverage:
+        raise ValueError(
+            "TCP port coverage differs. Compare snapshots with identical port coverage."
+        )
+    if after.started < before.started:
+        raise ValueError("Snapshots are reversed. Supply the earlier scan first.")
+    repeat_observations = (
+        before.started == after.started
+        and before.finished == after.finished
+        and before.inventory == after.inventory
+    )
+    if after.started < before.finished and not repeat_observations:
+        raise ValueError("Scan windows overlap. Use non-overlapping earlier and later scans.")
+
+    changes = []
+    for address in sorted(before.inventory.keys() | after.inventory.keys(), key=IPv4Address):
+        if (address in before.inventory) != (address in after.inventory):
+            changes.append(
+                Change(
+                    address,
+                    None,
+                    "observed" if address in before.inventory else None,
+                    "observed" if address in after.inventory else None,
+                )
+            )
+        old_ports = before.inventory.get(address, {})
+        new_ports = after.inventory.get(address, {})
+        for port in sorted(old_ports.keys() | new_ports.keys()):
+            old_state, new_state = old_ports.get(port), new_ports.get(port)
+            if old_state != new_state:
+                changes.append(Change(address, port, old_state, new_state))
+    return changes
+
+
+def _format_comparison(before: Snapshot, after: Snapshot, changes: list[Change]) -> str:
+    lines = [
+        "Snapshot comparison (not a security verdict)",
+        f"Earlier: {str(before.source)!a}",
+        f"  UTC window: {before.started.isoformat()} -> {before.finished.isoformat()}",
+        f"Later: {str(after.source)!a}",
+        f"  UTC window: {after.started.isoformat()} -> {after.finished.isoformat()}",
+        f"Scan: TCP {before.method}; Nmap {before.version}; {len(before.coverage)} declared ports",
+        "Context: same location, intended targets, and other settings confirmed by user.",
+        f"Observation differences: {len(changes)}",
+    ]
+    if not changes:
+        lines.append("No observed changes in explicit IPv4/TCP records.")
+    for change in changes:
+        target = change.address
+        if change.port is None:
+            label = "ADDRESS OBSERVATION"
+        else:
+            target += f" {change.port}/tcp"
+            label = (
+                "STATE CHANGE"
+                if change.before is not None and change.after is not None
+                else "PORT OBSERVATION"
+            )
+        lines.append(
+            f"{label} {target}: {change.before or 'not observed'} -> "
+            f"{change.after or 'not observed'}"
+        )
+    lines.extend(
+        [
+            "Missing and grouped port records are not classified as closed.",
+            "IP addresses are not device identities; port numbers are not application identities.",
+            "Context is user-confirmed, not independently verified by Watchpost.",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="watchpost",
+        description="Inspect and compare saved Nmap XML locally. No scans or network requests.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    inspect = commands.add_parser(
+        "inspect", help="List explicit IPv4/TCP observations in one scan."
+    )
+    inspect.add_argument("snapshot", type=Path, help="Path to a completed Nmap XML export.")
+    compare = commands.add_parser("compare", help="Compare two saved IPv4/TCP scans.")
+    compare.add_argument("before", type=Path, help="Earlier completed Nmap XML export.")
+    compare.add_argument("after", type=Path, help="Later completed Nmap XML export.")
+    compare.add_argument(
+        "--confirm-same-context",
+        action="store_true",
+        required=True,
+        help="Confirm the same scan location, intended targets, and other Nmap settings.",
+    )
+    compare.add_argument(
+        "--output", type=Path, help="Save a Markdown report to a new file; never overwrite."
+    )
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "compare":
+            before, after = read_snapshot(args.before), read_snapshot(args.after)
+            changes = compare_snapshots(
+                before, after, same_context_confirmed=args.confirm_same_context
+            )
+            if args.output is None:
+                print(_format_comparison(before, after, changes))
+            else:
+                write_report(args.output, render_markdown(before, after, changes))
+                print(f"Report saved to {str(args.output)!a}")
+            return 0
+        inventory = read_inventory(args.snapshot)
+    except (OSError, ValueError) as exc:
+        parser.exit(2, f"watchpost: error: {exc}\n")
+
+    print("IPv4/TCP observations (not a security verdict)")
+    if not inventory:
+        print("No IPv4 host observations.")
+    for address in sorted(inventory, key=IPv4Address):
+        print(address)
+        ports = inventory[address]
+        if not ports:
+            print("  No explicit TCP port observations.")
+        for number, state in sorted(ports.items()):
+            print(f"  {number}/tcp  {state}")
+    print("Only explicit port observations are listed; missing ports are not classified.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

watchpost_cli-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+watchpost.py,sha256=6_Q58hzCZxQMspSbL2W9M2jHw3x4W3T5gfOBEAQtQl4,13379
+watchpost_report.py,sha256=X2jF7fGc9X4UgOWaaMwfNjX4VJY1q1J8cblgJ077Nn4,8531
+watchpost_cli-0.0.1.dist-info/licenses/LICENSE,sha256=h2Fu_9apC0mxJm9UeAsOyilovHbq0hJdg6bN4q4H0t0,1068
+watchpost_cli-0.0.1.dist-info/METADATA,sha256=x4izvWQvmS4qNZ6vID8zmCheYbU7qz5udQM3IzZ8-WY,10022
+watchpost_cli-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+watchpost_cli-0.0.1.dist-info/entry_points.txt,sha256=bbBBF7yUYx7-hckl3wrERxvGxHSh8C9h8gMzJCbJkw0,45
+watchpost_cli-0.0.1.dist-info/top_level.txt,sha256=oCVfS7UQ3zD7JkMbcHow37IizEfAZjP68q6Bldp3AHc,27
+watchpost_cli-0.0.1.dist-info/RECORD,,

watchpost_cli-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

watchpost_cli-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+watchpost = watchpost:main

watchpost_cli-0.0.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+watchpost
+watchpost_report

watchpost_report.py

@@ -0,0 +1,205 @@
+"""Deterministic Markdown for validated comparisons; no scanning or network access."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from watchpost import Change, Snapshot
+
+
+def _finding_text(change: Change) -> tuple[str, str, str]:
+    """Return a category, explanation, and suggested human check."""
+    if change.port is None:
+        return (
+            "Address newly observed" if change.before is None else "Address not observed later",
+            "This address has a record in only one snapshot. This does not prove a device "
+            "was added or removed, or that the same device held this address in both scans.",
+            "Confirm target scope, address assignments, host availability, and scan reachability.",
+        )
+    if change.before is None:
+        return (
+            "Port newly observed",
+            "There is no earlier explicit port record. The later state is observed, but the "
+            "earlier state is unknown. This is not proof that a service just started.",
+            "Review earlier grouped or omitted records and confirm whether the later "
+            "service and exposure are expected from the scan location.",
+        )
+    if change.after is None:
+        return (
+            "Port not observed later",
+            "There is no later explicit port record. Absence is not a confirmed closure, "
+            "even if the later XML contains grouped closed-port counts.",
+            "Check host availability, grouped records, and scan conditions before "
+            "concluding that the port closed.",
+        )
+    if change.after == "open":
+        explanation = (
+            "Both scans contain explicit states, and the later scan reports this port as open. "
+            "This does not identify the application or prove Internet exposure or compromise."
+        )
+    elif change.after == "closed":
+        explanation = (
+            "Both scans contain explicit states, and the later scan reports this port as closed. "
+            "This observation does not prove it is inaccessible from every network location."
+        )
+    else:
+        explanation = (
+            "Both scans contain explicit states, but the later state does not establish open "
+            "or closed. Filtered and uncertain states must not be relabeled as either."
+        )
+    return (
+        "Port state changed",
+        explanation,
+        "Check expected service changes, listening interfaces, and firewall rules. "
+        "Confirm the intended result from the authorized scan location.",
+    )
+
+
+def _source_section(label: str, snapshot: Snapshot) -> list[str]:
+    # Indentation makes all filename markup literal; ascii escapes controls and newlines.
+    return [
+        f"### {label} snapshot",
+        "",
+        "Source path (escaped literal):",
+        "",
+        f"    {str(snapshot.source)!a}",
+        "",
+        f"- UTC start: `{snapshot.started.isoformat()}`",
+        f"- UTC finish: `{snapshot.finished.isoformat()}`",
+        f"- Nmap version: `{snapshot.version}`",
+        f"- Scan method: TCP `{snapshot.method}`",
+        f"- Declared TCP ports: {len(snapshot.coverage)}",
+        f"- IPv4 address records: {len(snapshot.inventory)}",
+        f"- Explicit TCP port records: {sum(len(ports) for ports in snapshot.inventory.values())}",
+        "",
+    ]
+
+
+def render_markdown(before: Snapshot, after: Snapshot, changes: list[Change]) -> str:
+    """Render read_snapshot/compare_snapshots results after the comparison gate passes."""
+    counts = dict.fromkeys(
+        (
+            "Port state changed",
+            "Port newly observed",
+            "Port not observed later",
+            "Address newly observed",
+            "Address not observed later",
+        ),
+        0,
+    )
+    findings = []
+    for number, change in enumerate(changes, 1):
+        category, explanation, check = _finding_text(change)
+        counts[category] += 1
+        record = f"IPv4 `{change.address}`"
+        if change.port is not None:
+            record += f", TCP port `{change.port}` (numeric ID)"
+        findings.extend(
+            [
+                f"### {number}. {category}",
+                "",
+                f"- **Record:** {record}",
+                f"- **Earlier evidence:** `{change.before or 'not observed'}` — Earlier snapshot",
+                f"- **Later evidence:** `{change.after or 'not observed'}` — Later snapshot",
+                "",
+                f"**Explanation:** {explanation}",
+                "",
+                f"**Suggested check:** {check}",
+                "",
+                "**Investigation notes:**",
+                "",
+                "**Conclusion:**",
+                "",
+            ]
+        )
+
+    lines = [
+        "# Watchpost change review",
+        "",
+        "> Observations, not a security verdict. Changes do not prove vulnerability or compromise.",
+        "",
+        "## Comparison context",
+        "",
+        "- Context: same location, intended targets, and other settings confirmed by user.",
+        "- Watchpost checked completion, timestamps, Nmap version, scan method, and port coverage.",
+        "- Matching metadata does not independently establish matching scan conditions.",
+        "",
+        *_source_section("Earlier", before),
+        *_source_section("Later", after),
+        "## Summary",
+        "",
+        f"Total observation differences: **{len(changes)}**",
+        "",
+        "| Observation category | Count |",
+        "|---|---:|",
+        *(f"| {category} | {count} |" for category, count in counts.items()),
+        "",
+        "Address and port differences are counted separately, "
+        "not as distinct incidents or devices.",
+        "",
+        "## Findings",
+        "",
+        "Source names below refer to the Earlier and Later snapshot sections above. "
+        "Port evidence is the explicit XML state for the listed IPv4 address and numeric TCP "
+        "port ID. Address evidence records presence only, not host status or device identity.",
+        "",
+        "`not observed` means no explicit record in the parsed inventory; it is not an Nmap state.",
+        "",
+        *(
+            findings
+            or [
+                "No observed changes in explicit IPv4/TCP records. This is not a safety verdict.",
+                "",
+            ]
+        ),
+        "## Limitations",
+        "",
+        "- Missing and grouped port records are not classified as closed.",
+        "- IP addresses are not device identities; port numbers are not application identities.",
+        "- Filtered and uncertain states are preserved, not treated as confirmed open or closed.",
+        "- Host status, hostnames, service names, scripts, and grouped states are not compared.",
+        "- These are scan-window observations, not proof of when or why a change happened.",
+        "- User confirmation is not independently verified by Watchpost.",
+        "- Keep the original XML files with this report; "
+        "references do not embed or authenticate them.",
+        "- Reports contain network details and are not anonymous. Review before sharing.",
+        "",
+        "## Human review",
+        "",
+        "**Reviewer:**",
+        "",
+        "**Reviewed at (UTC):**",
+        "",
+        "**Overall investigation notes:**",
+        "",
+        "**Overall conclusion:**",
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def write_report(path: Path, content: str) -> None:
+    """Publish a complete new file without replacing any existing destination."""
+    try:
+        with NamedTemporaryFile(
+            mode="w", encoding="utf-8", newline="\n", dir=path.parent, prefix=".watchpost-"
+        ) as temporary:
+            temporary.write(content)
+            temporary.flush()
+            os.fsync(temporary.fileno())
+            # Unlike replace/rename, link refuses even a concurrently created destination.
+            os.link(temporary.name, path)
+    except FileExistsError as exc:
+        raise ValueError(
+            f"Report destination already exists: {str(path)!a}. "
+            "Choose a new filename; existing files and notes are never overwritten."
+        ) from exc
+    except OSError as exc:
+        raise ValueError(
+            f"Cannot save report to {str(path)!a}: {exc.strerror or 'file operation failed'}. "
+            "Use an existing, writable directory on a filesystem that supports hard links."
+        ) from exc