csc-runner 0.5.0__tar.gz

csc_runner-0.5.0/.github/SECURITY_ADVISORY_TEMPLATE.md

@@ -0,0 +1,79 @@
+# Security Advisory Template
+
+## Summary
+
+<!-- One-sentence description of the vulnerability -->
+
+## Affected Versions
+
+<!-- Which versions are affected? -->
+
+- 0.x.y and earlier
+
+## Affected Components
+
+<!-- Check all that apply -->
+
+- [ ] Executor (`csc_runner/executor.py`)
+- [ ] Sandbox (`csc_runner/sandbox.py`)
+- [ ] Signing (`csc_runner/signing.py`)
+- [ ] Approval (`csc_runner/approval.py`)
+- [ ] Policy (`csc_runner/policy.py`)
+- [ ] Path enforcement (`csc_runner/pathutil.py`)
+- [ ] Resource limits (`csc_runner/limits.py`)
+- [ ] CLI (`csc_runner/cli.py`)
+- [ ] Schemas
+- [ ] Dockerfile / container image
+
+## Affected Modes
+
+- [ ] Local mode
+- [ ] Hardened mode
+- [ ] Both
+
+## Severity
+
+<!-- Critical / High / Medium / Low — see SECURITY.md for rubric -->
+
+## Bounded Production Claim Impact
+
+<!-- Does this issue block or weaken the bounded production claim?
+     High/critical issues block the claim until resolved.
+     Medium issues require an explicit acceptance note. -->
+
+- [ ] Blocks bounded production claim
+- [ ] Weakens claim (requires acceptance note)
+- [ ] No impact on claim
+
+## Description
+
+<!-- Detailed description of the vulnerability, including root cause -->
+
+## Impact
+
+<!-- What can an attacker do? What is the blast radius? -->
+
+## Reproduction
+
+<!-- Steps to reproduce, proof of concept, or test case -->
+
+## Fix
+
+<!-- Description of the fix, PR reference -->
+
+## Mitigation
+
+<!-- Workarounds available before applying the fix -->
+
+## Regression Test
+
+<!-- Reference to the regression test added for this vulnerability.
+     Required before closing the advisory. -->
+
+- Test file: <!-- e.g. tests/test_adversarial.py, tests/test_executor.py -->
+- Test name: <!-- e.g. test_vuln_123_path_traversal_regression -->
+- [ ] Regression test merged
+
+## Credit
+
+<!-- Reporter attribution (unless they request anonymity) -->

csc_runner-0.5.0/.github/SECURITY_RELEASE_TEMPLATE.md

@@ -0,0 +1,39 @@
+# Security Release Notes Template
+
+## Release vX.Y.Z — Security Fix
+
+### Security
+
+#### [SEVERITY] — Brief title
+
+**Advisory:** GHSA-xxxx-xxxx-xxxx
+
+**Affected versions:** 0.x.y and earlier
+
+**Affected component(s):** <!-- e.g. sandbox, signing, executor -->
+
+**Affected mode:** <!-- local / hardened / both -->
+
+**Bounded production claim impact:** <!-- blocks claim / weakens claim / no impact -->
+
+**Description:**
+
+<!-- 2-3 sentence description of the vulnerability and its impact, suitable for public disclosure. Do not include exploitation details beyond what is needed for users to assess their exposure. -->
+
+**Fix:**
+
+<!-- Brief description of what was changed to fix the vulnerability. -->
+
+**Mitigation for users who cannot upgrade immediately:**
+
+<!-- Workarounds, if any. "No workaround; upgrade required." if none. -->
+
+**Regression test:** <!-- e.g. tests/test_adversarial.py::test_vuln_123 -->
+
+**Credit:** <!-- Reporter attribution, or "Reported internally" -->
+
+---
+
+### Other Changes
+
+<!-- Non-security changes in this release, if any. -->

csc_runner-0.5.0/.github/dependabot.yml

@@ -0,0 +1,47 @@
+# Dependabot configuration
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates
+#
+# Notes:
+# - Docker entry watches root Dockerfile only. Add entries for subdirectory
+#   Dockerfiles if needed later.
+# - If update noise gets high, add groups to batch minor/patch updates.
+
+version: 2
+updates:
+  # Python dependencies (pip)
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "deps"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "ci"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci"
+
+  # Docker
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    commit-message:
+      prefix: "deps"
+    open-pull-requests-limit: 3
+    labels:
+      - "dependencies"
+      - "docker"

csc_runner-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Format check
+        run: ruff format --check .
+
+      - name: Test
+        run: python -m pytest tests/ -v

csc_runner-0.5.0/.github/workflows/hardened-tests.yml

@@ -0,0 +1,81 @@
+name: Hardened Integration Tests
+
+on:
+  push:
+    branches: [main, scaffold]
+  pull_request:
+    branches: [main, scaffold]
+
+permissions:
+  contents: read
+
+# This workflow runs:
+# 1. Standard tests on Linux (ubuntu-latest) across Python versions.
+#    Full platform matrix (Windows, macOS) belongs in ci.yml.
+# 2. Hardened integration tests inside the Docker container.
+#    The outer container runs as root with --privileged and AppArmor
+#    disabled so bwrap can create namespaces and configure loopback.
+#    Running as root is a CI-only requirement — bwrap --unshare-net
+#    needs CAP_NET_ADMIN to set up loopback in its network namespace.
+#    The product Dockerfile runs as non-root (csc-runner).
+#    Network isolation is enforced and tested by bwrap --unshare-net
+#    inside the sandbox — the primary hardened-mode boundary.
+#
+# Action versions are not yet pinned to SHA — that is a Stage 3 Step C task.
+
+jobs:
+  standard-tests:
+    name: Standard Tests (Linux)
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Run standard tests
+        run: python -m pytest --tb=short -q --ignore=tests/test_integration_hardened.py
+        timeout-minutes: 5
+
+  hardened-tests:
+    name: Hardened Integration Tests (Docker)
+    runs-on: ubuntu-latest
+    needs: standard-tests
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build hardened image
+        run: docker build -t csc-hardened .
+
+      - name: Verify sandbox tools available
+        run: |
+          docker run --rm --entrypoint bwrap csc-hardened --version
+          docker run --rm --entrypoint setpriv csc-hardened --version
+          docker run --rm --entrypoint prlimit csc-hardened --version
+
+      - name: Run hardened integration tests
+        run: |
+          docker run \
+            --rm \
+            --privileged \
+            --security-opt apparmor=unconfined \
+            --user 0 \
+            --entrypoint python \
+            -v ${{ github.workspace }}:/repo:ro \
+            -w /app \
+            csc-hardened \
+            -m pytest /repo/tests/test_integration_hardened.py -v --tb=short
+        timeout-minutes: 10

csc_runner-0.5.0/.github/workflows/release.yml

@@ -0,0 +1,173 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+# This workflow handles:
+# 1. Build wheel + sdist
+# 2. Dependency audit
+# 3. Generate SBOM from clean wheel install
+# 4. Publish to PyPI (trusted publishing — handles attestations)
+# 5. Sign release artifacts (sigstore) for GitHub release only
+# 6. Create GitHub release with signed artifacts + SBOM
+#
+# Prerequisites:
+# - PyPI trusted publishing configured for this repository
+#   (environment: pypi, package URL set)
+# - Repository has GitHub Actions allowed to create releases
+#
+# Action versions are not yet pinned to SHA — that is a follow-up task.
+
+jobs:
+  build:
+    name: Build Distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  audit:
+    name: Dependency Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install package and audit tool
+        run: |
+          pip install -e .
+          pip install pip-audit
+
+      - name: Run pip-audit
+        run: pip-audit
+
+  sbom:
+    name: Generate SBOM
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install wheel in clean environment
+        run: |
+          python -m venv sbom-env
+          sbom-env/bin/pip install dist/*.whl
+
+      - name: Generate CycloneDX SBOM
+        run: |
+          sbom-env/bin/pip install cyclonedx-bom
+          sbom-env/bin/cyclonedx-py environment \
+            --output sbom.json \
+            --output-format json
+
+      - name: Upload SBOM
+        uses: actions/upload-artifact@v4
+        with:
+          name: sbom
+          path: sbom.json
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build, audit]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/csc-runner
+    permissions:
+      id-token: write
+    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
+        with:
+          packages-dir: dist/
+
+  sign-for-release:
+    name: Sign Artifacts for GitHub Release
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Sign with sigstore
+        uses: sigstore/gh-action-sigstore-python@v3
+        with:
+          inputs: ./dist/*
+
+      - name: Upload signed artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-signed
+          path: dist/
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [publish-pypi, sign-for-release, sbom]
+    permissions:
+      contents: write
+    steps:
+      - name: Download signed artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-signed
+          path: dist/
+
+      - name: Download SBOM
+        uses: actions/download-artifact@v4
+        with:
+          name: sbom
+          path: .
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*
+            sbom.json
+          generate_release_notes: true

csc_runner-0.5.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+.python-version
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# Linting / type checking
+.ruff_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# CSC runtime output (root-level only, not test fixtures)
+/out/
+/receipts/

csc_runner-0.5.0/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-03-24
+
+### Added — Stage 1a (Protocol Complete)
+
+- Conformance test suite with golden fixtures (contracts, decisions, receipts)
+- Policy schema validation on load (`policy_schema_version` field)
+- Structured reason codes in PolicyDecision (ALLOW, COMMAND_NOT_ALLOWED, ARGV_PREFIX_DENIED, etc.)
+- Receipt field semantics: policy provenance, runner provenance, blocked vs failed distinction
+- Conditional receipt schema: success/failed require exit_code, stdout_hash, stderr_hash
+- Security targets, support matrix, compatibility matrix, canonicalization spec
+- PIC alignment RFC-0002 and mapping document
+- Reason-code registry (`docs/reason-codes.md`)
+
+### Added — Stage 1b (Hardened Defaults)
+
+- Resource exhaustion controls (`csc_runner/limits.py`): command count, argv size, pipeline depth, justification length, output capture caps
+- Filesystem path enforcement (`csc_runner/pathutil.py`): realpath resolution, symlink rejection, mixed-flavour fail-closed, glob prefix extraction
+- Popen-based executor with capped output capture, OS-pipe pipelines, ownership-based cleanup
+- Receipt integrity: hash-bound to contract, deterministic structure, truncation flags (stdout_truncated, stderr_truncated)
+- Adversarial test suite: shell escapes, path tricks, env leakage, timeout abuse, Unicode edge cases
+- Emergency deny-all policy mode
+- Policy provenance in receipts (policy_sha256, policy_schema_version)
+
+### Added — Stage 2 (First Hardened Mode)
+
+- Approval artifacts (`csc_runner/approval.py`): hash-bound to contract_sha256, expiry enforcement, temporal ordering, schema validation
+- Ed25519 receipt signing (`csc_runner/signing.py`): standalone `cryptography` library, CSC-native PublicKeyResolver protocol, authenticated signing metadata
+- Linux sandbox backend (`csc_runner/sandbox.py`): bubblewrap + setpriv + prlimit launcher, kernel-enforced namespace isolation, advisory command blocking
+- Hardened CLI: `--mode hardened`, `--sign`, `--signing-key`, `--key-id`, `--approval`, `--sandbox-debug`
+- `verify-receipt` CLI command
+- Executor integration: approval before sandbox, signing after execution, fail-closed on signing failure in hardened mode
+- In-memory approval consumption store with replay prevention (single-execution scope)
+- Dockerfile for hardened mode container image
+- End-to-end hardened integration tests (19 tests): filesystem boundaries, network isolation, no_new_privs, signed receipt verification
+- `docs/deployment-modes.md`: local vs hardened, security claims per mode
+- `docs/key-management.md`: rotation, revocation, CSC/PIC dependency boundary
+- `docs/policy-packs.md`: organizational conventions, not engine features
+- `cryptography` added as runtime dependency
+
+### Added — Stage 3 (Production Candidate)
+
+- Production readiness gate (`docs/production-readiness-gate.md`): formal checklist for bounded production claim
+- CI workflow for hardened integration tests (`.github/workflows/hardened-tests.yml`): Docker build, privileged container, bwrap `--unshare-net` for network isolation
+- Release workflow (`.github/workflows/release.yml`): sigstore signing, SBOM generation, PyPI trusted publishing
+- Security policy (`SECURITY.md`): severity rubric, SLA targets, disclosure process
+- Security advisory template (`.github/SECURITY_ADVISORY_TEMPLATE.md`)
+- Security release notes template (`.github/SECURITY_RELEASE_TEMPLATE.md`)
+- Dependabot configuration (`.github/dependabot.yml`): pip, GitHub Actions, Docker
+- Threat model (`docs/threat-model.md`): trust boundaries, 7 threat classes, known unsafe conditions
+- README updated to reflect hardened mode availability and bounded production claim
+- Branch protection on main: required status checks, PR review, no force push
+- Dependabot alerts, security updates, and private vulnerability reporting enabled
+
+### Changed
+
+- Version bumped from 0.1.0 to 0.5.0 to reflect protocol maturity
+- Receipt schema: conditional rules require exit_code/stdout_hash/stderr_hash for success/failed status
+- Executor signature: `run_contract()` accepts mode, approval, signing, and sandbox config
+- CLI: `run` command accepts hardened mode flags; `check` command unchanged
+
+## [0.1.0] - 2026-03-20
+
+### Added
+
+- Initial project scaffold
+- CSC v0.1 specification draft
+- JSON Schemas for CommandContract, PolicyDecision, ExecutionReceipt
+- Reference Python runner (`csc-runner`)
+- YAML policy profiles: dev-readonly, dev-test-no-network, regulated-restricted
+- Example contracts and receipts
+- RFC process with artifact integrity rules

csc_runner-0.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Code of Conduct
+
+## Our pledge
+
+We are committed to providing a friendly, safe, and welcoming environment for all contributors, regardless of experience level, gender identity, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project maintainers. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

csc_runner-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to CSC
+
+Thank you for your interest in contributing to the Command Scope Contract project.
+
+## Getting started
+
+1. Fork the repository
+2. Clone your fork
+3. Install dev dependencies: `pip install -e ".[dev]"`
+4. Create a feature branch: `git checkout -b my-feature`
+5. Make your changes
+6. Run checks: `make check`
+7. Submit a pull request
+
+## Where to start
+
+- Read the spec: `docs/spec-v0.1.md`
+- Review the schemas: `schemas/`
+- Look at example contracts: `examples/contracts/`
+
+## Code style
+
+This project uses [ruff](https://docs.astral.sh/ruff/) for linting and formatting.
+
+- `make lint` — check for issues
+- `make fmt` — auto-format
+
+## Tests
+
+Run the test suite with:
+
+```bash
+make test
+```
+
+All pull requests must pass CI before merging.
+
+## RFCs
+
+For changes to the protocol or significant design decisions, follow the RFC process described in `rfcs/RFC_PROCESS.md`.
+
+## Code of conduct
+
+Please follow our [Code of Conduct](CODE_OF_CONDUCT.md).