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
```
