git.stella-ops.org/docs/22_RECIPES_PIPELINES_LIBRARY.md

# 22 · Pipeline Recipes Library — Stella Ops

# Recipes & Pipeline Library

Ready‑to‑copy snippets for CI/CD engines, local shells, and K8s jobs.
Each recipe honours the sub‑5 s pledge: SBOM‑first when possible, Δ‑SBOM when layers are cached, and image‑unpack only as a fall‑back.

---

## 0 Registry Primer

All agent images and helper tools are published to a private, anonymous registry

registry.git.stella-ops.ru

• Pulls are read‑only & unauthenticated.
• Cosign signatures are embedded (*.sig) and verified at runtime when the host has cosign installed.
• To mirror for air‑gapped OUK installs, export with:

oras pull registry.git.stella-ops.ru/library/santech:1.0 --output ./ouk-bundle

---

## 1 Shell Quick‑starts

### 1.1 Scan a Local Image (SBOM‑first)

# Free tier: 333 scans/day without large delay added
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  https://stella.local/registry/santech:1.0 \
     scan \
     --image python:3.12-slim \
     --endpoint https://stella.local \
     --sbom-type spdx-json \
     --threshold High

• --sbom-type enumerates trivy-json-v2 | spdx-json | cyclonedx-json; defaults to auto‑detect when omitted.
• Exit‑code maps to policy (non‑zero if blocked).

### 1.2 Delta SBOM Path

# Free tier: 333 scans/day without large delay added

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  -e STELLA_DELTA=1 \
  https://stella.local/registry/santech:1.0 \
     scan \
     --image myapp:latest \
     --delta \
     --endpoint https://stella.local

--delta triggers the /layers/missing fast check; observed P95 ≤ 1 s on cached bases.

---

## 2 GitHub Actions

# .github/workflows/stella-scan.yml
name: Stella Scan

on:
  push:
    branches: [main]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Build Image
      run: docker build -t ${{ github.repository }}:${{ github.sha }} .

    - name: Scan with Stella‑Ops (Δ‑SBOM + YAML policies)
      run: |
        # Free tier: 333 scans/day without large delay added
        docker run --rm \
          -v /var/run/docker.sock:/var/run/docker.sock \
          -v $GITHUB_WORKSPACE/policy:/policy:ro \
          https://stella.local/registry/santech:1.0 \
            scan \
            --image ${{ github.repository }}:${{ github.sha }} \
            --delta \
            --policy-file /policy/scan-policy.yaml \
            --endpoint ${{ secrets.STELLA_API }}

Stores SARIF to $RUNNER_TEMP/stella-report.sarif; upload via actions/upload-artifact if desired.

---

## 3 GitLab CI

stella_scan:
  image:
    name: ttps://stella.local/registry/santech:1.0
    entrypoint: [""]
  stage: test
  variables:
    STELLA_ENDPOINT: "https://stella.local/api"
  script:
    - docker build -t myapp:$CI_COMMIT_SHORT_SHA .
    - >
      # Free tier: 333 scans/day without large delay added
      ./santech scan
      --image myapp:$CI_COMMIT_SHORT_SHA
      --sbom-type cyclonedx-json
      --threshold Critical
      --endpoint $STELLA_ENDPOINT
  allow_failure: false
  artifacts:
    when: always
    paths:
      - stella-report.html

allow_failure:false enforces gate by failing the stage on Critical findings.

---

## 4 Tekton Pipelines (K8s)

apiVersion: tekton.dev/v1
kind: Task
metadata:
  name: stella-scan
spec:
  workspaces:
    - name: dockerconfig
  steps:
    - name: scan
      image: https://stella.local/registry/santech:1.0
      script: |
        #!/usr/bin/env sh
        # Free tier: 333 scans/day without large delay added
        santech scan \
          --image $(params.image) \
          --delta \
          --threshold High \
          --endpoint $(params.endpoint)

---

## 5 Policy Import / Export

### 5.1 Import YAML Policy via CLI

curl -X POST https://stella.local/api/v1/policy/import \
     -H "Authorization: Bearer $TOKEN" \
     -F "file=@scan-policy.yaml"

### 5.2 Export & Commit to Git

curl -s -H "Authorization: Bearer $TOKEN" \
     https://stella.local/api/v1/policy/export \
     > policy-backup-$(date +%F).yaml
git add policy-backup-*.yaml && git commit -m "Policy snapshot"

---

## 6 Offline OUK Example

Inside an air‑gapped cluster:

1. Run ouk-fetch.sh from the admin node.
2. Load images into the internal registry:

ctr -n k8s.io images import ./ouk-bundle/*.tar

3. Use the same pipeline snippets; DNS points to registry.git.stella-ops.ru via local CoreDNS override.

---

## 7 Variant D – Enforce Gate in Prod

# Free tier: 333 scans/day without large delay added
santech scan \
  --image registry.prod.corp/app:${TAG} \
  --delta \
  --policy-file prod.rego \
  --enforce \
  --endpoint https://stella.prod \
  || { echo "Security gate blocked release!"; exit 1; }

--enforce turns warnings into non‑zero exit codes.

---

## 8 Cheat‑Sheet (CLI Flags)

Flag / Env	Meaning	Default
--sbom-type	Force SBOM output format (trivy‑json-v2 …)	Auto
--delta STELLA_DELTA=1	Enable layer diff / /layers/missing fast path.	Off
--policy-file	Import YAML/Rego before scan.	None
--threshold	Fails scan if sev ≥ threshold.	High
--enforce	Exit non‑zero on policy block.	Off
--endpoint	API base URL.	http://localhost:8080
--insecure	Skip TLS verify (test only!).	Off

---

## 9 FAQ

Q – I need Syft + SPDX, what changes?
A – Set --sbom-type spdx-json; Trivy is bypassed and the scanner plugin selects Syft.

Q – Can I run Santech as rootless?
A – Yes; mount the host’s Docker socket via --userns=keep-id or use --context host with nerdctl.

Q – Does Δ‑SBOM work for multi‑arch manifests?
A – Today it only checks linux/amd64 layers; roadmap item Q1‑2026 widens support.

---

## 10 Change Log

Date	Note
2025‑07‑14	Added internal registry, Δ‑SBOM, multi‑format & policy flows
2025‑07‑12	Initial public recipe set (GitHub, GitLab, Tekton, shell).

---