> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Prompt injection defense and QWED security hardening
> Harden QWED for production with prompt injection defense, secret management, network security, authentication, and OWASP LLM Top 10 compliance.
This guide provides instructions for hardening your QWED deployment for production environments. It covers prompt injection defense, secret management, network security, authentication, and compliance with OWASP LLM Top 10.
Only **QWED v5.x** is currently supported with security patches and updates. Versions 4.x and earlier are end-of-life. If you are running a prior version, upgrade before applying the guidance below.
## 1. Secret management
QWED relies on environment variables for sensitive configuration. **Never commit `.env` files to version control.**
### Environment variable injection
For production deployments, inject environment variables using your infrastructure's secret management solution.
#### Docker / Kubernetes
Use Kubernetes Secrets or HashiCorp Vault to inject secrets as environment variables into the container.
```yaml theme={null}
# Example Kubernetes Pod Spec
env:
- name: OPENAI_API_KEY
valueFrom:
secretKeyRef:
name: qwed-secrets
key: openai-api-key
- name: JWT_SECRET_KEY
valueFrom:
secretKeyRef:
name: qwed-secrets
key: jwt-secret
```
#### HashiCorp Vault integration
If you use Vault, you can use `envconsul` or the Vault Agent Injector to populate environment variables before the application starts.
```bash theme={null}
# Example with envconsul
envconsul -prefix qwed/prod/ qwed-api
```
### Critical secrets
### Required secrets
Changed in v5.0.0
`API_KEY_SECRET` is now **mandatory** — the server will not start without it. This secret is used for PBKDF2 API-key hashing. Generate one with:
```bash theme={null}
python -c "import secrets; print(secrets.token_urlsafe(48))"
```
Ensure these secrets are rotated regularly:
* `API_KEY_SECRET` (used for API key hashing — **required**)
* `OPENAI_API_KEY` (and other provider keys)
* `API_KEY_SECRET` (used for signing JWTs — **mandatory**, the server will not start without it)
* `JWT_SECRET_KEY` (used for signing session tokens)
* `DATABASE_URL` (if using an external database)
As of v5.0.0, `API_KEY_SECRET` no longer has a default value. You must set it explicitly before starting the server. Generate a secure value with:
```bash theme={null}
python -c "import secrets; print(secrets.token_urlsafe(48))"
```
***
## 2. Network security
### Firewall rules
Restrict network access to the QWED API server:
* **Public Access**: Allow ports `80` / `443` only via a Load Balancer / WAF.
* **Internal Access**: The QWED application port (default `8000`) should **not** be directly exposed to the internet.
* **Database**: Block all public access to the database port (e.g., `5432`). Only allow connections from the QWED application subnet.
### Rate limiting (production)
QWED includes a default in-memory rate limiter that is thread-safe — all check and record operations are protected by a lock, so it is safe to use with multi-threaded ASGI servers. For production, you should tune these limits and consider a distributed solution.
#### Configuration
You can adjust the rate limits using environment variables:
| Environment Variable | Default | Description |
| -------------------------------- | ------- | ---------------------------------------- |
| `RATE_LIMIT_REQUESTS_PER_MINUTE` | `100` | Max requests per minute **per API key**. |
| `RATE_LIMIT_WINDOW_SECONDS` | `60` | Time window in seconds. |
**Example:**
```bash theme={null}
export RATE_LIMIT_REQUESTS_PER_MINUTE=50
export RATE_LIMIT_WINDOW_SECONDS=60
```
#### Thread-safe in-memory limiter
New in v5.0.0
The in-memory rate limiter is now thread-safe. All check-and-record operations are protected by a lock, which prevents race conditions when multiple threads handle concurrent requests in a single process. This eliminates a class of bypass where two requests arriving simultaneously could both pass the limit check before either was recorded.
#### Redis backing (recommended)
The default in-memory limiter does not scale across multiple worker processes or replicas. For high-availability deployments, use a Redis-backed rate limiter to ensure consistent enforcement across your cluster.
The Redis-backed rate limiter uses a **fail-closed** policy. If Redis becomes unreachable at runtime, requests are denied rather than allowed through. This prevents a Redis outage from silently disabling rate limiting. An in-memory fallback is only used when Redis is unavailable at initialization time.
### CORS configuration
QWED requires you to explicitly configure allowed CORS origins. The `QWED_CORS_ORIGINS` environment variable must be set to a comma-separated list of trusted domains — the server will refuse to start if this variable is empty or unset.
Changed in v5.0.0
QWED no longer defaults to `*` for CORS origins. The `QWED_CORS_ORIGINS` environment variable is **required** — the server will refuse to start if it is not set.
Set it to a comma-separated list of trusted origins:
```bash theme={null}
export QWED_CORS_ORIGINS="https://app.yourcompany.com,https://admin.yourcompany.com"
```
Previous versions defaulted to allowing all origins (`*`) for development convenience. As of v5.0.0, CORS origins must be explicitly configured. If you need to allow all origins during local development, set `QWED_CORS_ORIGINS="*"` — but never use this in production.
When the origin list is set to `*`, the `allow_credentials` CORS header is automatically set to `false` to prevent credential leakage. For specific origin lists, credentials are allowed.
If you were previously relying on the default `*` origin, you must now explicitly set `QWED_CORS_ORIGINS` before upgrading. This is a breaking change in v5.0.0.
When `QWED_CORS_ORIGINS` is set to a wildcard (`*`), credentialed requests (`allow_credentials`) are automatically disabled to comply with the CORS specification.
***
## 3. Authentication hardening
### API key rotation
Regularly rotate API keys to minimize the impact of a potential leak.
QWED provides a built-in rotation mechanism via the `POST /admin/keys/rotate` endpoint. Old keys should be revoked immediately after the rotation window.
### Password policies
If you integrate QWED with a custom user database:
* Enforce a minimum length of 12 characters.
* Require a mix of uppercase, lowercase, numbers, and special characters.
* Use the built-in `bcrypt` hashing provided by QWED's authentication module.
### Session management
Control the lifetime of access tokens to reduce the window of opportunity for session hijacking.
| Environment Variable | Default | Description |
| --------------------------------- | ------- | --------------------------------------- |
| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | `60` | Minutes until the access token expires. |
**Recommendation:** Set this to a lower value (e.g., `15` or `30` minutes) and implement refresh tokens if needed.
```bash theme={null}
export JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
```
***
## 4. Enhanced prompt injection defense
New in v4.0.0
QWED v4.0.0 introduces a multi-layer `EnhancedSecurityGateway` (OWASP LLM01:2025 compliant) that screens all inputs through seven defense layers:
| Layer | Defense | Description |
| ----- | --------------------- | ------------------------------------------------------------------------------------------- |
| 1 | Pattern detection | Heuristic matching against 14 known injection patterns |
| 2 | Length limiting | Strict 2,000-character limit (blocks \~70% of injection attacks) |
| 3 | Base64 decoding | Detects and decodes base64-encoded payloads, then scans for injection keywords |
| 4 | Semantic similarity | Uses sequence matching against system prompt (threshold: 0.6) |
| 5 | Keyword detection | 28 high-risk keywords: `disregard`, `override`, `bypass`, `jailbreak`, etc. |
| 6 | Unicode script mixing | Detects Cyrillic/Arabic/Greek characters mixed with Latin (homoglyph attacks) |
| 7 | Zero-width characters | Detects invisible characters (`\u200B`, `\u200C`, `\u200D`, `\uFEFF`) used to hide payloads |
The gateway is enabled by default for all API endpoints. It also includes a block counter for monitoring injection attempt frequency.
### PII redaction
All API error paths now use a centralized `redact_pii()` function that masks email addresses, phone numbers, SSNs, and IP addresses before they reach logs. Stack traces are suppressed in error responses (`exc_info=False`) to prevent data leakage.
### Fail-closed code execution
New in v4.0.4
All model-generated Python code — in both the Stats and Consensus engines — runs exclusively inside a Docker sandbox (`SecureCodeExecutor`). The in-process Wasm and restricted execution fallbacks that existed in earlier versions have been permanently disabled.
If the Docker daemon is unreachable, the affected endpoints return HTTP 503 rather than degrading to an insecure execution mode. The executor performs a live health check (`docker.ping()`) on every request to detect runtime failures that would not be caught by a startup-time flag.
This design ensures that a Docker outage is surfaced as a visible service disruption rather than silently downgrading security.
#### Fail-closed when `CodeVerifier` is unavailable or failing
Updated May 2, 2026
`SecureCodeExecutor` delegates code-safety verification to `qwed_new.core.code_verifier.CodeVerifier`. The executor now blocks execution in two scenarios that previously could downgrade safety:
* **Import failure** — `from qwed_new.core.code_verifier import CodeVerifier` raises `ImportError` (for example, after a partial install or version mismatch).
* **Runtime failure** — `CodeVerifier.verify_code()` raises any unexpected exception (for example, an internal engine error). The exception is caught, sanitized, and logged; it is not surfaced to API callers.
Both cases route through the same `_build_fail_closed_safety_denial()` helper, so the response is deterministic. `SecureCodeExecutor.execute()` returns:
```python theme={null}
success = False
error = "Code safety validation failed: CodeVerifier unavailable; cannot validate code safety."
result = None
```
If the basic keyword scan would have flagged the input as dangerous, its reason is appended to the error message as advisory context only — it does not authorize execution:
```text theme={null}
Code safety validation failed: CodeVerifier unavailable; cannot validate code safety. Advisory-only fallback also flagged: dangerous operation
```
The container is never started in any of these cases. To restore execution, fix the underlying import error or runtime failure in `qwed_new.core.code_verifier`. Do not rely on the heuristic keyword scan as a substitute for the structured verifier.
#### Legacy `CodeExecutor` hard-blocked
The legacy `CodeExecutor` class — which previously used raw `exec()` to run model-generated Python — is now permanently hard-blocked. Any call to `CodeExecutor.execute()` raises a `RuntimeError` directing you to use `SecureCodeExecutor` instead.
If you import `CodeExecutor` directly in custom code or tests, you must migrate to `SecureCodeExecutor`:
```python theme={null}
# Before (raises RuntimeError)
from qwed_new.core.code_executor import CodeExecutor
executor = CodeExecutor()
executor.execute(code) # RuntimeError
# After
from qwed_new.core.secure_code_executor import SecureCodeExecutor
executor = SecureCodeExecutor()
result = executor.execute(code)
```
This change has no effect on the public API — the `/verify/stats` and `/verify/consensus` endpoints already use `SecureCodeExecutor` since v4.0.4. It only affects self-hosted deployments that imported `CodeExecutor` directly.
#### `CodeVerifier` failures block execution
If `SecureCodeExecutor` cannot use `CodeVerifier` (the primary structured safety verifier), it now fails closed and refuses to authorize execution. Earlier builds fell back to a basic keyword scan (`_basic_safety_check()`) as the authorization gate when the verifier was unavailable, which weakened the execution boundary from structured verification to heuristic filtering.
The hardened behavior covers both unavailability and runtime errors:
* **Import failure** — If `CodeVerifier` cannot be imported, the safety check returns `(False, "CodeVerifier unavailable; cannot validate code safety.")`.
* **Runtime failure** — If `CodeVerifier.verify_code()` raises any exception during validation, the executor logs a sanitized error and returns the same deterministic denial through the shared `_build_fail_closed_safety_denial()` helper. The exception message is not echoed to callers.
* **Execution blocked** — `SecureCodeExecutor.execute()` returns `(success=False, error="Code safety validation failed: ...", result=None)` and never reaches `containers.run()`.
* **Advisory-only keyword scan** — The basic keyword scan is retained only as diagnostic context. If it also flags the code, its reason is appended to the error message (`"... Advisory-only fallback also flagged: "`), but it can never authorize execution on its own.
This guarantees that a missing, broken, or crashing primary verifier surfaces as a blocked execution rather than a silent downgrade to heuristic-only filtering.
### Default-deny for unknown tool approvals
New in v5.1.0
The tool approval system now blocks all unknown tools by default, regardless of their heuristic risk score. In previous versions, tools with a risk score below `0.3` were automatically approved even if they were not in the allowlist. As of v5.1.0, any tool that is not explicitly allowlisted is denied unconditionally.
If you manage a custom tool allowlist, ensure all tools your agents use are explicitly registered. Unregistered tools return a blocked response with the message `"Unknown tool '' requires explicit allowlisting"`.
### Safe expression evaluation
All `eval()` calls have been fully eliminated and replaced with a custom AST-walking evaluator. Instead of compiling and executing code, the evaluator parses expressions into an AST, validates every node against a strict allow-list, and then interprets the tree directly — no `eval()` or `compile()` is ever invoked.
The safe evaluator enforces three layers of defense:
1. **AST allow-list** — only permitted node types (`Constant`, `Name`, `BinOp`, `UnaryOp`, `Call`, `Tuple`, `List`, and approved operators) pass validation. Unknown or dangerous nodes are rejected before evaluation.
2. **CodeGuard integration** — when the full `qwed_new` package is available, expressions are additionally screened by `CodeGuard` before execution.
3. **Restricted namespace** — the evaluator resolves symbols only from an explicit namespace. For SymPy paths, only whitelisted functions (e.g., `sqrt`, `sin`, `cos`, `log`, `Rational`, `pi`, `E`) are available. For Z3 paths, only `And`, `Or`, `Not`, `Implies`, `If`, `Int`, `Bool`, and `Real` are permitted.
Additional safeguards:
* Keyword unpacking (`**kwargs` via `None`-keyed keywords) is blocked in all call nodes
* `__` (double underscore) patterns are blocked to prevent attribute access attacks
* SymPy expressions use exact arithmetic (`sympy.Integer`, `sympy.Float`) to avoid floating-point drift during comparison
### Credential store security
The `qwed init` wizard and YAML provider config system write `.env` files with strict security guarantees:
* `.env` files written with `0600` permissions (owner-only on Unix)
* Atomic writes via `tempfile` + `os.replace` to prevent partial writes
* Symlink attack prevention (`O_NOFOLLOW` on Unix)
* Automatic `.gitignore` verification ensures `.env` is excluded from version control
* API keys are never printed in full — only the first 8 characters are shown in logs
***
## 5. OWASP LLM Top 10 compliance
QWED implements technical defenses for the [OWASP LLM Top 10](https://owasp.org/www-project-top-10-for-large-language-model-applications/). However, security is a shared responsibility.
### Your responsibilities (user/deployment)
While QWED handles internal verification, you must implement the following "Human in the loop" and deployment safeguards:
#### LLM01: Prompt injection and LLM02: Insecure output handling
* **Human in the loop**: For critical actions (e.g., financial transactions, code deployment), do not rely solely on QWED's verification. Implement a manual approval step.
* **Output monitoring**: Log and randomly audit verified outputs to ensure the verification engine itself hasn't been bypassed.
#### LLM05: Supply-chain vulnerabilities
* **Startup environment integrity**: QWED enforces environment integrity at startup by verifying all Python `.pth` startup hook files against a built-in allowlist. If any unrecognized `.pth` file is found, the server refuses to start. You can extend the allowlist for custom deployments using the `QWED_ALLOWED_STARTUP_PTH_FILES` environment variable (comma-separated list of filenames).
```bash theme={null}
export QWED_ALLOWED_STARTUP_PTH_FILES="my_custom_plugin.pth,internal_tool.pth"
```
If you need to bypass the environment integrity check entirely (for example, in development environments with non-standard `.pth` files), set `QWED_SKIP_ENV_INTEGRITY_CHECK=true`. The server will log a warning when this bypass is active.
```bash theme={null}
# Development only — do not use in production
export QWED_SKIP_ENV_INTEGRITY_CHECK=true
```
* **Startup hook detection**: Use [`StartupHookGuard`](/sdks/guards#startuphookguard) to scan for malicious `.pth` files in Python `site-packages` before your application starts. This defends against supply chain attacks that inject code-execution hooks via compromised PyPI packages.
* **Network Isolation**: Run the QWED backend in a VPC without direct outbound internet access, except to specific LLM provider APIs (allowlist).
* **Dependency Scanning**: Regularly scan your deployment container for vulnerabilities in system packages.
#### LLM06: Sensitive information disclosure
* **Data minimization:** Do not send PII (Personally Identifiable Information) to QWED unless required. Mask or redact sensitive data *before* it reaches the API.
For related deployment controls, see [Architecture overview](/architecture), [SDK guards](/sdks/guards), and [Troubleshooting guide](/troubleshooting).
***
## 6. Reporting a vulnerability
If you discover a security vulnerability in QWED, do **not** report it through public GitHub issues, pull requests, or discussions.
Instead, report it privately via email to **[rahul@qwedai.com](mailto:rahul@qwedai.com)**. If GitHub private vulnerability reporting is enabled for the repository, you may use that channel as well.
Include as much detail as possible:
* Steps to reproduce the issue
* Affected version(s)
* Relevant code, configuration, logs, or screenshots
* Proof-of-concept or exploit details, if available
* The potential impact on confidentiality, integrity, or availability
### Response timeline
* Your report will be acknowledged within **24 hours**
* The team will triage and validate the report as quickly as possible
* You will be kept informed of progress during investigation and remediation
* Disclosure timing will be coordinated with you when appropriate
### Coordinated disclosure
Please give the maintainers a reasonable amount of time to investigate and remediate the issue before making any public disclosure. You should:
* Avoid publicly disclosing the issue until a fix or mitigation is available
* Make a good-faith effort to avoid privacy violations, data destruction, or service disruption
* Avoid accessing, modifying, or exfiltrating data beyond what is necessary to demonstrate the issue
### Security issue vs. bug
* **Security issue** — A vulnerability that compromises the confidentiality, integrity, or availability of the system, such as code execution, injection, auth bypass, privilege escalation, sensitive data exposure, sandbox escape, or fail-open security behavior. Report these privately as described above.
* **Bug** — A functional defect or unexpected behavior that does not have security implications, such as a UI issue, incorrect calculation, documentation problem, or non-exploitable crash. Report these via the [GitHub Issue Tracker](https://github.com/QWED-AI/qwed-verification/issues).