diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e952d6..427cd0d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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). diff --git a/DOCUMENTATION_INDEX.md b/DOCUMENTATION_INDEX.md index d5712ed..3238d85 100644 --- a/DOCUMENTATION_INDEX.md +++ b/DOCUMENTATION_INDEX.md @@ -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 @@ -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 | diff --git a/action/requirements.lock b/action/requirements.lock index 33fb027..8b735d6 100644 --- a/action/requirements.lock +++ b/action/requirements.lock @@ -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 \ diff --git a/docs/AGENT_GATES.md b/docs/AGENT_GATES.md index e632387..2bd0aac 100644 --- a/docs/AGENT_GATES.md +++ b/docs/AGENT_GATES.md @@ -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 diff --git a/docs/plans/2026-11-14-op-reference-ids.md b/docs/plans/2026-11-14-op-reference-ids.md new file mode 100644 index 0000000..316f398 --- /dev/null +++ b/docs/plans/2026-11-14-op-reference-ids.md @@ -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. diff --git a/requirements-dev.lock b/requirements-dev.lock index 3dfdab7..6f18fb4 100644 --- a/requirements-dev.lock +++ b/requirements-dev.lock @@ -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 \ diff --git a/src/mcp_warden/auth_audit.py b/src/mcp_warden/auth_audit.py index 4cf850f..f7e7f06 100644 --- a/src/mcp_warden/auth_audit.py +++ b/src/mcp_warden/auth_audit.py @@ -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 @@ -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 diff --git a/src/mcp_warden/auth_refs.py b/src/mcp_warden/auth_refs.py index 6cb26ee..7fc859c 100644 --- a/src/mcp_warden/auth_refs.py +++ b/src/mcp_warden/auth_refs.py @@ -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? """ @@ -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. @@ -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({ diff --git a/tests/test_auth_refs_op_ids.py b/tests/test_auth_refs_op_ids.py new file mode 100644 index 0000000..692dd8b --- /dev/null +++ b/tests/test_auth_refs_op_ids.py @@ -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)