Initial commit

2025-11-30 08:35:26 +08:00
commit 3202054ccf
27 changed files with 628 additions and 0 deletions
--- a/SKILL.md
+++ b/SKILL.md
@@ -0,0 +1,115 @@
+---
+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