How promptdefender/promptdefender works
Purpose and API Surface
PromptDefender is a serverless, multi-layer prompt-security service for applications using arbitrary LLM providers. Its public REST contract is defined in api/openapi.yml and generated into the Go user Lambda at cmd/lambda_user/api.gen.go. Terraform provisions API Gateway and routes requests to layer-specific Lambdas (terraform/gateway.tf, terraform/lambda_user.tf, terraform/lambda_wall.tf, terraform/lambda_keep.tf).
Wall: Input Screening
Wall is the first request-defense stage. The Python Lambda receives prompt content and detects/sanitizes suspicious input, including jailbreak terms, PII, bad words, and user/IP probing behavior. Its handler and core rules are in cmd/lambda_wall_py/app.py, cmd/lambda_wall_py/badwords.py, and cmd/lambda_wall_py/injections_embeddings.csv. It uses cached state and runtime configuration through DynamoDB- and SSM-backed adapters in cmd/lambda_wall_py/cache/ddb_cache.py and cmd/lambda_wall_py/settings/ssm_retriever.py.
Keep: Prompt Hardening
Keep transforms or wraps an application's prompt with defensive instructions before the application sends it to an LLM. The Python Lambda entry point is cmd/lambda_keep_py/app.py; shared request behavior is in cmd/lambda_keep_py/shared.py. Like Wall, it obtains settings and cache state behind pluggable interfaces, with DynamoDB cache implementation at cmd/lambda_keep_py/cache/ddb_cache.py and Parameter Store retrieval at cmd/lambda_keep_py/settings/ssm_retriever.py.
User and Session Risk State
A dedicated Go Lambda manages user records used for tracking and banning suspicious users across requests. CRUD handlers live in cmd/lambda_user/create.go, cmd/lambda_user/retrieve_single.go, and cmd/lambda_user/delete.go. The Lambda depends on a repository abstraction (internal/user_repository/users_repository.go) with a DynamoDB implementation (internal/user_repository_ddb/users_repository_ddb.go), separating HTTP/Lambda handling from persistence.
Response Validation Library
Drawbridge is represented as reusable Go functionality rather than a deployed Lambda in this tree. pkg/canary/canary.go checks for canary leakage in LLM responses, while pkg/canary/intermediate_canary_checks.go supports intermediate validation and response cleanup policy. Consumers can apply this after invoking their own LLM, forming the outbound counterpart to Wall and Keep.
ML/Embedding Build Pipeline
Jailbreak data and embeddings are prepared offline, not generated in request paths. builder/build.go coordinates build work; builder/clean_jailbreaks_into_json.py normalizes source jailbreak data and builder/jailbreak_embeddings.py produces embeddings. Python dependency layers are built separately from cmd/deps/cmd/embeddings_layer/requirements.txt and cmd/deps/cmd/langchain_layer/requirements.txt, with scripts under scripts/.
AWS Infrastructure and Operations
The runtime is AWS Lambda (Python for Wall/Keep, Go for user management), API Gateway, DynamoDB cache/user storage, and AWS Systems Manager Parameter Store. Main environment provisioning is split between terraform/ and the prerequisite Hugging Face/deBERTa infrastructure in terraform-base-infrastructure/huggingface.tf. Shared AWS request logging and tracing wrappers reside in internal/base_aws/aws_request_log.go and internal/tracer/tracer_wrapper.go. Deployment, security scanning, and validation are automated by GitHub workflows including .github/workflows/deploy.yml and .github/workflows/trivy.yml.
Components 23
Request Security Runtime
- Public REST contract
api/openapi.yml - API Gateway · Routes layer-specific API requests to Lambdas.
terraform/gateway.tf - Wall screening Lambda · Screens and sanitizes incoming prompt content.
cmd/lambda_wall_py/app.py - Wall detection rules · Jailbreak, PII, bad-word, and probing detection inputs.
cmd/lambda_wall_py/badwords.py - Keep hardening Lambda · Wraps application prompts with defensive instructions.
cmd/lambda_keep_py/app.py - Keep request behavior
cmd/lambda_keep_py/shared.py - User management Lambda · CRUD and ban-tracking API for suspicious users.
cmd/lambda_user/create.go - Generated user API
cmd/lambda_user/api.gen.go - User repository abstraction
internal/user_repository/users_repository.go - Drawbridge response checks · Checks LLM responses for canary leakage and cleanup policy.
pkg/canary/canary.go - Consumer LLM call · Applications invoke their own LLM provider after hardening.
AWS State & Configuration
- DynamoDB · Stores cache state and user records.
- Parameter Store · Supplies runtime settings.
- Wall DynamoDB cache adapter
cmd/lambda_wall_py/cache/ddb_cache.py - Keep SSM settings adapter
cmd/lambda_keep_py/settings/ssm_retriever.py - DynamoDB user repository
internal/user_repository_ddb/users_repository_ddb.go
Offline ML Build
- Embedding build pipeline · Normalizes jailbreak data and generates embeddings outside request paths.
builder/build.go - Jailbreak data normalization
builder/clean_jailbreaks_into_json.py - Jailbreak embedding generation
builder/jailbreak_embeddings.py - Python dependency layers · Embeddings and LangChain dependencies are packaged separately.
cmd/deps/cmd/embeddings_layer/requirements.txt
Provisioning & Operations
- Terraform deployment · Provisions gateway and layer-specific Lambdas.
terraform/lambda_wall.tf - Hugging Face/deBERTa infra
terraform-base-infrastructure/huggingface.tf - Deployment & security automation
.github/workflows/deploy.yml
Connections 27
- Public REST contract → Generated user API: generated into
- Public REST contract → API Gateway: defines API
- API Gateway → Wall screening Lambda: routes screening requests
- API Gateway → Keep hardening Lambda: routes hardening requests
- API Gateway → User management Lambda: routes user requests
- Wall screening Lambda → Wall detection rules: applies
- Wall screening Lambda → Wall DynamoDB cache adapter: uses
- Wall DynamoDB cache adapter → DynamoDB: reads/writes state
- Keep hardening Lambda → Keep request behavior: uses
- Keep hardening Lambda → Keep SSM settings adapter: loads settings through
- Keep SSM settings adapter → Parameter Store: retrieves
- Keep hardening Lambda → Consumer LLM call: hardened prompt
- Consumer LLM call → Drawbridge response checks: response validation
- User management Lambda → User repository abstraction: depends on
- User repository abstraction → DynamoDB user repository: implemented by
- DynamoDB user repository → DynamoDB: persists users
- Embedding build pipeline → Jailbreak data normalization: coordinates
- Embedding build pipeline → Jailbreak embedding generation: coordinates
- Jailbreak embedding generation → Wall detection rules: produces embedding data
- Python dependency layers → Wall screening Lambda: runtime dependencies
- Python dependency layers → Keep hardening Lambda: runtime dependencies
- Terraform deployment → API Gateway: provisions
- Terraform deployment → Wall screening Lambda: deploys
- Terraform deployment → Keep hardening Lambda: deploys
- Terraform deployment → User management Lambda: deploys
- Hugging Face/deBERTa infra → Jailbreak embedding generation: supports model prerequisites
- Deployment & security automation → Terraform deployment: deploys and validates