docs: close consumer alpha readiness gaps

Author: relotnek

.github/workflows/g0-contract.yml

@@ -65,7 +65,16 @@ jobs:
 
       - name: Validate Ecosystem Baseline composition and planted fixtures
         run: |
-          bash scripts/test-ecosystem-baseline.sh
+          result_file="${RUNNER_TEMP}/ecosystem-baseline-detection.json"
+          docker run --rm \
+            --volume "${GITHUB_WORKSPACE}:/src:ro" \
+            --workdir /src \
+            semgrep/semgrep:1.93.0@sha256:f35c7891e2030110a84a721fdd556ce8f3da6e7e69d7fab1d3660ae1bb334474 \
+            semgrep scan --metrics=off --disable-version-check \
+              --config rules/ecosystem-baseline.yml \
+              --json test/fixtures/ecosystem-baseline/monorepo > "$result_file"
+          BASELINE_RUN_DETECTION=true BASELINE_RESULT_FILE="$result_file" \
+            bash scripts/test-ecosystem-baseline.sh
           bash scripts/test-consumer-alpha.sh
 
       - name: Validate shell, workflow, example, and fork-fixture syntax

docs/README.md

@@ -41,6 +41,7 @@ policy, exceptions, upgrades, and rollback across projects.
 - [Evaluation adapter](reference/evaluation-adapter.md)
 - [Evidence Bundle and profile conclusion](reference/evidence-bundle.md)
 - [Ecosystem Baseline static rules](reference/ecosystem-baseline-rules.md)
+- [Permission-free Zizmor adapter](reference/zizmor-scan.md)
 - [Release integrity](reference/release-integrity.md)
 - [Fork pull-request safety](reference/fork-pr-safety.md)
 - [Documentation architecture](DOCUMENTATION-ARCHITECTURE.md)

docs/consumers/quickstart.md

@@ -33,8 +33,9 @@ license, package installation, build command, or write permission. An unrelated
 4. Confirm the workflow uses ordinary `pull_request`, not
    `pull_request_target`.
 
-The example starts all finding gates advisory while keeping
-`require-complete: true`. Tool failure, missing evidence, a skipped required
+The example starts its configurable workflow, dependency, IaC, and static
+analysis gates advisory while keeping `require-complete: true`. Gitleaks
+findings remain blocking. Tool failure, missing evidence, a skipped required
 evaluation, or malformed output still fails `Profile Conclusion`.
 
 ## Verify The First Run

docs/consumers/understand-results.md

@@ -16,24 +16,26 @@ not equivalent to zero findings.
 
 ## Current Behavior
 
-The scanner outcome adapter and AI review action now emit the pre-v1
-[Evaluation Result contract](../reference/evaluation-result.md):
+The Ecosystem Baseline's five scanner adapters and the AI review action emit
+the pre-v1 [Evaluation Result contract](../reference/evaluation-result.md):
 
 - scanner outputs may appear in job logs, SARIF, or artifacts;
 - supported scanner gates keep advisory findings green by policy while
   malformed SARIF and tool failure fail independently;
 - scanner event/configuration skips are represented as `skipped`;
 - AI refusal and large-diff or response truncation are `incomplete`;
 - a missing Anthropic secret is `skipped`, never zero findings;
-- the umbrella workflow does not aggregate one authoritative completion status.
+- the Ecosystem Baseline aggregates its five required results into one Evidence
+  Bundle and one authoritative `Profile Conclusion` check.
 
-Until evidence aggregation is complete, inspect each action's
-`evaluation-result` output alongside its raw artifact and job conclusion.
+For the Ecosystem Baseline, start with `Profile Conclusion` and the
+`ecosystem-baseline-evidence` artifact. Inspect an individual Evaluation Result
+and its raw evidence when the bundle reports findings or incomplete coverage.
 
-For Trivy and Semgrep, the scanner-outcome adapter validates SARIF and reports
-all four completion states independently from `findings`/`no-findings` and
-`pass`/`fail`/`skip`/`error`. The parent workflow does not yet aggregate those
-values into one authoritative Evidence Bundle.
+The legacy full security pipeline has not migrated every scanner to the
+aggregate contract. In that pipeline, inspect each scanner's result, raw
+artifact, and job conclusion independently; do not infer suite-wide completion
+from a green parent workflow.
 
 ## Target Completion Status
 

docs/maintainers/g0-gate.md

@@ -25,6 +25,7 @@ It runs on every pull request and every push to `main`; it has only
 | Completion is never inferred from green status | Evaluation Result schema check | `test-evaluation-result.sh` covers complete, incomplete, skipped, and error outputs |
 | Secret scanning is secretless and scoped | checksum-pinned Gitleaks adapter | `test-gitleaks-scan.sh` plants credentials and tests PR-range/full-history behavior |
 | Consumer workflow definitions are evaluated | pinned Zizmor workflow | `test-consumer-actions-security.sh` plants unsafe triggers, refs, permissions, interpolation, checkout, OIDC, and invalid YAML |
+| Ecosystem rules detect supported language fixtures | digest-pinned Semgrep image | `test-ecosystem-baseline.sh` requires detections in Go, Rust, JavaScript, Solidity, and Dockerfile fixtures |
 | One pin selects the complete immutable graph | `check-release-graph.sh` | `test-release-graph.sh` mutates refs, image digests, nested workflows, and assets |
 | Fork PRs stay inside read-only, secretless boundaries | `check-fork-pr.sh` | `test-fork-pr.sh` mutates all eight fork boundaries |
 | Consumer examples remain valid contracts | documentation, authority, trust, and syntax checks | any stale permission, mutable pin, unsafe input, or invalid YAML fails G0 |

docs/reference/README.md

@@ -11,6 +11,7 @@ will replace manual tables after the evaluation and profile schemas stabilize.
 - [Evaluation adapter](evaluation-adapter.md)
 - [Evidence Bundle and profile conclusion](evidence-bundle.md)
 - [Ecosystem Baseline static rules](ecosystem-baseline-rules.md)
+- [Permission-free Zizmor adapter](zizmor-scan.md)
 - [Release integrity](release-integrity.md)
 - [Fork pull-request safety](fork-pr-safety.md)
 
@@ -36,6 +37,7 @@ will replace manual tables after the evaluation and profile schemas stabilize.
 
 - [AI code-review metadata](../../actions/ai-code-review/action.yml)
 - [Secretless Gitleaks adapter](../../actions/gitleaks-scan/action.yml)
+- [Permission-free Zizmor adapter](../../actions/zizmor-scan/action.yml)
 - [AI result schema](../../actions/ai-code-review/scripts/schema.json)
 - [Scanner outcome adapter](../../actions/scanner-outcome/action.yml)
 - [Generic evaluation adapter](../../actions/evaluation-adapter/action.yml)

docs/reference/current-contracts.md

@@ -89,8 +89,8 @@ The [Ecosystem Baseline](../../.github/workflows/ecosystem-baseline.yml) is the
 consumer-testable normalized profile. It composes workflow security,
 dependencies, secrets, IaC, and repository-owned static rules, then emits one
 Evidence Bundle and `Profile Conclusion`. Its inputs are
-`dependency-blocking`, `iac-blocking`, `static-analysis-blocking`,
-`require-complete`, and `skip-dirs`.
+`actions-security-blocking`, `dependency-blocking`, `iac-blocking`,
+`static-analysis-blocking`, `require-complete`, and `skip-dirs`.
 
 ### Scanner Toggles
 
@@ -113,11 +113,13 @@ Evidence Bundle and `Profile Conclusion`. Its inputs are
 | Input | Default | Notes |
 |---|---|---|
 | `skip-dirs` | `node_modules` | Comma-separated Trivy exclusions |
+| `actions-security-blocking` | `false` | Fail on workflow-definition findings; tool failure always fails |
 | `semgrep-blocking` | `false` | Fail on custom-rule findings; tool failure always fails |
 | `codeql-languages` | `["javascript-typescript"]` | JSON array |
 | `dependency-review-fail-on-severity` | `high` | Dependency-review threshold |
 | `dependency-blocking` | `false` | Fail on dependency findings; tool failure always fails |
 | `dependency-severity` | `CRITICAL,HIGH,MEDIUM` | Dependency findings included in the gate |
+| `publish-sarif` | `false` | Publish dependency SARIF using a separate write-authorized job |
 | `iac-blocking` | `false` | Fail on IaC findings; tool failure always fails |
 | `iac-severity` | `CRITICAL,HIGH,MEDIUM` | IaC findings included in the gate |
 | `license-blocking` | `false` | Fail on license findings; tool failure always fails |

docs/reference/zizmor-scan.md

@@ -0,0 +1,97 @@
+# Permission-Free Zizmor Adapter
+
+**Stability:** consumer-testable pre-v1 alpha. Introduced in the optimization
+release candidate; its inputs and outputs may change before v1.
+
+**Owner:** Filecoin ecosystem security platform maintainers. A repository-wide
+CODEOWNERS policy has not yet been established and remains a pre-v1 governance
+gap.
+
+[`actions/zizmor-scan`](../../actions/zizmor-scan/action.yml) inspects GitHub
+Actions workflow and action definitions with Zizmor 1.28.0 in offline mode. It
+separates operational success from findings and does not require GitHub Code
+Security or `security-events: write`.
+
+## Immutable Consumption
+
+The supported Ecosystem Baseline already composes this adapter. Platform
+Maintainers needing it inside a custom job can pin the repository action:
+
+```yaml
+permissions:
+  contents: read
+
+steps:
+  - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+    with:
+      persist-credentials: false
+  - id: zizmor
+    uses: filecoin-project/ff-sec-actions/actions/zizmor-scan@a6c0e17e90c5d2baef63b32e490c1f080ab97add
+    with:
+      input-path: .
+      result-file: ${{ runner.temp }}/zizmor-actions.sarif
+```
+
+Do not replace either full commit with a branch or mutable tag. Consumer
+Engineers who want the normalized result and stable merge check should use the
+[Ecosystem Baseline](../consumers/ecosystem-baseline.md), not this leaf action.
+
+## Authority And Execution Boundary
+
+| Boundary | Behavior |
+|---|---|
+| Permissions | The adapter calls no GitHub API. A preceding checkout normally needs only `contents: read`. |
+| Secrets | None required or read. |
+| Network | Downloads a Zizmor release archive from GitHub over HTTPS unless `ZIZMOR_BIN` selects a preinstalled executable. The archive SHA-256 is pinned per supported platform. Zizmor itself runs `--offline`. |
+| Consumer code | Parses workflow YAML and action metadata; it does not run project build, package-manager, shell, or lifecycle commands. |
+
+## Inputs
+
+| Input | Required | Default | Meaning |
+|---|---:|---|---|
+| `input-path` | No | `.` | Repository path containing workflow and action definitions. |
+| `config-path` | No | Empty | Explicit Zizmor configuration. Empty disables repository configuration discovery. |
+| `result-file` | No | `zizmor-results.sarif` | Runner-local SARIF destination. |
+
+## Outputs And Completion
+
+| Output | Meaning |
+|---|---|
+| `scanner-outcome` | `success` when Zizmor ran and emitted SARIF, including when it found issues; `failure` for installation or scanner errors. |
+| `result-file` | The requested runner-local SARIF path. |
+
+Findings do not fail this leaf action. Its caller must validate SARIF and choose
+advisory or blocking policy; the supported `sec-actions.yml` workflow does that
+with the Evaluation Adapter. Operational failure is exposed through
+`scanner-outcome=failure` so it cannot be represented as zero findings.
+
+The action itself uploads no artifact and sets no retention period. The
+supported workflow uploads `evaluation-result-zizmor-actions` using GitHub's
+repository-default artifact retention. Raw SARIF remains runner-local unless a
+caller explicitly uploads it.
+
+## Events, Forks, And Runners
+
+The action has no event-specific behavior and can run on `pull_request`,
+`push`, `schedule`, or `workflow_dispatch`. It is fork-safe under a normal
+`pull_request` when the caller keeps read-only permissions and passes no
+secrets. Do not switch a consumer workflow to `pull_request_target`.
+
+The verified installer supports GitHub-hosted Linux and macOS runners on x64
+and arm64. Other operating systems and architectures fail explicitly. Self-
+hosted runners must provide the same basic shell tools and outbound access, or
+preinstall Zizmor and select it with `ZIZMOR_BIN`.
+
+## Compatibility And Deprecation
+
+The adapter currently fixes Zizmor at 1.28.0 and uses its SARIF interface.
+Changing the tool version, checksums, severity/persona defaults, output shape,
+or supported platforms requires fixture verification and a reviewed immutable
+pin advance. There is no deprecated input or migration path yet because this
+surface is pre-v1.
+
+## Next
+
+- [Adopt the Ecosystem Baseline](../consumers/ecosystem-baseline.md)
+- [Understand Evaluation Results](../consumers/understand-results.md)
+- [Review release integrity](release-integrity.md)

examples/consumer-security-pipeline.yml

@@ -36,9 +36,9 @@ jobs:
       # installation hooks from repository content.
       skip-dirs: node_modules,contracts/lib,.sst
       publish-sarif: ${{ vars.ENABLE_GHAS == 'true' }}
-      # GitHub Actions security is enabled by default and blocks medium-or-higher
-      # zizmor auditor findings. Keep findings advisory for the first run, then
-      # set actions-security-blocking: true after triage.
+      # GitHub Actions security is enabled by default and reports
+      # medium-or-higher Zizmor auditor findings. Keep them advisory for the
+      # first run, then set actions-security-blocking: true after triage.
       actions-security-blocking: false
       # Finding gates are independent from tool failure; tool failure always
       # fails. Uncomment only after observing the advisory result volume:

scripts/check-docs.sh

@@ -63,6 +63,7 @@ required_pages=(
   "docs/reference/evaluation-adapter.md"
   "docs/reference/evidence-bundle.md"
   "docs/reference/ecosystem-baseline-rules.md"
+  "docs/reference/zizmor-scan.md"
   "docs/reference/release-integrity.md"
   "docs/reference/fork-pr-safety.md"
   "docs/DOCUMENTATION-ARCHITECTURE.md"
@@ -159,6 +160,13 @@ if [ -f ".github/workflows/g0-contract.yml" ]; then
   require_text ".github/workflows/g0-contract.yml" "bash scripts/check-fork-pr.sh"
   require_text ".github/workflows/g0-contract.yml" "bash scripts/test-fork-pr.sh"
   require_text ".github/workflows/g0-contract.yml" "bash scripts/test-ecosystem-baseline.sh"
+  require_text ".github/workflows/g0-contract.yml" "BASELINE_RUN_DETECTION=true"
+  require_text ".github/workflows/g0-contract.yml" "semgrep/semgrep:1.93.0@sha256:f35c7891e2030110a84a721fdd556ce8f3da6e7e69d7fab1d3660ae1bb334474"
+fi
+
+if [ -f "docs/reference/current-contracts.md" ]; then
+  require_text "docs/reference/current-contracts.md" "actions-security-blocking"
+  require_text "docs/reference/current-contracts.md" "publish-sarif"
 fi
 
 if grep -REq '^[[:space:]-]*uses:.*@v1([[:space:]]|$)' examples; then