Metadata-Version: 2.5
Name: subvectors
Version: 0.4.2
Summary: Reference matcher for OIDC CI/CD trust-condition conformance vectors
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Provides-Extra: dev
Requires-Dist: jsonschema>=4.18; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# subvectors

[![PyPI](https://img.shields.io/pypi/v/subvectors)](https://pypi.org/project/subvectors/)
[![CI](https://github.com/Dashtid/subvectors/actions/workflows/ci.yml/badge.svg)](https://github.com/Dashtid/subvectors/actions/workflows/ci.yml)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue.svg)](pyproject.toml)

**Conformance vectors for OIDC trust subjects — the answer key for CI/CD OIDC trust decisions: a
cited, versioned test-vector suite answering "does subject S satisfy trust condition C, and is C
safe?"**

When a CI pipeline authenticates to a cloud via OIDC (GitHub Actions to AWS/Azure/GCP today), the
entire security boundary is a string comparison: the token's `sub` claim versus an admin-written
matching rule — an AWS IAM trust-policy condition, an Azure federated-identity-credential (FIC)
subject, a GCP Workload Identity Federation attribute condition. Every security tool in this space
must re-implement that comparison and judge those rules. They re-figure it out alone, and they get
it wrong.

> Status: v0.4.2 on PyPI - the corpus ships inside the wheel. An independent personal
> project, built on personal time and personal equipment. Every vector is source-cited, and
> the AWS tranche is now `observed` against live AWS - each of those vectors links a committed
> transcript under [`observations/`](observations/) holding the exact request and the verbatim
> response, so the claim is auditable without an AWS account. The generated
> [Coverage](#coverage) block carries the exact `documented`/`observed` split.

## The proof this is needed (verified 2026-07-04)

Checkov — one of the most widely used IaC security scanners — ships the only Azure FIC subject
check anywhere (`CKV_AZURE_249`). Read against its own source:

- It PASSES `repo:org/*` (any repo in the org may assume the role) and
  `repo:org/repo:pull_request` (unreviewed PR code may) — dangerous patterns waved through.
- Its repo regex has no `@` in the charset, so it will FAIL every valid immutable-format subject
  (`repo:owner@123456/name@456789:...`) — the format GitHub makes mandatory for repos created
  after **2026-07-15**.

The formats churn (GitHub immutable claims, Azure flexible-FIC expressions in preview, per-issuer
dialects from GitLab/Bitbucket/CircleCI), and every scanner re-derives the semantics from prose
docs. A single maintained, cited corpus of test vectors fixes that for everyone.

## What a vector looks like

```json
{
  "id": "gh-aws-0007",
  "issuer": "github",
  "subject": "repo:acme/webapp:pull_request",
  "condition": { "consumer": "aws-stringlike", "pattern": "repo:acme/webapp:*" },
  "expect": "match",
  "judgment": {
    "grade": "dangerous",
    "reason": "pattern admits pull_request runs, which execute unmerged proposed changes rather than the protected default branch"
  },
  "sources": ["https://docs.github.com/en/actions/deployment/security-hardening-your-deployments"],
  "status": "documented"
}
```

Three layers per vector:

1. **Grammar** — is the subject well-formed for its issuer (classic AND immutable GitHub formats)?
2. **Match semantics** — does it satisfy the consumer's condition (AWS `StringLike`/`StringEquals`
   globbing, Azure FIC exact match + flexible expressions, GCP CEL)?
3. **Judgment** — is the condition safe? Graded findings for the patterns that matter:
   `pull_request` subjects, unprotected refs, wildcarded repos/orgs, missing `aud` pinning. The
   graded patterns are a stable, citable vocabulary — see
   [`docs/JUDGMENT-CATALOG.md`](docs/JUDGMENT-CATALOG.md).

Every vector carries a source citation and a provenance status — `documented` (derived from
primary documentation) or `observed` (recorded from a live exchange). The current split is
generated under [Coverage](#coverage) rather than asserted here, so it cannot drift. A ~100-line
reference matcher (Python, pytest) passes the suite — it is a correctness oracle, not a product.

## Coverage

<!-- COVERAGE:START (generated by scripts/coverage.py -- run `python scripts/coverage.py --write`) -->

**14 suites - 133 vectors** across 5 issuers and 6 consumer semantics.

Vectors by issuer x cloud-consumer semantics:

| Issuer | aws-stringlike | aws-stringequals | aws-all | azure-fic-exact | azure-fic-flexible | gcp-cel | Total |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `github` | 12 | 15 | 5 | 10 | 8 | 12 | **62** |
| `gitlab` | 5 | 5 | 6 | 6 | 5 | 6 | **33** |
| `bitbucket` | 1 | 2 | 3 | - | - | - | **6** |
| `circleci` | 4 | - | 3 | - | - | 6 | **13** |
| `terraform-cloud` | 3 | 3 | 1 | - | 6 | 6 | **19** |
| **Total** | **25** | **25** | **18** | **16** | **19** | **30** | **133** |

Suites:

- `bitbucket-aws` 0.1.0 - 6 vectors
- `circleci-aws` 0.1.0 - 7 vectors
- `circleci-gcp` 0.1.0 - 6 vectors
- `github-aws` 0.4.2 - 32 vectors
- `github-azure-flexible` 0.1.0 - 8 vectors
- `github-azure` 0.1.0 - 10 vectors
- `github-gcp` 0.1.0 - 12 vectors
- `gitlab-aws` 0.2.0 - 16 vectors
- `gitlab-azure-flexible` 0.1.0 - 5 vectors
- `gitlab-azure` 0.1.0 - 6 vectors
- `gitlab-gcp` 0.1.0 - 6 vectors
- `terraform-aws` 0.1.0 - 7 vectors
- `terraform-azure-flexible` 0.1.0 - 6 vectors
- `terraform-gcp` 0.1.0 - 6 vectors

Judgments: 30 safe - 45 caution - 36 dangerous - 22 ungraded (mechanical no-match / contrast vectors carry no safety grade).

Provenance: 122 `documented` - 11 `observed`.

<!-- COVERAGE:END -->

## Install

```bash
pip install subvectors
```

The wheel ships the entire corpus, so a consumer pins a versioned artifact
instead of vendoring JSON by hand:

```python
from subvectors import corpus

corpus.suite_names()                 # ['bitbucket-aws', ..., 'terraform-gcp']
corpus.load_suite("github-aws")      # one suite, parsed
corpus.load_schema()                 # the JSON Schema the suites validate against
```

Prefer no dependency at all? The vectors are plain JSON under `vectors/` —
clone and read. The corpus itself is CC0 (`vectors/LICENSE`).

## Why an answer key instead of another scanner

Scanners in this space compete and get obsoleted: SpecterOps GitHound already maps
workflow-to-cloud OIDC reach, Prowler shipped a GitHub provider (2026-07-02), Wiz and Datadog are
converging. A test-vector suite does
not compete with scanners — it grades them. Each new tool entering the space is a new consumer of
the corpus, the way Wycheproof tests everyone's cryptography and the JSON-Schema-Test-Suite tests
everyone's validators. Consumers keep their own matching code (no runtime dependency to trust) and
import the vectors at test time.

Bugs the vectors expose in real tools get fixed by upstream PRs (Checkov's OIDC check family,
Cartography's unparsed trust-policy conditions) — the distribution channel and the proof, in one.

## Scope order

GitHub issuer + AWS consumer first, Azure FIC as the depth tranche (its exact-match and
flexible-expression semantics are the least-tooled corner), then GCP CEL and non-GitHub issuers.
Fully offline: JSON vectors + pytest, no cloud account required.

## Why this project exists (for me)

Closes a specific, recurring gap: multi-cloud IAM / OIDC trust-boundary depth (AWS + **Azure**).
Writing a falsifiable, cited test case about a trust rule forces genuinely understanding the rule
— active-recall learning with a public artifact as the receipt.

## License

Dual-licensed to maximize adoptability:

- **Vector data (`vectors/`) — CC0-1.0** (public-domain dedication). Embed the vectors in your
  tool's test suite with zero attribution or licensing friction — that frictionlessness is the
  point. See [`vectors/LICENSE`](vectors/LICENSE).
- **Everything else** (the reference matcher, schema, docs) **— Apache-2.0**. See
  [`LICENSE`](LICENSE).
