116 lines
5.7 KiB
Markdown
116 lines
5.7 KiB
Markdown
---
|
|
name: working-with-provenance
|
|
description: Use when tracing Konflux builds from image references, finding build logs from artifacts, or verifying source commits for container images - extracts provenance attestations to navigate from images back to builds and source code
|
|
allowed-tools: Bash(cosign download:*), Bash(cosign verify:*), Bash(jq:*), Bash(~/.claude/skills/working-with-provenance/scripts/*:*)
|
|
---
|
|
|
|
# Working with Provenance
|
|
|
|
## Overview
|
|
|
|
Every Konflux build produces SLSA provenance attestations containing the complete build history: source repository, commit SHA, pipeline run URL, and build parameters. Use `cosign download attestation` with `jq` to extract this information and trace artifacts back to their origins.
|
|
|
|
## When to Use
|
|
|
|
Use this skill when you need to:
|
|
- Find build logs for an image (missing SBOM, failed tasks, debugging)
|
|
- Trace an image back to its source commit (what changed, code review)
|
|
- Verify which repository and commit produced an artifact (security, compliance)
|
|
- Extract build parameters or pipeline information (reproduce builds, debug configuration)
|
|
|
|
Do NOT use for non-Konflux images (Docker Hub, upstream images without attestations).
|
|
|
|
## Quick Reference
|
|
|
|
| Need | Command Pattern | Helper Script |
|
|
|------|----------------|---------------|
|
|
| Build log URL | `cosign download attestation $IMAGE \| jq '.payload \| @base64d \| fromjson \| .predicate.buildConfig.tasks[0].invocation.environment.annotations."pipelinesascode.tekton.dev/log-url"'` | `~/.claude/skills/working-with-provenance/scripts/build-log-link.sh $IMAGE` |
|
|
| Commit link | `cosign download attestation $IMAGE \| jq '.payload \| @base64d \| fromjson \| .predicate.buildConfig.tasks[0].invocation.environment.annotations \| ."pipelinesascode.tekton.dev/repo-url" + "/commit/" + ."pipelinesascode.tekton.dev/sha"'` | `~/.claude/skills/working-with-provenance/scripts/build-commit-link.sh $IMAGE` |
|
|
| Git repository | `cosign download attestation $IMAGE \| jq '.payload \| @base64d \| fromjson \| .predicate.buildConfig.tasks[0].invocation.environment.annotations."pipelinesascode.tekton.dev/repo-url"'` | `~/.claude/skills/working-with-provenance/scripts/build-git-repo.sh $IMAGE` |
|
|
| Origin pullspec | `cosign download attestation $IMAGE \| jq '.payload \| @base64d \| fromjson \| .subject[0].name + ":" + .predicate.buildConfig.tasks[0].invocation.environment.annotations."pipelinesascode.tekton.dev/sha"'` | `~/.claude/skills/working-with-provenance/scripts/build-origin-pullspec.sh $IMAGE` |
|
|
|
|
## Helper Scripts
|
|
|
|
This skill includes ready-to-use bash scripts that you can invoke directly:
|
|
|
|
```bash
|
|
# Extract build log URL
|
|
~/.claude/skills/working-with-provenance/scripts/build-log-link.sh quay.io/org/image:tag
|
|
|
|
# Extract commit URL (handles GitHub and GitLab)
|
|
~/.claude/skills/working-with-provenance/scripts/build-commit-link.sh quay.io/org/image:tag
|
|
|
|
# Extract git repository URL
|
|
~/.claude/skills/working-with-provenance/scripts/build-git-repo.sh quay.io/org/image:tag
|
|
|
|
# Extract original pullspec with commit SHA
|
|
~/.claude/skills/working-with-provenance/scripts/build-origin-pullspec.sh quay.io/org/image:tag
|
|
```
|
|
|
|
## Common Workflow
|
|
|
|
**Investigating missing SBOM:**
|
|
|
|
```bash
|
|
# 1. Get build log URL from provenance
|
|
LOG_URL=$(~/.claude/skills/working-with-provenance/scripts/build-log-link.sh quay.io/org/image:tag)
|
|
|
|
# 2. Open logs in browser or use debugging-pipeline-failures skill
|
|
echo $LOG_URL
|
|
```
|
|
|
|
**Tracing code changes:**
|
|
|
|
```bash
|
|
# 1. Get commit link from provenance
|
|
COMMIT=$(~/.claude/skills/working-with-provenance/scripts/build-commit-link.sh quay.io/org/image:tag)
|
|
|
|
# 2. View the commit
|
|
echo $COMMIT # Opens in browser
|
|
|
|
# 3. Check recent history
|
|
git clone $(~/.claude/skills/working-with-provenance/scripts/build-git-repo.sh quay.io/org/image:tag)
|
|
```
|
|
|
|
## Attestation Structure
|
|
|
|
Konflux provenance lives at:
|
|
```
|
|
.payload (base64-encoded)
|
|
└─ .predicate
|
|
├─ .buildConfig.tasks[0].invocation.environment.annotations
|
|
│ ├─ pipelinesascode.tekton.dev/log-url (pipeline logs)
|
|
│ ├─ pipelinesascode.tekton.dev/repo-url (git repository)
|
|
│ └─ pipelinesascode.tekton.dev/sha (commit SHA)
|
|
└─ .subject[0].name (image name)
|
|
```
|
|
|
|
## Common Mistakes
|
|
|
|
| Mistake | Fix |
|
|
|---------|-----|
|
|
| Trying to parse image tags for commit info | Tags can be arbitrary. Use provenance for definitive source. |
|
|
| Manual UI navigation to find logs | Use `build-log-link.sh` - faster and scriptable. |
|
|
| Assuming images without Konflux builds have provenance | Only Konflux-built images have SLSA attestations via Tekton Chains. |
|
|
| Forgetting to base64 decode payload | Always use `.payload \| @base64d \| fromjson` pattern. |
|
|
|
|
## Real-World Example
|
|
|
|
```bash
|
|
# User reports: "Build quay.io/redhat-user-workloads/konflux-ai-sig-tenant/llm-compressor-demo:7f9a553... missing SBOM"
|
|
|
|
# 1. Extract build log URL
|
|
$ ~/.claude/skills/working-with-provenance/scripts/build-log-link.sh quay.io/redhat-user-workloads/konflux-ai-sig-tenant/llm-compressor-demo:7f9a553dd100ba700fc8f9da942f8dfcecf6a1bd
|
|
https://konflux-ui.apps.kflux-prd-rh03.nnv1.p1.openshiftapps.com/ns/konflux-ai-sig-tenant/pipelinerun/llm-compressor-on-push-lvnc5
|
|
|
|
# 2. Extract source commit
|
|
$ ~/.claude/skills/working-with-provenance/scripts/build-commit-link.sh quay.io/redhat-user-workloads/konflux-ai-sig-tenant/llm-compressor-demo:7f9a553dd100ba700fc8f9da942f8dfcecf6a1bd
|
|
🐙 https://github.com/ralphbean/llm-compressor-hermetic-demo/commit/7f9a553dd100ba700fc8f9da942f8dfcecf6a1bd
|
|
|
|
# Now: Open logs to debug SBOM task, review commit for context
|
|
```
|
|
|
|
## Keywords
|
|
|
|
SLSA provenance, attestation, cosign, Tekton Chains, build logs, commit SHA, source tracing, artifact metadata, supply chain security, SBOM debugging, pipeline logs, container image verification
|