castops 0.2.1__tar.gz

castops-0.2.1/.github/workflows/deploy-website.yml

@@ -0,0 +1,44 @@
+# CAST — Deploy official website to GitHub Pages
+#
+# Triggers on push to main (website/ changes).
+# Serves website/ directory at https://castops.github.io/cast/
+
+name: Deploy Website
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'website/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

castops-0.2.1/.github/workflows/devsecops.yml

@@ -0,0 +1,148 @@
+# CAST — DevSecOps Pipeline for Python
+# https://github.com/castops/cast
+#
+# Includes:
+#   1. Secrets Detection  — Gitleaks
+#   2. SAST               — Semgrep
+#   3. SCA                — pip-audit
+#   4. Container Security — Trivy  (skipped if no Dockerfile)
+#   5. Code Quality       — Ruff
+#   6. Security Gate      — blocks merge on critical findings
+
+name: CAST DevSecOps
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write  # required for SARIF upload to GitHub Security tab
+  actions: read
+
+jobs:
+
+  # ── 1. Secrets Detection ───────────────────────────────────────────────────
+  secrets:
+    name: Secrets Detection
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          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
+          gitleaks version
+      - name: Gitleaks scan
+        run: gitleaks detect --source . --verbose --redact
+
+  # ── 2. SAST ────────────────────────────────────────────────────────────────
+  sast:
+    name: SAST
+    runs-on: ubuntu-latest
+    container:
+      image: semgrep/semgrep
+    steps:
+      - uses: actions/checkout@v4
+      - name: Semgrep scan
+        # SEMGREP_APP_TOKEN is optional — falls back to open-source rules
+        run: semgrep ci --sarif --output=semgrep.sarif || true
+        env:
+          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
+      - 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
+
+  # ── 3. SCA — Dependency Audit ──────────────────────────────────────────────
+  sca:
+    name: SCA
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+          cache: pip
+      - name: pip-audit
+        run: |
+          pip install pip-audit
+          pip-audit
+
+  # ── 4. Container Security ──────────────────────────────────────────────────
+  container:
+    name: Container Security
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check for Dockerfile
+        id: check_dockerfile
+        run: |
+          if [ -f Dockerfile ]; then
+            echo "found=true" >> $GITHUB_OUTPUT
+          else
+            echo "No Dockerfile found — skipping container scan"
+            echo "found=false" >> $GITHUB_OUTPUT
+          fi
+      - name: Build image
+        if: steps.check_dockerfile.outputs.found == 'true'
+        run: docker build -t cast-scan:${{ github.sha }} .
+      - name: Trivy scan
+        if: steps.check_dockerfile.outputs.found == 'true'
+        uses: aquasecurity/trivy-action@master
+        with:
+          image-ref: cast-scan:${{ github.sha }}
+          format: sarif
+          output: trivy.sarif
+          severity: CRITICAL,HIGH
+          exit-code: "0"  # gate handles blocking, not trivy directly
+      - 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
+
+  # ── 5. Code Quality ────────────────────────────────────────────────────────
+  quality:
+    name: Code Quality
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/ruff-action@v1
+
+  # ── 6. Security Gate ───────────────────────────────────────────────────────
+  gate:
+    name: Security Gate
+    runs-on: ubuntu-latest
+    needs: [secrets, sast, sca, quality]
+    if: always()
+    steps:
+      - name: Evaluate results
+        run: |
+          echo "secrets : ${{ needs.secrets.result }}"
+          echo "sast    : ${{ needs.sast.result }}"
+          echo "sca     : ${{ needs.sca.result }}"
+          echo "quality : ${{ needs.quality.result }}"
+
+          if [[ "${{ needs.secrets.result }}" == "failure" ||
+                "${{ needs.sast.result }}"    == "failure" ||
+                "${{ needs.sca.result }}"     == "failure" ]]; then
+            echo "❌ Security gate failed — merge blocked"
+            exit 1
+          fi
+
+          echo "✅ All checks passed — safe to merge"

castops-0.2.1/.github/workflows/publish.yml

@@ -0,0 +1,68 @@
+# CAST — Publish castops to PyPI
+#
+# Triggers on push of a version tag (e.g. v0.2.0).
+# Uses PyPI Trusted Publishing (OIDC) — no API token needed.
+#
+# One-time setup required on PyPI before first run:
+#   pypi.org → Manage account → Publishing → Add a new publisher
+#   Publisher: GitHub  |  Owner: castops  |  Repo: cast
+#   Workflow: publish.yml  |  Environment: pypi
+
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # setuptools-scm needs full history for version
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build sdist and wheel
+        run: |
+          # Strip leading 'v' from tag (v0.2.1 → 0.2.1) so PyPI gets a clean version.
+          # SETUPTOOLS_SCM_PRETEND_VERSION overrides the git-derived version entirely.
+          VERSION="${GITHUB_REF_NAME#v}"
+          SETUPTOOLS_SCM_PRETEND_VERSION="$VERSION" python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/castops/
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

castops-0.2.1/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+src/*.egg-info/
+dist/
+build/
+.eggs/
+.gstack/

castops-0.2.1/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to CAST are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Added
+
+- **Node.js and Go GitHub Actions templates** — production-ready pipelines for both stacks:
+  - Node.js: Gitleaks + Semgrep + npm audit + Trivy + ESLint + conftest gate
+  - Go: Gitleaks + Semgrep + govulncheck + Trivy + staticcheck + conftest gate
+- **GitLab CI templates** — full security parity with GitHub Actions for Python, Node.js, and Go:
+  - Use `cast init --platform gitlab` to generate a `.gitlab-ci.yml`
+  - Findings appear in GitLab's Security dashboard via SARIF artifact reports
+- **Policy as Code (OPA/conftest)** — the security gate now evaluates SARIF findings using
+  Rego policies instead of hardcoded shell logic:
+  - `policy/default.rego` — blocks on CRITICAL findings (default)
+  - `policy/strict.rego` — blocks on HIGH + CRITICAL
+  - `policy/permissive.rego` — audit only, never blocks merges
+  - Custom policies can be placed in a `policy/` directory alongside the workflow
+- **Static HTML security dashboard** — generate a compliance overview from SARIF results:
+  - `dashboard/generate.py`: parses SARIF files and renders a zero-dependency HTML page
+  - Red/green status per scan, collapsible finding details, commit SHA and timestamp
+  - Deploy to GitHub Pages with `templates/github/publish-dashboard.yml`
+- **`cast init --platform gitlab`** — the CLI now supports GitLab CI as a target platform
+- **Auto-detection of CI platform** — `cast init` detects `.gitlab-ci.yml` and `.github/`
+  to determine the platform automatically
+- **Chinese documentation** — full Chinese translation under `docs/zh/` and `README.zh.md`
+- **Test suite** — 65 tests covering project detection, template installation, dashboard
+  generation, and CLI behavior
+
+### Fixed
+
+- **Gitleaks in org repositories** — replaced the GitHub Action (requires paid org license)
+  with direct CLI installation from GitHub releases; works on all repositories for free
+- **SARIF upload without GitHub Advanced Security** — upload steps now use `continue-on-error`
+  so the pipeline does not fail when GHAS is not enabled on the repository
+- **Semgrep SARIF fallback** — added an "Ensure SARIF exists" step so the upload action
+  never fails when Semgrep exits non-zero without creating a SARIF file
+- **Auto-detection priority** — Go and Node.js are now detected before Python, so repositories
+  that use `pyproject.toml` only for tooling (Ruff, pre-commit) are not misidentified
+
+---
+
+## [0.1.0] — 2024-01-01
+
+### Added
+
+- **`cast` CLI** — new `castops` Python package installable via `pip install castops`
+  - `cast init` command: writes a DevSecOps workflow to `.github/workflows/devsecops.yml`
+  - `cast version` command: displays the installed package version
+  - Auto-detection of project type from marker files (`pyproject.toml`, `requirements.txt`, etc.)
+  - `--force` flag to overwrite existing workflow files
+  - `--type` flag to override auto-detection
+  - Rich terminal output with color-coded status messages
+- **Python DevSecOps template** — production-ready GitHub Actions workflow including:
+  - Secrets Detection via [Gitleaks](https://github.com/gitleaks/gitleaks) (full git history scan)
+  - SAST via [Semgrep](https://semgrep.dev) with SARIF upload to GitHub Security tab
+  - SCA via [pip-audit](https://pypi.org/project/pip-audit/) for vulnerable dependency detection
+  - Container Security via [Trivy](https://trivy.dev) (conditional on Dockerfile presence)
+  - Code Quality via [Ruff](https://docs.astral.sh/ruff/)
+  - Security Gate job that blocks merges on critical security failures
+- **Manual installation** support via `curl` for teams that prefer not to install the CLI
+
+### Technical Details
+
+- Python 3.9+ support
+- Templates embedded in the package via `importlib.resources` for offline use
+- MIT-compatible dependencies: [Typer](https://typer.tiangolo.com/) and [Rich](https://rich.readthedocs.io/)
+- Build system: `setuptools` + `setuptools-scm` (version from git tags)
+
+---
+
+## [0.0.1] — Initial Commit
+
+- Project scaffolding and initial Python workflow template
+- Apache 2.0 license
+
+---
+
+[Unreleased]: https://github.com/castops/cast/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/castops/cast/releases/tag/v0.1.0

castops-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,279 @@
+# Contributing to CAST
+
+Thank you for your interest in contributing to CAST. This document outlines the process
+for contributing code, templates, and documentation to the project.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Adding a New Template](#adding-a-new-template)
+- [Running Tests](#running-tests)
+- [Submitting a Pull Request](#submitting-a-pull-request)
+- [Release Process](#release-process)
+
+---
+
+## Code of Conduct
+
+This project follows a standard open-source code of conduct. Be respectful, constructive,
+and collaborative. Harassment of any kind will not be tolerated.
+
+---
+
+## Getting Started
+
+Before contributing, please:
+
+1. **Search existing issues** to avoid duplicates
+2. **Open an issue** for non-trivial changes to discuss the approach before writing code
+3. **Fork the repository** and create a feature branch from `main`
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.9 or higher
+- `git`
+
+### Install in Editable Mode
+
+```bash
+# Clone your fork
+git clone https://github.com/<your-username>/cast.git
+cd cast
+
+# Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+> If there is no `[dev]` extras group yet, install the base package with:
+> ```bash
+> pip install -e .
+> ```
+
+### Verify Installation
+
+```bash
+cast version
+```
+
+---
+
+## Project Structure
+
+```
+cast/
+├── src/
+│   └── cast_cli/
+│       ├── __init__.py
+│       ├── main.py          # CLI entry point — Typer app, all commands
+│       ├── detect.py        # Project type auto-detection
+│       ├── install.py       # Template fetching and writing
+│       └── templates/
+│           ├── python/devsecops.yml    # Embedded GitHub Actions templates
+│           ├── nodejs/devsecops.yml
+│           ├── go/devsecops.yml
+│           └── gitlab/
+│               ├── python/devsecops.yml  # Embedded GitLab CI templates
+│               ├── nodejs/devsecops.yml
+│               └── go/devsecops.yml
+├── templates/
+│   ├── python/devsecops.yml    # Source GitHub Actions templates
+│   ├── nodejs/devsecops.yml    # (must stay in sync with embedded copies above)
+│   ├── go/devsecops.yml
+│   ├── gitlab/
+│   │   ├── python/devsecops.yml  # Source GitLab CI templates
+│   │   ├── nodejs/devsecops.yml
+│   │   └── go/devsecops.yml
+│   └── github/
+│       └── publish-dashboard.yml   # GitHub Pages dashboard workflow
+├── dashboard/
+│   ├── generate.py         # SARIF → static HTML dashboard generator
+│   └── template.html       # Dashboard HTML/CSS template
+├── policy/
+│   ├── default.rego        # OPA policy: block on CRITICAL
+│   ├── strict.rego         # OPA policy: block on HIGH + CRITICAL
+│   └── permissive.rego     # OPA policy: audit only, never block
+├── docs/
+│   ├── getting-started.md
+│   ├── cli-reference.md
+│   ├── pipeline-reference.md
+│   ├── policy-reference.md
+│   ├── dashboard-guide.md
+│   ├── gitlab-guide.md
+│   └── zh/                 # Chinese documentation
+├── tests/
+│   ├── test_detect.py
+│   ├── test_install.py
+│   ├── test_dashboard.py
+│   └── test_cli.py
+├── pyproject.toml
+├── README.md
+├── README.zh.md
+├── CONTRIBUTING.md
+├── CHANGELOG.md
+└── SECURITY.md
+```
+
+### Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Templates are **embedded** in the package (`src/cast_cli/templates/`) | Ensures `cast init` works offline and without network calls at install time |
+| Templates also exist at **top-level** (`templates/`) | Allows direct `curl` access for manual installation without the CLI |
+| **Auto-detection** before explicit `--type` | Reduces friction for the happy path |
+| **`--force` flag** required to overwrite | Prevents accidental overwrites of customized workflows |
+
+---
+
+## Adding a New Template
+
+To add support for a new language or framework, follow these steps:
+
+### 1. Create the workflow template
+
+Create the file at both paths (they must be identical):
+
+```
+templates/<stack>/devsecops.yml
+src/cast_cli/templates/<stack>/devsecops.yml
+```
+
+A template must:
+
+- Follow the CAST naming convention (`name: CAST DevSecOps`)
+- Run on `push` and `pull_request` to `main`/`master`
+- Include at minimum: secrets detection, SAST, and SCA
+- Upload all SARIF results to GitHub Security tab
+- Include a `gate` job that blocks merges on critical failures
+
+Use the existing `templates/python/devsecops.yml` as a reference implementation.
+
+### 2. Register the marker files
+
+In `src/cast_cli/detect.py`, add your stack's marker files to the `MARKERS` dict.
+Order matters — entries listed first win in monorepos:
+
+```python
+MARKERS: dict[str, list[str]] = {
+    "go":     ["go.mod"],
+    "nodejs": ["package.json"],
+    "python": ["pyproject.toml", "requirements.txt", "setup.py", "setup.cfg"],
+    "<stack>": ["<marker-file>"],  # add your stack here
+}
+```
+
+### 3. Register the supported type
+
+In `src/cast_cli/install.py`, add your stack to the `SUPPORTED` set:
+
+```python
+SUPPORTED: set[str] = {"python", "nodejs", "go", "<stack>"}
+```
+
+### 4. Update documentation
+
+- Add the new stack to the **Templates** table in `README.md`
+- Add an entry in `CHANGELOG.md` under the appropriate version
+- Add the stack description to `SUPPORTED_TYPES` in `main.py`
+
+### 5. Test manually
+
+```bash
+# Create a temporary test directory with a marker file
+mkdir /tmp/test-<stack> && cd /tmp/test-<stack>
+touch <marker-file>
+
+# Run cast init and verify the workflow is created
+cast init
+cat .github/workflows/devsecops.yml
+```
+
+---
+
+## Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=cast_cli
+```
+
+> New contributions should include tests for any new detection logic, CLI behavior,
+> or template changes. The test suite covers `detect`, `install`, `dashboard`, and CLI.
+
+---
+
+## Code Style
+
+CAST uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting.
+
+```bash
+# Check for lint issues
+ruff check src/
+
+# Auto-fix issues
+ruff check --fix src/
+
+# Format code
+ruff format src/
+```
+
+All code must pass `ruff check` with no errors before a pull request can be merged.
+
+---
+
+## Submitting a Pull Request
+
+1. **Create a feature branch** from `main`:
+   ```bash
+   git checkout -b feat/nodejs-template
+   ```
+
+2. **Make your changes** following the guidelines in this document
+
+3. **Test your changes** manually and with the test suite
+
+4. **Update the changelog** in `CHANGELOG.md` under `[Unreleased]`
+
+5. **Push and open a PR** against `main`:
+   ```bash
+   git push origin feat/nodejs-template
+   ```
+
+### Pull Request Checklist
+
+- [ ] Changes are limited to a single concern
+- [ ] Code passes `ruff check` with no errors
+- [ ] Manual testing completed
+- [ ] `CHANGELOG.md` updated
+- [ ] Documentation updated (README, docstrings)
+
+---
+
+## Release Process
+
+Releases are managed by maintainers. The process:
+
+1. Update `CHANGELOG.md` — move items from `[Unreleased]` to a new version section
+2. Create and push a version tag: `git tag v0.x.0 && git push origin v0.x.0`
+3. `setuptools-scm` reads the tag to set the package version automatically
+4. The package is built and published to PyPI via CI
+
+---
+
+## Questions?
+
+Open a [GitHub Discussion](https://github.com/castops/cast/discussions) or file an
+[issue](https://github.com/castops/cast/issues).