Shapin

Every job in ci.yml and release.yml declares only the minimum permissions required for its specific activity:

test: contents: read only
codeql: contents: read + security-events: write (SARIF upload)
gosec: contents: read + security-events: write (SARIF upload)
grype: contents: read + security-events: write (SARIF upload)
dco: contents: read only
release: contents: write + id-token: write + attestations: write (no packages: write — that is scoped exclusively to the docker job)
docker: contents: read + packages: write + id-token: write
A top-level permissions: read-all default ensures any job without an explicit block cannot silently inherit broad permissions.

None of the CI/CD pipelines accept manual workflow_dispatch inputs — all workflows are triggered exclusively by push (tags or main) and pull_request events. There are no ${{ inputs.* }} expressions used anywhere in the pipeline. Consequently there is no collaborator-supplied input that could be injected into shell commands or pipeline logic.

All release assets include the semantic version identifier in their filename (e.g. shapin-v1.2.0-linux-amd64, shapin-v1.2.0-darwin-arm64). The version is also embedded in the binary at build time via -X main.Version. Assets are grouped under the corresponding GitHub Release tag (e.g. v1.2.0), and a checksums.txt SHA-256 manifest ties all assets to the release.

Documented in SECURITY.md. Shapin does not manage secrets — it accepts tokens as ephemeral runtime inputs only. The policy clarifies that the project repository contains no committed secrets, the CI/CD pipeline uses only the ephemeral GitHub-provisioned GITHUB_TOKEN with per-job minimum permissions, and users are responsible for secure handling of any tokens they pass to the tool.

https://github.com/Kirskov/Shapin/blob/main/SECURITY.md

README.md includes a "Verify release integrity" section under Installation documenting three independent verification methods with exact commands and expected output: (1) SHA-256 checksum verification via checksums.txt, (2) cosign bundle signature verification with the expected certificate identity and OIDC issuer, (3) SLSA provenance attestation via gh attestation verify. This is in the README, separate from the release workflow in .github/workflows/release.yml.

The "Verify release integrity" section in README.md documents the expected signer identity for both binary and Docker image verification:

Certificate identity: https://github.com/Kirskov/Shapin/.github/workflows/release.yml@refs/tags/vX.Y.Z
OIDC issuer: https://token.actions.githubusercontent.com
These identify the exact GitHub Actions workflow and tag that must have produced the signature, preventing acceptance of signatures from any other identity. This is stored in the README, separate from the release workflow.

The README.md includes a Support section documenting that only the latest release receives security and bug fixes, no backports are made to older releases, and there is no LTS program. Links to GitHub Issues for bug reports and SECURITY.md for vulnerability disclosure are included.

The Support section in README.md explicitly states: "A release stops receiving security updates as soon as a newer version is published." This makes the end-of-support trigger unambiguous — only the latest release is ever supported for security fixes.

MAINTAINERS.md documents that this is a single-maintainer project and that no collaborator will receive escalated permissions (write access, merge approval, secrets access) without explicit review and approval by the maintainer, including a demonstrated contribution history and verified identity.

An SBOM in SPDX-JSON format (sbom.spdx.json) is auto-generated by Syft (anchore/sbom-action) at release time and published as a release asset alongside the binaries. It is included in checksums.txt and signed with cosign.

Shapin is a single-repository project. There are no subprojects or additional source code repositories compiled into the release. This criterion does not apply.

CONTRIBUTING.md now includes a "Running tests" section documenting how to run the full suite locally (go test ./...), per-package, with verbose output, and fuzz tests. It explains what each package tests, what a passing run looks like, and how CI runs the tests automatically on every push and PR via the test job in ci.yml.

CONTRIBUTING.md defines an explicit testing policy that specifies what constitutes a major change (new provider, new CLI flag, regex/parsing changes, bug fixes, scanner logic changes) and requires tests for each. Bug fixes must include a regression test. PRs that reduce coverage without justification are rejected. The full suite must pass before submission.

This is a single-maintainer project with one contributor. Requiring a non-author approval is not feasible as there are no other collaborators with merge access. All changes are reviewed by the sole maintainer before merging.

SECURITY.md contains a threat model covering six identified threats across all critical attack surfaces: compromised upstream APIs (T1), directory traversal on file I/O (T2), token leakage via output channels (T3), regex DoS on content parsing (T4), malicious config file injection (T5), and supply chain compromise of Shapin itself (T6). Each threat includes impact rating, likelihood, specific mitigations applied in the code, and residual risk. The assessment also defines trust boundaries between the tool, the local filesystem, external APIs, and user-supplied credentials. It is updated with new features and breaking changes.

A vex.json OpenVEX document is maintained in the repository and published as a release asset. It starts with an empty statements array — entries are added when Grype identifies vulnerabilities in the SBOM that are not exploitable in this project's context, with justification and impact statements per the OpenVEX spec.

SECURITY.md defines a SCA remediation policy with severity-based thresholds: Critical must be fixed before the next release, High within the next release cycle, Medium within 90 days or documented as not affected in vex.json. The process covers how Grype findings flow from CI SARIF upload to remediation or VEX justification. License policy requires OSI-approved licenses compatible with MIT.

A sca-gate job runs Grype against the SBOM before every release, failing on Critical or High findings with fail-build: true and severity-cutoff: high. Both the release and docker jobs depend on sca-gate via needs:, so no release can proceed if the gate fails. Non-applicable findings are suppressed via vex.json. The policy and process are documented in SECURITY.md.

The grype job in ci.yml runs on every push to main and every PR. It scans the SBOM with Grype, uploads results as SARIF to GitHub Code Scanning, then runs a second gate step with fail-build: true and severity-cutoff: high. The vex.json is passed to suppress documented non-exploitable findings. Once added as a required status check in branch protection, this blocks any merge with unaddressed Critical or High vulnerabilities.

SECURITY.md defines the SAST remediation policy: Critical/High findings block merges, Medium findings must be resolved within 30 days, false positives are dismissed in GitHub Code Scanning with a documented reason (never silently ignored), and unresolved findings are tracked as GitHub issues. VEX is not used for SAST — it applies only to SCA findings in dependencies.

The codeql and gosec jobs in ci.yml run automatically on every push to main and every pull request. Both upload SARIF to GitHub Code Scanning. Once codeql and gosec are added as required status checks in branch protection (Settings → Branches → required status checks), no PR can be merged if either fails. The gosec gate uses fail-build behaviour via the SARIF upload step, and CodeQL fails the job on any finding above the configured threshold.