Only QWED v7.x is currently supported with security patches and updates. Versions 6.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.HashiCorp Vault integration
If you use Vault, you can useenvconsul or the Vault Agent Injector to populate environment variables before the application starts.
Critical secrets
Required secrets
Changed in v5.0.0
API_KEY_SECRET is now mandatory — the server will not start without it. Generate one with:
Changed in v7.2
QWED_API_KEY_LOOKUP_SECRET (required — the server fails at startup if it is missing or equal to QWED_JWT_SECRET_KEY). Rotating this secret invalidates all existing API-key digests and requires re-issuing every key, so treat it as long-lived. See Authentication.
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)
2. Network security
Firewall rules
Restrict network access to the QWED API server:- Public Access: Allow ports
80/443only 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:
Example:
Thread-safe in-memory limiter
New in v5.0.0
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. TheQWED_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
* 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:
*, 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 thePOST /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
bcrypthashing provided by QWED’s authentication module.
Session management
Control the lifetime of access tokens to reduce the window of opportunity for session hijacking.
Recommendation: Set this to a lower value (e.g.,
15 or 30 minutes) and implement refresh tokens if needed.
All-tenant metrics authorization
Changed in v7.2
GET /metrics and GET /metrics/prometheus expose cross-tenant data: request volumes, latencies, provider usage, and per-tenant breakdowns for every organization. Access is a platform-operator capability controlled by an explicit allowlist, not an organization role:
GET /metrics/{organization_id}) are unchanged and remain scoped to the caller’s own organization.
4. Enhanced prompt injection defense
New in v4.0.0
EnhancedSecurityGateway (OWASP LLM01:2025 compliant) that screens all inputs through seven defense layers:
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 centralizedredact_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
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.
Sandbox containment limits
Every sandbox container runs with hard resource and output bounds, and is always removed after execution:- Process cap —
pids_limit: 128prevents fork bombs from exhausting kernel PIDs, alongside the existing memory and CPU limits. - Log rotation — container logs use the
json-filedriver withmax-size: 10mandmax-file: 1, so a log-flooding payload cannot fill the host disk. - Guaranteed cleanup — the container is force-removed in a
finallyblock covering the whole post-creation lifecycle, including start failures, with one retry for transient daemon races. A cleanup failure is logged as a warning and never discards a valid verification result. - Result size cap — the sandbox result file is capped at 2 MB, enforced both inside the container during serialization and at host read-back. Result payloads stored in the verification audit log are additionally capped and always remain valid JSON, so the audit integrity verifier can parse capped entries.
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 CodeVerifierraisesImportError(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.
_build_fail_closed_safety_denial() helper, so the response is deterministic. SecureCodeExecutor.execute() returns:
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:
/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
CodeVerifiercannot 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 reachescontainers.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: <reason>"), but it can never authorize execution on its own.
Default-deny for unknown tool approvals
New in v5.1.0
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 '<name>' requires explicit allowlisting".
Safe expression evaluation
Alleval() 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 and validates every node against a strict allow-list. It then interprets the tree directly — no eval() or compile() is ever invoked.
The safe evaluator enforces three layers of defense:
- 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. - CodeGuard integration — when the full
qwed_newpackage is available, expressions are additionally screened byCodeGuardbefore execution. - 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, onlyAnd,Or,Not,Implies,If,Int,Bool, andRealare permitted.
- Keyword unpacking (
**kwargsviaNone-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
Theqwed init wizard and YAML provider config system write .env files with strict security guarantees:
.envfiles written with0600permissions (owner-only on Unix)- Atomic writes via
tempfile+os.replaceto prevent partial writes - Symlink attack prevention (
O_NOFOLLOWon Unix) - Automatic
.gitignoreverification ensures.envis 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. 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
.pthstartup hook files against a built-in allowlist. If any unrecognized.pthfile is found, the server refuses to start. You can extend the allowlist for custom deployments using theQWED_ALLOWED_STARTUP_PTH_FILESenvironment variable (comma-separated list of filenames).If you need to bypass the environment integrity check entirely (for example, in development environments with non-standard.pthfiles), setQWED_SKIP_ENV_INTEGRITY_CHECK=true. The server will log a warning when this bypass is active. -
Startup hook detection: Use
StartupHookGuardto scan for malicious.pthfiles in Pythonsite-packagesbefore 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.
6. Secret-scanning webhook intake
New in v7.3.0
POST /webhooks/secret-scanning endpoint accepts signed reports of leaked QWED API keys from GitHub secret scanning and compatible partner scanners. Because the endpoint must be reachable by external scanners with no QWED credentials, it is unauthenticated at the transport layer — the ECDSA signature over the raw request body is the only credential, and the intake is fail-closed at every step.
Trust model
- Raw-body signature verification. The signature is verified over the exact request bytes, in the exact order they arrived, before any JSON parsing, logging, or database work. Reformatting the payload would break the signature, so QWED never re-serializes the body.
- P-256 pinning at key-load. Signing keys fetched from
https://api.github.com/meta/public_keys/secret_scanningare pinned tosecp256r1(ECDSA-NIST-P256V1-SHA256) when the PEM is loaded, not at verify time. A future keys-list entry on another curve is dropped at load, never silently trusted. - 6h key cache with one-shot rotation refetch. Signing keys are cached in-process for 6 hours. A conditional (
ETag/If-None-Match) refetch keeps a stable key list quiet. If verification fails against an unknownkey_identifier, QWED refetches the list exactly once (throttled to at most one forced refetch per 60 seconds after a success, 10 seconds after a failure) and retries; anything still unknown fails closed. - Timing-safe verdict comparison. Signature success and failure paths run through
hmac.compare_digeston a fixed-shape verdict so the two branches are not distinguishable by timing. Every failure — missing headers, malformed base64, unknown key, off-spec curve, bad signature — returns the same generic 401/403 detail. - Tokens never logged. The receipt log line records the match count and the per-source breakdown only. Token values never appear in logs, error messages, or metrics.
- Fail-closed status separation.
401is missing headers,403is a proven-bad signature against a fresh trust anchor, and503is any state where verification was impossible (signing-key service unreachable, cached anchor unusable, rotation retry throttled). The scanner should redeliver on503.
Envelope limits
Bounded work is enforced before and after the crypto:- Request body capped at 1 MiB, checked incrementally on read (an over-cap body is rejected the instant the cap is exceeded — the endpoint never buffers an unbounded unsigned body).
- Matches per request capped at 500.
- Individual
tokenfield capped at 512 characters. - Signature header capped at 1024 characters before base64 decode.
Configuration
The endpoint works with no configuration — QWED fetches GitHub’s public keys anonymously. Two optional environment variables raise the rate limit on the outbound keys request by attaching a bearer token:
Neither token grants any authority on the incoming request; only the ECDSA signature does.
Automatic revocation of leaked keys
After a report passes signature verification, QWED returns200 to the scanner and processes the verified matches in the background. For each reported token, QWED computes the API-key lookup digest and acts on the result:
Handling is idempotent. If the same leak is redelivered, or two deliveries race, exactly one revokes the key and sends the email. The other is treated as already revoked. Scanners report only
qwed_live_ keys — the API key format spec excludes qwed_test_ keys from detection — so test keys never reach revocation. The revocation sink itself does not filter by prefix.
Revoked keys stop authenticating right away. The owner must issue a replacement key and rotate every service that used the old one.
Audit trail. The SECRET_LEAK_AUTO_REVOKED security event records the key’s key_preview, the scanner source, and the reported URL. The plaintext token is never written to the database, logs, or email. If the scanner echoes the token inside the URL or other metadata, QWED redacts it to [REDACTED] first.
Owner notification. QWED sends the email to the user who owns the key. If that user is inactive or has no email address, QWED falls back to the first active owner or admin of the key’s organization. The email subject is [QWED Security] QWED API key auto-revoked after public exposure. The body includes the key preview, key name, where the key was found, and the report source. Notification uses the SMTP settings from SMTP_HOST, SMTP_PORT, SMTP_USER, and SMTP_PASSWORD, with a 10-second timeout on every SMTP phase. Owner emails are never throttled, because each revocation is a distinct event.
Each revocation is committed separately, so one failing row cannot undo revocations for other keys in the same batch. If any row fails, QWED still processes the remaining matches, then logs the batch as failed.
False-positive feedback reporter
QWED can report a label for each verified match back to the scanning service. Scanners use these labels to improve detection quality over time. The reporter is opt-in and disabled by default. A match is labeledtrue_positive when its lookup digest matches a real API key (active or revoked), and false_positive when nothing matches. QWED computes the labels with a single read-only lookup before revocation. It sends them after the revocation step, whether that step succeeded or failed. The feedback request never delays revocation. It uses a 5-second timeout, and delivery failures are logged and dropped.
By default, each item carries the SHA-256 hash of the token, never the plaintext:
token_hash or token_raw, never both.
Raw mode transmits live secrets back out of your deployment. Enable
QWED_LEAK_FEEDBACK_SEND_RAW only when the receiving scanner requires plaintext tokens. In raw mode, QWED emits no feedback log lines, so delivery results are not logged.POST /webhooks/secret-scanning reference for the request/response contract and the full status-code table.
7. 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. 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.