A reusable, security-first engineering platform — not a toy, not a SaaS: a repository of real, reproducible CI/CD, supply-chain, and application-architecture practices you can inspect, run, and adopt.
Quick start · Security · Status · Roadmap · Contributing · Report a vulnerability
ForgeStack is a working reference implementation of the practices an enterprise engineering team actually audits: branch-protected CI/CD, SAST/SCA/secret scanning on every change, signed and validated SBOMs, documented vulnerability exceptions, and a modular, language- agnostic service contract — demonstrated with real Go and Python reference services, not diagrams. Everything below is either verified (built, run, and tested in this repository) or explicitly marked not yet verified / roadmap. Nothing here claims a certification, a security guarantee, or production deployment that hasn't actually happened.
It is also, honestly, a learning repository (see docs/ROADMAP.md's full
25-module curriculum) — the two goals aren't in tension: the security/CI tooling below is the
same tooling a real product team would run, taught by actually running it.
Every change to develop/staging/main runs through branch-protection rulesets (zero
bypass actors, 8 required status checks) and:
| Control | Tooling | Status |
|---|---|---|
| SAST | CodeQL (Go, Python, JavaScript/TypeScript) | Verified — 3 languages, see .github/workflows/codeql.yml |
| Dependency vulnerabilities (Go) | govulncheck (reachability-aware) |
Verified — zero findings as of this writing |
| Dependency vulnerabilities (Python) | pip-audit |
Verified — zero findings as of this writing |
| Dependency vulnerabilities (JS, build tooling) | npm audit against a reviewed, dated baseline |
Verified — 26 pre-existing, documented, dev-tooling-only findings; no known safe fix yet |
| Secret scanning | gitleaks on every PR (that PR's commits); a deeper full-history scan is run locally/on demand, not automatically on every PR |
Verified — zero leaks on every PR run to date; a full-history local scan also found zero |
| Container image scanning | Trivy (image + Dockerfile config) | Verified — Go image: 0 findings; Python image: 98 OS-package findings, all with no available upstream fix, tracked exception |
| SBOM generation | CycloneDX (Go module + both container images), validated against NTIA/CISA minimum elements | Verified locally — see cmd/sbomcheck |
| VEX vulnerability assessment | OpenVEX-shaped statements, evidence + reviewer + reassessment date required | Verified locally — see cmd/secreport |
| Artifact signing & provenance | Sigstore keyless signing, GitHub-native build attestation (SLSA-aligned) | Signing/verify mechanics proven locally; the live keyless/OIDC flow has not yet run in GitHub Actions |
| Supply-chain hardening | Digest-pinned base images, zero Linux capabilities, read-only filesystems, non-root execution | Verified — both services tested with cap_drop: [ALL] |
Nothing above claims zero vulnerabilities, a passed audit, or a compliance certification.
See docs/security/VULNERABILITY-LIFECYCLE.md
for the full process and every tracked exception's exact evidence, owner, and review date,
and docs/architecture/SUPPLY-CHAIN-SECURITY.md
for trust boundaries, the compliance-evidence mapping (explicitly labeled evidence, not
certification), and this session's own honestly-stated limitations.
govulncheck ./... # Go, reachability-aware
cd apps/python-api && pip-audit --requirement requirements-lock.txt
cd website && npm audit --json | python3 ../scripts/check-npm-audit-baseline.py /dev/stdin .security/npm-audit-baseline.json
go run ./cmd/secreport -govulncheck ... -pip-audit ... -json-out secreport.json -md-out secreport.md -vex-out vex.json
go run ./cmd/sbomcheck validate path/to/sbom.cdx.jsonFull commands, including the container/secret scans, are in
docs/security/VULNERABILITY-LIFECYCLE.md.
Two independent reference services, each idiomatic for its own language rather than forced
into a shared shape, both implementing the same documented cross-language contract
(docs/platform/CONTRACTS.md): health/readiness, structured JSON logging, request-correlation
IDs, and a consistent error-response shape.
- Go (
cmd/api,internal/modules/posts,internal/platform) — go-kit layered, stdlib-first, in-memory storage, full unit/integration/concurrency test coverage. - Python (
apps/python-api) — FastAPI, typed config viapydantic-settings, the same contract implemented independently (not via a shared library — seedocs/platform/CONTRACTS.mdfor why). - Adding a third language or service doesn't require touching the first two — see
docs/platform/CONTRACTS.md's extension guidance.
scripts/new-service.sh go /path/to/new-project --name my-service --port 9090 \
--module github.com/you/my-service --validate
scripts/new-service.sh python /path/to/new-project --name my-service --port 9090 --validateGenerates a complete, standalone project (health/readiness, correlation IDs, structured
logging, a hardened Dockerfile, self-contained CI) with no dependency on ForgeStack's own
repository — verified by actually generating, building, testing, and running example
projects from both templates. --validate builds and tests the generated project in
place before you touch it. See docs/VERSIONING.md for template
versioning, compatibility, and upgrade policy, and
docs/RELEASES.md for how ForgeStack's own trusted-release pipeline
reuses the same SBOM/signing tooling — live-exercised on main, with a verified
successful release (v0.1.2, after two earlier real failures were diagnosed and fixed;
see docs/RELEASES.md for the full history of all three attempts).
No AWS account, no cloud bill, no signup.
# Go reference service
go test ./...
go run ./cmd/api
curl -i http://localhost:8080/healthz
# Python reference service (in a second terminal)
cd apps/python-api && pip install -r requirements-lock.txt
uvicorn app.main:app --port 8081
curl -i http://localhost:8081/healthz
# both, containerized, hardened (non-root, read-only, zero capabilities)
docker compose up --build -d api python-api
curl -i http://localhost:8080/healthz && curl -i http://localhost:8081/healthz
docker compose downmake test, make race, make vet, make lint, make smoke also work for the Go service.
See docs/COMMANDS.md for every command this repository uses, explained.
| Phase | Scope | Status |
|---|---|---|
| F1 | Branch-protected gitflow (feature/* → develop → staging → main), CI baseline |
Implemented, live on GitHub (see docs/adr/0002-gitflow-branching-strategy.md) |
| F2 | Documentation-as-code (this Docusaurus site, generated references, link/diagram validation) | Implemented, live on GitHub Pages (docs/adr/0003-documentation-as-code.md) |
| F3 | Go + Python application foundation, shared service contract | Implemented, live on main (docs/adr/0004-f3-application-foundation.md) |
| F4 | Security & supply-chain foundation (this document's table above) | Implemented and live on main, including a verified live run of keyless signing + GitHub-native attestation (docs/adr/0005-f4-security-supply-chain.md) |
| F5 | Reusable Go/Python templates, SemVer policy, trusted-release pipeline | Implemented and live on main, including a verified successful live release (v0.1.2) — signed, attested, SBOM'd, and published as a GitHub Release. Two earlier live attempts (v0.1.0, v0.1.1) failed and were fixed first; see docs/RELEASES.md for the full history (docs/adr/0006-f5-templates-releases.md) |
| F6–F20 | Future phases (not yet scoped in detail; see docs/ROADMAP.md) |
Not started |
| Audit & Trust module | Evidence-collection expansion (infra/access/incident/backup), later a customer-facing Trust Center | Roadmap only, unscheduled against a specific F-number — see docs/ROADMAP.md's "Audit & Trust" module |
ForgeStack never self-issues a certification. If an independent audit is ever obtained for a product built on ForgeStack, it is tracked as an external fact (issuing authority, verified scope, issuance/expiry dates) — never granted by this repository's own tooling.
cmd/api,internal/modules/posts,internal/platform: Go reference service and testsapps/python-api: Python (FastAPI) reference servicecmd/secreport,internal/secreport: security report + VEX document generatorcmd/sbomcheck,internal/sbomcheck: SBOM minimum-elements validator/augmentercmd/semvercheck,internal/semver: SemVer validation and compatibility classificationtemplates/go-service,templates/python-service: reusable project templates, each with its own nestedgo.mod/pyproject.tomlso they're never part of this repository's own buildscripts/new-service.sh: generates a new, standalone project from a templatecmd/docgen: generatesdocs/generated/*directly from source; CI fails if these driftcompose.yaml,Dockerfile,apps/python-api/Dockerfile: hardened local containers (digest-pinned, non-root, read-only, zero Linux capabilities)infrastructure/terraform/aws-s3-sandbox: safe-by-default opt-in Terraform examplewebsite/: Docusaurus site that publishesdocs/to GitHub Pages.github/workflows: CI, lint, SAST, secret/container/IaC scanning, SBOM generation, signing/attestation, weekly deep security rescan, docs-check, Pages deploy, and a tag-gated trusted-release pipeline (release.yml, live-exercised — seedocs/RELEASES.mdfor thev0.1.0/v0.1.1/v0.1.2history) — no cloud auto-deploy anywheredocs/security/: vulnerability lifecycle, findings registerdocs/architecture/: trust boundaries, supply-chain security, application architecturedocs/adr/: every accepted architecture decision, with the tradeoffs considereddocs/ROADMAP.md: the full learning curriculum and the Audit & Trust module plan
python3 scripts/review_guard.py --ci
make test && make race && make vet && make lintEvery PR to develop/staging/main runs the required checks (go-quality,
security-baseline, analyze, gitleaks, trivy-image, validate, docs, check) plus
Python quality/security gates, hadolint, and an npm-audit baseline check. See
docs/AUTOMATED-CODE-REVIEW.md for exactly which checks are
required vs. advisory.
docs/ is published as a browsable Docusaurus site via GitHub Pages — nothing is duplicated,
so the site can't drift from the repository. Build it locally:
cd website
npm ci
npm run buildNo AWS account needed for anything above. The Terraform sample in
infrastructure/terraform/aws-s3-sandbox creates zero resources unless explicitly opted in;
GitHub workflows never run terraform apply/destroy. See docs/COST-SAFETY.md.
Contributions are welcome — read the contribution guide and
code of conduct. To report a vulnerability, use the private process in
SECURITY.md (GitHub Security Advisories) — not a public issue.
ForgeStack is licensed under the Apache License 2.0.