castops 0.3.0

CAST — DevSecOps governance toolkit for GitHub Actions and GitLab CI

CAST — CI/CD Automation & Security Toolkit

One engineer's standards. Every team's pipeline.

English | 中文

---

CAST is a DevSecOps governance toolkit for GitHub Actions and GitLab CI — so a single DevOps engineer can enforce pipeline standards across every team, without personally reviewing every repository.

Table of Contents

• Why CAST
• What You Get
• Quick Start
• CLI Reference
• Templates
• Pipeline Architecture
• Contributing
• License

---

Why CAST

The problem isn't that teams lack security tools. It's that one DevOps engineer's standards can't reach every team's pipeline.

The typical situation: a DevOps engineer defines a secure, policy-compliant pipeline for one project. Other teams write their own — often AI-generated, often untested against security standards, always "good enough to push." The DevOps engineer can't review every PR across every repository. Pipeline quality varies. Security gaps accumulate silently.

CAST is the governance layer that changes this. It's not "DevSecOps for teams with no DevOps expertise." It's "DevSecOps standards that enforce themselves — without your personal attention on every repository."

• Zero configuration — auto-detects your stack and CI platform, writes the workflow file
• Security-first — secrets scanning, SAST, SCA, and container scanning out of the box
• Policy as Code — OPA/conftest gate replaces fragile shell logic; policies are versioned
• Compliance dashboard — static HTML red/green board deployable to GitHub Pages
• Multi-platform — GitHub Actions and GitLab CI supported with identical security coverage

---

What You Get

Each CAST template configures your repository with a full security stack:

Layer	Tool	What It Does
Secrets Detection	Gitleaks	Scans entire git history for leaked credentials
SAST	Semgrep	Finds security bugs and anti-patterns in source code
SCA	pip-audit	Detects known vulnerabilities in dependencies
Container Security	Trivy	Scans Docker images for CVEs (skipped if no Dockerfile)
Code Quality	Ruff	Enforces code style and quality standards
Security Gate	conftest + OPA Rego	Policy-as-code gate; blocks merges on critical findings

All findings surface in GitHub's Security tab or GitLab's Security dashboard. No external accounts, no SaaS dependencies.

---

Quick Start

Option A — CLI (Recommended)

pip install castops
cast init

CAST auto-detects your project type and CI platform. One command. Done.

For GitLab CI:

cast init --platform gitlab

Option B — Manual

1. Copy the template for your stack:

curl -O https://raw.githubusercontent.com/castops/cast/main/src/cast_cli/templates/python/devsecops.yml

2. Move it to your repository:

mkdir -p .github/workflows
mv devsecops.yml .github/workflows/

3. Commit and push:

git add .github/workflows/devsecops.yml
git commit -m "ci: add CAST DevSecOps pipeline"
git push

Your pipeline is live. GitHub Actions will run all security checks on every push and pull request.

---

CLI Reference

The cast CLI is the fastest way to add a DevSecOps pipeline to any project.

Installation

pip install castops

Commands

cast init

Initialize a DevSecOps pipeline in the current directory.

Usage: cast init [OPTIONS]

  Initialize a DevSecOps pipeline for your project.

Options:
  -f, --force           Overwrite existing workflow file.
  -t, --type TEXT       Project type (python/nodejs/go). Auto-detected if omitted.
  -p, --platform TEXT   CI platform (github/gitlab). Auto-detected if omitted.
  --help                Show this message and exit.

Examples:

# Auto-detect project type and platform
cast init

# Specify project type explicitly
cast init --type nodejs

# Generate a GitLab CI pipeline
cast init --platform gitlab

# Go project on GitLab
cast init --type go --platform gitlab

# Overwrite an existing workflow
cast init --force

Auto-detection logic:

CAST detects your project type and CI platform by looking for marker files:

Project Type	Marker Files
Python	pyproject.toml, requirements.txt, setup.py, setup.cfg
Node.js	package.json
Go	go.mod

CI Platform	Detected by
GitLab	.gitlab-ci.yml exists
GitHub	.github/ directory exists (default)

cast version

Display the installed version of castops.

cast version
# cast 0.1.0

---

Templates

CAST ships with production-tested workflow templates for multiple stacks.

GitHub Actions

Stack	Security Tools	Status
Python	Gitleaks + Semgrep + pip-audit + Trivy + Ruff	✅ Available
Node.js	Gitleaks + Semgrep + npm audit + Trivy + ESLint	✅ Available
Go	Gitleaks + Semgrep + govulncheck + Trivy + staticcheck	✅ Available

GitLab CI

Stack	Security Tools	Status
Python	Gitleaks + Semgrep + pip-audit + Trivy + Ruff	✅ Available
Node.js	Gitleaks + Semgrep + npm audit + Trivy + ESLint	✅ Available
Go	Gitleaks + Semgrep + govulncheck + Trivy + staticcheck	✅ Available

Security Gate Policies

Policy	Blocks on	Activate via
default	CRITICAL findings	(default)
strict	HIGH + CRITICAL	CAST_POLICY=strict
permissive	Never (audit only)	CAST_POLICY=permissive

See docs/policy-reference.md for custom policy authoring.

---

Pipeline Architecture

Each CAST pipeline runs 5 parallel security jobs followed by 1 gate job that controls whether a pull request can be merged. The example below shows the Python pipeline; Node.js and Go pipelines follow the same structure with stack-appropriate tools.

┌─────────────────────────────────────────────────────────────┐
│                  CAST DevSecOps Pipeline                    │
│                                                             │
│  ┌──────────────┐  ┌──────┐  ┌─────┐  ┌───────────┐       │
│  │   Secrets    │  │ SAST │  │ SCA │  │ Container │       │
│  │  (Gitleaks)  │  │(Semgrep)│  │(pip-│  │  (Trivy)  │       │
│  │              │  │      │  │audit│  │           │       │
│  └──────┬───────┘  └──┬───┘  └──┬──┘  └─────┬─────┘       │
│         │             │         │            │             │
│         └─────────────┴────┬────┴────────────┘             │
│                            │                               │
│                    ┌───────▼────────┐                      │
│                    │ Security Gate  │                      │
│                    │ (blocks merge) │                      │
│                    └───────────────┘                      │
│                                                             │
│  ┌─────────────┐                                           │
│  │    Ruff     │  (runs independently, informational)      │
│  │  (Quality)  │                                           │
│  └─────────────┘                                           │
└─────────────────────────────────────────────────────────────┘

Trigger Conditions

The pipeline runs on:

Event	Branches
push	main, master
pull_request	main, master
workflow_dispatch	Any (manual trigger)

Security Gate Logic

The gate job runs after all security checks complete, regardless of individual job results:

IF secrets == "failure" OR sast == "failure" OR sca == "failure"
  → Block merge (exit 1)
ELSE
  → Allow merge (exit 0)

Code quality failures (Ruff) do not block merges by default. Adjust the gate job's needs array in the workflow to change this behavior.

SARIF Integration

All security findings (Semgrep, Trivy) are uploaded to GitHub's Security tab via SARIF. This means:

• All vulnerabilities are tracked as GitHub Security alerts
• Developers see findings inline on pull request diffs
• Security history is retained without any external tools

---

Requirements

• GitHub or GitLab repository with CI/CD enabled
• Python 3.9+ (for CLI usage)
• No additional accounts, tokens, or external services required

Optional: Set SEMGREP_APP_TOKEN as a secret to enable Semgrep's cloud dashboard and additional rulesets.

---

Security Dashboard

CAST can generate a static HTML compliance dashboard — red/green status per project, collapsible finding details, zero JavaScript dependencies.

python dashboard/generate.py --sarif-dir sarif-results --output index.html

Deploy to GitHub Pages with the included workflow:

templates/github/publish-dashboard.yml → .github/workflows/publish-dashboard.yml

See docs/dashboard-guide.md for setup instructions.

---

Documentation

Guide	Description
Getting Started	Step-by-step setup for your first pipeline
CLI Reference	Full cast command reference
Pipeline Reference	How each pipeline job works
GitLab Guide	GitLab CI setup and configuration
Policy Reference	Writing custom OPA/conftest policies
Plugin Guide	Extending CAST with custom security tools
Dashboard Guide	Security dashboard setup and GitHub Pages deployment

Chinese documentation: docs/zh/

---

Contributing

We welcome contributions. See CONTRIBUTING.md for details on:

• Development setup
• Adding new language templates
• Running tests
• Submitting pull requests

---

Security

To report a security vulnerability in CAST itself, see SECURITY.md.

---

Philosophy

One engineer's standards. Every team's pipeline.

CAST is the answer to a scaling problem: a single DevOps engineer cannot personally review every CI/CD pipeline across every team. CAST packages expert-validated standards as executable templates and policy gates — so the standard is enforced by the pipeline itself, not by PR review.

AI can generate a pipeline that runs. CAST enforces a pipeline that complies.

---

License

Apache 2.0 — see LICENSE for details.