subvectors 0.2.0__tar.gz

subvectors-0.2.0/.gitattributes

@@ -0,0 +1,10 @@
+# Normalize line endings to LF in the repo (kills the CRLF churn on Windows).
+* text=auto eol=lf
+
+# Explicitly text
+*.py    text eol=lf
+*.json  text eol=lf
+*.toml  text eol=lf
+*.md    text eol=lf
+*.yml   text eol=lf
+*.yaml  text eol=lf

subvectors-0.2.0/.github/dependabot.yml

@@ -0,0 +1,39 @@
+# Dependabot configuration - deliberately low-noise.
+#
+# Non-major updates arrive as ONE grouped PR per ecosystem per month.
+# Security updates stay ungrouped and uncooled so they land fast.
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 5
+    cooldown:
+      default-days: 7
+      semver-major-days: 30
+    groups:
+      python-non-major:
+        applies-to: version-updates
+        patterns:
+          - "*"
+        update-types:
+          - "minor"
+          - "patch"
+    labels:
+      - "dependencies"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 3
+    cooldown:
+      default-days: 7
+    groups:
+      actions-all:
+        applies-to: version-updates
+        patterns:
+          - "*"
+    labels:
+      - "dependencies"

subvectors-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+# Nothing in this workflow writes anywhere: tests are pure-offline and the
+# GITHUB_TOKEN is never used. A repo about CI/CD OIDC trust conditions should
+# hold itself to least privilege.
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      # The editable install exercises the hatchling packaging path and
+      # enforces the dev floors from pyproject instead of hand-picking
+      # pytest + jsonschema versions here.
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests
+        run: python -m pytest -q
+      # The README coverage table is generated from vectors/ - a vector change
+      # without a regenerated table is silent doc drift.
+      - name: README coverage table is current
+        run: |
+          python scripts/coverage.py --write
+          git diff --exit-code README.md

subvectors-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,58 @@
+name: Release
+
+# Publishes to PyPI via OIDC trusted publishing (no stored API token) - the
+# same short-lived-token mechanism this corpus exists to judge. Fires when a
+# GitHub Release is published; INERT until one exists. PyPI side is configured
+# once as a pending publisher: pypi.org -> owner Dashtid, repository
+# subvectors, workflow release.yml, environment pypi.
+#
+# [!] GATE before the first Release: decide vectors/ packaging. Today
+# [tool.hatch.build.targets.wheel] ships only src/subvectors - a wheel
+# WITHOUT the corpus, which for a corpus project is an empty shell. See
+# ROADMAP "What is actually open".
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write # OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
+        with:
+          name: dist
+          path: dist/
+      # Deliberately a moving branch, per pypa's own guidance: it tracks
+      # security fixes in the publish action; SHA-pinning here would freeze
+      # them. The job has no other write surface (id-token only).
+      - uses: pypa/gh-action-pypi-publish@release/v1

subvectors-0.2.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+.coverage
+htmlcov/
+
+# Secrets / real cloud data — never commit live trust policies, tokens, or account data
+.env
+.env*.local
+*.pem
+credentials*
+real-*/        # keep only sanitized fixtures under fixtures/; real org exports go here, ignored
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Private Claude Code build-session context — kept in-repo, not published
+CLAUDE.md
+.claude/

subvectors-0.2.0/ARCHITECTURE.md

@@ -0,0 +1,173 @@
+# How subvectors works
+
+A plain-language tour, for picking the project back up after time away.
+
+## The one thing to hold onto
+
+**subvectors is not a tool. It is a pile of test data.**
+
+That is the single most confusing thing about it, so it's worth saying plainly. There is Python in
+this repo, but the Python is *not the product* — it exists only to prove the data is correct. The
+product is the JSON in `vectors/`.
+
+The closest analogy: a **standard test fire** used to certify smoke detectors. It isn't a smoke
+detector and doesn't compete with any. It's the thing you test detectors *against*.
+
+## The problem it exists for
+
+When a CI pipeline authenticates to a cloud, the entire security boundary is one string comparison:
+the token's `sub` claim versus an admin-written matching rule.
+
+```
+   subject (what the pipeline presents)      condition (the admin's rule)
+   repo:acme/payments-api:pull_request   vs   repo:acme/payments-api:*
+```
+
+The catch: **that comparison means different things to different clouds.** The same rule is a
+wildcard glob to AWS `StringLike`, dead literal text to AWS `StringEquals`, dead literal text to
+classic Azure FIC, and a typed expression to GCP.
+
+Every security scanner (Checkov, Prowler, Wiz, …) has to re-implement this comparison, and they all
+work it out alone from prose docs. They get it wrong. subvectors is a **shared answer key** so they
+don't have to guess — and so their mistakes become visible.
+
+Crucially it **grades scanners rather than competing with them**. A new scanner is a new *consumer*
+of the corpus, not a rival. Same reason Wycheproof tests everyone's crypto.
+
+## What a vector is
+
+One vector is one falsifiable test case. From `vectors/github-aws.json`:
+
+```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"
+  },
+  "sources": ["https://docs.github.com/..."],
+  "status": "documented"
+}
+```
+
+Read it as: *"an issuer minted this subject; an admin wrote this rule; here is whether they match;
+here is whether the rule is safe; here is the doc that proves it."*
+
+Three separable layers, deliberately kept apart:
+
+1. **Grammar** — is the subject well-formed for its issuer?
+2. **Match** — does it satisfy the condition? *Mechanically checkable.* The matcher decides this.
+3. **Judgment** — is the condition *safe*? *A human opinion with a citation.* The matcher never
+   reads it, so a consumer who disagrees with a grade can strip judgment and still use layers 1–2.
+
+Two fields carry the honesty:
+- **`sources`** — every vector cites a primary source. Required by the schema.
+- **`status`** — `documented` (derived from docs) vs `observed` (confirmed against a real
+  issuer/cloud). **All vectors are currently `documented`.** Closing that gap is the highest-value
+  work available; see `BACKLOG.md`.
+
+## The files
+
+```
+vectors/           <- THE PRODUCT. 13 suites, 127 vectors. CC0-licensed.
+  github-aws.json        one file per (issuer x cloud) pair
+  github-azure.json      github/gitlab/bitbucket/circleci/terraform x aws/azure/gcp
+  ...
+  schema/                JSON Schema every vector must validate against
+  LICENSE                CC0-1.0 - copy these freely, no attribution needed
+
+src/subvectors/    <- THE ORACLE. ~865 lines. Proves the vectors are self-consistent.
+  matcher.py             satisfies(subject, condition) -> bool. The entry point.
+  cel.py                 mini CEL evaluator (GCP conditions are CEL expressions)
+  ffl.py                 mini expression evaluator (Azure flexible FIC, preview)
+  github.py              GitHub subject grammar (legacy + immutable @id formats)
+  gitlab.py              GitLab subject grammar (project_path + project_id forms)
+
+tests/             <- THE PROOF.
+  test_vectors.py        runs EVERY vector through the matcher, asserts `expect`
+  test_matcher.py        unit tests for the matching semantics
+  test_cel.py            CEL evaluator tests
+  ...
+
+docs/
+  JUDGMENT-CATALOG.md    the graded over-permission patterns
+```
+
+## How the matcher works
+
+`matcher.py` answers exactly one question: **does subject S satisfy condition C?**
+
+Each `condition` names a **consumer** — which cloud's matching rules to apply:
+
+| Consumer | Semantics |
+|---|---|
+| `aws-stringlike` | Glob. `*` = any characters, and it **spans `/` and `:`** — which is precisely why `repo:org/*` admits every repo in the org. |
+| `aws-stringequals` | Exact equality. `*` is a literal character, so `repo:org/*` matches *nothing real*. |
+| `azure-fic-exact` | Exact equality too — classic Azure FIC supports no wildcards at all. Opposite of AWS `StringLike`, from an identical-looking config. |
+| `gcp-cel` | Not a string comparison. A CEL expression over the whole claim set, evaluated by `cel.py`. |
+| `azure-fic-flexible` | Azure's preview expression language; wildcards are back. Evaluated by `ffl.py`. |
+| `aws-all` | A composite: a full IAM Condition block, ANDing several AWS sub-conditions. |
+
+Two behaviours worth remembering because they're where real bugs live:
+
+- **Values are OR'd (AWS only).** A condition may carry a *list* of patterns, and IAM ORs them — so
+  **one loose value poisons an otherwise tight list.**
+- **Unsupported consumers raise, never return False.** A vector can never pass by being silently
+  unmatched.
+
+## How to run it
+
+```bash
+pytest -q        # runs every vector through the matcher
+```
+
+That's the whole loop. If a vector's `expect` disagrees with the matcher, the suite goes red — so
+either the vector is wrong or the matcher is. Nothing else to start; there's no server, no CLI, no
+cloud account.
+
+## What it deliberately does NOT do
+
+Guardrails, not gaps. See the Scope section of `CONTRIBUTING.md`.
+
+- **Not a scanner, not a PR gate, no reachability graphs.** That was the original `oidc-reach` plan
+  and it was **killed on 2026-07-05** — the value decayed on a ~6-month incumbent fuse. If you find
+  a doc still describing this project as a "PR gate," that doc is stale.
+- **No runtime dependencies.** A consumer should be able to read or vendor the oracle, not have to
+  trust a package.
+- **It does not depend on subcheck** and never will. subcheck consumes *these* vectors as test
+  fixtures; the arrow points one way. An answer key can't depend on one of its students.
+
+## How success is measured
+
+**Bugs found and upstream PRs merged.** Not vector count.
+
+Vectors added is an *input*. A tranche that surfaces no bug and no adoption is a signal to stop, not
+progress. Cataloguing for its own sake is the named failure mode ("the librarian trap") — see
+`ROADMAP.md`.
+
+## Known issues
+
+Recorded here so they aren't rediscovered later (from the 2026-07-30 verification pass).
+Still open:
+
+- **Azure "fails silently, no error" is only half right.** *Creation* of a FIC is unvalidated and
+  silent; *token exchange* returns `AADSTS700213`. Still to correct in `matcher.py` and several
+  Azure vector files. (`ROADMAP.md` was corrected in `42285eb` and now states it correctly.)
+- **README says vectors carry a `documented` vs `observed` status**, implying a mix. All are
+  currently `documented`.
+
+Resolved:
+
+- **`RepoSegment.immutable` in `github.py` used `or`. FIXED 2026-08-18** — it is now `and`, since
+  GitHub emits `@id` on both segments or neither, so a one-sided subject is *malformed*, not
+  immutable. The branch was reachable (both id groups in `_REPO_RE` are independently optional, so
+  one-sided input parses); it is now covered by two unit tests. **subcheck had the identical bug
+  and fixed it first**: `decoder.py` shipped `"immutable" if (owner_id or repo_id) else "legacy"`
+  in `34a42ce` (2026-07-21) and corrected it to a three-state `immutable`/`malformed`/`legacy`
+  classification in `423964f` (2026-07-30). This repo lagged that correction by three weeks; the
+  two now agree on every input shape. `immutable` stays a two-state boolean here, so a one-sided
+  subject reads the same as a legacy one; `owner_id`/`repo_id` still distinguish them.