Update Development - #4
Conversation
# Building a SLSA3‑Compliant Development Workflow: A Practical Guide
You’ve asked to “Create development” – and that’s exactly what we’ll do. Below is a **step‑by‑step blueprint** for setting up a development environment and process that meets SLSA Level 3 requirements while remaining practical for everyday coding. This guide builds on everything we’ve discussed and gives you a concrete path forward.
## 🎯 Goal
Establish a development pipeline where every artifact (commits, builds, releases) carries verifiable proof of its origin and integrity, satisfying SLSA Build Level 3 and setting the foundation for higher levels.
---
## 📦 Phase 1: Repository Foundation
### 1.1 Enable Signed Commits
- **What**: Require that every commit is signed with a GPG, SSH, or S/MIME key.
- **How**:
- Generate a signing key (GPG: `gpg --full-generate-key`).
- Add the public key to your GitHub/GitLab account.
- Configure Git locally:
```bash
git config --global user.signingkey <key-id>
git config --global commit.gpgsign true
```
- **Why**: Establishes a chain of custody from developer to code, which is part of the source integrity expected by SLSA.
### 1.2 Branch Protection Rules
- **Require signed commits** on all protected branches (main, release/*).
- **Require pull request reviews** before merging.
- **Optionally require** that all status checks pass (including any SLSA verification steps you add later).
### 1.3 Dependency Locking
- Use lock files (`go.sum`, `package-lock.json`, `Cargo.lock`, etc.) to pin dependency versions.
- Commit these lock files to the repository.
---
## 🛠️ Phase 2: Local Developer Environment
### 2.1 Containerized Development Environment
- Provide a `Dockerfile` or Dev Container configuration that mirrors your CI build environment.
- Example `.devcontainer/devcontainer.json`:
```json
{
"name": "MyApp Dev",
"build": { "dockerfile": "Dockerfile" },
"features": {
"ghcr.io/devcontainers/features/common-utils:2": {}
}
}
```
- This ensures builds are reproducible and eliminates “works on my machine” discrepancies.
### 2.2 Pre‑commit Hooks for Security
- Use [pre-commit](https://pre-commit.com/) to run:
- **Dependency hash verification** (e.g., check `go.sum` against a known good state).
- **Linting and static analysis**.
- **Secret scanning** (e.g., `detect-secrets` or `truffleHog`).
- Example `.pre-commit-config.yaml`:
```yaml
repos:
- repo: local
hooks:
- id: verify-deps
name: Verify dependencies
entry: scripts/verify-deps.sh
language: script
files: '.*\.(mod|sum|lock)$'
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.4.0
hooks:
- id: detect-aws-credentials
- id: detect-private-key
```
### 2.3 Local Build with Provenance (Optional but Recommended)
- For testing, you can generate lightweight attestations using [in-toto](https://in-toto.io/).
- Example wrapper script `local-build.sh`:
```bash
#!/bin/bash
in-toto-run --step-name local-build --products myapp --key mykey -- ./build.sh
```
- This creates a link file that you can keep locally for debugging.
---
## 🔁 Phase 3: Continuous Integration (CI) Pipeline
### 3.1 Reusable Build Workflow
Create a reusable workflow (`.github/workflows/build.yml`) that encapsulates your build steps and outputs artifact hashes.
```yaml
name: Reusable Build
on:
workflow_call:
outputs:
base64-subjects:
description: "Base64-encoded subjects (artifacts with digests)"
value: ${{ jobs.build.outputs.base64-subjects }}
jobs:
build:
runs-on: ubuntu-latest
outputs:
base64-subjects: ${{ steps.hashes.outputs.base64_subjects }}
steps:
- uses: actions/checkout@v4
- run: make build
- run: mkdir -p artifacts && cp bin/* artifacts/
- id: hashes
run: |
cd artifacts
subjects="[]"
for file in *; do
hash=$(sha256sum "$file" | cut -d' ' -f1)
subjects=$(jq -c --arg name "$file" --arg hash "sha256:$hash" \
'. += [{"name": $name, "digest": $hash}]' <<< "$subjects")
done
echo "base64_subjects=$(echo -n "$subjects" | base64 -w0)" >> $GITHUB_OUTPUT
- uses: actions/upload-artifact@v4
with:
name: build-artifacts-${{ github.run_id }}
path: artifacts/
```
### 3.2 Main CI Workflow (PRs and Merges)
Create a main workflow (`.github/workflows/ci.yml`) that calls the reusable build and then verifies dependencies.
```yaml
name: CI
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
id-token: write # Needed if you verify provenance of dependencies
jobs:
build:
uses: ./.github/workflows/build.yml
verify-deps:
runs-on: ubuntu-latest
needs: build
steps:
- name: Download dependency provenance
run: |
# Example: verify a third-party binary used in build
curl -LO https://example.com/dependency.bin
curl -LO https://example.com/dependency.intoto.jsonl
slsa-verifier verify-artifact \
--provenance-path dependency.intoto.jsonl \
--source-uri github.com/trusted-owner/dependency \
--builder-id trusted-builder-id \
dependency.bin
```
### 3.3 Release Workflow with SLSA3 Provenance
Create a separate workflow (`.github/workflows/release.yml`) triggered on tags or release publication.
```yaml
name: Release
on:
release:
types: [published]
permissions:
id-token: write
attestations: write
contents: write
actions: read
jobs:
build:
uses: ./.github/workflows/build.yml
provenance:
needs: build
uses: slsa-framework/slsa-github-generator/.github/workflows/generator_generic_slsa3.yml@v2.1.0
with:
base64-subjects: ${{ needs.build.outputs.base64-subjects }}
upload-artifacts-name: build-artifacts-${{ github.run_id }}
upload-assets: true
verify-and-publish:
needs: provenance
runs-on: ubuntu-latest
steps:
- uses: actions/download-artifact@v4
with:
name: build-artifacts-${{ github.run_id }}
path: artifacts/
- name: Verify provenance
run: |
gh attestation verify artifacts/myapp \
--owner ${{ github.repository_owner }} \
--signer-repo slsa-framework/slsa-github-generator
- name: Upload to release
run: |
gh release upload ${{ github.event.release.tag_name }} artifacts/* provenance.json
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
---
## 🔐 Phase 4: Verification Gate Before Deployment
### 4.1 Deployment Job
In the release workflow (or a separate deployment workflow), add a final verification step:
```yaml
deploy:
needs: verify-and-publish
runs-on: ubuntu-latest
environment: production
steps:
- name: Verify attestation again (defense in depth)
run: |
gh attestation verify artifacts/myapp \
--owner ${{ github.repository_owner }}
- name: Deploy
run: ./deploy.sh artifacts/
```
### 4.2 Enforce Verification in Production Environment
- Configure GitHub Environments with **required reviewers**.
- Optionally, use a deployment protection rule that calls an external verification service (e.g., via a custom GitHub Action).
---
## 📘 Phase 5: Developer Onboarding & Documentation
Create a `CONTRIBUTING.md` or `DEVELOPMENT.md` that covers:
- How to set up the local environment (Docker, pre‑commit, signing keys).
- How to run a local build that mimics CI.
- How to interpret verification failures.
- Where to find provenance files and how to manually verify them.
Example section:
```markdown
## Verifying Artifacts Locally
After a CI build, you can download the provenance file from the workflow run and verify it:
```bash
gh attestation verify myapp --owner myorg
```
Or using the `slsa-verifier` tool:
```bash
slsa-verifier verify-artifact \
--provenance-path provenance.json \
--source-uri github.com/myorg/myapp \
myapp
```
```
---
## 🧪 Phase 6: Testing the Pipeline
1. **Test a pull request**: Push a change, ensure the CI workflow runs, and that dependency verification passes.
2. **Create a pre‑release**: Tag a commit, push the tag, and trigger the release workflow. Download the artifacts and verify them manually.
3. **Simulate a tampering attempt**: Modify an artifact locally and try to verify it – the verification should fail.
4. **Rotate keys**: If using GPG for commit signing, practice rotating a developer key and updating the repository settings.
---
## 📈 Ongoing Maintenance
- Keep the SLSA generator version up to date (check for releases at [slsa-framework/slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator/releases)).
- Periodically review dependency verification rules.
- Update developer documentation as tooling evolves.
---
## 🎉 You’re Now SLSA3‑Ready
By following this guide, your development workflow will:
- Produce **non‑forgeable provenance** for every release.
- Ensure **source integrity** through signed commits.
- Provide **reproducible builds** via containerized environments.
- Build a **culture of security** where every developer understands and participates in supply chain protection.
This is a living process – adapt it to your team’s size, tech stack, and release cadence. And remember, the SLSA community is constantly improving tooling and practices; stay engaged to keep your pipeline cutting‑edge.
Would you like help with any specific part, such as setting up the containerized environment or writing the reusable workflow? I’m here to assist!
Sazwanismail
added
documentation
|
|
CodeAnt AI is reviewing your PR. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a comprehensive, step-by-step guide for establishing a SLSA Level 3 compliant development workflow. It covers practical recommendations from securing the repository and local development environment to implementing robust CI/CD pipelines with provenance generation and verification, ensuring every artifact has verifiable proof of its origin and integrity. The aim is to integrate security practices seamlessly into daily development, fostering a culture of supply chain protection. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
codeant-ai
Bot
added
size:L
Sequence DiagramThis PR replaces a general contributing guide with a SLSA3 oriented development workflow. The new core flow emphasizes local dependency verification and reproducible builds, followed by CI provenance verification before merge and signed release. sequenceDiagram
participant Developer
participant LocalEnv
participant CI
participant Verifier
participant Release
Developer->>LocalEnv: Pull signed commits and implement change
Developer->>LocalEnv: Run pre commit dependency and security checks
Developer->>LocalEnv: Build and test in reproducible container
Developer->>CI: Push branch and open pull request
CI->>Verifier: Verify dependency provenance and build provenance
Verifier-->>CI: Verification passed
CI-->>Developer: Provenance checks green
Developer->>Release: Merge and publish signed artifact with provenance
Generated by CodeAnt AI |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request replaces the existing Development file, which served as a contribution guide, with a new document focused on implementing a SLSA3-compliant development workflow. While the new guide on SLSA3 is detailed and valuable, this change results in the complete removal of the previous contribution guidelines, which may be unintentional. My review includes suggestions to improve the new content's quality as a technical document, primarily by removing conversational language that seems to have been copied from a draft or interactive session. I recommend you consider whether the original contribution guide should be preserved, for example by integrating the new SLSA3 information into it or by placing the SLSA3 guide in a separate file.
Nitpicks 🔍
|
![codeant-ai[bot]](https://avatars.githubusercontent.com/in/646884?s=60&v=4){kind=small}
|
CodeAnt AI finished reviewing your PR. |
1 participant
User description
Building a SLSA3‑Compliant Development Workflow: A Practical Guide
You’ve asked to “Create development” – and that’s exactly what we’ll do. Below is a step‑by‑step blueprint for setting up a development environment and process that meets SLSA Level 3 requirements while remaining practical for everyday coding. This guide builds on everything we’ve discussed and gives you a concrete path forward.
🎯 Goal
Establish a development pipeline where every artifact (commits, builds, releases) carries verifiable proof of its origin and integrity, satisfying SLSA Build Level 3 and setting the foundation for higher levels.
📦 Phase 1: Repository Foundation
1.1 Enable Signed Commits
gpg --full-generate-key).bash git config --global user.signingkey <key-id> git config --global commit.gpgsign true1.2 Branch Protection Rules
1.3 Dependency Locking
go.sum,package-lock.json,Cargo.lock, etc.) to pin dependency versions.🛠️ Phase 2: Local Developer Environment
2.1 Containerized Development Environment
Dockerfileor Dev Container configuration that mirrors your CI build environment..devcontainer/devcontainer.json:json { "name": "MyApp Dev", "build": { "dockerfile": "Dockerfile" }, "features": { "ghcr.io/devcontainers/features/common-utils:2": {} } }2.2 Pre‑commit Hooks for Security
go.sumagainst a known good state).detect-secretsortruffleHog)..pre-commit-config.yaml: ```yaml repos:2.3 Local Build with Provenance (Optional but Recommended)
local-build.sh:bash #!/bin/bash in-toto-run --step-name local-build --products myapp --key mykey -- ./build.sh🔁 Phase 3: Continuous Integration (CI) Pipeline
3.1 Reusable Build Workflow
Create a reusable workflow (
.github/workflows/build.yml) that encapsulates your build steps and outputs artifact hashes.3.2 Main CI Workflow (PRs and Merges)
Create a main workflow (
.github/workflows/ci.yml) that calls the reusable build and then verifies dependencies.3.3 Release Workflow with SLSA3 Provenance
Create a separate workflow (
.github/workflows/release.yml) triggered on tags or release publication.🔐 Phase 4: Verification Gate Before Deployment
4.1 Deployment Job
In the release workflow (or a separate deployment workflow), add a final verification step:
4.2 Enforce Verification in Production Environment
📘 Phase 5: Developer Onboarding & Documentation
Create a
CONTRIBUTING.mdorDEVELOPMENT.mdthat covers:Example section:
Or using the
slsa-verifiertool: