Skip to content

Commit 7cde42e

Browse files
St0rmz1St0rmz1
authored
St0rmz1/feature/use securebuild for builds (#319)
* init of using securebuild * delete the old apko template * update docs * clean up
1 parent 3955743 commit 7cde42e

File tree

14 files changed

+1144
-154
lines changed

14 files changed

+1144
-154
lines changed

‎.github/workflows/publish.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ jobs:
7575
- uses: dagger/[email protected]
7676
id: dagger-publish
7777
env:
78+
USE_SECUREBUILD: true
7879
OP_SERVICE_ACCOUNT: ${{ secrets.OP_SERVICE_ACCOUNT }}
7980
OP_SERVICE_ACCOUNT_PRODUCTION: ${{ secrets.OP_SERVICE_ACCOUNT_PRODUCTION }}
8081
with:
@@ -99,6 +100,7 @@ jobs:
99100
- uses: dagger/[email protected]
100101
id: dagger-publish
101102
env:
103+
USE_SECUREBUILD: true
102104
OP_SERVICE_ACCOUNT: ${{ secrets.OP_SERVICE_ACCOUNT }}
103105
OP_SERVICE_ACCOUNT_PRODUCTION: ${{ secrets.OP_SERVICE_ACCOUNT_PRODUCTION }}
104106
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎certs/README.md‎

Lines changed: 39 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,60 @@
11
# Certificates and Verification Tools
22

3-
This directory contains certificates and verification tools used for validating the authenticity and integrity of Replicated SDK container images.
3+
> **⚠️ DEPRECATION NOTICE**: This directory is transitioning away from manual image verification tools as SecureBuild now automatically handles SLSA attestations, SBOM generation, and image signing for staging and production builds. See migration notes below.
44
5-
## Contents
5+
This directory contains legacy certificates and verification tools that were used for validating the authenticity and integrity of Replicated SDK container images.
6+
7+
## 🔄 Migration to SecureBuild
8+
9+
**As of September 2025**, the Replicated SDK build pipeline uses [SecureBuild](https://securebuild.com) for staging and production image builds, which provides:
10+
11+
- **Automatic SLSA Attestation**: Built-in provenance generation without manual workflows
12+
- **Automatic SBOM Generation**: Comprehensive software bill of materials with CVE remediation data
13+
- **Automatic Image Signing**: Cryptographic signatures managed by SecureBuild
14+
- **Multi-Registry Publishing**: Images published to Docker Hub, Replicated registries, and CVE0.io
15+
16+
### Current Build Architecture
17+
18+
- **Development Builds**: May still use traditional pipeline with manual verification (optional SecureBuild)
19+
- **Staging/Production Builds**: Use SecureBuild with automatic security attestations
20+
- **Environment Flag**: Controlled by `USE_SECUREBUILD=true` in GitHub Actions
21+
22+
## 📋 Legacy Contents (For Reference)
623

724
### Verification Script
8-
- `verify-image.sh` - Script to verify SLSA attestation, image signatures, and SBOM for SDK images
25+
- `verify-image.sh` - **Legacy script** for manual SLSA attestation, image signatures, and SBOM verification
926

1027
### Public Keys
11-
- `cosign-dev.pub` - Development environment public key for image signature verification
12-
- `cosign-stage.pub` - Staging environment public key for image signature verification
13-
- `cosign-prod.pub` - Production environment public key for image signature verification
28+
- `cosign-dev.pub` - **Legacy**: Development environment public key for image signature verification
29+
- `cosign-stage.pub` - **Legacy**: Staging environment public key for image signature verification
30+
- `cosign-prod.pub` - **Legacy**: Production environment public key for image signature verification
31+
32+
## 🔧 Verification Methods
1433

15-
## Usage
34+
### For SecureBuild Images (Recommended)
35+
SecureBuild images include built-in attestations and can be verified using SecureBuild's verification tools. Refer to the [SecureBuild documentation](https://securebuild.com) for current verification methods.
1636

17-
The verification script supports three environments (dev, stage, prod) and can be run as follows:
37+
### For Legacy Images (Development/Fallback)
38+
If using traditional pipeline builds, the legacy verification script can still be used:
1839

1940
```bash
2041
./verify-image.sh --env <environment> --version <version> --digest <image-digest>
2142
```
2243

23-
For detailed usage instructions and examples, run:
44+
For detailed usage instructions:
2445
```bash
2546
./verify-image.sh --help
2647
```
2748

28-
## Environment-Specific Verification
49+
## ⚠️ Important Notes
2950

30-
- **Development**: Uses `cosign-dev.pub` for signature verification
31-
- **Staging**: Uses `cosign-stage.pub` for signature verification
32-
- **Production**: Uses `cosign-prod.pub` for signature verification
51+
1. **Production Images**: All production images now use SecureBuild attestations - legacy verification may not apply
52+
2. **Staging Images**: All staging images now use SecureBuild attestations - legacy verification may not apply
53+
3. **Development Images**: May use either SecureBuild or legacy pipeline depending on `USE_SECUREBUILD` flag
54+
4. **Future Plans**: This directory may be removed in future releases once SecureBuild migration is complete
3355

34-
## Security Notes
56+
## 📚 Documentation References
3557

36-
- The public keys in this directory are used only for verification
58+
- **Current Build Process**: See `/dagger/README.md` for comprehensive SecureBuild integration guide
59+
- **SecureBuild Benefits**: Zero-CVE images, enhanced security, compliance-ready attestations
60+
- **Migration Guide**: All GitHub Actions workflows automatically use SecureBuild for staging/production

‎dagger.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "replicated-sdk",
3-
"engineVersion": "v0.18.6",
3+
"engineVersion": "v0.18.14",
44
"sdk": {
55
"source": "go"
66
},

‎dagger/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@
22
/internal/dagger
33
/internal/querybuilder
44
/internal/telemetry
5+
/.env

‎dagger/README.md‎

Lines changed: 158 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,40 @@
11
# Dagger Pipeline Usage
22

3+
## Build Architecture Overview
4+
5+
This Dagger pipeline supports two build approaches:
6+
7+
### 🚀 **SecureBuild** (Default for staging/production)
8+
- **What**: Zero-CVE container images built by SecureBuild.com
9+
- **Benefits**: Enhanced security, compliance, automatic CVE remediation
10+
- **Requirements**: SecureBuild account + 1Password access
11+
- **Registries**: Docker Hub + Replicated registries + CVE0.io
12+
13+
### 🛠️ **Wolfi/TTL.sh** (Fallback for development)
14+
- **What**: Traditional Wolfi-based images for development
15+
- **Benefits**: No credentials required
16+
- **Requirements**: None (public repositories only)
17+
- **Registries**: TTL.sh
18+
19+
---
20+
21+
## 🔧 **Environment Configuration**
22+
23+
### SecureBuild Mode (Recommended)
24+
```bash
25+
export USE_SECUREBUILD=true
26+
export OP_SERVICE_ACCOUNT="your-1password-service-account-token"
27+
export OP_SERVICE_ACCOUNT_PRODUCTION="your-production-1password-token" # for production builds
28+
```
29+
30+
### Traditional Mode (Development Fallback)
31+
```bash
32+
# No environment variables needed - will use deploy/apko-wolfi.yaml
33+
# Images published to ttl.sh with 24h expiration
34+
```
35+
36+
---
37+
338
## Validation
439

540
To validate the codebase without publishing:
@@ -10,47 +45,133 @@ dagger call validate --progress=plain \
1045

1146
## Publishing
1247

13-
The publish pipeline supports different environments and configurations. Here are the common usage patterns:
48+
The publish pipeline supports different environments and configurations:
49+
50+
> **Note**: All version numbers in examples below (e.g., `1.0.0-dev.1`, `1.0.0-beta.1`, `1.0.0`) are for illustration purposes only. Use your actual release version numbers when running commands.
1451
1552
### Development Release (ttl.sh)
1653

17-
For local testing using ttl.sh registry:
54+
#### Option 1: SecureBuild Development (with credentials)
55+
In this scenario, the pipeline uses SecureBuild and will publish the image to ttl.sh
1856
```bash
57+
export USE_SECUREBUILD=true
1958
dagger call publish --progress=plain \
2059
--op-service-account=env:OP_SERVICE_ACCOUNT \
2160
--dev=true \
2261
--staging=false \
23-
--version=1.6.0-dev.1 \
62+
--version=1.0.0-dev.1 \
2463
--slsa=false
2564
```
65+
**Result**: Uses `deploy/apko-securebuild.yaml` → publishes to TTL.sh + CVE0.io
66+
In this scenario, the pipeline uses Wolfi and will publish to ttl.sh
67+
68+
#### Option 2: Traditional Wolfi Development (no credentials)
69+
```bash
70+
# DO NOT set USE_SECUREBUILD
71+
dagger call publish --progress=plain \
72+
--op-service-account=env:OP_SERVICE_ACCOUNT \
73+
--dev=true \
74+
--staging=false \
75+
--version=1.0.0-dev.1 \
76+
--slsa=false
77+
```
78+
**Result**: Uses `deploy/apko-wolfi.yaml` → publishes to TTL.sh only
2679

27-
### Staging Release
80+
### Staging Release (SecureBuild Required)
2881

2982
For publishing to staging environment:
3083
```bash
84+
export USE_SECUREBUILD=true # Required for staging builds
3185
dagger call publish --progress=plain \
3286
--op-service-account=env:OP_SERVICE_ACCOUNT \
3387
--op-service-account-production=env:OP_SERVICE_ACCOUNT_PRODUCTION \
3488
--dev=false \
3589
--staging=true \
36-
--version=1.6.0-beta.5 \
37-
--slsa=true \
38-
--github-token=env:GITHUB_TOKEN
90+
--version=1.0.0-beta.1
3991
```
92+
**Result**: Uses SecureBuild staging → publishes to:
93+
- `docker.io/replicated/replicated-sdk:1.0.0-beta.1`
94+
- `registry.staging.replicated.com/library/replicated-sdk-image:1.0.0-beta.1`
95+
- `cve0.io/replicated-sdk:1.0.0-beta.1`
4096

41-
### Production Release
97+
### Production Release (SecureBuild Required)
4298

4399
For publishing to production:
44100
```bash
101+
export USE_SECUREBUILD=true # Required for production builds
45102
dagger call publish --progress=plain \
46103
--op-service-account=env:OP_SERVICE_ACCOUNT \
47104
--op-service-account-production=env:OP_SERVICE_ACCOUNT_PRODUCTION \
48105
--dev=false \
49106
--staging=false \
50-
--version=1.6.0 \
51-
--slsa=true \
52-
--github-token=env:GITHUB_TOKEN
107+
--version=1.0.0
53108
```
109+
**Result**: Uses SecureBuild production → publishes to:
110+
- `docker.io/replicated/replicated-sdk:1.0.0`
111+
- `registry.replicated.com/library/replicated-sdk-image:1.0.0`
112+
- `cve0.io/replicated-sdk:1.0.0`
113+
114+
> **Note**: SecureBuild automatically handles SLSA attestations and SBOM generation, so `--slsa` and `--github-token` flags are not required (and are ignored) when using SecureBuild.
115+
116+
---
117+
118+
## 🔐 **SecureBuild Integration**
119+
120+
### Requirements for SecureBuild
121+
1. **SecureBuild Account**: Active account at SecureBuild.com
122+
2. **Team Configuration**:
123+
- Feature flags enabled for "Custom APKO Upload" and "Custom Melange Upload"
124+
- Team subscribed to the image/catalog item in SecureBuild
125+
3. **1Password Access**: Service account tokens for dev/production vaults
126+
4. **Credentials**: Proper 1Password items configured:
127+
- `SecureBuild-Dev-Token` (in developer automation vault)
128+
- `SecureBuild-Replicated-SDK-Prod-Token` (in production vault)
129+
130+
### SecureBuild Benefits
131+
- **Zero CVE Images**: Automatically patched base images
132+
- **Multi-Registry Publishing**: Single build → multiple registries
133+
- **Enhanced Security**: SLSA attestations + SBOM generation
134+
- **Compliance Ready**: Meets enterprise security requirements
135+
136+
### Image Naming Architecture
137+
SecureBuild handles different registry naming requirements:
138+
- **Docker Hub**: Uses `replicated-sdk` image name
139+
- **Replicated Registries**: Uses `replicated-sdk-image` image name
140+
- **CVE0.io**: Uses `replicated-sdk` image name
141+
142+
This ensures compatibility with existing Docker Hub users and Replicated Helm charts.
143+
144+
### Configuration Files
145+
- **SecureBuild**: Uses `deploy/apko-securebuild.yaml`
146+
- **Traditional**: Uses `deploy/apko-wolfi.yaml`
147+
- **Selection**: Automatic based on `USE_SECUREBUILD` environment variable
148+
149+
### Current Limitations
150+
**Package Dependency Requirement**: The SecureBuild pipeline dynamically modifies the APKO configuration:
151+
- Version substitution: `VERSION: 1.0.0` → `VERSION: "your-version"`
152+
- Package substitution: `- replicated` → `- replicated-your-version`
153+
154+
**Important**: The versioned package (e.g., `replicated-1.0.0-beta.1`) must already exist in the CVE0.io repository before the APKO build. The current pipeline does not automatically create these packages via melange submission.
155+
156+
### Troubleshooting SecureBuild
157+
Common issues and solutions:
158+
159+
**403 Forbidden Errors**:
160+
- Check 1Password service account has vault access
161+
- Verify SecureBuild team has "Custom APKO Upload" feature flag
162+
- Confirm API tokens are valid in 1Password items
163+
164+
**Missing Package Errors**:
165+
- SecureBuild uses CVE0.io repository for packages
166+
- Package `replicated-{version}` must exist before APKO build
167+
- **Current workaround**: Manually create packages in SecureBuild before running builds
168+
- **Future enhancement**: Automatic melange.yaml submission for package generation
169+
170+
**Build Timeouts**:
171+
- Monitor build status in SecureBuild dashboard
172+
- Check Dagger traces for detailed timing
173+
174+
---
54175

55176
## Available Flags
56177

@@ -60,19 +181,19 @@ dagger call publish --progress=plain \
60181
- `--dev`: (boolean) Use development environment (ttl.sh)
61182
- `--staging`: (boolean) Use staging environment
62183
- `--version`: Version string for the release
63-
- `--slsa`: (boolean) Enable SLSA provenance generation
64-
- `--github-token`: GitHub token for SLSA workflow access
184+
- `--slsa`: (boolean) Enable SLSA provenance generation *(ignored when using SecureBuild)*
185+
- `--github-token`: GitHub token for SLSA workflow access *(ignored when using SecureBuild)*
65186

66-
Note: SLSA provenance generation requires both `--slsa=true` and a valid `--github-token`.
187+
**Note**: When using SecureBuild (`USE_SECUREBUILD=true`), SLSA attestations and SBOM generation are automatic. The `--slsa` and `--github-token` flags are only used with the traditional Chainguard pipeline.
67188

68189
## SBOM Generation
69190

70191
Software Bill of Materials (SBOM) is automatically generated during the build process:
71192

72193
1. **Generation Method**:
73-
- Uses Chainguard's melange and apko to create SPDX-formatted SBOMs
74-
- SBOMs are generated for both the base image and application layers
75-
- Includes all direct and transitive dependencies
194+
- **SecureBuild**: Automatically generates comprehensive SBOMs with CVE remediation data
195+
- **Traditional**: Uses Chainguard's melange and apko to create SPDX-formatted SBOMs
196+
- SBOMs include all direct and transitive dependencies with license information
76197

77198
2. **SBOM Format**:
78199
- Format: SPDX JSON
@@ -83,33 +204,25 @@ Software Bill of Materials (SBOM) is automatically generated during the build pr
83204
- Creation metadata
84205

85206
3. **Verification**:
86-
- SBOMs are signed using cosign
87-
- Attestations are attached to the container image
88-
- Use the verification script in `certs/verify-image.sh` to verify:
89-
- SLSA provenance
90-
- Image signatures
91-
- SBOM attestations
92-
```bash
93-
./certs/verify-image.sh --env <dev|stage|prod> --version <version> --digest <image-digest>
94-
```
207+
- Refer to the instructions at securebuild.com
95208

96209
4. **Viewing SBOM**:
97-
- Full SBOM content can be viewed using the `--show-sbom` flag with verify-image.sh:
98-
```bash
99-
./certs/verify-image.sh --env <dev|stage|prod> --version <version> --digest <image-digest> --show-sbom
100-
```
101-
102-
## Image Attestation
103-
104-
- Images pushed to Dockerhub are attested using cosign
105-
- This provides an additional layer of verification for public images
106-
- The attestation includes:
107-
- SBOM data
108-
- Build provenance
109-
- Image signatures
110-
111-
For production releases, SLSA provenance is automatically generated:
112-
- Triggered by the Dagger pipeline during production releases
113-
- Requires a GitHub token with permissions to trigger the SLSA workflow (`slsa.yml`)
114-
- The workflow is triggered via GitHub API to generate and attach provenance to the image
115-
- This step is skipped for development and staging releases
210+
- Refer to the instructions at securebuild.com
211+
212+
5. **Image Attestation**
213+
- Refer to the instructions at securebuild.com
214+
215+
---
216+
217+
## 🔄 **Migration Notes**
218+
219+
### GitHub Actions Integration
220+
As of September 2025, GitHub Actions workflows automatically use SecureBuild for staging and production builds:
221+
- **Environment Variable**: `USE_SECUREBUILD=true` is set in `.github/workflows/publish.yml`
222+
- **Backward Compatibility**: Wolfi based pipeline remains as fallback if flag is removed
223+
- **No Breaking Changes**: All existing interfaces and outputs remain unchanged
224+
225+
### For Contributors
226+
- **Development builds**: Can still use TTL.sh without any SecureBuild credentials
227+
- **No setup required**: Traditional Wolfi builds work without configuration
228+
- **Optional SecureBuild**: Set `USE_SECUREBUILD=true` only if you have access

0 commit comments

Comments
 (0)