Chapter 13: Unified Configuration Reference

The langchain-security-extension framework and its companion applications support deterministic, zero-trust configuration via declarative Python decorators, property configuration files (config.properties), and standard environment variables.

Every property defined in config.properties can be overridden at deployment time by declaring an uppercase environment variable where dots are replaced by underscores (for example, security.pdp.mode is overridden by SECURITY_PDP_MODE).

1. Policy Decision Point (PDP) & Authorization Engine

These settings govern whether policy evaluation is performed in-process by the embedded rule engine or delegated to an external service like Open Policy Agent (OPA), as well as remote circuit breaker thresholds.

Property Key / Env Var Type & Values Default Value Description & Operational Impact
security.pdp.mode
SECURITY_PDP_MODE		 String
EMBEDDED | OPA		 EMBEDDED Selects the primary authorization engine. EMBEDDED evaluates role hierarchies and numeric clearance locally in Python memory with sub-millisecond latency. OPA delegates evaluations to an external REST endpoint.
security.pdp.opa.url
SECURITY_PDP_OPA_URL		 String (URL) http://localhost:8181/v1/data/langchain/security/allow The target REST endpoint for Open Policy Agent (or Cedar sidecar) decision queries when security.pdp.mode=OPA.
security.pdp.opa.timeout
SECURITY_PDP_OPA_TIMEOUT		 Float (Seconds) 0.05 (50ms) HTTP client timeout for remote PDP evaluations. Outages or latency spikes exceeding this threshold immediately record an evaluation failure.
security.pdp.circuitbreaker.threshold
SECURITY_PDP_CIRCUITBREAKER_THRESHOLD		 Integer 1 (assistant)
5 (library core)		 Number of consecutive network timeouts or 5xx errors from the remote PDP that trip the circuit breaker into OPEN state.
security.pdp.circuitbreaker.recovery
SECURITY_PDP_CIRCUITBREAKER_RECOVERY		 Float (Seconds) 30.0 Cooldown window before an OPEN circuit breaker transitions to HALF_OPEN to probe remote PDP recovery. During OPEN, requests fail closed deterministically.

2. Two-Tier Decision Cache (L1 & L2)

The library features a two-tier decision caching architecture to avoid redundant evaluations and eliminate token-stage delays.

Property Key / Env Var Type & Values Default Value Description & Operational Impact
security.cache.l1.enabled
SECURITY_CACHE_L1_ENABLED		 Boolean
true | false		 true Enables Tier 1 invocation-scoped memoization. Decisions are stored directly inside LangChain's RunnableConfig["configurable"]["sec:decision_cache"], providing zero-lock, thread-agnostic cache hits across all sub-agents and tools within a single request.
security.cache.l2.enabled
SECURITY_CACHE_L2_ENABLED		 Boolean
true | false		 true Enables Tier 2 cross-request LRU decision caching across multiple invocations for identical caller roles and resources.
security.cache.l2.ttl
SECURITY_CACHE_L2_TTL		 Float (Seconds) 60.0 (assistant)
300.0 (library core)		 Time-to-live for Tier 2 cached verdicts. Automatically invalidated early if caller roles or clearance are revoked via OPACacheInvalidationHandler.
security.cache.l2.maxEntries
SECURITY_CACHE_L2_MAXENTRIES		 Integer 1000 (assistant)
4096 (library core)		 Maximum capacity of the Tier 2 LRU cache. When exceeded, least-recently-used authorization verdicts are pruned.

3. Tool Interception, Anti-Looping & Abuse Throttling

Settings governing pre-execution tool parameter validation, retry budgets for soft model feedback, and cross-turn brute-force abuse protection.

Property Key / Env Var Type & Values Default Value Description & Operational Impact
security.retry.maxViolations
SECURITY_RETRY_MAXVIOLATIONS		 Integer 3 (assistant)
2 (library core)		 Maximum number of consecutive policy denials permitted for informational tools before escalating to a HARD_ABORT. Shuts down runaway LLM tool retry loops.
security.abuse.windowSeconds
SECURITY_ABUSE_WINDOWSECONDS		 Float (Seconds) 60.0 Sliding temporal window in seconds used to track denied tool executions per subject across turns.
security.abuse.maxDenials
SECURITY_ABUSE_MAXDENIALS		 Integer 3 Denial cap within security.abuse.windowSeconds. When reached, triggers a critical POLICY_BRUTE_FORCE_SCANNING threat alert in SIEM and throttles execution.

4. Data Loss Prevention (DLP) & In-Flight PII Redaction

Governs automated regex masking of sensitive parameters, Luhn-valid credit card numbers, Indian Aadhaar/PAN IDs, passwords, and bearer tokens.

Property Key / Env Var Type & Values Default Value Description & Operational Impact
security.pii.redaction.scope
SECURITY_PII_REDACTION_SCOPE		 String
audit_only | full_in_flight | disabled		 audit_only audit_only: Scrubs PII and credentials exclusively before payloads are emitted to SIEM and log aggregators.
full_in_flight: Irreversibly scrubs PII across prompts, tool arguments, tool outputs, RAG chunks, and audit logs.
disabled: Disables automated PII scrubbing.
DEFAULT_REDACTION_TOKEN String [REDACTED] Replacement token substituted in place of detected secrets, credit cards, or PII.

5. Knowledge Ingestion & Vector Retrieval (RAG) Security

Controls metadata labeling, cryptographic HMAC verification, and oversampling retrieval behavior for knowledge bases.

Property Key / Env Var Type & Values Default Value Description & Operational Impact
security.ingestion.mode
SECURITY_INGESTION_MODE		 String
STRICT_FAIL_CLOSED | EVERYTHING_CLASSIFIED | EVERYTHING_PUBLIC		 STRICT_FAIL_CLOSED STRICT_FAIL_CLOSED: Rejects and rolls back document batches if any chunk lacks mandatory sec:* metadata envelopes.
EVERYTHING_CLASSIFIED: Tags unlabelled chunks as sec:quarantined = true with RESTRICTED classification.
EVERYTHING_PUBLIC: Defaults unlabelled chunks to PUBLIC (clearance 0).
security.hmac.secret
SECURITY_HMAC_SECRET		 String enterprise-hmac-secret-key Shared secret key used to compute and verify the HMAC-SHA256 signature in sec:envelope_hash. Prevents direct database tampering of chunk clearance.
security.retriever.oversampling
SECURITY_RETRIEVER_OVERSAMPLING		 Float 3.0 Predictive multiplier ($K_{fetch} = K_{target} \times factor$) applied to vector search candidate windows to guarantee Top-K documents remain after post-retrieval clearance pruning.
DEFAULT_MAX_FETCH_CAP Integer 50 Absolute upper bound on candidate chunks fetched from the vector store during oversampling.

6. Multi-Tenancy & Default Identity Attributes

Fallback identity parameters applied when perimeter tokens lack explicit tenant or organizational claims.

Property Key / Env Var Type & Values Default Value Description & Operational Impact
security.default.tenant
SECURITY_DEFAULT_TENANT		 String CORP_MAIN (assistant)
DEFAULT_TENANT (core)		 Tenant partition assigned when no tenant_id claim is present in caller credentials.
security.default.department
SECURITY_DEFAULT_DEPARTMENT		 String IT_OPS (assistant)
GENERAL (core)		 Department partition assigned when no department attribute is supplied in caller identity.
jwt.secret
JWT_SECRET		 String secret-key HMAC secret key used by perimeter authentication filters to sign and verify Bearer JWT tokens.

7. Audit Telemetry & SIEM Streaming

Parameters governing non-blocking asynchronous log shipping to enterprise SIEM platforms (Splunk, Elastic, Datadog).

Property Key / Env Var Type & Values Default Value Description & Operational Impact
DEFAULT_RING_BUFFER_CAPACITY Integer 16384 Capacity of the in-memory ring buffer for audit events. Background publisher threads drain this buffer asynchronously without adding latency to agent turns.
DEFAULT_PAYLOAD_MAX_CHARS Integer 2048 Truncation threshold for raw event payload dumps inside emitted audit logs to prevent SIEM message exhaustion.
splunk.hec.url
SPLUNK_HEC_URL		 String (URL) Optional (Empty) Splunk HTTP Event Collector (HEC) endpoint URL for direct streaming of RFC 5424 / OCSF audit events.
splunk.token
SPLUNK_TOKEN		 String Optional (Empty) Authentication bearer token for Splunk HEC ingestion.

8. Demonstrator Server & Model Configuration

These settings configure the host server and language model integrations in langchain-enterprise-incident-assistant.

Property Key / Env Var Type & Values Default Value Description & Operational Impact
server.host / SERVER_HOST String 0.0.0.0 Host binding interface for the embedded FastAPI server.
server.port / SERVER_PORT Integer 8080 Listening TCP port for the embedded assistant server.
chroma.url / CHROMA_URL String (URL) http://localhost:8000 Target ChromaDB vector database instance URL.
chroma.collection / CHROMA_COLLECTION String it_runbooks ChromaDB collection storing classified IT incident runbooks.
model1.baseUrl
MODEL1_BASEURL		 String (URL) http://localhost:11434 Base URL of LLM provider for Model 1 (Triage Agent). Supports Ollama, OpenAI, Gemini, or Claude.
model1.modelclass
MODEL1_MODELCLASS		 String
ollama | openai		 ollama ChatModel adapter protocol for Model 1 (Triage Agent). Use openai for OpenAI, Gemini Flash (OpenAI compatibility mode), or Claude gateways.
model1.modelname
MODEL1_MODELNAME		 String llama3.2:3b Target model identifier for Model 1 (Triage Agent).
model1.apikey
MODEL1_APIKEY		 String Optional (Empty) API key for commercial providers for Model 1.
model1.timeout
MODEL1_TIMEOUT		 String 300s HTTP client timeout for Model 1 inferences.
model2.baseUrl
MODEL2_BASEURL		 String (URL) http://localhost:11434 Base URL of LLM provider for Model 2 (Remediation Agent). Can match model1 or point to an independent model backend.
model2.modelclass
MODEL2_MODELCLASS		 String
ollama | openai		 ollama ChatModel adapter protocol for Model 2 (Remediation Agent).
model2.modelname
MODEL2_MODELNAME		 String llama3.2:3b Target model identifier for Model 2 (Remediation Agent).
model2.apikey
MODEL2_APIKEY		 String Optional (Empty) API key for commercial providers for Model 2.
model2.timeout
MODEL2_TIMEOUT		 String 300s HTTP client timeout for Model 2 inferences.

Summary & Related Guides