v1.3.3 - CodeQL Compliance Hotfix

This is a rapid follow-up patch to address a GitHub CodeQL Code Scanning Alert identified in v1.3.2.

What's Changed

🛡️ CodeQL md5 Suppression

In v1.3.2, we reverted from pbkdf2_hmac back to md5(usedforsecurity=False) for generating deterministic synthetic seed integers. While this drastically improved performance and satisfied standard Python Linters (Bandit/Ruff), GitHub CodeQL continued to flag the explicit presence of the md5 token as a High-Severity security risk (Rule: Use of a broken or weak cryptographic hashing algorithm on sensitive data).

• Fix: Upgraded the deterministic seed generation to use the natively fast hashlib.sha256().hexdigest()[:16] instead.
• Impact: This maintains the exact same microsecond-level speed as md5, keeps deterministic Fake data consistent, and successfully resolves the CodeQL alert without needing manual dismissals or PR overrides in the GitHub UI.

Validation

• ✅ CodeQL: Addressed alert #17 in llm_shield_proxy/engines/vault.py
• ✅ Pytest: 100% Pass (No regressions in deterministic vault mappings)

Full Changelog: v1.3.2...v1.3.3

v1.3.2 - Security Linter Hardening & Performance Hotfix

This release focuses on optimizing performance regressions introduced in recent cryptographic changes while hardening our security posture against false-positive static analysis alerts.

What's Changed:

⚡ Performance Hotfix (Vault Synthetic Seeding) The previous update replaced md5 with sha256 for deterministic hashing across the board. While this satisfied CodeQL for password storage, it introduced a significant bottleneck inside the Vault when generating the integer seed for Faker's synthetic data engine (random.Random(seed)).

Fix: Switched back to the highly performant md5, but explicitly passed usedforsecurity=False (supported in Python 3.9+). This guarantees 0ms latency impact without triggering FIPS compliance violations or linters.
🛡️ Security Linting & Suppressions Bandit and Ruff reported 4 distinct categories of security issues. These were false positives given the context of the proxy, and have now been properly suppressed with explicit inline justifications to prevent future LLM/linter regressions:

B104 / S104: Suppressed the warning for binding the proxy host to 0.0.0.0 (Explicitly required for Docker deployments).
S103: Suppressed the os.chmod warning. The sticky bit 0o1770 is intentionally applied to the socket directory for IPC security.
S311: Suppressed the warning for using random.uniform instead of secrets (Used for exponential backoff jitter, not cryptographic key generation).
S110: Suppressed warnings for try-except-pass blocks that silently drop failed metrics / logs to prevent catastrophic proxy failure.
🔄 Terminology Updates

Fully migrated all SYNTHETIC_CRYPTO and STATELESS_SYNTHETIC references to STATELESS_CRYPTO across the codebase, configuration schemas, and documentation to accurately reflect behavior.

Full Changelog: v1.3.1...v1.3.2

Release Notes: LLM-Shield-Proxy v1.3.1

Terminology & Core Concepts

Global Terminology Shift: Completely migrated the STATELESS_CRYPTO redaction mode to STATELESS_SYNTHETIC across the entire codebase, configuration schemas, and documentation. This name much more accurately reflects the behavior: the engine deterministically generates synthetic fake data (e.g. [Maya]) but statelessly bundles the encrypted original text in-band, rather than implying raw ciphertext is sent to the LLM.
Security & Infrastructure

Helm Chart Hardening: Tightened the security posture of the llm-shield-proxy Kubernetes deployment. The Helm chart now strictly enforces securityContext settings, including readOnlyRootFilesystem: true and explicit capability drops, ensuring the proxy container runs with minimal privileges.
Documentation & Diagrams

Dual-Pipeline Architecture SVG: Overhauled the main data-flow architecture diagram. Replaced the clunky Mermaid.js diagram with a crisp, theme-aware SVG.
Unified the color styling of the STATEFUL and STATELESS routing boxes to match the standard JSON-RPC router.
Re-rendered the Redis Vault as a standard architectural cylinder rather than a rounded rectangle.
Architecture Cleanup: Fully removed the older, highly cluttered "Architecture Diagram" section in the README.
Link Fixes: Removed lingering, inaccurate text (e.g., "with faker Tier 2)") from the internal Markdown hyperlink structures.
Build & CI

CI Pipeline Fixes (Linting): Resolved an issue where GitHub Actions CI was failing due to W293 (trailing whitespace) and W291.
Removed legacy, unformatted scratch python scripts that were polluting the repository root.
Systematically stripped all trailing whitespace across all Markdown (.md) documentation files to ensure standard markdown compliance.

Full Changelog: v1.3.0...v1.3.1

v1.3.0: Stateless Cryptography, MCP Governance, Air-Gapped Egress, and System Hardening

This major release marks a massive leap forward in enterprise readiness and infrastructure resilience for LLM-Shield-Proxy. Version 1.3.0 introduces revolutionary zero-data stateless cryptography, strict agent identity enforcement, dynamic MCP governance, overhauled deployment topologies, and fortified cryptographic safeguards designed for the most demanding zero-trust environments.

🛡️ Core Security & Identity Enforcement

• Edge-Level Agent Identity Enforcer: Implemented a cryptographic Zero-Trust ingress barrier that intercepts autonomous agent tool-calls. Strictly validates mathematically signed Workload Identity (JWT) and DPoP proofs in <1ms to prevent rogue agent escalation and enforce O(1) identity mapping.
• Stateless Cryptography (Zero-Data Mode): Fully integrated ephemeral TTL vaults and AES-256-GCM envelope encryption, guaranteeing zero long-term data liability. The proxy operates completely statelessly in an ultra-low footprint (<85 MB RAM) without ever persisting sensitive prompts to disk.

🧠 Advanced Agent Governance

• Context-Aware Tool Catalog Pruner (MCP Discovery): Built a dynamic network-edge interceptor for JSON-RPC server/discover payloads (Model Context Protocol). Enforces $O(1)$ Pluggable Tool-Call RBAC to silently prune unauthorized tool schemas before they ever reach the LLM's context window.

🔌 Resiliency & Infrastructure

• Air-Gapped Egress Topologies: Introduced formal architectural patterns for deploying the proxy in Zero-Internet, strict Air-Gapped VPC configurations. The proxy now elegantly routes through internal network gateways (Squid, Envoy) while retaining full SSE hydration.
• Graceful K8s SIGTERM Draining: Resolved race conditions in the Kubernetes 25-second connection draining logic. Active Server-Sent Event (SSE) streams will now completely finish their token transmission during Pod termination before tearing down the sockets.
• Port-Collision & Mocking Stability: Overhauled the Out-Of-The-Box (OOTB) test suite to eliminate port-collisions and enforce deterministic connection binding during Docker standalone test executions.

🚀 Performance & Code Quality

• Production-Grade Exception Handling: Replaced all underlying logic assert statements within the proxy lifecycle with strict, deterministic RuntimeError and typed Exceptions. This prevents ungraceful process halting during unexpected streaming network edge cases.
• Token Bloat Optimization: Re-engineered the cryptographic benchmark suites, replacing lambda heuristics with exact TikToken bytecode encoders to achieve extreme precision in base64 token bloat telemetry.
• Elimination of Unused Pointers: Conducted a massive repository-wide static analysis and linting sweep to eliminate all trailing whitespaces, unused mock bindings, and floating variables to guarantee 100% execution integrity.

📚 Documentation & Repository Overhaul

• Comprehensive Architecture Documentation: Wrote and expanded dedicated documentation for Topologies, Agent Identity Enforcement, MCP Pruner, and BYOM/BYOR rules.
• Structural Consolidation: Massively reorganized the repository root. Migrated all core documentation to docs/, relocated local binaries to bin/, and completely eradicated over a dozen legacy throwaway/generation scripts, resulting in a significantly leaner, faster-to-clone repository structure.

Full Changelog: v1.2.14...v1.3.0

v1.2.14: CodeQL Security Hardening & PBKDF2 Tenant Cryptographic Isolation

What's Changed in v1.2.14

🔒 Cryptographic & Security Hardening (CodeQL Resolution)

• PBKDF2-HMAC Key Derivation for Multi-Tenant Virtual Keys: Replaced unsalted single-pass sha256 hashing in dynamic virtual key resolution with cryptographically salted hashlib.pbkdf2_hmac (get_virtual_key_id), utilizing 600,000 rounds, salt, and LRU cache for 0ms routing overhead. Resolves CodeQL alert py/weak-sensitive-data-hashing.
• Strict URI/Hostname Sanitization: Updated test assertions in antifragile dispatcher to enforce explicit URL hostname verification via urllib.parse.urlparse, eliminating potential domain substring spoofing vulnerabilities. Resolves CodeQL alert py/incomplete-url-substring-sanitization.

🧪 Quality Assurance & Test Verification

• 128 Automated Unit, Integration & Stress Tests Passing (100% test suite pass rate).
• Complete verification against Python 3.10, 3.11, and 3.12 runtimes.
• 0 linter errors across the entire codebase (ruff check .).

---

Full Changelog: v1.2.13...v1.2.14

Full Changelog: v1.2.13...v1.2.14

v1.2.12 — Dynamic Policy-as-Code (RBAC), Zero-Downtime Hot-Reloading & Enterprise Hardening

What's New in v1.2.12

🛡️ Dynamic Policy-as-Code (RBAC) & Zero-Downtime Hot Reloading

• Hierarchical Role-Based Access Control: Introduced declarative policies.yaml mapping virtual_key_id identities to granular security roles (e.g., developer_tier, clinical_tier, financial_tier).
• Zero-Downtime Hot-Reloading: Built-in background file watcher dynamically reloads and recompiles policy rules upon file modification without restarting proxy processes or interrupting active streaming connections.
• Dynamic Thread-Safe Context Settings: Implemented DynamicSettingsProxy using Python contextvars to provide per-request, $O(1)$ setting overrides for masking modes, rate limits, PII profiling, and fail-safe behaviors.
• Granular NER & Detection Scoping: Enables per-tenant toggling of Tier 3 ONNX/regex NER engines, custom regex patterns, and synthetic swapping behaviors.

⚡ Concurrency & Architecture Hardening

• Thread-Safe ContextVar Propagation: Redaction workloads dispatched to CPU worker pools via loop.run_in_executor now utilize contextvars.copy_context().run to ensure thread-pool execution inherits active request policy overrides.
• Lifecycle-Bound Event Loops: Refactored AppState.shutdown_event to bind dynamically inside FastAPI's async lifespan handler, eliminating event loop concurrency mismatches under multi-worker environments and test harnesses.
• BetterProto Python 3.11+ Dataclass Compatibility: Decorated Envoy ext_proc gRPC protobuf definitions with @dataclass(eq=False, repr=False) to guarantee standard compliance and zero serialization overhead across Python 3.11 and 3.12 runtimes.

📖 Documentation & Compliance Hub

• Added POLICIES.md: Exhaustive guide to RBAC configuration, custom role definitions, dynamic overrides, and audit trail schemas.
• Updated DEPLOYMENT.md and FEATURES.md with streamlined enterprise architectural notes.
• Updated README.md with curl verification examples and policy-as-code operational commands.

---

📦 Installation & Verification

Install the latest release directly from PyPI:

pip install --upgrade llm-shield-proxy==1.2.12

**Full Changelog**: https://github.com/ninadphalak/LLM-Shield-Proxy/compare/v1.2.11...v1.2.12

v1.2.11: Kubernetes-Native GRC Dispatcher & OOM Resilience Fix

🚀 What's New

Kubernetes-Native GRC Dispatcher

We've introduced a robust, non-blocking asynchronous transport layer to stream PII redaction and Tool-Call RBAC decision logs directly to GRC platforms (Vanta, Drata, Sprinto) and SIEMs without impacting the Data Plane's critical <1ms SSE streaming latency.

• AsyncWebhookTransport: Supports fire-and-forget HTTP webhooks for direct evidence ingestion into compliance platforms. Re-uses httpx connection pools to prevent socket exhaustion at high concurrency.
• SidecarFileTransport: Append-only WORM file writer optimized for fluentd/promtail logging stacks native to Kubernetes sidecar patterns.

🐛 Bug Fixes & Stability

• Memory Resilience (OOM Fix): Resolved a memory leak in the Trace Exporter during high concurrent streaming load. The proxy now aggressively conforms to its <55MB RAM footprint, even under Docker/K8s cgroup hard limits (--memory="55m"), by dropping excessive async task overhead and correctly managing garbage collection of completed transport events.
• InMemoryPolicyResolver Fallback: Ensured high availability of the Pluggable Tool-Call RBAC engine by adding a resilient in-memory fallback strategy if the primary Redis/OPA/Vault cluster becomes temporarily unavailable.
• Documentation Updates: Improved internal navigation by hyperlinking all Enterprise Flagship Features in the README.md to their corresponding architectural, security, and compliance deep dives.

Full Changelog: v1.2.9...v1.2.11

v1.2.9: Comprehensive Integration Testing Suite (k8s & OOTB)

Release Notes
Integration Testing: Added robust end-to-end integration test suites (tests/k8s, tests/k8s_ootb, tests/ootb) covering Kubernetes sidecar behavior, concurrency memory limits, stream resilience, and out-of-the-box (OOTB) Docker standalone configurations.
Tooling Updates: Implemented run_stress_tests.sh and verification bash scripts (verify_k8s_ootb.sh, verify_ootb.sh) in the test harness for isolated automated smoke testing.
CI/CD Optimization: Fixed GitHub Actions pipeline failures by isolating local Kubernetes and Docker integration tests from standard unit test runs, ensuring green builds.
Code Quality: Resolved trailing whitespaces, unorganized imports, and E701 syntax linting errors via comprehensive ruff linting and formatting.
Benchmarking: Tracked exception and failure metrics during Locust load testing directly via CSV exports.
Docs: Migrated PyPI version badge to img.shields.io for instant cache invalidation.

Full Changelog: v1.2.7...v1.2.9

Release v1.2.7: High-Concurrency Event Loop Unblocking & OTel Fixes

Release v1.2.7: High-Concurrency Event Loop Unblocking & OTel Fixes

This patch specifically targets ASGI event loop starvation under extreme concurrency (1,000+ users), resolving silent I/O blocking bottlenecks and fixing OpenTelemetry export behavior for enterprise deployments.

⚡ Performance & Telemetry Fixes

• True Asynchronous WORM Audit Logging: Refactored the core audit_logger to utilize a lock-free QueueHandler and QueueListener. SOC 2 audit logs now instantly drop into an unbounded memory queue and flush to sys.stdout on a dedicated background thread, completely decoupling disk/console I/O from the main ASGI event loop.
• OpenTelemetry OTLP Exporter Override: Fixed a severe bug where TELEMETRY_ENABLED=True would mistakenly instantiate a ConsoleSpanExporter and block the main thread. Traces are now correctly exported asynchronously over the network via HTTP using the standard OTLPSpanExporter.

🛠️ Testing & Dependency Hardening

• Betterproto Stabilization: Pinned betterproto dependency from the 2.0.0b6 beta up to the official 2.0.0 stable release.
• Test Suite Hygiene: Quieted upstream Starlette httpx2 DeprecationWarning noise via strict pytest.ini filter overrides.
• State Leakage Fixes: Added automatic _readyz_cache.clear() calls to the pytest conftest.py teardown hooks to eliminate PermissionError state bleeding across preflight isolation tests.

📚 Documentation

• Windows Sizing Limits: Added extensive benchmarking notes to the Enterprise Sizing Guide, establishing the absolute limit of a single Python ProactorEventLoop core on Windows at ~800 to 900 concurrent streaming users before accept() backlog saturation triggers ConnectionRefusedError.
• Config Tables: Exposed the TELEMETRY_ENABLED flag in the primary 12-factor configuration table.

Full Changelog: v1.2.6...v1.2.7

Release v1.2.6: High-Concurrency Event Loop Unblocking & OTel Fixes

Release v1.2.6: High-Concurrency Event Loop Unblocking & OTel Fixes

This patch specifically targets ASGI event loop starvation under extreme concurrency (1,000+ users), resolving silent I/O blocking bottlenecks and fixing OpenTelemetry export behavior for enterprise deployments.

⚡ Performance & Telemetry Fixes

• True Asynchronous WORM Audit Logging: Refactored the core audit_logger to utilize a lock-free QueueHandler and QueueListener. SOC 2 audit logs now instantly drop into an unbounded memory queue and flush to sys.stdout on a dedicated background thread, completely decoupling disk/console I/O from the main ASGI event loop.
• OpenTelemetry OTLP Exporter Override: Fixed a severe bug where TELEMETRY_ENABLED=True would mistakenly instantiate a ConsoleSpanExporter and block the main thread. Traces are now correctly exported asynchronously over the network via HTTP using the standard OTLPSpanExporter.

🛠️ Testing & Dependency Hardening

• Betterproto Stabilization: Pinned betterproto dependency from the 2.0.0b6 beta up to the official 2.0.0 stable release.
• Test Suite Hygiene: Quieted upstream Starlette httpx2 DeprecationWarning noise via strict pytest.ini filter overrides.
• State Leakage Fixes: Added automatic _readyz_cache.clear() calls to the pytest conftest.py teardown hooks to eliminate PermissionError state bleeding across preflight isolation tests.

📚 Documentation

• Windows Sizing Limits: Added extensive benchmarking notes to the Enterprise Sizing Guide, establishing the absolute limit of a single Python ProactorEventLoop core on Windows at ~800 to 900 concurrent streaming users before accept() backlog saturation triggers ConnectionRefusedError.
• Config Tables: Exposed the TELEMETRY_ENABLED flag in the primary 12-factor configuration table.

Full Changelog: v1.2.5...v1.2.6