mcp-behaviour-guard 0.4.1__tar.gz

mcp_behaviour_guard-0.4.1/.env.example

@@ -0,0 +1,13 @@
+TENANT_A_TOKEN=tenant-a-token
+TENANT_B_TOKEN=tenant-b-token
+READ_ONLY_TOKEN=readonly-token
+ADMIN_TOKEN=admin-token
+
+TENANT_A_READER_TOKEN=replace-me
+TENANT_A_OPERATOR_TOKEN=replace-me
+TENANT_B_READER_TOKEN=replace-me
+TENANT_B_OPERATOR_TOKEN=replace-me
+TENANT_C_READER_TOKEN=replace-me
+
+DEMO_AGENT_TOKEN=local-demo-token
+MCP_GUARD_WEBHOOK=

mcp_behaviour_guard-0.4.1/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11.14'
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff format --check .
+      - run: ruff check .
+      - run: mypy src/mcp_behaviour_guard
+      - run: pytest
+
+  integration-demos:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11.14'
+          cache: pip
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e .
+      - name: Run STDIO security contract
+        env:
+          DEMO_AGENT_TOKEN: ci-fake-secret
+        run: mcp-guard run contracts/stdio-demo.yaml --lab-mode --no-fail --output reports-stdio --database .guard/stdio.db
+      - name: Run temporal metadata-drift demo
+        run: mcp-guard run contracts/temporal-demo.yaml --no-fail --output reports-temporal --database .guard/temporal.db
+      - name: Verify temporal drift was detected after repeated calls
+        run: |
+          python - <<'PY'
+          import json
+          from pathlib import Path
+
+          reports = list(Path("reports-temporal").glob("*/report.json"))
+          assert len(reports) == 1, f"expected one temporal report, got {len(reports)}"
+          payload = json.loads(reports[0].read_text(encoding="utf-8"))
+          finding = next(
+              item for item in payload["findings"]
+              if item["test_id"] == "TEMPORAL-METADATA-001"
+          )
+          assert finding["status"] == "failed", finding
+          assert finding["severity"] == "high", finding
+          assert finding["observed"]["first_drift"]["after_call"] == 3, finding
+          PY
+      - name: Start HTTP lab
+        run: docker compose up --build -d --wait
+      - name: Run HTTP security contract
+        run: mcp-guard run contracts/http-demo.yaml --lab-mode --no-fail --output reports-http --database .guard/http.db
+      - name: Verify reports exist
+        run: |
+          test -n "$(find reports-stdio -name index.html -print -quit)"
+          test -n "$(find reports-temporal -name index.html -print -quit)"
+          test -n "$(find reports-http -name index.html -print -quit)"
+      - if: always()
+        run: docker compose down -v
+
+  docker-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: false
+          platforms: linux/amd64,linux/arm64

mcp_behaviour_guard-0.4.1/.gitignore

@@ -0,0 +1,27 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+.env
+.guard/
+reports/
+baselines/
+baseline-diff.json
+demo_runtime/*
+!demo_runtime/.gitkeep
+dist/
+build/
+*.egg-info/
+*.db
+host-config-diff.json
+
+# Local validation evidence generated during demo/regression runs
+reports-temporal/
+reports-regression-http/
+reports-regression-stdio/
+reports-*/

mcp_behaviour_guard-0.4.1/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## 0.4.1 - 2026-09-17
+- Fix the duplicated Safety and limitations heading in the README.
+- Add package-index project links for the repository, issue tracker and changelog.
+- Modernize MIT license metadata to the SPDX/PEP 639 format.
+- Prepare package metadata for the initial PyPI publication.
+
+## 0.4.0 - 2026-09-16
+- Distinguish confirmed denials from failed connections and generic tool errors.
+- Require a working positive control before a negative authorization check passes.
+- Report observer outages and zero-effect replay runs as inconclusive.
+- Do not start replay or state-changing behaviour probes when required observers fail to start.
+- Omit raw invocation arguments and responses from exported traces and reports.
+- Expose the contract runner to Python callers and add a separate CLI runner image.
+- Keep MCP SDK v2 migration and PyPI publishing out of this patch.
+
+## 0.3.0
+
+- Removed the optional suggestion command and its external suggestion-service probe from the CLI.
+- Added persistent-session temporal-integrity checks with configurable re-tests per session.
+- Temporal drivers are contract-validated as reviewed read-only tools before execution.
+- Added deterministic fingerprints and before/after evidence for tool, prompt and resource metadata.
+- Added prompt payload probes and capture of MCP list-change notifications.
+- Added a harmless three-call sleeper demo that changes metadata without touching credentials or external services.
+- Added redacted MCP host-configuration snapshot/diff commands for supply-chain provenance checks, including additional server controls and VS Code-style sandbox/input blocks.
+- Added JSONC/JSON5-style parsing for common editor MCP configuration files.
+- Added CI coverage that verifies the temporal demo detects drift after the third call.
+- Kept the MCP Python SDK pinned at `1.28.1`; SDK 2.x / protocol 2026-07-28 subscription handling is intentionally left for a separately validated migration.
+
+
+## 0.2.0
+
+- Added first-class STDIO transport support.
+- Added a deliberately vulnerable local-agent MCP demonstration.
+- Added conservative contract draft generation from MCP discovery.
+- Added CSV and role-policy tenant compilation with per-tenant allow/deny exceptions.
+- Added deterministic path-boundary and inherited-secret response probes.
+- Added JSONL side-effect observation for controlled STDIO labs.
+- Added interval monitoring, high/critical webhook alerts and SQLite deduplication.
+- Improved HTML reports with critical-first rows, filtering and expandable evidence.
+- Added MCP configuration examples for local and editor-based clients.
+- Added macOS launchd and Ubuntu cron scheduling templates.
+- Added HTTP and STDIO integration checks to CI.
+
+## 0.1.0
+
+- Initial Streamable HTTP security-contract harness.
+- Authorization, tenant isolation, session isolation, side-effect, replay and baseline checks.
+- SQLite, HTML, JSON, JUnit and SARIF reporting.

mcp_behaviour_guard-0.4.1/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+## Local checks
+
+```bash
+python -m pip install -e '.[dev]'
+ruff format .
+ruff check .
+mypy src/mcp_behaviour_guard
+pytest
+```
+
+Exercise the demonstrations when changing clients, observers or engine behaviour:
+
+```bash
+make demo-stdio
+docker compose up --build -d
+make demo-http
+docker compose down -v
+```
+
+Keep pass/fail rules deterministic. Changes to security checks must remain reviewable and require normal code review.
+
+New checks should include:
+
+- a contract field or explicit test input;
+- an objective expected property;
+- reproducible observed evidence;
+- a unit test for pass and fail cases; and
+- a safety note when the check can change state.
+
+Do not submit real credentials, customer data or scan evidence from systems you are not authorized to test.

mcp_behaviour_guard-0.4.1/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.11.14-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+COPY demo ./demo
+RUN python -m pip install --upgrade pip && python -m pip install .
+
+RUN useradd --create-home --uid 10001 guard && \
+    mkdir -p /data /runtime && \
+    chown -R guard:guard /app /data /runtime
+USER guard
+
+CMD ["uvicorn", "demo.server.app:app", "--host", "0.0.0.0", "--port", "8000"]

mcp_behaviour_guard-0.4.1/Dockerfile.runner

@@ -0,0 +1,35 @@
+FROM python:3.11.14-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+RUN printf '%s\n' \
+    'Types: deb' \
+    'URIs: https://deb.debian.org/debian' \
+    'Suites: trixie trixie-updates' \
+    'Components: main' \
+    'Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg' \
+    '' \
+    'Types: deb' \
+    'URIs: https://security.debian.org/debian-security' \
+    'Suites: trixie-security' \
+    'Components: main' \
+    'Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg' \
+    > /etc/apt/sources.list.d/debian.sources && \
+    apt-get -o Acquire::Retries=5 update && \
+    DEBIAN_FRONTEND=noninteractive apt-get -y upgrade && \
+    rm -rf /var/lib/apt/lists/* && \
+    python -m pip install . && \
+    python -m pip uninstall -y wheel setuptools && \
+    useradd --create-home --uid 10001 guard && \
+    mkdir -p /work && \
+    chown guard:guard /work
+
+USER guard
+WORKDIR /work
+ENTRYPOINT ["mcp-guard"]
+CMD ["--help"]

mcp_behaviour_guard-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arjun Arjun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_behaviour_guard-0.4.1/Makefile

@@ -0,0 +1,35 @@
+.PHONY: install lint format test demo-up demo-down demo-http demo-stdio demo-temporal clean
+
+install:
+	python -m pip install -e '.[dev]'
+
+lint:
+	ruff format --check .
+	ruff check .
+	mypy src/mcp_behaviour_guard
+
+format:
+	ruff format .
+	ruff check --fix .
+
+test:
+	pytest
+
+demo-up:
+	docker compose up --build -d
+
+demo-down:
+	docker compose down -v
+
+demo-http:
+	mcp-guard run contracts/http-demo.yaml --lab-mode --no-fail
+
+demo-stdio:
+	DEMO_AGENT_TOKEN=local-demo-token mcp-guard run contracts/stdio-demo.yaml --lab-mode --no-fail
+
+demo-temporal:
+	mcp-guard run contracts/temporal-demo.yaml --no-fail
+
+clean:
+	rm -rf .guard reports reports-http reports-stdio reports-temporal baselines baseline-diff.json host-config-diff.json
+	find demo_runtime -type f ! -name .gitkeep -delete