ClawSec: A Production-Ready Security Framework For LLM Agents Built From The Ground Up

AI Agent Security  ·  LLM Governance  ·  FastAPI  ·  Prompt Injection  ·  RBAC  ·  OpenTelemetry  ·  Python  ·  Apache 2.0

SnackOnAI Engineering  ·  Senior AI Systems Researcher  ·  March 2026  
·  Source: github.com/mohnishbasha/clawsec  ·  License: Apache 2.0

Imagine a developer at a US healthcare startup wiring up a new LLM-powered assistant. They copy an environment variable into a test prompt to debug a configuration issue: api_key=sk-abc123.... The request goes straight to the model. The model echoes the value back in its response. The response gets logged. The log gets indexed. The key is now in plaintext in three different places. Nobody noticed.

This is not a contrived scenario. It is the default behavior of every unguarded LLM endpoint. ClawSec by Mohnish Basha is a production-ready Python framework that puts a multi-layer security envelope around any LLM agent: intercepting dangerous inputs before they reach the model, sanitizing outputs before they reach the caller, enforcing role-based access at every endpoint, and logging every event to an immutable audit trail. It is the kind of infrastructure that should ship with every LLM deployment but almost never does.

Most LLM deployments start as demos. A FastAPI route calls OpenAI, returns the response, ships on Friday. The security controls that should have been designed in from the start get deferred indefinitely. The attack surface of an LLM endpoint is qualitatively different from a traditional API: the input is natural language, which means any structured security pattern embedded in user text is a potential attack vector. Prompt injection, credential exfiltration, PII leakage, and unauthorized access are all live risks from the first request.

The four failure modes ClawSec directly addresses are: prompt injection, where adversarial text hijacks the model's behavior; secret exfiltration, where credentials embedded in prompts or responses leak to unauthorized consumers; PII exposure, where personally identifiable data flows through the LLM unredacted; and access control gaps, where every user has the same permissions regardless of role. None of these are hypothetical. All four have caused real incidents in production AI systems.

ClawSec is a Python 3.11+ application built on FastAPI, SQLAlchemy, OpenTelemetry, and Prometheus. It is not a library you import or a plugin you install. It is a self-contained, deployable service that sits in front of any OpenAI-compatible LLM backend and enforces security policy at the API boundary. The stack includes six core source modules, a 60-plus case integration test suite, Kubernetes manifests, Docker Compose for local development, pre-built Grafana dashboards, and a single-page web UI that requires no build step. It is licensed under the Apache 2.0 license.

The design philosophy is explicit in the codebase: security controls are not middleware add-ons bolted onto a working application — they are the primary logic. The route handler calls validate_input() before it ever touches the LLM agent, and calls validate_output() before returning anything to the caller. The LLM call is sandwiched between two security layers.

The six source modules have clean, non-overlapping responsibilities. main.py wires the application together and owns all telemetry counters. rbac.py owns identity: JWT creation, verification, and the Starlette middleware that enforces authentication before any handler runs. policy_engine.py owns all content security. governance.py owns the audit trail via SQLAlchemy. agent.py owns the LLM call. observability.py owns telemetry bootstrap.

The request flow is sequential and mandatory: HTTP request hits RBACMiddleware first (JWT check), then validate_input() covering injection, secrets, length, and PII, then LLMAgent.query(), then validate_output() for secret redaction and PII scrubbing, then log_event(). Telemetry flows to Prometheus on port 9090 and via OTLP gRPC to the OTel Collector, which feeds Grafana.

All regex patterns are compiled at module load time into COMPILED_INJECTION, COMPILED_SECRETS, and COMPILED_PII lists — a critical performance choice that avoids regex compilation overhead on every request. The injection set covers 13 attack families. The secret detection set covers 10 credential types. The PII set covers 17 data categories applied to both inputs and outputs.

The PII coverage is unusually thorough: US SSNs, passport numbers, driver license formats, six major credit card BINs plus a fallback 16-digit pattern, IBAN, bank account numbers near contextual keywords, email addresses, US and UK phone numbers, medical record numbers, NHS numbers, IPv4, IPv6, and date-of-birth patterns near contextual keywords. The key architectural choice is that PII is applied to both inputs before the LLM sees them, and outputs before the caller receives them.

The asymmetry between input and output handling is deliberate. Injection and secrets on inputs always block (HTTP 400). Secrets and PII in outputs are redacted rather than blocked, so callers still receive a useful response. This avoids the failure mode where legitimate responses are blocked because the model echoed a pattern from training data.

Permissions are embedded in the JWT payload at issuance and re-verified on every request by RBACMiddleware before any handler logic runs. The middleware handles authentication — is the token valid? Individual handlers call check_permission() for authorization — does this role have this permission? No auth header returns HTTP 403. Expired token returns HTTP 401. Wrong role returns HTTP 403 and writes an rbac_denial audit event.

The auditor role can read logs but cannot submit queries — a segregation of duties control that satisfies SOX and HIPAA requirements out of the box.

Two deliberate data handling decisions stand out. First, prompt content is never stored — only metadata like prompt length and outcome. This limits blast radius if the audit database is compromised. Second, the request_id UUID is stamped on the HTTP response header, the OTel trace span, and the audit record simultaneously — enabling end-to-end traceability from any user complaint to the exact LLM call and its full security context.

Six metrics are registered at startup in main.py: llm_requests_total, policy_violations_total, pii_redactions_total, rbac_denials_total, audit_events_total, and llm_request_duration_seconds histogram. The pre-built Grafana dashboard ships with five panels covering all counters and latency distribution — a working security metrics dashboard exists on day one of deployment. Distributed traces ship via OTLP gRPC. The Python root logger is bridged to OTel automatically, so all application logs become structured telemetry without extra instrumentation.

The multi-stage Dockerfile isolates the build toolchain entirely from the runtime image. The runtime stage creates a dedicated non-root user (UID 1000, no login shell), mounts /tmp as tmpfs, and uses exec-form ENTRYPOINT. The health check uses Python's stdlib urllib rather than installing curl — a minimal attack surface choice.

The Kubernetes Deployment sets runAsNonRoot: true, readOnlyRootFilesystem: true, allowPrivilegeEscalation: false, drops all Linux capabilities, disables service account token auto-mounting, applies a RuntimeDefault seccomp profile, and uses topologySpreadConstraints to spread replicas across nodes. JWT secrets and LLM API keys are sourced from Kubernetes Secrets via secretKeyRef, never from ConfigMaps.

The most important pattern is policy as configuration. The YAML files in config/ mirror every pattern in source with a human-readable description, meaning security policy can be reviewed in PRs by security and compliance teams who are not Python engineers. The PolicyResult dataclass is a clean abstraction: every policy check returns allowed, violations, sanitized_text, and pii_detections — handlers use one boolean check for flow control while full violation detail flows to the audit log.

The mock mode in agent.py means all 60-plus integration tests run in CI with zero API keys required. Security infrastructure this easy to develop against actually gets adopted.

A US healthcare SaaS company deploying a clinical documentation assistant needs to guarantee that no PHI flows through the LLM unredacted. ClawSec's PII redaction covering SSNs, MRNs, dates of birth, and phone numbers handles this automatically on both input and output. The governance module's decision not to store prompt content directly supports HIPAA's minimum necessary data principle. The auditor role gives compliance officers full event log access without any ability to submit queries or modify configuration.

A US financial services firm running an AI analyst assistant needs proof that no credentials flow through the LLM and that every query is attributable to a specific user for SOX audit purposes. ClawSec's secret detection blocks prompts containing API keys, passwords, or AWS access keys before they reach the model. The audit trail records every query with user ID, role, IP address, request ID, and timestamp. The agent/auditor role split satisfies segregation of duties at the code level — not just in documentation.

ClawSec's strongest contribution is the completeness of its security envelope. The combination of policy engine, RBAC, audit trail, container hardening, Kubernetes manifests, and pre-built observability in a single Apache 2.0 licensed repository is rare. Most open-source AI security projects address one or two of these concerns. ClawSec addresses all of them with a test suite that validates the controls end-to-end.

The primary limitation is reliance on static regex patterns. Adversarial prompt injection using character substitution, Unicode lookalikes, or multi-turn decomposition will not be caught by string matching alone. A semantic analysis layer using a small local classifier would raise the detection ceiling without breaking the existing architecture — the validate_input() pipeline is explicitly designed to be extended. The POST /token endpoint also requires an IdP replacement in production, which the README's production checklist calls out directly and honestly.

ClawSec by Mohnish Basha is a production-ready answer to a real and growing problem. Its policy engine covers 13 injection attack families and 10 credential patterns. Its RBAC system implements a principled four-role permission matrix enforced at middleware. Its governance module writes immutable, privacy-respecting audit records for every security-relevant event. Its observability stack provides real-time security metrics from day one. Its container and Kubernetes configurations enforce defense-in-depth at the runtime layer. It is free to use and modify under the Apache 2.0 license.

LLM security is not a feature you add after launch. It is the structure you build around the model call from the first line of code. ClawSec shows exactly what that structure looks like in Python, FastAPI, and Kubernetes — with a test suite that proves the controls work and a production checklist that is honest about what still needs to be configured for your specific environment.

requirements.txt (from repo)

Dockerfile overview (multi-stage, non-root)

Example pull request workflow

Security demo: blocked vs allowed requests

1. ClawSec — Secure LLM Agent Framework (Apache 2.0) — github.com/mohnishbasha/clawsec

2. FastAPI — fastapi.tiangolo.com

3. OpenTelemetry Python SDK — opentelemetry.io/docs/languages/python

4. OWASP Agentic Security Initiative — owasp.org/www-project-agentic-security-initiative

5. NIST AI Risk Management Framework — nist.gov/ai/rmf

6. Kubernetes Pod Security Standards — kubernetes.io/docs/concepts/security/pod-security-standards

Bibliography

Basha, Mohnish. ClawSec: Secure LLM Agent Framework. Apache 2.0. GitHub, 2026.
OWASP Foundation. Agentic Security Initiative Top 10. OWASP, 2025.
NIST. AI Risk Management Framework (AI RMF 1.0). NIST, 2023.
NIST. Adversarial Machine Learning: A Taxonomy and Terminology. NIST AI 100-2, 2023.

Appendix A — Source Modules

main.py · rbac.py · policy_engine.py · governance.py · agent.py · observability.py

Appendix B — Prometheus Metrics

llm_requests_total · policy_violations_total · pii_redactions_total · rbac_denials_total · audit_events_total · llm_request_duration_seconds

© 2026 Snackon AI · www.snackonai.com · Analysis based on github.com/mohnishbasha/clawsec (Apache 2.0).

This guide distills 10 AI strategies from industry leaders that are transforming marketing.

Outpace your competitors by mastering AI.

Get Your Free Guide