Add API and CLI option for offline (no TUF refresh) verification (#104)

* Add `offline` option to CLI and API

Signed-off-by: Facundo Tuesca <[email protected]>

* ci: run offline tests in offline environment

Signed-off-by: Facundo Tuesca <[email protected]>

* Fix offline test not working offline

Signed-off-by: Facundo Tuesca <[email protected]>

---------

Signed-off-by: Facundo Tuesca <[email protected]>

Author: facutuesca

.github/workflows/tests.yml

@@ -38,3 +38,25 @@ jobs:
 
       - name: test
         run: make test INSTALL_EXTRA=test
+
+  test-offline:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5
+        with:
+          python-version: 3.13
+          cache: "pip"
+          cache-dependency-path: pyproject.toml
+          allow-prereleases: true
+
+      - name: install firejail
+        run: sudo apt-get install -y firejail
+
+      - name: run tests offline
+        run: |
+          make dev INSTALL_EXTRA=test
+          firejail --noprofile --net=none --env=TEST_OFFLINE=1 make test-nocoverage

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- The `Attestation.verify(...)` API has been changed to accept an `offline`
+  parameter that, when True, disables TUF refreshes.
+- The CLI `verify` commands now also accept an `--offline` flag that disables
+  TUF refreshes. Additionally, when used with the `verify pypi` subcommand, the
+  `--offline` flag enforces that the distribution and provenance file arguments
+  must be local file paths.
+
 ## [0.0.22]
 
 ### Changed

Makefile

@@ -70,6 +70,11 @@ test tests: $(VENV)/pyvenv.cfg
 		pytest --cov=$(PY_IMPORT) $(T) $(TEST_ARGS) && \
 		python -m coverage report -m $(COV_ARGS)
 
+.PHONY: test-nocoverage
+test-nocoverage: $(VENV)/pyvenv.cfg
+	. $(VENV_BIN)/activate && \
+		pytest $(T) $(TEST_ARGS)
+
 .PHONY: doc
 doc: $(VENV)/pyvenv.cfg
 	. $(VENV_BIN)/activate && \

README.md

@@ -51,7 +51,6 @@ print(attestation.model_dump_json())
 # Verify an attestation against a Python artifact
 attestation_path = Path("test_package-0.0.1-py3-none-any.whl.attestation")
 attestation = Attestation.model_validate_json(attestation_path.read_bytes())
-verifier = Verifier.production()
 identity = policy.Identity(identity="[email protected]", issuer="https://accounts.google.com")
 attestation.verify(identity=identity, dist=dist)
 ```

src/pypi_attestations/_cli.py

@@ -125,6 +125,13 @@ def _parser() -> argparse.ArgumentParser:
         help="Use the staging environment",
     )
 
+    verify_attestation_command.add_argument(
+        "--offline",
+        action="store_true",
+        default=False,
+        help="Disable TUF refresh",
+    )
+
     verify_attestation_command.add_argument(
         "files",
         metavar="FILE",
@@ -157,6 +164,13 @@ def _parser() -> argparse.ArgumentParser:
         help="Use the staging environment",
     )
 
+    verify_pypi_command.add_argument(
+        "--offline",
+        action="store_true",
+        default=False,
+        help="Force use of local files and disable TUF refresh",
+    )
+
     verify_pypi_command.add_argument(
         "--provenance-file",
         type=Path,
@@ -239,7 +253,7 @@ def _download_file(url: str, dest: Path) -> None:
             _die(f"Error downloading file: {e}")
 
 
-def _get_distribution_from_arg(arg: str) -> Distribution:
+def _get_distribution_from_arg(arg: str, offline: bool) -> Distribution:
     """Parse the artifact argument for the `verify pypi` subcommand.
 
     The argument can be:
@@ -248,6 +262,8 @@ def _get_distribution_from_arg(arg: str) -> Distribution:
     - A path to a local file
     """
     if arg.startswith("pypi:") or arg.startswith("https://"):
+        if offline:
+            _die("The '--offline' option can only be used with local files")
         pypi_url = _get_direct_url_from_arg(arg)
         dist_filename = pypi_url.path.split("/")[-1]
         with TemporaryDirectory() as temp_dir:
@@ -497,7 +513,7 @@ def _verify_attestation(args: argparse.Namespace) -> None:
                 _die(f"Invalid Python package distribution: {e}")
 
             try:
-                attestation.verify(pol, dist, staging=args.staging)
+                attestation.verify(pol, dist, staging=args.staging, offline=args.offline)
             except VerificationError as verification_error:
                 _die(f"Verification failed for {file_path}: {verification_error}")
 
@@ -512,9 +528,11 @@ def _verify_pypi(args: argparse.Namespace) -> None:
     from PyPI if not provided), and against the repository URL passed by the user
     as a CLI argument.
     """
-    dist = _get_distribution_from_arg(args.distribution_file)
+    dist = _get_distribution_from_arg(args.distribution_file, offline=args.offline)
 
     if args.provenance_file is None:
+        if args.offline:
+            _die("The '--offline' option can only be used with local files")
         provenance = _get_provenance_from_pypi(dist)
     else:
         if not args.provenance_file.exists():
@@ -530,7 +548,7 @@ def _verify_pypi(args: argparse.Namespace) -> None:
             _check_repository_identity(expected_repository_url=args.repository, publisher=publisher)
             policy = publisher._as_policy()  # noqa: SLF001.
             for attestation in attestation_bundle.attestations:
-                attestation.verify(policy, dist, staging=args.staging)
+                attestation.verify(policy, dist, staging=args.staging, offline=args.offline)
     except VerificationError as verification_error:
         _die(f"Verification failed for {dist.name}: {verification_error}")
 

src/pypi_attestations/_impl.py

@@ -230,6 +230,7 @@ def verify(
         dist: Distribution,
         *,
         staging: bool = False,
+        offline: bool = False,
     ) -> tuple[str, Optional[dict[str, Any]]]:
         """Verify against an existing Python distribution.
 
@@ -241,6 +242,9 @@ def verify(
         `staging` parameter can be toggled to enable the staging verifier
         instead.
 
+        If `offline` is `True`, the verifier will not attempt to refresh the
+        TUF repository.
+
         On failure, raises an appropriate subclass of `AttestationError`.
         """
         # NOTE: Can't do `isinstance` with `Publisher` since it's
@@ -253,9 +257,9 @@ def verify(
             policy = identity
 
         if staging:
-            verifier = Verifier.staging()
+            verifier = Verifier.staging(offline=offline)
         else:
-            verifier = Verifier.production()
+            verifier = Verifier.production(offline=offline)
 
         bundle = self.to_bundle()
         try:

test/test_cli.py

@@ -23,9 +23,11 @@
 )
 from pypi_attestations._impl import Attestation, AttestationError, Distribution
 
-ONLINE_TESTS = "CI" in os.environ or "TEST_INTERACTIVE" in os.environ
-online = pytest.mark.skipif(not ONLINE_TESTS, reason="online tests not enabled")
+ONLINE_TESTS = (
+    "CI" in os.environ or "TEST_INTERACTIVE" in os.environ
+) and "TEST_OFFLINE" not in os.environ
 
+online = pytest.mark.skipif(not ONLINE_TESTS, reason="online tests not enabled")
 
 _HERE = Path(__file__).parent
 _ASSETS = _HERE / "assets"
@@ -216,6 +218,7 @@ def test_verify_attestation_command(caplog: pytest.LogCaptureFixture) -> None:
         [
             "verify",
             "attestation",
+            "--offline",
             "--identity",
             publish_attestation_identity,
             artifact_path.as_posix(),
@@ -233,6 +236,7 @@ def test_verify_attestation_command(caplog: pytest.LogCaptureFixture) -> None:
                 "verify",
                 "attestation",
                 "--staging",
+                "--offline",
                 "--identity",
                 publish_attestation_identity,
                 artifact_path.as_posix(),
@@ -256,6 +260,7 @@ def test_verify_attestation_invalid_attestation(caplog: pytest.LogCaptureFixture
                 [
                     "verify",
                     "attestation",
+                    "--offline",
                     "--identity",
                     publish_attestation_identity,
                     fake_package_name.as_posix(),
@@ -271,6 +276,7 @@ def test_verify_attestation_missing_artifact(caplog: pytest.LogCaptureFixture) -
             [
                 "verify",
                 "attestation",
+                "--offline",
                 "--identity",
                 publish_attestation_identity,
                 "not_a_file.txt",
@@ -288,6 +294,7 @@ def test_verify_attestation_missing_attestation(caplog: pytest.LogCaptureFixture
                 [
                     "verify",
                     "attestation",
+                    "--offline",
                     "--identity",
                     publish_attestation_identity,
                     f.name,
@@ -310,6 +317,7 @@ def test_verify_attestation_invalid_artifact(
             [
                 "verify",
                 "attestation",
+                "--offline",
                 "--identity",
                 publish_attestation_identity,
                 copied_artifact.as_posix(),
@@ -393,6 +401,7 @@ def test_verify_pypi_command_with_local_files(caplog: pytest.LogCaptureFixture)
         [
             "verify",
             "pypi",
+            "--offline",
             "--repository",
             "https://github.com/trailofbits/pypi-attestations",
             "--provenance-file",
@@ -403,6 +412,40 @@ def test_verify_pypi_command_with_local_files(caplog: pytest.LogCaptureFixture)
     assert f"OK: {pypi_sdist_filename}" in caplog.text
 
 
+def test_verify_pypi_command_offline_without_local_dist(caplog: pytest.LogCaptureFixture) -> None:
+    with pytest.raises(SystemExit):
+        run_main_with_command(
+            [
+                "verify",
+                "pypi",
+                "--offline",
+                "--repository",
+                "https://github.com/trailofbits/pypi-attestations",
+                "--provenance-file",
+                pypi_sdist_provenance_path.as_posix(),
+                pypi_sdist_url,
+            ]
+        )
+    assert "The '--offline' option can only be used with local files" in caplog.text
+
+
+def test_verify_pypi_command_offline_without_local_provenance(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    with pytest.raises(SystemExit):
+        run_main_with_command(
+            [
+                "verify",
+                "pypi",
+                "--offline",
+                "--repository",
+                "https://github.com/trailofbits/pypi-attestations",
+                pypi_sdist_path.as_posix(),
+            ]
+        )
+    assert "The '--offline' option can only be used with local files" in caplog.text
+
+
 @online
 def test_verify_pypi_command_env_fail(caplog: pytest.LogCaptureFixture) -> None:
     with pytest.raises(SystemExit):
@@ -558,7 +601,7 @@ def test_verify_pypi_error_getting_provenance(
     monkeypatch.setattr(
         pypi_attestations._cli,
         "_get_distribution_from_arg",
-        lambda arg: Distribution(name=pypi_wheel_filename, digest="a"),
+        lambda arg, offline: Distribution(name=pypi_wheel_filename, digest="a"),
     )
     response = requests.Response()
     response.status_code = status_code
@@ -622,7 +665,7 @@ def test_verify_pypi_error_validating_provenance(
     monkeypatch.setattr(
         pypi_attestations._cli,
         "_get_distribution_from_arg",
-        lambda arg: Distribution(name=pypi_wheel_filename, digest="a"),
+        lambda arg, offline: Distribution(name=pypi_wheel_filename, digest="a"),
     )
     response = stub(status_code=200, raise_for_status=lambda: None, text="not json")
     response.status_code = 200
@@ -714,6 +757,7 @@ def test_verify_pypi_command_local_nonexistent_artifact(caplog: pytest.LogCaptur
             [
                 "verify",
                 "pypi",
+                "--offline",
                 "--repository",
                 "https://github.com/trailofbits/pypi-attestations",
                 "--provenance-file",
@@ -730,6 +774,7 @@ def test_verify_pypi_command_local_nonexistent_provenance(caplog: pytest.LogCapt
             [
                 "verify",
                 "pypi",
+                "--offline",
                 "--repository",
                 "https://github.com/trailofbits/pypi-attestations",
                 "--provenance-file",
@@ -746,7 +791,7 @@ def test_verify_pypi_command_local_invalid_provenance(
     monkeypatch.setattr(
         pypi_attestations._cli,
         "_get_distribution_from_arg",
-        lambda arg: Distribution(name=pypi_sdist_filename, digest="a"),
+        lambda arg, offline: Distribution(name=pypi_sdist_filename, digest="a"),
     )
 
     with tempfile.NamedTemporaryFile(suffix=".provenance") as f:
@@ -757,6 +802,7 @@ def test_verify_pypi_command_local_invalid_provenance(
                 [
                     "verify",
                     "pypi",
+                    "--offline",
                     "--repository",
                     "https://github.com/trailofbits/pypi-attestations",
                     "--provenance-file",