jfrog-xray 0.1.0__tar.gz

jfrog_xray-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build
+build/
+dist/
+
+# Environments
+.venv/
+.env
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/

jfrog_xray-0.1.0/.idea/.gitignore

@@ -0,0 +1,3 @@
+# Default ignored files
+/shelf/
+/workspace.xml

jfrog_xray-0.1.0/.idea/workspace.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="PropertiesComponent">{}</component>
+</project>

jfrog_xray-0.1.0/LICENSE

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

jfrog_xray-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: jfrog-xray
+Version: 0.1.0
+Summary: A modern, typed Python client for the JFrog Xray REST API (read side).
+Project-URL: Homepage, https://github.com/helic0ptr/jfrog-xray
+Project-URL: Repository, https://github.com/helic0ptr/jfrog-xray
+License: MIT
+License-File: LICENSE
+Keywords: artifactory,cve,jfrog,sbom,sca,security,xray
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# jfrog-xray
+
+A modern, typed Python client for the **JFrog Xray REST API** — read side.
+
+It focuses on the questions teams actually ask of Xray on Artifactory: *what
+are the CVEs for this artifact?*, *what violations do we have?*, and the
+summary / scan-status / license lookups around them. Responses are parsed into
+[pydantic](https://docs.pydantic.dev) models, list endpoints auto-paginate,
+transient failures are retried, and HTTP errors surface as typed exceptions.
+
+> Import name is `jfrog_xray`. Sync client today; the core is structured so an
+> async client can be added without a rewrite.
+
+## Install
+
+```bash
+uv add jfrog-xray        # or: pip install jfrog-xray
+```
+
+## Quickstart
+
+```python
+from jfrog_xray import XrayClient
+
+# base_url is the JFrog Platform root; token is a Bearer access token.
+# Both fall back to env vars: XRAY_URL / XRAY_BASE_URL and XRAY_TOKEN.
+with XrayClient(base_url="https://acme.jfrog.io", token="...") as x:
+    x.system.ping()  # {"status": "pong"}
+```
+
+## Headline: CVEs for an artifact
+
+Get the vulnerabilities for a single artifact as a typed list (via Summary v2):
+
+```python
+for cve in x.artifacts.vulnerabilities(repo="docker-local",
+                                       path="nginx/1.25/manifest.json"):
+    print(cve.cve, cve.severity, cve.component, cve.fixed_versions)
+
+# ...or identify the artifact by checksum:
+x.artifacts.vulnerabilities(sha256="9f6c...")
+```
+
+Or download a full report / SBOM (ZIP) for it:
+
+```python
+x.artifacts.export(
+    component_name="nginx",
+    package_type="docker",
+    vulnerabilities=True,
+    sbom="cyclonedx",      # or "spdx"
+    out="nginx-report.zip",
+)
+```
+
+## Other read APIs
+
+```python
+# Violations — the returned page auto-paginates when iterated.
+for v in x.violations.list(watch_name="prod", min_severity="High"):
+    print(v.issue_id, v.severity, v.violation_details_url)
+
+# Summaries
+summary = x.summaries.artifact(paths=["docker-local/nginx/1.25/manifest.json"])
+build = x.summaries.build(build_name="my-app", build_number="42")
+
+# CVE / component lookups
+x.components.search_by_cves(["CVE-2023-0001"])
+x.components.search_cves_by_components(["gav://com.example:app:1.0.0"])
+for r in x.components.impacted_resources(vulnerability="CVE-2023-0001"):
+    print(r.repository, r.path)
+
+# Scan status & licenses
+x.scans.artifact_status(repo="docker-local", path="nginx/1.25/manifest.json")
+x.licenses.list()
+```
+
+## Configuration
+
+```python
+XrayClient(
+    base_url=...,          # or XRAY_URL / XRAY_BASE_URL
+    token=...,             # or XRAY_TOKEN; alternatively auth=<httpx.Auth>
+    timeout=30.0,          # float seconds or httpx.Timeout
+    max_retries=2,         # connection/timeout/5xx/429, honoring Retry-After
+    http_client=...,       # inject a preconfigured httpx.Client
+)
+
+# Per-call overrides (shares the same underlying HTTP client):
+x.with_options(timeout=5.0, max_retries=0).system.ping()
+```
+
+## Errors
+
+All errors derive from `XrayError`. HTTP failures raise an `APIStatusError`
+subclass carrying `.status_code`, `.response`, and `.body`:
+
+`BadRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError`
+(403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError`
+(422), `RateLimitError` (429, with `.retry_after`), `InternalServerError` (5xx).
+Network problems raise `APIConnectionError` / `APITimeoutError`.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check src tests
+uv run mypy src
+uv run pytest                 # unit tests (respx-mocked; no network)
+```
+
+### Integration tests
+
+Live tests in `tests/test_integration.py` run read-only against a real JFrog
+Platform. They **skip** unless `XRAY_URL` (or `XRAY_BASE_URL`) and `XRAY_TOKEN`
+are set; individual tests skip when their resource env var is absent.
+
+```bash
+export XRAY_URL="https://acme.jfrog.io"
+export XRAY_TOKEN="..."
+# optional, to exercise resource-specific tests:
+export XRAY_TEST_ARTIFACT_PATH="docker-local/nginx/1.25/manifest.json"
+export XRAY_TEST_CVE="CVE-2021-44228"
+# ...see the module docstring for the full list
+
+uv run pytest -m integration
+```
+
+## Scope
+
+**In v1 (read side):** system, summaries, violations, CVE/component lookups,
+scan status, licenses, and the `artifacts` convenience resource.
+
+**Deferred:** async client, the async Reports API (create → poll → paginated
+content → delete), governance reads (watches / policies / ignore rules), and
+all write-side actions.
+
+## License
+
+MIT

jfrog_xray-0.1.0/README.md

@@ -0,0 +1,140 @@
+# jfrog-xray
+
+A modern, typed Python client for the **JFrog Xray REST API** — read side.
+
+It focuses on the questions teams actually ask of Xray on Artifactory: *what
+are the CVEs for this artifact?*, *what violations do we have?*, and the
+summary / scan-status / license lookups around them. Responses are parsed into
+[pydantic](https://docs.pydantic.dev) models, list endpoints auto-paginate,
+transient failures are retried, and HTTP errors surface as typed exceptions.
+
+> Import name is `jfrog_xray`. Sync client today; the core is structured so an
+> async client can be added without a rewrite.
+
+## Install
+
+```bash
+uv add jfrog-xray        # or: pip install jfrog-xray
+```
+
+## Quickstart
+
+```python
+from jfrog_xray import XrayClient
+
+# base_url is the JFrog Platform root; token is a Bearer access token.
+# Both fall back to env vars: XRAY_URL / XRAY_BASE_URL and XRAY_TOKEN.
+with XrayClient(base_url="https://acme.jfrog.io", token="...") as x:
+    x.system.ping()  # {"status": "pong"}
+```
+
+## Headline: CVEs for an artifact
+
+Get the vulnerabilities for a single artifact as a typed list (via Summary v2):
+
+```python
+for cve in x.artifacts.vulnerabilities(repo="docker-local",
+                                       path="nginx/1.25/manifest.json"):
+    print(cve.cve, cve.severity, cve.component, cve.fixed_versions)
+
+# ...or identify the artifact by checksum:
+x.artifacts.vulnerabilities(sha256="9f6c...")
+```
+
+Or download a full report / SBOM (ZIP) for it:
+
+```python
+x.artifacts.export(
+    component_name="nginx",
+    package_type="docker",
+    vulnerabilities=True,
+    sbom="cyclonedx",      # or "spdx"
+    out="nginx-report.zip",
+)
+```
+
+## Other read APIs
+
+```python
+# Violations — the returned page auto-paginates when iterated.
+for v in x.violations.list(watch_name="prod", min_severity="High"):
+    print(v.issue_id, v.severity, v.violation_details_url)
+
+# Summaries
+summary = x.summaries.artifact(paths=["docker-local/nginx/1.25/manifest.json"])
+build = x.summaries.build(build_name="my-app", build_number="42")
+
+# CVE / component lookups
+x.components.search_by_cves(["CVE-2023-0001"])
+x.components.search_cves_by_components(["gav://com.example:app:1.0.0"])
+for r in x.components.impacted_resources(vulnerability="CVE-2023-0001"):
+    print(r.repository, r.path)
+
+# Scan status & licenses
+x.scans.artifact_status(repo="docker-local", path="nginx/1.25/manifest.json")
+x.licenses.list()
+```
+
+## Configuration
+
+```python
+XrayClient(
+    base_url=...,          # or XRAY_URL / XRAY_BASE_URL
+    token=...,             # or XRAY_TOKEN; alternatively auth=<httpx.Auth>
+    timeout=30.0,          # float seconds or httpx.Timeout
+    max_retries=2,         # connection/timeout/5xx/429, honoring Retry-After
+    http_client=...,       # inject a preconfigured httpx.Client
+)
+
+# Per-call overrides (shares the same underlying HTTP client):
+x.with_options(timeout=5.0, max_retries=0).system.ping()
+```
+
+## Errors
+
+All errors derive from `XrayError`. HTTP failures raise an `APIStatusError`
+subclass carrying `.status_code`, `.response`, and `.body`:
+
+`BadRequestError` (400), `AuthenticationError` (401), `PermissionDeniedError`
+(403), `NotFoundError` (404), `ConflictError` (409), `UnprocessableEntityError`
+(422), `RateLimitError` (429, with `.retry_after`), `InternalServerError` (5xx).
+Network problems raise `APIConnectionError` / `APITimeoutError`.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check src tests
+uv run mypy src
+uv run pytest                 # unit tests (respx-mocked; no network)
+```
+
+### Integration tests
+
+Live tests in `tests/test_integration.py` run read-only against a real JFrog
+Platform. They **skip** unless `XRAY_URL` (or `XRAY_BASE_URL`) and `XRAY_TOKEN`
+are set; individual tests skip when their resource env var is absent.
+
+```bash
+export XRAY_URL="https://acme.jfrog.io"
+export XRAY_TOKEN="..."
+# optional, to exercise resource-specific tests:
+export XRAY_TEST_ARTIFACT_PATH="docker-local/nginx/1.25/manifest.json"
+export XRAY_TEST_CVE="CVE-2021-44228"
+# ...see the module docstring for the full list
+
+uv run pytest -m integration
+```
+
+## Scope
+
+**In v1 (read side):** system, summaries, violations, CVE/component lookups,
+scan status, licenses, and the `artifacts` convenience resource.
+
+**Deferred:** async client, the async Reports API (create → poll → paginated
+content → delete), governance reads (watches / policies / ignore rules), and
+all write-side actions.
+
+## License
+
+MIT

jfrog_xray-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jfrog-xray"
+version = "0.1.0"
+description = "A modern, typed Python client for the JFrog Xray REST API (read side)."
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+keywords = ["jfrog", "xray", "artifactory", "security", "sca", "cve", "sbom"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://github.com/helic0ptr/jfrog-xray"
+Repository = "https://github.com/helic0ptr/jfrog-xray"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.2",
+    "respx>=0.21",
+    "anyio>=4.4",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jfrog_xray"]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4", "RUF"]
+ignore = ["B008"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101"]
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+plugins = ["pydantic.mypy"]
+files = ["src"]
+
+[tool.pydantic-mypy]
+init_forbid_extra = true
+init_typed = true
+warn_required_dynamic_aliases = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+markers = [
+    "integration: tests that hit a real JFrog Platform (require XRAY_URL/XRAY_TOKEN)",
+]

jfrog_xray-0.1.0/src/jfrog_xray/__init__.py

@@ -0,0 +1,72 @@
+"""A modern, typed Python client for the JFrog Xray REST API (read side)."""
+
+from __future__ import annotations
+
+from ._auth import ApiKeyAuth, BearerAuth
+from ._client import XrayClient
+from ._exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+    XrayError,
+)
+from ._pagination import SyncPage
+from ._version import __version__
+from .models import (
+    ArtifactSummary,
+    BuildSummary,
+    Component,
+    ComponentDetail,
+    Cve,
+    CveSearchResult,
+    IgnoredViolation,
+    ImpactedResource,
+    License,
+    PackageType,
+    Severity,
+    Violation,
+    Vulnerability,
+)
+
+__all__ = [  # noqa: RUF022 -- grouped by category for readability
+    "__version__",
+    "XrayClient",
+    "BearerAuth",
+    "ApiKeyAuth",
+    "SyncPage",
+    # errors
+    "XrayError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    # models
+    "Severity",
+    "PackageType",
+    "Cve",
+    "Component",
+    "License",
+    "ArtifactSummary",
+    "BuildSummary",
+    "Violation",
+    "IgnoredViolation",
+    "ComponentDetail",
+    "CveSearchResult",
+    "ImpactedResource",
+    "Vulnerability",
+]

jfrog_xray-0.1.0/src/jfrog_xray/_auth.py

@@ -0,0 +1,48 @@
+"""Authentication flows for the Xray client.
+
+Bearer access tokens are first-class (JFrog's recommended method), but auth is
+pluggable: any :class:`httpx.Auth` can be supplied instead. Auth classes are
+I/O-free so a single instance works for both the sync and (future) async client.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+
+import httpx
+
+__all__ = ["ApiKeyAuth", "BearerAuth", "resolve_auth"]
+
+
+class BearerAuth(httpx.Auth):
+    """Adds ``Authorization: Bearer <token>`` to every request."""
+
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response]:
+        request.headers["Authorization"] = f"Bearer {self._token}"
+        yield request
+
+
+class ApiKeyAuth(httpx.Auth):
+    """Adds a legacy JFrog API-key header (``X-JFrog-Art-Api`` by default)."""
+
+    def __init__(self, api_key: str, *, header: str = "X-JFrog-Art-Api") -> None:
+        self._api_key = api_key
+        self._header = header
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response]:
+        request.headers[self._header] = self._api_key
+        yield request
+
+
+def resolve_auth(*, token: str | None, auth: httpx.Auth | None) -> httpx.Auth | None:
+    """Turn the ``token`` / ``auth`` constructor arguments into an ``httpx.Auth``."""
+    if token is not None and auth is not None:
+        raise ValueError("Pass either `token=` or `auth=`, not both.")
+    if auth is not None:
+        return auth
+    if token is not None:
+        return BearerAuth(token)
+    return None