dsoxlab 0.1.0__tar.gz

dsoxlab-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,3 @@
+# Default owner for everything in the repository. Pull requests require a
+# review from a code owner (enforced by branch protection on `main`).
+* @stephrobert

dsoxlab-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+name: Bug report
+description: Report a defect in the dsoxlab CLI
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug. Please fill in the fields
+        below so we can reproduce and fix it quickly.
+        For security issues, do not open a public issue — see SECURITY.md.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: A clear description of the bug and what you expected instead.
+      placeholder: When I run `dsoxlab check ...`, it fails with ...
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      description: The exact commands, run from which directory / lab repository.
+      placeholder: |
+        1. cd ~/Projets/linux-training
+        2. dsoxlab run linux.depanner.service-crash-loop
+        3. ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: dsoxlab version
+      description: Output of `dsoxlab --version`.
+      placeholder: dsoxlab 0.1.0
+    validations:
+      required: true
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: Ubuntu 24.04 / Fedora 41 / ...
+    validations:
+      required: true
+  - type: dropdown
+    id: runtime
+    attributes:
+      label: Runtime involved
+      options:
+        - shell
+        - incus
+        - kvm
+        - not applicable
+    validations:
+      required: false
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / output
+      description: Relevant output. This will be rendered as code, no backticks needed.
+      render: shell
+    validations:
+      required: false

dsoxlab-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation and tutorials
+    url: https://blog.stephane-robert.info
+    about: Guides and lab walkthroughs on the author's blog.
+  - name: Security report
+    url: https://github.com/stephrobert/dsoxlab/security/advisories/new
+    about: Report a vulnerability privately instead of opening a public issue.

dsoxlab-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,36 @@
+name: Feature request
+description: Suggest an idea or improvement for dsoxlab
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Remember the golden rule: the engine stays domain-agnostic. Domain
+        logic belongs in a lab repository's contract, not in dsoxlab itself.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem to solve
+      description: What are you trying to do that is hard or impossible today?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: How could dsoxlab solve it? CLI command, contract field, runtime…
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false
+  - type: checkboxes
+    id: agnostic
+    attributes:
+      label: Domain-agnostic check
+      options:
+        - label: This request keeps the engine free of domain-specific logic.
+          required: true

dsoxlab-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+# Summary
+
+<!-- What does this PR change and why? -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Refactor
+- [ ] Documentation
+- [ ] Chore / tooling
+
+## Checklist
+
+- [ ] `uv run ruff check src/dsoxlab` passes
+- [ ] `uv run mypy src/dsoxlab` passes (strict)
+- [ ] `uv run pytest` passes
+- [ ] The engine stays domain-agnostic (no domain-specific logic in `src/dsoxlab/`)
+- [ ] New/changed user-facing strings are added to **both** `i18n/strings/en.py` and `i18n/strings/fr.py`
+- [ ] New/changed command or option is reflected in its `help=_()`, the i18n keys, and `fullhelp` (EN + FR)
+- [ ] `CHANGELOG.md` updated when behavior changes
+- [ ] Manually tested against at least one lab repository
+
+## Related issues
+
+<!-- e.g. Closes #123 -->

dsoxlab-0.1.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "chore(deps)"
+    # Wait before proposing a brand-new release: a compromised package is
+    # usually yanked within days, so a cooldown shrinks the exposure window.
+    cooldown:
+      default-days: 7
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "chore(ci)"
+    cooldown:
+      default-days: 7

dsoxlab-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,114 @@
+# Contribution gate. zizmor statically analyzes the workflows first, as a fast
+# security gate; the heavier jobs (quality matrix, CodeQL) only run once it
+# passes, so an insecure workflow fails fast without burning runners.
+#
+# Deeper CI/CD policy scanning and the compliance score live in plumber.yml
+# (trusted context only); supply-chain posture in scorecard.yml.
+#
+# Hardening baseline: every action is pinned to a full commit SHA, the default
+# token has no permissions, each job grants only what it needs, checkout never
+# persists credentials, and jobs are time-boxed.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Deny-by-default: jobs opt into the scopes they need, nothing is inherited.
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Fast security gate — the quality and CodeQL jobs depend on it.
+  zizmor:
+    name: Zizmor (workflow static analysis)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      # Gate-only (no SARIF upload) so the check also passes on pull requests
+      # from forks, where the token cannot write to code scanning. Findings in
+      # the Security tab come from CodeQL and plumber.yml on same-repo events.
+      - name: Zizmor
+        uses: zizmorcore/zizmor-action@192e21d79ab29983730a13d1382995c2307fbcaa # v0.5.7
+        with:
+          version: "1.26.1"
+          advanced-security: false
+
+  quality:
+    name: Lint, type-check and test (py${{ matrix.python-version }})
+    needs: zizmor
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+    env:
+      # Passed through the environment (not template-expanded into run blocks)
+      # so no context value is ever interpolated into shell code.
+      PYTHON_VERSION: ${{ matrix.python-version }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: "0.11.26"
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install "$PYTHON_VERSION"
+
+      - name: Sync dependencies (locked)
+        run: uv sync --frozen --python "$PYTHON_VERSION"
+
+      - name: Lint and security (ruff)
+        run: uv run ruff check src/dsoxlab tests
+
+      - name: Type-check (mypy strict)
+        run: uv run mypy src/dsoxlab
+
+      - name: Test (pytest)
+        run: uv run pytest
+
+  codeql:
+    name: CodeQL analyze (python)
+    needs: zizmor
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    permissions:
+      contents: read
+      security-events: write   # upload the CodeQL results to Code Scanning
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        with:
+          languages: python
+          build-mode: none   # Python is interpreted, no build step to observe
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        with:
+          category: "/language:python"

dsoxlab-0.1.0/.github/workflows/plumber.yml

@@ -0,0 +1,61 @@
+# Validates dsoxlab's own CI/CD with Plumber (getplumber.io): it analyzes the
+# repo's GitHub Actions workflows and repository settings against .plumber.yaml,
+# uploads findings to Code Scanning, publishes the compliance score to the
+# README badge, and fails below the threshold. The action verifies the
+# downloaded Plumber binary's SLSA build-provenance attestation before running.
+#
+# This workflow runs ONLY in trusted contexts (push to main, schedule, manual):
+# it needs a privileged token (Administration:read) to verify branch protection,
+# and that secret must never be exposed to pull_request runs — especially from
+# forks. Pull requests are gated for workflow security by zizmor in ci.yml,
+# which uses no secrets.
+name: Plumber compliance
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    - cron: '30 2 * * 1'
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  plumber:
+    name: Plumber analyze
+    # Skips while private (SARIF upload needs Advanced Security, free on public
+    # repos); activates automatically once the repo is public.
+    if: ${{ !github.event.repository.private }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    # The privileged token lives in this protected environment, which is
+    # restricted to the main branch — it is unreachable from pull_request runs.
+    environment: security
+    permissions:
+      contents: read
+      security-events: write   # upload SARIF to Code Scanning
+      actions: read            # read the workflow run for Plumber status
+      id-token: write          # OIDC to publish the score to score.getplumber.io
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Plumber compliance scan
+        uses: getplumber/plumber@fdd2a2d0555bb3b33cbb2efff3b955dea5a6bbf0 # v0.4.3
+        with:
+          version: "v0.4.3"
+          verify-attestation: "true"   # check the binary's SLSA provenance before running
+          threshold: "100"
+          upload-sarif: "true"
+          upload-artifacts: "true"
+          score-push: "true"           # publish the score to the README badge
+          # Fine-grained PAT (Administration + Contents + Metadata = Read),
+          # stored as an environment secret in the protected `security`
+          # environment, so branchMustBeProtected is verified for real.
+          github-token: ${{ secrets.PLUMBER_ADMIN_TOKEN }}

dsoxlab-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,93 @@
+# Publish dsoxlab to PyPI when a version tag (vX.Y.Z) is pushed.
+#
+# Security model:
+# - PyPI Trusted Publishing (OIDC). No API token or long-lived secret: the
+#   `publish` job mints a short-lived id-token that PyPI trusts. Configure the
+#   trusted publisher on PyPI (project: dsoxlab, workflow: release.yml,
+#   environment: pypi) before the first release.
+# - Privilege separation: `build` compiles the artifacts with read-only access
+#   and runs project code; `publish` runs no project code, only downloads the
+#   built artifacts and hands them to PyPI with `id-token: write`.
+# - The `pypi` GitHub Environment gates the publish step (add required
+#   reviewers / tag protection there for a manual approval before upload).
+# - Every action is pinned to a full commit SHA; the default token has no
+#   permissions; no build cache in the publishing path (cache-poisoning
+#   hardening).
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions: {}
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write       # mint the OIDC token used to sign the provenance
+      attestations: write   # record the SLSA build provenance for the artifacts
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
+        with:
+          version: "0.11.26"
+          enable-cache: false   # no cache in the publishing path (cache-poisoning hardening)
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      # SLSA build provenance for the wheel and sdist, verifiable with
+      # `gh attestation verify <artifact> --repo stephrobert/dsoxlab` or
+      # slsa-verifier. Complements the PEP 740 attestations PyPI records.
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
+        with:
+          subject-path: 'dist/*'
+
+      - name: Upload distribution artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 1
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/dsoxlab
+    permissions:
+      id-token: write   # OIDC token for Trusted Publishing — the only scope needed
+    steps:
+      - name: Download distribution artifact
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI (Trusted Publishing)
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          attestations: true
+          print-hash: true

dsoxlab-0.1.0/.github/workflows/scorecard.yml

@@ -0,0 +1,55 @@
+# OpenSSF Scorecard: measures the repository's supply-chain security posture
+# (branch protection, pinned dependencies, token permissions, code review, …)
+# and publishes the result to the public Scorecard viewer and the README badge.
+name: OpenSSF Scorecard
+
+on:
+  push:
+    branches: [main]
+  branch_protection_rule:
+  schedule:
+    - cron: '30 1 * * 1'
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    # Scorecard needs a public repository (commit-graph API + result
+    # publication). Skips while private (pre-launch); activates once public.
+    if: ${{ !github.event.repository.private }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      security-events: write   # upload SARIF to Code Scanning
+      id-token: write          # publish results to the OpenSSF Scorecard API
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Run Scorecard
+        uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+
+      - name: Upload SARIF to Code Scanning
+        uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        with:
+          sarif_file: results.sarif
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: scorecard-results
+          path: results.sarif
+          retention-days: 5

dsoxlab-0.1.0/.gitignore

@@ -0,0 +1,76 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtualenv
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.cache/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# OS
+Thumbs.db
+
+# Local agent / editor tooling (machine-specific, not for the public repo)
+.claude/
+CLAUDE.md
+
+# Task/todo scratch — never published
+todos/
+.todos/
+TODO/
+todo/
+
+# Build metadata
+*.egg-info/
+
+# dsoxlab — état runtime local (jamais versionné)
+.dsoxlab-context.json
+.dsoxlab.db
+
+# Terraform validate artefacts dans les templates packagés (non committables)
+src/dsoxlab/templates/terraform/*/.terraform/
+src/dsoxlab/templates/terraform/*/.terraform.lock.hcl