Add Baseline Level 3 paperwork, SBOM, and SCA tooling

Phase A (paperwork):
- SECURITY.md: explicit Scope of Support and Duration of Support
  language; new Secrets and Credentials Policy section that lays out
  the no-long-lived-secrets stance (OIDC for PyPI, OAuth for RTD,
  zero GitHub Actions secrets configured). Closes OSPS-BR-07.02,
  OSPS-DO-04.01, OSPS-DO-05.01.
- VERIFICATION.md: how downstream consumers verify a release.
  Covers SHA-256 hash verification, PEP 740 attestation verification
  via pypi-attestations CLI, and SBOM verification. Closes
  OSPS-DO-03.01 and OSPS-DO-03.02.
- SECURITY_POLICIES.md: combined SAST and SCA policies. CVSS-based
  remediation thresholds, release-blocking criteria, suppression
  rules, license compliance posture. Closes OSPS-VM-05.01,
  OSPS-VM-05.02, and OSPS-VM-06.01.
- contributing.rst: 'Automated Tests' becomes 'Testing Policy' with
  MUST language for major changes and an explicit definition of
  what counts as major. Closes OSPS-QA-06.03.

Phase B (tooling):
- publish.yml: CycloneDX SBOM generation step that installs the
  built wheel into an isolated venv, snapshots it with
  cyclonedx-py, and attaches the resulting bitmath-<version>.cdx.json
  to the GitHub release alongside the wheel and sdist. Closes
  OSPS-QA-02.02.
- sca.yml: new workflow that runs pip-audit (PyPA's official audit
  tool) against requirements.txt on every push and pull request.
  Pinned to v1.1.0 by SHA. Needs to be added to required status
  checks on master to enforce blocking. Closes OSPS-VM-05.03.

ARCHITECTURE.md and SECURITY_ASSESSMENT.md headers were also
title-cased to align with the project documentation header
conventions; cross-references were verified intact.

Author: timlnx

.github/workflows/publish.yml

@@ -18,6 +18,16 @@ jobs:
           python-version: "3.12"
       - name: Build package
         run: pip install build && python -m build
+      - name: Generate CycloneDX SBOM
+        run: |
+          pip install cyclonedx-bom
+          VERSION=$(cat VERSION)
+          python -m venv /tmp/sbom-env
+          /tmp/sbom-env/bin/pip install --upgrade pip
+          /tmp/sbom-env/bin/pip install --no-deps dist/*.whl
+          cyclonedx-py environment /tmp/sbom-env/bin/python \
+            --output-format JSON \
+            --output-file "dist/bitmath-${VERSION}.cdx.json"
       - name: Upload dist artifacts
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
@@ -30,6 +40,7 @@ jobs:
     environment: pypi
     permissions:
       id-token: write
+      contents: write
     steps:
       - name: Download dist artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -38,3 +49,13 @@ jobs:
           path: dist/
       - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          # Keep the SBOM out of the PyPI upload; it ships on the GitHub release instead.
+          packages-dir: dist/
+          skip-existing: false
+      - name: Attach SBOM to GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          gh release upload "$TAG" dist/bitmath-*.cdx.json --clobber --repo "$GITHUB_REPOSITORY"

.github/workflows/sca.yml

@@ -0,0 +1,32 @@
+---
+name: SCA Security Scan
+
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+  schedule:
+    - cron: "0 0 * * 0"
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Audit dev dependencies with pip-audit
+        uses: pypa/gh-action-pip-audit@1220774d901786e6f652ae159f7b6bc8fea6d266 # v1.1.0
+        with:
+          inputs: requirements.txt

ARCHITECTURE.md

@@ -8,15 +8,15 @@
 
 ## Contents
 
-- [Why this document exists](#why-this-document-exists)
-- [Runtime architecture](#runtime-architecture)
-- [Build and release pipeline](#build-and-release-pipeline)
-- [CI and quality gates](#ci-and-quality-gates)
-- [Trust boundaries](#trust-boundaries)
-- [Documentation pipeline](#documentation-pipeline)
+- [Why This Document Exists](#why-this-document-exists)
+- [Runtime Architecture](#runtime-architecture)
+- [Build and Release Pipeline](#build-and-release-pipeline)
+- [CI and Quality Gates](#ci-and-quality-gates)
+- [Trust Boundaries](#trust-boundaries)
+- [Documentation Pipeline](#documentation-pipeline)
 - [Maintenance](#maintenance)
 
-## Why this document exists
+## Why This Document Exists
 
 This is the architecture map for bitmath. It exists so downstream
 consumers and future contributors can see, in one place, what the
@@ -40,9 +40,9 @@ adding a new public function, restructuring the class hierarchy,
 changing the build backend, or changing how releases get published.
 No, if you are fixing a bug or adding a test.
 
-## Runtime architecture
+## Runtime Architecture
 
-### Component inventory
+### Component Inventory
 
 The runtime library is a single Python module, `bitmath`, deliberately
 kept small. Almost all the logic lives in `bitmath/__init__.py`. The
@@ -58,7 +58,7 @@ actors that show up at runtime:
 | Constants | `bitmath.NIST`, `bitmath.SI`, `bitmath.NIST_PREFIXES`, `bitmath.SI_PREFIXES`, `bitmath.ALL_UNIT_TYPES` | Module-level lookup tables and system identifiers |
 | OS abstraction layer | Standard library: `shutil`, `os`, `fcntl` (Linux), `ctypes` (Windows) | Platform-specific calls used by the capacity-query functions |
 
-### Layered view
+### Layered View
 
 ```
 +--------------------------------------------------------------+
@@ -141,7 +141,7 @@ consumer triggers them:
    elevated privileges on Linux (root) and Windows (administrator);
    macOS raises `NotImplementedError`.
 
-### Data flow
+### Data Flow
 
 Untrusted input enters the library at exactly three runtime places:
 the string parsers (`parse_string`, `parse_string_unsafe`), the
@@ -153,9 +153,9 @@ what bitmath does and does not validate at each entry point. See
 [SECURITY_ASSESSMENT.md](SECURITY_ASSESSMENT.md) for the full threat
 model.
 
-## Build and release pipeline
+## Build and Release Pipeline
 
-### Component inventory
+### Component Inventory
 
 | Actor | Lives at | What it does |
 |-------|----------|--------------|
@@ -170,7 +170,7 @@ model.
 | PyPI | pypi.org | The distribution channel; serves wheels and sdists over HTTPS to `pip` |
 | Read The Docs | bitmath.readthedocs.io | Hosts the rendered documentation; rebuilds on push to master |
 
-### Pipeline view
+### Pipeline View
 
 ```
                   +------------------------+
@@ -249,7 +249,7 @@ model.
    against the published SHA-256 hash, and installs into their
    environment.
 
-## CI and quality gates
+## CI and Quality Gates
 
 CI runs continuously on `master` and on every pull request. These
 actors influence what is merged but do not produce released
@@ -269,7 +269,7 @@ The first three are required status checks on the `master` branch.
 Merges are blocked until they pass. `enforce_admins: true` so I
 cannot bypass them.
 
-## Trust boundaries
+## Trust Boundaries
 
 bitmath validates input only at the places untrusted data enters the
 library. The ingress points are:
@@ -293,7 +293,7 @@ library. The ingress points are:
 See [SECURITY_ASSESSMENT.md](SECURITY_ASSESSMENT.md) for the full
 threat model and the specific mitigations at each boundary.
 
-## Documentation pipeline
+## Documentation Pipeline
 
 The documentation lives in `docsite/source/`. Sphinx builds it.
 `index.rst.in` is the source template; `index.rst` is generated from

SECURITY.md

@@ -13,6 +13,18 @@ As of the 2.0.0 re-factor only versions ≥ 2.0.0 will receive support. Versions
 | `≥ 2.0.0`   | :white_check_mark: |
 | `< 2.x.y`   | :x:              |
 
+### Scope of Support
+
+* **Security fixes** are issued as patch releases on the latest minor in the 2.x series. If the current line is 2.1.x, security fixes ship as 2.1.y.
+* **Bug fixes** are issued on the latest minor in the 2.x series. Older minors do not receive bug-fix backports unless the bug is also a security issue covered above.
+* **Functional changes** ship in new minor releases (2.x → 2.(x+1)).
+
+### Duration of Support
+
+* The **2.x series** receives security fixes for as long as it is the current major. Today that is open-ended; a future 3.x release would start a deprecation clock on 2.x with at least 12 months of overlap announced in `NEWS.rst` before 2.x support ends.
+* The **1.x series** (legacy) is end-of-life. No further releases will be made on 1.x. Users on 1.x should plan a migration to 2.x; the 2.x API is drop-in compatible for the documented public surface.
+* The **pre-1.x series** is historical and not supported in any form.
+
 This list will be updated when future releases are made in the 2-version series that require specific callouts for supportability.
 
 If you have discovered what you think is a harmful bug with the potential for exploitation in a supported version series, and this bug may lead to loss of life or data, then you have two options for reporting available to you:
@@ -52,3 +64,41 @@ As an emergency backup you can find me on bsky or instagram and direct message m
 * [insta - @tim.lnx](https://www.instagram.com/tim.lnx/)
 
 For less serious security issues with lower potential for exploitation or damage, please open a bug on the project and apply the `security` label to it.
+
+## Secrets and Credentials Policy
+
+bitmath is built around the principle that **no long-lived secrets should exist in the project**. The policy is short because the implementation is austere.
+
+### What Secrets the Project Handles
+
+* **PyPI publish authority** is handled via [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (OIDC). The publish workflow exchanges a short-lived GitHub Actions OIDC token for upload credentials at the moment of publication. There is no long-lived PyPI API token stored as a GitHub secret.
+* **Read The Docs build credentials** are managed by Read The Docs via OAuth integration with GitHub. No credentials are stored in this repo.
+* **The `bitmath@lnx.cx` email address** is a forwarding alias used only for security correspondence. Compromise of that mailbox does not affect any project resource directly.
+
+### Storage
+
+* No secret values are stored in the repository. GitHub secret scanning is enabled at the repository level and runs continuously.
+* No secret values are stored in `.github/workflows/*.yml`. The workflows authenticate via OIDC tokens, not stored credentials.
+* The list of GitHub Actions secrets configured on this repository is **empty**, verifiable with `gh api /repos/timlnx/bitmath/actions/secrets`.
+
+### Access Control
+
+* The single maintainer (see [MAINTAINERS.md](MAINTAINERS.md)) has admin access to the repository, the PyPI project, and the Read The Docs project.
+* The PyPI Trusted Publishing trust relationship is scoped to the `.github/workflows/publish.yml` workflow on `master`. Any other workflow or branch attempting to authenticate to PyPI as bitmath will be rejected.
+* Two-factor authentication is required on both the GitHub account (authenticator app + GitHub Mobile, SMS disabled) and the PyPI account.
+
+### Rotation
+
+* OIDC tokens are short-lived (minutes) and rotated automatically on every workflow run by GitHub Actions and PyPI.
+* No long-lived credentials exist, so there is no rotation schedule to maintain.
+* The Trusted Publisher trust relationship itself can be revoked or re-scoped via the PyPI web UI if the workflow file ever needs to change in a way that would alter the trust boundary.
+
+### Incident Response
+
+If a project secret or credential is suspected to be compromised:
+
+1. Revoke the Trusted Publisher relationship on PyPI immediately, before doing anything else. This breaks any in-flight publish attempt by an attacker.
+2. Audit recent activity in GitHub Actions runs and PyPI release history for unexpected events. The PyPI publish journal and GitHub Actions logs are public and inspectable.
+3. Reach out through the reporting channels above so the incident can be coordinated and disclosed.
+
+This policy is reviewed at every minor release.

SECURITY_ASSESSMENT.md

@@ -99,7 +99,7 @@ and operate on a descriptor the consumer has already opened.
   Protection model makes the call meaningless. There is no codepath
   to exploit there because there is no codepath at all.
 
-### 4. The build and release pipeline
+### 4. The Build and Release Pipeline
 
 The build pipeline itself is an attack surface: if the publishing
 workflow could be tricked into emitting a malicious wheel, every

SECURITY_POLICIES.md

@@ -0,0 +1,126 @@
+# Security Policies
+
+This document defines bitmath's policies for handling findings from
+Software Composition Analysis (SCA), Static Application Security
+Testing (SAST), and license compliance scanning. It exists so
+downstream consumers can understand the project's commitments and so
+future maintainers can apply the policies consistently.
+
+The threat model that motivates these policies is in
+[SECURITY_ASSESSMENT.md](SECURITY_ASSESSMENT.md). The vulnerability
+reporting process is in [SECURITY.md](SECURITY.md). The release
+verification process is in [VERIFICATION.md](VERIFICATION.md). The
+workflows that enforce these policies live in `.github/workflows/`.
+
+## Software Composition Analysis (SCA)
+
+SCA covers known vulnerabilities and license compliance in
+bitmath's dependencies. Because bitmath has **zero runtime
+dependencies** (verifiable in `pyproject.toml`), the operational
+scope of SCA is the development dependency set listed in
+`requirements.txt`.
+
+### Tools
+
+* **Dependabot** opens pull requests for dependency updates and
+  surfaces known vulnerabilities. Configured in
+  `.github/dependabot.yml`.
+* **pip-audit** runs on every push and pull request via
+  `.github/workflows/sca.yml` against `requirements.txt`. The
+  workflow is a required status check on `master`.
+* **GitHub secret scanning** (enabled at the repository level)
+  catches credentials accidentally committed to the repository.
+
+### Remediation Thresholds
+
+Severity ratings follow the CVSS score reported by the SCA tool.
+The remediation clock starts when the finding becomes visible in
+the project (Dependabot alert or `pip-audit` CI failure).
+
+| Severity | CVSS range | Action | Timeline |
+|----------|-----------|--------|----------|
+| Critical | 9.0 – 10.0 | Patch or replace the affected dependency. Block any release until remediated. | Within 7 days of disclosure |
+| High | 7.0 – 8.9 | Patch or replace the affected dependency. Block release if the next release is within 30 days; otherwise remediate before that release. | Within 30 days of disclosure |
+| Medium | 4.0 – 6.9 | Patch when the next dependency update naturally cycles through. | Within 90 days |
+| Low | 0.1 – 3.9 | Patch opportunistically. | Best effort |
+
+A finding may be suppressed only when it is demonstrably
+non-exploitable in bitmath's usage of the dependency. Suppression is
+documented inline in the SCA workflow configuration with a comment
+explaining why.
+
+### Release Blocking
+
+A release of bitmath **MUST NOT** ship while a Critical or High SCA
+finding against a dev dependency is unaddressed, unless the finding
+has been formally suppressed as non-exploitable per the rule above.
+The `.github/workflows/sca.yml` status check enforces this on the
+merge path; the release process (see
+[ARCHITECTURE.md](ARCHITECTURE.md)) is gated by the same branch
+protection.
+
+### License Compliance
+
+All direct dependencies must use a license listed as
+[OSI-approved](https://opensource.org/licenses) or
+[FSF-approved](https://www.gnu.org/licenses/license-list.html).
+Today every dev dependency uses MIT, Apache 2.0, or BSD. Adding a
+new dev dependency that introduces a copyleft license (GPL, AGPL,
+LGPL) requires explicit consideration before being merged; the PR
+that introduces it must document the decision in the description.
+
+## Static Application Security Testing (SAST)
+
+SAST covers security weaknesses in bitmath's own source code.
+
+### Tools
+
+* **Bandit** scans `bitmath/` and `tests/` for common Python
+  security smells. Runs on every push and pull request via
+  `.github/workflows/bandit.yml`. Required status check.
+* **CodeQL** performs semantic analysis for Python vulnerabilities.
+  Runs on every push, pull request, and weekly via
+  `.github/workflows/codeql.yml`. Required status check.
+* **OSSF Scorecard** performs a weekly meta-analysis of repository
+  security posture. Reports to the GitHub Security tab.
+
+### Remediation Thresholds
+
+| Severity | Action | Timeline |
+|----------|--------|----------|
+| High | Fix in the next patch release. Block any merge that introduces a new High finding. | Within 7 days for existing findings; immediately for new ones |
+| Medium | Fix in the next minor release. | Within 30 days |
+| Low | Address in the normal development cycle. | Best effort |
+| Informational | Triage and either fix or suppress with a justifying comment. | Best effort |
+
+A finding may be suppressed only when it is a true false positive.
+The suppression must include a `# nosec` comment with an inline
+justification (Bandit) or a `# lgtm[py/...]` annotation (CodeQL)
+explaining the rationale. The justification should be specific
+enough that a future maintainer can re-evaluate the suppression
+without re-deriving the analysis.
+
+### Release Blocking
+
+A release of bitmath **MUST NOT** ship while any High SAST finding
+against the project's own code is unaddressed, unless the finding is
+formally suppressed as a false positive per the rule above. The
+Bandit and CodeQL required status checks enforce this on the merge
+path.
+
+## Review and Updates
+
+This policy is reviewed at every minor release. The contract:
+
+* A new SAST or SCA tool added to CI → update the corresponding
+  Tools section.
+* A change to remediation thresholds or release-blocking rules →
+  update the corresponding table and re-state the rationale in the
+  commit message.
+* A suppression added in code → also add a brief justification in
+  the suppression comment so the rationale survives the next
+  review.
+
+If this policy drifts out of sync with what the workflows actually
+enforce, that is a defect worth [opening an
+issue](https://github.com/timlnx/bitmath/issues/new) or a PR.