Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions DOCUMENTATION_INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -328,4 +328,5 @@ review/signature CLI. Tests are `tests/test_artifact_trust.py`,

| Date | Change |
|------|--------|
| 2026-11-14 | Shipped DSE-718 in v2.3.0; normal company OIDC upload, matching GitHub/PyPI hashes, verified signatures/provenance and installed CLI smoke. See [release proof](RELEASING.md#normal-release-proof--2026-11-14). Manual fallback retained. README operator examples preserved in [archive](docs/archive/2026-11-14-readme-operations.md). |
| 2026-11-06 | Recorded TheDataExperts PyPI ownership, Active organization billing, normal company publisher and removal of the obsolete personal publisher; linked successful authentication-only run 42224199909. Account-wide token revoked; project-only manual fallback retained. No upload today; 2.2.0 unchanged and next normal release upload/provenance proof outstanding. |
37 changes: 9 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,10 @@ Hints are server claims, not proof of safety, and schemas do not certify content
operators can check production OIDC without uploading via [`RELEASING.md`](RELEASING.md).

`mcp-warden-cli` is owned by the [TheDataExperts PyPI organization](https://pypi.org/org/TheDataExperts/).
The company-repository publisher passed an authentication-only check on 2026-11-06;
that check uploaded no package. The next normal release must prove OIDC upload
and provenance; see the [publishing status](RELEASING.md#ownership-and-publishing-status--2026-11-06).
The normal [v2.3.0 release](https://github.com/DataScience-EngineeringExperts/mcp-warden/releases/tag/v2.3.0)
uploaded through the company Trusted Publisher, with matching GitHub/PyPI artifact
hashes, verified signatures and PyPI provenance. See the
[release proof](RELEASING.md#normal-release-proof--2026-11-14).

The proposed next direction is a protocol-neutral **Warden**: human-approved tool versions and bounded actions, with untrusted inputs kept separate from authority.
The [upgrade plan and checkpoint proposal](docs/plans/2026-10-02-tool-integrity-upgrade.md)
Expand Down Expand Up @@ -454,16 +455,8 @@ failure codes and `--require-consensus`.

## Policy (design-time only)

`policy` **lints** a YAML policy and **evaluates a single provided sample call**.
It does **not** intercept live calls — there is no runtime enforcement in v0.1
(deferred to v0.2). Fail-closed defaults: `shell_exec.allow=false`,
`http_request.deny_private=true` (SSRF ranges), `sql_query.allow_readonly_only=true`,
empty `allow_paths` = deny-all. See [`docs/POLICY_MODEL.md`](docs/POLICY_MODEL.md).

```bash
.venv/bin/mcp-warden policy eval policy.yaml ssrf_sample.json
# -> deny: host 169.254.169.254 is in deny_private range 169.254.0.0/16 (exit 1)
```
`policy` lints YAML and evaluates a supplied sample call; it does not intercept live calls.
See [the contract](docs/POLICY_MODEL.md) and [operator examples](docs/archive/2026-11-14-readme-operations.md#policy-design-time-only).

---

Expand All @@ -489,21 +482,9 @@ schemas in `warden.lock` and the SARIF output match them byte-for-byte.

## Tests

```bash
PATH="$PWD/.venv/bin:$PATH" .venv/bin/python -m pytest -q
```

The headline test is a real stdio round-trip: spawn the clean fixture → `pin` →
re-run `check` against the mutated fixture → assert non-zero exit + the expected
drift + SARIF finding.

The live runtime attack surface — the stdio JSON-RPC **framer**, the ANSI/control
**stripper**, the exfil-**domain** matcher, and the secret **redactor** — is
additionally **property-fuzzed** with [`hypothesis`](https://hypothesis.works/)
under `tests/fuzz/` (construction-based liveness + soundness properties: a
known-malicious input IS detected, and the parser never invents, leaks, or
misclassifies). The deep soak runs via `make fuzz`; see
[`CONTRIBUTING.md`](CONTRIBUTING.md#fuzzing).
Run `.venv/bin/python -m pytest -q`; see [test details](docs/archive/2026-11-14-readme-operations.md#tests)
and [fuzzing](CONTRIBUTING.md#fuzzing). Normalization additionally requires the
[actual-image qualification](docs/CONTENT_NORMALIZATION.md#qualification-and-rollback).

## Contributing & security

Expand Down
33 changes: 29 additions & 4 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,10 +67,35 @@ exchange; build, signing and upload jobs were skipped. This establishes authenti
not project upload permission or successful release publication.

The account-wide upload token was revoked. A `mcp-warden-cli`-only manual fallback
is retained pending the next normal release's successful OIDC upload and provenance
verification. It is not a workflow fallback. No upload or release was performed on
2026-11-06; the published version remains **2.2.0**. Keep the next-release proof
outstanding until section 2 confirms the new version and attestations.
remains retained and is not a workflow fallback. No upload or release was performed
on 2026-11-06; the published version was then **2.2.0**. The normal release below
now supplies upload/provenance proof. Retiring the fallback remains separately gated.

### Normal release proof — 2026-11-14

[v2.3.0](https://github.com/DataScience-EngineeringExperts/mcp-warden/releases/tag/v2.3.0)
was published from reviewed merge `8c8b59c58ff90402354187058f2e5e4b42fd49f0`.
[Release run 43605647867](https://github.com/DataScience-EngineeringExperts/mcp-warden/actions/runs/43605647867)
succeeded in build, production PyPI OIDC upload and Sigstore signing/self-verification.
GitHub release assets and [PyPI 2.3.0](https://pypi.org/project/mcp-warden-cli/2.3.0/)
contain identical package bytes:

| Artifact | SHA-256 |
|---|---|
| `mcp_warden_cli-2.3.0-py3-none-any.whl` | `fc1acd2ce66fb5e1b10697473bc7693a3b745478a7ac71a3cf39d5a1e2779146` |
| `mcp_warden_cli-2.3.0.tar.gz` | `7e1876bae5e7a936faf1c329dd85fb9d95169f1394f7040649c9ffec2c05d2ae` |

The [wheel provenance](https://pypi.org/integrity/mcp-warden-cli/2.3.0/mcp_warden_cli-2.3.0-py3-none-any.whl/provenance)
and [sdist provenance](https://pypi.org/integrity/mcp-warden-cli/2.3.0/mcp_warden_cli-2.3.0.tar.gz/provenance)
identify GitHub repository `DataScience-EngineeringExperts/mcp-warden`, workflow
`release.yml`, environment `null`. Release assets include their Sigstore bundles.
A fresh Linux Python 3.12 environment installed the downloaded wheel and exercised
the qualified worker: safe text exits 0, unknown MIME refuses with exit 2, an
encoded injection phrase is detected at its configured monitor tier, and a
synthetic token blocks with exit 1 while remaining redacted.

This proves a normal company-publisher release upload and installed CLI use.
It does not prove fallback-token retirement or whole-kernel conformance.

### New projects only — pending publisher

Expand Down
7 changes: 5 additions & 2 deletions SYSTEM_CONTEXT_DIAGRAM.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,8 +125,11 @@ flowchart LR
> the company-repository publisher subsequently passed the 2026-11-06
> authentication-only check ([run 42224199909](https://github.com/DataScience-EngineeringExperts/mcp-warden/actions/runs/42224199909)).
> `mcp-warden-cli` now belongs to the [TheDataExperts PyPI organization](https://pypi.org/org/TheDataExperts/).
> That authentication-only check uploaded no package. End-to-end OIDC upload
> and provenance require proof from the next normal release. See [`RELEASING.md`](RELEASING.md).
> The normal [v2.3.0 release run](https://github.com/DataScience-EngineeringExperts/mcp-warden/actions/runs/43605647867)
> subsequently built, OIDC-uploaded and Sigstore-signed the package. GitHub/PyPI
> artifact hashes match; PyPI provenance identifies the company repository and
> `release.yml`. The manual fallback remains retained; retirement is separate.
> See [`RELEASING.md`](RELEASING.md#normal-release-proof--2026-11-14).

---

Expand Down
38 changes: 38 additions & 0 deletions docs/archive/2026-11-14-readme-operations.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# README operator examples archived 2026-11-14

Preserved from the README to keep its overview bounded. Run the commands below
from the repository root.

## Policy (design-time only)

`policy` **lints** a YAML policy and **evaluates a single provided sample call**.
It does **not** intercept live calls — there is no runtime enforcement in v0.1
(deferred to v0.2). Fail-closed defaults: `shell_exec.allow=false`,
`http_request.deny_private=true` (SSRF ranges), `sql_query.allow_readonly_only=true`,
empty `allow_paths` = deny-all. See [`docs/POLICY_MODEL.md`](../POLICY_MODEL.md).

```bash
.venv/bin/mcp-warden policy eval policy.yaml ssrf_sample.json
# -> deny: host 169.254.169.254 is in deny_private range 169.254.0.0/16 (exit 1)
```

---

## Tests

```bash
PATH="$PWD/.venv/bin:$PATH" .venv/bin/python -m pytest -q
```

The headline test is a real stdio round-trip: spawn the clean fixture → `pin` →
re-run `check` against the mutated fixture → assert non-zero exit + the expected
drift + SARIF finding.

The live runtime attack surface — the stdio JSON-RPC **framer**, the ANSI/control
**stripper**, the exfil-**domain** matcher, and the secret **redactor** — is
additionally **property-fuzzed** with [`hypothesis`](https://hypothesis.works/)
under `tests/fuzz/` (construction-based liveness + soundness properties: a
known-malicious input IS detected, and the parser never invents, leaks, or
misclassifies). The deep soak runs via `make fuzz`; see
[`CONTRIBUTING.md`](../../CONTRIBUTING.md#fuzzing).

Loading