246 lines
6.6 KiB
Markdown
246 lines
6.6 KiB
Markdown
# 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). |
|
||
|
||
---
|