blc-ssh-mcp 0.6.1__tar.gz

blc_ssh_mcp-0.6.1/.dockerignore

@@ -0,0 +1,81 @@
+# Git and version control
+.git
+.gitignore
+.gitattributes
+
+# Python virtual environments and caches
+.venv
+venv
+ENV
+env
+__pycache__
+*.py[cod]
+*$py.class
+.Python
+*.egg-info/
+dist/
+build/
+
+# Testing and coverage
+tests/
+pytest.ini
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+.sublime-project
+.sublime-workspace
+
+# Development tools
+.claude/
+.claude_code/
+
+# CI/CD
+.github/
+.gitlab-ci.yml
+.travis.yml
+azure-pipelines.yml
+
+# Documentation and changelog
+docs/
+CHANGELOG.md
+CONTRIBUTING.md
+SECURITY.md
+PLAN.md
+
+# Logs and temporary files
+logs/
+*.log
+*.log.*
+tmp/
+temp/
+
+# Build artifacts
+*.tar.gz
+*.zip
+*.whl
+
+# Dependencies and lock files (handled by uv during build)
+# Note: pyproject.toml and uv.lock ARE copied and used
+node_modules/
+npm-debug.log
+yarn-error.log
+
+# SSH and sensitive files (use runtime volumes instead)
+.ssh/
+*.pem
+*.key
+config/servers.toml
+
+# Miscellaneous
+.env
+.env.local
+.env.*.local

blc_ssh_mcp-0.6.1/.github/workflows/audit.yml

@@ -0,0 +1,74 @@
+name: Scheduled Audit
+
+# Proactive advisory discovery, decoupled from PR activity.
+#
+# `pip-audit`'s input is the live OSV/PyPI advisory database, so its result is
+# a function of world-state rather than of any commit. Running it ONLY on
+# push/pull_request means a newly published CVE first surfaces as a red build
+# on whatever unrelated PR happens to be open — which is how a Dependabot
+# lockfile bump (PR #45) ended up blocked by an unrelated `click` advisory.
+#
+# This workflow adds a daily run against the default branch so new advisories
+# get discovered on their own schedule and can be remediated in a dedicated
+# PR. It does NOT replace either of the two commit-triggered `audit` jobs:
+#
+#   * ci.yml's `audit` runs on pushes to `main`, on `v*` tags, and on PRs
+#     targeting `main` — note that a push to a feature branch gets no audit at
+#     all — and unconditionally gates the GHCR image publish via
+#     `docker: needs: [test, lint, audit]`.
+#   * release.yml's `audit` runs on `v*` tags only and unconditionally gates
+#     the PyPI publish via `build: needs: [test, lint, audit]`; it is the audit
+#     that guards the release path.
+#
+# Note that blocking a PR *merge* on ci.yml's job additionally requires
+# `Dependency audit` to be listed in the repository's branch-protection
+# required checks — that is a settings change, not something either workflow
+# file can enforce. (release.yml deliberately names its audit job
+# `Dependency audit` as well, so the two are indistinguishable by name.)
+#
+# Caveat on the "proactive" claim: this workflow's only failure signal is a red
+# scheduled run on `main` — there is no notification step and no
+# .github/dependabot.yml — and GitHub disables `schedule:` triggers after 60
+# days of repository inactivity, silently, so on a quiet repo the daily gate
+# stops running with no signal at all.
+on:
+  schedule:
+    # 06:00 UTC daily. Cron in GitHub Actions is best-effort, not exact.
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+# Scheduled runs always use the default branch, so a `workflow_dispatch` on
+# `main` shares this group and cancels an in-flight scheduled audit. Harmless —
+# both runs do exactly the same thing.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  audit:
+    name: Scheduled dependency audit
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57  # v8.0.0
+        with:
+          version: "0.11.32"
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --locked --extra dev
+
+      - name: Audit dependencies
+        run: uv run pip-audit

blc_ssh_mcp-0.6.1/.github/workflows/ci.yml

@@ -0,0 +1,344 @@
+name: CI
+
+# Branches AND `v*` tags. The tag path is not a dry run: `PUBLISH` (docker job)
+# is true for it, so a tag push runs the full matrix and publishes a GHCR image
+# — concurrently with release.yml, which re-runs its own copies of test/lint/
+# audit on the same tag. release.yml's header comment and
+# tests/test_ci_lint_determinism.py both still describe ci.yml as branches-only.
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Unlike release.yml (`cancel-in-progress: false`, "never cancel a
+  # half-finished publish"), this cancels in flight — on the tag and main paths
+  # too, where the docker job is publishing.
+  cancel-in-progress: true
+
+permissions: {}
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57  # v8.0.0
+        with:
+          version: "0.11.32"
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked --extra dev
+
+      - name: Run tests
+        run: uv run python -m pytest tests/ -v --cov=ssh_mcp --cov-report=term-missing
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57  # v8.0.0
+        with:
+          version: "0.11.32"
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --locked --extra dev
+
+      # ruff and bandit come from the LOCKED dev env at a pinned version.
+      # `uvx` was used here previously; it floats to the newest release, so
+      # ruff 0.16.0's default-rule expansion (59 -> 413 on 2026-07-23) turned
+      # this job red on commits it had passed days earlier. See pyproject.toml
+      # [tool.ruff.lint] for the explicitly declared rule set.
+      #
+      # mypy also gates this job (below) but is NOT exactly pinned
+      # (`mypy>=1.15` in pyproject.toml); its determinism rests on uv.lock
+      # alone, not on the pin rationale above. Same blind spot in
+      # PINNED_LINT_TOOLS in tests/test_ci_lint_determinism.py.
+      - name: Check formatting with ruff
+        run: uv run ruff format --check src/ tests/
+
+      - name: Lint with ruff
+        run: uv run ruff check src/ tests/
+
+      - name: Type check with mypy
+        run: uv run mypy src/
+
+      - name: Security scan with bandit
+        run: uv run bandit -r src/ -q
+
+  # `pip-audit` lives in its own job rather than inside `lint` because its
+  # input is the LIVE advisory database, not the commit: a newly published
+  # CVE against any transitive dependency fails this job on every open PR at
+  # once. Keeping it separate makes that failure attributable instead of
+  # masquerading as a lint error.
+  #
+  # Two different guarantees, do not conflate them:
+  #   * The GHCR image publish is gated UNCONDITIONALLY — `docker` lists this
+  #     job in its `needs:` (see below), enforced by this workflow itself.
+  #   * Blocking a PR merge is enforced by BRANCH PROTECTION, not by this
+  #     file. Until `Dependency audit` is in the repository's required-checks
+  #     list, this job runs on every PR but does not block merging.
+  #
+  # A scheduled counterpart runs daily in audit.yml.
+  audit:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57  # v8.0.0
+        with:
+          version: "0.11.32"
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --locked --extra dev
+
+      - name: Audit dependencies
+        run: uv run pip-audit
+
+  docker:
+    name: Docker Build & Push
+    runs-on: ubuntu-latest
+    # `audit` is REQUIRED here. When pip-audit lived inside `lint` this
+    # dependency existed only implicitly; making it explicit is what keeps a
+    # known-vulnerable image from reaching GHCR. Do not remove it — a
+    # regression test asserts this list contains `audit`.
+    needs: [test, lint, audit]
+    permissions:
+      contents: read
+      packages: write
+      id-token: write        # sign the provenance attestation
+      attestations: write    # record it
+    env:
+      # Single source of truth for the PUBLISH path: build, scan, promote and
+      # attest all derive their reference from it, so those four steps cannot
+      # drift apart. The PR path deliberately stays out of the registry and
+      # hardcodes `ssh-mcp:ci` in its build and scan steps instead.
+      IMAGE: ghcr.io/${{ github.repository }}
+      # Publishing is the exception, not the default. PRs build + scan only.
+      PUBLISH: ${{ github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')) }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd  # v4
+
+      - name: Log in to GHCR
+        if: env.PUBLISH == 'true'
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121  # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Only this step's `tags` output is consumed (by promote + verify). Its
+      # `labels`/`annotations` outputs are computed and then used by nothing —
+      # the publish build passes no `labels:`, so published images carry none.
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051  # v5
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=sha
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      # -----------------------------------------------------------------------
+      # ONE build per path. On the publish path it goes straight to GHCR *by
+      # digest* — no tag is attached, so nothing in the registry is reachable by
+      # name until Trivy's CRITICAL gate has passed. PRs take the second step
+      # below, which loads the image locally instead. The two are independent
+      # BuildKit invocations with different exporters, NOT the same build — see
+      # test_docker_job_builds_exactly_once in
+      # tests/test_ci_lint_determinism.py for why that distinction matters.
+      #
+      # On the publish step provenance/sbom are disabled on purpose: BuildKit's
+      # inline attestations wrap the image in an index, which complicates
+      # digest promotion, and GHCR's Referrers API support for them is
+      # incomplete. GitHub Artifact Attestations (below) are meant to cover the
+      # same ground with a working verifier — but see the verify step: that
+      # attest step does not currently run. The PR step sets neither input; it
+      # never leaves the runner. (The CycloneDX SBOM is a release.yml artifact,
+      # not something this job produces or attests.)
+      # -----------------------------------------------------------------------
+      - name: Build image (publish path — push by digest, no tags)
+        id: build
+        if: env.PUBLISH == 'true'
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7
+        with:
+          context: .
+          outputs: type=image,name=${{ env.IMAGE }},push-by-digest=true,name-canonical=true,push=true
+          provenance: false
+          sbom: false
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Build image (PR path — local only)
+        id: build_local
+        if: env.PUBLISH != 'true'
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f  # v7
+        with:
+          context: .
+          push: false
+          load: true
+          tags: ssh-mcp:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      # -----------------------------------------------------------------------
+      # Scan the EXACT digest that was pushed. `${IMAGE}@sha256:…` is content-
+      # addressed: there is no tag in the reference, so nothing can have been
+      # substituted between the build step and this one.
+      #
+      # Scope of the gate, deliberately narrow: `severity: CRITICAL` only, so
+      # HIGH image findings never fail the build, and `ignore-unfixed` is unset.
+      # Open posture decision, tracked in docs/fixes/05-followups.md §3.
+      # -----------------------------------------------------------------------
+      - name: Scan published digest with Trivy
+        if: env.PUBLISH == 'true'
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25  # v0.36.0
+        with:
+          image-ref: ${{ env.IMAGE }}@${{ steps.build.outputs.digest }}
+          severity: CRITICAL
+          exit-code: 1
+          trivyignores: .trivyignore
+
+      - name: Scan local image with Trivy
+        if: env.PUBLISH != 'true'
+        uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25  # v0.36.0
+        with:
+          image-ref: ssh-mcp:ci
+          severity: CRITICAL
+          exit-code: 1
+          trivyignores: .trivyignore
+
+      # -----------------------------------------------------------------------
+      # Only now does a human-readable tag come into existence, and it is
+      # created FROM the scanned digest. No rebuild, no second BuildKit run.
+      # Mind the ordering: this step publishes the tags, and the verify step
+      # below only reports on them afterwards — a failing verify untags nothing.
+      # -----------------------------------------------------------------------
+      - name: Promote scanned digest to tags
+        if: env.PUBLISH == 'true'
+        env:
+          TAGS: ${{ steps.meta.outputs.tags }}
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          set -euo pipefail
+          TAG_ARGS=()
+          while IFS= read -r tag; do
+            [ -n "$tag" ] && TAG_ARGS+=(--tag "$tag")
+          done <<< "$TAGS"
+          docker buildx imagetools create "${TAG_ARGS[@]}" "${IMAGE}@${DIGEST}"
+
+      # Proof, in the job log, that every published tag serves the bytes Trivy
+      # cleared — nothing more.
+      #
+      # Production incident 2026-07-26: the original check compared
+      # `sha256sum` of `imagetools inspect --raw` against the build digest and
+      # failed on EVERY publish run, taking the attest step below down with it
+      # (images published between 2026-07-26 and this fix carry no provenance
+      # attestation). Confirmed cause: `imagetools create` does NOT reuse the
+      # source digest — it wraps the single-platform manifest in a NEW OCI
+      # index, so the tag's own digest legitimately differs from the scanned
+      # manifest's. Verified against the live registry: `:latest` was index
+      # sha256:8204263e… whose sole child was the scanned sha256:12db37ce…,
+      # and re-hashing those bytes reproduces 8204263e exactly.
+      # (Piping `inspect --raw` into `sha256sum` is separately fragile if the
+      # CLI appends a newline — not the cause here, but a reason not to go back
+      # to hashing stdout.)
+      #
+      # So compare the right thing: the set of image manifests the tag actually
+      # serves must be exactly {scanned digest}. Attestation manifests that
+      # buildx/attest may attach are excluded — they are metadata about the
+      # image, not another runnable image. Do not "simplify" this back to
+      # comparing the tag's own digest; that asserts an invariant the promote
+      # step deliberately does not hold.
+      - name: Verify every tag serves only the scanned digest
+        if: env.PUBLISH == 'true'
+        env:
+          TAGS: ${{ steps.meta.outputs.tags }}
+          DIGEST: ${{ steps.build.outputs.digest }}
+        run: |
+          set -euo pipefail
+          while IFS= read -r tag; do
+            [ -z "$tag" ] && continue
+            raw="$(docker buildx imagetools inspect --raw "$tag")"
+            # An index lists children under .manifests; a bare manifest has none.
+            served="$(printf '%s' "$raw" | jq -r '
+              if .manifests then
+                [ .manifests[]
+                  | select((.annotations["vnd.docker.reference.type"] // "")
+                           != "attestation-manifest")
+                  | .digest ] | join(" ")
+              else
+                empty
+              end')"
+            if [ -z "$served" ]; then
+              served="$(docker buildx imagetools inspect --format '{{.Manifest.Digest}}' "$tag")"
+            fi
+            echo "${tag} serves: ${served} (scanned ${DIGEST})"
+            for d in $served; do
+              if [ "$d" != "${DIGEST}" ]; then
+                echo "::error::${tag} serves ${d}, which is not the scanned digest ${DIGEST}" >&2
+                exit 1
+              fi
+            done
+            if [ -z "$served" ]; then
+              echo "::error::${tag} resolved to no image manifest at all" >&2
+              exit 1
+            fi
+          done <<< "$TAGS"
+
+      - name: Attest build provenance for the image
+        if: env.PUBLISH == 'true'
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373  # v4.1.1
+        with:
+          subject-name: ${{ env.IMAGE }}   # no tag — the digest identifies the subject
+          subject-digest: ${{ steps.build.outputs.digest }}
+          push-to-registry: true