Shapin

The CI/CD pipeline sets permissions: read-all at the top level of both ci.yml and release.yml, establishing a read-only default for all jobs. Individual jobs then explicitly declare only the minimum permissions they require (e.g. security-events: write for SARIF upload, contents: write for release creation, id-token: write for cosign signing). Any job without an explicit permissions block inherits the restrictive read-all default.

All releases are tagged with a unique semantic version identifier (e.g. v1.2.0) via Git tags. The release workflow is triggered exclusively on push: tags: "v*", ensuring every GitHub Release is tied to a unique, immutable version tag. The version is also embedded into the binary at build time via -X main.Version=${GITHUB_REF_NAME} ldflags.

Every release automatically generates a changelog via orhun/git-cliff-action using conventional commits, grouped by type (Features, Bug Fixes, Refactoring, CI, etc.) and published as the GitHub Release body. The changelog includes a full diff link to the previous version. This is configured in cliff.toml and executed as part of the release workflow on every tag push.

The build pipeline uses standard Go tooling (go build, go mod) to resolve and ingest dependencies declared in go.mod and go.sum. The Docker image is built via docker/build-push-action. All dependency versions are pinned — Go module checksums are verified by the Go toolchain via go.sum, and GitHub Actions dependencies are pinned to immutable commit SHAs. Dependabot is configured to keep both Go module and Actions dependencies up to date.

Every release asset is signed using two complementary mechanisms:

cosign sign-blob — each binary is signed with a Sigstore bundle (.bundle file) uploaded alongside the release assets, providing keyless signing via the Sigstore transparency log.
actions/attest-build-provenance — SLSA provenance attestations are generated for all build artifacts, cryptographically linking each binary to its source commit and build environment.
checksums.txt — a SHA-256 manifest of all release assets is included in every release, allowing users to verify integrity independently. The Docker image is additionally signed with cosign sign against its digest.

Documented in the Dependencies section of README.md. Dependencies are selected for minimal footprint, declared and pinned in go.mod/go.sum, verified by the Go checksum database on every build, and tracked weekly by Dependabot with automated PRs for updates.

The README.md includes a Build from source section documenting the only prerequisite (Go 1.24+) and the exact build command. The go.mod file specifies the minimum Go version. No additional libraries, frameworks, or SDKs beyond the standard Go toolchain are required.

The list of project members with access to sensitive resources is publicly visible on the GitHub repository at https://github.com/Kirskov/Shapin/graphs/contributors and via the repository's collaborators page. As a single-maintainer project, only the repository owner (Kirskov) has access to sensitive resources such as secrets, release publishing, and package registry credentials.

MAINTAINERS.md at the repository root lists all project members with their roles and responsibilities. It defines the Maintainer role (merge access, release publishing, sensitive resource access) and Contributor role (no privileged access), and identifies the current maintainer.

CONTRIBUTING.md documents requirements for acceptable contributions including: coding standards (gofmt, go vet, no new dependencies without discussion), testing requirements (all new code must have tests, bug fixes need regression tests, full suite must pass), security requirements (no hardcoded credentials, HTTPS-only HTTP calls), and PR submission guidelines (single concern per PR, all CI checks must pass before review).

The DCO file is included in the repository root containing the Developer Certificate of Origin v1.1. The .github/workflows/dco.yml workflow runs on every PR and fails if any commit is missing a Signed-off-by trailer. Instructions for contributors are documented in CONTRIBUTING.md.

Branch protection on main requires all CI status checks (test, codeql, gosec, grype, dco) to pass before a PR can be merged. Manual bypass is restricted by the "Do not allow bypassing the above settings" option, which applies to administrators as well.

The ci.yml workflow runs go test ./... on every push to main and every pull request targeting main. The test suite covers unit and integration tests across all providers and the scanner package. Results are publicly visible in the GitHub Actions tab. Contributors can run the same suite locally with go test ./... — no special environment or secrets required, as all tests use fake HTTP servers via net/http/httptest.

ARCHITECTURE.md documents all actors (User, CLI, Scanner, Providers, Docker Resolver, external APIs), their responsibilities, and the complete data flow from invocation to file rewriting. It includes the provider interface contract, the concurrency model, and a table of all external API interactions. It is linked from the README and will be updated for new providers or breaking changes.

All external software interfaces are documented in ARCHITECTURE.md under "External software interfaces": the CLI (all flags, inputs, outputs, exit codes), the .shapin.json config file schema, the JSON output schema, and the SARIF 2.1.0 output format. The README cross-references these with full usage examples. This documentation is updated alongside any new flags or breaking changes.

SECURITY.md includes a full security assessment covering scope, trust boundaries, and six identified threats (compromised upstream API, directory traversal, token leakage, regex DoS, malicious config file, supply chain compromise of Shapin itself) with impact ratings, mitigations, and residual risk for each. Out-of-scope items are also documented.

SECURITY.md at the repository root defines the coordinated vulnerability disclosure policy: reporters must use private email (not public issues), must include description, reproduction steps, and impact. The project commits to a 7-day response SLA, a fix as soon as possible upon confirmation, and credit in release notes. GitHub also surfaces this file automatically via the "Report a vulnerability" button on the Security tab.

SECURITY.md provides two private reporting channels: GitHub's native private vulnerability reporting (via the Security tab → "Report a vulnerability") and a dedicated private email address. Both are documented at the repository root where GitHub surfaces them automatically to security researchers.

Vulnerability disclosures are published as GitHub Security Advisories at the repository's Security Advisories page, including affected versions, vulnerability description, and upgrade instructions. Fix releases reference the advisory in the changelog. This is documented in SECURITY.md.