# 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)

```bash
# 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

```bash
# 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

```yaml
# .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

```yaml
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)

```yaml
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

```bash
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

```bash
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:  

```bash
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

```bash
# 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).   |

---