Add initial documentation
This commit is contained in:
245
docs/22_RECIPES_PIPELINES_LIBRARY.md
Normal file
245
docs/22_RECIPES_PIPELINES_LIBRARY.md
Normal file
@ -0,0 +1,245 @@
|
||||
# 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). |
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user