` is fine, deeper nesting confuses the model and leaks tag tokens into responses). See [Prompt Injection Defenses](references/prompt-injection-defenses.md) for the full guardrails stack (pattern library, output scanner, instruction hierarchy). ### Step 2 — Enforce the tool allowlist via `create_react_agent`, never free-text Legacy ReAct agents parse free-text `Action: ` lines. If a model hallucinates `Action: shell_exec`, a permissive parser tries to call it — the allowlist was only advisory (P32). The fix is provider-native tool calling: ```python from langchain_anthropic import ChatAnthropic from langgraph.prebuilt import create_react_agent from langchain_core.tools import tool @tool def lookup_order(order_id: str) -> str: """Look up an order by ID. Only digits and dashes allowed.""" if not order_id.replace("-", "").isdigit(): raise ValueError("order_id must contain only digits and dashes") return db.fetch_order(order_id) model = ChatAnthropic(model="claude-sonnet-4-6", temperature=0, timeout=30, max_retries=2) agent = create_react_agent(model, tools=[lookup_order]) ``` Because Anthropic's API accepts a structured tool schema and returns a structured tool call, the model physically cannot emit a tool name that isn't in the bound list — the provider enforces the allowlist. Free-text ReAct in production is a security anti-pattern; see [Tool Allowlist Enforcement](references/tool-allowlist-enforcement.md) for the per-call allowlist pattern and the tool-arg deny-list for dangerous values. ### Step 3 — Redact PII in middleware upstream of cache and tracing PII that reaches the provider cache or OTEL exporter is durable — caches survive restarts, traces land in a SIEM. Redact in LangChain middleware before either sees the content. See `langchain-middleware-patterns` for the ordering contract; the security-relevant invariant is: ``` raw_user_input → redaction_middleware (replaces PII with [EMAIL_1], [SSN_1], ...) → cache_key_hasher → provider_call → trace_exporter ``` Typical PII detector precision on a Presidio-style pipeline is **~92%** on credit-card / SSN / email regex patterns and **~78%** on named-entity PII (person, location) — never trust redaction as a complete defense; treat it as one layer. Pair with the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` policy from Step 6. ### Step 4 — Validate outputs and tool args with Pydantic + deny-list Even with `create_react_agent` enforcing tool names, tool **arguments** are free text. A `WebBaseLoader` tool called with `http://169.254.169.254/latest/meta-data/` probes AWS instance metadata — the inverse of P50 (Cloudflare blocking a loader) is a loader probing internal networks. Apply a domain allowlist and a link-local deny-list: ```python from pydantic import BaseModel, field_validator, HttpUrl from urllib.parse import urlparse ALLOWED_DOMAINS = {"example.com", "docs.example.com"} BLOCKED_HOSTS = {"169.254.169.254", "127.0.0.1", "0.0.0.0", "::1", "localhost"} class FetchArgs(BaseModel): url: HttpUrl @field_validator("url") @classmethod def _check_host(cls, v): host = urlparse(str(v)).hostname if host in BLOCKED_HOSTS: raise ValueError(f"blocked host: {host}") if host not in ALLOWED_DOMAINS: raise ValueError(f"host not in allowlist: {host}") return v ``` Output validation catches the two failure modes named in the error table below: **injection-via-document** (canary token appears in response → reject) and **synthesized-tool call** (Pydantic validator rejects malformed args → the react loop retries or fails closed). ### Step 5 — Load secrets via secret manager + `pydantic.SecretStr`, not `.env` `python-dotenv` populates `os.environ` — anyone with `docker exec` access can print every key (P37). Production loads secrets from a secret manager into memory only, wrapped in `pydantic.SecretStr` so accidental prints redact: ```python from pydantic import BaseModel, SecretStr from google.cloud import secretmanager def _fetch(name: str) -> str: client = secretmanager.SecretManagerServiceClient() resp = client.access_secret_version(name=f"projects/my-proj/secrets/{name}/versions/latest") return resp.payload.data.decode("utf-8") class Settings(BaseModel): anthropic_api_key: SecretStr openai_api_key: SecretStr settings = Settings( anthropic_api_key=SecretStr(_fetch("anthropic-api-key")), openai_api_key=SecretStr(_fetch("openai-api-key")), ) # Pass to LangChain — providers accept SecretStr directly in 1.0 model = ChatAnthropic( model="claude-sonnet-4-6", api_key=settings.anthropic_api_key, # SecretStr, not str ) ``` Decision tree: | Environment | Secret source | Wrapper | |-------------|---------------|---------| | Local dev | `.env` (gitignored) | `SecretStr` from `os.getenv` | | Staging | Secret Manager | `SecretStr` from fetch helper | | Production | Secret Manager + rotation | `SecretStr` + scheduled refresh | See [Secrets Lifecycle](references/secrets-lifecycle.md) for per-cloud provisioning, IAM binding, and rotation schedules. ### Step 6 — Set OTEL trace-content policy per tenancy mode `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false` is the safe default — traces capture timing and token counts but not prompt/response text (P27). Flip to `true` only in single-tenant environments with no PII in prompts. In multi-tenant, leave it off; if prompt visibility is required for debugging, run the redaction middleware from Step 3 and export redacted snapshots to a separate, access-controlled sink. ### Step 7 — Override provider safety filters explicitly, document posture Gemini's `HARM_BLOCK_THRESHOLD=BLOCK_MEDIUM_AND_ABOVE` default rejects benign medical, legal, and security-research prompts with `finish_reason=SAFETY` (P65). For domain apps, override explicitly and record the override in the compliance posture document: ```python from langchain_google_genai import ChatGoogleGenerativeAI, HarmCategory, HarmBlockThreshold gemini = ChatGoogleGenerativeAI( model="gemini-2.5-pro", safety_settings={ HarmCategory.HARM_CATEGORY_MEDICAL: HarmBlockThreshold.BLOCK_NONE, HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_MEDIUM_AND_ABOVE, }, ) ``` See [Compliance Posture](references/compliance-posture.md) for the GDPR / HIPAA / SOC2 touchpoints and the audit-log fields a reviewer will ask for. ## Threat model: OWASP LLM Top 10 → LangChain mitigation | OWASP ID | Category | LangChain 1.0 mitigation | Skill | |----------|----------|--------------------------|-------| | LLM01 | Prompt Injection | XML tag boundary + canary (Step 1); GuardrailsRunnable | this, `langchain-middleware-patterns` | | LLM02 | Insecure Output Handling | Pydantic validation + URL/arg deny-list (Step 4) | this, `langchain-sdk-patterns` | | LLM03 | Training Data Poisoning | Out of scope — provider concern for managed models | N/A | | LLM04 | Model DoS | `max_retries=2`, timeout=30, circuit breaker | `langchain-rate-limits` | | LLM05 | Supply Chain | Pin `langchain-core 1.0.x`, verify package signatures | `langchain-upgrade-migration` | | LLM06 | Sensitive Information Disclosure | PII redaction middleware (Step 3); OTEL content off (Step 6) | this, `langchain-middleware-patterns` | | LLM07 | Insecure Plugin Design | `create_react_agent` tool allowlist (Step 2); arg deny-list (Step 4) | this, `langchain-langgraph-agents` | | LLM08 | Excessive Agency | Recursion limits, per-tool permission checks, human-in-loop | `langchain-langgraph-agents` | | LLM09 | Overreliance | Output validation, structured outputs, confidence thresholds | `langchain-sdk-patterns` | | LLM10 | Model Theft | API auth, rate limit per tenant, watermark responses | `langchain-enterprise-rbac` | ## Output 1. User-supplied content wrapped in `` / `` XML tags with canary token (max tag depth 2) 2. Tool-calling agents built with `create_react_agent`; zero free-text ReAct in production 3. PII redaction middleware installed upstream of cache + OTEL (precision ~92% regex / ~78% NER) 4. Pydantic + domain-allowlist / host-deny-list validation on every tool arg and fetcher URL 5. Secrets loaded from GCP/AWS/Vault into `pydantic.SecretStr`; `.env` gitignored, dev-only 6. `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false` in multi-tenant; documented override in single-tenant 7. Provider safety settings explicitly set; compliance posture doc names the profile ## Error Handling | Error | Cause | Fix | |-------|-------|-----| | Model output contains the canary token | Injection-via-document — tag boundary was bypassed (P34) | Reject response, log the document ID, add the bypass pattern to the GuardrailsRunnable | | `Action: shell_exec` appears in agent trace with no `shell_exec` tool bound | Synthesized-tool call in free-text ReAct (P32) | Migrate to `create_react_agent` — provider enforces allowlist | | `ValueError: blocked host: 169.254.169.254` on WebBaseLoader | Output validator caught an internal-network probe (P50 inverse) | Working as intended; log, alert, and review the prompt that produced the URL | | `docker exec env` prints the API key | `python-dotenv` loaded secrets into `os.environ` (P37) | Move to Secret Manager + `SecretStr`; remove `.env` from prod image | | Multi-tenant OTEL trace shows Tenant A prompt in Tenant B dashboard | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` in multi-tenant (P27) | Set to `false`; rotate any leaked data; re-scan traces for residual PII | | `google.api_core.exceptions.InvalidArgument: finish_reason=SAFETY` on benign medical prompt | Gemini default safety threshold (P65) | Override `safety_settings` for the domain, document the rationale | | `print(settings)` shows plain-text API key | Settings object stores `str`, not `SecretStr` | Wrap in `pydantic.SecretStr`; LangChain 1.0 providers accept it directly | ## Examples ### Layered injection defense — tag boundary plus canary verification The Step 1 wrapper catches the easy cases. For a domain like legal document review where injected instructions in uploaded PDFs are a known threat, add a post-call verifier that inspects the model output for the canary and for known jailbreak patterns (`"Ignore previous"`, `"DAN mode"`, `"system override"`). A positive hit rejects the response before it reaches the user and emits a security event. See [Prompt Injection Defenses](references/prompt-injection-defenses.md) for the full GuardrailsRunnable pattern and the output-pattern scanner. ### Per-call tool allowlist for multi-tenant agents Tenant A may call `lookup_order`, Tenant B may call `lookup_shipment`. `create_react_agent` binds tools at graph construction — pass the tenant-scoped tool list per invocation via `config["configurable"]["tools"]` and rebuild the agent per request, or use LangGraph's dynamic tool binding from 1.0+. See [Tool Allowlist Enforcement](references/tool-allowlist-enforcement.md) for the per-request construction pattern and the tool-arg deny-list. ### Compliance posture for a HIPAA-adjacent medical app Gemini's default safety filters reject a chunk of legitimate medical discussion (P65). Override `HARM_CATEGORY_MEDICAL` to `BLOCK_NONE`, log the override, route prompts through the PII redaction middleware, and disable OTEL content capture (P27). The posture document names the provider, the safety profile, the PII detector precision, and the secret-rotation cadence. See [Compliance Posture](references/compliance-posture.md) for the reviewer checklist and the audit-log schema. ## Resources - [LangChain security concepts](https://python.langchain.com/docs/security/) - [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/) - [Anthropic: Use XML tags for structured prompts](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/use-xml-tags) - [`create_react_agent` reference (LangGraph)](https://langchain-ai.github.io/langgraph/reference/prebuilt/#langgraph.prebuilt.chat_agent_executor.create_react_agent) - [Pydantic `SecretStr`](https://docs.pydantic.dev/latest/api/types/#pydantic.types.SecretStr) - [OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) - Pack pain catalog: `docs/pain-catalog.md` (entries P27, P32, P34, P37, P50, P65)