Goal: make ff-sec-actions a robust, reusable security-evaluation platform for
independent Filecoin ecosystem projects without turning a green check into a
false claim of safety.
This map is the canonical decision artifact. The machine-readable roadmap is the canonical implementation queue for task order, dependencies, acceptance criteria, verification, and status. Resolve open decision tickets when their corresponding roadmap task is claimed.
- Ecosystem Baseline — secretless, read-only, safe on untrusted PRs.
- Security Profiles — Go node, Rust/FVM actor, Solidity/FEVM, service, and infrastructure coverage layered on the baseline.
- Privileged Analyses — AI review, PR comments, publishing, and other capabilities isolated behind explicit authority.
- Evidence and policy — every evaluation emits a normalized result and completion status; consumers independently choose their Merge Gate.
- Documentation system — Consumer Engineers, Platform Maintainers, and Rollout Operators each have a tested path through adoption, operation, extension, release, and rollback.
| Gate | Exit criteria |
|---|---|
| G0 — Trustworthy foundation | No untrusted code runs with write/OIDC authority; transitive workflow code is immutably pinned; scanners cannot silently pass on findings or incomplete execution; examples and trust claims are checked against implementation. |
| G1 — Internal alpha | Ecosystem Baseline and one Security Profile pass adversarial fixtures and run end-to-end in a sandbox Consumer Project through the documented quickstart. |
| G2 — Multi-profile pilot | Go, Rust, Solidity, and service profiles run in representative projects; evidence is normalized; every pilot profile has tested consumer, operator, upgrade, and rollback guidance. |
| G3 — Public v1 | Immutable release, compatibility policy, public access model, governance, support path, migration tooling, audience navigation, and generated reference documentation are operational. |
| G4 — Ecosystem scale | Adoption inventory, health telemetry, profile owners, update automation, documentation feedback, and effectiveness reviews operate continuously. |
| Tranche | Scope | Status |
|---|---|---|
| T1 — Navigable foundation | README audience router, documentation home, first consumer/maintainer/operator journeys, reference index, executable pilot examples, local-link contract, and CI enforcement | Implemented on the current branch |
| T2 — G0 trust foundation | Explicit workflow permissions, no unnecessary install hooks, honest scanner gates, completion status, safe fork behavior, and immutable transitive refs | Implemented; enforced by the G0 contract workflow |
| T3 — Evaluation platform | Evaluation Result schema, scanner adapter contract, evidence aggregation, and first end-to-end Security Profile | Next |
| T4 — Privileged analysis | Bounded AI context/threat-model/review pipeline, validation, privacy, cost, and fork handling | Blocked by T3 and open decisions |
| T5 — Release and governance | Verification corpus, CODEOWNERS, vulnerability process, compatibility policy, release automation, revocation, and generated reference | Blocked by earlier tranches |
| T6 — Ecosystem rollout | Representative pilots, migration tooling, adoption inventory, support, effectiveness measures, and recurring review | Blocked by public-v1 readiness |
Blocked by: Status: resolved Type: Research
Which current defects can be fixed without waiting for product decisions?
The initial review established a no-regret remediation lane:
- give every workflow explicit least privilege and use
persist-credentials: false; - never run package lifecycle scripts merely to inspect dependencies;
- scope OIDC permission to Scorecard only;
- make Trivy gates validate SARIF and emit a non-zero gate conclusion without masking tool failure, and pass every gate input through the umbrella;
- distinguish
complete,incomplete,skipped, anderrorfrom finding severity, including AI refusal and truncated coverage; - replace mutable or missing self-references with an immutable release graph;
- align examples with refs that exist;
- add automated Actionlint, ShellCheck, schema, workflow-security, and documentation-contract checks;
- make the README an audience router and ensure every supported workflow and profile has an executable consumer example.
G0 cannot pass until each item has a regression test.
Blocked by: Status: resolved Type: Grilling
What does "effective security evaluation for all Filecoin projects" mean, and what must the platform never claim?
The platform provides repeatable evidence and policy inputs; it does not certify that a project is secure. Every supported Consumer Project receives a safe Ecosystem Baseline, then selects a Security Profile. Privileged Analyses are additive and must never be required for baseline coverage. A clean result means only that the declared evaluations completed their declared scope and reported no findings at their configured thresholds.
Blocked by: product-contract Status: resolved Type: Decision
Should ecosystem delivery be public reusable workflows alone, a GitHub App that manages installation and credentials, organization-managed deployment, or a staged combination?
Use immutable public reusable workflows for the initial self-service release. Consumers install by full release commit SHA; updates and rollback are reviewed SHA changes. Add a narrowly scoped GitHub App only when measured installation drift, fork publishing, cross-organization health, evidence retention, or onboarding scale cannot be solved cleanly with native Actions.
Blocked by: distribution-model Status: resolved Type: Prototype
How will a consumer pin one version and be certain that every nested workflow, composite action, container, prompt, rule, and third-party action is immutable?
Use a layered immutable graph. A consumer pins one umbrella commit; that commit
pins a leaf-workflow commit, and each leaf pins repository actions/assets,
third-party actions, containers, and tool versions. The layered shape avoids
the impossible requirement for a Git commit to contain its own SHA while
preserving one-reference upgrade and rollback. The recursive
check-release-graph.sh release gate
validates every supported entrypoint and rejects mutable or incomplete graph
edges. Moving tags may be offered as discovery aliases, but are never the
reproducibility boundary. See the
release-integrity contract.
Blocked by: product-contract Status: resolved Type: Prototype
Which evaluations only inspect files, which execute Consumer Project code, and what token, credential, network, runner, and OIDC boundaries apply to each?
The execution-trust contract defines four
release-allowed tiers: a secretless, read-only, non-executing
ecosystem-baseline; a no-checkout privileged-publisher; an explicitly
opted-in privileged-build-analysis with no secrets, writes, OIDC, persisted
credentials, or durable runner; and a no-execution
privileged-external-analysis with one declared provider and bounded data
transfer. legacy-mixed records pre-v1 violations and is never releasable;
control-repository-ci is not a Consumer Project tier.
The machine-readable security/execution-trust.json
classifies every current workflow, example, and action, including its token,
secret, network, runner, cache, and OIDC behavior and target migration. The
threat model records
15 threats and their follow-on controls. CI rejects missing surfaces,
implementation/classification drift, or any release-allowed current tier that
violates its execution and authority contract.
Blocked by: product-contract Status: resolved Type: Grilling
What normalized schema should every evaluation emit, and how do incomplete coverage, tool errors, findings, suppressions, and Merge Gates interact?
Current normalized adapters emit the strict 1.1.0 Evaluation Result with
durable artifact identity and separate fields
for tool/scope identity, completion, coverage and limitations, findings,
suppressions, evidence integrity, timing, and merge policy. complete + zero findings is distinct from incomplete, skipped, and error; unknown fields
are rejected. A Merge Gate conclusion is policy over an observation and never
rewrites completion or finding evidence. Profile-level completeness remains the
aggregator's responsibility. See the
Evaluation Result contract.
Blocked by: product-contract Status: open Type: Research
Which Security Profiles cover the real ecosystem, and which checks are required, optional, or unsupported for each?
Pending. Start with evidence from representative repositories and test five candidates: Go node, Rust/FVM actor, Solidity/FEVM, service application, and infrastructure. Define language detection, monorepo composition, Filecoin invariants, dependency analysis, build requirements, and profile ownership.
Blocked by: distribution-model, execution-trust Status: resolved Type: Prototype
How will fork PRs receive useful evaluation when secrets and write tokens are
unavailable, without introducing a pull_request_target code-execution path?
Run the declared non-executing baseline on ordinary pull_request with an
explicit contents: read caller cap and no forwarded secrets. Do not use
pull_request_target for evaluation. The fixture covers every workflow in the
baseline policy and rejects write tokens, secret forwarding, persisted checkout
credentials, cache, OIDC, self-hosted runners, and Consumer Project execution.
Secret-dependent AI remains an explicit skipped result on fork PRs; any later
privileged publishing or GitHub App path must remain a separate trust tier. See
the fork safety contract.
Blocked by: execution-trust, evaluation-contract, profile-taxonomy Status: resolved Type: Prototype
How should scanners be selected, configured, gated, and normalized so that a profile is portable without hiding tool failures or producing intolerable noise?
Use a thin tool invocation followed by the generic Evaluation Adapter. The
caller supplies immutable tool identity, raw outcome/evidence, coverage, and
finding policy. The adapter validates SARIF, hashes raw evidence, emits v1, and
reserves exit 1 for blocking findings and exit 2 for timeout, cancellation,
crash, or malformed evidence. The Trivy dependency workflow is the first
vertical slice; success, findings, timeout, crash, malformed output, and skip
are fixture-tested. See the adapter contract.
Blocked by: evaluation-contract, execution-trust, fork-pr-model Status: open Type: Prototype
How should context collection, threat modeling, review, validation, prompt-injection handling, large diffs, refusals, privacy, and cost limits work without treating model availability as correctness?
Pending. Recommended pipeline: deterministic context pack, scoped threat model, focused review, independent finding validation, and explicit incomplete status. AI findings remain attributable evidence, not the sole basis for a Filecoin-critical Merge Gate, until measured against a maintained corpus.
Blocked by: evaluation-contract, profile-taxonomy Status: resolved Type: Prototype
What should appear in the check summary, PR, Security tab, artifacts, and machine-readable outputs, and how are results aggregated across nested jobs?
Emit one versioned Evidence Bundle plus a Markdown job summary and stable
Profile Conclusion check. The bundle retains every validated Evaluation
Result, missing ids, completion states, coverage, observed findings and
suppressions, and the selected completeness/finding policy. Duplicate ids and
invalid results fail aggregation. PR comments remain optional; the authoritative
automation surface is the bundle and required conclusion job. See the
Evidence Bundle contract.
Blocked by: product-contract Status: resolved Type: Research
How should documentation be organized, navigated, tested, and maintained so that consumers can adopt and operate the platform while maintainers can extend it without reverse-engineering workflows?
Documentation is a first-class product surface, not a subsection of migration. The durable architecture is recorded in DOCUMENTATION-ARCHITECTURE.md.
The README routes three named audiences: Consumer Engineer, Platform Maintainer, and Rollout Operator. Documentation then uses progressive disclosure: quickstart, profile selection, task guides, concepts, generated reference, and maintainer/operator guidance. Examples are executable contract fixtures, reference tables are generated from metadata, and documentation agreement is required at every release gate.
Blocked by: release-integrity, scanner-runtime, ai-assurance, evidence-interface, documentation-system Status: open Type: Prototype
Which tests and adversarial fixtures are required to demonstrate portability, security, failure semantics, and useful detection for every release?
Pending. Include malicious install hooks, token and OIDC probes, fork PRs, missing secrets, tool outages, malformed SARIF, truncated diffs, prompt injection, planted Filecoin bugs, monorepos, unsupported languages, noisy findings, and upgrade/rollback. Define measurable recall, precision, completion, runtime, and cost thresholds per profile.
Blocked by: distribution-model, release-integrity, evaluation-contract Status: open Type: Grilling
Who owns profiles, approves policy and prompt changes, handles vulnerabilities, publishes releases, responds to broken consumers, and can perform emergency rollback?
Pending. Recommended minimum: CODEOWNERS for workflows, actions, prompts, and profiles; required security review; SECURITY.md; signed immutable releases; compatibility and deprecation policy; automated dependency updates; change log; emergency revocation procedure; and named maintainers for each profile.
Blocked by: profile-taxonomy, evidence-interface, documentation-system, verification-system, governance-model Status: open Type: Prototype
How can a project discover its profile, install the correct pinned workflow, start advisory, tighten gates, customize suppressions, upgrade, and roll back without copying implementation?
Pending. Prototype a profile-selection command or workflow generator that emits a minimal consumer file and compatibility report. Rollout should progress from observe, to critical-only gating, to profile policy, with an escape hatch that is visible and time-bounded.
Blocked by: consumer-migration, distribution-model, governance-model Status: open Type: Research
Which projects form the pilot cohorts, how will adoption be supported across organizations, and which measures prove that the platform is improving security rather than merely running more jobs?
Pending. Use representative low-, medium-, and consensus-critical projects. Track install and upgrade coverage, completion rate, time to triage, confirmed finding rate, false-positive suppression, time to remediation, profile drift, runtime, and cost. G4 requires recurring review with project maintainers and a published coverage matrix.
The executable sequence is maintained in roadmap/state.json
and validated by bash scripts/roadmap.sh validate. At a phase level, work
follows this dependency order:
- Complete the
known-blockersremediation lane and enforce G0. - Build the immutable release and execution foundations.
- Establish the audience router, documentation home, page contracts, and documentation-contract CI before expanding the public surface.
- Implement the Evaluation Result contract and one vertical scanner slice.
- Add Security Profiles and the shared evidence interface.
- Bound and validate Privileged Analyses, including fork PR behavior.
- Establish the verification and governance systems.
- Pilot documented migration across representative projects.
- Publish v1 only after G3 evidence is reviewed; scale only after pilot effectiveness is measured.