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
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@ Streamable HTTP; the v0.3 `guard` proxy adds deterministic runtime *result* insp

### Fixed

- Both dependency locks pin `opentelemetry-api` 1.45.2 to address
GHSA-mf5v-w3w3-f6cg (quadratic-time traceparent parsing).
- `auth audit` accepts 26-character lowercase alphanumeric 1Password vault/item
IDs in exact `op://vault/item/field` references. Field and fragment token checks
and checks for other URI schemes and filesystem paths remain in force (DSE-2124).
- `check` no longer passes when `overall_digest` differs but no per-entry drift fires
(e.g. a baseline lock with duplicate tool/resource/prompt keys): it now reports
`digest-mismatch-unexplained` (high) and exits non-zero (DSE-2125).
Expand Down
5 changes: 3 additions & 2 deletions DOCUMENTATION_INDEX.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Documentation Index — mcp-warden

Last Updated: 2026-11-06
Last Updated: 2026-11-14

Master index of every document in this repository. The `docs/` files are the
**security contract and source of truth** for all algorithms; the three core docs
Expand Down Expand Up @@ -47,10 +47,11 @@ is the MCP auth posture sound. Both reuse the `check` exit-code contract (0 clea
| [`src/mcp_warden/deploy_gate.py`](src/mcp_warden/deploy_gate.py) | `WRD-GATE-*` engine: eval thresholds, guardrail presence, budget, approval receipt |
| [`src/mcp_warden/cli_deploy_gate.py`](src/mcp_warden/cli_deploy_gate.py) | `deploy-gate` command body (register idiom) |
| [`src/mcp_warden/auth_audit.py`](src/mcp_warden/auth_audit.py) | `WRD-AUTH-*` static config audit; reuses `checks_secret.scan_field` for vendor patterns (vendor hits are never downgraded); template fill-me-ins are `WRD-AUTH-PLACEHOLDER-SECRET` (low), matched on whole tokens |
| [`src/mcp_warden/auth_refs.py`](src/mcp_warden/auth_refs.py) | Reference / locator / placeholder heuristics behind `WRD-AUTH-*`: `${VAR}` forms, secret-manager URIs and credential paths, token-shaped segments (incl. `-`/`_`-joined tokens, DSE-1540), placeholder bounds |
| [`src/mcp_warden/auth_refs.py`](src/mcp_warden/auth_refs.py) | Reference / locator / placeholder heuristics behind `WRD-AUTH-*`: `${VAR}` forms, secret-manager URIs and credential paths, token-shaped segments (incl. `-`/`_`-joined tokens, DSE-1540), position-scoped 1Password IDs (DSE-2124), placeholder bounds |
| [`src/mcp_warden/cli_auth.py`](src/mcp_warden/cli_auth.py) | `auth audit` sub-app command body |
| [`tests/test_deploy_gate.py`](tests/test_deploy_gate.py) | Engine per-control pass/fail + CLI exit codes + fail-closed on malformed evidence |
| [`tests/test_auth_audit.py`](tests/test_auth_audit.py) | Every rule, the deliberate non-flags (loopback, `${VAR}` refs, stdio), redaction, CLI/JSON/SARIF |
| [`tests/test_auth_refs_op_ids.py`](tests/test_auth_refs_op_ids.py) | 1Password ID references and field, fragment, scheme, length, case and malformed-path regression controls (DSE-2124) |
| [`tests/test_agent_gates_examples.py`](tests/test_agent_gates_examples.py) | Pins the shipped examples to the per-server verdicts their README claims, so a rule change cannot silently make the docs wrong; also asserts the planted fake credentials never reach a finding field |
| [`examples/agent-gates/`](examples/agent-gates/) | Runnable demos — a 6-server config (4 flagged / 2 deliberately clean, incl. the `Bearer ${VAR}` embedded-reference shape from #94) and pass/fail deploy evidence, with expected verdicts documented and verified |

Expand Down
6 changes: 3 additions & 3 deletions action/requirements.lock
Original file line number Diff line number Diff line change
Expand Up @@ -231,9 +231,9 @@ mdurl==0.1.2 \
--hash=sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8 \
--hash=sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba
# via markdown-it-py
opentelemetry-api==1.45.1 \
--hash=sha256:aa38ed19bcc084ba42782a73255b3582283eced7ad6dddbd6695189e69adfb75 \
--hash=sha256:b31553efa588ae44bc306f863c785c5333a9ecc091248c6ee68b4b6c87fdedfb
opentelemetry-api==1.45.2 \
--hash=sha256:2cbd737377e710ee740d261c94e93fa0f08e6d037c18f17513cc0a2d94479a34 \
--hash=sha256:d7b0008e21e5fd61cbe7a7f34ca3b6905a78ab677d9bc395e299359c75cda6b4
# via mcp
pycparser==3.0 ; implementation_name != 'PyPy' and platform_python_implementation != 'PyPy' \
--hash=sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29 \
Expand Down
10 changes: 9 additions & 1 deletion docs/AGENT_GATES.md
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,15 @@ follows, each bound pinned by a test with a sub-threshold bypass string:
empty, itself a reference (recursively), or itself a placeholder.**
`${TOKEN:-9f8e7d6c5b4a}` and `${T:-${U:-hunter2!}}` are committed credentials
wearing a reference; `${VAR:?msg}` stays a reference.
- **Locators need >= 2 segments and no token-shaped segment.** Token-shaped is
- **Locators need >= 2 segments and no token-shaped segment**, except that an
`op://vault/item/field` reference with exactly three nonempty slash-separated
segments may use 26-character lowercase `[a-z0-9]` IDs in its vault and item
positions (DSE-2124). The field and any fragment retain the token checks;
IDs under other URI schemes or filesystem paths receive no exemption.
Only those validated vault/item IDs are masked for the whole-value entropy
pass; vendor patterns still scan the original reference, and the field,
fragment and named segments still receive entropy checks.
Token-shaped is
an alphanumeric-only segment that is 20+ characters, or 16+ at >= 3.5 bits/char,
or 16+ mixed-case (`Passw0rdPassw0rd`). A segment with a dot is judged piece
by piece: its plain alphanumeric pieces are a stem and an extension
Expand Down
45 changes: 45 additions & 0 deletions docs/plans/2026-11-14-op-reference-ids.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# 1Password Reference IDs Implementation Plan

> **For Claude:** Implement and verify each task in order; retain the scoped security review.

**Goal:** Recognize 1Password vault/item IDs without exempting credential literals elsewhere.

**Architecture:** Keep generic locator checks unchanged. Add a scheme- and
position-scoped exception, then mask validated IDs only for auth audit's entropy
scan; retain vendor-pattern scanning over the original value.

**Tech Stack:** Python, pytest, Ruff; all execution on the AWS builder.

---

### Task 1: Reproduce the false positive

Files: `tests/test_auth_refs_op_ids.py`.

1. Add valid vault/item ID references and negative twins for fields, fragments,
other schemes, lengths, case, query strings and malformed paths.
2. Run `PYTHONPATH=src .venv/bin/pytest -q tests/test_auth_refs_op_ids.py` on the
builder. Expected before the fix: valid-ID cases fail, negative controls pass.

### Task 2: Implement the scoped exception

Files: `src/mcp_warden/auth_refs.py`, `src/mcp_warden/auth_audit.py`.

1. Recognize `[a-z0-9]{26}` only in vault/item slots of a valid three-part `op://`
reference. Keep field and fragment checks and generic locator logic.
2. Mask only validated IDs for entropy evaluation. Keep original-value vendor
matches, and retain entropy checks outside the ID positions.
3. Run the new matrix plus `tests/test_auth_audit.py` and `tests/test_doctor.py`.
Expected: all pass. Run Ruff over both modules and the new test module.

### Task 3: Verify and prepare review

Files: `docs/AGENT_GATES.md`, `DOCUMENTATION_INDEX.md`, `CHANGELOG.md`.

1. Document the exact exception and entropy/vendor boundaries; verify the core
README and system diagram retain their accurate static-audit architecture.
2. Run the full pytest coverage suite and lint on the builder, then GitHub CI.
3. Obtain independent CSO review on the exact commit and open the scoped PR.

Rollback: revert the isolated change. No credentials, dependencies, network
access, transport semantics or release version changes are part of this work.
6 changes: 3 additions & 3 deletions requirements-dev.lock
Original file line number Diff line number Diff line change
Expand Up @@ -391,9 +391,9 @@ mdurl==0.1.2 \
--hash=sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8 \
--hash=sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba
# via markdown-it-py
opentelemetry-api==1.45.1 \
--hash=sha256:aa38ed19bcc084ba42782a73255b3582283eced7ad6dddbd6695189e69adfb75 \
--hash=sha256:b31553efa588ae44bc306f863c785c5333a9ecc091248c6ee68b4b6c87fdedfb
opentelemetry-api==1.45.2 \
--hash=sha256:2cbd737377e710ee740d261c94e93fa0f08e6d037c18f17513cc0a2d94479a34 \
--hash=sha256:d7b0008e21e5fd61cbe7a7f34ca3b6905a78ab677d9bc395e299359c75cda6b4
# via mcp
packaging==26.2 \
--hash=sha256:5fc45236b9446107ff2415ce77c807cee2862cb6fac22b8a73826d0693b0980e \
Expand Down
7 changes: 6 additions & 1 deletion src/mcp_warden/auth_audit.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
from pathlib import Path
from typing import Any

from .auth_refs import _looks_like_placeholder, _looks_like_secret_ref
from .auth_refs import _looks_like_placeholder, _looks_like_secret_ref, _mask_op_ids_for_entropy
from .checks_secret import scan_field
from .models import Finding
from .redact import redact_secret
Expand Down Expand Up @@ -104,6 +104,11 @@ def _scan_mapping_for_literals(mapping: dict[str, Any], target: str) -> list[Fin
# credential no matter how it is dressed up, and is never downgraded to
# a placeholder or excused as a reference.
vendor = scan_field(value, target)
entropy_value = _mask_op_ids_for_entropy(value)
if entropy_value != value:
vendor = [f for f in vendor if f.rule_id != "WRD-SEC-ENTROPY"] + [
f for f in scan_field(entropy_value, target) if f.rule_id == "WRD-SEC-ENTROPY"
]
if _is_auth_key(key) and (vendor or not _looks_like_secret_ref(value)):
if not vendor and _looks_like_placeholder(value):
# A template's fill-me-in slot is a real (low) finding — shipping
Expand Down
34 changes: 31 additions & 3 deletions src/mcp_warden/auth_refs.py
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
"""Reference, locator and placeholder heuristics for the WRD-AUTH-* audit.

Split out of :mod:`mcp_warden.auth_audit` (DSE-1540). The only behaviour change
is the separator-token rule in :func:`_tokenish_segment` and its use on URI
fragments and ``:?`` messages. Everything here
Split out of :mod:`mcp_warden.auth_audit` (DSE-1540). Includes separator-token
checks on locators, fragments and ``:?`` messages, plus position-scoped
1Password vault/item ID recognition (DSE-2124). Everything here
answers one question about a config value: does it carry a credential, or
only point at / stand in for one?
"""
Expand Down Expand Up @@ -104,6 +104,8 @@ def _text_carries_a_token(text: str) -> bool:
_SECRET_URI = re.compile(
r"^(?:op|vault|awssm|gcpsm|azkv|secretref|keyring|pass)://(\S+)$", re.IGNORECASE
)
#: Only vault/item positions in an exact three-part ``op://`` path may use IDs.
_ONEPASSWORD_ID = re.compile(r"[a-z0-9]{26}")
#: A filesystem path pointing at a credential file. Every branch (``~/``, ``./``,
#: ``../``, ``/``, ``C:\``) needs >= 2 path-safe segments, none token-shaped, so a
#: base64 blob that happens to start with ``/`` stays a literal.
Expand All @@ -124,11 +126,37 @@ def _is_secret_locator(v: str) -> bool:
path, _, fragment = m.group(1).partition("#")
if fragment and (not _PATH_SEGMENT.fullmatch(fragment) or _text_carries_a_token(fragment)):
return False # `#key` names a field; `#9f8e…` carries the secret
segments = path.split("/")
if v[:5].lower() == "op://" and len(segments) == 3:
return all(
_PATH_SEGMENT.fullmatch(seg)
and (index < 2 and _ONEPASSWORD_ID.fullmatch(seg) or not _tokenish_segment(seg))
for index, seg in enumerate(segments)
)
return _segments_are_a_locator(path)
m = _PATH_PREFIX.match(v)
return bool(m) and _segments_are_a_locator(v[m.end():])


def _mask_op_ids_for_entropy(value: str) -> str:
"""Remove only validated op vault/item IDs from the entropy scan input.

Vendor-pattern scanning must still use the original value. The field,
fragment and named segments remain available to the entropy heuristic.
"""
v = value.strip()
if v[:5].lower() != "op://" or not _is_secret_locator(v):
return value
path, marker, fragment = v[5:].partition("#")
segments = path.split("/")
if len(segments) != 3:
return value
for index in (0, 1):
if _ONEPASSWORD_ID.fullmatch(segments[index]):
segments[index] = "id"
return v[:5] + "/".join(segments) + marker + fragment


#: Strong placeholder tokens — a value is a fill-me-in only if at least one of
#: these is present as a WHOLE token and every other token is filler (CSO F2).
_PLACEHOLDER_TOKENS = frozenset({
Expand Down
99 changes: 99 additions & 0 deletions tests/test_auth_refs_op_ids.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
"""DSE-2124: exempt 1Password IDs only in exact vault/item reference slots."""

import pytest

from mcp_warden.auth_audit import audit_server
from mcp_warden.auth_refs import _looks_like_secret_ref

# Synthetic IDs from the issue's documented shape, not credentials.
OP_ID = "ykw6kguqbbfp3krwdpfd6b2qmm"
OTHER_ID = "a1234567890123456789012345"


def _rules(value):
findings = audit_server(
"op-ids", {"url": "https://mcp.example.com", "headers": {"Authorization": value}}
)
return {finding.rule_id for finding in findings}


@pytest.mark.parametrize("vault,item", [
("Private", OP_ID), (OP_ID, "GitHub"), (OP_ID, OTHER_ID),
])
@pytest.mark.parametrize("scheme", ["op", "OP"])
def test_op_vault_and_item_ids_are_references(vault, item, scheme):
value = f"{scheme}://{vault}/{item}/password"
assert _looks_like_secret_ref(value)
assert _rules(value) == set()


@pytest.mark.parametrize("value", [
f"op://Private/{OP_ID}/{OTHER_ID}",
f"op://{OP_ID}/{OTHER_ID}/Passw0rdPassw0rd",
f"op://{OP_ID}/{OTHER_ID}/token-9f8e7d6c5b4a3e2d1c0b",
f"op://{OP_ID}/{OTHER_ID}/password#{OP_ID}",
f"op://{OP_ID}/{OTHER_ID}/password#Passw0rdPassw0rd",
])
def test_op_field_and_fragment_are_never_exempt(value):
assert not _looks_like_secret_ref(value)
assert "WRD-AUTH-TOKEN-IN-CONFIG" in _rules(value)


@pytest.mark.parametrize("prefix", [
"~/", "./", "/", "vault://", "pass://", "awssm://", "gcpsm://", "azkv://",
"secretref://", "keyring://",
])
def test_other_schemes_and_paths_do_not_exempt_ids(prefix):
value = f"{prefix}Private/{OP_ID}/password"
assert not _looks_like_secret_ref(value)
assert "WRD-AUTH-TOKEN-IN-CONFIG" in _rules(value)


@pytest.mark.parametrize("near_id", [OP_ID[:-1], OP_ID + "a", OP_ID.upper(), "A" + OP_ID[1:]])
@pytest.mark.parametrize("position", [0, 1])
def test_id_shape_is_exact(near_id, position):
segments = ["Private", "GitHub", "password"]
segments[position] = near_id
value = "op://" + "/".join(segments)
assert not _looks_like_secret_ref(value)
assert "WRD-AUTH-TOKEN-IN-CONFIG" in _rules(value)


@pytest.mark.parametrize("path", [
f"Private/{OP_ID}", f"Private/{OP_ID}/section/password",
f"Private/{OP_ID}/password/", f"/Private/{OP_ID}/password",
f"Private//{OP_ID}/password", f"Private/{OP_ID}//password",
f"Private\\{OP_ID}\\password", f"Private/{OP_ID}/password?field=token",
f"Private/{OP_ID}/password%2Ftoken", f"/{OP_ID}/password",
f"Private/{OP_ID}/", f"Private/{OP_ID}/pass word",
])
def test_malformed_or_non_three_part_paths_do_not_gain_exemption(path):
value = "op://" + path
assert not _looks_like_secret_ref(value)
assert "WRD-AUTH-TOKEN-IN-CONFIG" in _rules(value)


def test_existing_names_and_safe_fragment_remain_references():
for value in ("op://Private/GitHub/token", f"op://Private/{OP_ID}/password#credential"):
assert _looks_like_secret_ref(value)
assert _rules(value) == set()


def test_vendor_secret_in_field_is_still_high():
value = f"op://Private/{OP_ID}/ghp_" + "a" * 36
assert "WRD-AUTH-TOKEN-IN-CONFIG" in _rules(value)


@pytest.mark.parametrize("field", [
"aB3xK9mQ7pL2wR5tY8vN4jH6~", "password#aB3xK9mQ7pL2wR5tY8vN4jH6",
])
def test_entropy_in_non_id_positions_is_still_high(field):
assert "WRD-SEC-ENTROPY" in _rules(f"op://Private/{OP_ID}/{field}")


def test_vendor_scan_uses_original_reference_even_when_id_is_masked():
# This short vendor pattern in a dotted field passes the locator heuristic.
value = f"op://Private/{OP_ID}/AKIA1234567890ABCDEF.json"
assert _looks_like_secret_ref(value)
assert "WRD-SEC-AWS-AKID" in _rules(value)
assert "WRD-AUTH-TOKEN-IN-CONFIG" in _rules(value)
Loading