notify doctors work, audit work, new product advisory sprints

2026-01-13 08:36:29 +02:00
parent b8868a5f13
commit 9ca7cb183e
343 changed files with 24492 additions and 3544 deletions
--- a/docs/examples/binary-diff/ci-cd-integration.md
+++ b/docs/examples/binary-diff/ci-cd-integration.md
@@ -0,0 +1,371 @@
+# CI/CD Integration
+
+This example demonstrates how to integrate binary diff attestation into your CI/CD pipelines.
+
+## GitHub Actions
+
+### Basic Workflow
+
+```yaml
+# .github/workflows/binary-diff.yml
+name: Binary Diff Attestation
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  binary-diff:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # For keyless signing
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Stella CLI
+        uses: stellaops/setup-stella@v1
+        with:
+          version: 'latest'
+
+      - name: Login to Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Get Previous Tag
+        id: prev-tag
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          echo "tag=$PREV_TAG" >> $GITHUB_OUTPUT
+
+      - name: Binary Diff
+        if: steps.prev-tag.outputs.tag != ''
+        run: |
+          stella scan diff \
+            --base ghcr.io/${{ github.repository }}:${{ steps.prev-tag.outputs.tag }} \
+            --target ghcr.io/${{ github.repository }}:${{ github.ref_name }} \
+            --mode=elf \
+            --emit-dsse=./attestations/ \
+            --format=json > diff.json
+
+      - name: Upload Attestations
+        uses: actions/upload-artifact@v4
+        with:
+          name: binary-diff-attestations
+          path: |
+            attestations/
+            diff.json
+
+      - name: Attach Attestation to Image
+        run: |
+          # Using cosign to attach attestation
+          cosign attach attestation \
+            --attestation ./attestations/linux-amd64-binarydiff.dsse.json \
+            ghcr.io/${{ github.repository }}:${{ github.ref_name }}
+```
+
+### With Release Gate
+
+```yaml
+# .github/workflows/release-gate.yml
+name: Release Gate with Binary Diff
+
+on:
+  workflow_dispatch:
+    inputs:
+      base_version:
+        description: 'Base version to compare'
+        required: true
+      target_version:
+        description: 'Target version to release'
+        required: true
+
+jobs:
+  binary-diff-gate:
+    runs-on: ubuntu-latest
+    outputs:
+      verdict: ${{ steps.analyze.outputs.verdict }}
+
+    steps:
+      - name: Setup Stella CLI
+        uses: stellaops/setup-stella@v1
+
+      - name: Binary Diff Analysis
+        id: diff
+        run: |
+          stella scan diff \
+            --base myapp:${{ inputs.base_version }} \
+            --target myapp:${{ inputs.target_version }} \
+            --format=json > diff.json
+
+      - name: Analyze Results
+        id: analyze
+        run: |
+          # Check for unknown verdicts
+          UNKNOWN_COUNT=$(jq '.summary.verdicts.unknown // 0' diff.json)
+          if [ "$UNKNOWN_COUNT" -gt "0" ]; then
+            echo "verdict=review-required" >> $GITHUB_OUTPUT
+            echo "::warning::Found $UNKNOWN_COUNT binaries with unknown verdicts"
+          else
+            echo "verdict=approved" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Gate Decision
+        if: steps.analyze.outputs.verdict == 'review-required'
+        run: |
+          echo "Manual review required for unknown binary changes"
+          exit 1
+```
+
+## GitLab CI
+
+### Basic Pipeline
+
+```yaml
+# .gitlab-ci.yml
+stages:
+  - build
+  - analyze
+  - release
+
+variables:
+  STELLA_VERSION: "latest"
+
+binary-diff:
+  stage: analyze
+  image: stellaops/cli:${STELLA_VERSION}
+  script:
+    - |
+      # Get previous tag
+      PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+
+      if [ -n "$PREV_TAG" ]; then
+        stella scan diff \
+          --base ${CI_REGISTRY_IMAGE}:${PREV_TAG} \
+          --target ${CI_REGISTRY_IMAGE}:${CI_COMMIT_TAG} \
+          --mode=elf \
+          --emit-dsse=attestations/ \
+          --format=json > diff.json
+
+        # Upload to GitLab artifacts
+        echo "Binary diff completed"
+      else
+        echo "No previous tag found, skipping diff"
+      fi
+  artifacts:
+    paths:
+      - attestations/
+      - diff.json
+    expire_in: 30 days
+  only:
+    - tags
+```
+
+### With Security Gate
+
+```yaml
+# .gitlab-ci.yml
+security-gate:
+  stage: analyze
+  image: stellaops/cli:latest
+  script:
+    - |
+      stella scan diff \
+        --base ${CI_REGISTRY_IMAGE}:${BASE_VERSION} \
+        --target ${CI_REGISTRY_IMAGE}:${TARGET_VERSION} \
+        --format=json > diff.json
+
+      # Fail if any unknown verdicts
+      UNKNOWN=$(jq '.summary.verdicts.unknown // 0' diff.json)
+      if [ "$UNKNOWN" -gt "0" ]; then
+        echo "Security gate failed: $UNKNOWN unknown binary changes"
+        jq '.findings[] | select(.verdict == "unknown")' diff.json
+        exit 1
+      fi
+
+      echo "Security gate passed"
+  allow_failure: false
+```
+
+## Jenkins Pipeline
+
+```groovy
+// Jenkinsfile
+pipeline {
+    agent any
+
+    environment {
+        STELLA_VERSION = 'latest'
+    }
+
+    stages {
+        stage('Binary Diff') {
+            steps {
+                script {
+                    def prevTag = sh(
+                        script: 'git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo ""',
+                        returnStdout: true
+                    ).trim()
+
+                    if (prevTag) {
+                        sh """
+                            stella scan diff \\
+                                --base ${REGISTRY}/${IMAGE}:${prevTag} \\
+                                --target ${REGISTRY}/${IMAGE}:${TAG} \\
+                                --mode=elf \\
+                                --emit-dsse=attestations/ \\
+                                --format=json > diff.json
+                        """
+
+                        archiveArtifacts artifacts: 'attestations/*, diff.json'
+
+                        // Parse and check results
+                        def diff = readJSON file: 'diff.json'
+                        if (diff.summary.verdicts.unknown > 0) {
+                            unstable("Found ${diff.summary.verdicts.unknown} unknown binary changes")
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+## Azure DevOps
+
+```yaml
+# azure-pipelines.yml
+trigger:
+  tags:
+    include:
+      - v*
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+steps:
+  - task: Bash@3
+    displayName: 'Install Stella CLI'
+    inputs:
+      targetType: 'inline'
+      script: |
+        curl -sSL https://get.stellaops.io | sh
+        stella --version
+
+  - task: Docker@2
+    displayName: 'Login to Registry'
+    inputs:
+      containerRegistry: 'myRegistry'
+      command: 'login'
+
+  - task: Bash@3
+    displayName: 'Binary Diff'
+    inputs:
+      targetType: 'inline'
+      script: |
+        PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+        if [ -n "$PREV_TAG" ]; then
+          stella scan diff \
+            --base $(REGISTRY)/$(IMAGE):${PREV_TAG} \
+            --target $(REGISTRY)/$(IMAGE):$(Build.SourceBranchName) \
+            --mode=elf \
+            --emit-dsse=$(Build.ArtifactStagingDirectory)/attestations/ \
+            --format=json > $(Build.ArtifactStagingDirectory)/diff.json
+        fi
+
+  - task: PublishBuildArtifacts@1
+    inputs:
+      pathToPublish: '$(Build.ArtifactStagingDirectory)'
+      artifactName: 'binary-diff'
+```
+
+## Best Practices
+
+### 1. Always Use Digest References in Production
+
+```bash
+# Instead of tags
+stella scan diff --base myapp:v1.0.0 --target myapp:v1.0.1
+
+# Use digests for immutability
+stella scan diff \
+  --base myapp@sha256:abc123... \
+  --target myapp@sha256:def456...
+```
+
+### 2. Store Attestations with Releases
+
+Attach DSSE attestations to your container images or store them alongside release artifacts.
+
+### 3. Set Appropriate Timeouts
+
+```bash
+# For large images, increase timeout
+stella scan diff \
+  --base myapp:v1 \
+  --target myapp:v2 \
+  --timeout=600
+```
+
+### 4. Use Caching
+
+```yaml
+# GitHub Actions with caching
+- uses: actions/cache@v4
+  with:
+    path: ~/.stella/cache
+    key: stella-${{ runner.os }}-${{ hashFiles('**/Dockerfile') }}
+```
+
+### 5. Fail Fast on Critical Issues
+
+```bash
+# Exit code indicates issues
+stella scan diff --base old --target new --format=json > diff.json
+if [ $? -ne 0 ]; then
+  echo "Diff failed"
+  exit 1
+fi
+
+# Check for critical verdicts
+jq -e '.summary.verdicts.unknown == 0' diff.json || exit 1
+```
+
+## Troubleshooting
+
+### Registry Authentication
+
+```bash
+# Use Docker config
+stella scan diff \
+  --base myapp:v1 \
+  --target myapp:v2 \
+  --registry-auth=~/.docker/config.json
+```
+
+### Platform Issues
+
+```bash
+# Explicitly specify platform for multi-arch
+stella scan diff \
+  --base myapp:v1 \
+  --target myapp:v2 \
+  --platform=linux/amd64
+```
+
+### Timeout Issues
+
+```bash
+# Increase timeout for slow registries
+stella scan diff \
+  --base myapp:v1 \
+  --target myapp:v2 \
+  --timeout=900
+```