manifesto-cloudsmith 1.0.0__tar.gz

manifesto_cloudsmith-1.0.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: manifesto-cloudsmith
+Version: 1.0.0
+Summary: Inspect, analyze, and manage Docker images in Cloudsmith repositories — multi-arch support, vulnerability scanning, and bulk cleanup.
+Author-email: Colin Moynes <colinmoynes@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/colinmoynes/Manifesto
+Project-URL: Repository, https://github.com/colinmoynes/Manifesto
+Project-URL: Issues, https://github.com/colinmoynes/Manifesto/issues
+Keywords: docker,cloudsmith,container,manifest,registry
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Software Distribution
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: rich>=10.0.0
+Requires-Dist: rich-argparse>=1.0.0
+
+# Manifesto
+
+<div align="center">
+<img src="assets/manifesto-logo.png">
+
+
+**Analyze your Cloudsmith repositories with a hierarchical view of your Docker images, including 
+manifest/lists (tags), digests, platform support, Cloudsmith sync status, and download statistics.**
+
+
+</div>
+
+> [!CAUTION]
+> This project is an independent, community-developed tool and is **not** affiliated with, endorsed by, or supported by Cloudsmith Ltd. It is provided "as is", without warranty of any kind. Cloudsmith Ltd. accepts no responsibility or liability for any loss, damage, or issues arising from the use of this tool. Use at your own risk.
+
+
+This Python script audits for Docker images stored in your Cloudsmith repositories. It interacts with both the Cloudsmith API and Docker Manifest V2 endpoints to provide a detailed analysis of your images.
+
+Here is a summary of its capabilities:
+
+1. **Visualization & Hierarchy**
+    - **Rich Tables:** Uses the `rich` library to render formatted, colored terminal tables.
+    - **Multi-Arch & Single Images:** Visually groups architecture-specific images under their parent Manifest List tag, and automatically detects standalone single-architecture images.
+    - **Details:** Displays the Tag, Type, Platform, Status, Download Counts, and SHA256 Digests.
+    - **Export Options:** Supports exporting analysis data to JSON or CSV for integration with other tools.
+    - **Multi-Arch status:** Aggregates child image quarantine states to determine parent manifest status.
+2. **Inspection Modes**
+    - **Single Image:** Can inspect a specific image repository (e.g., `my-org/my-repo/my-image`).
+    - **Full Catalog:** If no image name is provided, it automatically fetches the catalog and scans every image in the repository.
+    - **Detailed View:** The `--detailed` flag expands the output to show every individual child digest and its specific download count.
+    - **Summary View:** The `--summary` flag shows a compact one-line-per-image overview with tag counts, architecture breakdown, total downloads, and optional vulnerability totals.
+    - **Manifest Inspect:** The `--inspect` flag fetches and displays the raw Docker V2 manifest for a given tag or digest reference.
+    - **Filtering:** The `--filter` flag accepts Cloudsmith's package query syntax (`tag:`, `uploaded:`, `downloads:`, etc.) to narrow the scan.
+3. **Maintenance & Cleanup**
+    - **Untagged Detection:** The `--untagged` flag scans for "orphaned" images or manifest lists that exist but have no version tags.
+    - **Granular Deletion:** Supports deleting specific tags (`--delete-tag`), cleaning up untagged items (`--untagged-delete`), or wiping all detected images (`--delete-all`).
+4. **Data Aggregation**
+    - It combines data from two sources:
+        - **Docker Manifests:** To determine architecture/OS platforms and digest relationships.
+        - **Cloudsmith API:** To retrieve processing status (Synced, Failed, In Progress) and download statistics.
+    - For multi-arch tags, download counts are aggregated across the manifest list and its per-architecture children.
+5. **Security & Vulnerability Scanning**
+    - **CVE Summary:** The `--vulnerabilities` flag queries Cloudsmith's vulnerability scan results for each image, displaying scan status and counts by severity (Critical, High, Medium, Low).
+    - **Multi-Arch Rollup:** For manifest lists, vulnerability counts are rolled up from child images (using max-per-severity to avoid double-counting shared CVEs).
+6. **Cosign Artifact Handling**
+    - **Hidden by default:** Cosign signature, attestation, and SBOM tags (e.g. `sha256-<digest>.sig`) are filtered from the output so they don't pollute your tag list.
+    - **Opt-in:** Pass `--show-signatures` to include them, where they are labelled with their artifact type (`signature` / `attestation` / `sbom`).
+
+#### Query repository for images.
+<img src="assets/simple.gif">
+
+#### Query for detailed results. 
+<img src="assets/detailed.gif">
+
+#### Inspect Docker manifest. 
+<img src="assets/inspect.gif">
+
+
+## Installation
+
+**From PyPI:**
+```bash
+pip install manifesto-cloudsmith
+```
+
+**From source:**
+```bash
+git clone https://github.com/your-org/manifesto.git
+cd manifesto
+pip install .
+```
+
+Once installed, the `manifesto` command is available directly:
+```bash
+manifesto my-org my-repo
+```
+
+## Authentication
+
+Manifesto resolves credentials in the following order — the first match wins:
+
+**1. Environment variable** — highest priority, recommended for CI/CD:
+```bash
+export CLOUDSMITH_API_KEY=<your-api-key>
+```
+
+**2. Cloudsmith CLI login** — if you have the [Cloudsmith CLI](https://docs.cloudsmith.com/developer-tools/cli) installed and have run `cloudsmith login`, Manifesto will automatically read credentials from the CLI's `credentials.ini` file:
+```bash
+cloudsmith login
+```
+
+If no credentials are found, Manifesto will exit with an error indicating which options are available.
+
+## Prerequisites
+
+1. **Multi Arch Deletions**
+   To ensure that multi-arch images are fully deleted including child digests, ensure that you have the feature flag `Docker Manifest List Cascading` enabled for your Cloudsmith account.  
+   This feature implements cascading deletions whenever the parent manifest/list is deleted. Please reach out to [Cloudsmith Support](https://help.cloudsmith.io/docs/contact-us) for further assistance with enabling this.
+   
+
+## How to use
+
+1. **Basic Usage**
+   Run the script targeting your Organization and Repository.
+
+   - Scan a specific image:
+     ```bash
+     manifesto my-org my-repo my-image
+     ```
+
+   - Scan ALL images in the repository:
+     (Omit the image name)
+
+2. **Advanced Flags**
+   **Inspection**
+   | Flag                  | Description                                                  |
+   |-----------------------|--------------------------------------------------------------|
+   | `--detailed`         | Shows child digests for multi-arch images. |
+   | `--untagged`         | Show untagged manifest lists and orphaned images (untagged and unreferenced). |
+   | `--vulnerabilities`  | Show vulnerability scan status and CVE severity summary (Critical/High/Medium/Low). |
+   | `--filter QUERY`     | Query using Cloudsmith's package syntax (e.g. `tag:latest`, `uploaded:<'30 days ago'`, `downloads:>0`). |
+   | `--show-signatures`  | Include cosign signature/attestation/SBOM artifact tags (hidden by default). |
+   | `--summary`          | One-line-per-image summary with tag counts, downloads, and vulnerability totals. |
+   | `--inspect REF`      | Fetch and display the raw Docker V2 manifest for a tag or digest. |
+
+   **Deletion**
+   | Flag                  | Description                                                  |
+   |-----------------------|--------------------------------------------------------------|
+   | `--delete-tag TAG`   | Deletes an image via tag.                 |
+   | `--delete-all`       | Wipes all images and manifest lists detected.   |
+   | `--untagged-delete`  | Deletes any untagged/orphaned images found.                  |
+   | `--force`            | Force deletion without interactive prompt. Helpful for programmatic workflows.   |
+
+   **Output**
+   | Flag                  | Description                                                  |
+   |-----------------------|--------------------------------------------------------------|
+   | `--output FORMAT`    | Output format: `table` (default), `json`, or `csv`.   |
+   | `--debug-log`        | Enable verbose debug logging to `manifesto.log`. |
+   | `--version`          | Print the version number and exit. |
+
+3. **Examples**
+   - Scan all images in a repository:
+     ```bash
+     manifesto my-org my-repo
+     ```
+
+   - Get a summary of all tags for a specific image:
+     ```bash
+     manifesto my-org my-repo my-image
+     ```
+
+   - See full breakdown (platforms & digests) for all images:
+     ```bash
+     manifesto my-org my-repo --detailed
+     ```
+
+   - Show vulnerability scan results:
+     ```bash
+     manifesto my-org my-repo my-image --vulnerabilities
+     ```
+
+   - Get untagged/orphaned images:
+     ```bash
+     manifesto my-org my-repo my-image --untagged
+     ```
+
+   - Filter by tag:
+     ```bash
+     manifesto my-org my-repo my-image --filter "tag:latest"
+     ```
+
+   - Filter by upload date and download count:
+     ```bash
+     manifesto my-org my-repo --filter "uploaded:<'30 days ago' AND downloads:>0"
+     ```
+
+   - Include cosign signature/SBOM artifacts in the output:
+     ```bash
+     manifesto my-org my-repo my-image --show-signatures
+     ```
+
+   - Quick summary across all images:
+     ```bash
+     manifesto my-org my-repo --summary
+     ```
+
+   - Inspect the raw manifest for a tag:
+     ```bash
+     manifesto my-org my-repo my-image --inspect latest
+     ```
+
+   - Export results to JSON:
+     ```bash
+     manifesto my-org my-repo --output json
+     ```
+
+   - Export results to CSV:
+     ```bash
+     manifesto my-org my-repo --output csv > report.csv
+     ```
+
+   - Delete untagged/orphaned images:
+     ```bash
+     manifesto my-org my-repo my-image --untagged-delete
+     ```
+
+   - Delete a specific tag:
+     ```bash
+     manifesto my-org my-repo my-image --delete-tag tag
+     ```
+
+   - Wipe all detected images (use with caution!):
+     ```bash
+     manifesto my-org my-repo --delete-all
+     ```
+
+
+
+
+
+
+

manifesto_cloudsmith-1.0.0/README.md

@@ -0,0 +1,222 @@
+# Manifesto
+
+<div align="center">
+<img src="assets/manifesto-logo.png">
+
+
+**Analyze your Cloudsmith repositories with a hierarchical view of your Docker images, including 
+manifest/lists (tags), digests, platform support, Cloudsmith sync status, and download statistics.**
+
+
+</div>
+
+> [!CAUTION]
+> This project is an independent, community-developed tool and is **not** affiliated with, endorsed by, or supported by Cloudsmith Ltd. It is provided "as is", without warranty of any kind. Cloudsmith Ltd. accepts no responsibility or liability for any loss, damage, or issues arising from the use of this tool. Use at your own risk.
+
+
+This Python script audits for Docker images stored in your Cloudsmith repositories. It interacts with both the Cloudsmith API and Docker Manifest V2 endpoints to provide a detailed analysis of your images.
+
+Here is a summary of its capabilities:
+
+1. **Visualization & Hierarchy**
+    - **Rich Tables:** Uses the `rich` library to render formatted, colored terminal tables.
+    - **Multi-Arch & Single Images:** Visually groups architecture-specific images under their parent Manifest List tag, and automatically detects standalone single-architecture images.
+    - **Details:** Displays the Tag, Type, Platform, Status, Download Counts, and SHA256 Digests.
+    - **Export Options:** Supports exporting analysis data to JSON or CSV for integration with other tools.
+    - **Multi-Arch status:** Aggregates child image quarantine states to determine parent manifest status.
+2. **Inspection Modes**
+    - **Single Image:** Can inspect a specific image repository (e.g., `my-org/my-repo/my-image`).
+    - **Full Catalog:** If no image name is provided, it automatically fetches the catalog and scans every image in the repository.
+    - **Detailed View:** The `--detailed` flag expands the output to show every individual child digest and its specific download count.
+    - **Summary View:** The `--summary` flag shows a compact one-line-per-image overview with tag counts, architecture breakdown, total downloads, and optional vulnerability totals.
+    - **Manifest Inspect:** The `--inspect` flag fetches and displays the raw Docker V2 manifest for a given tag or digest reference.
+    - **Filtering:** The `--filter` flag accepts Cloudsmith's package query syntax (`tag:`, `uploaded:`, `downloads:`, etc.) to narrow the scan.
+3. **Maintenance & Cleanup**
+    - **Untagged Detection:** The `--untagged` flag scans for "orphaned" images or manifest lists that exist but have no version tags.
+    - **Granular Deletion:** Supports deleting specific tags (`--delete-tag`), cleaning up untagged items (`--untagged-delete`), or wiping all detected images (`--delete-all`).
+4. **Data Aggregation**
+    - It combines data from two sources:
+        - **Docker Manifests:** To determine architecture/OS platforms and digest relationships.
+        - **Cloudsmith API:** To retrieve processing status (Synced, Failed, In Progress) and download statistics.
+    - For multi-arch tags, download counts are aggregated across the manifest list and its per-architecture children.
+5. **Security & Vulnerability Scanning**
+    - **CVE Summary:** The `--vulnerabilities` flag queries Cloudsmith's vulnerability scan results for each image, displaying scan status and counts by severity (Critical, High, Medium, Low).
+    - **Multi-Arch Rollup:** For manifest lists, vulnerability counts are rolled up from child images (using max-per-severity to avoid double-counting shared CVEs).
+6. **Cosign Artifact Handling**
+    - **Hidden by default:** Cosign signature, attestation, and SBOM tags (e.g. `sha256-<digest>.sig`) are filtered from the output so they don't pollute your tag list.
+    - **Opt-in:** Pass `--show-signatures` to include them, where they are labelled with their artifact type (`signature` / `attestation` / `sbom`).
+
+#### Query repository for images.
+<img src="assets/simple.gif">
+
+#### Query for detailed results. 
+<img src="assets/detailed.gif">
+
+#### Inspect Docker manifest. 
+<img src="assets/inspect.gif">
+
+
+## Installation
+
+**From PyPI:**
+```bash
+pip install manifesto-cloudsmith
+```
+
+**From source:**
+```bash
+git clone https://github.com/your-org/manifesto.git
+cd manifesto
+pip install .
+```
+
+Once installed, the `manifesto` command is available directly:
+```bash
+manifesto my-org my-repo
+```
+
+## Authentication
+
+Manifesto resolves credentials in the following order — the first match wins:
+
+**1. Environment variable** — highest priority, recommended for CI/CD:
+```bash
+export CLOUDSMITH_API_KEY=<your-api-key>
+```
+
+**2. Cloudsmith CLI login** — if you have the [Cloudsmith CLI](https://docs.cloudsmith.com/developer-tools/cli) installed and have run `cloudsmith login`, Manifesto will automatically read credentials from the CLI's `credentials.ini` file:
+```bash
+cloudsmith login
+```
+
+If no credentials are found, Manifesto will exit with an error indicating which options are available.
+
+## Prerequisites
+
+1. **Multi Arch Deletions**
+   To ensure that multi-arch images are fully deleted including child digests, ensure that you have the feature flag `Docker Manifest List Cascading` enabled for your Cloudsmith account.  
+   This feature implements cascading deletions whenever the parent manifest/list is deleted. Please reach out to [Cloudsmith Support](https://help.cloudsmith.io/docs/contact-us) for further assistance with enabling this.
+   
+
+## How to use
+
+1. **Basic Usage**
+   Run the script targeting your Organization and Repository.
+
+   - Scan a specific image:
+     ```bash
+     manifesto my-org my-repo my-image
+     ```
+
+   - Scan ALL images in the repository:
+     (Omit the image name)
+
+2. **Advanced Flags**
+   **Inspection**
+   | Flag                  | Description                                                  |
+   |-----------------------|--------------------------------------------------------------|
+   | `--detailed`         | Shows child digests for multi-arch images. |
+   | `--untagged`         | Show untagged manifest lists and orphaned images (untagged and unreferenced). |
+   | `--vulnerabilities`  | Show vulnerability scan status and CVE severity summary (Critical/High/Medium/Low). |
+   | `--filter QUERY`     | Query using Cloudsmith's package syntax (e.g. `tag:latest`, `uploaded:<'30 days ago'`, `downloads:>0`). |
+   | `--show-signatures`  | Include cosign signature/attestation/SBOM artifact tags (hidden by default). |
+   | `--summary`          | One-line-per-image summary with tag counts, downloads, and vulnerability totals. |
+   | `--inspect REF`      | Fetch and display the raw Docker V2 manifest for a tag or digest. |
+
+   **Deletion**
+   | Flag                  | Description                                                  |
+   |-----------------------|--------------------------------------------------------------|
+   | `--delete-tag TAG`   | Deletes an image via tag.                 |
+   | `--delete-all`       | Wipes all images and manifest lists detected.   |
+   | `--untagged-delete`  | Deletes any untagged/orphaned images found.                  |
+   | `--force`            | Force deletion without interactive prompt. Helpful for programmatic workflows.   |
+
+   **Output**
+   | Flag                  | Description                                                  |
+   |-----------------------|--------------------------------------------------------------|
+   | `--output FORMAT`    | Output format: `table` (default), `json`, or `csv`.   |
+   | `--debug-log`        | Enable verbose debug logging to `manifesto.log`. |
+   | `--version`          | Print the version number and exit. |
+
+3. **Examples**
+   - Scan all images in a repository:
+     ```bash
+     manifesto my-org my-repo
+     ```
+
+   - Get a summary of all tags for a specific image:
+     ```bash
+     manifesto my-org my-repo my-image
+     ```
+
+   - See full breakdown (platforms & digests) for all images:
+     ```bash
+     manifesto my-org my-repo --detailed
+     ```
+
+   - Show vulnerability scan results:
+     ```bash
+     manifesto my-org my-repo my-image --vulnerabilities
+     ```
+
+   - Get untagged/orphaned images:
+     ```bash
+     manifesto my-org my-repo my-image --untagged
+     ```
+
+   - Filter by tag:
+     ```bash
+     manifesto my-org my-repo my-image --filter "tag:latest"
+     ```
+
+   - Filter by upload date and download count:
+     ```bash
+     manifesto my-org my-repo --filter "uploaded:<'30 days ago' AND downloads:>0"
+     ```
+
+   - Include cosign signature/SBOM artifacts in the output:
+     ```bash
+     manifesto my-org my-repo my-image --show-signatures
+     ```
+
+   - Quick summary across all images:
+     ```bash
+     manifesto my-org my-repo --summary
+     ```
+
+   - Inspect the raw manifest for a tag:
+     ```bash
+     manifesto my-org my-repo my-image --inspect latest
+     ```
+
+   - Export results to JSON:
+     ```bash
+     manifesto my-org my-repo --output json
+     ```
+
+   - Export results to CSV:
+     ```bash
+     manifesto my-org my-repo --output csv > report.csv
+     ```
+
+   - Delete untagged/orphaned images:
+     ```bash
+     manifesto my-org my-repo my-image --untagged-delete
+     ```
+
+   - Delete a specific tag:
+     ```bash
+     manifesto my-org my-repo my-image --delete-tag tag
+     ```
+
+   - Wipe all detected images (use with caution!):
+     ```bash
+     manifesto my-org my-repo --delete-all
+     ```
+
+
+
+
+
+
+