From 7c021f2fbfe65048bbf864e80b5d963045ee440d Mon Sep 17 00:00:00 2001 From: w1ck3ds0d4 Date: Thu, 24 Sep 2026 21:40:58 +0200 Subject: [PATCH] (docs) standard doc set and roadmap --- CLAUDE.md | 43 +++++++++++++++ ROADMAP.md | 155 ++++++++++++++++++++++------------------------------- 2 files changed, 106 insertions(+), 92 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6d22629 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,43 @@ +# SecureCheck + +A reusable GitHub Actions security pipeline: gitleaks (secrets), Semgrep (SAST), +Trivy (CVE + IaC), SARIF upload to code scanning, severity gating, and an +optional Claude Sonnet PR review. Consumer repos call it from their own +`security.yml`. Free and public, on the path to a Marketplace v1.0.0 listing. + +## Commands + +```bash +npm install +npm test # node --test "scripts/**/*.test.mjs" +``` + +There is no build or lint step; the composite action's steps live in +`action.yml` and run directly in the consumer's job. + +## Layout + +| Path | What it is | +| --- | --- | +| `action.yml` | The composite action: inputs, secrets, and every step | +| `scripts/` | Node scripts the action shells out to (embed, gate, notify, Claude review) | +| `scripts/*.test.mjs` | Tests beside the script they cover | +| `examples/` | Copy-paste consumer workflow templates | +| `.github/workflows/` | This repo's own CI, scan, and reusable security workflow | +| `ROADMAP.md` | v1.0.0 acceptance checklist and milestones | + +## Conventions + +- Commit format: `(type) lowercase summary` - `feat`, `fix`, `chore`, `docs`, + `refactor`, `revert`. No trailing period, no body unless needed. +- ASCII hyphens only. No em dashes or en dashes anywhere. +- Feature branch per change set, one PR per branch, squash-merge. +- Third-party actions in `action.yml` and the workflows are pinned to a commit + SHA with the version as a trailing comment, not a floating tag. +- A new script under `scripts/` gets a `*.test.mjs` beside it. + +## Do not read + +- `node_modules/` (not committed, but ignore if present locally) +- `package-lock.json` +- Any scanner output under a runner's temp directory (not part of the repo) diff --git a/ROADMAP.md b/ROADMAP.md index 3db6f9b..80d38b7 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,93 +1,64 @@ -# SecureCheck v1 Roadmap - -## What v1 is - -A reusable GitHub Actions workflow that consumer repos call from their own -`security.yml`. Runs gitleaks (secrets in history), Semgrep (SAST with -`auto` ruleset), Trivy (CVE + IaC), and an optional Claude Sonnet code review -on PRs. Posts a severity-coloured Discord embed and uploads raw scanner -output as artifacts. - -## Current state - -Workflow is in production and consumed across several private repositories. -Gitleaks 8.24.3, Semgrep `auto`, -Trivy, Claude Sonnet step (gated on `ANTHROPIC_API_KEY`). Discord severity -coding (green clean / yellow findings / orange many findings / red gitleaks -hit). Per-scanner JSON artifacts retained 14 days. PR heartbeat posts even -when green. Silent on clean pushes to main. - -## v1 acceptance criteria - -- [x] gitleaks scanner with current pinned version -- [x] Semgrep `auto` ruleset -- [x] Trivy CVE + IaC scan -- [x] Optional Claude Sonnet PR review -- [x] Discord severity coding -- [x] Per-scanner JSON artifact upload (14-day retention) -- [x] PR heartbeat posts on green PRs -- [x] Silent on clean main pushes +# Roadmap + +**Status:** release: path to v1.0.0. **Last reviewed:** 2026-09-24. + +SecureCheck is a reusable GitHub Actions security pipeline (gitleaks, Semgrep, +Trivy, optional Claude PR review) that consumer repos call from their own +`security.yml`. All the scanning and gating logic already runs in production +across several private repos. "Done" for v1.0.0 means the remaining +documentation and pinning gates are closed and a tagged, Marketplace-listed +release exists. + +> How this file is used: Claude Project threads build the first unticked item +> under **Now**, one item per branch and pull request, and tick it in that +> same PR as `- [x] ... (#PR)`. Daniel owns the order and the lists; threads +> never add to Now, Next or Later themselves, they propose under **Ideas**. + +## Now (path to v1.0.0) +- [ ] **Document the input matrix**: every `workflow_call`/action input, its + default, and what it does, in README. Done when: README has a table + covering every input in `action.yml`. +- [ ] **Document the secret matrix**: every secret the action expects + (`DISCORD_WEBHOOK_URL`, `ANTHROPIC_API_KEY`, `GITHUB_TOKEN` scopes) and + whether it is required. Done when: README lists each one with required/optional. +- [ ] **Consumer install template**: add `examples/security.yml` (minimal) and + `examples/security-with-claude.yml` (Claude variant), linked from README. + Done when: both files exist under `examples/` and are linked from README. +- [ ] **Version pinning policy**: document in README/CHANGELOG that consumers + pin `@v1` for stable or `@main` for latest, and the `v1.0.0`/`v1.0.1`/`v1.1.0` + tag scheme. Done when: the policy is written down and CHANGELOG has an + Unreleased section following it. +- [ ] **Consumer smoke fixture**: a `tests/consumer-fixture/` with intentional + leaks/SAST hits/CVEs, run in this repo's own CI. Done when: `ci.yml` runs the + action against the fixture and the run is green. +- [ ] **Tag v1.0.0 and list on Marketplace (Daniel)**: cut the tag, publish a + GitHub release, and complete the Marketplace listing. Done when: `v1.0.0` is + tagged, a GitHub release exists, and the Marketplace listing is live. + +## Next +- [ ] **Update consumer repos to pin `@v1.0.0`**: move private consumers off + branch/SHA references onto the tag. Done when: at least 5 consumer repos + reference `@v1.0.0`. +- [ ] **Severity threshold gating**: add a "fail PR if critical findings" mode + on top of the existing `fail-on` input. Done when: a new input controls this + and is documented. + +## Later +- Additional scanners (osv-scanner, kubesec for k8s manifests) +- Slack/Teams channel posters alongside Discord +- Markdown PR comment with findings, alongside the Discord embed +- Re-run knob to refresh a stale Trivy DB without bumping the workflow version + +## Ideas +(empty to start; threads add proposals here) + +## Done +- [x] gitleaks, Semgrep `auto`, and Trivy CVE/IaC scanning wired into the + composite action +- [x] SARIF upload to GitHub code scanning (`upload-sarif` input) +- [x] Configurable severity gate (`fail-on` input) +- [x] Optional Claude Sonnet PR review, gated on `ANTHROPIC_API_KEY` +- [x] Discord severity-coded embed (green/yellow/orange/red) plus PR heartbeat +- [x] Per-scanner JSON artifacts retained 14 days - [x] Em-dash style check gate -- [x] Gitleaks fails on intro -- [ ] Documented input matrix (every input the workflow accepts + default + meaning) -- [ ] Documented secret matrix (every secret the workflow expects + where it's used) -- [ ] Consumer install template (`.github/workflows/security.yml` example with placeholders) -- [ ] Version pinning policy + changelog -- [ ] Smoke test consumer: a `tests/consumer-fixture` repo or scratch run validating each scanner produces output as expected -- [ ] Tag `v1.0.0` once the input + secret matrices and consumer template are in tree - -## Milestones to v1 - -### M1. Input + secret matrix (S) - -- [ ] Document every `workflow_call` input in README (name, type, default, meaning) -- [ ] Document every secret expected (`DISCORD_WEBHOOK_URL`, `ANTHROPIC_API_KEY`, `GITHUB_TOKEN` scopes) -- [ ] Note which inputs / secrets are optional vs required - -**Acceptance:** a consumer can wire the workflow without reading the YAML. - -### M2. Consumer install template (S) - -- [ ] Add `examples/security.yml` showing the minimal caller -- [ ] Add `examples/security-with-claude.yml` showing the Claude variant -- [ ] Link both from README - -**Acceptance:** copy-paste from `examples/` gets a new consumer to green in 5 minutes. - -### M3. Versioning + changelog (S) - -- [ ] Add CHANGELOG.md -- [ ] Document version pinning policy: consumers reference `@v1` for stable, `@main` for latest -- [ ] Tag policy: `v1.0.0`, `v1.0.1` for patches, `v1.1.0` for additive features, `v2.0.0` for breaking changes - -**Acceptance:** consumers know exactly which tag to pin and what they get. - -### M4. Smoke fixture (S/M) - -- [ ] A `tests/consumer-fixture/` scratch dir with intentional leaks / SAST hits / Trivy CVEs -- [ ] CI on the SecureCheck repo runs the workflow against the fixture and asserts expected severities -- [ ] Document how to run it locally with `act` (or note that it requires GitHub Actions) - -**Acceptance:** changes to the workflow can't ship without proving all scanners still fire. - -### M5. Tag v1.0.0 (S) - -- [ ] README polish -- [ ] Tag `v1.0.0` -- [ ] Update consumer repos one-by-one to pin `@v1.0.0` - -**Acceptance:** at least 5 consumer repos pin the v1.0.0 tag. - -## Beyond v1 (post-1.0 polish) - -- Additional scanners (e.g., `osv-scanner`, `kubesec` for k8s manifests) -- Slack / Teams channel posters alongside Discord -- Markdown PR comment with findings (alongside Discord embed) -- Severity threshold gating ("fail PR if critical findings") -- Re-run knob to refresh stale Trivy DB without bumping the workflow version - -## Out of scope for v1 - -- Hosting a SaaS edition (it's a GitHub-native workflow) -- Replacing any of the underlying scanners (they're best-of-class for the niche) -- Container image building / publishing (consumer's responsibility) +- [x] Third-party actions pinned to commit SHAs (2026-06-13)