stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

docs consolidation and others

Browse Source
This commit is contained in:
master
2026-01-06 19:02:21 +02:00
parent d7bdca6d97
commit 4789027317
849 changed files with 16551 additions and 66770 deletions
Download Patch File Download Diff File Expand all files Collapse all files

310
docs/modules/authority/guides Normal file
View File

@@ -0,0 +1,310 @@
# Identity Constraints for Keyless Verification
## Overview
Keyless signing binds cryptographic signatures to OIDC identities. When verifying signatures, you must specify which identities are trusted. This document covers identity constraint patterns for all supported CI/CD platforms.
## Core Concepts
### Certificate Identity
The certificate identity is the subject claim from the OIDC token, embedded in the Fulcio certificate. It identifies:
- **Who** created the signature (repository, branch, workflow)
- **When** the signature was created (within the certificate validity window)
- **Where** the signing happened (CI platform, environment)
### OIDC Issuer
The OIDC issuer is the URL of the identity provider that issued the token. Each CI platform has its own issuer:
| Platform | Issuer URL |
|----------|------------|
| GitHub Actions | `https://token.actions.githubusercontent.com` |
| GitLab CI (SaaS) | `https://gitlab.com` |
| GitLab CI (Self-hosted) | `https://your-gitlab-instance.com` |
| Gitea | `https://your-gitea-instance.com` |
### Verification Flow
```
┌─────────────────────────────────────────────────────────────────────────┐
│ Verification Process │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. Extract certificate from attestation │
│ └─▶ Contains: subject, issuer, SAN, validity period │
│ │
│ 2. Validate certificate chain │
│ └─▶ Chains to trusted Fulcio root │
│ │
│ 3. Check OIDC issuer │
│ └─▶ Must match --certificate-oidc-issuer │
│ │
│ 4. Check certificate identity │
│ └─▶ Subject must match --certificate-identity pattern │
│ │
│ 5. Verify Rekor inclusion (if required) │
│ └─▶ Signature logged during certificate validity │
│ │
│ 6. Verify signature │
│ └─▶ Signature valid for artifact digest │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
## Platform-Specific Patterns
### GitHub Actions
GitHub Actions OIDC tokens include rich context about the workflow execution.
#### Token Claims
| Claim | Description | Example |
|-------|-------------|---------|
| `sub` | Subject (identity) | `repo:org/repo:ref:refs/heads/main` |
| `repository` | Full repository name | `org/repo` |
| `repository_owner` | Organization/user | `org` |
| `ref` | Git ref | `refs/heads/main` |
| `ref_type` | Ref type | `branch` or `tag` |
| `job_workflow_ref` | Workflow file | `.github/workflows/release.yml@refs/heads/main` |
| `environment` | Deployment environment | `production` |
#### Identity Patterns
| Constraint | Pattern | Example |
|------------|---------|---------|
| Any ref | `repo:<owner>/<repo>:.*` | `repo:stellaops/scanner:.*` |
| Main branch | `repo:<owner>/<repo>:ref:refs/heads/main` | `repo:stellaops/scanner:ref:refs/heads/main` |
| Any branch | `repo:<owner>/<repo>:ref:refs/heads/.*` | `repo:stellaops/scanner:ref:refs/heads/.*` |
| Version tags | `repo:<owner>/<repo>:ref:refs/tags/v.*` | `repo:stellaops/scanner:ref:refs/tags/v.*` |
| Environment | `repo:<owner>/<repo>:environment:<env>` | `repo:stellaops/scanner:environment:production` |
| Workflow | (use SAN) | N/A |
#### Examples
```bash
# Accept only main branch
stella attest verify \
--artifact sha256:abc123... \
--certificate-identity "repo:stellaops/scanner:ref:refs/heads/main" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
# Accept main or release branches
stella attest verify \
--artifact sha256:abc123... \
--certificate-identity "repo:stellaops/scanner:ref:refs/heads/(main|release/.*)" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
# Accept any version tag
stella attest verify \
--artifact sha256:abc123... \
--certificate-identity "repo:stellaops/scanner:ref:refs/tags/v[0-9]+\.[0-9]+\.[0-9]+.*" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
# Accept production environment only
stella attest verify \
--artifact sha256:abc123... \
--certificate-identity "repo:stellaops/scanner:environment:production" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
```
### GitLab CI
GitLab CI provides OIDC tokens with project and pipeline context.
#### Token Claims
| Claim | Description | Example |
|-------|-------------|---------|
| `sub` | Subject | `project_path:group/project:ref_type:branch:ref:main` |
| `project_path` | Full project path | `stellaops/scanner` |
| `namespace_path` | Namespace | `stellaops` |
| `ref` | Git ref | `main` |
| `ref_type` | Ref type | `branch` or `tag` |
| `ref_protected` | Protected ref | `true` or `false` |
| `environment` | Environment name | `production` |
| `pipeline_source` | Trigger source | `push`, `web`, `schedule` |
#### Identity Patterns
| Constraint | Pattern | Example |
|------------|---------|---------|
| Any ref | `project_path:<group>/<project>:.*` | `project_path:stellaops/scanner:.*` |
| Main branch | `project_path:<group>/<project>:ref_type:branch:ref:main` | Full pattern |
| Protected refs | `project_path:<group>/<project>:ref_protected:true` | Full pattern |
| Tags | `project_path:<group>/<project>:ref_type:tag:ref:.*` | Full pattern |
#### Examples
```bash
# Accept main branch only
stella attest verify \
--artifact sha256:abc123... \
--certificate-identity "project_path:stellaops/scanner:ref_type:branch:ref:main" \
--certificate-oidc-issuer "https://gitlab.com"
# Accept any protected ref
stella attest verify \
--artifact sha256:abc123... \
--certificate-identity "project_path:stellaops/scanner:ref_protected:true.*" \
--certificate-oidc-issuer "https://gitlab.com"
# Self-hosted GitLab
stella attest verify \
--artifact sha256:abc123... \
--certificate-identity "project_path:mygroup/myproject:.*" \
--certificate-oidc-issuer "https://gitlab.internal.example.com"
```
### Gitea
Gitea OIDC tokens follow a similar pattern to GitHub Actions.
#### Token Claims
| Claim | Description | Example |
|-------|-------------|---------|
| `sub` | Subject | `org/repo:ref:refs/heads/main` |
| `repository` | Repository path | `org/repo` |
| `ref` | Git ref | `refs/heads/main` |
#### Identity Patterns
| Constraint | Pattern | Example |
|------------|---------|---------|
| Any ref | `<org>/<repo>:.*` | `stellaops/scanner:.*` |
| Main branch | `<org>/<repo>:ref:refs/heads/main` | `stellaops/scanner:ref:refs/heads/main` |
| Tags | `<org>/<repo>:ref:refs/tags/.*` | `stellaops/scanner:ref:refs/tags/.*` |
#### Examples
```bash
# Accept main branch
stella attest verify \
--artifact sha256:abc123... \
--certificate-identity "stella-ops.org/git.stella-ops.org:ref:refs/heads/main" \
--certificate-oidc-issuer "https://git.stella-ops.org"
```
## Best Practices
### Security Recommendations
1. **Always Constrain to Repository**
Never accept wildcards that could match any repository:
```bash
# BAD - accepts any repository
--certificate-identity "repo:.*"
# GOOD - specific repository
--certificate-identity "repo:stellaops/scanner:.*"
```
2. **Prefer Branch/Tag Constraints for Production**
```bash
# Better - only main branch
--certificate-identity "repo:stellaops/scanner:ref:refs/heads/main"
# Even better - only signed tags
--certificate-identity "repo:stellaops/scanner:ref:refs/tags/v.*"
```
3. **Use Environment Constraints When Available**
```bash
# Most specific - production environment only
--certificate-identity "repo:stellaops/scanner:environment:production"
```
4. **Always Require Rekor Proofs**
```bash
# Always include --require-rekor for production
stella attest verify \
--artifact sha256:... \
--certificate-identity "..." \
--certificate-oidc-issuer "..." \
--require-rekor
```
5. **Pin Trusted Issuers**
Only trust expected OIDC issuers. Never accept `.*` for issuer.
### Common Patterns
#### Multi-Environment Trust
```yaml
# GitHub Actions - Different constraints per environment
staging:
identity: "repo:myorg/myrepo:ref:refs/heads/.*"
production:
identity: "repo:myorg/myrepo:ref:refs/(heads/main|tags/v.*)"
```
#### Cross-Repository Trust
```bash
# Trust signatures from multiple repositories
stella attest verify \
--artifact sha256:... \
--certificate-identity "repo:myorg/(repo1|repo2|repo3):ref:refs/heads/main" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
```
#### Organization-Wide Trust
```bash
# Trust any repository in organization (use with caution)
stella attest verify \
--artifact sha256:... \
--certificate-identity "repo:myorg/.*:ref:refs/heads/main" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"
```
## Troubleshooting
### Common Errors
| Error | Cause | Solution |
|-------|-------|----------|
| `identity mismatch` | Pattern doesn't match certificate subject | Check ref format (refs/heads/ vs branch name) |
| `issuer mismatch` | Wrong OIDC issuer URL | Use correct issuer for platform |
| `certificate expired` | Signing cert expired, no Rekor proof | Ensure `--require-rekor` and Rekor was used at signing |
| `no attestations found` | Attestation not attached to artifact | Verify attestation was pushed to registry |
### Debugging Identity Patterns
```bash
# Inspect certificate to see actual identity
stella attest inspect \
--artifact sha256:... \
--show-cert
# Expected output:
# Certificate Subject: repo:stellaops/scanner:ref:refs/heads/main
# Certificate Issuer: https://token.actions.githubusercontent.com
# Certificate SAN: https://github.com/stellaops/scanner/.github/workflows/release.yml@refs/heads/main
```
### Testing Patterns
```bash
# Test pattern matching locally
echo "repo:myorg/myrepo:ref:refs/heads/main" | \
grep -E "repo:myorg/myrepo:ref:refs/heads/(main|develop)"
```
## Related Documentation
- [Keyless Signing Guide](../modules/signer/guides/keyless-signing.md)
- [GitHub Actions Templates](../../.github/workflows/examples/)
- [GitLab CI Templates](../../deploy/gitlab/examples/)
- [Sigstore Documentation](https://docs.sigstore.dev/)

4
docs/modules/authority/operations/backup-restore.md
View File

@@ -80,12 +80,12 @@
docker compose up -d
curl -fsS http://localhost:8080/health
```
6. **Validate JWKS and tokens:** call `/jwks` and issue a short-lived token via the CLI to confirm key material matches expectations. If the restored environment requires a fresh signing key, follow the rotation SOP in [`docs/11_AUTHORITY.md`](../../../11_AUTHORITY.md) using `ops/authority/key-rotation.sh` to invoke `/internal/signing/rotate`.
6. **Validate JWKS and tokens:** call `/jwks` and issue a short-lived token via the CLI to confirm key material matches expectations. If the restored environment requires a fresh signing key, follow the rotation SOP in [`docs/AUTHORITY.md`](../../../AUTHORITY.md) using `ops/authority/key-rotation.sh` to invoke `/internal/signing/rotate`.
## Disaster Recovery Notes
- **Air-gapped replication:** replicate archives via the Offline Update Kit transport channels; never attach USB devices without scanning.
- **Retention:** maintain 30 daily snapshots + 12 monthly archival copies. Rotate encryption keys annually.
- **Key compromise:** if signing keys are suspected compromised, restore from the latest clean backup, rotate via OPS3 (see `ops/authority/key-rotation.sh` and [`docs/11_AUTHORITY.md`](../../../11_AUTHORITY.md)), and publish a revocation notice.
- **Key compromise:** if signing keys are suspected compromised, restore from the latest clean backup, rotate via OPS3 (see `ops/authority/key-rotation.sh` and [`docs/AUTHORITY.md`](../../../AUTHORITY.md)), and publish a revocation notice.
- **PostgreSQL version:** keep dump/restore images pinned to the deployment version (compose uses `postgres:16`). Npgsql 8.x requires PostgreSQL **12+**—clusters still on older versions must be upgraded before restore.
## Verification Checklist

4
docs/modules/authority/operations/key-rotation.md
View File

@@ -1,7 +1,7 @@
# Authority Signing Key Rotation Playbook
> **Status:** Authored 2025-10-12 as part of OPS3.KEY-ROTATION rollout.
> Use together with `docs/11_AUTHORITY.md` (Authority service guide) and the automation shipped under `ops/authority/`.
> Use together with `docs/AUTHORITY.md` (Authority service guide) and the automation shipped under `ops/authority/`.
## 1. Overview
@@ -78,7 +78,7 @@ Treat these as examples; real environments must maintain their own PEM material.
## 6. References
- `docs/11_AUTHORITY.md` – Architecture and rotation SOP (Section 5).
- `docs/AUTHORITY.md` – Architecture and rotation SOP (Section 5).
- `docs/modules/authority/operations/backup-restore.md` – Recovery flow referencing this playbook.
- `ops/authority/README.md` – CLI usage and examples.
- `scripts/rotate-policy-cli-secret.sh` – Helper to mint new `policy-cli` shared secrets when policy scope bundles change.