certone-sdk 0.2.0__py3-none-any.whl

certone_sdk/__init__.py

@@ -0,0 +1,27 @@
+"""CertOne SDK — a typed API client + the run-at-source agent.
+
+    from certone_sdk import CertOneClient
+    c = CertOneClient("https://api.yourco.com", token)
+    c.ingest_report(report, asset="Fraud Scorer", environment="ci", country_code="EU")
+
+``certone-submit`` sends a project for a confidential scan and gates on the verdict (the path every
+CI/MLOps/editor integration uses). The ``certone-agent`` CLI runs the engine where your code lives
+and submits only the results, for systems that may not leave your environment.
+"""
+
+from __future__ import annotations
+
+from certone_sdk.client import CertOneClient, CertOneError, sha256_digest
+from certone_sdk.submit import ProgressPrinter, Submission, pack_project, submit_and_wait
+
+__all__ = [
+    "CertOneClient",
+    "CertOneError",
+    "ProgressPrinter",
+    "Submission",
+    "__version__",
+    "pack_project",
+    "sha256_digest",
+    "submit_and_wait",
+]
+__version__ = "0.2.0"

certone_sdk/agent.py

@@ -0,0 +1,274 @@
+"""certone-agent — certify an AI project from where it lives (a gateway, a build box, a device).
+
+Two modes, for CI/cron (`run`, one-shot) or a long-running watcher (`watch`):
+
+* ``--mode local`` (default, run-at-source): the model/code never leaves your environment. The
+  agent builds the AI BOM + runs the verdict loop locally, then POSTs the **report** (plus a content
+  digest that binds the ⑥ attestation) to the control plane via the SDK.
+* ``--mode confidential``: the project is sent to the platform and processed inside an attested
+  confidential worker (static + dynamic tests on the target + metrics + the in-TEE correction),
+  exactly as ``certone-submit`` does. ``watch`` re-submits only when the project's content changes,
+  so a gateway re-certifies each new model version as it lands.
+
+The API key comes from ``--token`` or ``$CERTONE_API_KEY`` (preferred: it then never appears in the
+process list).
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+from certone_sdk.client import CertOneClient, CertOneError
+from certone_sdk.submit import SKIP_DIRS, pack_project, submit_and_wait
+
+
+def run_once(
+    project: str,
+    pack_paths: list[str],
+    *,
+    client: CertOneClient,
+    asset: str | None = None,
+    environment: str = "ci",
+    country_code: str = "ZZ",
+    fail_on: str = "high",
+    snapshot_ref: str | None = None,
+    repo: str | None = None,
+    commit_hash: str | None = None,
+) -> dict[str, Any]:
+    """Run the engine over ``project`` against ``pack_paths``; submit the report (run-at-source).
+
+    Pass ``repo`` + ``commit_hash`` (or run inside GitHub Actions, where they're auto-detected) to
+    close the two-way loop: the verdict is posted back as a native Check Run on that commit.
+    """
+    from certone_engine.archive import make_targz
+    from certone_engine.evaluation.runner import run_check
+
+    result = run_check(project, list(pack_paths), fail_on=fail_on, snapshot_ref=snapshot_ref)
+    report = result.report.to_dict()
+    # Bind the attestation to the snapshot content without uploading it.
+    digest = "sha256:" + hashlib.sha256(make_targz(Path(project))).hexdigest()
+    return client.ingest_report(
+        report,
+        asset=asset,
+        environment=environment,
+        country_code=country_code,
+        snapshot_ref=snapshot_ref,
+        input_digest=digest,
+        repo=repo,
+        commit_hash=commit_hash,
+    )
+
+
+def content_digest(project: str | Path) -> str:
+    """``sha256:`` over the project's files (paths + bytes), skipping VCS metadata and caches --
+    what ``watch`` compares to decide whether a new version landed."""
+    root = Path(project).resolve()
+    h = hashlib.sha256()
+    for path in sorted(root.rglob("*")):
+        rel = path.relative_to(root)
+        if path.is_file() and not path.is_symlink() and not SKIP_DIRS.intersection(rel.parts):
+            h.update(rel.as_posix().encode() + b"\0")
+            with path.open("rb") as fh:
+                for chunk in iter(lambda: fh.read(1 << 20), b""):
+                    h.update(chunk)
+    return f"sha256:{h.hexdigest()}"
+
+
+def run_confidential(
+    project: str | Path,
+    *,
+    client: CertOneClient,
+    asset: str | None = None,
+    environment: str = "edge",
+    country_code: str = "ZZ",
+    fail_on: str = "high",
+    tee: str = "amd_sev_snp",
+    snapshot_ref: str | None = None,
+    commit_hash: str | None = None,
+) -> str:
+    """Send ``project`` for a confidential scan and print its verdict; returns the verdict."""
+    root = Path(project).resolve()
+    name = asset or root.name
+    sub = submit_and_wait(
+        client,
+        pack_project(root),
+        asset=name,
+        environment=environment,
+        country_code=country_code,
+        fail_on=fail_on,
+        tee=tee,
+        snapshot_ref=snapshot_ref,
+        commit_hash=commit_hash,
+        on_submitted=lambda scan_id, digest: print(
+            f"certone-agent: {name} -> confidential scan {scan_id} ({digest})", flush=True
+        ),
+    )
+    by = sub.report.get("by_severity") or {}
+    runtime = (sub.run.get("execution") or {}).get("runtime") or "the confidential worker"
+    att = sub.attestation.get("attestation_id") if sub.attestation else None
+    attestation = f"; attestation {att}" if att else ""
+    print(
+        f"certone-agent: verdict {sub.verdict.upper()} ({by.get('high', 0)} high, "
+        f"{by.get('medium', 0)} medium, {by.get('low', 0)} low) in {runtime}{attestation}",
+        flush=True,
+    )
+    return sub.verdict
+
+
+def watch_confidential(scan: Any, project: str | Path, interval: int, *, polls: int = 0) -> None:
+    """Call ``scan()`` for the first version of ``project`` and again whenever its content changes.
+
+    A failed scan is retried on the next poll. ``polls`` > 0 bounds the loop (tests); 0 = forever.
+    """
+    seen: str | None = None
+    done = 0
+    while polls <= 0 or done < polls:
+        digest = content_digest(project)
+        if digest != seen:
+            if seen is not None:
+                print(f"certone-agent: new version detected ({digest})", flush=True)
+            try:
+                scan()
+                seen = digest
+            except CertOneError as exc:
+                print(f"certone-agent: {exc}", file=sys.stderr, flush=True)
+        done += 1
+        if polls <= 0 or done < polls:
+            time.sleep(max(1, interval))
+
+
+def _ci_source(repo: str | None, commit_hash: str | None) -> tuple[str | None, str | None]:
+    """Fill repo/commit from the GitHub Actions environment when not given explicitly."""
+    return (
+        repo or os.environ.get("GITHUB_REPOSITORY") or None,
+        commit_hash or os.environ.get("GITHUB_SHA") or None,
+    )
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--project", default=".", help="path to the AI project (default: .)")
+    p.add_argument(
+        "--mode",
+        choices=("local", "confidential"),
+        default="local",
+        help="local: run at source and submit the report; confidential: scan in the platform TEE",
+    )
+    p.add_argument(
+        "--pack", action="append", default=[], dest="packs", help="PaC pack dir (repeatable)"
+    )
+    p.add_argument(
+        "--api", required=True, help="control-plane base URL, e.g. https://api.yourco.com"
+    )
+    p.add_argument("--token", default=None, help="API token, member role ($CERTONE_API_KEY)")
+    p.add_argument("--asset", help="AI system name (auto from snapshot-ref if omitted)")
+    p.add_argument("--environment", default=None, help="ci|jupyter|vscode|edge|api|cloud|cli")
+    p.add_argument("--country-code", default="ZZ", help="origin region, e.g. EU")
+    p.add_argument("--fail-on", default="high", help="low|medium|high|none")
+    p.add_argument("--tee", default="amd_sev_snp", help="amd_sev_snp | kata_cc (confidential)")
+    p.add_argument("--snapshot-ref", help="stable source ref, e.g. git:repo@sha")
+    p.add_argument("--repo", help="GitHub repo 'owner/name' for native PR checks (auto in Actions)")
+    p.add_argument("--commit", help="head SHA to post the Check Run on (auto in Actions)")
+
+
+def deliver(client: CertOneClient, envelope_path: str | Path) -> dict[str, Any]:
+    """Deliver a result signed inside an air-gapped network (``certone result sign``)."""
+    envelope = json.loads(Path(envelope_path).read_text(encoding="utf-8"))
+    return client.ingest_signed_result(envelope)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="certone-agent", description=__doc__)
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    run_p = sub.add_parser("run", help="run once and submit (CI/cron)")
+    _add_common(run_p)
+    watch_p = sub.add_parser("watch", help="keep certifying (long-running)")
+    _add_common(watch_p)
+    watch_p.add_argument("--interval", type=int, default=300, help="seconds between checks")
+    deliver_p = sub.add_parser(
+        "deliver", help="deliver a signed result carried out of an air-gapped network"
+    )
+    deliver_p.add_argument(
+        "envelope", help="the result.signed.json written by `certone result sign`"
+    )
+    deliver_p.add_argument("--api", required=True, help="control-plane base URL")
+    deliver_p.add_argument("--token", default=None, help="API token ($CERTONE_API_KEY)")
+    args = parser.parse_args(argv)
+
+    token = args.token or os.environ.get("CERTONE_API_KEY")
+    if not token:
+        parser.error("no API key: pass --token or set CERTONE_API_KEY")
+    client = CertOneClient(args.api, token)
+
+    if args.cmd == "deliver":
+        try:
+            out = deliver(client, args.envelope)
+        except CertOneError as exc:
+            print(f"certone-agent: delivery refused: {exc}", file=sys.stderr)
+            return 2
+        report = out.get("report") or {}
+        print(
+            f"certone-agent: signed result accepted (signature verified): scan "
+            f"{out['scan_run']['id']}, verdict {str(report.get('verdict_status', '?')).upper()}"
+        )
+        return 0
+    repo, commit_hash = _ci_source(args.repo, args.commit)
+
+    if args.mode == "confidential":
+
+        def scan() -> str:
+            return run_confidential(
+                args.project,
+                client=client,
+                asset=args.asset,
+                environment=args.environment or "edge",
+                country_code=args.country_code,
+                fail_on=args.fail_on,
+                tee=args.tee,
+                snapshot_ref=args.snapshot_ref,
+                commit_hash=commit_hash,
+            )
+
+        if args.cmd == "watch":
+            print(f"certone-agent: watching {Path(args.project).resolve()}", flush=True)
+            watch_confidential(scan, args.project, args.interval)
+            return 0
+        try:
+            return 0 if scan() == "pass" else 1
+        except CertOneError as exc:
+            print(f"certone-agent: {exc}", file=sys.stderr)
+            return 2
+
+    def _go() -> str:
+        out = run_once(
+            args.project,
+            args.packs,
+            client=client,
+            asset=args.asset,
+            environment=args.environment or "ci",
+            country_code=args.country_code,
+            fail_on=args.fail_on,
+            snapshot_ref=args.snapshot_ref,
+            repo=repo,
+            commit_hash=commit_hash,
+        )
+        return str(out.get("report", {}).get("verdict_status", "?"))
+
+    if args.cmd == "watch":
+        while True:
+            verdict = _go()
+            print(f"certone-agent: submitted (verdict={verdict})")
+            time.sleep(max(5, args.interval))
+    verdict = _go()
+    print(f"certone-agent: submitted (verdict={verdict})")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

certone_sdk/client.py

@@ -0,0 +1,262 @@
+"""Typed HTTP client for the CertOne control-plane API (the SDK enterprises script against).
+
+Implements the operations in ``sdk/SPEC.md``, the contract every CertOne SDK shares.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import IO, Any
+
+# (connect, read) timeout for every API call so a hung control plane can't hang the caller's CI job.
+_HTTP_TIMEOUT = (5, 30)
+# Snapshot uploads can be large; the read side waits for the control plane to accept the archive.
+_UPLOAD_TIMEOUT = (5, 300)
+
+Snapshot = str | Path | bytes | IO[bytes]
+
+
+class CertOneError(RuntimeError):
+    """A control-plane API call failed. ``status`` is the HTTP status (0 when none was received)."""
+
+    def __init__(self, message: str, status: int = 0, detail: str = "") -> None:
+        super().__init__(message)
+        self.status = status
+        self.detail = detail
+
+
+def sha256_digest(data: Snapshot) -> str:
+    """``sha256:<hex>`` of a snapshot, the ``input_digest`` that binds an attestation to it."""
+    h = hashlib.sha256()
+    if isinstance(data, bytes):
+        h.update(data)
+    elif isinstance(data, str | Path):
+        with Path(data).open("rb") as fh:
+            for chunk in iter(lambda: fh.read(1 << 20), b""):
+                h.update(chunk)
+    else:
+        for chunk in iter(lambda: data.read(1 << 20), b""):
+            h.update(chunk)
+    return f"sha256:{h.hexdigest()}"
+
+
+class CertOneClient:
+    """Minimal client. ``requests`` is imported lazily; inject ``session`` in tests."""
+
+    def __init__(self, base_url: str, token: str | None = None, *, session: Any = None) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self._session = session
+
+    def _sess(self) -> Any:
+        if self._session is None:
+            import requests  # lazy: only when a real call is made
+
+            self._session = requests.Session()
+        return self._session
+
+    def _headers(self, json_body: bool = False) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self.token:
+            headers["authorization"] = f"Bearer {self.token}"
+        if json_body:
+            headers["content-type"] = "application/json"
+        return headers
+
+    def _post(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
+        resp = self._sess().post(
+            f"{self.base_url}{path}",
+            json=body,
+            headers=self._headers(json_body=True),
+            timeout=_HTTP_TIMEOUT,
+        )
+        result: dict[str, Any] = _result(resp)
+        return result
+
+    def _get(self, path: str) -> Any:
+        resp = self._sess().get(
+            f"{self.base_url}{path}", headers=self._headers(), timeout=_HTTP_TIMEOUT
+        )
+        return _result(resp)
+
+    def _submit(self, path: str, snapshot: Snapshot, form: dict[str, str]) -> dict[str, Any]:
+        if isinstance(snapshot, str | Path):
+            with Path(snapshot).open("rb") as fh:
+                return self._submit(path, fh, form)
+        resp = self._sess().post(
+            f"{self.base_url}{path}",
+            data={k: v for k, v in form.items() if v is not None},
+            files={"snapshot": ("snapshot.tar.gz", snapshot, "application/gzip")},
+            headers=self._headers(),
+            timeout=_UPLOAD_TIMEOUT,
+        )
+        result: dict[str, Any] = _result(resp)
+        return result
+
+    # --- submit a project snapshot (.tar.gz) ---
+    def submit_check(
+        self,
+        snapshot: Snapshot,
+        *,
+        asset: str | None = None,
+        environment: str = "api",
+        country_code: str = "ZZ",
+        fail_on: str = "high",
+        packs: str = "",
+        snapshot_ref: str | None = None,
+        commit_hash: str | None = None,
+    ) -> dict[str, Any]:
+        """Static verdict (AI BOM + policy-as-code) over a snapshot."""
+        return self._submit(
+            "/v1/checks",
+            snapshot,
+            _form(asset, environment, country_code, fail_on, packs, snapshot_ref, commit_hash),
+        )
+
+    def submit_process(
+        self,
+        snapshot: Snapshot,
+        *,
+        asset: str | None = None,
+        environment: str = "api",
+        country_code: str = "ZZ",
+        fail_on: str = "high",
+        packs: str = "",
+        snapshot_ref: str | None = None,
+        commit_hash: str | None = None,
+        tee: str = "amd_sev_snp",
+    ) -> dict[str, Any]:
+        """Full processing in the attested confidential worker (static + dynamic + metrics).
+
+        On the confidential worker pool the result is ``queued`` with no report yet: follow it with
+        :meth:`wait_for_report`.
+        """
+        form = _form(asset, environment, country_code, fail_on, packs, snapshot_ref, commit_hash)
+        form["tee"] = tee
+        return self._submit("/v1/process", snapshot, form)
+
+    # --- run-at-source: submit a pre-computed report (no artifact upload) ---
+    def ingest_report(
+        self,
+        report: dict[str, Any],
+        *,
+        asset: str | None = None,
+        environment: str = "api",
+        country_code: str = "ZZ",
+        snapshot_ref: str | None = None,
+        input_digest: str | None = None,
+        repo: str | None = None,
+        commit_hash: str | None = None,
+    ) -> dict[str, Any]:
+        return self._post(
+            "/v1/checks/report",
+            {
+                "report": report,
+                "asset": asset,
+                "environment": environment,
+                "country_code": country_code,
+                "snapshot_ref": snapshot_ref,
+                "input_digest": input_digest,
+                "repo": repo,
+                "commit_hash": commit_hash,
+            },
+        )
+
+    # --- air-gapped run-at-source: deliver a result signed inside the closed network ---
+    def ingest_signed_result(self, envelope: dict[str, Any]) -> dict[str, Any]:
+        """Submit a ``certone result sign`` envelope; the platform verifies its source-key
+        signature before accepting it (re-delivering the same file returns the same scan)."""
+        return self._post("/v1/checks/report/signed", envelope)
+
+    # --- scans, reports, attestations ---
+    def get_scan(self, scan_id: str) -> dict[str, Any]:
+        scan: dict[str, Any] = self._get(f"/v1/scans/{scan_id}")
+        return scan
+
+    def wait_for_report(
+        self,
+        scan_id: str,
+        *,
+        timeout: float = 900.0,
+        interval: float = 2.0,
+        on_status: Callable[[str, float], None] | None = None,
+    ) -> dict[str, Any]:
+        """Poll a scan until it finishes, then return its report summary. ``on_status(status,
+        elapsed_s)`` is called after every poll (``queued``, ``running``, ``succeeded``...).
+
+        Raises :class:`CertOneError` when the scan failed or did not finish within ``timeout``.
+        """
+        start = time.monotonic()
+        deadline = start + timeout
+        while True:
+            scan = self.get_scan(scan_id)
+            if on_status is not None:
+                on_status(str(scan.get("status", "")), time.monotonic() - start)
+            if scan.get("status") == "succeeded":
+                report: dict[str, Any] = self._get(f"/v1/scans/{scan_id}/report")
+                return report
+            if scan.get("status") == "failed":
+                raise CertOneError(f"scan {scan_id} failed: {scan.get('error') or 'no detail'}")
+            if time.monotonic() >= deadline:
+                raise CertOneError(f"scan {scan_id} did not finish within {timeout:.0f}s")
+            time.sleep(interval)
+
+    def get_run(self, scan_id: str) -> dict[str, Any]:
+        """How a scan ran: ``execution.runtime`` (where its code executed) and ``tee_evidence``
+        (the confidential VM's hardware attestation, ``attested``)."""
+        run: dict[str, Any] = self._get(f"/v1/scans/{scan_id}/run")
+        return run
+
+    def get_report_document(self, report_id: str) -> dict[str, Any]:
+        """The full engine report: verdict, summary, issues (``report_id``: the record ``id``)."""
+        doc: dict[str, Any] = self._get(f"/v1/reports/{report_id}/document")
+        return doc
+
+    def get_attestation(self, report_id: str) -> dict[str, Any]:
+        """The signed attestation of a passing report (404 -> CertOneError when it did not pass)."""
+        attestation: dict[str, Any] = self._get(f"/v1/reports/{report_id}/attestation")
+        return attestation
+
+    # --- reads ---
+    def observability_summary(self) -> dict[str, Any]:
+        summary: dict[str, Any] = self._get("/v1/observability/summary")
+        return summary
+
+    def list_systems(self) -> list[dict[str, Any]]:
+        systems: list[dict[str, Any]] = self._get("/v1/systems")
+        return systems
+
+
+def _form(
+    asset: str | None,
+    environment: str,
+    country_code: str,
+    fail_on: str,
+    packs: str,
+    snapshot_ref: str | None,
+    commit_hash: str | None,
+) -> dict[str, str]:
+    form = {"environment": environment, "country_code": country_code, "fail_on": fail_on}
+    optional = {
+        "asset": asset,
+        "packs": packs,
+        "snapshot_ref": snapshot_ref,
+        "commit_hash": commit_hash,
+    }
+    form.update({k: v for k, v in optional.items() if v})
+    return form
+
+
+def _result(resp: Any) -> Any:
+    status = int(getattr(resp, "status_code", 0))
+    if status >= 400:
+        detail = ""
+        try:
+            detail = str(resp.json().get("detail", ""))
+        except Exception:  # best-effort error detail extraction
+            detail = getattr(resp, "text", "")
+        raise CertOneError(f"HTTP {status}: {detail}", status=status, detail=detail)
+    return resp.json()

certone_sdk/submit.py

@@ -0,0 +1,363 @@
+"""certone-submit — send a project to CertOne for a confidential scan and gate on the verdict.
+
+The one submission path every integration shares (GitHub Actions, GitLab CI, Azure ML, VS Code,
+Jupyter, the edge agent): the project is packed, uploaded to the platform, and processed inside an
+attested confidential worker (AMD SEV-SNP CVM or Kata confidential containers) -- static analysis,
+dynamic tests on the target, metrics and the in-TEE correction. The command waits for the verdict,
+prints the findings, writes the evidence, and exits non-zero unless the verdict passes, so a
+pipeline step can gate on it.
+
+    certone-submit --project . --asset "Card Fraud Scorer"      # key from $CERTONE_API_KEY
+
+Exit codes: 0 pass, 1 the verdict did not pass, 2 the scan could not be run (error, timeout).
+The API key is read from ``--api-key`` or ``$CERTONE_API_KEY`` and is never printed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import os
+import sys
+import tarfile
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import IO, Any, ClassVar
+
+from certone_sdk.client import CertOneClient, CertOneError, sha256_digest
+
+#: Never shipped in a snapshot: VCS metadata, caches, virtualenvs, dependency trees.
+SKIP_DIRS = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        "__pycache__",
+        ".venv",
+        "venv",
+        "node_modules",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".ipynb_checkpoints",
+        ".certone",
+    }
+)
+DEFAULT_API = "https://platform.certkor.ai"
+
+
+def pack_project(project: Path, top: str | None = None) -> bytes:
+    """``project`` as a gzip tarball under one top-level folder (``top``, default: its name)."""
+    root = project.resolve()
+    name = top or root.name or "project"
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tar:
+        for path in sorted(root.rglob("*")):
+            rel = path.relative_to(root)
+            if path.is_file() and not path.is_symlink() and not SKIP_DIRS.intersection(rel.parts):
+                tar.add(path, arcname=f"{name}/{rel.as_posix()}")
+    return buf.getvalue()
+
+
+@dataclass(frozen=True)
+class Submission:
+    """A finished confidential scan: its id, report summary, full document and attestation."""
+
+    scan_id: str
+    report: dict[str, Any]
+    document: dict[str, Any]
+    attestation: dict[str, Any] | None
+    #: How it ran (``execution.runtime``, ``tee_evidence.attested``); empty when unavailable.
+    run: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def verdict(self) -> str:
+        return str(self.report.get("verdict_status", "unknown"))
+
+    @property
+    def passed(self) -> bool:
+        return self.verdict == "pass"
+
+
+def submit_and_wait(
+    client: CertOneClient,
+    project: Path | bytes,
+    *,
+    asset: str,
+    environment: str = "ci",
+    country_code: str = "ZZ",
+    fail_on: str = "high",
+    tee: str = "amd_sev_snp",
+    snapshot_ref: str | None = None,
+    commit_hash: str | None = None,
+    timeout: float = 1800.0,
+    on_submitted: Any = None,
+    on_progress: Callable[[str, float], None] | None = None,
+) -> Submission:
+    """Submit ``project`` (a folder, or an already-packed snapshot) for confidential processing and
+    wait for its verdict. ``on_submitted(scan_id, digest)`` is called once the platform accepted
+    it, ``on_progress(status, elapsed_s)`` on every status poll while it runs (see
+    :class:`ProgressPrinter`). Raises :class:`CertOneError` when the scan cannot be run or does not
+    finish in time."""
+    snapshot = project if isinstance(project, bytes) else pack_project(project)
+    submitted = client.submit_process(
+        snapshot,
+        asset=asset,
+        environment=environment,
+        country_code=country_code,
+        fail_on=fail_on,
+        snapshot_ref=snapshot_ref,
+        commit_hash=commit_hash,
+        tee=tee,
+    )
+    scan_id = str(submitted["scan_run"]["id"])
+    if on_submitted is not None:
+        on_submitted(scan_id, sha256_digest(snapshot))
+    report = client.wait_for_report(scan_id, timeout=timeout, on_status=on_progress)
+    document = client.get_report_document(report["id"])
+    attestation = (
+        client.get_attestation(report["id"]) if report.get("verdict_status") == "pass" else None
+    )
+    try:
+        run = client.get_run(scan_id)
+    except CertOneError:
+        run = {}  # informational only: the verdict and evidence above are what gate the pipeline
+    return Submission(scan_id, report, document, attestation, run)
+
+
+class ProgressPrinter:
+    """Shows a running scan's progress: one line per status change, plus -- on a terminal -- a
+    spinner with the elapsed time, or -- in CI logs -- a heartbeat line every ``heartbeat_s``.
+
+        submit_and_wait(client, project, asset="...", on_progress=ProgressPrinter())
+    """
+
+    LABELS: ClassVar[dict[str, str]] = {
+        "queued": "queued for a confidential worker",
+        "running": "processing inside the TEE (static analysis, dynamic tests, metrics)",
+        "succeeded": "verdict ready",
+        "failed": "scan failed",
+    }
+
+    def __init__(self, stream: IO[str] | None = None, heartbeat_s: float = 30.0) -> None:
+        self.stream = stream or sys.stdout
+        self.tty = bool(getattr(self.stream, "isatty", lambda: False)())
+        utf8 = "utf" in (getattr(self.stream, "encoding", None) or "").lower()
+        self.spinner = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏" if utf8 else "|/-\\"
+        self.heartbeat_s = heartbeat_s
+        self._status: str | None = None
+        self._beat = 0.0
+        self._tick = 0
+
+    def __call__(self, status: str, elapsed: float) -> None:
+        clock = f"{int(elapsed) // 60}:{int(elapsed) % 60:02d}"
+        label = self.LABELS.get(status, status)
+        if status != self._status:
+            self._status, self._beat = status, elapsed
+            self._write(f"  [{clock}] {label}\n")
+        elif self.tty:
+            self._tick += 1
+            frame = self.spinner[self._tick % len(self.spinner)]
+            self._write(f"  {frame} {label} ... {clock}")
+        elif elapsed - self._beat >= self.heartbeat_s:
+            self._beat = elapsed
+            self._write(f"  [{clock}] still {status}\n")
+
+    def _write(self, text: str) -> None:
+        if self.tty:
+            text = "\r\x1b[K" + text  # replace the spinner line
+        self.stream.write(text)
+        self.stream.flush()
+
+
+def key_from_vault(secret_url: str) -> str:
+    """The API key held in an Azure Key Vault secret (``https://<vault>.vault.azure.net/secrets/
+    <name>[/<version>]``), read with the default Azure credential -- on Azure ML compute that is
+    the cluster's managed identity. Needs ``pip install "certone-sdk[azure]"``."""
+    from urllib.parse import urlsplit
+
+    from azure.identity import DefaultAzureCredential
+    from azure.keyvault.secrets import SecretClient
+
+    parts = urlsplit(secret_url)
+    segments = [s for s in parts.path.split("/") if s]
+    if parts.scheme != "https" or len(segments) < 2 or segments[0] != "secrets":
+        raise ValueError("expected https://<vault>.vault.azure.net/secrets/<name>")
+    client = SecretClient(f"https://{parts.netloc}", DefaultAzureCredential())
+    value = client.get_secret(segments[1], segments[2] if len(segments) > 2 else None).value
+    if not value:
+        raise ValueError(f"secret {segments[1]!r} is empty")
+    return str(value)
+
+
+def _git_commit(project: Path) -> str | None:
+    """The CI's commit (GitHub, GitLab, Azure Pipelines), else None -- never shells out."""
+    for var in ("GITHUB_SHA", "CI_COMMIT_SHA", "BUILD_SOURCEVERSION"):
+        if os.environ.get(var):
+            return os.environ[var]
+    head = project / ".git" / "HEAD"
+    try:
+        ref = head.read_text(encoding="utf-8").strip()
+        if ref.startswith("ref: "):
+            return (project / ".git" / ref[5:]).read_text(encoding="utf-8").strip() or None
+        return ref or None
+    except OSError:
+        return None
+
+
+def _findings(sub: Submission) -> list[tuple[str, str, str]]:
+    """``(severity, description, where)`` for every finding, most severe first."""
+    order = {"high": 0, "medium": 1, "low": 2}
+    out: list[tuple[str, str, str]] = []
+    for issue in sorted(
+        sub.document.get("issues", []), key=lambda i: order.get(i.get("severity"), 3)
+    ):
+        loc = issue.get("location") or {}
+        artifact, line = loc.get("artifact"), loc.get("line_start")
+        where = f"{artifact}{f':{line}' if line else ''}" if artifact not in (None, "", ".") else ""
+        out.append((str(issue.get("severity", "")), str(issue.get("description", "")), where))
+    return out
+
+
+def _runtime(sub: Submission) -> str:
+    runtime = (sub.run.get("execution") or {}).get("runtime")
+    if not runtime:
+        return ""
+    attested = (sub.run.get("tee_evidence") or {}).get("attested")
+    return str(runtime) + (" · hardware-attested" if attested else "")
+
+
+def _counts(sub: Submission) -> str:
+    by_sev = sub.report.get("by_severity") or {}
+    return ", ".join(f"{by_sev.get(s, 0)} {s}" for s in ("high", "medium", "low"))
+
+
+def _print_result(sub: Submission, out: Any) -> None:
+    total = sub.report.get("total_issues", 0)
+    print(f"verdict: {sub.verdict.upper()}  ({total} finding(s): {_counts(sub)})", file=out)
+    if runtime := _runtime(sub):
+        print(f"executed in: {runtime}", file=out)
+    for severity, description, where in _findings(sub):
+        print(
+            f"  [{severity.upper():6}] {description}" + (f"  ({where})" if where else ""), file=out
+        )
+    if sub.attestation:
+        print(f"attestation: {sub.attestation.get('attestation_id')}", file=out)
+
+
+def _markdown(sub: Submission, asset: str) -> str:
+    """A job summary (GitHub ``$GITHUB_STEP_SUMMARY``, GitLab/Azure Pipelines artifacts)."""
+    icon = "✅" if sub.passed else "❌"
+    lines = [
+        f"## {icon} CertOne: {asset} — {sub.verdict.upper()}",
+        "",
+        f"Confidential scan `{sub.scan_id}` · findings: {_counts(sub)}",
+    ]
+    if runtime := _runtime(sub):
+        lines.append(f"Executed in: **{runtime}**")
+    if sub.attestation:
+        lines.append(f"Attestation: `{sub.attestation.get('attestation_id')}`")
+    rows = _findings(sub)
+    if rows:
+        lines += ["", "| Severity | Finding | Where |", "|---|---|---|"]
+        for severity, description, where in rows:
+            cell = description.replace("|", "\\|")
+            lines.append(f"| {severity} | {cell} | {f'`{where}`' if where else ''} |")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="certone-submit", description=__doc__.split("\n\n")[0])
+    ap.add_argument("--project", type=Path, default=Path(), help="project folder (default: .)")
+    ap.add_argument("--asset", required=True, help="AI system name in CertOne")
+    ap.add_argument(
+        "--api",
+        default=os.environ.get("CERTONE_API_URL", DEFAULT_API),
+        help="platform URL (default: $CERTONE_API_URL or %(default)s)",
+    )
+    ap.add_argument("--api-key", default=None, help="API key (default: $CERTONE_API_KEY)")
+    ap.add_argument(
+        "--api-key-vault",
+        default=None,
+        help="read the key from an Azure Key Vault secret URL "
+        "(https://<vault>.vault.azure.net/secrets/<name>) with the compute's managed identity",
+    )
+    ap.add_argument("--environment", default="ci", help="ci|jupyter|vscode|edge|api|cloud|cli")
+    ap.add_argument("--country-code", default="ZZ", help="data-residency region, e.g. EU, US")
+    ap.add_argument("--fail-on", default="high", help="low|medium|high|none")
+    ap.add_argument("--tee", default="amd_sev_snp", help="amd_sev_snp | kata_cc")
+    ap.add_argument("--snapshot-ref", default=None, help="stable source ref, e.g. git:repo@sha")
+    ap.add_argument("--commit", default=None, help="commit hash (default: from CI / .git)")
+    ap.add_argument("--timeout", type=float, default=1800.0, help="seconds to wait for the verdict")
+    ap.add_argument("--report-out", type=Path, default=None, help="write the full report JSON here")
+    ap.add_argument(
+        "--attestation-out",
+        type=Path,
+        default=None,
+        help="write the attestation JSON here (passing verdicts only)",
+    )
+    ap.add_argument(
+        "--markdown-out",
+        type=Path,
+        default=None,
+        help="append a markdown summary here (e.g. $GITHUB_STEP_SUMMARY)",
+    )
+    a = ap.parse_args(argv)
+
+    key = a.api_key or os.environ.get("CERTONE_API_KEY")
+    if not key and a.api_key_vault:
+        try:
+            key = key_from_vault(a.api_key_vault)
+        except Exception as exc:  # any vault/identity failure: report it, never the key
+            print(f"certone-submit: cannot read the key from Key Vault: {exc}", file=sys.stderr)
+            return 2
+    if not key:
+        print(
+            "certone-submit: no API key (pass --api-key, --api-key-vault or set CERTONE_API_KEY)",
+            file=sys.stderr,
+        )
+        return 2
+    if not a.project.is_dir():
+        print(f"certone-submit: {a.project} is not a folder", file=sys.stderr)
+        return 2
+
+    def submitted(scan_id: str, digest: str) -> None:
+        print(
+            f"submitted {a.asset!r} for confidential processing: scan {scan_id} ({digest})",
+            flush=True,
+        )
+
+    print(f"CertOne: packing {a.project.resolve().name} -> {a.api}", flush=True)
+    try:
+        sub = submit_and_wait(
+            CertOneClient(a.api, key),
+            a.project,
+            asset=a.asset,
+            environment=a.environment,
+            country_code=a.country_code,
+            fail_on=a.fail_on,
+            tee=a.tee,
+            snapshot_ref=a.snapshot_ref,
+            commit_hash=a.commit or _git_commit(a.project),
+            timeout=a.timeout,
+            on_submitted=submitted,
+            on_progress=ProgressPrinter(),
+        )
+    except CertOneError as exc:
+        print(f"certone-submit: {exc}", file=sys.stderr)
+        return 2
+    _print_result(sub, sys.stdout)
+    if a.report_out:
+        a.report_out.write_text(json.dumps(sub.document, indent=2), encoding="utf-8")
+    if a.attestation_out and sub.attestation:
+        a.attestation_out.write_text(json.dumps(sub.attestation, indent=2), encoding="utf-8")
+    if a.markdown_out:
+        with a.markdown_out.open("a", encoding="utf-8") as fh:
+            fh.write(_markdown(sub, a.asset))
+    return 0 if sub.passed else 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

certone_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.5
+Name: certone-sdk
+Version: 0.2.0
+Summary: CertOne SDK — typed API client, certone-submit (confidential scan + verdict gate) and the run-at-source agent.
+Project-URL: Homepage, https://certkor.ai
+Author: Certkor AI
+License: Proprietary
+Keywords: ai-compliance,certification,ci,confidential-computing,eu-ai-act
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31
+Provides-Extra: agent
+Requires-Dist: certone-engine>=0.1.0; extra == 'agent'
+Provides-Extra: azure
+Requires-Dist: azure-identity>=1.15; extra == 'azure'
+Requires-Dist: azure-keyvault-secrets>=4.7; extra == 'azure'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# certone-sdk
+
+The Python SDK and command-line tools for [CertOne](https://certkor.ai), Certkor's AI compliance
+certification platform. Send an AI project for a confidential scan from any pipeline, notebook,
+editor or device, gate on the verdict, and fetch the evidence and the attestation.
+
+CertOne evaluates the project inside a hardware-attested trusted execution environment (AMD SEV-SNP
+confidential VMs, or Kata confidential containers): it builds the AI bill of materials, checks it
+against the policy packs for the regions where the system runs (EU AI Act, NIST AI RMF, ISO/IEC
+42001, sector rules...), runs dynamic tests and computes the evaluation metrics.
+
+You need a CertOne tenant and an API key (Developer Hub -> API keys, `member` role).
+
+## Install
+
+```bash
+pip install certone-sdk
+```
+
+Python 3.10+. Extras: `certone-sdk[azure]` reads the API key from Azure Key Vault with the compute's
+managed identity.
+
+## Command line: `certone-submit`
+
+One command for any CI/CD system. It packs the project, submits it for a confidential scan, shows
+progress until the verdict, and exits `0` on pass, `1` on fail, `2` on error -- so the job stops on a
+failing certification.
+
+```bash
+export CERTONE_API_KEY=ck_...            # a tenant member key
+certone-submit --project . --asset "Fraud Scorer" --country-code EU --environment ci
+```
+
+| option | |
+|---|---|
+| `--asset` | AI system name in CertOne (required) |
+| `--country-code` | region the system operates in, e.g. `EU`, `US`, `CA` |
+| `--environment` | `ci`, `jupyter`, `vscode`, `edge`, `api`, `cloud`, `cli` |
+| `--tee` | `amd_sev_snp` (default) or `kata_cc` |
+| `--fail-on` | lowest severity that fails the gate: `low`, `medium`, `high` (default), `none` |
+| `--api` | platform URL (default `$CERTONE_API_URL`, else `https://platform.certkor.ai`) |
+| `--api-key-vault` | read the key from `https://<vault>.vault.azure.net/secrets/<name>` |
+| `--report-out`, `--attestation-out`, `--markdown-out` | write the report, the attestation (passing verdicts) or a markdown summary (e.g. `$GITHUB_STEP_SUMMARY`) |
+
+## Python
+
+```python
+import os
+from certone_sdk import CertOneClient, ProgressPrinter, submit_and_wait
+
+client = CertOneClient("https://platform.certkor.ai", os.environ["CERTONE_API_KEY"])
+sub = submit_and_wait(client, "rag-service", asset="RAG Answering Service", tee="kata_cc",
+                      country_code="EU", on_progress=ProgressPrinter())
+print(sub.verdict, sub.report["by_severity"])
+for issue in sub.document["issues"]:
+    print(issue["severity"], issue["description"])
+if sub.passed:
+    print(sub.attestation["attestation_id"])
+```
+
+The client also covers the rest of the API: `list_systems()`, `observability_summary()`,
+`get_run()` (where the scan executed and the TEE's hardware attestation), `get_report_document()`,
+`get_attestation()`.
+
+## Agent: `certone-agent`
+
+For devices and long-running services: keep certifying a project as it changes.
+
+```bash
+# re-scan confidentially whenever the project's content changes
+certone-agent watch --mode confidential --project /opt/model --asset "Line Robot Picker" \
+  --api https://platform.certkor.ai --environment edge --country-code EU --interval 600
+```
+
+`--mode local` runs the evaluation where the code lives and submits only the results (needs the
+CertOne engine, `certone-sdk[agent]`, available to CertOne customers). `certone-agent deliver`
+uploads a result signed inside an air-gapped network (`certone result sign`); the platform verifies
+it against the source keys registered for the tenant.
+
+## Licence
+
+Proprietary. Use requires a CertOne subscription; see https://certkor.ai.

certone_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+certone_sdk/__init__.py,sha256=7sVcWywbVzVTTjiH_xXPYn8NGktxEMAipZ3cMho8LGY,936
+certone_sdk/agent.py,sha256=p6551qG0KR7-qdUqHcKVgJ_G_JeCAoW1CuJUq7CNHso,10829
+certone_sdk/client.py,sha256=kfOYjp47LziXruFZtbgBjm4WOG6ysuvQinaZRinNyps,9672
+certone_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+certone_sdk/submit.py,sha256=cZKd9yAWUkErjCgJSbF_5bYfEgH1NH0IA1xZc0M7oUo,14654
+certone_sdk-0.2.0.dist-info/METADATA,sha256=SmWMcPIoo-c62kzSwuxUz5XFvZqHl6ktL-yEct4hapA,4891
+certone_sdk-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+certone_sdk-0.2.0.dist-info/entry_points.txt,sha256=uj_QGQNe5pBWMLWfbY9tHsMwGf6GsGr-MPYdDBIPH_c,98
+certone_sdk-0.2.0.dist-info/RECORD,,

certone_sdk-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

certone_sdk-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+certone-agent = certone_sdk.agent:main
+certone-submit = certone_sdk.submit:main