certone-sdk 0.2.0__tar.gz

certone_sdk-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/

certone_sdk-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,82 @@
+# 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/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-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())