feat(langchain): SecretMiddleware for tool-call credential detection

[Bagatur (baskaryan)]

Description

Adds a tool-call middleware (SecretMiddleware) that detects known credential patterns in tool-call arguments and either blocks the call or redacts the matched substring before the tool runs.

Motivation

Agents that read attacker-controllable input — system prompts, retrieved documents, tool-result content from upstream tools — can be steered (via prompt injection) into emitting tool calls that embed credentials they read from elsewhere, exfiltrating them through the legitimate tool surface. The egress allowlist on the agent's environment can't help here because the destination host is exactly the one you have to allow for legitimate use.

A chokepoint in front of tool execution that inspects args closes that gap. It's the natural complement to PIIMiddleware (which scans messages for PII) — different threat surface (tool args), different patterns (credentials), but the same shape of solution.

API

from langchain.agents import create_agent
from langchain.agents.middleware import SecretMiddleware

# Default: block any tool call carrying a known secret.
agent = create_agent("openai:gpt-5", tools=[...], middleware=[SecretMiddleware()])

# Or redact in place and let the tool run on rewritten args.
agent = create_agent(
    "openai:gpt-5",
    tools=[...],
    middleware=[SecretMiddleware(strategy="redact")],
)

Other constructor args:

• tools=[...] — limit to specific tools (mirrors ToolRetryMiddleware).
• secret_types=[...] — limit to specific built-in detectors. See BUILTIN_SECRET_TYPES for the full set: github_classic_token, github_fine_grained_pat, langsmith_key, anthropic_key, openai_project_key, openai_legacy_key, aws_access_key_id, jwt.
• custom_detectors={"name": finder} — register additional detectors. Each finder takes a string and yields (start, end) byte-offset pairs.

Public surface: SecretMiddleware, SecretMatch, find_secrets, BUILTIN_SECRET_TYPES.

Design notes

No \b word-boundary anchors on the patterns. Each detector relies on prefix + length + alphabet to be tight on its own. Boundaries would block matches when secrets are concatenated with alphanumeric characters in JSON the agent built up by interpolation — exactly the case attackers exploit. The negative corpus in test_find_secrets_negative_corpus (commit SHAs, UUIDs, ULIDs, {"lc": 1, ...} manifest snippets, prose like "the docs mention sk- as a prefix") confirms FP rate stays at zero without them.

Block strategy never echoes the matched substring back. Returning the match in the ToolMessage content would re-publish the secret into the agent's context window, defeating the purpose. The rejection mentions only the type (e.g. github_classic_token) and the tool name.

Redact uses request.override to produce a new ToolCallRequest with rewritten args, leaving the original immutable.

Tests

51 tests covering: each built-in pattern detected, negative corpus, nested dict walking with path tracking, offset reporting, block strategy, redact strategy (incl. nested + overlapping spans), tools filter, secret_types filter, custom detectors with and without built-ins, async wrap, missing args dict, and end-to-end create_agent integration for both strategies.

51 passed in 3.60s

Lint clean (uv run --group lint ruff check), formatted (uv run --group lint ruff format).

[codspeed-hq]

Merging this PR will not alter performance

✅ 2 untouched benchmarks
⏩ 13 skipped benchmarks¹

---

_{Comparing baskaryan:feat/secret-middleware (e9f83fc) with master (5a9b1ec)²}

Footnotes

1. 13 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

2. No successful run was found on master (9bd730e) during the generation of this report, so 5a9b1ec was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[Eugene Yurtsev (eyurtsev)]

Have you seeing the PIIMiddleware interface?