feat: cast audit, upgrade, org audit, and baseline profiles

.github/workflows/devsecops.yml

@@ -36,7 +36,7 @@
           fetch-depth: 0  # full history so Gitleaks can scan all commits
       - name: Install Gitleaks
         run: |
           curl -sSfL https://github.com/gitleaks/gitleaks/releases/download/v8.27.2/gitleaks_8.27.2_linux_x64.tar.gz \
             -o /tmp/gitleaks.tar.gz
           tar -xzf /tmp/gitleaks.tar.gz -C /tmp gitleaks
           sudo mv /tmp/gitleaks /usr/local/bin/gitleaks
@@ -60,11 +60,11 @@
       - name: Ensure SARIF exists
         if: always()
         run: |
           [ -f semgrep.sarif ] || echo '{"version":"2.1.0","$schema":"https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json","runs":[]}' > semgrep.sarif
       - name: Upload to GitHub Security tab
         uses: github/codeql-action/upload-sarif@v3
         if: always()
         continue-on-error: true  # requires GitHub Advanced Security; skip gracefully if not enabled
         with:
           sarif_file: semgrep.sarif
 
@@ -83,7 +83,7 @@
           pip install pip-audit
           pip install -e ".[dev]"
           # CVE-2026-4539: ReDoS in pygments AdlLexer — no fix released yet
           # (https://github.com/advisories/GHSA-5239-wwwm-4pmq); re-enable once patched
           pip-audit --ignore-vuln CVE-2026-4539
 
   # ── 4. Container Security ──────────────────────────────────────────────────
@@ -106,7 +106,7 @@
         run: docker build -t cast-scan:${{ github.sha }} .
       - name: Trivy scan
         if: steps.check_dockerfile.outputs.found == 'true'
-        uses: aquasecurity/trivy-action@master
+        uses: aquasecurity/trivy-action@v0.36.0
         with:
           image-ref: cast-scan:${{ github.sha }}
           format: sarif
@@ -116,7 +116,7 @@
       - name: Upload to GitHub Security tab
         if: steps.check_dockerfile.outputs.found == 'true'
         uses: github/codeql-action/upload-sarif@v3
         continue-on-error: true  # requires GitHub Advanced Security; skip gracefully if not enabled
         with:
           sarif_file: trivy.sarif
 
@@ -137,9 +137,9 @@
       - name: Install yamllint
         run: pip install yamllint
       - name: Lint workflow files
         # Templates embed shell heredocs whose content is intentionally at column 1
         # (required by bash heredoc syntax). GitHub Actions handles this correctly,
         # but yamllint's YAML parser reports false-positive syntax errors for such files.
         # Only lint pure workflow YAML files in .github/workflows/.
         run: yamllint -d relaxed .github/workflows/*.yml
 

README.md

@@ -177,6 +177,145 @@ CAST detects your project type and CI platform by looking for marker files:
 | GitLab | `.gitlab-ci.yml` exists |
 | GitHub | `.github/` directory exists (default) |
 
+#### `cast audit`
+
+Audit the current repo's pipeline against CAST baseline compliance.
+
+```
+Usage: cast audit [OPTIONS] [PATH]
+
+  Audit the current repo's pipeline against CAST baseline.
+
+Options:
+  --json      Output results as JSON.
+  --help      Show this message and exit.
+```
+
+**Examples:**
+
+```bash
+# Check current directory
+cast audit
+
+# Check a specific repository
+cast audit /path/to/repo
+
+# Machine-readable output
+cast audit --json
+```
+
+**Checks performed:**
+
+| Check | What it verifies |
+|-------|------------------|
+| Workflow file exists | `.github/workflows/*.yml` or `.gitlab-ci.yml` present |
+| Secrets scanning | Gitleaks or equivalent configured |
+| SAST | Semgrep, CodeQL, or equivalent configured |
+| Dependency scanning (SCA) | pip-audit, npm audit, govulncheck, etc. |
+| Container scanning | Trivy or equivalent configured |
+| Code quality | Ruff, ESLint, staticcheck, etc. |
+| SARIF upload | Findings uploaded to GitHub Security tab |
+| Security gate | conftest/OPA policy gate configured |
+| Action pinning (SHA) | GitHub Actions pinned by commit SHA |
+| Workflow permissions | Top-level permissions block declared |
+| OpenSSF Scorecard | Scorecard workflow integrated |
+| Branch protection | Informational only (requires GitHub API) |
+
+Exit codes: `0` = all checks passed, `1` = one or more checks failed.
+
+#### `cast upgrade`
+
+Check if your CAST workflow is up-to-date with the latest baseline template.
+
+```
+Usage: cast upgrade [OPTIONS] [PATH]
+
+  Check if your CAST workflow is up-to-date with the latest baseline.
+
+Options:
+  --diff      Show unified diff between current and baseline.
+  --help      Show this message and exit.
+```
+
+**Examples:**
+
+```bash
+# Check for drift
+cast upgrade
+
+# Show detailed diff
+cast upgrade --diff
+```
+
+Exit codes: `0` = up-to-date, `1` = drift detected or no workflow found.
+
+#### `cast org audit`
+
+Audit multiple repositories at once — the organization-level governance view.
+
+```
+Usage: cast org audit [OPTIONS] ORG_PATH
+
+  Organization-level governance: audit multiple repos at once.
+
+Options:
+  --json      Output results as JSON.
+  --help      Show this message and exit.
+```
+
+**Examples:**
+
+```bash
+# Scan a directory of repos
+cast org audit ~/my-org-repos/
+
+# JSON output for dashboards/CI
+cast org audit --json ~/my-org-repos/
+```
+
+Output table:
+
+| Repo | CAST installed | Security gate | Score |
+|------|---------------|---------------|-------|
+| repo-a | yes | yes | 92 |
+| repo-b | no | no | 34 |
+
+#### `cast profiles`
+
+List available baseline profiles for `cast init --profile`.
+
+```bash
+cast profiles
+```
+
+**Available profiles:**
+
+| Profile | Policy | Scorecard | SLSA | Use case |
+|---------|--------|-----------|------|----------|
+| `opensource` | permissive | — | — | Public open-source projects |
+| `enterprise` | strict | ✓ | ✓ | Enterprise with compliance requirements |
+| `strict` | strict | ✓ | — | Maximum security posture |
+| `ai-generated-code` | strict | ✓ | — | AI-generated codebases with extra checks |
+
+```bash
+cast init --profile enterprise
+```
+
+#### `cast init --profile`
+
+Initialize a pipeline with a pre-configured baseline profile.
+
+```bash
+# Enterprise: strict policy + Scorecard + SLSA
+cast init --profile enterprise
+
+# Open-source: permissive policy, minimal overhead
+cast init --profile opensource
+
+# AI-generated code: extra lint rules for generated code
+cast init --profile ai-generated-code
+```
+
 #### `cast version`
 
 Display the installed version of `castops`.
@@ -357,6 +496,20 @@ templates and policy gates — so the standard is enforced by the pipeline itsel
 
 AI can generate a pipeline that runs. CAST enforces a pipeline that complies.
 
+### CAST and OpenSSF Scorecard
+
+CAST is not another security scanner. It is the **enforcement layer** that translates industry
+standards into executable CI baselines:
+
+> **OpenSSF Scorecard tells you what is wrong. CAST helps you install and enforce the fix across CI/CD.**
+
+Scorecard evaluates open-source project security practices. CAST takes those findings — along with
+org-specific policies — and turns them into automated checks that run on every commit. Together,
+they provide full-cycle governance: Scorecard for assessment, CAST for enforcement.
+
+Use `cast init --profile enterprise` to install a baseline that includes OpenSSF Scorecard
+integration out of the box.
+
 ---
 
 ## License