Skip to content
CI - Testing and Code Quality

NIST P-256/384/521, ML-KEM/ML-DSA parameter sets, and key interoperability formats #2484

Sign in to view logs

NIST P-256/384/521, ML-KEM/ML-DSA parameter sets, and key interoperability formats

NIST P-256/384/521, ML-KEM/ML-DSA parameter sets, and key interoperability formats #2484

Workflow file for this run

.github/workflows/ci.yml at f947b35
# Copyright (C) 2025-2026 Steel Security Advisors LLC
# SPDX-License-Identifier: Apache-2.0
name: CI - Testing and Code Quality
on:
push:
branches: [ main, develop, 'feature/**', 'fix/**' ]
pull_request:
branches: [ main, develop ]
workflow_dispatch:
permissions:
contents: read
# Collapse overlapping runs on the same ref to avoid runner-queue
# saturation when rapid pushes fire both push- and pull_request-triggered
# workflows in parallel. Cancelling in-flight runs is safe for feature
# branches and PR heads; `main` and scheduled runs are preserved by
# excluding them from ``cancel-in-progress``.
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: ${{ github.ref != 'refs/heads/main' && github.event_name != 'schedule' }}
jobs:
test:
name: Test ${{ matrix.os }} / Python ${{ matrix.python-version }}
runs-on: ${{ matrix.os }}
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
include:
# ARM64 (AArch64) runners — GitHub-hosted ubuntu arm64
- os: ubuntu-24.04-arm
python-version: "3.11"
- os: ubuntu-24.04-arm
python-version: "3.13"
steps:
- name: Checkout code
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- name: Set up Python ${{ matrix.python-version }}
id: setup-python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
continue-on-error: true
with:
python-version: ${{ matrix.python-version }}
cache: 'pip'
# First-party retry path: actions/setup-python intermittently fails on
# GitHub-hosted Windows runners during the Python 3.13 install
# (toolcache / cache-restore flake; see PR #306 review). The retry
# is non-fatal on the first miss and only re-runs when needed, so the
# happy path remains a single setup-python call.
- name: Set up Python ${{ matrix.python-version }} (retry without cache)
if: steps.setup-python.outcome == 'failure'
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
with:
python-version: ${{ matrix.python-version }}
- name: Install system dependencies (Linux)
if: runner.os == 'Linux'
run: |
sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list /etc/apt/sources.list.d/azure-cli.list || true
sudo apt-get update
sudo apt-get install -y build-essential cmake
- name: Install system dependencies (Windows)
if: runner.os == 'Windows'
shell: pwsh
# CMake is pre-installed on GitHub-hosted Windows runners
# (see https://github.com/actions/runner-images/ image manifests),
# so the common case is a no-op. Only install via Chocolatey —
# with retries — if ``cmake`` is genuinely missing, so a transient
# Chocolatey CDN outage cannot break the build. Matches the
# pattern already used in ``ci-build-test.yml``; PR #258 review
# fix for the flaky ``Install system dependencies (Windows)``
# step that was single-attempt ``choco install cmake``.
run: |
if (Get-Command cmake -ErrorAction SilentlyContinue) {
Write-Host "CMake already available: $(cmake --version | Select-Object -First 1)"
} else {
Write-Host "CMake not found; installing via Chocolatey with retries..."
$maxAttempts = 5
for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
Write-Host "Attempt ${attempt}/${maxAttempts}: choco install cmake..."
choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System' -y 2>&1
if ($LASTEXITCODE -eq 0) {
Write-Host "Successfully installed cmake"
break
}
if ($attempt -lt $maxAttempts) {
$delay = $attempt * 15
Write-Host "Install failed, waiting ${delay}s before retry..."
Start-Sleep -Seconds $delay
}
}
if ($LASTEXITCODE -ne 0) {
Write-Error "All ${maxAttempts} attempts to install cmake via Chocolatey failed"
exit 1
}
Import-Module "$env:ChocolateyInstall\helpers\chocolateyProfile.psm1"
refreshenv
}
- name: Build native C library (Linux)
if: runner.os == 'Linux'
run: |
cmake -B build -DAMA_USE_NATIVE_PQC=ON -DCMAKE_BUILD_TYPE=Release -DAMA_BUILD_TESTS=OFF -DAMA_BUILD_EXAMPLES=OFF
cmake --build build -j$(nproc)
- name: Build native C library (Windows)
if: runner.os == 'Windows'
run: |
cmake -B build -DAMA_USE_NATIVE_PQC=ON -DCMAKE_BUILD_TYPE=Release -DAMA_BUILD_TESTS=OFF -DAMA_BUILD_EXAMPLES=OFF
cmake --build build --config Release --parallel
- name: Install Python dependencies
run: |
python -m pip install --upgrade pip setuptools wheel
pip install "Cython>=3.0.0" "numpy>=1.24.0,<3.0.0"
# [legacy] + [benchmark] supply PyCA cryptography / PyNaCl, and
# pycryptodome backs the AES-GCM differential harness. Without them the
# cross-implementation validation tests (tests/test_differential.py,
# the PyCA interop cases in test_ed25519_native.py / test_aes_gcm_native.py
# / test_hkdf_sha3_256.py) silently SKIP, so a divergence between AMA's
# native C primitives and a reference implementation would go unnoticed.
# Installing them converts those skips into real assertions.
pip install -e ".[dev,legacy,benchmark]" pycryptodome
- name: Verify module integrity digest is current
shell: bash
run: |
python -c "
from ama_cryptography._self_test import verify_module_integrity
ok, detail = verify_module_integrity()
if not ok:
raise SystemExit(
f'FATAL: Module integrity digest is stale or tampered: {detail}\n'
'Run: python -m ama_cryptography.integrity --update'
)
print(f'Module integrity: OK ({detail})')
"
- name: Verify crypto backends are available
shell: bash
run: |
python -c "
from ama_cryptography.pqc_backends import (
DILITHIUM_AVAILABLE, KYBER_AVAILABLE, SPHINCS_AVAILABLE,
_ED25519_NATIVE_AVAILABLE, _AES_GCM_NATIVE_AVAILABLE,
)
backends = {
'Dilithium': DILITHIUM_AVAILABLE,
'Kyber': KYBER_AVAILABLE,
'SPHINCS+': SPHINCS_AVAILABLE,
'AES-GCM native': _AES_GCM_NATIVE_AVAILABLE,
'Ed25519 native': _ED25519_NATIVE_AVAILABLE,
}
missing = [name for name, avail in backends.items() if not avail]
for name, avail in backends.items():
status = 'OK' if avail else 'MISSING'
print(f' {name}: {status}')
if missing:
raise SystemExit(
f'FATAL: Crypto backends not available in CI: {missing}. '
'The C library must be built before running tests.'
)
print('All crypto backends verified.')
"
- name: Verify cross-implementation reference libraries are importable
shell: bash
# The differential / interop suites validate AMA's native C primitives
# against independent reference implementations. They are written to SKIP
# when a reference library is absent, which means a missing install would
# quietly delete that coverage instead of failing. Assert the imports here
# so the skip path can never silently return in CI.
run: |
python -c "
import importlib
refs = {
'cryptography': 'PyCA interop (Ed25519 / AES-GCM / HKDF cross-checks)',
'nacl': 'PyNaCl differential validation',
'Crypto': 'pycryptodome AES-GCM differential validation',
}
missing = []
for mod, why in refs.items():
try:
importlib.import_module(mod)
print(f' {mod}: OK ({why})')
except ImportError:
missing.append(f'{mod} ({why})')
print(f' {mod}: MISSING ({why})')
if missing:
raise SystemExit(
'FATAL: cross-implementation reference libraries missing in CI: '
f'{missing}. Interop tests would SKIP and silently drop coverage.'
)
print('All cross-implementation reference libraries verified.')
"
- name: Run pytest test suite
env:
AMA_CI_REQUIRE_BACKENDS: "1"
run: |
python -m pytest tests/ -v --tb=short --no-cov
- name: "Wycheproof corpus (vendored, offline, fail-closed)"
# Google's Project Wycheproof is a corpus of the cases that *break*
# implementations. Running it against this library for the first time
# found a real Ed25519 malleability defect (RFC 8032 §5.1.7) in under a
# minute — and then a second divergence in X25519 non-canonical
# u-coordinate handling. Neither had any standing gate; this is it.
#
# The corpus is vendored under wycheproof_vectors/ and pinned by
# manifest.json (upstream commit, per-file SHA-256, per-file vector
# count), so nothing is fetched at test time and a swapped vector file
# fails before a single vector runs. Every one of the 2,733 vectors
# lands in a named bucket with an asserted count — there is no silent
# skip, and an unrunnable vector is a red build with a reason.
run: |
python wycheproof_vectors/run_wycheproof.py
- name: Run demonstration
env:
PYTHONUTF8: "1"
run: |
python -m ama_cryptography
- name: Verify demonstration output
shell: bash
run: |
python -c "
import os
import subprocess
import sys
env = os.environ.copy()
env['PYTHONUTF8'] = '1'
result = subprocess.run([sys.executable, '-m', 'ama_cryptography'],
capture_output=True, text=True, timeout=60,
encoding='utf-8', errors='replace', env=env)
if result.returncode != 0:
print('ERROR: Demonstration failed')
print(result.stderr)
sys.exit(1)
output = result.stdout
# Verify critical outputs
checks = [
('AMA Cryptography', 'Title present'),
('Generating key management system', 'Key generation'),
('Creating Omni-Code cryptographic package', 'Package creation'),
('Signing package', 'Signing process'),
('Verifying cryptographic package', 'Verification'),
('ALL VERIFICATIONS PASSED', 'Success confirmation')
]
failed = []
for check, desc in checks:
if check not in output:
failed.append(f'{desc}: \"{check}\" not found')
if failed:
print('ERROR: Output validation failed:')
for fail in failed:
print(f' - {fail}')
sys.exit(1)
print('All verification checks passed')
"
code-quality:
name: Code Quality Checks
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Checkout code
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
with:
python-version: "3.11"
cache: 'pip'
- name: Install dependencies
run: |
python -m pip install --upgrade pip
# Pin the exact linter versions from requirements-lock.txt so the gate
# matches the pinned dev toolchain and pre-commit. An unpinned ruff
# (previously ``ruff>=0.4``) lets a routine ruff release start failing
# an unrelated PR; mypy floated on 1.x while the [dev] extra and
# [tool.mypy] config target 2.x, so local and CI could disagree.
# types-PyYAML keeps tools/check_workflow_commands.py and its tests
# inside `mypy --strict` rather than behind an ignore_missing_imports
# override; tests/ imports the tool, so mypy follows into it.
pip install "black==26.5.1" "ruff==0.15.20" "mypy==2.1.0" \
"PyYAML==6.0.3" "types-PyYAML==6.0.12.20260724"
- name: Lint with ruff
run: |
ruff check .
- name: Check code formatting with Black
run: |
black --check --diff .
- name: Type checking with MyPy (--strict)
continue-on-error: false
run: |
mypy --strict ama_cryptography/ tests/
- name: "INVARIANT-13: Suppression hygiene check"
run: |
python tools/check_suppression_hygiene.py
- name: "Uniform license headers (SPDX)"
# The tree carried five different header shapes at once — a two-line
# Apache note, the full thirteen-line boilerplate block, a bare SPDX
# tag on four files, a one-off "Apache License 2.0" spelling, and the
# C block-comment forms of each. No machine license scanner could
# read that reliably and a new file could pick any shape. This gate
# pins the canonical two-line header with the *registered* SPDX
# identifier (`Apache-2.0`; `Apache 2.0` is not a valid identifier).
# Detection and normalization are both pinned by tests/test_headers.py,
# so the gate cannot silently degrade into a no-op.
run: |
python tools/check_headers.py --check
docs-build:
# Run sphinx-build with -W on every PR / push so any docstring-format
# regression (e.g. malformed Raises: blocks, dangling indent) is caught
# at PR time, not on the post-merge auto-docs job whose failure does
# not block the merge that introduced it.
name: Sphinx Docs Build (Python API)
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- name: Checkout code
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
with:
python-version: "3.11"
cache: 'pip'
- name: Install documentation dependencies
run: |
python -m pip install --upgrade pip
python -m pip install sphinx sphinx_rtd_theme sphinx-autodoc-typehints
- name: Build Sphinx HTML — warnings are errors
env:
# INVARIANT-7 docs-build gate. Lift the native-backend import
# guards for autodoc only; ``--keep-going`` reports every warning
# in the run while ``-W`` makes the job fail on any of them.
AMA_SPHINX_BUILD: '1'
run: sphinx-build -W --keep-going -b html docs docs/_build/html
security-checks:
name: Security Checks
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- name: Checkout code
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
with:
python-version: "3.11"
- name: Install dependencies
run: |
python -m pip install --upgrade pip
# PyYAML is pinned to the requirements-lock.txt version because
# tools/check_workflow_commands.py (INVARIANT-25) runs in this job and
# parses the workflow files structurally.
pip install pip-audit bandit "PyYAML==6.0.3"
- name: Audit dependencies (strict, lock-file scoped)
# Scope the audit to requirements-lock.txt — this project's pinned
# dependency set — rather than auditing the whole runner environment.
# A bare `pip-audit` reports CVEs in packages AMA does not ship (pip,
# pyjwt, urllib3 and whatever else the GitHub runner image preinstalls),
# so the gate turned red for reasons unrelated to this repository and
# unfixable from it. Lock-file scoping makes the result reproducible
# across reruns and runner-image rolls, and matches the contract already
# used by security.yml. `--strict` still fails the job on any
# vulnerability found in our own pinned set.
run: pip-audit --strict --desc --requirement requirements-lock.txt
- name: Security linting with Bandit
run: |
bandit -r ama_cryptography/ -l -f json -o bandit-report.json
bandit -r ama_cryptography/ -l
- name: Upload Bandit report
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
if: success()
with:
name: bandit-security-report
path: bandit-report.json
- name: Semgrep security scan
continue-on-error: false
run: |
python -m pip install semgrep==1.74.0
semgrep --config .semgrep.yml ama_cryptography/ --json -o semgrep-report.json
- name: Upload Semgrep report
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
if: success()
with:
name: semgrep-security-report
path: semgrep-report.json
- name: "INVARIANT-24: Verify pinned action SHAs resolve upstream"
# A SHA-pinned action is only a supply-chain control if the SHA is real.
# release.yml carried a pypa/cibuildwheel pin whose commit existed
# nowhere upstream, so EVERY wheel job aborted with "unable to find
# version" — which is why the v3.2.0 and v3.3.0 releases shipped with
# zero binary artefacts. Nothing caught it because release.yml only
# runs on a tag push. Checking here means a bad pin fails on the PR
# that introduces it, not on release day.
run: |
python tools/check_action_pins.py --strict
- name: "INVARIANT-25: Verify workflow runner labels and command strings"
# release.yml runs only on a tag push, so anything wrong inside it stays
# invisible until release day. Three defects shipped that way, each on
# its own enough to produce a release with zero binary artefacts: a
# retired `macos-13` runner label (the job queued until timeout), a
# `python -c` payload broken by YAML folding (every wheel built, then
# failed with IndentationError), and POSIX single-quoting handed to
# cmd.exe (every Windows wheel died on `Invalid requirement: "'cmake"`).
# All three are decidable without running anything, so they are decided
# here — on the pull request that introduces them. Both directions are
# pinned by tests/test_workflow_command_checks.py.
run: |
python tools/check_workflow_commands.py
- name: "INVARIANT-31: Verify every pull-request job is reachable from its gate"
# Branch protection requires the aggregating gate context of each
# workflow, not the individual job names. A job missing from its gate's
# `needs:` therefore still runs, still shows its own red X on the pull
# request, and still cannot block the merge — "all required checks
# passed" stays true next to a visibly failing job.
#
# `c-library-no-native-pqc` was exactly that: the guard for the
# AMA_USE_NATIVE_PQC=OFF build, absent from ci-build-test.yml's gate
# while commit f3dd0c2 had to repair that very configuration after it
# broke undetected. Every gate comment in this repository asserts that
# each job in the workflow must be green; this check is what makes that
# true. Both directions are pinned by tests/test_gate_coverage.py.
run: |
python tools/check_gate_coverage.py
- name: "INVARIANT-32: Verify documented install extras are declared"
# pip does not fail on an extra a distribution does not provide — it
# warns, installs WITHOUT it, and exits 0. A stale name in an install
# instruction therefore yields an incomplete install and a success
# message, surfacing much later as an ImportError from a subsystem the
# reader believes they enabled.
#
# wiki/Installation.md — published to the public wiki by wiki-sync.yml —
# shipped `pip install -e ".[secure-memory]"`, described as "libsodium
# secure memory bindings", in its own "Everything at once" line. No such
# extra ever existed, secure_memory is stdlib-only, and INVARIANT-1
# forbids libsodium outright. Both directions are pinned by
# tests/test_documented_extras.py.
run: |
python tools/check_documented_extras.py
- name: "INVARIANT-33: Verify every fuzz harness is registered everywhere"
# A fuzz harness is registered in three independent lists: the CMake
# target lists, the fuzzing.yml job matrix, and oss-fuzz/build.sh.
# Nothing tied them together, and they had drifted: fuzz_agent_binding
# was added to CMake and to the CI matrix when the agent-binding layer
# landed, and never to build.sh — so OSS-Fuzz never built it. build.sh
# skips a missing target with a warning and exits 0, which is why the
# omission stayed invisible.
#
# A harness nobody runs is indistinguishable from one that finds
# nothing. Both directions are pinned by
# tests/test_fuzz_target_registration.py.
run: |
python tools/check_fuzz_target_registration.py
- name: "INVARIANT-23: Secret scan (in-house)"
# tools/check_secrets.py is written in house rather than adopting a
# third-party scanner — see the module docstring for why a generic
# entropy scanner is the wrong tool for a repository whose tracked
# content is largely published high-entropy test vectors. Detection
# and non-detection are pinned by tests/test_secret_scanner.py, so this
# gate cannot silently degrade into a no-op.
run: |
python tools/check_secrets.py
- name: Enforce safe os.fdopen usage (fd-ownership, AST-verified)
# Replaces a grep-plus-filename-allowlist check. That construction could
# not tell a correctly guarded call from a leaking one — it only asked
# whether the file was on a list, so it was satisfied by editing the list
# — and it had already rotted: the allowlist named `key_storage.py`, a
# module that does not exist in this package, while omitting the module
# that actually performs the call. tools/check_fdopen_safety.py instead
# parses the AST and verifies the property that prevents the leak: every
# os.fdopen call sits in a try whose handlers (or finally) can close the
# raw descriptor when the hand-off fails. No allowlist to maintain, and
# it applies to every tracked module rather than three named ones.
# Both directions are pinned by tests/test_fdopen_safety.py.
run: |
python tools/check_fdopen_safety.py
benchmark-regression:
name: Benchmark Regression Detection (${{ matrix.runner_cpu_class }})
# x86_64 entry uses ubuntu-latest; arm64 entry uses ubuntu-24.04-arm
# (GitHub-hosted Cortex-A78 / Graviton-class AArch64 runner). The
# arm-baseline.json arm entry exercises the NEON paths wired by this
# PR (AES-GCM, ChaCha20, Argon2) end-to-end so any byte-level
# divergence between the NEON kernel and the scalar reference shows
# up as a regression-detector hit, not a silent passing build.
strategy:
fail-fast: false
matrix:
include:
- os: ubuntu-latest
runner_cpu_class: x86_64
baseline_path: benchmarks/baseline.json
- os: ubuntu-24.04-arm
runner_cpu_class: aarch64
baseline_path: benchmarks/arm-baseline.json
runs-on: ${{ matrix.os }}
timeout-minutes: 15
steps:
- name: Checkout code
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
with:
python-version: "3.11"
cache: 'pip'
- name: Install system dependencies
run: |
sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list /etc/apt/sources.list.d/azure-cli.list || true
sudo apt-get update
sudo apt-get install -y build-essential cmake util-linux
- name: Capture runner CPU class
id: cpu_class
run: |
# lscpu reports the canonical "Architecture:" field which we
# treat as the source of truth. Pin the value into the runner
# matrix entry so a benchmark JSON produced by ubuntu-24.04-arm
# is unambiguously distinguishable from one produced by
# ubuntu-latest x86_64 (the regression detector keys off this).
ARCH=$(lscpu | awk -F: '/^Architecture:/ {gsub(/^ +/, "", $2); print $2}')
echo "arch=${ARCH}" >> "$GITHUB_OUTPUT"
echo "matrix_class=${{ matrix.runner_cpu_class }}" >> "$GITHUB_OUTPUT"
- name: Build native C library
run: |
# AMA_ENABLE_AVX512=ON enables the in-house AVX-512 4-way Keccak
# kernel on x86-64 hosts (gated on runtime CPUID at dispatch
# init, so a no-op on AArch64). AMA_ENABLE_NATIVE_ARCH=ON adds
# -march=native so the benchmark exercises the host's full
# microarchitecture (AES-NI, BMI2, AVX2/AVX-512, NEON Crypto
# Extensions as appropriate). Without these flags the benchmark
# numbers reflect the lowest-common-denominator generic C path,
# not what users actually run.
cmake -B build \
-DAMA_USE_NATIVE_PQC=ON \
-DCMAKE_BUILD_TYPE=Release \
-DAMA_BUILD_TESTS=OFF \
-DAMA_BUILD_EXAMPLES=OFF \
-DAMA_ENABLE_AVX512=ON \
-DAMA_ENABLE_NATIVE_ARCH=ON
cmake --build build -j$(nproc)
- name: Install dependencies
run: |
python -m pip install --upgrade pip setuptools wheel
pip install "Cython>=3.0.0" "numpy>=1.24.0,<3.0.0"
pip install -e ".[dev]"
- name: Run benchmark regression tests
env:
AMA_RUNNER_CPU_CLASS: ${{ steps.cpu_class.outputs.arch }}
AMA_MATRIX_BASELINE: ${{ matrix.baseline_path }}
run: |
# Pin to a single core (`taskset -c 0`) and raise scheduling
# priority (`nice -n -10`) so the benchmark numbers are not
# contaminated by other tasks on the shared GitHub-hosted
# runner. Mirrors the same harness dudect.yml uses for its
# constant-time measurements at the identical priority — the
# dudect t-statistic and the benchmark medians both depend on
# the same noise floor.
#
# `--baseline "$AMA_MATRIX_BASELINE"` is the per-matrix entry
# baseline path (Copilot review #3249188319): the x86 entry
# compares against benchmarks/baseline.json, the AArch64 entry
# against benchmarks/arm-baseline.json. Without this, both
# entries default to the x86 baseline and the AArch64 job
# reports spurious regressions on every PR.
taskset -c 0 nice -n -10 python benchmarks/benchmark_runner.py \
--verbose \
--baseline "$AMA_MATRIX_BASELINE" \
--require-runner-class "$AMA_RUNNER_CPU_CLASS" \
--require-populated-baseline \
--output benchmarks/benchmark-results.json \
--markdown benchmark-report.md
# Annotate the result JSON with the runner CPU class so the
# arm and x86 artefacts are unambiguously distinguishable.
# The downstream `check_baseline_justification.py` uses this
# tag to compare against the matching baseline.
python - <<'PY'
import json, os, pathlib
path = pathlib.Path("benchmarks/benchmark-results.json")
if path.exists():
data = json.loads(path.read_text())
data.setdefault("metadata", {})["runner_cpu_class"] = (
os.environ.get("AMA_RUNNER_CPU_CLASS", "unknown")
)
data["metadata"]["matrix_baseline_path"] = (
os.environ.get("AMA_MATRIX_BASELINE", "")
)
path.write_text(json.dumps(data, indent=2) + "\n")
PY
- name: Upload benchmark results
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
if: success()
with:
name: benchmark-results-${{ matrix.runner_cpu_class }}
path: |
benchmarks/benchmark-results.json
benchmark-report.md
constant-time-check:
name: Constant-Time Verification (Smoke Test)
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- name: Checkout code
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- name: Install build dependencies
run: |
sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list /etc/apt/sources.list.d/azure-cli.list || true
sudo apt-get update
sudo apt-get install -y build-essential cmake
- name: Build C library
run: |
mkdir -p build
cd build
cmake ..
make
- name: Build and run dudect harnesses
run: |
cd tools/constant_time
make clean
make all
# Run smoke tests with 50K iterations (faster for CI).
#
# Pin to a single core (`taskset -c 0`) and best-effort
# elevate priority (`nice -n -10`) to suppress CPU-contention
# noise on shared GitHub-hosted runners. Without this, the
# dudect t-statistic at 50K iterations can drift past its
# leakage threshold from background noise alone.
#
# GHA hosted runners lack CAP_SYS_NICE so the negative-nice
# request prints "Permission denied" but still execs the
# binary; probe once up front and drop the prefix when the
# runner refuses (PR #326), so the log stays clean. The
# v3.2.0 dudect setup-symmetry harness fixes made the lanes
# noise-tolerant enough that taskset-only pinning is the
# load-bearing CI gate; the nice prefix is opportunistic on
# privileged self-hosted runners. The full dudect.yml gate
# (path-filtered to src/c/** changes) remains the
# authoritative constant-time check; this smoke test exists
# as a fast pre-gate for every PR regardless of path filter.
NICE_PREFIX=""
if nice -n -10 true 2>/dev/null; then NICE_PREFIX="nice -n -10"; fi
echo "=== Utility function timing analysis ==="
taskset -c 0 $NICE_PREFIX ./dudect_harness 50000
echo "=== Crypto primitive timing analysis ==="
taskset -c 0 $NICE_PREFIX ./dudect_crypto 50000
- name: Upload timing analysis results
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
if: success()
with:
name: constant-time-results
path: tools/constant_time/
# ============================================================================
# AVX-512 SHA3 4-way KAT (PR C — 2026-04)
#
# Best-effort gate: GitHub-hosted ubuntu-latest currently rotates among
# Cascade Lake / Ice Lake / Sapphire Rapids host CPUs, so AVX-512 hits
# only some fraction of runs. We probe /proc/cpuinfo for the avx512f
# feature flag and skip honestly when it's missing — the build/test
# body itself never uses continue-on-error (INVARIANT-2: fail-closed
# CI on the steps that actually run). Local validation ladder for
# pre-merge: SDE (`sde64 -spr -- ./test_sha3_avx512_kat`) plus a
# quarterly bare-metal bench post-merge.
# ============================================================================
test-avx512:
name: AVX-512 SHA3 4-way KAT
runs-on: ubuntu-latest
needs: test
steps:
- name: Checkout code
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- name: Probe /proc/cpuinfo for AVX-512F + AVX-512VL
id: cpu
run: |
if grep -q '\bavx512f\b' /proc/cpuinfo && grep -q '\bavx512vl\b' /proc/cpuinfo; then
echo "have_avx512=1" >> "$GITHUB_OUTPUT"
echo "::notice::ubuntu-latest runner reports AVX-512F + AVX-512VL — running KAT"
else
echo "have_avx512=0" >> "$GITHUB_OUTPUT"
echo "::notice::ubuntu-latest runner lacks AVX-512F or AVX-512VL — skipping KAT job"
fi
- name: Install build dependencies
if: steps.cpu.outputs.have_avx512 == '1'
run: |
sudo rm -f /etc/apt/sources.list.d/microsoft-prod.list /etc/apt/sources.list.d/azure-cli.list || true
sudo apt-get update
sudo apt-get install -y cmake build-essential
- name: Configure with AVX-512 enabled
if: steps.cpu.outputs.have_avx512 == '1'
run: cmake -S . -B build -DAMA_ENABLE_AVX512=ON -DAMA_BUILD_TESTS=ON
- name: Build AVX-512 KAT test
if: steps.cpu.outputs.have_avx512 == '1'
run: cmake --build build --target test_sha3_avx512_kat --parallel
- name: Run AVX-512 KAT test (byte-identity vs scalar + AVX2)
if: steps.cpu.outputs.have_avx512 == '1'
run: ctest --test-dir build -R test_sha3_avx512_kat --output-on-failure
ed25519-backend-differential:
name: Ed25519 backend differential (donna vs fe51)
# WHY THIS JOB EXISTS
#
# This repository ships TWO Ed25519 implementations and picks between them
# at configure time (CMakeLists.txt removes src/c/ama_ed25519.c from the
# source list and substitutes src/c/ed25519_donna_shim.c whenever
# AMA_ED25519_ASSEMBLY is ON, which is the default on x86-64):
#
# * ed25519-donna — x86-64 assembly, what every x86-64 lane builds
# * fe51 — the portable path in ama_ed25519.c
#
# Until this job existed, no CI lane ever built fe51 on x86-64. It was
# exercised only incidentally on the ubuntu-24.04-arm runners, and nothing
# anywhere compared the two against each other.
#
# That is not a theoretical gap. INVARIANT-26 fixed an RFC 8032 §5.1.7
# canonical-S defect that was present in BOTH backends but for DIFFERENT
# reasons — donna's `RS[63] & 224` test was too weak, while fe51 had no
# range check at all — so a fix written against one could easily have left
# the other broken. Two implementations of one public API that nothing
# compares will drift; the only question is when it is noticed.
#
# This job builds both on the same runner and asserts they return the same
# verdict for every signature in a shared corpus. It is a differential
# test, not a KAT: it does not care which answer is right, only that the
# two backends cannot disagree without failing the build.
runs-on: ubuntu-latest
# Two full CMake builds of the native library plus a C test run. Measured
# at roughly 4 minutes locally; 30 leaves headroom for a cold runner
# without letting a genuinely hung build sit for an hour.
timeout-minutes: 30
steps:
- name: Checkout code
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
with:
python-version: "3.11"
- name: Install build toolchain
run: |
sudo apt-get update
sudo apt-get install -y build-essential cmake
- name: Build donna backend (x86-64 default)
run: |
cmake -S . -B build-donna \
-DAMA_ED25519_ASSEMBLY=ON \
-DAMA_USE_NATIVE_PQC=ON \
-DCMAKE_BUILD_TYPE=Release \
-DAMA_BUILD_TESTS=ON \
-DAMA_BUILD_EXAMPLES=OFF
cmake --build build-donna -j"$(nproc)"
- name: Build fe51 backend (portable path, never built on x86-64 before)
run: |
cmake -S . -B build-fe51 \
-DAMA_ED25519_ASSEMBLY=OFF \
-DAMA_USE_NATIVE_PQC=ON \
-DCMAKE_BUILD_TYPE=Release \
-DAMA_BUILD_TESTS=ON \
-DAMA_BUILD_EXAMPLES=OFF
cmake --build build-fe51 -j"$(nproc)"
- name: Run the C test suite against the fe51 backend
# The donna backend's C tests already run in ci-build-test.yml on every
# x86-64 lane. This is the half that had no coverage.
working-directory: build-fe51
run: ctest --output-on-failure
- name: Differential — both backends must agree on every signature
run: |
python tools/check_ed25519_backend_parity.py \
--donna build-donna/lib/libama_cryptography.so \
--fe51 build-fe51/lib/libama_cryptography.so
ci-gate:
name: CI Gate
# Single aggregating status check for this workflow. Branch protection
# should require ONLY this context (one per primary CI workflow) instead of
# the individual job names: adding, renaming, or matrix-expanding a job then
# updates this needs: list under code review rather than drifting the
# branch-protection config out of sync (required-context drift). `needs:` is
# workflow-local, so each of ci.yml / ci-build-test.yml / static-analysis.yml
# carries its own gate.
#
# if: always() so the gate always resolves to a definitive red/green even
# when a dependency fails — otherwise it would be reported as `skipped` and
# leave the PR stuck "waiting for status".
if: always()
needs:
- test
- code-quality
- docs-build
- security-checks
- benchmark-regression
- constant-time-check
- test-avx512
- ed25519-backend-differential
runs-on: ubuntu-latest
timeout-minutes: 3
steps:
- name: Fail unless every required job succeeded
# STRICT. Every job in this workflow runs unconditionally — none carries a
# job-level `if:` — so on the authoritative head-commit run each MUST be
# `success`. `skipped` now fails the gate too: on this workflow it can only
# mean a `needs:` dependency failed (already red) or a future job's `if:`
# drifted so it silently stopped running — exactly the gap a lenient gate
# hides. `cancelled` also fails, but only ever appears on a run superseded
# by a newer push or a manual abort, neither of which gates the latest head
# commit that branch protection evaluates. Matrix jobs are fail-fast:false
# and timeouts report as `failure`.
if: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'skipped') || contains(needs.*.result, 'cancelled') }}
run: |
echo "::error::CI Gate failed — a required job did not succeed."
echo "Dependency results: ${{ join(needs.*.result, ', ') }}"
exit 1
- name: All required jobs succeeded
run: echo "CI Gate passed — all required jobs are green."