api

Simple Container is a rolling-release product with calver tags YYYY.M.X; we do not maintain older minor branches. The upgrade path is to re-run the install bootstrap: curl -s "https://dist.simple-container.com/sc.sh" | bash (replaces the local sc binary; signature-verified via cosign). Breaking changes are called out in the per-release notes at https://github.com/simple-container-com/api/releases.

GitHub Issues: https://github.com/simple-container-com/api/issues.

No externally-reported vulnerabilities have been resolved in the last 12 months. Should one be published, credit will be given in the corresponding GitHub Security Advisory at https://github.com/simple-container-com/api/security/advisories per the process documented in docs/SECURITY.md.

Documented in docs/SECURITY.md — reporting channels (GitHub Security Advisory preferred; security@ / direct email fallback), triage SLA, fix-and-disclose flow, advisory publication, and credit policy.

URL: https://github.com/simple-container-com/api/blob/main/docs/SECURITY.md

Primary language is Go; we follow the standard Go style guide (gofmt, go vet, staticcheck, Effective Go) as enforced by golangci-lint. Configuration is at .golangci.yml. Contribution rules in docs/CONTRIBUTING.md require PRs to pass these checks before merge.

URLs: https://go.dev/doc/effective_go and https://github.com/simple-container-com/api/blob/main/.golangci.yml

gofmt, go vet, and golangci-lint run as required CI checks in .github/workflows/build-staging.yml on every PR, and branch protection on main blocks merge until they pass.

The product is built with the Go toolchain, which does not consume CC / CFLAGS / CXX / CXXFLAGS / LDFLAGS in the C-compiler sense. Build flags are passed via the Go toolchain's own conventions (-ldflags, -trimpath, GOFLAGS) and are configured in the welder build descriptor.

The Go toolchain's release builds intentionally strip path information via -trimpath to produce reproducible binaries; symbol tables are retained by default (we do not pass -ldflags='-s -w' in release builds). There is no separate "install" step that would strip debug info.

Go modules drive the build; there is no recursive make over subdirectories. go build resolves the full dependency graph from go.mod + go.sum in a single invocation.

Go build reproducibility: go.sum hashes all transitive deps, the build uses -trimpath to strip filesystem prefixes, the toolchain version is pinned in go.mod's go directive, base images are SHA-digest-pinned. Released binaries carry SLSA Build L3 provenance (via attest-build-provenance@v4) and a CycloneDX SBOM, so a verifier can rebuild from the recorded inputs.

Install via the signature-verified bootstrap: curl -s "https://dist.simple-container.com/sc.sh" | bash which fetches the platform tarball, verifies the cosign signature against the maintainer's identity, and places the sc binary on $PATH. Uninstall is rm $(which sc) — a single static binary. The same bootstrap on a newer release performs an upgrade.

sc.sh installs to /usr/local/bin/sc by default and honors the SC_INSTALL_DIR environment variable for non-standard destinations. The install path is logged at the end of the bootstrap run.

docs/CONTRIBUTING.md [osps_do_07_01]

Multiple machine-readable manifests, all in the public repo:
Go runtime deps: go.mod + go.sum (cryptographic hashes for every direct and transitive module)
Python docs deps: docs/requirements.in (sources) + docs/requirements.txt (pip-compile output with --generate-hashes)
Container base images: Dockerfiles pin by SHA digest
GitHub Actions: SHA-pinned in every workflow under .github/workflows/
Per-release CycloneDX SBOM: attached as .sbom.cdx.json sidecar to every Release artifact (the canonical machine-readable inventory of what shipped)
Policy: https://github.com/simple-container-com/api/blob/main/docs/DEPENDENCIES.md

Every change is automatically evaluated against the documented SCA policy in docs/DEPENDENCIES.md ("Pre-release SCA gate" + "Suppressing a finding") [osps_vm_05_03]

[osps_qa_02_01]

Go deprecation warnings surface as staticcheck SA1019 findings in CI (golangci-lint config at .golangci.yml). Recent example: fix(deps): migrate aws-sdk-go v1 → v2 (commit on main, 2026-05-18) replaced the legacy AWS SDK with its non-deprecated successor across the codebase as part of vulnerability remediation. Deprecated GitHub Actions are surfaced by Dependabot and SHA-pinned only after confirming a non-deprecated alternative.

[test_continuous_integration] [osps_qa_06_01]

Bug-fix PRs that touch a code path with existing unit tests extend or add cases to that suite; fixes to the security-critical HMAC parse path are covered by the Go-native fuzz target at pkg/security/cache_fuzz_test.go which runs in CI on every PR (.github/workflows/fuzz.yml). Pure CI / packaging / dependency-bump fixes do not have a test-suite equivalent and are validated by the rebuild + reachability scan (govulncheck reachability-aware gate per .github/workflows/govulncheck.yml) instead.

go test

[tests_documented_added] [osps_qa_06_03]

docs/CONTRIBUTING.md requires PRs touching production code paths to include unit tests covering the new behaviour, with stricter standards for security-sensitive paths (pkg/security/, push.yaml, sc.sh, anything in the SLSA / cosign / Sigstore chain). PRs lacking tests are blocked at maintainer review.

URL: https://github.com/simple-container-com/api/blob/main/docs/CONTRIBUTING.md

golangci-lint runs in CI with a strict ruleset (gofmt, goimports, govet, staticcheck, errcheck, ineffassign, unused, gosec) and any warning fails the build — there is no "warning, don't fail" tier. Configuration is at .golangci.yml. CI invocation is in .github/workflows/build-staging.yml.

Documented in docs/SECURITY.md (STRIDE threat model + V1-V5 attack vectors) and docs/ARCHITECTURE.md (trust-boundary diagram). Concrete applications:

Minimise attack surface: single static binary; no plugins, no eval, no shell-out paths from untrusted input.
Defense in depth: install bootstrap layers SHA256 → cosign keyless signature → SLSA Build L3 provenance verification before executing the binary.
Fail-safe defaults: signature-verification failure aborts install; no silent downgrade.
Least privilege: every CI workflow declares permissions: explicitly and starts from read-all, upgrading per-job; secrets injected via env, never embedded.
Separation of trust boundaries: each external edge (dist.simple-container.com, GitHub, cloud APIs) is explicit in the architecture diagram with the controls applied to it.

Default crypto primitives in the codebase:

HMAC: HMAC-SHA256 (pkg/security/cache.go)
Public-key encryption: RSA-OAEP-SHA256 and ed25519+ChaCha20-Poly1305 (pkg/api/secrets/ciphers/encryption.go)
Key derivation: HKDF-SHA256
Artifact signing: Sigstore/cosign (ECDSA P-256 + SHA-256 by default)
TLS: Go stdlib defaults (TLS 1.3 preferred, 1.2 floor)
No SHA-1, MD5, RC4, single-DES, or CBC-without-MAC paths in any production code.

The codebase exercises multiple modern primitives concurrently: RSA-OAEP-SHA256 and ed25519+ChaCha20-Poly1305 for secrets encryption (the user picks which), HMAC-SHA256 for cache MAC (switchable to SHA-384/512 via Go stdlib hash.Hash interface — one-line change), Sigstore artifact signing (algorithm controlled by Fulcio, currently ECDSA P-256). All Go stdlib primitives are interchangeable through the hash.Hash / cipher.AEAD interfaces.

SC never embeds credentials in code. Cloud credentials live in user-managed secret stores referenced from cfg.yaml (env vars, AWS Secrets Manager paths, file paths). Rotation = update the secret store; no rebuild. The HMAC cache key is auto-generated to .hmac.key (mode 0600) on first use and can be regenerated by deleting the file. CI tokens for the project itself live as GitHub Actions secrets, rotable via the GitHub admin UI.

All outbound network traffic uses HTTPS (TLS 1.2+) or SSH (Sigstore Fulcio + Rekor, GitHub API, AWS/GCP/Azure SDKs, dist.simple-container.com). Go stdlib net/http.Transport defaults reject TLS 1.0/1.1. No FTP / telnet / plaintext HTTP code paths.

Go stdlib crypto/tls defaults to TLS 1.3 with TLS 1.2 floor. The codebase does not override MinVersion to any value below tls.VersionTLS12 in any production code path.

Go stdlib http.Transport verifies certificates by default. grep -rn "InsecureSkipVerify" --include="*.go" returns zero hits in production code; the only matches are in a Semgrep test fixture (actions/semgrep-scan/tests/go_cases.go) used to validate our own SAST rule that flags this anti-pattern.

Same Go stdlib behaviour — the TLS handshake (including certificate validation) completes before any application data, including request headers or secure cookies, is transmitted. We do not implement a custom HTTP client that bypasses this ordering.

SECURITY.md cosign-verify-blob block — the --certificate-identity-regexp is anchored to https://github.com/simple-container-com/api/.github/workflows/push.yaml@refs/heads/main, which IS the authoring identity (the production publish workflow). --certificate-oidc-issuer pins to GitHub Actions OIDC. The Sigstore Rekor entry records this identity in a public transparency log. [osps_do_03_02]

Every release tag is materialised in a GitHub Release with cosign keyless signatures attached as .sigstore.json + .cosign-bundle sidecars per platform binary, plus SHA256 checksum and CycloneDX SBOM. The Sigstore transparency-log entry (Rekor) is the verifiable cryptographic anchor — the git tag itself doesn't need a GPG signature because the artifact-level Sigstore signature is the stronger guarantee.

URL: https://github.com/simple-container-com/api/releases

Untrusted inputs:

CLI arguments: validated by cobra command framework with explicit type / choice constraints.
YAML config (cfg.yaml, secret configs): parsed strict-mode (unknown keys rejected).
Cache entries: HMAC-verified before deserialization (pkg/security/cache.go); the parse path is fuzz-tested (pkg/security/cache_fuzz_test.go).
Cloud API responses: validated by the official AWS/GCP/Azure/Kubernetes SDKs.
No raw eval, no shell-injection sinks, no string-concat SQL.

Hardening of the produced artifacts. (1) Build: release binaries use -trimpath + CGO_ENABLED=0 (static, reproducible - https://github.com/simple-container-com/api/blob/main/docs/REPRODUCIBLE-BUILD.md); container images use multi-stage Dockerfiles on SHA-digest-pinned base images (e.g. github-actions.Dockerfile and caddy.Dockerfile pin alpine:3.23@sha256:... and caddy:2.11.4@sha256:...). (2) CI: every workflow declares least-privilege permissions and pins third-party actions to full commit SHAs; release signing uses GitHub OIDC keyless Sigstore/cosign instead of long-lived secrets - https://github.com/simple-container-com/api/tree/main/.github/workflows. (3) Distribution: the install bootstrap sc.sh, when cosign is on PATH, verifies the keyless Sigstore signature against the maintainer identity and aborts on a verification/fetch failure (it warns and continues only when cosign is absent, to avoid hard-blocking fresh installs) - https://github.com/simple-container-com/api/blob/main/sc.sh.

The assurance case is the combined contents of:

Threat model: docs/SECURITY.md (STRIDE table + attack vectors V1-V5 + responsible-disclosure channels)
Trust boundaries: docs/ARCHITECTURE.md (mermaid trust-boundary diagram + actors + data flows)
Secure design principles argument: docs/SECURITY.md defence-in-depth + least-privilege + fail-safe-defaults sections
Common implementation weaknesses countered: CodeQL (Go), Semgrep custom rules, golangci-lint with gosec, govulncheck reachability-aware gate, OpenVEX-only suppressions per docs/DEPENDENCIES.md
URL (entry point with cross-refs to all the above): https://github.com/simple-container-com/api/blob/main/docs/SECURITY.md

Four FLOSS analyzers run on every PR; each blocks merge on findings:

CodeQL (Go) — .github/workflows/codeql.yml
Semgrep with custom org rules — .github/workflows/semgrep.yml
gosec + staticcheck via golangci-lint — .golangci.yml
govulncheck (reachability-aware) — .github/workflows/govulncheck.yml
Suppressions go through the OpenVEX not_affected channel (vex/openvex.json) only — .trivyignore / # nosemgrep / // nolint: are banned by docs/DEPENDENCIES.md policy.

The software is written entirely in Go (memory-safe). CGO_ENABLED=0 for release builds — no C/C++ dependencies; binaries are fully static. The criterion does not apply.