pivotcheck 2.0.0__tar.gz → 2.0.2__tar.gz

{pivotcheck-2.0.0 → pivotcheck-2.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pivotcheck
-Version: 2.0.0
+Version: 2.0.2
 Summary: Passive network discovery and pivot path validation for authorized security assessments
 Author: PivotCheck contributors
 License: GPL-3.0-only

{pivotcheck-2.0.0 → pivotcheck-2.0.2}/pivotcheck/__init__.py

@@ -3,4 +3,4 @@
 Copyright (c) 2026 PivotCheck contributors. GPL-3.0-only licensed.
 """
 
-__version__ = "2.0.0"
+__version__ = "2.0.2"

{pivotcheck-2.0.0 → pivotcheck-2.0.2}/pivotcheck/analysis/explanation.py

@@ -47,9 +47,11 @@ def _finding(network: str, report: DiffReport) -> DiffFinding | None:
     return None
 
 
-def _reason(finding: DiffFinding | None) -> str:
+def _reason(finding: DiffFinding | None, observed: bool = True) -> str:
     if finding is None:
-        return "Network observed in current discovery evidence."
+        if observed:
+            return "Network observed in current discovery evidence."
+        return "Network not found in current discovery evidence."
     reasons = {
         "NEW_REACHABILITY": "Newly observed network not present in baseline.",
         "EXPANDED_REACHABILITY": "Network coverage expanded relative to baseline.",
@@ -73,21 +75,34 @@ def explain_network(
     If not, provides standalone explanation from current evidence only.
     """
     canonical = str(ipaddress.ip_network(network, strict=False))
-    
-    if report is not None:
-        finding = _finding(canonical, report)
-        classification = finding.classification if finding else "CURRENT_EVIDENCE"
-        reason = _reason(finding)
-    else:
-        # Standalone mode: no comparison context
-        classification = "CURRENT_EVIDENCE"
-        reason = "Network observed in current discovery evidence."
-    
+
     evidence = next(
-        (item for item in current.networks 
+        (item for item in current.networks
          if str(ipaddress.ip_network(item.cidr, strict=False)) == canonical),
         None
     )
+    observed = evidence is not None
+
+    if report is not None:
+        finding = _finding(canonical, report)
+        if finding is not None:
+            classification = finding.classification
+            reason = _reason(finding)
+        else:
+            # Comparison context covers a different scope than the current
+            # snapshot: classification follows what the CURRENT evidence
+            # actually shows, never an assumed observation.
+            classification = "CURRENT_EVIDENCE" if observed else "NOT_OBSERVED"
+            reason = _reason(None, observed)
+    else:
+        # Standalone mode: no comparison context.
+        if observed:
+            classification = "CURRENT_EVIDENCE"
+            reason = _reason(None, observed)
+        else:
+            classification = "NOT_OBSERVED"
+            reason = _reason(None, observed)
+
     routes = _route_evidence(canonical, current)
     
     # Get transit evidence if available

{pivotcheck-2.0.0 → pivotcheck-2.0.2}/pivotcheck/cli.py

@@ -32,6 +32,7 @@ from __future__ import annotations
 
 import argparse
 import getpass
+import ipaddress
 import os
 import re
 import sys
@@ -1674,8 +1675,33 @@ def _run_next(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
+def _validate_network_argument(network: str) -> int | None:
+    """Validate a network CLI argument against the canonical CIDR model.
+
+    Returns ``None`` when the argument is valid, otherwise ``EXIT_USAGE``
+    after printing the standard operator error. Validation is pure: invalid
+    input fails before discovery (no filesystem, network, or subprocess
+    side effects), and the original argument is passed through to analysis
+    unchanged, so valid-path behavior is byte-identical.
+    """
+    try:
+        ipaddress.ip_network(network, strict=False)
+    except ValueError:
+        print(f"[-] Invalid network argument: {network!r}.", file=sys.stderr)
+        print(
+            "    Provide a CIDR network (e.g. 10.50.0.0/16) or an IP address.",
+            file=sys.stderr,
+        )
+        return EXIT_USAGE
+    return None
+
+
 def _run_gaps(args: argparse.Namespace) -> int:
     """Execute evidence gap analysis."""
+    error = _validate_network_argument(args.network)
+    if error is not None:
+        return error
+
     # Run discovery once
     try:
         snapshot = run_discovery()
@@ -1700,6 +1726,10 @@ def _run_gaps(args: argparse.Namespace) -> int:
 
 def _run_explain(args: argparse.Namespace) -> int:
     """Execute standalone network explanation."""
+    error = _validate_network_argument(args.network)
+    if error is not None:
+        return error
+
     # If the operator explicitly requested contextual baseline analysis,
     # load the baseline BEFORE any discovery or socket activity. A missing
     # or invalid baseline fails explicitly rather than silently performing

{pivotcheck-2.0.0 → pivotcheck-2.0.2}/pivotcheck.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pivotcheck
-Version: 2.0.0
+Version: 2.0.2
 Summary: Passive network discovery and pivot path validation for authorized security assessments
 Author: PivotCheck contributors
 License: GPL-3.0-only

{pivotcheck-2.0.0 → pivotcheck-2.0.2}/tests/test_intelligence_cli.py

@@ -267,4 +267,102 @@ class TestDiscoverSummary:
         out = capsys.readouterr().out
         assert "Connected Coverage: 1" in out
         assert "Routed Coverage: 2" in out
-        assert "Inferred Pivot Paths: 1" in out
+        assert "Inferred Pivot Paths: 1" in out
+
+
+class TestNetworkArgumentValidation:
+    """Stage 9 DEFECT-002 regression: invalid network arguments must follow
+    the established CLI error contract (clean `[-]` message on stderr, no
+    Python traceback, EXIT_USAGE, no partial output, no side effects).
+
+    These tests fail against the defective 2.0.0 implementation, which
+    leaked an uncaught ValueError traceback from models/network.py and
+    exited 1.
+    """
+
+    BAD_NETWORKS = (
+        "not-a-cidr",
+        "999.999.1.0/24",  # malformed IPv4 octets
+        "10.0.0.0/33",  # invalid IPv4 prefix length
+        "10.0.0.0/120",  # IPv6 prefix length applied to IPv4
+        "10.0.0.0/24/24",  # double prefix
+        "2001:db8::/wxyz",  # malformed IPv6 prefix
+    )
+
+    @pytest.fixture(autouse=True)
+    def fake_discovery(self, monkeypatch):
+        from pivotcheck import cli
+
+        monkeypatch.setattr(cli, "run_discovery", make_snapshot)
+
+    @pytest.mark.parametrize("bad", BAD_NETWORKS)
+    def test_gaps_invalid_network_is_usage_error(self, bad, capsys):
+        assert _run(["gaps", bad]) == EXIT_USAGE
+        err = capsys.readouterr().err
+        assert "Invalid network argument" in err
+        assert "Traceback" not in err
+        assert "ValueError" not in err
+
+    @pytest.mark.parametrize("bad", BAD_NETWORKS)
+    def test_explain_invalid_network_is_usage_error(self, bad, capsys):
+        assert _run(["explain", bad]) == EXIT_USAGE
+        err = capsys.readouterr().err
+        assert "Invalid network argument" in err
+        assert "Traceback" not in err
+
+    @pytest.mark.parametrize("bad", BAD_NETWORKS)
+    def test_invalid_network_json_path_has_no_partial_result(self, bad, capsys):
+        for command in ("gaps", "explain"):
+            assert _run([command, bad, "--json"]) == EXIT_USAGE
+            captured = capsys.readouterr()
+            # No partial JSON artifact may pretend the request succeeded.
+            assert captured.out.strip() == ""
+            assert "Traceback" not in captured.err
+
+    def test_invalid_network_fails_before_discovery(self, monkeypatch, capsys):
+        """Invalid input must produce zero side effects: discovery (and any
+        I/O behind it) must never run for an invalid network argument."""
+        from pivotcheck import cli
+
+        def _must_not_run(*_args, **_kwargs):
+            raise AssertionError("discovery must not run for invalid input")
+
+        monkeypatch.setattr(cli, "run_discovery", _must_not_run)
+        assert _run(["gaps", "not-a-cidr"]) == EXIT_USAGE
+        assert "Invalid network argument" in capsys.readouterr().err
+
+    def test_valid_cidr_behavior_unchanged(self, capsys):
+        assert _run(["gaps", "10.50.0.0/16"]) == EXIT_OK
+        out = capsys.readouterr().out
+        assert "10.50.0.0/16" in out
+        assert "EVIDENCE GAP" in out
+
+    def test_bare_ip_still_valid(self, capsys):
+        assert _run(["explain", "10.50.5.1"]) == EXIT_OK
+        assert "10.50.0.0/16" in capsys.readouterr().out
+
+    def test_host_bits_set_still_accepted(self, capsys):
+        # strict=False semantics are preserved: host bits are normalized,
+        # exactly as in 2.0.0.
+        assert _run(["gaps", "10.50.5.1/16"]) == EXIT_OK
+
+    def test_ipv6_cidr_still_valid(self, capsys):
+        assert _run(["explain", "2001:db8:a::/48"]) == EXIT_OK
+        out = capsys.readouterr().out
+        assert "2001:db8:a::/48" in out
+        assert "CURRENT_EVIDENCE" in out
+
+    def test_explain_unobserved_network_is_not_observed(self, capsys):
+        """Stage 9 DEFECT-001 regression at the CLI boundary: absence of
+        observation must never be promoted to CURRENT_EVIDENCE. Fails
+        against 2.0.0, which reported CURRENT_EVIDENCE here."""
+        assert _run(["explain", "192.168.99.0/24"]) == EXIT_OK
+        out = capsys.readouterr().out
+        assert "NOT_OBSERVED" in out
+        assert "CURRENT_EVIDENCE" not in out
+
+    def test_explain_unobserved_network_json_classification(self, capsys):
+        assert _run(["explain", "192.168.99.0/24", "--json"]) == EXIT_OK
+        payload = json.loads(capsys.readouterr().out)
+        assert payload["classification"] == "NOT_OBSERVED"
+        assert payload["reason"] == "Network not found in current discovery evidence."

{pivotcheck-2.0.0 → pivotcheck-2.0.2}/tests/test_operator_intelligence.py

@@ -63,3 +63,32 @@ def test_recommendations_are_deterministic_when_input_order_changes():
     first = DiscoverySnapshot("h", "o", networks=(DiscoveredNetwork("192.168.0.0/24", NetworkOrigin.CONNECTED, Confidence.HIGH), DiscoveredNetwork("172.16.0.0/24", NetworkOrigin.CONNECTED, Confidence.HIGH)))
     second = DiscoverySnapshot("h", "o", networks=tuple(reversed(first.networks)))
     assert recommend(first, report) == recommend(second, report)
+
+
+def test_explain_unobserved_network_is_not_reported_as_observed():
+    """Stage 9 regression: explain() on a network absent from the current
+    snapshot must be classified NOT_OBSERVED - never CURRENT_EVIDENCE."""
+    snapshot = DiscoverySnapshot("host", "OS", networks=(
+        DiscoveredNetwork("172.16.0.0/24", NetworkOrigin.CONNECTED, Confidence.HIGH, "eth0"),
+    ))
+    standalone = explain_network("10.9.9.0/24", snapshot)
+    assert standalone.classification == "NOT_OBSERVED"
+    assert "not found in current discovery evidence" in standalone.reason.lower()
+    assert standalone.origin is None and standalone.interface is None
+
+    with_report = explain_network(
+        "10.9.9.0/24", snapshot,
+        compare(perspective(BaselineNetwork("172.16.0.0/24", NetworkOrigin.CONNECTED, Confidence.HIGH)), perspective()),
+    )
+    assert with_report.classification == "NOT_OBSERVED"
+    assert "not found in current discovery evidence" in with_report.reason.lower()
+
+
+def test_explain_observed_network_still_current_evidence():
+    snapshot = DiscoverySnapshot("host", "OS", networks=(
+        DiscoveredNetwork("172.16.0.0/24", NetworkOrigin.CONNECTED, Confidence.HIGH, "eth0"),
+    ))
+    explanation = explain_network("172.16.0.0/24", snapshot)
+    assert explanation.classification == "CURRENT_EVIDENCE"
+    assert "observed in current discovery evidence" in explanation.reason.lower()
+    assert explanation.origin == "connected"