fix(icu): update documentation and fixes

This allows to be sure that the image name is verified by a known public
key, rather than relying on an input by the user, which can lead to issues.

dangerzone/container_utils.py

@@ -3,7 +3,7 @@ import logging
 import platform
 import shutil
 import subprocess
-from typing import List, Tuple
+from typing import List, Optional, Tuple
 
 from . import errors
 from .util import get_resource_path, get_subprocess_startupinfo
@@ -180,7 +180,6 @@ def get_image_id_by_digest(digest: str) -> str:
     process = subprocess.run(
         cmd, startupinfo=get_subprocess_startupinfo(), check=True, capture_output=True
     )
-    breakpoint()
     # In case we have multiple lines, we only want the first one.
     return process.stdout.decode().strip().split("\n")[0]
 
@@ -193,10 +192,14 @@ def container_pull(image: str) -> bool:
     return process.returncode == 0
 
 
-def get_local_image_hash(image: str) -> str:
+def get_local_image_hash(image: str) -> Optional[str]:
     """
     Returns a image hash from a local image name
     """
     cmd = [get_runtime_name(), "image", "inspect", image, "-f", "{{.Digest}}"]
-    result = subprocess.run(cmd, capture_output=True, check=True)
+    try:
-    return result.stdout.strip().decode().strip("sha256:")
+        result = subprocess.run(cmd, capture_output=True, check=True)
+    except subprocess.CalledProcessError as e:
+        return None
+    else:
+        return result.stdout.strip().decode().strip("sha256:")

dangerzone/updater/attestations.py

@@ -1,17 +1,17 @@
 import subprocess
 from tempfile import NamedTemporaryFile
 
-from . import utils
+from . import cosign
 
 
-def verify_attestation(
+def verify(
     manifest: bytes, attestation_bundle: bytes, image_tag: str, expected_repo: str
 ) -> bool:
     """
     Look up the image attestation to see if the image has been built
     on Github runners, and from a given repository.
     """
-    utils.ensure_cosign()
+    cosign.ensure_installed()
 
     # Put the value in files and verify with cosign
     with (

dangerzone/updater/cli.py

@@ -5,16 +5,10 @@ import logging
 import click
 
 from ..util import get_resource_path
-from . import errors, log, registry
+from . import attestations, errors, log, registry, signatures
-from .attestations import verify_attestation
-from .signatures import (
-    upgrade_container_image,
-    upgrade_container_image_airgapped,
-    verify_offline_image_signature,
-)
 
 DEFAULT_REPOSITORY = "freedomofpress/dangerzone"
-DEFAULT_IMAGE_NAME = "ghcr.io/freedomofpress/dangerzone"
+DEFAULT_IMAGE_NAME = "ghcr.io/freedomofpress/dangerzone/dangerzone"
 PUBKEY_DEFAULT_LOCATION = get_resource_path("freedomofpress-dangerzone-pub.key")
 
 
@@ -30,14 +24,18 @@ def main(debug: bool) -> None:
 
 
 @main.command()
-@click.argument("image")
+@click.argument("image", default=DEFAULT_IMAGE_NAME)
 @click.option("--pubkey", default=PUBKEY_DEFAULT_LOCATION)
 def upgrade(image: str, pubkey: str) -> None:
     """Upgrade the image to the latest signed version."""
     manifest_hash = registry.get_manifest_hash(image)
     try:
-        is_upgraded = upgrade_container_image(image, manifest_hash, pubkey)
+        is_upgraded = signatures.upgrade_container_image(image, manifest_hash, pubkey)
-        click.echo(f"✅ The local image {image} has been upgraded")
+        if is_upgraded:
+            click.echo(f"✅ The local image {image} has been upgraded")
+            click.echo(f"✅ The image has been signed with {pubkey}")
+            click.echo(f"✅ Signatures has been verified and stored locally")
+
     except errors.ImageAlreadyUpToDate as e:
         click.echo(f"✅ {e}")
         raise click.Abort()
@@ -46,12 +44,15 @@ def upgrade(image: str, pubkey: str) -> None:
 @main.command()
 @click.argument("image_filename")
 @click.option("--pubkey", default=PUBKEY_DEFAULT_LOCATION)
-@click.option("--image-name", default=DEFAULT_IMAGE_NAME)
+def load_archive(image_filename: str, pubkey: str) -> None:
-def upgrade_airgapped(image_filename: str, pubkey: str, image_name: str) -> None:
+    """Upgrade the local image to the one in the archive."""
-    """Upgrade the image to the latest signed version."""
     try:
-        upgrade_container_image_airgapped(image_filename, pubkey, image_name)
+        loaded_image = signatures.upgrade_container_image_airgapped(
-        click.echo(f"✅ Installed image {image_filename} on the system")
+            image_filename, pubkey
+        )
+        click.echo(
+            f"✅ Installed image {image_filename} on the system as {loaded_image}"
+        )
     except errors.ImageAlreadyUpToDate as e:
         click.echo(f"✅ {e}")
         raise click.Abort()
@@ -59,13 +60,22 @@ def upgrade_airgapped(image_filename: str, pubkey: str, image_name: str) -> None
 
 @main.command()
 @click.argument("image")
+@click.option("--output", default="dangerzone-airgapped.tar")
+def prepare_archive(image: str, output: str) -> None:
+    """Prepare an archive to upgrade the dangerzone image on an airgapped environment."""
+    signatures.prepare_airgapped_archive(image, output)
+    click.echo(f"✅ Archive {output} created")
+
+
+@main.command()
+@click.argument("image", default=DEFAULT_IMAGE_NAME)
 @click.option("--pubkey", default=PUBKEY_DEFAULT_LOCATION)
-def verify_offline(image: str, pubkey: str) -> None:
+def verify_local(image: str, pubkey: str) -> None:
     """
     Verify the local image signature against a public key and the stored signatures.
     """
     # XXX remove a potentiel :tag
-    if verify_offline_image_signature(image, pubkey):
+    if signatures.verify_local_image(image, pubkey):
         click.echo(
             (
                 f"Verifying the local image:\n\n"
@@ -79,6 +89,7 @@ def verify_offline(image: str, pubkey: str) -> None:
 @main.command()
 @click.argument("image")
 def list_remote_tags(image: str) -> None:
+    """List the tags available for a given image."""
     click.echo(f"Existing tags for {image}")
     for tag in registry.list_tags(image):
         click.echo(tag)
@@ -87,6 +98,7 @@ def list_remote_tags(image: str) -> None:
 @main.command()
 @click.argument("image")
 def get_manifest(image: str) -> None:
+    """Retrieves a remove manifest for a given image and displays it."""
     click.echo(registry.get_manifest(image))
 
 
@@ -109,7 +121,7 @@ def attest_provenance(image: str, repository: str) -> None:
     parsed = registry.parse_image_location(image)
     manifest, bundle = registry.get_attestation(image)
 
-    verified = verify_attestation(manifest, bundle, parsed.tag, repository)
+    verified = attestations.verify(manifest, bundle, parsed.tag, repository)
     if verified:
         click.echo(
             f"🎉 The image available at `{parsed.full_name}` has been built by Github Runners from the `{repository}` repository"

dangerzone/updater/cosign.py

@@ -0,0 +1,32 @@
+import subprocess
+
+from . import errors, log
+
+
+def ensure_installed() -> None:
+    try:
+        subprocess.run(["cosign", "version"], capture_output=True, check=True)
+    except subprocess.CalledProcessError:
+        raise errors.CosignNotInstalledError()
+
+
+def verify_local_image(oci_image_folder: str, pubkey: str) -> bool:
+    """Verify the given path against the given public key"""
+
+    ensure_installed()
+    cmd = [
+        "cosign",
+        "verify",
+        "--key",
+        pubkey,
+        "--offline",
+        "--local-image",
+        oci_image_folder,
+    ]
+    log.debug(" ".join(cmd))
+    result = subprocess.run(cmd, capture_output=True)
+    if result.returncode == 0:
+        log.info("Signature verified")
+        return True
+    log.info("Failed to verify signature", result.stderr)
+    return False

dangerzone/updater/errors.py

@@ -6,6 +6,10 @@ class ImageAlreadyUpToDate(UpdaterError):
     pass
 
 
+class ImageNotFound(UpdaterError):
+    pass
+
+
 class SignatureError(UpdaterError):
     pass
 
@@ -14,6 +18,10 @@ class RegistryError(UpdaterError):
     pass
 
 
+class AirgappedImageDownloadError(UpdaterError):
+    pass
+
+
 class NoRemoteSignatures(SignatureError):
     pass
 

dangerzone/updater/signatures.py

@@ -11,7 +11,7 @@ from tempfile import NamedTemporaryFile, TemporaryDirectory
 from typing import Dict, List, Optional, Tuple
 
 from .. import container_utils as runtime
-from . import errors, log, registry, utils
+from . import cosign, errors, log, registry
 
 try:
     import platformdirs
@@ -55,39 +55,22 @@ def signature_to_bundle(sig: Dict) -> Dict:
     }
 
 
-def cosign_verify_local_image(oci_image_folder: str, pubkey: str) -> bool:
-    """Verify the given path against the given public key"""
-
-    utils.ensure_cosign()
-    cmd = [
-        "cosign",
-        "verify",
-        "--key",
-        pubkey,
-        "--offline",
-        "--local-image",
-        oci_image_folder,
-    ]
-    log.debug(" ".join(cmd))
-    result = subprocess.run(cmd, capture_output=True)
-    if result.returncode == 0:
-        log.debug("Signature verified")
-        return True
-    log.debug("Failed to verify signature", result.stderr)
-    return False
-
-
 def verify_signature(signature: dict, image_hash: str, pubkey: str) -> bool:
     """Verify a signature against a given public key"""
     # XXX - Also verfy the identity/docker-reference field against the expected value
     # e.g. ghcr.io/freedomofpress/dangerzone/dangerzone
 
-    utils.ensure_cosign()
+    cosign.ensure_installed()
     signature_bundle = signature_to_bundle(signature)
 
     payload_bytes = b64decode(signature_bundle["Payload"])
-    if json.loads(payload_bytes)["critical"]["type"] != f"sha256:{image_hash}":
+    payload_hash = json.loads(payload_bytes)["critical"]["image"][
-        raise errors.SignatureMismatch("The signature does not match the image hash")
+        "docker-manifest-digest"
+    ]
+    if payload_hash != f"sha256:{image_hash}":
+        raise errors.SignatureMismatch(
+            f"The signature does not match the image hash ({payload_hash}, {image_hash})"
+        )
 
     with (
         NamedTemporaryFile(mode="w") as signature_file,
@@ -160,15 +143,15 @@ def _get_blob(tmpdir: str, hash: str) -> Path:
     return Path(tmpdir) / "blobs" / "sha256" / hash.replace("sha256:", "")
 
 
-def upgrade_container_image_airgapped(
+def upgrade_container_image_airgapped(container_tar: str, pubkey: str) -> str:
-    container_tar: str, pubkey: str, image_name: str
-) -> bool:
     """
     Verify the given archive against its self-contained signatures, then
     upgrade the image and retag it to the expected tag.
 
     Right now, the archive is extracted and reconstructed, requiring some space
     on the filesystem.
+
+    :return: The loaded image name
     """
 
     # XXX Use a memory buffer instead of the filesystem
@@ -186,9 +169,7 @@ def upgrade_container_image_airgapped(
         with tarfile.open(container_tar, "r") as archive:
             archive.extractall(tmpdir)
 
-        # XXX Check if the contained signatures match the given ones?
+        if not cosign.verify_local_image(tmpdir, pubkey):
-        # Or maybe store both signatures?
-        if not cosign_verify_local_image(tmpdir, pubkey):
             raise errors.SignatureVerificationError()
 
         # Remove the signatures from the archive.
@@ -204,7 +185,8 @@ def upgrade_container_image_airgapped(
         ]
 
         with open(signature_filename, "rb") as f:
-            signatures = convert_oci_images_signatures(json.load(f), tmpdir)
+            image_name, signatures = convert_oci_images_signatures(json.load(f), tmpdir)
+        log.info(f"Found image name: {image_name}")
 
         image_digest = index_json["manifests"][0].get("digest").replace("sha256:", "")
 
@@ -223,12 +205,12 @@ def upgrade_container_image_airgapped(
             runtime.tag_image_by_digest(image_digest, image_name)
 
     store_signatures(signatures, image_digest, pubkey)
-    return True
+    return image_name
 
 
 def convert_oci_images_signatures(
     signatures_manifest: List[Dict], tmpdir: str
-) -> List[Dict]:
+) -> (str, List[Dict]):
     def _to_cosign_signature(layer: Dict) -> Dict:
         signature = layer["annotations"]["dev.cosignproject.cosign/signature"]
         bundle = json.loads(layer["annotations"]["dev.sigstore.cosign/bundle"])
@@ -243,11 +225,19 @@ def convert_oci_images_signatures(
             "Payload": payload_b64,
             "Cert": None,
             "Chain": None,
-            "rekorBundle": bundle,
+            "Bundle": bundle,
             "RFC3161Timestamp": None,
         }
 
-    return [_to_cosign_signature(layer) for layer in signatures_manifest["layers"]]
+    layers = signatures_manifest["layers"]
+    signatures = [_to_cosign_signature(layer) for layer in layers]
+
+    payload_location = _get_blob(tmpdir, layers[0]["digest"])
+    with open(payload_location, "r") as f:
+        payload = json.load(f)
+        image_name = payload["critical"]["identity"]["docker-reference"]
+
+    return image_name, signatures
 
 
 def get_file_hash(file: Optional[str] = None, content: Optional[bytes] = None) -> str:
@@ -315,18 +305,22 @@ def store_signatures(signatures: list[Dict], image_hash: str, pubkey: str) -> No
     pubkey_signatures.mkdir(exist_ok=True)
 
     with open(pubkey_signatures / f"{image_hash}.json", "w") as f:
-        log.debug(
+        log.info(
             f"Storing signatures for {image_hash} in {pubkey_signatures}/{image_hash}.json"
         )
         json.dump(signatures, f)
 
 
-def verify_offline_image_signature(image: str, pubkey: str) -> bool:
+def verify_local_image(image: str, pubkey: str) -> bool:
     """
     Verifies that a local image has a valid signature
     """
     log.info(f"Verifying local image {image} against pubkey {pubkey}")
-    image_hash = runtime.get_local_image_hash(image)
+    try:
+        image_hash = runtime.get_local_image_hash(image)
+    except subprocess.CalledProcessError:
+        raise errors.ImageNotFound(f"The image {image} does not exist locally")
+
     log.debug(f"Image hash: {image_hash}")
     signatures = load_signatures(image_hash, pubkey)
     if len(signatures) < 1:
@@ -341,7 +335,7 @@ def verify_offline_image_signature(image: str, pubkey: str) -> bool:
 
 def get_remote_signatures(image: str, hash: str) -> List[Dict]:
     """Retrieve the signatures from the registry, via `cosign download`."""
-    utils.ensure_cosign()
+    cosign.ensure_installed()
 
     process = subprocess.run(
         ["cosign", "download", "signature", f"{image}@sha256:{hash}"],
@@ -356,3 +350,28 @@ def get_remote_signatures(image: str, hash: str) -> List[Dict]:
     if len(signatures) < 1:
         raise errors.NoRemoteSignatures("No signatures found for the image")
     return signatures
+
+
+def prepare_airgapped_archive(image_name, destination):
+    if "@sha256:" not in image_name:
+        raise errors.AirgappedImageDownloadError(
+            "The image name must include a digest, e.g. ghcr.io/freedomofpress/dangerzone/dangerzone@sha256:123456"
+        )
+
+    cosign.ensure_installed()
+    # Get the image from the registry
+
+    with TemporaryDirectory() as tmpdir:
+        msg = f"Downloading image {image_name}. \nIt might take a while."
+        log.info(msg)
+
+        process = subprocess.run(
+            ["cosign", "save", image_name, "--dir", tmpdir],
+            capture_output=True,
+            check=True,
+        )
+        if process.returncode != 0:
+            raise errors.AirgappedImageDownloadError()
+
+        with tarfile.open(destination, "w") as archive:
+            archive.add(tmpdir, arcname=".")

dangerzone/updater/utils.py

@@ -1,10 +0,0 @@
-import subprocess
-
-from . import errors
-
-
-def ensure_cosign() -> None:
-    try:
-        subprocess.run(["cosign", "version"], capture_output=True, check=True)
-    except subprocess.CalledProcessError:
-        raise errors.CosignNotInstalledError()

docs/developer/independent-container-updates.md

@@ -1,19 +1,19 @@
 # Independent Container Updates
 
 Since version 0.9.0, Dangerzone is able to ship container images independently
-from issuing a new release of the software.
+from releases.
 
-This is useful as images need to be kept updated with the latest security fixes.
+One of the main benefits of doing so is to lower the time needed to patch security issues inside the containers.
 
-## Nightly images and attestations
+## Checking attestations
 
-Each night, new images are built and pushed to our container registry, alongside
+Each night, new images are built and pushed to the container registry, alongside
 with a provenance attestation, enabling anybody to ensure that the image has
 been originally built by Github CI runners, from a defined source repository (in our case `freedomofpress/dangerzone`).
 
 To verify the attestations against our expectations, use the following command:
 ```bash
-poetry run ./dev_scripts/registry.py attest ghcr.io/freedomofpress/dangerzone/dangerzone:latest --repo freedomofpress/dangerzone
+dangerzone-image attest-provenance ghcr.io/freedomofpress/dangerzone/dangerzone --repository freedomofpress/dangerzone
 ```
 
 In case of sucess, it will report back:
@@ -21,3 +21,36 @@ In case of sucess, it will report back:
 ```
 🎉 The image available at `ghcr.io/freedomofpress/dangerzone/dangerzone:latest` has been built by Github runners from the `freedomofpress/dangerzone` repository.
 ```
+
+## Install updates
+
+To check if a new container image has been released, and update your local installation with it, you can use the following commands:
+
+```bash
+./dev_scripts/dangerzone-image --debug upgrade ghcr.io/almet/dangerzone/dangerzone
+```
+
+## Verify local
+
+You can verify that the image you have locally matches the stored signatures, and that these have been signed with a trusted public key:
+
+```bash
+dangerzone-image verify-local ghcr.io/almet/dangerzone/dangerzone
+```
+
+## Air-gapped environments
+
+In order to make updates on an air-gapped environment, you will need to prepare an archive for the air-gapped environment. This archive will contain all the needed material to validate that the new container image has been signed and is valid.
+
+On the machine on which you prepare the packages:
+
+```bash
+dangerzone-image prepare-archive --output dz-fa94872.tar ghcr.io/almet/dangerzone/dangerzone@sha256:fa948726aac29a6ac49f01ec8fbbac18522b35b2491fdf716236a0b3502a2ca7
+```
+
+On the airgapped machine, copy the file and run the following command:
+
+```bash
+dangerzone-image load-archive dz-fa94872.tar
+```
+