docker-scout-graphql 0.2.0__tar.gz

docker_scout_graphql-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codex
+
+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.

docker_scout_graphql-0.2.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include src *.py
+recursive-include tests *.py
+recursive-include scripts *.ps1
+global-exclude __pycache__ *.py[cod] .DS_Store
+global-exclude *.exe
+prune src/docker_scout_graphql.egg-info

docker_scout_graphql-0.2.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: docker-scout-graphql
+Version: 0.2.0
+Summary: CLI for querying Docker Scout GraphQL vulnerabilities for Docker images.
+Author: Codex
+License-Expression: MIT
+Project-URL: Homepage, https://pypi.org/project/docker-scout-graphql/
+Project-URL: Documentation, https://docs.docker.com/scout/
+Keywords: docker,scout,security,vulnerabilities,graphql,sbom
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Security
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == "dev"
+Requires-Dist: twine>=5.1.1; extra == "dev"
+Requires-Dist: pytest>=8.3.0; extra == "dev"
+Dynamic: license-file
+
+# docker-scout-graphql
+
+`docker-scout-graphql` scans Docker images by:
+
+1. Extracting package dependencies from `docker sbom --format syft-json`.
+2. Converting package URLs into the format expected by Docker Scout's GraphQL backend.
+3. Querying `https://api.dso.docker.com/v1/graphql`.
+4. Returning vulnerabilities separated by image layer hierarchy.
+
+It can scan one image or all local images.
+
+## Install
+
+```powershell
+pip install .
+```
+
+For development mode:
+
+```powershell
+pip install -e .
+```
+
+## Usage
+
+Scan one image and print JSON (default):
+
+```powershell
+docker-scout-graphql debian:12-slim
+```
+
+Scan one image and write JSON report:
+
+```powershell
+docker-scout-graphql debian:12-slim -o report.json
+```
+
+Scan all local images and write JSON:
+
+```powershell
+docker-scout-graphql --all-images -o report.json
+```
+
+Markdown output (optional):
+
+```powershell
+docker-scout-graphql debian:12-slim --markdown -o report.md
+```
+
+## Output
+
+Default output is JSON with this top-level shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at_utc": "2026-02-27T02:17:14.428185+00:00",
+  "images_scanned": 1,
+  "images": []
+}
+```
+
+Each `images[]` entry contains:
+
+- overall counts (`queried_packages`, `vulnerable_packages_count`, `vulnerability_count`)
+- raw vulnerable package records (`packages`)
+- layered hierarchy (`image_hierarchy.layers`) with vulnerable packages grouped by image layer
+
+## Release
+
+For TestPyPI/PyPI publishing steps, see [PYPI_RELEASE.md](PYPI_RELEASE.md).
+You can also use the helper script:
+
+```powershell
+.\scripts\publish.ps1 -TestPyPI
+.\scripts\publish.ps1
+```

docker_scout_graphql-0.2.0/README.md

@@ -0,0 +1,77 @@
+# docker-scout-graphql
+
+`docker-scout-graphql` scans Docker images by:
+
+1. Extracting package dependencies from `docker sbom --format syft-json`.
+2. Converting package URLs into the format expected by Docker Scout's GraphQL backend.
+3. Querying `https://api.dso.docker.com/v1/graphql`.
+4. Returning vulnerabilities separated by image layer hierarchy.
+
+It can scan one image or all local images.
+
+## Install
+
+```powershell
+pip install .
+```
+
+For development mode:
+
+```powershell
+pip install -e .
+```
+
+## Usage
+
+Scan one image and print JSON (default):
+
+```powershell
+docker-scout-graphql debian:12-slim
+```
+
+Scan one image and write JSON report:
+
+```powershell
+docker-scout-graphql debian:12-slim -o report.json
+```
+
+Scan all local images and write JSON:
+
+```powershell
+docker-scout-graphql --all-images -o report.json
+```
+
+Markdown output (optional):
+
+```powershell
+docker-scout-graphql debian:12-slim --markdown -o report.md
+```
+
+## Output
+
+Default output is JSON with this top-level shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "generated_at_utc": "2026-02-27T02:17:14.428185+00:00",
+  "images_scanned": 1,
+  "images": []
+}
+```
+
+Each `images[]` entry contains:
+
+- overall counts (`queried_packages`, `vulnerable_packages_count`, `vulnerability_count`)
+- raw vulnerable package records (`packages`)
+- layered hierarchy (`image_hierarchy.layers`) with vulnerable packages grouped by image layer
+
+## Release
+
+For TestPyPI/PyPI publishing steps, see [PYPI_RELEASE.md](PYPI_RELEASE.md).
+You can also use the helper script:
+
+```powershell
+.\scripts\publish.ps1 -TestPyPI
+.\scripts\publish.ps1
+```

docker_scout_graphql-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "docker-scout-graphql"
+version = "0.2.0"
+description = "CLI for querying Docker Scout GraphQL vulnerabilities for Docker images."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Codex" }]
+keywords = ["docker", "scout", "security", "vulnerabilities", "graphql", "sbom"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: System :: Systems Administration",
+  "Topic :: Utilities",
+]
+dependencies = []
+license-files = ["LICENSE"]
+
+[project.scripts]
+docker-scout-graphql = "docker_scout_graphql.cli:main"
+
+[project.urls]
+Homepage = "https://pypi.org/project/docker-scout-graphql/"
+Documentation = "https://docs.docker.com/scout/"
+
+[project.optional-dependencies]
+dev = ["build>=1.2.2", "twine>=5.1.1", "pytest>=8.3.0"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

docker_scout_graphql-0.2.0/scripts/publish.ps1

@@ -0,0 +1,30 @@
+param(
+    [switch]$TestPyPI
+)
+
+if (-not $env:TWINE_USERNAME) {
+    $env:TWINE_USERNAME = "__token__"
+}
+
+if (-not $env:TWINE_PASSWORD) {
+    Write-Error "TWINE_PASSWORD is not set. Export your PyPI token first."
+    exit 1
+}
+
+python -m build
+if ($LASTEXITCODE -ne 0) {
+    exit $LASTEXITCODE
+}
+
+python -m twine check dist/*
+if ($LASTEXITCODE -ne 0) {
+    exit $LASTEXITCODE
+}
+
+if ($TestPyPI) {
+    python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
+} else {
+    python -m twine upload dist/*
+}
+
+exit $LASTEXITCODE

docker_scout_graphql-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

docker_scout_graphql-0.2.0/src/docker_scout_graphql/__init__.py

@@ -0,0 +1,19 @@
+"""Docker Scout GraphQL scanner package."""
+
+from .scout import (
+    DockerScoutGraphQLClient,
+    build_json_document,
+    list_local_images,
+    scan_image,
+    scan_images,
+)
+
+__all__ = [
+    "DockerScoutGraphQLClient",
+    "build_json_document",
+    "list_local_images",
+    "scan_image",
+    "scan_images",
+]
+
+__version__ = "0.2.0"

docker_scout_graphql-0.2.0/src/docker_scout_graphql/cli.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from textwrap import dedent
+from pathlib import Path
+
+from .scout import (
+    DockerScoutGraphQLClient,
+    build_json_document,
+    list_local_images,
+    render_markdown_report,
+    scan_images,
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    description = (
+        "Scan Docker images by querying Docker Scout's GraphQL API with package URLs "
+        "extracted from docker sbom. Default output is JSON."
+    )
+    epilog = dedent(
+        """\
+        Quick Start:
+          1) Scan a single image (JSON to stdout):
+             docker-scout-graphql debian:12-slim
+
+          2) Scan a single image and write JSON file:
+             docker-scout-graphql debian:12-slim -o result.json
+
+          3) Scan all local images and write markdown:
+             docker-scout-graphql --all-images --markdown -o report.md
+
+          4) Scan your existing FastAPI image:
+             docker-scout-graphql fastapiproject-fastapi:latest -o test.json
+
+        Arguments:
+          image
+            Optional positional Docker image reference (for example: debian:12-slim).
+            Required unless --all-images is provided.
+
+          --all-images
+            Scans every image currently returned by `docker images`.
+            Cannot be used together with the positional `image`.
+
+          -o, --output PATH
+            Optional destination file path.
+            If omitted, output is written to stdout.
+
+          --markdown
+            Optional switch to output markdown instead of JSON.
+            JSON is the default format.
+
+          --timeout N
+            HTTP timeout in seconds for each GraphQL request.
+
+          --chunk-size N
+            Number of package URLs per GraphQL request. Larger values reduce
+            request count but can increase per-request latency.
+
+          --retries N
+            Retry count for transient GraphQL errors (429/5xx/network).
+
+        JSON Output Shape (default):
+          {
+            "schema_version": "1.0",
+            "generated_at_utc": "...",
+            "images_scanned": 1,
+            "images": [
+              {
+                "image": "repo:tag",
+                "queried_packages": 123,
+                "vulnerable_packages_count": 10,
+                "vulnerability_count": 23,
+                "correlation_ids": ["..."],
+                "packages": [
+                  {
+                    "purl": "pkg:...",
+                    "package": { "name": "...", "version": "...", "type": "...", "origin": "binary|source" },
+                    "layer_id": "sha256:...",
+                    "vulnerabilities": [ ... ]
+                  }
+                ],
+                "image_hierarchy": {
+                  "type": "layered_image",
+                  "root_layer_id": "sha256:...",
+                  "layers": [
+                    {
+                      "id": "sha256:...",
+                      "index": 0,
+                      "parent": null,
+                      "vulnerable_packages_count": 2,
+                      "vulnerability_count": 5,
+                      "packages": [ ... ]
+                    }
+                  ]
+                }
+              }
+            ]
+          }
+
+        Notes:
+          - All vulnerabilities come directly from Docker's backend GraphQL response.
+          - Correlation IDs are included for traceability with backend requests.
+        """
+    )
+    parser = argparse.ArgumentParser(
+        prog="docker-scout-graphql",
+        description=description,
+        epilog=epilog,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "image",
+        nargs="?",
+        help="Docker image reference to scan (for example: debian:12-slim)",
+    )
+    parser.add_argument(
+        "--all-images",
+        action="store_true",
+        help="Scan every local Docker image.",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="Optional output file path.",
+    )
+    parser.add_argument(
+        "--markdown",
+        action="store_true",
+        help="Output markdown instead of JSON (JSON is the default).",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=60,
+        help="GraphQL request timeout in seconds (default: 60).",
+    )
+    parser.add_argument(
+        "--chunk-size",
+        type=int,
+        default=200,
+        help="Number of package URLs per GraphQL request chunk (default: 200).",
+    )
+    parser.add_argument(
+        "--retries",
+        type=int,
+        default=3,
+        help="GraphQL retries per chunk on transient failures (default: 3).",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.all_images and args.image:
+        parser.error("Provide either an image or --all-images, not both.")
+    if not args.all_images and not args.image:
+        parser.error("Provide an image name or use --all-images.")
+
+    images = list_local_images() if args.all_images else [args.image]
+    if not images:
+        parser.error("No local images found.")
+
+    client = DockerScoutGraphQLClient(
+        timeout_seconds=max(1, args.timeout),
+        chunk_size=max(1, args.chunk_size),
+        max_retries=max(0, args.retries),
+    )
+    reports = scan_images(images=images, client=client)
+    json_document = build_json_document(reports)
+
+    if args.markdown:
+        output_text = render_markdown_report(reports)
+    else:
+        output_text = json.dumps(json_document, indent=2)
+
+    if args.output:
+        output_path = Path(args.output)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(output_text, encoding="utf-8")
+    else:
+        sys.stdout.write(output_text)
+
+    return 1 if any(report.get("error") for report in reports) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())