mcp-warden-cli 1.0.0__tar.gz

mcp_warden_cli-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,75 @@
+name: 🐛 Bug report
+description: Report a defect in mcp-warden (NOT a security vulnerability)
+labels: ["bug", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ⚠️ **Do not report security vulnerabilities here.** If this is a way to
+        bypass a control mcp-warden claims to enforce (drift slips through, a real
+        secret is emitted unredacted, a poisoned result evades the block tier),
+        report it privately per [SECURITY.md](https://github.com/ernestprovo23/mcp-warden/blob/main/SECURITY.md).
+  - type: checkboxes
+    id: prechecks
+    attributes:
+      label: Pre-flight
+      options:
+        - label: This is a functional bug, not a security vulnerability.
+          required: true
+        - label: I searched existing issues and this is not a duplicate.
+          required: true
+        - label: I can reproduce this on the latest release or `main`.
+          required: true
+  - type: input
+    id: version
+    attributes:
+      label: mcp-warden version
+      description: Output of `mcp-warden --version`, or the commit SHA.
+      placeholder: "1.0.0"
+    validations:
+      required: true
+  - type: dropdown
+    id: command
+    attributes:
+      label: Which command?
+      options:
+        - pin
+        - check
+        - policy
+        - guard
+        - inspect
+        - other / not sure
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Reproduction
+      description: >
+        Exact command(s) and flags, plus a minimal MCP server fixture, `warden.lock`,
+        policy file, or `trace.jsonl` that reproduces it. **Strip or fake any real
+        secrets first.**
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: Include the full output / exit code. Redact anything sensitive.
+    validations:
+      required: true
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: OS, Python version, how you installed (uv / pip), and how you run tests.
+      placeholder: "macOS 14 / Python 3.11.8 / uv / .venv"
+    validations:
+      required: false

mcp_warden_cli-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 🔒 Report a security vulnerability
+    url: https://github.com/ernestprovo23/mcp-warden/security/advisories/new
+    about: "Security issues must be reported privately — do NOT open a public issue. See SECURITY.md."
+  - name: 📖 Documentation & threat model
+    url: https://github.com/ernestprovo23/mcp-warden/tree/main/docs
+    about: "Read the design specs and threat model before filing — some behaviors are explicitly out of scope."

mcp_warden_cli-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,52 @@
+name: 💡 Feature / new check request
+description: Propose a feature, or a new WRD-* / WRD-RES-* detection rule
+labels: ["enhancement", "triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        New checks are very welcome. mcp-warden blocks **only on deterministic
+        signals** (~0 false positives); heuristic/fuzzy detectors are accepted only
+        in the monitor (log-only) tier. Frame your proposal around a concrete threat.
+  - type: textarea
+    id: threat
+    attributes:
+      label: Threat / problem
+      description: What attack or failure does this address? Where does it appear (MCP surface, tool-result shape, CLI workflow)?
+    validations:
+      required: true
+  - type: dropdown
+    id: kind
+    attributes:
+      label: What are you proposing?
+      options:
+        - New static check (WRD-* — pin/check time)
+        - New result-inspection rule (WRD-RES-* — guard/inspect time)
+        - CLI / workflow feature
+        - Other
+    validations:
+      required: true
+  - type: dropdown
+    id: tier
+    attributes:
+      label: For a new check — deterministic or fuzzy?
+      description: Deterministic = can block (near-zero false positives). Fuzzy = monitor/log-only.
+      options:
+        - Deterministic (block-capable)
+        - Fuzzy (monitor / log-only)
+        - N/A — not a check
+    validations:
+      required: false
+  - type: textarea
+    id: detection
+    attributes:
+      label: Proposed detection / behavior
+      description: How would it match deterministically? What severity? Any false-positive risk and how you'd anchor against it?
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+    validations:
+      required: false

mcp_warden_cli-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,39 @@
+<!--
+Thanks for contributing to mcp-warden. mcp-warden is a security tool, so PRs are
+held to a determinism + specs-in-sync bar. See CONTRIBUTING.md.
+Do NOT use a PR to report a security vulnerability — follow SECURITY.md.
+-->
+
+## What & why
+
+<!-- What does this change do, and what problem does it solve? Link any issue. -->
+
+Closes #
+
+## Type of change
+
+- [ ] Bug fix (non-breaking)
+- [ ] New feature / check (non-breaking)
+- [ ] Breaking change (alters a hash, canonical form, rule verdict, or CLI contract)
+- [ ] Docs / specs only
+- [ ] CI / tooling
+
+## Checklist
+
+- [ ] **Tests pass** via the repo venv: `.venv/bin/python -m pytest -q` is green.
+- [ ] **Specs updated.** Any behavior change (hashing, canonicalization, the
+      `WRD-*` / `WRD-RES-*` catalogs, drift semantics, block posture, policy,
+      reserved error codes) updates the matching `docs/` spec in this same PR.
+- [ ] **Determinism preserved.** No unintended change to a digest, canonical form,
+      or rule verdict on an unchanged surface. If a hash change is intentional, it
+      is documented and the version is bumped.
+- [ ] **`guard` / `inspect` parity** holds for any result-rule change
+      (`tests/test_inspect_parity.py`).
+- [ ] **No secrets.** No real credentials anywhere; test fixtures use obviously-fake
+      placeholders (already allowlisted in `.gitleaks.toml`).
+- [ ] **Docs in sync.** README / CLI reference / `DOCUMENTATION_INDEX.md` updated if
+      user-facing behavior or flags changed.
+
+## Notes for reviewers
+
+<!-- Anything you want a reviewer to look at first; fixture/spec diffs welcome. -->

mcp_warden_cli-1.0.0/.github/dependabot.yml

@@ -0,0 +1,24 @@
+version: 2
+updates:
+  # Python dependencies declared in pyproject.toml.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+    commit-message:
+      prefix: "deps"
+
+  # GitHub Actions used by the CI workflows.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "ci"
+    commit-message:
+      prefix: "ci"

mcp_warden_cli-1.0.0/.github/workflows/action-test.yml

@@ -0,0 +1,147 @@
+name: Action self-test
+
+# Validates the composite mcp-warden-action against the fixture MCP servers
+# on all three supported runner OSes. Also runs a dedicated ubuntu job that
+# exercises the real SARIF upload path (requires security-events: write).
+#
+# Runs on every push/PR that touches the action itself or its fixtures.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "action.yml"
+      - "action/**"
+      - "tests/fixtures/**"
+      - ".github/workflows/action-test.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "action.yml"
+      - "action/**"
+      - "tests/fixtures/**"
+      - ".github/workflows/action-test.yml"
+
+jobs:
+  # --------------------------------------------------------------------------
+  # Matrix job: pass path + blocking proof on ubuntu / macos / windows.
+  # upload-sarif: false — the matrix legs do not have security-events: write.
+  # --------------------------------------------------------------------------
+  action-matrix:
+    name: "Action test (${{ matrix.os }})"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      # -----------------------------------------------------------------------
+      # Pass path: clean server vs committed lock — gate must exit 0.
+      # -----------------------------------------------------------------------
+      - name: "Pass path — clean server must exit 0"
+        id: pass-path
+        uses: ./
+        with:
+          server-cmd: "python tests/fixtures/clean_server.py"
+          lock: "tests/fixtures/clean.warden.lock"
+          sarif: "clean-check.sarif"
+          upload-sarif: "false"
+
+      - name: "Assert pass-path exit code is 0"
+        shell: bash
+        run: |
+          code="${{ steps.pass-path.outputs.exit-code }}"
+          if [ "$code" != "0" ]; then
+            echo "ERROR: pass path exit code was $code (expected 0)" >&2
+            exit 1
+          fi
+          echo "Pass path exited 0 — OK"
+
+      # -----------------------------------------------------------------------
+      # Blocking proof: mutated server vs same lock — gate must exit 1.
+      # continue-on-error: true so the job does not fail on the expected non-0.
+      # We then assert that the step outcome was 'failure' and exit-code == '1'.
+      # -----------------------------------------------------------------------
+      - name: "Blocking proof — mutated server must exit 1"
+        id: blocking-proof
+        uses: ./
+        continue-on-error: true
+        with:
+          server-cmd: "python tests/fixtures/mutated_server.py"
+          lock: "tests/fixtures/clean.warden.lock"
+          sarif: "mutated-check.sarif"
+          upload-sarif: "false"
+
+      - name: "Assert blocking-proof step failed with exit-code 1"
+        shell: bash
+        run: |
+          outcome="${{ steps.blocking-proof.outcome }}"
+          code="${{ steps.blocking-proof.outputs.exit-code }}"
+          if [ "$outcome" != "failure" ]; then
+            echo "ERROR: blocking-proof step outcome was '$outcome' (expected 'failure')" >&2
+            exit 1
+          fi
+          if [ "$code" != "1" ]; then
+            echo "ERROR: blocking-proof exit-code was '$code' (expected '1')" >&2
+            exit 1
+          fi
+          echo "Blocking proof step outcome=failure, exit-code=1 — gate is working correctly"
+
+  # --------------------------------------------------------------------------
+  # Dedicated upload job: ubuntu only, with security-events: write.
+  # Exercises the real SARIF upload path end-to-end against the clean fixture.
+  # --------------------------------------------------------------------------
+  action-upload-sarif:
+    name: "Action test (SARIF upload, ubuntu)"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: "Clean server — upload-sarif true (real upload path)"
+        id: upload-test
+        uses: ./
+        with:
+          server-cmd: "python tests/fixtures/clean_server.py"
+          lock: "tests/fixtures/clean.warden.lock"
+          sarif: "upload-test.sarif"
+          upload-sarif: "true"
+          category: "mcp-warden-action-test"
+
+      - name: "Assert upload-test exit code is 0"
+        shell: bash
+        run: |
+          code="${{ steps.upload-test.outputs.exit-code }}"
+          if [ "$code" != "0" ]; then
+            echo "ERROR: upload-test exit code was $code (expected 0)" >&2
+            exit 1
+          fi
+          echo "SARIF upload path exited 0 — OK"
+
+      - name: "Assert SARIF upload step succeeded"
+        shell: bash
+        env:
+          UPLOAD_OUTCOME: ${{ steps.upload-test.outputs['sarif-upload'] }}
+        run: |
+          # The composite action's sarif-upload step id is internal; we verify
+          # upload success by confirming the overall action step exited 0 (already
+          # asserted above) and that the SARIF file was produced and is non-empty.
+          sarif_path="${{ steps.upload-test.outputs.sarif }}"
+          if [ -z "$sarif_path" ] || [ ! -f "$sarif_path" ]; then
+            echo "ERROR: SARIF file not found at path '$sarif_path' — upload cannot have succeeded" >&2
+            exit 1
+          fi
+          sarif_size=$(wc -c < "$sarif_path")
+          if [ "$sarif_size" -eq 0 ]; then
+            echo "ERROR: SARIF file is empty — upload would have been rejected" >&2
+            exit 1
+          fi
+          echo "SARIF file present at $sarif_path (${sarif_size} bytes) and action exited 0 — upload confirmed OK"

mcp_warden_cli-1.0.0/.github/workflows/deps-locked.yml

@@ -0,0 +1,88 @@
+name: deps-locked
+
+# Proves mcp-warden "heals itself": its OWN dev/CI dependency closure installs
+# reproducibly from a fully hash-pinned lockfile (requirements-dev.lock). A
+# supply-chain integrity gate that ships unpinned transitive deps is
+# indefensible — this job is the standing evidence that we don't (issue #14,
+# conclave v1 must-do #4).
+#
+# What it asserts, in a CLEAN environment, on every push/PR:
+#   1. `pip install --require-hashes` accepts the committed lockfile end-to-end.
+#      --require-hashes makes pip REFUSE any artifact whose sha256 is not pinned,
+#      so a drifted or tampered transitive dep fails the job here.
+#   2. The lockfile is still in sync with pyproject.toml — we regenerate it with
+#      the documented `uv pip compile` command and fail if the committed file
+#      differs (catches "bumped pyproject, forgot to regenerate the lock").
+#   3. The package + its runtime/dev closure import from the locked set.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  deps-locked:
+    name: Hash-locked dev/CI install
+    runs-on: ubuntu-latest
+
+    steps:
+      # Pinned to the same full-SHA actions the rest of CI uses (test_workflow_pins.py
+      # enforces 40-char SHA + version comment on every `uses:`). Bump majors
+      # deliberately, never float tags — this is the supply-chain tool's own CI.
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.11"
+
+      # --------------------------------------------------------------------
+      # 1. Hash-verified install in a clean venv.
+      #    --require-hashes makes pip reject ANY package whose artifact hash is
+      #    not pinned in requirements-dev.lock, so transitive drift fails closed.
+      # --------------------------------------------------------------------
+      - name: Install dev/CI closure with --require-hashes
+        run: |
+          python -m venv /tmp/locked
+          /tmp/locked/bin/python -m pip install --upgrade pip
+          /tmp/locked/bin/python -m pip install --require-hashes -r requirements-dev.lock
+
+      # --------------------------------------------------------------------
+      # 2. Lockfile-in-sync check.
+      #    Regenerate with the SAME documented command and fail if the committed
+      #    lock drifted from pyproject.toml. Keeps the lock from silently rotting.
+      # --------------------------------------------------------------------
+      - name: Install uv (pinned)
+        run: python -m pip install "uv==0.6.16"
+
+      - name: Verify lockfile is in sync with pyproject.toml
+        run: |
+          uv pip compile --universal --generate-hashes --python-version 3.11 \
+            --extra dev pyproject.toml -o /tmp/requirements-dev.regenerated.lock
+          # Compare only the dependency body. The autogenerated header comment
+          # embeds the `-o` output path, which differs by construction (the CI
+          # run writes to /tmp), so we strip leading `#` comment lines before
+          # diffing. Pins, markers, and hashes are all in the body and are
+          # compared exactly.
+          if ! diff -u \
+               <(grep -v '^#' requirements-dev.lock) \
+               <(grep -v '^#' /tmp/requirements-dev.regenerated.lock); then
+            echo "::error::requirements-dev.lock is out of sync with pyproject.toml."
+            echo "Regenerate it (see SECURITY.md / CONTRIBUTING.md) and commit the result:"
+            echo "  uv pip compile --universal --generate-hashes --python-version 3.11 --extra dev pyproject.toml -o requirements-dev.lock"
+            exit 1
+          fi
+          echo "requirements-dev.lock is in sync with pyproject.toml."
+
+      # --------------------------------------------------------------------
+      # 3. The locked closure actually works — import the package + key deps.
+      # --------------------------------------------------------------------
+      - name: Import package + locked closure
+        run: |
+          /tmp/locked/bin/python -m pip install --no-deps -e .
+          /tmp/locked/bin/python -c "import mcp_warden; from mcp_warden import cli; import mcp, rfc8785, pydantic, typer, rich, yaml, anyio, pytest, hypothesis; print('OK: mcp_warden + hash-locked dev/CI closure import clean')"

mcp_warden_cli-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,81 @@
+name: Docs
+
+# Builds the mkdocs-material documentation site.
+#   - On every PR: `mkdocs build --strict` is the gate (no broken internal
+#     links, no warnings). It does NOT deploy.
+#   - On push to main: build, then deploy to GitHub Pages.
+#
+# All third-party actions are pinned to a full 40-char commit SHA with a version
+# comment (enforced by tests/test_workflow_pins.py).
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+# Least-privilege by default; the deploy job widens scope locally.
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # --------------------------------------------------------------------------
+  # Job 1: strict build — the PR gate. Runs on PRs and on main.
+  # Fails the build on any broken internal link or mkdocs warning.
+  # --------------------------------------------------------------------------
+  build:
+    name: mkdocs build --strict
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.11"
+
+      - name: Install mkdocs-material
+        run: pip install "mkdocs-material==9.7.6"
+
+      - name: Build site (strict)
+        run: mkdocs build --strict --site-dir site
+
+      - name: Upload Pages artifact
+        # Only needed on main, where the deploy job consumes it. Harmless on PRs
+        # (artifact is just not deployed), and keeps the build job self-contained.
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
+        with:
+          path: site
+
+  # --------------------------------------------------------------------------
+  # Job 2: deploy to GitHub Pages — only on push to main.
+  #
+  # NOTE: this requires GitHub Pages to be enabled for the repo with the
+  # "GitHub Actions" source (Settings -> Pages). Until that one-time enable is
+  # done, this job will fail on main but the PR gate (job 1) is unaffected.
+  # --------------------------------------------------------------------------
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Configure Pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
+
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5

mcp_warden_cli-1.0.0/.github/workflows/examples.yml

@@ -0,0 +1,95 @@
+name: Examples
+
+# Keeps examples/ honest:
+#   1. lint  — YAML-lint every example workflow so a broken copy-paste template
+#      can never merge.
+#   2. check — re-run `mcp-warden check` against each committed lock under
+#      examples/pinned-servers/ so the example locks stay green (a drifted
+#      upstream server or a stale lock fails this job).
+#
+# All third-party actions are pinned to a full 40-char commit SHA with a version
+# comment (enforced by tests/test_workflow_pins.py).
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # --------------------------------------------------------------------------
+  # Job 1: YAML-lint the example workflows.
+  # --------------------------------------------------------------------------
+  lint:
+    name: YAML lint example workflows
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.11"
+
+      - name: Install yamllint
+        run: pip install "yamllint==1.35.1"
+
+      # Lint the example workflow / CI / config YAML. The relaxed ruleset focuses
+      # on syntactic validity and basic hygiene rather than strict formatting,
+      # since these are copy-paste templates authored for readability.
+      - name: Lint example YAML
+        run: |
+          yamllint -d relaxed \
+            examples/github-actions \
+            examples/gitlab-ci \
+            examples/pre-commit
+
+  # --------------------------------------------------------------------------
+  # Job 2: re-check the committed example locks.
+  #
+  # Launches each real, openly-available server via its PINNED ref and verifies
+  # the committed warden.lock still matches the live surface. No paid creds, no
+  # secrets — every server is public.
+  # --------------------------------------------------------------------------
+  check-locks:
+    name: Re-check committed example locks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.11"
+
+      # Node provides npx for the @modelcontextprotocol/* servers.
+      - name: Set up Node 22
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "22"
+
+      - name: Install mcp-warden
+        run: pip install -e .
+
+      - name: "check: server-everything (npx, pinned @2026.1.26)"
+        run: |
+          mcp-warden check \
+            --lock examples/pinned-servers/server-everything/warden.lock \
+            --timeout 120 \
+            -- npx -y @modelcontextprotocol/server-everything@2026.1.26
+
+      - name: "check: server-memory (npx, pinned @2026.1.26)"
+        run: |
+          mcp-warden check \
+            --lock examples/pinned-servers/server-memory/warden.lock \
+            --timeout 120 \
+            -- npx -y @modelcontextprotocol/server-memory@2026.1.26
+
+      - name: "check: server-sequential-thinking (npx, pinned @2025.12.18)"
+        run: |
+          mcp-warden check \
+            --lock examples/pinned-servers/server-sequential-thinking/warden.lock \
+            --timeout 120 \
+            -- npx -y @modelcontextprotocol/server-sequential-thinking@2025.12.18