diff --git a/.github/workflows/secret-scanner-self-test.yml b/.github/workflows/secret-scanner-self-test.yml index 5bde18c..8610b14 100644 --- a/.github/workflows/secret-scanner-self-test.yml +++ b/.github/workflows/secret-scanner-self-test.yml @@ -24,6 +24,10 @@ jobs: yq '.' .github/workflows/secret-scanner-reusable.yml >/dev/null yq '.' templates/secret-scanner-caller.yml >/dev/null yq '.' actions/secret-scan-check/action.yml >/dev/null + - name: Capability atlas inventory, navigation and negative controls + run: | + bash scripts/build-capability-catalogue.sh --check + bash tests/capability-catalogue.sh - name: Governance pin representation regressions (not full lock verification) run: bash tests/lock-pin-contract.sh - name: Official SonarCloud receipt regressions diff --git a/CATALOGUE.adoc b/CATALOGUE.adoc new file mode 100644 index 0000000..a368ae5 --- /dev/null +++ b/CATALOGUE.adoc @@ -0,0 +1,208 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Generated by scripts/build-capability-catalogue.sh; edit catalogue/capabilities.json. += The CI/CD Capability Atlas +:toc: +:toclevels: 2 + +*Repository assurance, organised by purpose. Discover by clade; choose by nature; adopt with evidence.* + +*32 composite actions · 8 clades · two independent discovery axes.* + +This is a visitor-facing product catalogue, not a repo-chora file, a BoJ cartridge implementation, or a certification scheme. Inspired by BoJ's separation of capability domain from interface/type, it groups existing CI/CD building blocks without moving their paths or changing their behaviour. + +== Find your route + +* *Protect credentials:* <> — bounded secret scanning and authoritative result receipts. +* *Establish repository policy:* <>, <> and <>. +* *Compile, test or prove:* <> — language-specific execution and explicitly labelled source checks. +* *Integrate the ecosystem:* <> — BoJ applicability, Pons and Panic Attack. +* *Explore signals and future work:* <> and <> — no inflated assurance claims. + +== The clade matrix + +[cols="2,4,1,1,1,1,1",options="header"] +|=== +|Clade |Purpose |Total |Enforcing |Tool-dependent |Advisory |Stub +|<> |Find exposed credentials and verify authoritative analysis without manufacturing a green result. |4 |4 |0 |0 |0 +|<> |Establish repository identity, policy documents, attribution and licensing. |4 |4 |0 |0 |0 +|<> |Control source debt, document formats, language policy and task-runner syntax. |4 |4 |0 |0 |0 +|<> |Validate structured manifests and executable contract declarations. |2 |1 |1 |0 |0 +|<> |Compile, test, inspect interfaces and execute proof tools where applicable. |7 |6 |1 |0 |0 +|<> |Connect BoJ capabilities and external analysis tools to repository checks. |2 |1 |1 |0 |0 +|<> |Discover useful signals without presenting warnings or heuristics as certification. |7 |0 |0 |7 |0 +|<> |Visible roadmap boundaries: not implemented assurance and not recommended gates. |2 |0 |0 |0 |2 +|=== + +== Read the assurance labels + +* *Enforcing (20):* can reject a subject. This is not a guarantee of completeness, applicability, production readiness or formal verification. +* *Tool-dependent (3):* requires explicitly supplied validators/toolchains; inspect applicability and not-run behaviour before adoption. +* *Advisory (7):* signals and warnings, not an assurance verdict. Some current outputs are simulated or heuristic; each card names the boundary. +* *Stub (2):* unfinished integration or placeholder. Do not deploy as evidence of a completed check. + +Nature is a separate axis: a policy-pattern scan is not a compiler, a receipt verifier is not an analyser, and a proof executor is not a proof that every program is correct. These labels are reviewed inventory metadata; tests enforce coverage and consistency, not semantic correctness of every gate. + +== Browse by nature + +[cols="2,1,7",options="header"] +|=== +|Nature |Count |Capabilities +|advisory |7 |link:actions/badges-check/action.yml[Accreditations & badges] · link:actions/gitsea-check/action.yml[Analytics declarations] · link:actions/hosting-check/action.yml[Hosting configuration] · link:actions/metrics-check/action.yml[Metrics & proof indicators] · link:actions/tests-benches-check/action.yml[Test & benchmark discoverability] · link:actions/trust-humans-check/action.yml[Human trust declarations] · link:actions/www-compliance-check/action.yml[Web & well-known conventions] +|build-test |2 |link:actions/rust-ci-check/action.yml[Strict Rust CI] · link:actions/kanren-check/action.yml[Relational-code checks] +|integration |2 |link:actions/boj-cartridge-check/action.yml[BoJ cartridge applicability] · link:actions/custom-tools-check/action.yml[Pons & Panic Attack] +|placeholder |2 |link:actions/prat-check/action.yml[PRAT testing placeholder] · link:actions/semantic-audit-check/action.yml[Semantic audit placeholder] +|policy-gate |10 |link:actions/secrets-check/action.yml[Private-key material] · link:actions/vaulted-tokens-check/action.yml[Vaulted token format] · link:actions/required-files-check/action.yml[Repository foundations] · link:actions/spdx-license-check/action.yml[Licensing & SPDX] · link:actions/affirmation-check/action.yml[Affirmation snapshots] · link:actions/code-hygiene-check/action.yml[Source debt & proof escapes] · link:actions/formatting-check/action.yml[Document format policy] · link:actions/linguist-check/action.yml[Language inventory policy] · link:actions/idris2-abi-check/action.yml[Idris2 ABI source policy] · link:actions/zig-unified-api-adapter-check/action.yml[Zig adapter source policy] +|proof-executor |3 |link:actions/creusot-check/action.yml[Rust deductive verification] · link:actions/spark-check/action.yml[Ada/SPARK proof] · link:actions/proof-runner-check/action.yml[Idris2 & Lean proof runner] +|receipt-verifier |1 |link:actions/sonarcloud-result-check/action.yml[Authoritative SonarCloud receipt] +|scanner |1 |link:actions/secret-scan-check/action.yml[Bounded secret scanning] +|validator |4 |link:actions/referencing-check/action.yml[Citation metadata] · link:actions/recipes-set-check/action.yml[Task-runner syntax] · link:actions/manifest-check/action.yml[DEED & K9 manifests] · link:actions/contractile-validation-check/action.yml[Contractile declarations] +|=== + +[[sentinel]] +== Sentinel — security & trusted results + +Find exposed credentials and verify authoritative analysis without manufacturing a green result. + +link:catalogue/clades/sentinel.adoc[Explore this clade — 4 capabilities] + +[cols="2,2,2,5",options="header"] +|=== +|Capability |Nature |Status |What it does +|link:actions/secret-scan-check/action.yml[Bounded secret scanning] |scanner |enforcing |Redacted working-tree and history scans with checksum-pinned Gitleaks, real detector controls and Rust/shell supplements. +|link:actions/secrets-check/action.yml[Private-key material] |policy-gate |enforcing |Detect PEM/OpenSSH private-key material in the working tree. +|link:actions/vaulted-tokens-check/action.yml[Vaulted token format] |policy-gate |enforcing |Enforce the estate token-wrapper representation policy. +|link:actions/sonarcloud-result-check/action.yml[Authoritative SonarCloud receipt] |receipt-verifier |enforcing |Verify the newest official-app result for an exact repository and commit. +|=== + +[[covenant]] +== Covenant — governance & provenance + +Establish repository identity, policy documents, attribution and licensing. + +link:catalogue/clades/covenant.adoc[Explore this clade — 4 capabilities] + +[cols="2,2,2,5",options="header"] +|=== +|Capability |Nature |Status |What it does +|link:actions/required-files-check/action.yml[Repository foundations] |policy-gate |enforcing |Check required structural documents, substance and repository-specific ownership. +|link:actions/spdx-license-check/action.yml[Licensing & SPDX] |policy-gate |enforcing |Inspect licence files and estate SPDX conventions. +|link:actions/affirmation-check/action.yml[Affirmation snapshots] |policy-gate |enforcing |Validate applicable AFFIRMATION snapshots and configured signature trust. +|link:actions/referencing-check/action.yml[Citation metadata] |validator |enforcing |Validate core Citation File Format fields when applicable. +|=== + +[[forge]] +== Forge — source & build hygiene + +Control source debt, document formats, language policy and task-runner syntax. + +link:catalogue/clades/forge.adoc[Explore this clade — 4 capabilities] + +[cols="2,2,2,5",options="header"] +|=== +|Capability |Nature |Status |What it does +|link:actions/code-hygiene-check/action.yml[Source debt & proof escapes] |policy-gate |enforcing |Find untracked debt markers and undeclared proof circumventions with source-aware rules. +|link:actions/formatting-check/action.yml[Document format policy] |policy-gate |enforcing |Enforce estate file-format conventions with named exceptions. +|link:actions/linguist-check/action.yml[Language inventory policy] |policy-gate |enforcing |Inspect language policy and Linguist configuration. +|link:actions/recipes-set-check/action.yml[Task-runner syntax] |validator |enforcing |Parse-check Justfile or Makefile recipes. +|=== + +[[schema]] +== Schema — manifests & contracts + +Validate structured manifests and executable contract declarations. + +link:catalogue/clades/schema.adoc[Explore this clade — 2 capabilities] + +[cols="2,2,2,5",options="header"] +|=== +|Capability |Nature |Status |What it does +|link:actions/manifest-check/action.yml[DEED & K9 manifests] |validator |enforcing |Use maintained format validators for manifest structure. +|link:actions/contractile-validation-check/action.yml[Contractile declarations] |validator |tool-dependent |Validate applicable DEED contract declarations with maintained tooling. +|=== + +[[proof]] +== Proof — languages & verification + +Compile, test, inspect interfaces and execute proof tools where applicable. + +link:catalogue/clades/proof.adoc[Explore this clade — 7 capabilities] + +[cols="2,2,2,5",options="header"] +|=== +|Capability |Nature |Status |What it does +|link:actions/rust-ci-check/action.yml[Strict Rust CI] |build-test |enforcing |Locked check, formatting, clippy, tests, doctests, documentation and MSRV phases. +|link:actions/creusot-check/action.yml[Rust deductive verification] |proof-executor |enforcing |Inspect verification claims, run planted controls and execute Creusot obligations. +|link:actions/spark-check/action.yml[Ada/SPARK proof] |proof-executor |enforcing |Inspect SPARK projects, run planted controls and execute GNATprove. +|link:actions/kanren-check/action.yml[Relational-code checks] |build-test |enforcing |Detect relations, require goal-level tests and run applicable relational tests. +|link:actions/proof-runner-check/action.yml[Idris2 & Lean proof runner] |proof-executor |tool-dependent |Run applicable Idris2 project typechecks and Lean lake builds. +|link:actions/idris2-abi-check/action.yml[Idris2 ABI source policy] |policy-gate |enforcing |When abi.ipkg exists, scan selected ABI source paths for prohibited IO/unsafe patterns. +|link:actions/zig-unified-api-adapter-check/action.yml[Zig adapter source policy] |policy-gate |enforcing |Scan Zig files for direct std.fs/std.io usage prohibited by estate adapter policy. +|=== + +[[bridge]] +== Bridge — ecosystem integration + +Connect BoJ capabilities and external analysis tools to repository checks. + +link:catalogue/clades/bridge.adoc[Explore this clade — 2 capabilities] + +[cols="2,2,2,5",options="header"] +|=== +|Capability |Nature |Status |What it does +|link:actions/boj-cartridge-check/action.yml[BoJ cartridge applicability] |integration |enforcing |Check cartridge presence when BoJ integration applies or is declared required. +|link:actions/custom-tools-check/action.yml[Pons & Panic Attack] |integration |tool-dependent |Execute pons scan and panic-attack assail with explicit unavailable-tool outcomes. +|=== + +[[observatory]] +== Observatory — advisory signals + +Discover useful signals without presenting warnings or heuristics as certification. + +link:catalogue/clades/observatory.adoc[Explore this clade — 7 capabilities] + +[cols="2,2,2,5",options="header"] +|=== +|Capability |Nature |Status |What it does +|link:actions/badges-check/action.yml[Accreditations & badges] |advisory |advisory |Inspect badge/accreditation conventions and report advisory signals. +|link:actions/gitsea-check/action.yml[Analytics declarations] |advisory |advisory |Inspect Git-Sea analytics configuration and disclaimer conventions. +|link:actions/hosting-check/action.yml[Hosting configuration] |advisory |advisory |Identify hosting targets from repository configuration. +|link:actions/metrics-check/action.yml[Metrics & proof indicators] |advisory |advisory |Extract log/source heuristics for an advisory metrics view. +|link:actions/tests-benches-check/action.yml[Test & benchmark discoverability] |advisory |advisory |Look for benchmark mentions and test/benchmark dashboards. +|link:actions/trust-humans-check/action.yml[Human trust declarations] |advisory |advisory |Inspect trust.txt/humans.txt and association conventions. +|link:actions/www-compliance-check/action.yml[Web & well-known conventions] |advisory |advisory |Inspect website and well-known/resource conventions. +|=== + +[[frontier]] +== Frontier — unfinished capabilities + +Visible roadmap boundaries: not implemented assurance and not recommended gates. + +link:catalogue/clades/frontier.adoc[Explore this clade — 2 capabilities] + +[cols="2,2,2,5",options="header"] +|=== +|Capability |Nature |Status |What it does +|link:actions/prat-check/action.yml[PRAT testing placeholder] |placeholder |stub |Heuristic presence/mention detection for prospective property-testing integration. +|link:actions/semantic-audit-check/action.yml[Semantic audit placeholder] |placeholder |stub |Reserved integration point for future semantic analysis. +|=== + +== Adopt deliberately + +Start with a reusable workflow/caller template where supplied: it handles orchestration that a bare composite may not. Read the action's inputs, scripts, prerequisites and test controls. Pin an already-published, tested source SHA; update the caller lock and complete dependency closure together. Never turn unavailable tools, absent analysis or skipped work into a green assurance claim. + +* link:templates/estate-audit-caller.yml[Estate-audit caller] +* link:.github/workflows/main-estate-audit.yml[Estate-audit orchestration] +* link:docs/SECRET-SCANNER-ROLLOUT.adoc[Secret-scanner rollout and security boundaries] +* link:docs/GOVERNANCE-AND-SONAR-REPAIR.adoc[Governance and Sonar verification guidance] +* link:README.adoc[Operational README, known defects and test guidance] + +== Keep the atlas honest + +The single inventory is link:catalogue/capabilities.json[catalogue/capabilities.json]. Every action must appear exactly once in one primary clade; status and nature remain independent. Adding an action without cataloguing it, breaking a target link, duplicating an entry or leaving generated pages stale fails the catalogue checks. + +[source,shell] +---- +bash scripts/build-capability-catalogue.sh +bash scripts/build-capability-catalogue.sh --check +bash tests/capability-catalogue.sh +---- diff --git a/README.adoc b/README.adoc index 318e6ad..d7ac64b 100644 --- a/README.adoc +++ b/README.adoc @@ -1,9 +1,41 @@ -== cicd-suite += CI/CD Suite -Composite GitHub Actions for estate-wide CI/CD auditing. They are run by -the reusable workflow `+.github/workflows/main-estate-audit.yml+`. Each -repository *calls* that workflow from a ten-line caller; it does not copy -it (see _Consuming it_). +*An atlas of composable repository assurance: security, governance, build hygiene, +contracts, language verification and ecosystem integration.* + +== Discover the suite + +Start with the link:CATALOGUE.adoc[*CI/CD Capability Atlas*]: *32 composite actions +in 8 clades*, organised by both purpose and nature. Each capability has a source +link, an assurance boundary and a status: enforcing, tool-dependent, advisory or +unfinished. Reusable workflows and caller templates are linked where provided. +This is the visitor catalogue, not repository-chora metadata. + +[cols="1,3",options="header"] +|=== +|Clade |Explore +|link:catalogue/clades/sentinel.adoc[Sentinel] |Security scanning & trusted result receipts +|link:catalogue/clades/covenant.adoc[Covenant] |Governance, attribution & licensing +|link:catalogue/clades/forge.adoc[Forge] |Source debt, formats & build hygiene +|link:catalogue/clades/schema.adoc[Schema] |Manifest & contract validation +|link:catalogue/clades/proof.adoc[Proof] |Language CI, proof execution & interface policy +|link:catalogue/clades/bridge.adoc[Bridge] |BoJ applicability & external analysis tools +|link:catalogue/clades/observatory.adoc[Observatory] |Advisory signals, with limitations made explicit +|link:catalogue/clades/frontier.adoc[Frontier] |Unfinished capabilities, not deployable assurance +|=== + +Clades are a discovery taxonomy, not new runtime packages or a claim that every +gate formally verifies code. Existing action paths and execution semantics are +unchanged. The catalogue is generated from link:catalogue/capabilities.json[a +validated inventory]; CI rejects uncatalogued actions and stale pages. + +== Estate-wide audit + +A subset of the suite is orchestrated by the reusable workflow +`+.github/workflows/main-estate-audit.yml+`. Each repository *calls* that workflow +from a small caller; it does not copy it (see _Consuming it_). Dedicated language +and scanner workflows are separate entry points, not automatically part of the +estate audit. The audit reports five component checks, one check run each: @@ -32,9 +64,13 @@ absent tool a `not_run`/exit 2 instead of a pass. Before wiring this into a repository, read _Known defects_ and _Consuming it_. -=== What actually enforces +=== What actually enforces in the original audit inventory -Of 26 actions, *17 can fail a build and 9 cannot* — and neither group +The following 26-action baseline is not the total suite inventory. The current +link:CATALOGUE.adoc[catalogue] includes the four later language gates, bounded +secret scanner and official SonarCloud receipt verifier as well. + +Of the original 26 actions, *17 can fail a build and 9 cannot* — and neither group is one kind of thing: the 17 split into 14 always-in-the-audit enforcing gates and 3 tool-dependent gates that also refuse (`not_run`, exit 2) when their tool is absent, while the 9 split into 7 advisory gates and @@ -49,9 +85,9 @@ when their tool is absent, while the 9 split into 7 advisory gates and vaulted-tokens · zig-unified-api-adapter |Can fail. A green tick means something. |*Advisory* (7) |badges · gitsea · hosting · metrics · tests-benches · -trust-humans · www-compliance |Do real work, warn on genuinely soft -findings. Failing the estate over a missing Keybase link would be -worse than not checking. +trust-humans · www-compliance |Signal-only checks; some outputs are simulated or heuristic. +Warnings are not certification or a successful live-service check. +See the catalogue cards for each capability’s actual boundary. |*Tool-dependent, not in the audit* (3) |contractile-validation · custom-tools · proof-runner |Can fail — and can refuse: with a subject @@ -74,15 +110,19 @@ the remaining advisory seven are advisory _by design_, which is defensible — provided nobody reads their green tick as a guarantee. Renaming them `+*-advisory+` would settle that permanently. -Verify at any time: +Verify inventory coverage and generated pages at any time: [source,sh] ---- -for a in actions/*/; do - grep -rq 'exit 1' "$a" && echo "ENFORCE $(basename $a)" || echo "advise $(basename $a)" -done +bash scripts/build-capability-catalogue.sh --check +bash tests/capability-catalogue.sh ---- +Classifications are reviewed metadata, not inferred by grepping for `exit 1`. +That string alone cannot establish applicability, enforcement or real execution. +The advisory cards explicitly flag simulated hosting output and heuristic/mock +metrics; they must not be read as live health checks or proof certification. + A gate that cannot fail is worse than no gate, because it is credited as assurance. The advisory seven should either grow teeth or be renamed so nobody reads their green tick as a guarantee. diff --git a/catalogue/README.adoc b/catalogue/README.adoc new file mode 100644 index 0000000..75ae7a3 --- /dev/null +++ b/catalogue/README.adoc @@ -0,0 +1,53 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += Maintaining the Capability Atlas + +For visitors, start at link:../CATALOGUE.adoc[the CI/CD Capability Atlas]. +This directory holds its inventory and generated clade cards, not executable +packages, a repo-chora file or a new required governance document for consumers. + +== Two axes, one primary home + +* *Clade:* the capability's primary purpose. Sentinel, Covenant, Forge, Schema, + Proof, Bridge, Observatory and Frontier are discoverable families. +* *Nature:* what the capability actually does: scanner, receipt verifier, + policy gate, validator, build/test executor, proof executor, integration, + advisory signal or placeholder. +* *Status:* its enforcement boundary, independent of the two discovery axes. + An enforcing source-pattern check is still not a compiler or formal proof. + +BoJ's separation of capability domain and interface/type inspired this layout; +these entries are GitHub Actions, not certified BoJ cartridges. Existing public +paths remain stable. One capability gets one primary clade; related behaviours +are described in its summary and limitations rather than counted as extra products. +Workflow wrappers and caller templates are entry points, not additional actions. + +== Add or revise a capability + +. Implement/review the actual action and its tests first. +. Add its single entry to link:capabilities.json[capabilities.json]. Use a stable + ID matching `actions/-check/action.yml` and an existing primary clade. +. Describe actual behaviour, not aspirational marketing. Record prerequisites, + skipped/not-applicable behaviour and important assurance limitations. Put + unfinished integrations in Frontier with stub/placeholder classification. +. Link the reusable workflow and caller template when these exist. Do not copy + runtime code into clade directories or change public action paths to match names. +. Run the renderer, update the README's headline counts when the inventory grows, + and run the regression checks below. +. Review rendered links and labels. Generated coverage checks do not establish + the semantic correctness of an action or replace its positive/negative controls. + +[source,shell] +---- +bash scripts/build-capability-catalogue.sh +bash scripts/build-capability-catalogue.sh --check +bash tests/capability-catalogue.sh +---- + +The tools use Bash, jq and standard Unix utilities, following repository language policy. The existing hosted controls run +the read-only drift check and tests. Inventory omissions, duplicate/unknown +classifications, missing targets, path escapes, stale pages and stale README +counts fail the checks. Negative controls exercise these boundaries. + +Do not hand-edit generated `clades/*.adoc` or `../CATALOGUE.adoc`; change the +inventory or renderer. A taxonomy change must not silently alter runtime policy, +required contexts, toolchain installation, lock closure or rollout approval. diff --git a/catalogue/capabilities.json b/catalogue/capabilities.json new file mode 100644 index 0000000..2826626 --- /dev/null +++ b/catalogue/capabilities.json @@ -0,0 +1,377 @@ +{ + "schema_version": 1, + "clades": [ + { + "id": "sentinel", + "title": "Sentinel — security & trusted results", + "summary": "Find exposed credentials and verify authoritative analysis without manufacturing a green result." + }, + { + "id": "covenant", + "title": "Covenant — governance & provenance", + "summary": "Establish repository identity, policy documents, attribution and licensing." + }, + { + "id": "forge", + "title": "Forge — source & build hygiene", + "summary": "Control source debt, document formats, language policy and task-runner syntax." + }, + { + "id": "schema", + "title": "Schema — manifests & contracts", + "summary": "Validate structured manifests and executable contract declarations." + }, + { + "id": "proof", + "title": "Proof — languages & verification", + "summary": "Compile, test, inspect interfaces and execute proof tools where applicable." + }, + { + "id": "bridge", + "title": "Bridge — ecosystem integration", + "summary": "Connect BoJ capabilities and external analysis tools to repository checks." + }, + { + "id": "observatory", + "title": "Observatory — advisory signals", + "summary": "Discover useful signals without presenting warnings or heuristics as certification." + }, + { + "id": "frontier", + "title": "Frontier — unfinished capabilities", + "summary": "Visible roadmap boundaries: not implemented assurance and not recommended gates." + } + ], + "capabilities": [ + { + "id": "secret-scan", + "clade": "sentinel", + "status": "enforcing", + "nature": "scanner", + "title": "Bounded secret scanning", + "summary": "Redacted working-tree and history scans with checksum-pinned Gitleaks, real detector controls and Rust/shell supplements.", + "limitations": "Full-history default; complete ancestry required. Fast PR mode requires security-owner approval.", + "path": "actions/secret-scan-check/action.yml", + "workflow": ".github/workflows/secret-scanner-reusable.yml", + "template": "templates/secret-scanner-caller.yml" + }, + { + "id": "secrets", + "clade": "sentinel", + "status": "enforcing", + "nature": "policy-gate", + "title": "Private-key material", + "summary": "Detect PEM/OpenSSH private-key material in the working tree.", + "limitations": "Narrow detector, not a replacement for full-history secret scanning.", + "path": "actions/secrets-check/action.yml" + }, + { + "id": "vaulted-tokens", + "clade": "sentinel", + "status": "enforcing", + "nature": "policy-gate", + "title": "Vaulted token format", + "summary": "Enforce the estate token-wrapper representation policy.", + "limitations": "A format check is not proof that credentials are valid, secret or rotated.", + "path": "actions/vaulted-tokens-check/action.yml" + }, + { + "id": "sonarcloud-result", + "clade": "sentinel", + "status": "enforcing", + "nature": "receipt-verifier", + "title": "Authoritative SonarCloud receipt", + "summary": "Verify the newest official-app result for an exact repository and commit.", + "limitations": "Does not run analysis; missing/pending/skipped/API failures cannot pass. Requires checks: read and existing app coverage.", + "path": "actions/sonarcloud-result-check/action.yml" + }, + { + "id": "required-files", + "clade": "covenant", + "status": "enforcing", + "nature": "policy-gate", + "title": "Repository foundations", + "summary": "Check required structural documents, substance and repository-specific ownership.", + "limitations": "Applicability and repository policy still require review.", + "path": "actions/required-files-check/action.yml" + }, + { + "id": "spdx-license", + "clade": "covenant", + "status": "enforcing", + "nature": "policy-gate", + "title": "Licensing & SPDX", + "summary": "Inspect licence files and estate SPDX conventions.", + "limitations": "Not a legal opinion or full dependency licence audit.", + "path": "actions/spdx-license-check/action.yml" + }, + { + "id": "affirmation", + "clade": "covenant", + "status": "enforcing", + "nature": "policy-gate", + "title": "Affirmation snapshots", + "summary": "Validate applicable AFFIRMATION snapshots and configured signature trust.", + "limitations": "Optional unless declared required; a document is not self-proving.", + "path": "actions/affirmation-check/action.yml" + }, + { + "id": "referencing", + "clade": "covenant", + "status": "enforcing", + "nature": "validator", + "title": "Citation metadata", + "summary": "Validate core Citation File Format fields when applicable.", + "limitations": "Not a scholarly accuracy or citation-completeness review.", + "path": "actions/referencing-check/action.yml" + }, + { + "id": "code-hygiene", + "clade": "forge", + "status": "enforcing", + "nature": "policy-gate", + "title": "Source debt & proof escapes", + "summary": "Find untracked debt markers and undeclared proof circumventions with source-aware rules.", + "limitations": "Declared trusted bases and reviewed exemptions matter; not a semantic proof.", + "path": "actions/code-hygiene-check/action.yml" + }, + { + "id": "formatting", + "clade": "forge", + "status": "enforcing", + "nature": "policy-gate", + "title": "Document format policy", + "summary": "Enforce estate file-format conventions with named exceptions.", + "limitations": "Opinionated estate policy, not a general-purpose formatter.", + "path": "actions/formatting-check/action.yml" + }, + { + "id": "linguist", + "clade": "forge", + "status": "enforcing", + "nature": "policy-gate", + "title": "Language inventory policy", + "summary": "Inspect language policy and Linguist configuration.", + "limitations": "Static repository policy, not compiler validation.", + "path": "actions/linguist-check/action.yml" + }, + { + "id": "recipes-set", + "clade": "forge", + "status": "enforcing", + "nature": "validator", + "title": "Task-runner syntax", + "summary": "Parse-check Justfile or Makefile recipes.", + "limitations": "Syntax validation does not execute or prove every recipe.", + "path": "actions/recipes-set-check/action.yml" + }, + { + "id": "manifest", + "clade": "schema", + "status": "enforcing", + "nature": "validator", + "title": "DEED & K9 manifests", + "summary": "Use maintained format validators for manifest structure.", + "limitations": "Validator/source prerequisites apply; structure is not runtime correctness.", + "path": "actions/manifest-check/action.yml" + }, + { + "id": "contractile-validation", + "clade": "schema", + "status": "tool-dependent", + "nature": "validator", + "title": "Contractile declarations", + "summary": "Validate applicable DEED contract declarations with maintained tooling.", + "limitations": "Not in the default estate audit; applicability and validator prerequisites apply.", + "path": "actions/contractile-validation-check/action.yml" + }, + { + "id": "rust-ci", + "clade": "proof", + "status": "enforcing", + "nature": "build-test", + "title": "Strict Rust CI", + "summary": "Locked check, formatting, clippy, tests, doctests, documentation and MSRV phases.", + "limitations": "Use the reusable workflow for toolchain setup; only applicable Rust subjects are checked.", + "path": "actions/rust-ci-check/action.yml", + "workflow": ".github/workflows/rust-ci.yml", + "template": "templates/rust-ci-caller.yml" + }, + { + "id": "creusot", + "clade": "proof", + "status": "enforcing", + "nature": "proof-executor", + "title": "Rust deductive verification", + "summary": "Inspect verification claims, run planted controls and execute Creusot obligations.", + "limitations": "Pinned proof tooling and actual obligations required; inspect detect/theatre/prove phases.", + "path": "actions/creusot-check/action.yml", + "workflow": ".github/workflows/creusot-gate.yml", + "template": "templates/creusot-gate-caller.yml" + }, + { + "id": "spark", + "clade": "proof", + "status": "enforcing", + "nature": "proof-executor", + "title": "Ada/SPARK proof", + "summary": "Inspect SPARK projects, run planted controls and execute GNATprove.", + "limitations": "Requires the proof toolchain; absence is not proof success.", + "path": "actions/spark-check/action.yml", + "workflow": ".github/workflows/spark-gate.yml", + "template": "templates/spark-gate-caller.yml" + }, + { + "id": "kanren", + "clade": "proof", + "status": "enforcing", + "nature": "build-test", + "title": "Relational-code checks", + "summary": "Detect relations, require goal-level tests and run applicable relational tests.", + "limitations": "Interpreter prerequisites apply; impure-operator policy is configurable.", + "path": "actions/kanren-check/action.yml", + "workflow": ".github/workflows/kanren-gate.yml", + "template": "templates/kanren-gate-caller.yml" + }, + { + "id": "proof-runner", + "clade": "proof", + "status": "tool-dependent", + "nature": "proof-executor", + "title": "Idris2 & Lean proof runner", + "summary": "Run applicable Idris2 project typechecks and Lean lake builds.", + "limitations": "Not in default audit; a present project without its tool reports not_run, not success.", + "path": "actions/proof-runner-check/action.yml" + }, + { + "id": "idris2-abi", + "clade": "proof", + "status": "enforcing", + "nature": "policy-gate", + "title": "Idris2 ABI source policy", + "summary": "When abi.ipkg exists, scan selected ABI source paths for prohibited IO/unsafe patterns.", + "limitations": "Source-pattern check only: this action does not run the Idris2 compiler or establish formal purity.", + "path": "actions/idris2-abi-check/action.yml" + }, + { + "id": "zig-unified-api-adapter", + "clade": "proof", + "status": "enforcing", + "nature": "policy-gate", + "title": "Zig adapter source policy", + "summary": "Scan Zig files for direct std.fs/std.io usage prohibited by estate adapter policy.", + "limitations": "Pattern check, not a Zig compiler invocation or proof of adapter correctness.", + "path": "actions/zig-unified-api-adapter-check/action.yml" + }, + { + "id": "boj-cartridge", + "clade": "bridge", + "status": "enforcing", + "nature": "integration", + "title": "BoJ cartridge applicability", + "summary": "Check cartridge presence when BoJ integration applies or is declared required.", + "limitations": "Does not prove a cartridge conforms to the full BoJ specification.", + "path": "actions/boj-cartridge-check/action.yml" + }, + { + "id": "custom-tools", + "clade": "bridge", + "status": "tool-dependent", + "nature": "integration", + "title": "Pons & Panic Attack", + "summary": "Execute pons scan and panic-attack assail with explicit unavailable-tool outcomes.", + "limitations": "Install both tools first; not in default audit. Missing tools are not a passing scan.", + "path": "actions/custom-tools-check/action.yml" + }, + { + "id": "badges", + "clade": "observatory", + "status": "advisory", + "nature": "advisory", + "title": "Accreditations & badges", + "summary": "Inspect badge/accreditation conventions and report advisory signals.", + "limitations": "Not independent certification of the advertised accreditation.", + "path": "actions/badges-check/action.yml" + }, + { + "id": "gitsea", + "clade": "observatory", + "status": "advisory", + "nature": "advisory", + "title": "Analytics declarations", + "summary": "Inspect Git-Sea analytics configuration and disclaimer conventions.", + "limitations": "Configuration signals, not a privacy or analytics-service audit.", + "path": "actions/gitsea-check/action.yml" + }, + { + "id": "hosting", + "clade": "observatory", + "status": "advisory", + "nature": "advisory", + "title": "Hosting configuration", + "summary": "Identify hosting targets from repository configuration.", + "limitations": "Live service-health reporting is simulated in the current action; no verified deployment health.", + "path": "actions/hosting-check/action.yml" + }, + { + "id": "metrics", + "clade": "observatory", + "status": "advisory", + "nature": "advisory", + "title": "Metrics & proof indicators", + "summary": "Extract log/source heuristics for an advisory metrics view.", + "limitations": "Contains simulated defaults and brittle source-count heuristics; never use its PROVEN label as proof evidence.", + "path": "actions/metrics-check/action.yml" + }, + { + "id": "tests-benches", + "clade": "observatory", + "status": "advisory", + "nature": "advisory", + "title": "Test & benchmark discoverability", + "summary": "Look for benchmark mentions and test/benchmark dashboards.", + "limitations": "Does not execute tests/benchmarks; metric extraction is mocked/N/A.", + "path": "actions/tests-benches-check/action.yml" + }, + { + "id": "trust-humans", + "clade": "observatory", + "status": "advisory", + "nature": "advisory", + "title": "Human trust declarations", + "summary": "Inspect trust.txt/humans.txt and association conventions.", + "limitations": "Presence is not verification of identity or trustworthiness.", + "path": "actions/trust-humans-check/action.yml" + }, + { + "id": "www-compliance", + "clade": "observatory", + "status": "advisory", + "nature": "advisory", + "title": "Web & well-known conventions", + "summary": "Inspect website and well-known/resource conventions.", + "limitations": "Advisory repository inspection, not a complete standards-conformance audit.", + "path": "actions/www-compliance-check/action.yml" + }, + { + "id": "prat", + "clade": "frontier", + "status": "stub", + "nature": "placeholder", + "title": "PRAT testing placeholder", + "summary": "Heuristic presence/mention detection for prospective property-testing integration.", + "limitations": "Does not execute property tests or prove PRAT coverage; excluded from default audit.", + "path": "actions/prat-check/action.yml" + }, + { + "id": "semantic-audit", + "clade": "frontier", + "status": "stub", + "nature": "placeholder", + "title": "Semantic audit placeholder", + "summary": "Reserved integration point for future semantic analysis.", + "limitations": "Current action prints a success message without invoking the proposed analyser. Not assurance; excluded from default audit.", + "path": "actions/semantic-audit-check/action.yml" + } + ] +} diff --git a/catalogue/clades/bridge.adoc b/catalogue/clades/bridge.adoc new file mode 100644 index 0000000..ebfece7 --- /dev/null +++ b/catalogue/clades/bridge.adoc @@ -0,0 +1,30 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Generated by scripts/build-capability-catalogue.sh; edit catalogue/capabilities.json. += Bridge — ecosystem integration +:toc: + +link:../../CATALOGUE.adoc[Back to the Capability Atlas] + +Connect BoJ capabilities and external analysis tools to repository checks. + +[[boj-cartridge]] +== BoJ cartridge applicability + +*`boj-cartridge` · integration · enforcing* + +Check cartridge presence when BoJ integration applies or is declared required. + +*Assurance boundary:* Does not prove a cartridge conforms to the full BoJ specification. + +* link:../../actions/boj-cartridge-check/action.yml[Action definition and inputs] + +[[custom-tools]] +== Pons & Panic Attack + +*`custom-tools` · integration · tool-dependent* + +Execute pons scan and panic-attack assail with explicit unavailable-tool outcomes. + +*Assurance boundary:* Install both tools first; not in default audit. Missing tools are not a passing scan. + +* link:../../actions/custom-tools-check/action.yml[Action definition and inputs] diff --git a/catalogue/clades/covenant.adoc b/catalogue/clades/covenant.adoc new file mode 100644 index 0000000..a2899ec --- /dev/null +++ b/catalogue/clades/covenant.adoc @@ -0,0 +1,52 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Generated by scripts/build-capability-catalogue.sh; edit catalogue/capabilities.json. += Covenant — governance & provenance +:toc: + +link:../../CATALOGUE.adoc[Back to the Capability Atlas] + +Establish repository identity, policy documents, attribution and licensing. + +[[required-files]] +== Repository foundations + +*`required-files` · policy-gate · enforcing* + +Check required structural documents, substance and repository-specific ownership. + +*Assurance boundary:* Applicability and repository policy still require review. + +* link:../../actions/required-files-check/action.yml[Action definition and inputs] + +[[spdx-license]] +== Licensing & SPDX + +*`spdx-license` · policy-gate · enforcing* + +Inspect licence files and estate SPDX conventions. + +*Assurance boundary:* Not a legal opinion or full dependency licence audit. + +* link:../../actions/spdx-license-check/action.yml[Action definition and inputs] + +[[affirmation]] +== Affirmation snapshots + +*`affirmation` · policy-gate · enforcing* + +Validate applicable AFFIRMATION snapshots and configured signature trust. + +*Assurance boundary:* Optional unless declared required; a document is not self-proving. + +* link:../../actions/affirmation-check/action.yml[Action definition and inputs] + +[[referencing]] +== Citation metadata + +*`referencing` · validator · enforcing* + +Validate core Citation File Format fields when applicable. + +*Assurance boundary:* Not a scholarly accuracy or citation-completeness review. + +* link:../../actions/referencing-check/action.yml[Action definition and inputs] diff --git a/catalogue/clades/forge.adoc b/catalogue/clades/forge.adoc new file mode 100644 index 0000000..c80fc55 --- /dev/null +++ b/catalogue/clades/forge.adoc @@ -0,0 +1,52 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Generated by scripts/build-capability-catalogue.sh; edit catalogue/capabilities.json. += Forge — source & build hygiene +:toc: + +link:../../CATALOGUE.adoc[Back to the Capability Atlas] + +Control source debt, document formats, language policy and task-runner syntax. + +[[code-hygiene]] +== Source debt & proof escapes + +*`code-hygiene` · policy-gate · enforcing* + +Find untracked debt markers and undeclared proof circumventions with source-aware rules. + +*Assurance boundary:* Declared trusted bases and reviewed exemptions matter; not a semantic proof. + +* link:../../actions/code-hygiene-check/action.yml[Action definition and inputs] + +[[formatting]] +== Document format policy + +*`formatting` · policy-gate · enforcing* + +Enforce estate file-format conventions with named exceptions. + +*Assurance boundary:* Opinionated estate policy, not a general-purpose formatter. + +* link:../../actions/formatting-check/action.yml[Action definition and inputs] + +[[linguist]] +== Language inventory policy + +*`linguist` · policy-gate · enforcing* + +Inspect language policy and Linguist configuration. + +*Assurance boundary:* Static repository policy, not compiler validation. + +* link:../../actions/linguist-check/action.yml[Action definition and inputs] + +[[recipes-set]] +== Task-runner syntax + +*`recipes-set` · validator · enforcing* + +Parse-check Justfile or Makefile recipes. + +*Assurance boundary:* Syntax validation does not execute or prove every recipe. + +* link:../../actions/recipes-set-check/action.yml[Action definition and inputs] diff --git a/catalogue/clades/frontier.adoc b/catalogue/clades/frontier.adoc new file mode 100644 index 0000000..bf05a6e --- /dev/null +++ b/catalogue/clades/frontier.adoc @@ -0,0 +1,30 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Generated by scripts/build-capability-catalogue.sh; edit catalogue/capabilities.json. += Frontier — unfinished capabilities +:toc: + +link:../../CATALOGUE.adoc[Back to the Capability Atlas] + +Visible roadmap boundaries: not implemented assurance and not recommended gates. + +[[prat]] +== PRAT testing placeholder + +*`prat` · placeholder · stub* + +Heuristic presence/mention detection for prospective property-testing integration. + +*Assurance boundary:* Does not execute property tests or prove PRAT coverage; excluded from default audit. + +* link:../../actions/prat-check/action.yml[Action definition and inputs] + +[[semantic-audit]] +== Semantic audit placeholder + +*`semantic-audit` · placeholder · stub* + +Reserved integration point for future semantic analysis. + +*Assurance boundary:* Current action prints a success message without invoking the proposed analyser. Not assurance; excluded from default audit. + +* link:../../actions/semantic-audit-check/action.yml[Action definition and inputs] diff --git a/catalogue/clades/observatory.adoc b/catalogue/clades/observatory.adoc new file mode 100644 index 0000000..689b7d0 --- /dev/null +++ b/catalogue/clades/observatory.adoc @@ -0,0 +1,85 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Generated by scripts/build-capability-catalogue.sh; edit catalogue/capabilities.json. += Observatory — advisory signals +:toc: + +link:../../CATALOGUE.adoc[Back to the Capability Atlas] + +Discover useful signals without presenting warnings or heuristics as certification. + +[[badges]] +== Accreditations & badges + +*`badges` · advisory · advisory* + +Inspect badge/accreditation conventions and report advisory signals. + +*Assurance boundary:* Not independent certification of the advertised accreditation. + +* link:../../actions/badges-check/action.yml[Action definition and inputs] + +[[gitsea]] +== Analytics declarations + +*`gitsea` · advisory · advisory* + +Inspect Git-Sea analytics configuration and disclaimer conventions. + +*Assurance boundary:* Configuration signals, not a privacy or analytics-service audit. + +* link:../../actions/gitsea-check/action.yml[Action definition and inputs] + +[[hosting]] +== Hosting configuration + +*`hosting` · advisory · advisory* + +Identify hosting targets from repository configuration. + +*Assurance boundary:* Live service-health reporting is simulated in the current action; no verified deployment health. + +* link:../../actions/hosting-check/action.yml[Action definition and inputs] + +[[metrics]] +== Metrics & proof indicators + +*`metrics` · advisory · advisory* + +Extract log/source heuristics for an advisory metrics view. + +*Assurance boundary:* Contains simulated defaults and brittle source-count heuristics; never use its PROVEN label as proof evidence. + +* link:../../actions/metrics-check/action.yml[Action definition and inputs] + +[[tests-benches]] +== Test & benchmark discoverability + +*`tests-benches` · advisory · advisory* + +Look for benchmark mentions and test/benchmark dashboards. + +*Assurance boundary:* Does not execute tests/benchmarks; metric extraction is mocked/N/A. + +* link:../../actions/tests-benches-check/action.yml[Action definition and inputs] + +[[trust-humans]] +== Human trust declarations + +*`trust-humans` · advisory · advisory* + +Inspect trust.txt/humans.txt and association conventions. + +*Assurance boundary:* Presence is not verification of identity or trustworthiness. + +* link:../../actions/trust-humans-check/action.yml[Action definition and inputs] + +[[www-compliance]] +== Web & well-known conventions + +*`www-compliance` · advisory · advisory* + +Inspect website and well-known/resource conventions. + +*Assurance boundary:* Advisory repository inspection, not a complete standards-conformance audit. + +* link:../../actions/www-compliance-check/action.yml[Action definition and inputs] diff --git a/catalogue/clades/proof.adoc b/catalogue/clades/proof.adoc new file mode 100644 index 0000000..ce534ec --- /dev/null +++ b/catalogue/clades/proof.adoc @@ -0,0 +1,93 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Generated by scripts/build-capability-catalogue.sh; edit catalogue/capabilities.json. += Proof — languages & verification +:toc: + +link:../../CATALOGUE.adoc[Back to the Capability Atlas] + +Compile, test, inspect interfaces and execute proof tools where applicable. + +[[rust-ci]] +== Strict Rust CI + +*`rust-ci` · build-test · enforcing* + +Locked check, formatting, clippy, tests, doctests, documentation and MSRV phases. + +*Assurance boundary:* Use the reusable workflow for toolchain setup; only applicable Rust subjects are checked. + +* link:../../actions/rust-ci-check/action.yml[Action definition and inputs] +* link:../../.github/workflows/rust-ci.yml[Reusable workflow] +* link:../../templates/rust-ci-caller.yml[Caller template] + +[[creusot]] +== Rust deductive verification + +*`creusot` · proof-executor · enforcing* + +Inspect verification claims, run planted controls and execute Creusot obligations. + +*Assurance boundary:* Pinned proof tooling and actual obligations required; inspect detect/theatre/prove phases. + +* link:../../actions/creusot-check/action.yml[Action definition and inputs] +* link:../../.github/workflows/creusot-gate.yml[Reusable workflow] +* link:../../templates/creusot-gate-caller.yml[Caller template] + +[[spark]] +== Ada/SPARK proof + +*`spark` · proof-executor · enforcing* + +Inspect SPARK projects, run planted controls and execute GNATprove. + +*Assurance boundary:* Requires the proof toolchain; absence is not proof success. + +* link:../../actions/spark-check/action.yml[Action definition and inputs] +* link:../../.github/workflows/spark-gate.yml[Reusable workflow] +* link:../../templates/spark-gate-caller.yml[Caller template] + +[[kanren]] +== Relational-code checks + +*`kanren` · build-test · enforcing* + +Detect relations, require goal-level tests and run applicable relational tests. + +*Assurance boundary:* Interpreter prerequisites apply; impure-operator policy is configurable. + +* link:../../actions/kanren-check/action.yml[Action definition and inputs] +* link:../../.github/workflows/kanren-gate.yml[Reusable workflow] +* link:../../templates/kanren-gate-caller.yml[Caller template] + +[[proof-runner]] +== Idris2 & Lean proof runner + +*`proof-runner` · proof-executor · tool-dependent* + +Run applicable Idris2 project typechecks and Lean lake builds. + +*Assurance boundary:* Not in default audit; a present project without its tool reports not_run, not success. + +* link:../../actions/proof-runner-check/action.yml[Action definition and inputs] + +[[idris2-abi]] +== Idris2 ABI source policy + +*`idris2-abi` · policy-gate · enforcing* + +When abi.ipkg exists, scan selected ABI source paths for prohibited IO/unsafe patterns. + +*Assurance boundary:* Source-pattern check only: this action does not run the Idris2 compiler or establish formal purity. + +* link:../../actions/idris2-abi-check/action.yml[Action definition and inputs] + +[[zig-unified-api-adapter]] +== Zig adapter source policy + +*`zig-unified-api-adapter` · policy-gate · enforcing* + +Scan Zig files for direct std.fs/std.io usage prohibited by estate adapter policy. + +*Assurance boundary:* Pattern check, not a Zig compiler invocation or proof of adapter correctness. + +* link:../../actions/zig-unified-api-adapter-check/action.yml[Action definition and inputs] diff --git a/catalogue/clades/schema.adoc b/catalogue/clades/schema.adoc new file mode 100644 index 0000000..af73134 --- /dev/null +++ b/catalogue/clades/schema.adoc @@ -0,0 +1,30 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Generated by scripts/build-capability-catalogue.sh; edit catalogue/capabilities.json. += Schema — manifests & contracts +:toc: + +link:../../CATALOGUE.adoc[Back to the Capability Atlas] + +Validate structured manifests and executable contract declarations. + +[[manifest]] +== DEED & K9 manifests + +*`manifest` · validator · enforcing* + +Use maintained format validators for manifest structure. + +*Assurance boundary:* Validator/source prerequisites apply; structure is not runtime correctness. + +* link:../../actions/manifest-check/action.yml[Action definition and inputs] + +[[contractile-validation]] +== Contractile declarations + +*`contractile-validation` · validator · tool-dependent* + +Validate applicable DEED contract declarations with maintained tooling. + +*Assurance boundary:* Not in the default estate audit; applicability and validator prerequisites apply. + +* link:../../actions/contractile-validation-check/action.yml[Action definition and inputs] diff --git a/catalogue/clades/sentinel.adoc b/catalogue/clades/sentinel.adoc new file mode 100644 index 0000000..5546892 --- /dev/null +++ b/catalogue/clades/sentinel.adoc @@ -0,0 +1,54 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 +// Generated by scripts/build-capability-catalogue.sh; edit catalogue/capabilities.json. += Sentinel — security & trusted results +:toc: + +link:../../CATALOGUE.adoc[Back to the Capability Atlas] + +Find exposed credentials and verify authoritative analysis without manufacturing a green result. + +[[secret-scan]] +== Bounded secret scanning + +*`secret-scan` · scanner · enforcing* + +Redacted working-tree and history scans with checksum-pinned Gitleaks, real detector controls and Rust/shell supplements. + +*Assurance boundary:* Full-history default; complete ancestry required. Fast PR mode requires security-owner approval. + +* link:../../actions/secret-scan-check/action.yml[Action definition and inputs] +* link:../../.github/workflows/secret-scanner-reusable.yml[Reusable workflow] +* link:../../templates/secret-scanner-caller.yml[Caller template] + +[[secrets]] +== Private-key material + +*`secrets` · policy-gate · enforcing* + +Detect PEM/OpenSSH private-key material in the working tree. + +*Assurance boundary:* Narrow detector, not a replacement for full-history secret scanning. + +* link:../../actions/secrets-check/action.yml[Action definition and inputs] + +[[vaulted-tokens]] +== Vaulted token format + +*`vaulted-tokens` · policy-gate · enforcing* + +Enforce the estate token-wrapper representation policy. + +*Assurance boundary:* A format check is not proof that credentials are valid, secret or rotated. + +* link:../../actions/vaulted-tokens-check/action.yml[Action definition and inputs] + +[[sonarcloud-result]] +== Authoritative SonarCloud receipt + +*`sonarcloud-result` · receipt-verifier · enforcing* + +Verify the newest official-app result for an exact repository and commit. + +*Assurance boundary:* Does not run analysis; missing/pending/skipped/API failures cannot pass. Requires checks: read and existing app coverage. + +* link:../../actions/sonarcloud-result-check/action.yml[Action definition and inputs] diff --git a/catalogue/render.jq b/catalogue/render.jq new file mode 100644 index 0000000..72386b6 --- /dev/null +++ b/catalogue/render.jq @@ -0,0 +1,70 @@ +# SPDX-License-Identifier: MPL-2.0 +# Emit standalone page records. Only fixed paths and validated clade IDs form paths. +def link($target; $caption; $page): + "link:" + (if $page == "CATALOGUE.adoc" then "" else "../../" end) + $target + "[" + $caption + "]"; +def count_status($items; $status): [$items[] | select(.status == $status)] | length; +def preamble($title): [ + "// SPDX-License-Identifier: CC-BY-SA-4.0", + "// Generated by scripts/build-capability-catalogue.sh; edit catalogue/capabilities.json.", + "= " + $title, ":toc:" +]; +def card($e; $page): [ + "[[" + $e.id + "]]", "== " + $e.title, "", + "*`" + $e.id + "` · " + $e.nature + " · " + $e.status + "*", "", + $e.summary, "", "*Assurance boundary:* " + $e.limitations, "", + "* " + link($e.path; "Action definition and inputs"; $page) +] + (if $e.workflow then ["* " + link($e.workflow; "Reusable workflow"; $page)] else [] end) + + (if $e.template then ["* " + link($e.template; "Caller template"; $page)] else [] end) + [""]; +. as $all | .capabilities as $entries | +[ + (.clades[] as $clade | + "catalogue/clades/\($clade.id).adoc" as $page | + {path: $page, content: ((preamble($clade.title) + ["", link("CATALOGUE.adoc"; "Back to the Capability Atlas"; $page), "", $clade.summary, ""] + + [$entries[] | select(.clade == $clade.id) | card(.; $page)[]]) | join("\n"))}), + {path: "CATALOGUE.adoc", content: (( + preamble("The CI/CD Capability Atlas") + [ + ":toclevels: 2", "", + "*Repository assurance, organised by purpose. Discover by clade; choose by nature; adopt with evidence.*", "", + "*\($entries | length) composite actions · \(.clades | length) clades · two independent discovery axes.*", "", + "This is a visitor-facing product catalogue, not a repo-chora file, a BoJ cartridge implementation, or a certification scheme. Inspired by BoJ's separation of capability domain from interface/type, it groups existing CI/CD building blocks without moving their paths or changing their behaviour.", "", + "== Find your route", "", + "* *Protect credentials:* <> — bounded secret scanning and authoritative result receipts.", + "* *Establish repository policy:* <>, <> and <>.", + "* *Compile, test or prove:* <> — language-specific execution and explicitly labelled source checks.", + "* *Integrate the ecosystem:* <> — BoJ applicability, Pons and Panic Attack.", + "* *Explore signals and future work:* <> and <> — no inflated assurance claims.", "", + "== The clade matrix", "", "[cols=\"2,4,1,1,1,1,1\",options=\"header\"]", "|===", + "|Clade |Purpose |Total |Enforcing |Tool-dependent |Advisory |Stub" + ] + [ + .clades[] as $c | [$entries[] | select(.clade == $c.id)] as $group | + "|<<\($c.id),\($c.title)>> |\($c.summary) |\($group | length) |\(count_status($group; "enforcing")) |\(count_status($group; "tool-dependent")) |\(count_status($group; "advisory")) |\(count_status($group; "stub"))" + ] + [ + "|===", "", "== Read the assurance labels", "", + "* *Enforcing (\(count_status($entries; "enforcing"))):* can reject a subject. This is not a guarantee of completeness, applicability, production readiness or formal verification.", + "* *Tool-dependent (\(count_status($entries; "tool-dependent"))):* requires explicitly supplied validators/toolchains; inspect applicability and not-run behaviour before adoption.", + "* *Advisory (\(count_status($entries; "advisory"))):* signals and warnings, not an assurance verdict. Some current outputs are simulated or heuristic; each card names the boundary.", + "* *Stub (\(count_status($entries; "stub"))):* unfinished integration or placeholder. Do not deploy as evidence of a completed check.", "", + "Nature is a separate axis: a policy-pattern scan is not a compiler, a receipt verifier is not an analyser, and a proof executor is not a proof that every program is correct. These labels are reviewed inventory metadata; tests enforce coverage and consistency, not semantic correctness of every gate.", "", + "== Browse by nature", "", "[cols=\"2,1,7\",options=\"header\"]", "|===", "|Nature |Count |Capabilities" + ] + [ + ($entries | group_by(.nature)[]) as $group | + "|\($group[0].nature) |\($group | length) |" + ([$group[] | link(.path; .title; "CATALOGUE.adoc")] | join(" · ")) + ] + ["|===", ""] + [ + .clades[] as $c | [$entries[] | select(.clade == $c.id)] as $group | + ["[[" + $c.id + "]]", "== " + $c.title, "", $c.summary, "", + link("catalogue/clades/\($c.id).adoc"; "Explore this clade — \($group | length) capabilities"; "CATALOGUE.adoc"), "", + "[cols=\"2,2,2,5\",options=\"header\"]", "|===", "|Capability |Nature |Status |What it does"] + + [$group[] | "|" + link(.path; .title; "CATALOGUE.adoc") + " |\(.nature) |\(.status) |\(.summary)"] + ["|===", ""] | .[] + ] + [ + "== Adopt deliberately", "", + "Start with a reusable workflow/caller template where supplied: it handles orchestration that a bare composite may not. Read the action's inputs, scripts, prerequisites and test controls. Pin an already-published, tested source SHA; update the caller lock and complete dependency closure together. Never turn unavailable tools, absent analysis or skipped work into a green assurance claim.", "", + "* " + link("templates/estate-audit-caller.yml"; "Estate-audit caller"; "CATALOGUE.adoc"), + "* " + link(".github/workflows/main-estate-audit.yml"; "Estate-audit orchestration"; "CATALOGUE.adoc"), + "* " + link("docs/SECRET-SCANNER-ROLLOUT.adoc"; "Secret-scanner rollout and security boundaries"; "CATALOGUE.adoc"), + "* " + link("docs/GOVERNANCE-AND-SONAR-REPAIR.adoc"; "Governance and Sonar verification guidance"; "CATALOGUE.adoc"), + "* " + link("README.adoc"; "Operational README, known defects and test guidance"; "CATALOGUE.adoc"), "", + "== Keep the atlas honest", "", + "The single inventory is " + link("catalogue/capabilities.json"; "catalogue/capabilities.json"; "CATALOGUE.adoc") + ". Every action must appear exactly once in one primary clade; status and nature remain independent. Adding an action without cataloguing it, breaking a target link, duplicating an entry or leaving generated pages stale fails the catalogue checks.", "", + "[source,shell]", "----", "bash scripts/build-capability-catalogue.sh", "bash scripts/build-capability-catalogue.sh --check", "bash tests/capability-catalogue.sh", "----", "" + ]) | join("\n"))} +] | .[] diff --git a/catalogue/validate.jq b/catalogue/validate.jq new file mode 100644 index 0000000..830fc0f --- /dev/null +++ b/catalogue/validate.jq @@ -0,0 +1,30 @@ +# SPDX-License-Identifier: MPL-2.0 +# Reviewed metadata structure only; not a proof of gate behaviour. +def text: type == "string" and test("\\S") and (test("[\\x00-\\x1f]") | not); +def ident: text and test("^[a-z][a-z0-9-]*$"); +def is_unique: length == (unique | length); +. as $all | +(type == "object") and +(keys == ["capabilities", "clades", "schema_version"]) and +(.schema_version == 1) and +(.clades | type == "array" and length > 0) and +all(.clades[]; (keys == ["id", "summary", "title"]) and all(.[]; text) and (.id | ident)) and +([.clades[].id] | is_unique) and +(.capabilities | type == "array" and length > 0) and +all(.capabilities[]; + . as $e | + (["id", "clade", "status", "nature", "title", "summary", "limitations", "path"] - keys | length == 0) and + (keys - ["id", "clade", "status", "nature", "title", "summary", "limitations", "path", "workflow", "template"] | length == 0) and + all(.[]; text) and + (.id | ident) and + ($all.clades | map(.id) | index($e.clade) != null) and + (["enforcing", "tool-dependent", "advisory", "stub"] | index($e.status) != null) and + (["scanner", "receipt-verifier", "policy-gate", "validator", "build-test", "proof-executor", "integration", "advisory", "placeholder"] | index($e.nature) != null) and + ((.status == "stub") == (.nature == "placeholder")) and + (.path == ("actions/" + .id + "-check/action.yml")) and + ((has("workflow") | not) or (.workflow | test("^\\.github/workflows/[a-zA-Z0-9_-]+\\.yml$"))) and + ((has("template") | not) or (.template | test("^templates/[a-zA-Z0-9_-]+\\.yml$"))) +) and +([.capabilities[].id] | is_unique) and +([.capabilities[].path] | is_unique) and +(([.capabilities[].clade] | unique | sort) == ([.clades[].id] | sort)) diff --git a/scripts/build-capability-catalogue.sh b/scripts/build-capability-catalogue.sh new file mode 100644 index 0000000..0d7a18b --- /dev/null +++ b/scripts/build-capability-catalogue.sh @@ -0,0 +1,44 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Validate reviewed catalogue metadata and render visitor-facing AsciiDoc. +# --check is read-only. CATALOGUE_ROOT supports isolated regression fixtures. +set -euo pipefail +ROOT=${CATALOGUE_ROOT:-$(cd "$(dirname "$0")/.." && pwd)} +ROOT=$(realpath -e "$ROOT") +mode=${1:-} +[[ $# -le 1 && ( -z $mode || $mode == --check ) ]] || { echo 'usage: build-capability-catalogue.sh [--check]' >&2; exit 2; } +for tool in jq realpath cmp; do command -v "$tool" >/dev/null || { echo "$tool required" >&2; exit 2; }; done +inventory=$ROOT/catalogue/capabilities.json +tmp=$(mktemp -d) +trap 'rm -rf "$tmp"' EXIT +jq -e -f "$ROOT/catalogue/validate.jq" "$inventory" >/dev/null || { echo 'invalid catalogue metadata' >&2; exit 1; } +while IFS= read -r target; do + resolved=$(realpath -e "$ROOT/$target") || { echo "missing catalogue target: $target" >&2; exit 1; } + [[ $resolved == "$ROOT/"* && -f $resolved ]] || { echo "escaping catalogue target: $target" >&2; exit 1; } +done < <(jq -r '.capabilities[] | (.path, .workflow, .template) | select(. != null)' "$inventory") +for path in "$ROOT"/actions/*/action.yml; do + [[ ! -f $path ]] || printf '%s\n' "${path#"$ROOT/"}" +done | LC_ALL=C sort > "$tmp/actual" +jq -r '.capabilities[].path' "$inventory" | LC_ALL=C sort > "$tmp/declared" +cmp -s "$tmp/actual" "$tmp/declared" || { echo 'action inventory drift: every action must appear exactly once' >&2; exit 1; } +jq -c -f "$ROOT/catalogue/render.jq" "$inventory" > "$tmp/pages.jsonl" +mkdir -p "$tmp/pages" +while IFS= read -r record; do + page=$(jq -er '.path' <<< "$record") + [[ $page == CATALOGUE.adoc || $page =~ ^catalogue/clades/[a-z][a-z0-9-]*\.adoc$ ]] || exit 1 + mkdir -p "$tmp/pages/$(dirname "$page")" + jq -j '.content' <<< "$record" > "$tmp/pages/$page" + if [[ $mode == --check ]]; then + cmp -s "$tmp/pages/$page" "$ROOT/$page" || { echo "stale catalogue page: $page" >&2; exit 1; } + fi +done < "$tmp/pages.jsonl" +# Reject orphan generated pages; never silently delete a page from the repo. +for page in "$ROOT"/catalogue/clades/*.adoc; do + [[ ! -f $page || -f "$tmp/pages/catalogue/clades/$(basename "$page")" ]] || { echo "orphan clade page: $page" >&2; exit 1; } +done +if [[ $mode != --check ]]; then + mkdir -p "$ROOT/catalogue/clades" + cp "$tmp/pages/CATALOGUE.adoc" "$ROOT/CATALOGUE.adoc" + cp "$tmp/pages/catalogue/clades/"*.adoc "$ROOT/catalogue/clades/" +fi +jq -r '"Catalogue: \(.capabilities|length) actions, \(.clades|length) clades; inventory and pages valid"' "$inventory" diff --git a/tests/capability-catalogue.sh b/tests/capability-catalogue.sh new file mode 100644 index 0000000..f7892dd --- /dev/null +++ b/tests/capability-catalogue.sh @@ -0,0 +1,75 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Inventory/navigation regression tests with actual jq and isolated mutants. +set -euo pipefail +ROOT=$(cd "$(dirname "$0")/.." && pwd) +tmp=$(mktemp -d) +trap 'rm -rf "$tmp"' EXIT +builder=$ROOT/scripts/build-capability-catalogue.sh +bash "$builder" --check +n=$(jq '.capabilities | length' "$ROOT/catalogue/capabilities.json") +c=$(jq '.clades | length' "$ROOT/catalogue/capabilities.json") +grep -Fq "*$n composite actions" "$ROOT/README.adoc" +grep -Fq "in $c clades*" "$ROOT/README.adoc" +echo 'ok: README entrypoint and counts' +grep -Fq 'link:CATALOGUE.adoc[' "$ROOT/README.adoc" +while IFS= read -r page; do + while IFS= read -r target; do + [[ -f "$(dirname "$page")/$target" ]] || { echo "broken link: $page -> $target" >&2; exit 1; } + done < <(grep -oE 'link:[^[]+\[' "$page" | sed 's/^link://; s/\[$//') +done < <(printf '%s\n' "$ROOT/CATALOGUE.adoc" "$ROOT"/catalogue/clades/*.adoc) +while IFS= read -r target; do + grep -Fxq "[[$target]]" "$ROOT/CATALOGUE.adoc" || { echo "missing clade anchor: $target" >&2; exit 1; } +done < <(grep -oE '<<[^,>]+,' "$ROOT/CATALOGUE.adoc" | sed 's/^</dev/null +expect_failure() { + local name=$1 + if CATALOGUE_ROOT=$fixture bash "$builder" --check > "$tmp/log" 2>&1; then + echo "FAIL: accepted mutant $name" >&2; exit 1 + fi + echo "ok: refused $name" +} +mutate() { + jq "$2" "$ROOT/catalogue/capabilities.json" > "$fixture/catalogue/capabilities.json" + expect_failure "$1" + cp "$ROOT/catalogue/capabilities.json" "$fixture/catalogue/capabilities.json" +} +mutate 'dropped action' '.capabilities |= .[:-1]' +mutate 'duplicate action' '.capabilities += [.capabilities[0]]' +mutate 'unknown clade' '.capabilities[0].clade="imaginary"' +mutate 'unknown status' '.capabilities[0].status="certified-perfect"' +mutate 'unknown nature' '.capabilities[0].nature="magic"' +mutate 'path traversal' '.capabilities[0].workflow="../outside.yml"' +mutate 'missing target' '.capabilities[0].workflow=".github/workflows/absent.yml"' +mutate 'placeholder relabelled enforcing' '(.capabilities[] | select(.status=="stub")).status="enforcing"' +mutate 'empty assurance boundary' '.capabilities[0].limitations=" "' +mutate 'unsupported schema' '.schema_version=99' +mutate 'empty clade' '.clades += [{id:"empty",title:"Empty",summary:"No entries"}]' +mkdir "$fixture/actions/uncatalogued-check" +printf 'name: uncatalogued\n' > "$fixture/actions/uncatalogued-check/action.yml" +expect_failure 'uncatalogued new action' +rm "$fixture/actions/uncatalogued-check/action.yml" +rmdir "$fixture/actions/uncatalogued-check" +first=$(jq -r '.capabilities[0].path' "$ROOT/catalogue/capabilities.json") +cp "$fixture/$first" "$tmp/action.yml" +rm "$fixture/$first" +ln -s "$tmp/action.yml" "$fixture/$first" +expect_failure 'symlink escape' +rm "$fixture/$first" +cp "$tmp/action.yml" "$fixture/$first" +printf 'stale\n' > "$fixture/CATALOGUE.adoc" +expect_failure 'stale output' +cp "$ROOT/CATALOGUE.adoc" "$fixture/CATALOGUE.adoc" +printf 'orphan\n' > "$fixture/catalogue/clades/orphan.adoc" +expect_failure 'orphan page' +rm "$fixture/catalogue/clades/orphan.adoc" +# A real regeneration must be deterministic and recreate the original pages. +CATALOGUE_ROOT=$fixture bash "$builder" >/dev/null +cmp "$ROOT/CATALOGUE.adoc" "$fixture/CATALOGUE.adoc" +diff -r "$ROOT/catalogue/clades" "$fixture/catalogue/clades" +CATALOGUE_ROOT=$fixture bash "$builder" --check >/dev/null +echo 'ok: deterministic regeneration, current pages and 15 negative controls'