# ocx_sdk

*module*

Python SDK for [OCX](https://github.com/ocx-sh/ocx).

`ocx-sdk` drives the ocx binary rather than reimplementing it: ocx owns
resolution, verification, and the identifier grammar, and this package gives
you typed, CWD-independent handles over the commands it exposes.

```python
from ocx_sdk import Ocx, bootstrap

ocx = Ocx(exe=bootstrap.ensure())
project = ocx.project("/srv/build")
project.pull()
project.exec(["task", "verify"])
```

**This module is the API.** Everything listed in `__all__` is the stable
surface; every other module is underscored and package-private, and the one
public submodule is `ocx_sdk.bootstrap`. Reaching into an underscored path
means the next release may move it without notice — pre-1.0, breaking
changes ship without shims.

Start at `Ocx` for the runtime API and `bootstrap.ensure` for provisioning.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/__init__.py#L1-L1)

## ocx_sdk.SignatureEntry

*class* · *dataclass*

```python
class SignatureEntry
```

Re-exported from: `ocx_sdk._results`

One signature `verify` found on the inspected object (C-012).

Field list verified against `verification.rs:50-85`.

**Attributes**

- `signature_format` (`str`) — Which format this entry is, carried as raw `str` (D8).
- `discovery_method` (`str`) — How ocx found it — referrer API or sidecar tag, carried as raw `str` (D8).
- `key_backend` (`str`) — Which key backend verified it, carried as raw `str` (D8).
- `referrer_digest` (`str`) — This signature's own digest. **Not always a manifest digest** — for a simplesigning sidecar it is a layer blob digest; feeding it to a manifest fetch 404s.
- `certificate_identity` (`str | None`) — The Fulcio certificate's identity, when the signature is keyless.
- `certificate_oidc_issuer` (`str | None`) — The Fulcio certificate's OIDC issuer, when the signature is keyless.
- `signed_at` (`str | None`) — When the signature was produced, as ocx spelled it, when present.
- `rekor_log_index` (`int | None`) — The Rekor entry index, when present. **Named differently from `SignatureReport`/`AttestationReport`'s `transparency_log_index`** — same concept, two wire names, and unlike those two structs this field is absent rather than always-present-nullable. Do not unify the handling.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_results.py#L1648-L1698)

### ocx_sdk.SignatureEntry.signature_format

*attribute* · *instance attribute*

```python
signature_format: str
```

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_results.py#L1677-L1677)

## ocx_sdk.SignatureLegReport

*class* · *dataclass*

```python
class SignatureLegReport
```

Re-exported from: `ocx_sdk._results`

One signature format's outcome within a `SignatureReport` (C-011).

**Attributes**

- `format` (`str`) — The signature format this leg produced — `"bundle"` or `"simplesigning"` (`signature.rs:89`; `"both"` is write-side only — it requests two legs, never labels one), carried as raw `str` (D8).
- `payload_digest` (`str | None`) — Digest of the signed payload, when this leg landed.
- `manifest_digest` (`str | None`) — Digest of the manifest the signature attaches to, when this leg landed.
- `error` (`str | None`) — Why this leg failed, when it did. A `--signature-format both` run where one leg lands and one fails names the failed leg here (D10) — recover the whole report with `partial_report(err)`.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_results.py#L1535-L1565)

### ocx_sdk.SignatureLegReport.error

*attribute* · *class attribute* · *instance attribute*

```python
error: str | None = None
```

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_results.py#L1555-L1555)

### ocx_sdk.SignatureLegReport.format

*attribute* · *instance attribute*

```python
format: str
```

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_results.py#L1552-L1552)

### ocx_sdk.SignatureLegReport.manifest_digest

*attribute* · *class attribute* · *instance attribute*

```python
manifest_digest: str | None = None
```

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_results.py#L1554-L1554)

### ocx_sdk.SignatureLegReport.payload_digest

*attribute* · *class attribute* · *instance attribute*

```python
payload_digest: str | None = None
```

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_results.py#L1553-L1553)

### ocx_sdk.SignatureLegReport.from_dict

*method* · *classmethod*

```python
def from_dict(data: Mapping[str, Any]) -> SignatureLegReport
```

Build from one decoded entry of `SignatureReport.legs`.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_results.py#L1557-L1565)