Quarkus applications enforce security across reactive boundaries, CDI dependency injection scopes, and enterprise authentication channels. The framework protects HTTP routes, REST endpoints, and messaging pipelines by default, while requiring explicit configuration for authorization, CORS, secrets, and native reflections. Developers must ensure that all security mechanisms fail closed and that sensitive endpoints, management interfaces, and telemetry exposures are strictly isolated.
Essential implementation rules
Configure Least-Privilege Kubernetes RBAC and Namespace Scoping
Specify exact resource names, API groups, and targeted verbs in application properties for Kubernetes roles and prefer namespace-scoped roles over cluster-wide privileges.
Enforce Strict CORS and Avoid Wildcard Origins
Enable CORS filters using quarkus.http.cors.enabled=true, define explicit trusted origins via quarkus.http.cors.origins, and avoid mixing programmatic builders with property configurations.
Protect Jakarta REST Endpoints with Declarative Security Annotations
Secure endpoints using @RolesAllowed, @Authenticated, or @PermissionsAllowed, and enable default denial of unannotated routes via quarkus.security.jaxrs.deny-unannotated-endpoints=true.
Manage CDI Dependency Injection Scopes and Lifecycles Securely
Qualify persistence units explicitly using @PersistenceUnit, access normal-scoped bean state via getters and setters, and ensure dependent Arc bean instance handles are properly closed.
Verify OIDC and JWT Tokens, Signatures, and Certificate Chains
Validate token signatures, algorithms, exact issuer strings, and audience properties explicitly while enabling access token certificate binding in mTLS environments.
Prevent Observability Data and Telemetry Exposure
Restrict access to in-memory trace data export endpoints, keep OpenTelemetry user principal attribute export disabled by default, and disable logging exporters in production environments.
Enforce Extension Catalog and Configuration Integrity
Declare explicit BOM origins, exact artifact coordinates, and platform capabilities in extension catalogs while separating static build-time configurations from runtime overrides.
Hash Passwords Securely and Configure Cryptographic Keys
Pass plain-text passwords through BcryptUtil.bcryptHash() prior to database persistence and generate cryptographically sound keys with sufficient sizes using KeyUtils.
Configure CSRF Prevention and Token Verification for Web Forms
Set quarkus.rest-csrf.token-signature-key with a secure secret of at least 32 characters and embed hidden CSRF token input fields inside Qute HTML templates.
Use Type-Safe Deserializers and Strict JSON Configurations
Configure structured type-safe deserializers like ObjectMapperDeserializer for messaging channels and enable strict JSON parsing by setting quarkus.jackson.fail-on-unknown-properties=true.
Isolate and Secure Management and Health Endpoints
Place management endpoints on a dedicated internal network interface and port using quarkus.management.enabled=true, enforce HTTP basic auth, and enable TLS encryption.
Configure Reflection and Native Initialization for GraalVM Images
Register reflectively accessed classes explicitly using @RegisterForReflection, defer random number generator initialization to runtime, and avoid side effects during static initialization.
Load Sensitive Credentials Securely Using External Stores
Inject sensitive database passwords and client secrets dynamically using Quarkus CredentialsProvider or environment variables rather than embedding plain text credentials in configuration files.
Set Secure and HttpOnly Attributes on Session Cookies
Ensure form-based authentication and OIDC session cookies are protected by enabling HttpOnly and secure attributes to prevent client-side script access and unencrypted transmission.
quarkus: All Security Cards
Approximately 8,968 tokens
On this card
Category: access control
Configure Explicit Least-Privilege Kubernetes RBAC and Namespace Scoping
Use when
Configuring Kubernetes RBAC permissions and role bindings using Quarkus deployment properties for application workloads.
Secure rules
Rule 1: Declare explicitly bounded policy rules with minimal required API groups, resources, and verbs in application properties
Avoid granting administrative or wildcard permissions in Role and ClusterRole definitions. Specify exact resource names and targeted verbs to prevent excessive privileges if the application container is compromised.
Rule 2: Prefer namespace-scoped Roles and RoleBindings over ClusterRoles and ClusterRoleBindings
Limit workload permissions to their own deployment namespace when global cluster access is not required, thereby reducing the blast radius and preventing cross-namespace resource access.
Configure Strict CORS Origins, Methods, and Credentials in Quarkus
Use when
Developing or configuring cross-origin resource sharing (CORS) rules in Quarkus applications via application properties, programmatic builders, or CDI observers.
Secure rules
Rule 1: Explicitly define allowed CORS origins and avoid wildcard configurations in production environments.
Enable the CORS filter using quarkus.http.cors.enabled=true and specify trusted origins via quarkus.http.cors.origins. Avoid using wildcard origins (*) in production unless the API is entirely read-only with no side effects or credential handling.
Rule 3: Avoid mixing programmatic and property-based CORS configurations
If CORS options are configured in application.properties, calling HttpSecurity.cors(...) programmatically throws an IllegalStateException. Choose a single configuration method and use the CORS builder to specify required options explicitly.
Restrict REST Endpoints and Web Resources Using Declarative Security Annotations
Use when
Enforcing access control, authentication, and role checks on JAX-RS endpoints, controllers, and web application paths.
Secure rules
Rule 1: Protect Jakarta REST endpoints using standard authorization annotations such as @RolesAllowed, @Authenticated, or @PermitAll to restrict access to authorized callers.
Annotate secure methods explicitly with required roles using @RolesAllowed, or require general authentication using @Authenticated. To prevent accidental exposure of unannotated resources, configure quarkus.security.jaxrs.deny-unannotated-endpoints=true in application.properties to apply @DenyAll access control defaults to all Jakarta REST endpoints lacking explicit security annotations.
Rule 2: Enforce HTTP path permissions and security policies to secure web application routes and virtual paths.
Configure explicit HTTP auth permission paths and policies in application.properties such as quarkus.http.auth.permission.authenticated.paths to ensure protected paths enforce the authenticated policy and prevent unauthenticated access to virtual paths.
Rule 3: Enforce fine-grained method-level permissions using @PermissionsAllowed and custom permission checkers.
Annotate service methods and CDI beans with @PermissionsAllowed to enforce granular checks. Ensure custom permission checker methods are non-private, non-static CDI methods returning boolean or Uni<Boolean>, annotated with @PermissionChecker.
@ApplicationScopedpublic class OrderService { @PermissionsAllowed("order:create") public Uni<Void> createOrder() { return Uni.createFrom().nullItem(); }}
Category: api contract misuse
Configure valid OpenAPI filter execution stages and document names
Use when
When registering custom OpenAPI filters to sanitize or adjust API schemas using Quarkus smallrye-openapi.
Secure rules
Rule 1: Declare valid execution stages and matching document names when using @OpenApiFilter.
Ensure that custom OpenAPI filters configure explicit non-empty execution stages and valid document names. Mismatched document names or empty stages will trigger build-time errors and cause custom security filters to be skipped.
@OpenApiFilter( stages = {OpenApiFilter.RunStage.BUILD}, documentNames = {OpenApiFilter.DEFAULT_DOCUMENT_NAME})public class CustomSecurityOpenApiFilter implements OASFilter { // Custom OASFilter implementation to adjust security schema}
Manage CDI Dependency Injection Scopes and Lifecycles Securely in Quarkus
Use when
Developing Quarkus applications using CDI dependency injection where normal-scoped beans, request contexts, programmatic lookups, and persistence units are configured.
Secure rules
Rule 1: Ensure request contexts are active and restrict policy execution to Jakarta REST endpoints when injecting request-scoped beans into security policies.
Standard HTTP authorization runs before Quarkus prepares certain request-scoped beans. To prevent context resolution failures, restrict policy execution to Jakarta REST endpoints by configuring applies-to=jaxrs in application properties or by using the AuthorizationPolicy annotation.
Rule 2: Qualify injected persistence units correctly using the Quarkus PersistenceUnit annotation.
When injecting JPA or Hibernate components for named persistence units, always qualify the injection site with the Quarkus PersistenceUnit annotation instead of the standard Jakarta Persistence annotation to prevent cross-database data leakage.
@ApplicationScopedpublic class UserService { @Inject @PersistenceUnit("users") EntityManager entityManager; @Transactional public void createUser(User user) { entityManager.persist(user); }}
Rule 3: Access normal-scoped CDI bean state exclusively through public getter and setter methods.
Do not read or write fields directly on normal-scoped CDI beans injected via client proxies. Direct field access interacts with the uninitialized proxy shell instead of the contextual instance, which can lead to state corruption or multi-tenant scope bleed.
@ApplicationScopedpublic class UserSession { private String tenantId; public String getTenantId() { return tenantId; } public void setTenantId(String tenantId) { this.tenantId = tenantId; }}@ApplicationScopedpublic class Service { @Inject UserSession userSession; public void process() { String id = userSession.getTenantId(); }}
Rule 4: Define normal-scoped beans as proxyable types with non-final classes and default constructors.
Normal-scoped beans require client proxies to enforce contextual lifecycles. Ensure bean classes are non-final and include accessible default constructors so client proxies can be correctly synthesized.
@ApplicationScopedpublic class IdentityResolver { public IdentityResolver() { } public String resolveUserToken(String user) { return ""; }}
When programmatically looking up dependency instances from ArcContainer, ensure returned instance handles are properly destroyed or closed after use to prevent memory leaks and gradual resource exhaustion.
try (InstanceHandle<MyDependentService> handle = Arc.container().instance(MyDependentService.class)) { if (handle.isAvailable()) { MyDependentService service = handle.get(); service.execute(); }}
Rule 6: Use the Identifier qualifier instead of Named to prevent CDI dependency injection ambiguity.
When using string-based qualifiers for dependency injection, prefer the SmallRye identifier qualifier over the standard named annotation to prevent beans from automatically receiving the default qualifier and causing deployment ambiguity.
@ApplicationScopedpublic class ServiceProducers { @Produces @Identifier("customService") MyService produceCustomService() { return new CustomServiceImpl(); }}@ApplicationScopedpublic class Consumer { @Inject @Identifier("customService") MyService service;}
Category: authentication
Configure Multifactor Verification and Certificate Binding for Identity Assurance
Use when
Implementing WebAuthn multi-factor authentication or binding access tokens to client certificates in mTLS environments.
Secure rules
Rule 1: Require user verification and user presence for WebAuthn authenticators.
Ensure userVerification remains set to required and userPresenceRequired is set to true when configuring WebAuthn authentication mechanisms to maintain proper multifactor verification standards.
Rule 2: Enable access token certificate binding in mTLS environments.
Set quarkus.oidc.token.binding.certificate=true so OidcIdentityProvider verifies that the confirmation claim in the access token matches the client X.509 certificate thumbprint from the TLS session.
Configure OIDC and JWT Token Signature, Issuer, and Audience Verification
Use when
Configuring OpenID Connect and SmallRye JWT authentication to validate bearer tokens and session tokens securely.
Secure rules
Rule 1: Validate token signatures, algorithms, issuers, and audiences explicitly before accepting identity
Ensure that mp.jwt.verify.issuer is set to the exact expected issuer string and mp.jwt.verify.publickey.location points to the valid public key PEM file. Configure exact expected issuer and audience properties instead of using wildcards like any to prevent accepting tokens from untrusted issuers or other applications.
Rule 2: Configure remote token introspection for opaque bearer tokens lacking digital signatures.
When processing opaque tokens, define quarkus.oidc.introspection-path or enable discovery via quarkus.oidc.discovery-enabled=true so that tokens are verified remotely.
Ensure X.509 certificate chains embedded in JWT x5c headers are ordered leaf-first, validate to a trusted root, and verify the token signature with the leaf certificate’s public key. Trust the leaf certificate directly or configure its expected name.
Verify Passwords and Configure Credential Verifiers for Authentication
Use when
Setting up password-based authentication and database or custom identity providers in Quarkus.
Secure rules
Rule 1: Configure JDBC principal queries with explicit 1-based index mapping and secure password verification.
Configure elytron-security-jdbc using a parameterized SQL statement with bcrypt password mapping and accurate 1-based column index mappings for user role attributes.
quarkus.security.jdbc.enabled=truequarkus.security.jdbc.principal-query.sql=SELECT u.password, u.role FROM test_user u WHERE u.username=?quarkus.security.jdbc.principal-query.bcrypt-password-mapper.enabled=truequarkus.security.jdbc.principal-query.bcrypt-password-mapper.password-index=1quarkus.security.jdbc.principal-query.attribute-mappings.0.index=2quarkus.security.jdbc.principal-query.attribute-mappings.0.to=groups
Rule 2: Delegate authentication logic to IdentityProviderManager in custom authentication mechanisms.
When creating a custom HttpAuthenticationMechanism, delegate authentication to IdentityProviderManager rather than validating credentials inline to ensure consistent identity handling across mechanisms.
Prevent Observability Data Exposure in Traces and Telemetry Endpoints
Use when
Configuring OpenTelemetry tracing, span attributes, exporters, and telemetry endpoints in Quarkus applications.
Secure rules
Rule 1: Restrict access to in-memory trace data export endpoints and isolate test span exporters.
Do not expose in-memory trace data collected by InMemorySpanExporter through public REST endpoints in non-test builds. Isolate test exporter components within test source directories (src/test/java) or enforce authentication and authorization such as @RolesAllowed on telemetry endpoints.
Rule 2: Disable OpenTelemetry End User attributes to prevent exposing PII in trace spans.
Keep quarkus.otel.traces.eusp.enabled disabled by default unless telemetry storage meets compliance requirements, to prevent leaking SecurityIdentity user principal and role details as span attributes.
# Keep disabled to prevent PII exposure in trace spansquarkus.otel.traces.eusp.enabled=falsequarkus.http.auth.proactive=true
Rule 3: Disable OpenTelemetry logging exporters in production environments.
Do not configure OpenTelemetry logging exporters like quarkus.otel.traces.exporter=logging or quarkus.otel.metrics.exporter=logging in production deployments to prevent writing raw trace spans and metrics to standard console logs where unencrypted log aggregators might capture them. Limit logging exporters strictly to development profiles.
Rule 4: Disable instrumentation for sensitive data pathways in OpenTelemetry
Selectively disable OpenTelemetry instrumentation for sensitive subsystems such as SQL and Redis clients when SQL statement text or database operation metadata must not be recorded in trace spans.
# Disable SQL Client and Redis database operation telemetryquarkus.otel.instrument.vertx-sql-client=falsequarkus.otel.instrument.vertx-redis-client=false# Disable the OpenTelemetry SDK entirely if telemetry collection is prohibitedquarkus.otel.sdk.disabled=true
Validate Redirect Back Locations Against Request Scheme and Authority
Use when
Handling form authentication redirects where user-controlled return locations must be verified at the server boundary before transitioning state.
Secure rules
Rule 1: Verify that redirect-back locations strictly match the request scheme and authority to prevent open redirect vulnerabilities
Do not override verifyRedirectBackLocation with relaxed domain checks. When running behind reverse proxies, enable proxy forwarding only with quarkus.http.proxy.trusted-proxies limited to those proxies so untrusted forwarding headers cannot control the validated scheme and authority.
Avoid mixing programmatic and property security configurations
Use when
Configuring security controls in Quarkus using both configuration files and programmatic builders simultaneously.
Secure rules
Rule 1: Choose a single primary mechanism for defining HTTP security configurations to prevent configuration overlap
Avoid defining HTTP security controls such as CORS, form authentication, basic authentication, or mTLS simultaneously in application.properties and via the HttpSecurity programmatic builder. When using programmatic HttpSecurity customization, ensure related application.properties settings are omitted to prevent runtime exceptions or dropped configuration mappings.
public void configureSecurity(@jakarta.enterprise.event.Observes HttpSecurity http) { http.path("/api/*") .methods("GET", "POST") .authenticated();}
Enforce Extension Catalog and BOM Integrity
Use when
Configuring Quarkus platform descriptors, extension catalogs, and dependencies to prevent untrusted artifact resolution during build time.
Secure rules
Rule 1: Explicitly declare BOM origins, exact artifact coordinates, provided capabilities, and extension dependencies in Quarkus extension catalogs
Ensure extension platform descriptors map explicit artifact coordinates and origin mappings to their platform BOMs so Quarkus tooling can identify extension origins and platform compatibility.
Hash user passwords securely before database persistence
Use when
You are implementing user registration or credential update workflows where passwords must be securely hashed prior to storage.
Secure rules
Rule 1: Hash user passwords using BcryptUtil.bcryptHash before persisting credentials.
Pass plain text passwords through BcryptUtil.bcryptHash() when adding or updating user records in persistent storage. Do not pre-hash passwords and never store plain text passwords in production.
User user = new User();user.username = username;user.password = BcryptUtil.bcryptHash(password);user.role = role;user.persist();
Use authenticated encryption and strong key generation for tokens
Use when
You are generating cryptographic secret keys or configuring token state encryption within Quarkus security features.
Secure rules
Rule 1: Generate cryptographically sound secret keys with sufficient key sizes using KeyUtils.
Ensure that symmetric secret keys match target algorithm requirements by utilizing io.smallrye.jwt.util.KeyUtils to produce correctly sized, cryptographically sound keys for signing and encryption.
Rule 2: Maintain token state encryption with strong cryptographic algorithms.
Keep token state encryption enabled and provide a secure encryption secret and algorithm when configuring token state management to prevent exposure of sensitive session tokens.
Configure CSRF prevention and token verification in Quarkus REST
Use when
Building web forms or REST endpoints in Quarkus that handle state-changing browser requests using ambient credentials and require anti-CSRF token protection.
Secure rules
Rule 1: Configure a strong token signature key for REST CSRF protection
Add quarkus.rest-csrf.token-signature-key to your application.properties with a secure secret that is at least 32 characters long to generate and verify HMAC signatures for CSRF tokens.
Rule 2: Inject CSRF tokens into Qute templates and HTML forms
Include the hidden CSRF token input field inside your Qute HTML templates so that the server filter can verify the submitted value against the CSRF cookie on state-changing requests.
Rule 3: Restrict CSRF verification paths and content types safely
Scope CSRF verification to specific form paths using quarkus.rest-csrf.create-token-path and set quarkus.rest-csrf.require-form-url-encoded=false if header-based token verification is required for non-form payloads.
# Limit CSRF verification to specific endpoint pathsquarkus.rest-csrf.create-token-path=/service/user# Allow non-form content types on the token path when using header tokensquarkus.rest-csrf.require-form-url-encoded=false
Category: deserialization
Use Type-Safe Deserializers and Strict Configurations for Untrusted Payloads
Use when
Deserializing untrusted incoming data streams such as Kafka records or JSON payloads in Quarkus applications.
Secure rules
Rule 1: Use explicit type-safe deserializers and declare concrete payload types on messaging channels to prevent arbitrary object instantiation.
When processing Kafka records or consuming messages from Kafka channels via @Incoming, configure structured type-safe deserializers like ObjectMapperDeserializer or JsonbDeserializer and declare concrete Java types on method parameters. Ensure underlying ObjectMapper instances do not enable unrestricted polymorphic default typing.
Rule 2: Enforce strict JSON deserialization by rejecting unknown properties.
Prevent unexpected input parameter injection during JSON deserialization by configuring quarkus.jackson.fail-on-unknown-properties=true in application.properties or annotating model classes with @JsonIgnoreProperties(ignoreUnknown = false).
quarkus.jackson.fail-on-unknown-properties=true
Rule 3: Apply all registered object mapper customizers when defining custom producers.
When creating custom CDI producers for ObjectMapper or JSON-B components to override framework defaults, inject and iterate over all registered ObjectMapperCustomizer or JsonbConfigCustomizer beans to preserve security-relevant configurations.
@Singleton@ProducesObjectMapper objectMapper(@All List<ObjectMapperCustomizer> customizers) { ObjectMapper mapper = new ObjectMapper(); for (ObjectMapperCustomizer customizer : customizers) { customizer.customize(mapper); } return mapper;}
Category: file handling
Configure Static File Paths to Prevent Directory Traversal
Use when
When configuring local filesystem static file paths and endpoints in Quarkus applications to serve web resources securely.
Secure rules
Rule 1: Specify safe relative paths without directory traversal elements in application properties.
Ensure that relative paths and endpoints do not contain directory traversal constructs like .. or wildcards like *. Configure safe relative paths directly in application.properties using properties such as quarkus.http.static-dir.path and quarkus.http.static-dir.endpoint to prevent unauthorized access to sensitive files outside the intended web root.
Safely Resolve OIDC Tenants Using Validated Routing Context
Use when
Implementing custom tenant resolution via TenantResolver or TenantConfigResolver in a Quarkus OIDC multi-tenancy application.
Secure rules
Rule 1: Validate request paths and verify routing context attributes before assigning tenant configurations to prevent cross-tenant access vulnerabilities.
Check the RoutingContext for an existing attribute such as tenant-id before parsing request paths. Explicitly validate request paths against known allowed patterns before assigning tenant identifiers to prevent attackers from redirecting operations into unauthorized trust domains.
@ApplicationScopedpublic class CustomTenantResolver implements TenantResolver { @Override public String resolve(RoutingContext context) { String tenantId = context.get("tenant-id"); if (tenantId != null) { return tenantId; } String path = context.request().path(); if (path.startsWith("/tenant-a/")) { return "tenant-a"; } return null; }}
Category: interface protocol hardening
Enforce Protocol Version Restriction and Transport Security for WebSockets
Use when
Configuring network transport schemes and protocol versions for WebSocket communication in production environments.
Secure rules
Rule 1: Require TLS encryption using the wss:// protocol scheme for WebSocket connections.
Unencrypted ws:// connections transmit frames over raw TCP in plain text, exposing handshake HTTP headers, authentication tokens, and message payloads to network eavesdropping and tampering. Ensure HTTP/TLS is properly configured for the application and require clients to initiate connections using the wss:// protocol URL scheme.
wss://example.com/chat/username
Secure and Isolate Management and Health Endpoints
Use when
Configuring management, health checks, and metrics endpoints in Quarkus to prevent unauthorized exposure.
Secure rules
Rule 1: Isolate management endpoints on a separate internal network interface.
Configure a dedicated internal network host and port for management traffic using quarkus.management.enabled=true, quarkus.management.host, and quarkus.management.port properties to prevent exposing sensitive internal telemetry on public application interfaces.
Rule 2: Enforce authentication and role-based access policies on management endpoints.
Explicitly enable authentication on the management interface using quarkus.management.auth.enabled=true and define path-based permissions and role policies to restrict operational routes.
Rule 3: Enable TLS encryption on the dedicated management interface.
Configure HTTPS on the management server using quarkus.management.tls-configuration-name to ensure management traffic and HTTP Basic Auth credentials are encrypted in transit.
Rule 4: Validate Host headers and reverse proxy forwarding headers for management endpoints.
Configure explicit host header validation via quarkus.management.host-validation.allowed-hosts and restrict forwarding headers using quarkus.management.proxy.proxy-address-forwarding=true to prevent host spoofing and header injection.
Enable TLS Certificate Validation and Hostname Verification for Outbound REST Clients
Use when
Configuring outbound REST client connections, OIDC integration, and Keycloak policy enforcer endpoints that communicate across network trust boundaries.
Secure rules
Rule 1: Enforce strict TLS certificate validation and hostname verification for all outgoing REST client and authentication connections
Ensure that trust-all is not set to true and hostname verification is not disabled in production configurations. Configure valid truststores and explicit TLS configurations to prevent interception and man-in-the-middle attacks.
Configure OIDC Token Caching to Prevent Authorization Server Resource Exhaustion
Use when
Configuring OIDC bearer token authentication in Quarkus applications to handle remote token introspection and UserInfo endpoint responses efficiently.
Secure rules
Rule 1: Enable and configure the built-in token cache for remote OIDC endpoints to reduce repetitive synchronous HTTP calls and prevent authorization server denial of service.
Define properties such as quarkus.oidc.token-cache.max-size, quarkus.oidc.token-cache.time-to-live, and quarkus.oidc.token-cache.clean-up-timer-interval in application.properties to bound cache size and lifecycle.
Configure Reflection and Native Initialization for Native Images
Use when
Developing or packaging Quarkus applications as GraalVM native images where dynamic reflection, native initialization, and proxy configurations are required.
Secure rules
Rule 1: Explicitly register reflectively accessed classes, dynamic proxies, and third-party dependency hierarchies for native image compilation.
Use @RegisterForReflection or ReflectiveClassBuildItem to ensure that classes requiring dynamic instantiation or field access are preserved during GraalVM closed-world dead-code elimination. Ensure dynamic proxy interfaces are declared using @RegisterForProxy to prevent runtime UnsupportedFeatureError exceptions.
@RegisterForReflection(targets = { User.class, UserImpl.class })public class MyReflectionConfiguration {}
Rule 2: Defer pseudo-random number generator initialization and stateful security managers to runtime
Prevent static build-time caching of SecureRandom seed values or sensitive security contexts by explicitly configuring --initialize-at-run-time for PRNG-dependent classes and registering stateful managers using RuntimeInitializedClassBuildItem.
Rule 3: Avoid performing side effects and runtime operations during static initialization.
Restrict @Record(STATIC_INIT) build steps strictly to immutable build-time metadata setup, and defer port binding, thread creation, and runtime configuration access to @Record(RUNTIME_INIT) steps executed when the application launches.
Disable Development Mode in Production Environments
Use when
Configuring deployment environments and packaging Quarkus applications for live production or staging usage.
Secure rules
Rule 1: Run packaged Quarkus applications using standard production launch modes to prevent development-only exception message disclosure.
Ensure application deployments run in production mode and do not enable development flags or interactive debugging features in live environments, preventing detailed authentication failure exceptions from exposing sensitive internal behavior.
java -jar target/quarkus-app/quarkus-run.jar
Secure Container and Deployment Configuration in Quarkus
Use when
Configuring container runtimes, deployment manifests, build-time versus runtime configuration separation, and development utilities for Quarkus applications.
Secure rules
Rule 1: Restrict custom Dev UI actions to local development and validate configuration targets
When implementing Dev UI actions in a Quarkus extension, register mutating actions only for local development by using @BuildStep(onlyIf = IsLocalDevelopment.class). Validate dynamically supplied configuration filenames against an explicit allowlist before resolving them within the resource directory.
Rule 2: Separate build-time configuration from container runtime overrides and enforce strict configuration binding.
Ensure configuration properties that require container environment customization or dynamic runtime overrides are defined using @ConfigRoot(phase = ConfigPhase.RUN_TIME). Reserve build-time phases strictly for static build optimizations. When defining deployment configuration models using Spring Boot @ConfigurationProperties, explicitly set ignoreUnknownFields = false to force Quarkus to validate that all supplied deployment configuration keys strictly match defined model fields.
@ConfigurationProperties(prefix = "app.deployment", ignoreUnknownFields = false)public class DeploymentConfig { private String trustedSubnet; private boolean enforceTls; public String getTrustedSubnet() { return trustedSubnet; } public void setTrustedSubnet(String trustedSubnet) { this.trustedSubnet = trustedSubnet; } public boolean isEnforceTls() { return enforceTls; } public void setEnforceTls(boolean enforceTls) { this.enforceTls = enforceTls; }}
Rule 3: Configure explicit security contexts, least-privilege service accounts, and secure secret mounting in generated Kubernetes manifests.
Configure explicit security contexts, least-privilege service accounts, and resource boundaries via Quarkus Kubernetes deployment settings. Define securityContext(), serviceAccount(), and resources() to restrict container privileges and resource limits. Mount sensitive runtime application credentials via appSecret or secretVolumes rather than embedding them in plain environment variables or appConfigMap.
Load and configure sensitive client and database credentials securely using external stores and environment variables
Use when
When configuring authentication client secrets, database passwords, SSL key store passwords, and third-party service credentials in Quarkus applications.
Secure rules
Rule 1: Avoid hardcoding plaintext credentials and secrets in source code or configuration files.
Use Quarkus CredentialsProvider, MicroProfile config properties, or environment variables to inject sensitive values dynamically rather than committing plain text secrets into application.properties.
Rule 2: Explicitly configure encryption keys for session management, token state, and form authentication.
Supply static and robust encryption keys using configuration properties like quarkus.http.auth.session.encryption-key or quarkus.oidc.token-state-manager.encryption-secret instead of relying on runtime auto-generated keys that break across cluster nodes and restarts.
Configure Throttled Commit Strategy and Unprocessed Record Max Age for Kafka Streams
Use when
Configuring incoming Kafka messaging consumers in Quarkus to protect against resource exhaustion caused by unacknowledged records.
Secure rules
Rule 1: Maintain a positive max age threshold for throttled offset commits to prevent unbounded memory accumulation.
When using the throttled commit strategy in the Kafka connector, ensure throttled.unprocessed-record-max-age.ms remains set to a positive value such as 60000. Never disable this health check by setting the value to less than or equal to zero, as unacknowledged poison pill records could otherwise stall offset commits indefinitely and lead to application resource exhaustion.
Maintain Consistent State and Fail Closed When Access Tokens and Role Sources Depend on Preservation
Use when
Configuring OIDC tenant authorization and token state manager strategies where role validation or UserInfo lookups depend on retained access tokens.
Secure rules
Rule 1: Ensure the token state manager strategy retains access tokens when token-based role sources or UserInfo requirements are enabled.
When configuring OIDC tenant authorization with quarkus.oidc.roles.source set to accesstoken or userinfo, you must configure quarkus.oidc.token-state-manager.strategy to retain all tokens (such as keep-all-tokens). Discarding tokens prevents subsequent authorization checks and security control enforcement from functioning correctly.
Configure Secure and HttpOnly Attributes for Session Cookies
Use when
Configuring session cookies and form authentication in Quarkus web applications to protect authentication state against cross-site scripting and unauthorized interception.
Secure rules
Rule 1: Enable HttpOnly and Secure cookie attributes on form-based authentication and OIDC session configurations.
Ensure that session cookies are protected by enabling HttpOnly and secure attributes to prevent client-side script access and unencrypted transmission.
Manage Server-Side and Local Session Invalidation on Logout
Use when
Implementing user logout workflows to ensure both server-side authentication state and local web session cookies are properly invalidated and destroyed.
Secure rules
Rule 1: Invalidate server-side session state and clear local web session cookies during logout operations.
Invoke the authentication mechanism logout method on the server side and redirect users through the appropriate logout endpoints to clear local session cookies.
@InjectSecurityIdentity identity;@POST@Path("/logout")public Response logout() { if (identity.isAnonymous()) { throw new UnauthorizedException("Not authenticated"); } FormAuthenticationMechanism.logout(identity); return Response.noContent().build();}
Configure Explicit Least-Privilege Kubernetes RBAC and Namespace Scoping
Approximately 1,222 tokens
Use when
Configuring Kubernetes RBAC permissions and role bindings using Quarkus deployment properties for application workloads.
Secure rules
Rule 1: Declare explicitly bounded policy rules with minimal required API groups, resources, and verbs in application properties
Avoid granting administrative or wildcard permissions in Role and ClusterRole definitions. Specify exact resource names and targeted verbs to prevent excessive privileges if the application container is compromised.
Rule 2: Prefer namespace-scoped Roles and RoleBindings over ClusterRoles and ClusterRoleBindings
Limit workload permissions to their own deployment namespace when global cluster access is not required, thereby reducing the blast radius and preventing cross-namespace resource access.
Configure Strict CORS Origins, Methods, and Credentials in Quarkus
Use when
Developing or configuring cross-origin resource sharing (CORS) rules in Quarkus applications via application properties, programmatic builders, or CDI observers.
Secure rules
Rule 1: Explicitly define allowed CORS origins and avoid wildcard configurations in production environments.
Enable the CORS filter using quarkus.http.cors.enabled=true and specify trusted origins via quarkus.http.cors.origins. Avoid using wildcard origins (*) in production unless the API is entirely read-only with no side effects or credential handling.
Rule 3: Avoid mixing programmatic and property-based CORS configurations
If CORS options are configured in application.properties, calling HttpSecurity.cors(...) programmatically throws an IllegalStateException. Choose a single configuration method and use the CORS builder to specify required options explicitly.
Restrict REST Endpoints and Web Resources Using Declarative Security Annotations
Use when
Enforcing access control, authentication, and role checks on JAX-RS endpoints, controllers, and web application paths.
Secure rules
Rule 1: Protect Jakarta REST endpoints using standard authorization annotations such as @RolesAllowed, @Authenticated, or @PermitAll to restrict access to authorized callers.
Annotate secure methods explicitly with required roles using @RolesAllowed, or require general authentication using @Authenticated. To prevent accidental exposure of unannotated resources, configure quarkus.security.jaxrs.deny-unannotated-endpoints=true in application.properties to apply @DenyAll access control defaults to all Jakarta REST endpoints lacking explicit security annotations.
Rule 2: Enforce HTTP path permissions and security policies to secure web application routes and virtual paths.
Configure explicit HTTP auth permission paths and policies in application.properties such as quarkus.http.auth.permission.authenticated.paths to ensure protected paths enforce the authenticated policy and prevent unauthenticated access to virtual paths.
Rule 3: Enforce fine-grained method-level permissions using @PermissionsAllowed and custom permission checkers.
Annotate service methods and CDI beans with @PermissionsAllowed to enforce granular checks. Ensure custom permission checker methods are non-private, non-static CDI methods returning boolean or Uni<Boolean>, annotated with @PermissionChecker.
@ApplicationScopedpublic class OrderService { @PermissionsAllowed("order:create") public Uni<Void> createOrder() { return Uni.createFrom().nullItem(); }}
Configure valid OpenAPI filter execution stages and document names
Approximately 966 tokens
Use when
When registering custom OpenAPI filters to sanitize or adjust API schemas using Quarkus smallrye-openapi.
Secure rules
Rule 1: Declare valid execution stages and matching document names when using @OpenApiFilter.
Ensure that custom OpenAPI filters configure explicit non-empty execution stages and valid document names. Mismatched document names or empty stages will trigger build-time errors and cause custom security filters to be skipped.
@OpenApiFilter( stages = {OpenApiFilter.RunStage.BUILD}, documentNames = {OpenApiFilter.DEFAULT_DOCUMENT_NAME})public class CustomSecurityOpenApiFilter implements OASFilter { // Custom OASFilter implementation to adjust security schema}
Manage CDI Dependency Injection Scopes and Lifecycles Securely in Quarkus
Use when
Developing Quarkus applications using CDI dependency injection where normal-scoped beans, request contexts, programmatic lookups, and persistence units are configured.
Secure rules
Rule 1: Ensure request contexts are active and restrict policy execution to Jakarta REST endpoints when injecting request-scoped beans into security policies.
Standard HTTP authorization runs before Quarkus prepares certain request-scoped beans. To prevent context resolution failures, restrict policy execution to Jakarta REST endpoints by configuring applies-to=jaxrs in application properties or by using the AuthorizationPolicy annotation.
Rule 2: Qualify injected persistence units correctly using the Quarkus PersistenceUnit annotation.
When injecting JPA or Hibernate components for named persistence units, always qualify the injection site with the Quarkus PersistenceUnit annotation instead of the standard Jakarta Persistence annotation to prevent cross-database data leakage.
@ApplicationScopedpublic class UserService { @Inject @PersistenceUnit("users") EntityManager entityManager; @Transactional public void createUser(User user) { entityManager.persist(user); }}
Rule 3: Access normal-scoped CDI bean state exclusively through public getter and setter methods.
Do not read or write fields directly on normal-scoped CDI beans injected via client proxies. Direct field access interacts with the uninitialized proxy shell instead of the contextual instance, which can lead to state corruption or multi-tenant scope bleed.
@ApplicationScopedpublic class UserSession { private String tenantId; public String getTenantId() { return tenantId; } public void setTenantId(String tenantId) { this.tenantId = tenantId; }}@ApplicationScopedpublic class Service { @Inject UserSession userSession; public void process() { String id = userSession.getTenantId(); }}
Rule 4: Define normal-scoped beans as proxyable types with non-final classes and default constructors.
Normal-scoped beans require client proxies to enforce contextual lifecycles. Ensure bean classes are non-final and include accessible default constructors so client proxies can be correctly synthesized.
@ApplicationScopedpublic class IdentityResolver { public IdentityResolver() { } public String resolveUserToken(String user) { return ""; }}
When programmatically looking up dependency instances from ArcContainer, ensure returned instance handles are properly destroyed or closed after use to prevent memory leaks and gradual resource exhaustion.
try (InstanceHandle<MyDependentService> handle = Arc.container().instance(MyDependentService.class)) { if (handle.isAvailable()) { MyDependentService service = handle.get(); service.execute(); }}
Rule 6: Use the Identifier qualifier instead of Named to prevent CDI dependency injection ambiguity.
When using string-based qualifiers for dependency injection, prefer the SmallRye identifier qualifier over the standard named annotation to prevent beans from automatically receiving the default qualifier and causing deployment ambiguity.
@ApplicationScopedpublic class ServiceProducers { @Produces @Identifier("customService") MyService produceCustomService() { return new CustomServiceImpl(); }}@ApplicationScopedpublic class Consumer { @Inject @Identifier("customService") MyService service;}
Configure Multifactor Verification and Certificate Binding for Identity Assurance
Approximately 1,005 tokens
Use when
Implementing WebAuthn multi-factor authentication or binding access tokens to client certificates in mTLS environments.
Secure rules
Rule 1: Require user verification and user presence for WebAuthn authenticators.
Ensure userVerification remains set to required and userPresenceRequired is set to true when configuring WebAuthn authentication mechanisms to maintain proper multifactor verification standards.
Rule 2: Enable access token certificate binding in mTLS environments.
Set quarkus.oidc.token.binding.certificate=true so OidcIdentityProvider verifies that the confirmation claim in the access token matches the client X.509 certificate thumbprint from the TLS session.
Configure OIDC and JWT Token Signature, Issuer, and Audience Verification
Use when
Configuring OpenID Connect and SmallRye JWT authentication to validate bearer tokens and session tokens securely.
Secure rules
Rule 1: Validate token signatures, algorithms, issuers, and audiences explicitly before accepting identity
Ensure that mp.jwt.verify.issuer is set to the exact expected issuer string and mp.jwt.verify.publickey.location points to the valid public key PEM file. Configure exact expected issuer and audience properties instead of using wildcards like any to prevent accepting tokens from untrusted issuers or other applications.
Rule 2: Configure remote token introspection for opaque bearer tokens lacking digital signatures.
When processing opaque tokens, define quarkus.oidc.introspection-path or enable discovery via quarkus.oidc.discovery-enabled=true so that tokens are verified remotely.
Ensure X.509 certificate chains embedded in JWT x5c headers are ordered leaf-first, validate to a trusted root, and verify the token signature with the leaf certificate’s public key. Trust the leaf certificate directly or configure its expected name.
Verify Passwords and Configure Credential Verifiers for Authentication
Use when
Setting up password-based authentication and database or custom identity providers in Quarkus.
Secure rules
Rule 1: Configure JDBC principal queries with explicit 1-based index mapping and secure password verification.
Configure elytron-security-jdbc using a parameterized SQL statement with bcrypt password mapping and accurate 1-based column index mappings for user role attributes.
quarkus.security.jdbc.enabled=truequarkus.security.jdbc.principal-query.sql=SELECT u.password, u.role FROM test_user u WHERE u.username=?quarkus.security.jdbc.principal-query.bcrypt-password-mapper.enabled=truequarkus.security.jdbc.principal-query.bcrypt-password-mapper.password-index=1quarkus.security.jdbc.principal-query.attribute-mappings.0.index=2quarkus.security.jdbc.principal-query.attribute-mappings.0.to=groups
Rule 2: Delegate authentication logic to IdentityProviderManager in custom authentication mechanisms.
When creating a custom HttpAuthenticationMechanism, delegate authentication to IdentityProviderManager rather than validating credentials inline to ensure consistent identity handling across mechanisms.
Prevent Observability Data Exposure in Traces and Telemetry Endpoints
Approximately 680 tokens
Use when
Configuring OpenTelemetry tracing, span attributes, exporters, and telemetry endpoints in Quarkus applications.
Secure rules
Rule 1: Restrict access to in-memory trace data export endpoints and isolate test span exporters.
Do not expose in-memory trace data collected by InMemorySpanExporter through public REST endpoints in non-test builds. Isolate test exporter components within test source directories (src/test/java) or enforce authentication and authorization such as @RolesAllowed on telemetry endpoints.
Rule 2: Disable OpenTelemetry End User attributes to prevent exposing PII in trace spans.
Keep quarkus.otel.traces.eusp.enabled disabled by default unless telemetry storage meets compliance requirements, to prevent leaking SecurityIdentity user principal and role details as span attributes.
# Keep disabled to prevent PII exposure in trace spansquarkus.otel.traces.eusp.enabled=falsequarkus.http.auth.proactive=true
Rule 3: Disable OpenTelemetry logging exporters in production environments.
Do not configure OpenTelemetry logging exporters like quarkus.otel.traces.exporter=logging or quarkus.otel.metrics.exporter=logging in production deployments to prevent writing raw trace spans and metrics to standard console logs where unencrypted log aggregators might capture them. Limit logging exporters strictly to development profiles.
Rule 4: Disable instrumentation for sensitive data pathways in OpenTelemetry
Selectively disable OpenTelemetry instrumentation for sensitive subsystems such as SQL and Redis clients when SQL statement text or database operation metadata must not be recorded in trace spans.
# Disable SQL Client and Redis database operation telemetryquarkus.otel.instrument.vertx-sql-client=falsequarkus.otel.instrument.vertx-redis-client=false# Disable the OpenTelemetry SDK entirely if telemetry collection is prohibitedquarkus.otel.sdk.disabled=true
Validate Redirect Back Locations Against Request Scheme and Authority
Use when
Handling form authentication redirects where user-controlled return locations must be verified at the server boundary before transitioning state.
Secure rules
Rule 1: Verify that redirect-back locations strictly match the request scheme and authority to prevent open redirect vulnerabilities
Do not override verifyRedirectBackLocation with relaxed domain checks. When running behind reverse proxies, enable proxy forwarding only with quarkus.http.proxy.trusted-proxies limited to those proxies so untrusted forwarding headers cannot control the validated scheme and authority.
Avoid mixing programmatic and property security configurations
Approximately 498 tokens
Use when
Configuring security controls in Quarkus using both configuration files and programmatic builders simultaneously.
Secure rules
Rule 1: Choose a single primary mechanism for defining HTTP security configurations to prevent configuration overlap
Avoid defining HTTP security controls such as CORS, form authentication, basic authentication, or mTLS simultaneously in application.properties and via the HttpSecurity programmatic builder. When using programmatic HttpSecurity customization, ensure related application.properties settings are omitted to prevent runtime exceptions or dropped configuration mappings.
public void configureSecurity(@jakarta.enterprise.event.Observes HttpSecurity http) { http.path("/api/*") .methods("GET", "POST") .authenticated();}
Enforce Extension Catalog and BOM Integrity
Use when
Configuring Quarkus platform descriptors, extension catalogs, and dependencies to prevent untrusted artifact resolution during build time.
Secure rules
Rule 1: Explicitly declare BOM origins, exact artifact coordinates, provided capabilities, and extension dependencies in Quarkus extension catalogs
Ensure extension platform descriptors map explicit artifact coordinates and origin mappings to their platform BOMs so Quarkus tooling can identify extension origins and platform compatibility.
Hash user passwords securely before database persistence
Approximately 448 tokens
Use when
You are implementing user registration or credential update workflows where passwords must be securely hashed prior to storage.
Secure rules
Rule 1: Hash user passwords using BcryptUtil.bcryptHash before persisting credentials.
Pass plain text passwords through BcryptUtil.bcryptHash() when adding or updating user records in persistent storage. Do not pre-hash passwords and never store plain text passwords in production.
User user = new User();user.username = username;user.password = BcryptUtil.bcryptHash(password);user.role = role;user.persist();
Use authenticated encryption and strong key generation for tokens
Use when
You are generating cryptographic secret keys or configuring token state encryption within Quarkus security features.
Secure rules
Rule 1: Generate cryptographically sound secret keys with sufficient key sizes using KeyUtils.
Ensure that symmetric secret keys match target algorithm requirements by utilizing io.smallrye.jwt.util.KeyUtils to produce correctly sized, cryptographically sound keys for signing and encryption.
Rule 2: Maintain token state encryption with strong cryptographic algorithms.
Keep token state encryption enabled and provide a secure encryption secret and algorithm when configuring token state management to prevent exposure of sensitive session tokens.
Configure CSRF prevention and token verification in Quarkus REST
Approximately 477 tokens
Use when
Building web forms or REST endpoints in Quarkus that handle state-changing browser requests using ambient credentials and require anti-CSRF token protection.
Secure rules
Rule 1: Configure a strong token signature key for REST CSRF protection
Add quarkus.rest-csrf.token-signature-key to your application.properties with a secure secret that is at least 32 characters long to generate and verify HMAC signatures for CSRF tokens.
Rule 2: Inject CSRF tokens into Qute templates and HTML forms
Include the hidden CSRF token input field inside your Qute HTML templates so that the server filter can verify the submitted value against the CSRF cookie on state-changing requests.
Rule 3: Restrict CSRF verification paths and content types safely
Scope CSRF verification to specific form paths using quarkus.rest-csrf.create-token-path and set quarkus.rest-csrf.require-form-url-encoded=false if header-based token verification is required for non-form payloads.
# Limit CSRF verification to specific endpoint pathsquarkus.rest-csrf.create-token-path=/service/user# Allow non-form content types on the token path when using header tokensquarkus.rest-csrf.require-form-url-encoded=false
Use Type-Safe Deserializers and Strict Configurations for Untrusted Payloads
Approximately 409 tokens
Use when
Deserializing untrusted incoming data streams such as Kafka records or JSON payloads in Quarkus applications.
Secure rules
Rule 1: Use explicit type-safe deserializers and declare concrete payload types on messaging channels to prevent arbitrary object instantiation.
When processing Kafka records or consuming messages from Kafka channels via @Incoming, configure structured type-safe deserializers like ObjectMapperDeserializer or JsonbDeserializer and declare concrete Java types on method parameters. Ensure underlying ObjectMapper instances do not enable unrestricted polymorphic default typing.
Rule 2: Enforce strict JSON deserialization by rejecting unknown properties.
Prevent unexpected input parameter injection during JSON deserialization by configuring quarkus.jackson.fail-on-unknown-properties=true in application.properties or annotating model classes with @JsonIgnoreProperties(ignoreUnknown = false).
quarkus.jackson.fail-on-unknown-properties=true
Rule 3: Apply all registered object mapper customizers when defining custom producers.
When creating custom CDI producers for ObjectMapper or JSON-B components to override framework defaults, inject and iterate over all registered ObjectMapperCustomizer or JsonbConfigCustomizer beans to preserve security-relevant configurations.
@Singleton@ProducesObjectMapper objectMapper(@All List<ObjectMapperCustomizer> customizers) { ObjectMapper mapper = new ObjectMapper(); for (ObjectMapperCustomizer customizer : customizers) { customizer.customize(mapper); } return mapper;}
Configure Static File Paths to Prevent Directory Traversal
Approximately 184 tokens
Use when
When configuring local filesystem static file paths and endpoints in Quarkus applications to serve web resources securely.
Secure rules
Rule 1: Specify safe relative paths without directory traversal elements in application properties.
Ensure that relative paths and endpoints do not contain directory traversal constructs like .. or wildcards like *. Configure safe relative paths directly in application.properties using properties such as quarkus.http.static-dir.path and quarkus.http.static-dir.endpoint to prevent unauthorized access to sensitive files outside the intended web root.
Safely Resolve OIDC Tenants Using Validated Routing Context
Approximately 255 tokens
Use when
Implementing custom tenant resolution via TenantResolver or TenantConfigResolver in a Quarkus OIDC multi-tenancy application.
Secure rules
Rule 1: Validate request paths and verify routing context attributes before assigning tenant configurations to prevent cross-tenant access vulnerabilities.
Check the RoutingContext for an existing attribute such as tenant-id before parsing request paths. Explicitly validate request paths against known allowed patterns before assigning tenant identifiers to prevent attackers from redirecting operations into unauthorized trust domains.
@ApplicationScopedpublic class CustomTenantResolver implements TenantResolver { @Override public String resolve(RoutingContext context) { String tenantId = context.get("tenant-id"); if (tenantId != null) { return tenantId; } String path = context.request().path(); if (path.startsWith("/tenant-a/")) { return "tenant-a"; } return null; }}
Enforce Protocol Version Restriction and Transport Security for WebSockets
Approximately 628 tokens
Use when
Configuring network transport schemes and protocol versions for WebSocket communication in production environments.
Secure rules
Rule 1: Require TLS encryption using the wss:// protocol scheme for WebSocket connections.
Unencrypted ws:// connections transmit frames over raw TCP in plain text, exposing handshake HTTP headers, authentication tokens, and message payloads to network eavesdropping and tampering. Ensure HTTP/TLS is properly configured for the application and require clients to initiate connections using the wss:// protocol URL scheme.
wss://example.com/chat/username
Secure and Isolate Management and Health Endpoints
Use when
Configuring management, health checks, and metrics endpoints in Quarkus to prevent unauthorized exposure.
Secure rules
Rule 1: Isolate management endpoints on a separate internal network interface.
Configure a dedicated internal network host and port for management traffic using quarkus.management.enabled=true, quarkus.management.host, and quarkus.management.port properties to prevent exposing sensitive internal telemetry on public application interfaces.
Rule 2: Enforce authentication and role-based access policies on management endpoints.
Explicitly enable authentication on the management interface using quarkus.management.auth.enabled=true and define path-based permissions and role policies to restrict operational routes.
Rule 3: Enable TLS encryption on the dedicated management interface.
Configure HTTPS on the management server using quarkus.management.tls-configuration-name to ensure management traffic and HTTP Basic Auth credentials are encrypted in transit.
Rule 4: Validate Host headers and reverse proxy forwarding headers for management endpoints.
Configure explicit host header validation via quarkus.management.host-validation.allowed-hosts and restrict forwarding headers using quarkus.management.proxy.proxy-address-forwarding=true to prevent host spoofing and header injection.
Enable TLS Certificate Validation and Hostname Verification for Outbound REST Clients
Approximately 216 tokens
Use when
Configuring outbound REST client connections, OIDC integration, and Keycloak policy enforcer endpoints that communicate across network trust boundaries.
Secure rules
Rule 1: Enforce strict TLS certificate validation and hostname verification for all outgoing REST client and authentication connections
Ensure that trust-all is not set to true and hostname verification is not disabled in production configurations. Configure valid truststores and explicit TLS configurations to prevent interception and man-in-the-middle attacks.
Configure OIDC Token Caching to Prevent Authorization Server Resource Exhaustion
Approximately 225 tokens
Use when
Configuring OIDC bearer token authentication in Quarkus applications to handle remote token introspection and UserInfo endpoint responses efficiently.
Secure rules
Rule 1: Enable and configure the built-in token cache for remote OIDC endpoints to reduce repetitive synchronous HTTP calls and prevent authorization server denial of service.
Define properties such as quarkus.oidc.token-cache.max-size, quarkus.oidc.token-cache.time-to-live, and quarkus.oidc.token-cache.clean-up-timer-interval in application.properties to bound cache size and lifecycle.
Configure Reflection and Native Initialization for Native Images
Approximately 1,168 tokens
Use when
Developing or packaging Quarkus applications as GraalVM native images where dynamic reflection, native initialization, and proxy configurations are required.
Secure rules
Rule 1: Explicitly register reflectively accessed classes, dynamic proxies, and third-party dependency hierarchies for native image compilation.
Use @RegisterForReflection or ReflectiveClassBuildItem to ensure that classes requiring dynamic instantiation or field access are preserved during GraalVM closed-world dead-code elimination. Ensure dynamic proxy interfaces are declared using @RegisterForProxy to prevent runtime UnsupportedFeatureError exceptions.
@RegisterForReflection(targets = { User.class, UserImpl.class })public class MyReflectionConfiguration {}
Rule 2: Defer pseudo-random number generator initialization and stateful security managers to runtime
Prevent static build-time caching of SecureRandom seed values or sensitive security contexts by explicitly configuring --initialize-at-run-time for PRNG-dependent classes and registering stateful managers using RuntimeInitializedClassBuildItem.
Rule 3: Avoid performing side effects and runtime operations during static initialization.
Restrict @Record(STATIC_INIT) build steps strictly to immutable build-time metadata setup, and defer port binding, thread creation, and runtime configuration access to @Record(RUNTIME_INIT) steps executed when the application launches.
Disable Development Mode in Production Environments
Use when
Configuring deployment environments and packaging Quarkus applications for live production or staging usage.
Secure rules
Rule 1: Run packaged Quarkus applications using standard production launch modes to prevent development-only exception message disclosure.
Ensure application deployments run in production mode and do not enable development flags or interactive debugging features in live environments, preventing detailed authentication failure exceptions from exposing sensitive internal behavior.
java -jar target/quarkus-app/quarkus-run.jar
Secure Container and Deployment Configuration in Quarkus
Use when
Configuring container runtimes, deployment manifests, build-time versus runtime configuration separation, and development utilities for Quarkus applications.
Secure rules
Rule 1: Restrict custom Dev UI actions to local development and validate configuration targets
When implementing Dev UI actions in a Quarkus extension, register mutating actions only for local development by using @BuildStep(onlyIf = IsLocalDevelopment.class). Validate dynamically supplied configuration filenames against an explicit allowlist before resolving them within the resource directory.
Rule 2: Separate build-time configuration from container runtime overrides and enforce strict configuration binding.
Ensure configuration properties that require container environment customization or dynamic runtime overrides are defined using @ConfigRoot(phase = ConfigPhase.RUN_TIME). Reserve build-time phases strictly for static build optimizations. When defining deployment configuration models using Spring Boot @ConfigurationProperties, explicitly set ignoreUnknownFields = false to force Quarkus to validate that all supplied deployment configuration keys strictly match defined model fields.
@ConfigurationProperties(prefix = "app.deployment", ignoreUnknownFields = false)public class DeploymentConfig { private String trustedSubnet; private boolean enforceTls; public String getTrustedSubnet() { return trustedSubnet; } public void setTrustedSubnet(String trustedSubnet) { this.trustedSubnet = trustedSubnet; } public boolean isEnforceTls() { return enforceTls; } public void setEnforceTls(boolean enforceTls) { this.enforceTls = enforceTls; }}
Rule 3: Configure explicit security contexts, least-privilege service accounts, and secure secret mounting in generated Kubernetes manifests.
Configure explicit security contexts, least-privilege service accounts, and resource boundaries via Quarkus Kubernetes deployment settings. Define securityContext(), serviceAccount(), and resources() to restrict container privileges and resource limits. Mount sensitive runtime application credentials via appSecret or secretVolumes rather than embedding them in plain environment variables or appConfigMap.
Load and configure sensitive client and database credentials securely using external stores and environment variables
Approximately 315 tokens
Use when
When configuring authentication client secrets, database passwords, SSL key store passwords, and third-party service credentials in Quarkus applications.
Secure rules
Rule 1: Avoid hardcoding plaintext credentials and secrets in source code or configuration files.
Use Quarkus CredentialsProvider, MicroProfile config properties, or environment variables to inject sensitive values dynamically rather than committing plain text secrets into application.properties.
Rule 2: Explicitly configure encryption keys for session management, token state, and form authentication.
Supply static and robust encryption keys using configuration properties like quarkus.http.auth.session.encryption-key or quarkus.oidc.token-state-manager.encryption-secret instead of relying on runtime auto-generated keys that break across cluster nodes and restarts.
Configure Throttled Commit Strategy and Unprocessed Record Max Age for Kafka Streams
Approximately 395 tokens
Use when
Configuring incoming Kafka messaging consumers in Quarkus to protect against resource exhaustion caused by unacknowledged records.
Secure rules
Rule 1: Maintain a positive max age threshold for throttled offset commits to prevent unbounded memory accumulation.
When using the throttled commit strategy in the Kafka connector, ensure throttled.unprocessed-record-max-age.ms remains set to a positive value such as 60000. Never disable this health check by setting the value to less than or equal to zero, as unacknowledged poison pill records could otherwise stall offset commits indefinitely and lead to application resource exhaustion.
Maintain Consistent State and Fail Closed When Access Tokens and Role Sources Depend on Preservation
Use when
Configuring OIDC tenant authorization and token state manager strategies where role validation or UserInfo lookups depend on retained access tokens.
Secure rules
Rule 1: Ensure the token state manager strategy retains access tokens when token-based role sources or UserInfo requirements are enabled.
When configuring OIDC tenant authorization with quarkus.oidc.roles.source set to accesstoken or userinfo, you must configure quarkus.oidc.token-state-manager.strategy to retain all tokens (such as keep-all-tokens). Discarding tokens prevents subsequent authorization checks and security control enforcement from functioning correctly.
Configure Secure and HttpOnly Attributes for Session Cookies
Approximately 335 tokens
Use when
Configuring session cookies and form authentication in Quarkus web applications to protect authentication state against cross-site scripting and unauthorized interception.
Secure rules
Rule 1: Enable HttpOnly and Secure cookie attributes on form-based authentication and OIDC session configurations.
Ensure that session cookies are protected by enabling HttpOnly and secure attributes to prevent client-side script access and unencrypted transmission.
Manage Server-Side and Local Session Invalidation on Logout
Use when
Implementing user logout workflows to ensure both server-side authentication state and local web session cookies are properly invalidated and destroyed.
Secure rules
Rule 1: Invalidate server-side session state and clear local web session cookies during logout operations.
Invoke the authentication mechanism logout method on the server side and redirect users through the appropriate logout endpoints to clear local session cookies.
@InjectSecurityIdentity identity;@POST@Path("/logout")public Response logout() { if (identity.isAnonymous()) { throw new UnauthorizedException("Not authenticated"); } FormAuthenticationMechanism.logout(identity); return Response.noContent().build();}
