Secure Coding Guide¶

Version: 4.1

When you write code for a WSO2 product, follow this guide. Each section opens with the canonical external reading (OWASP, NIST, RFCs), then lists what's WSO2-specific: named helpers to use, default configurations to override, anti-patterns to avoid, and stack-specific call shapes. For the general "what and why" of a category, follow the external links.

How to read this guide. Click the tab for your stack (Java stack for Carbon-based products, Go stack for the new Go-based products). Material remembers your choice across the site.

Companion pages.

• OWASP Top 10 - 2025 Prevention: a mapping table to the sections below.
• OWASP API Security Top 10 - 2023 Prevention: the API-specific mapping.
• General Recommendations for React Secure Coding: the frontend specifics.
• Tooling Recommendations for Secure Coding.

Canonical external references¶

Read these once; we link back to specific entries throughout this guide instead of restating them.

• General: OWASP Top 10, OWASP API Security Top 10, OWASP ASVS, OWASP Proactive Controls, OWASP Cheat Sheet Series, CWE Top 25.
• Identity and OAuth: NIST SP 800-63, RFC 9700: OAuth 2.0 Security BCP, RFC 7636: PKCE, RFC 8725: JWT BCP, OpenID Connect Core.
• Cryptography and transport: NIST SP 800-131A, NIST SP 800-52, NIST SP 800-57, Mozilla TLS config generator.
• Supply chain: SLSA, OWASP SCVS, OpenSSF Best Practices, CycloneDX, SPDX.
• WSO2 internal: Secure Software Development Process · Vulnerability Management · Cloud Security Process · Security Reporting · Incident clarifications.

Principles specific to WSO2 product code¶

The general principles (defense in depth, fail secure, least privilege, deny by default, secure defaults, no security through obscurity) are covered in OWASP Proactive Controls. The principles that are not obvious from external references and must be applied when writing WSO2 product code:

1. Tenant identity rides in context, never in caller input. Carbon's PrivilegedCarbonContext in Java; a typed context.Context key in Go. Reading tenant id from a header, query parameter, or request body is wrong by construction.
2. Re-check authorization at the data layer. The store layer carries tenant and owner predicates on every query and refuses to return non-matching rows; handler-level checks alone are insufficient.
3. Centralize crypto behind audited helpers. Carbon's CryptoUtil; a central encryption package (dispatcher + per-algorithm providers) in Go. Never call Cipher.getInstance / crypto/aes directly from product code.
4. Configuration is code. Security-relevant settings (CORS allow-lists, lockout thresholds, JWT issuers, federated IdPs, log layouts) are version-controlled and reviewed.

Broken Access Control¶

Read these for the access-control model and enforcement patterns: OWASP A01 · Authorization Cheat Sheet · Access Control Cheat Sheet for the deny-by-default model these subsections enforce.

Two rules cut across everything below: deny by default (every function requires an explicit grant before it runs), and re-check authorization at the layer that touches data, not only at the edge. Authorization checks must complete before any state-changing operation runs.

Object-level access control (IDOR)¶

Read OWASP API1:2023 for the attack pattern and the test cases to run against each object-returning endpoint.

The enforcement point is the data layer, not the handler. An authenticated user is authorized to act on their objects; the object id in the request is attacker-controlled and proves nothing. Bind every lookup to the caller's tenant and subject identity inside the query, so an id belonging to another tenant or owner simply returns no rows.

type tenantCtxKey struct{}

func WithTenant(ctx context.Context, tenantID string) context.Context {
    return context.WithValue(ctx, tenantCtxKey{}, tenantID)
}

func GetTenant(ctx context.Context) (string, bool) {
    tenantID, ok := ctx.Value(tenantCtxKey{}).(string)
    return tenantID, ok && tenantID != ""
}

Object property-level access control (mass assignment)¶

Read OWASP API3:2023 for how mass assignment lets a client set fields it should never control (role, tenant, internal status).

Never serialize a persistence entity directly, and never bind an inbound request onto an open property bag or onto the domain object by reflection. Drive both directions through an explicit Data Transfer Object: the request DTO declares exactly the fields a client may set, and the response DTO declares exactly the fields it may see. Map field-by-field at the service layer.

type UpdateUserRequest struct {
    DisplayName string `json:"display_name" validate:"required,min=1,max=128"`
    Locale      string `json:"locale"       validate:"required,bcp47_language_tag"`
}

type UpdateUserResponse struct {
    ID          string    `json:"id"`
    DisplayName string    `json:"display_name"`
    Locale      string    `json:"locale"`
    UpdatedAt   time.Time `json:"updated_at"`
    // role, password_hash, internal_status: deliberately not exposed
}

Path Traversal¶

Read OWASP Path Traversal for the ../ escape technique and Zip Slip for the archive-extraction variant of the same flaw.

Do not accept absolute paths or path fragments from the end user, apart from administrative configuration. Where a path fragment must be accepted, build the final path against a fixed base directory, normalize it so .. elements resolve, and confirm the result is still inside the base directory before using it.

full := filepath.Clean(filepath.Join(base, userDirectory, logFile))
baseAbs, err := filepath.Abs(base)         // 500 on error
fullAbs, err := filepath.Abs(full)         // 500 on error
if !strings.HasPrefix(fullAbs, baseAbs) {  // 400 "Invalid path"
    http.Error(w, "Invalid path", http.StatusBadRequest)
    return
}

Missing Function Level Access Control¶

Read OWASP API5:2023 for the attack pattern: sensitive handlers reachable because the authentication or authorization check is missing or insufficient.

Every restricted handler must check authentication and then role permission before it does any work; the enforcement mechanism must deny all access by default and require an explicit grant to specific roles for each function. If the function is part of a workflow, also verify the workflow is in a state that allows the operation. Log authentication- and authorization-related changes to the audit trail.

Cross-Site Request Forgery (CSRF)¶

Read the OWASP CSRF Prevention Cheat Sheet for the Synchronizer Token and Double-Submit-Cookie patterns.

CSRF targets state change, so the first rule is that no state-changing operation may use HTTP GET: use POST/PUT/DELETE and validate the token before processing the operation. Bearer-token APIs with no browser-session cookie typically do not need CSRF tokens, but each such endpoint must document why it is exempt.

The strategy is keyed to the Carbon Kernel version:

• Carbon Kernel prior to 4.4.6 used Referer-header-based prevention, no longer recommended; do not carry it forward.
• Carbon Kernel 4 (4.4.6+) products use the Synchronizer Token Pattern via OWASP CSRFGuard.
• Carbon Kernel 5+ products and any new application use the Double-Submit-Cookie approach.

Server Side Request Forgery (SSRF)¶

Read the OWASP SSRF Prevention Cheat Sheet for the full list of bypasses; this is a high-severity class because the server can be turned into a proxy for internal port scanning, file:// access, and gopher:///tftp:// protocol smuggling.

WSO2 surfaces that take URLs from input are the back-channel operations where the product acts as the client (e.g. webhook destinations, OIDC discovery, or federated-IdP metadata fetches). Validate the resolved address, not the host string, because DNS rebinding makes a host-string allow-list bypassable.

Prevention techniques:

• Avoid using user input in backend requests: URLs, IP addresses, and file paths used in back-channel operations, and unvalidated XML passed to a parser without XXE protections (see Injection).
• Strict error handling: return an identical generic error (e.g. "Invalid Data Retrieved") whether the backend request fails or invalid data is returned, so the response cannot be used as an open/closed-port oracle.
• Strict response handling: validate the response server-side (expected content-type, schema) before processing it or returning it to the client.

Unvalidated Redirects and Forwards¶

Read the OWASP Unvalidated Redirects and Forwards Cheat Sheet for how an open redirect enables phishing under a trusted server name and how a forward can reach a restricted resource through a less-restricted one.

Do not accept absolute forward URLs, or absolute redirect URLs (apart from administrative configuration), or URL fragments used to build them, from the end user. Where an absolute URL is unavoidable, match it against a registered allow-list before redirecting. Where only a fragment is expected, validate that the fragment is exactly the expected type of value (e.g. an integer id). The same exact-match rule that governs OAuth redirect_uri applies here (see Authentication Failures).

Security Misconfiguration¶

External: OWASP A05 · HTTP Headers Cheat Sheet. Read these for the category model; this section covers what to set in WSO2 code and deployments.

Production hardening (per-product, per-version) is a separate concern from code defaults. Follow the version-indexed Security Guidelines for Production Deployment for your product and version; the controls below are the ones you own in code and manifests regardless of deployment.

HTTP security headers¶

The header set your code should emit, and how to wire it on Carbon/Tomcat, Go services, the WSO2 API Gateway, reverse proxies, and Kubernetes ingresses, is in HTTP Security Headers: Configuration Reference. Do not hand-roll header logic per service; delegate to that reference.

Distinguish the two tiers when reviewing a change:

• Mandatory on every response from a WSO2 service: framing defense (X-Frame-Options / CSP frame-ancestors 'none', see ClickJacking below) and X-Content-Type-Options: nosniff, plus any other header the companion page marks as required. Do not emit X-XSS-Protection: 1; mode=block. The header is deprecated, browsers have removed the XSS Auditor, and the companion page lists it under headers your code must not emit; rely on a strict nonce-based Content-Security-Policy for reflected and stored XSS defense instead. If any legacy code still emits it, set the value to 0.
• Configurable (CSP source lists, HSTS max-age such as Strict-Transport-Security: max-age=31536000; includeSubDomains, and CORS allow-lists): version-controlled and reviewed as configuration, never hardcoded per build. Ship a long max-age (at least one year) with includeSubDomains; treat preload as an operator decision, an irreversible per-hostname commitment that engineers never hardcode. See HTTP Security Headers for the authoritative split and the recommended values.

Container security defaults¶

This is net-new general engineering guidance, not extracted from the secure-coding source: the controls below are external-standard baselines adopted as the WSO2 baseline. Read Kubernetes Pod Security Standards (Restricted) for the exact field set the Restricted profile enforces, and NIST SP 800-190 for the container-platform threat model. Pod Security, NetworkPolicy, and image-pinning follow those standards.

Apply at the workload and namespace level:

• Pod Security: Restricted. Run as non-root, drop all Linux capabilities, readOnlyRootFilesystem: true, allowPrivilegeEscalation: false, seccompProfile: RuntimeDefault. Enforce the profile with the namespace label pod-security.kubernetes.io/enforce: restricted so non-conforming pods are rejected at admission, not merely warned.
• Distroless or minimal base image. No shell, no package manager, no build tooling in the runtime image. This shrinks both the attack surface and the CVE-bearing dependency set.
• Pin images by digest, not tag. Reference image@sha256:..., not image:latest or a floating version tag, so the running artifact is the one that was scanned and approved.
• NetworkPolicy default-deny per namespace. Every namespace starts with a deny-all ingress and egress policy; each service gets an explicit allow for exactly the peers it needs. Internal services use ClusterIP, never LoadBalancer. Deny by default is the rule, not the exception.
• PodDisruptionBudget for critical workloads, so voluntary disruptions cannot drain a service below quorum.
• No secrets in images, manifests, or ConfigMaps. Mount them from a secret store at runtime.

Configuration is code: these belong in version-controlled manifests reviewed in the same flow as application changes, not applied imperatively against a live cluster.

XML External Entity (XXE)¶

External: OWASP XXE Prevention Cheat Sheet. See it for the per-parser flag matrix and test payloads.

// imports org.apache.xerces.impl.Constants
private static final int ENTITY_EXPANSION_LIMIT = 0;

DocumentBuilderFactory dbf = DocumentBuilderFactory.newInstance();
dbf.setNamespaceAware(true);
dbf.setXIncludeAware(false);
dbf.setExpandEntityReferences(false);
dbf.setFeature(Constants.SAX_FEATURE_PREFIX + Constants.EXTERNAL_GENERAL_ENTITIES_FEATURE, false);
dbf.setFeature(Constants.SAX_FEATURE_PREFIX + Constants.EXTERNAL_PARAMETER_ENTITIES_FEATURE, false);
dbf.setFeature(Constants.XERCES_FEATURE_PREFIX + Constants.LOAD_EXTERNAL_DTD_FEATURE, false);

SecurityManager securityManager = new SecurityManager();
securityManager.setEntityExpansionLimit(ENTITY_EXPANSION_LIMIT);
dbf.setAttribute(Constants.XERCES_PROPERTY_PREFIX + Constants.SECURITY_MANAGER_PROPERTY, securityManager);

private static final int ENTITY_EXPANSION_LIMIT = 0;

XMLInputFactory xif = XMLInputFactory.newInstance();
xif.setProperty(XMLInputFactory.IS_NAMESPACE_AWARE, true);
xif.setProperty(XMLInputFactory.SUPPORT_DTD, false);
xif.setProperty(XMLInputFactory.IS_SUPPORTING_EXTERNAL_ENTITIES, false);
// Woodstox StAX 5+: also disable entity expansion
// xif.setProperty("com.ctc.wstx.maxEntityDepth", 1);

ClickJacking and Cross Frame Scripting¶

External: OWASP Clickjacking Defense Cheat Sheet. Read it for the framing-defense test cases.

Emit both the standard CSP directive and the legacy header on every page, especially admin consoles:

• Content-Security-Policy: frame-ancestors 'none' in all cases, except where the product must frame a page exposed elsewhere in the same product, where frame-ancestors 'self' may be used.
• X-Frame-Options: DENY in all cases, or SAMEORIGIN for the same-product framing exception.

Set the values through the HTTP Security Headers configuration; do not invent per-page values.

Cross-Origin Resource Sharing¶

External: MDN: CORS · OWASP HTML5 Security Cheat Sheet.

• Reject Access-Control-Allow-Origin: * combined with Access-Control-Allow-Credentials: true at code review: the combination is invalid and browsers will not honor it, but shipping it signals a misunderstanding of the trust boundary.
• A wildcard Access-Control-Allow-Origin is appropriate only for content that is fully public to any site. It must not be the default in WSO2 products. Where a wildcard option exists, an admin must be able to switch it to domain-level restriction; the allow-list is configuration, version-controlled and reviewed.
• Admin and management APIs must be domain-restricted, never wildcard.

API inventory, versioning, deprecation¶

This topic is not covered by the secure-coding source; the guidance here is general engineering practice plus standard stack technique. Read OWASP API9:2023 for the inventory-management failure modes, and RFC 8594: Sunset header for the deprecation-signalling contract before emitting deprecation signals.

Unmanaged versions and undocumented endpoints are the misconfiguration here: an old /v1 left running, a debug route never removed, a host with no spec. Controls:

• Inventory is authoritative and generated, not maintained by hand. Every reachable endpoint, on every host and version, appears in a machine-readable spec. Routing is driven from that spec; a handler that is not in the spec is a defect.
• Deny by default for non-public surfaces. Internal, debug, and management endpoints are not reachable from public ingress. Bind them to localhost or an internal network and front them with a deny-default NetworkPolicy.
• Signal deprecation in the response using the standard contract. Per RFC 8594, emit Sunset (with the retirement date), Deprecation, and a Link to the migration guide on deprecated resources so consumers can detect and act before removal. Use your stack's normal response-header mechanism; this is standard HTTP technique, not a WSO2-specific control.
• Retire on a schedule. Track deprecated versions to a removal date; do not leave superseded versions serving traffic indefinitely.

Default credentials, sample apps, management console exposure¶

WSO2-specific operational rules; these are the defaults attackers try first:

• Rotate the Carbon admin password before any exposure. Replace all shipped keystore and truststore passwords as well. Store the rotated secrets in the product's secure secret store or an external secret manager; never leave them in plaintext config or commit them.
• Remove or isolate sample apps and demo content before production. Do not ship demo artifacts on a public surface.
• Keep the Carbon Management Console, JMX, debug/profiling, and any reflection or diagnostic endpoints off public ingress: bind them to localhost or an internal network. Document every default credential, default certificate, and open port in the product documentation so operators can harden them.
• Suppress version-disclosing response banners and headers so the running version is not advertised; follow the version-indexed production-deployment guide for the exact settings.
• Do not grant the Management Console "login" permission to self-registered users. Deny it by default and grant it explicitly only to roles that need console access. This is particularly important for API Manager Store users, who must not reach the admin console.
• Keep production and staging configured identically, with config and artifact promotion automated through change management, so no unreviewed configuration change lands directly in production.

Software Supply Chain Failures¶

External: SLSA for the build-integrity levels to target · OWASP SCVS for the component-verification checklist. Read these for the threat model and the maturity targets; the controls below are what they translate to in WSO2 product code.

Deployments that diverge from the official release baseline are the recurring supply-chain failure pattern: an artefact, dependency, or build step that no longer matches what was reviewed and released.

Operational rules:

• Pin every dependency to an exact version. Commit lock files (go.sum, package-lock.json, pnpm-lock.yaml). CI installs from the lock file, never re-resolving: npm ci, pnpm install --frozen-lockfile, GOFLAGS=-mod=readonly.
• Resolve every dependency from a single organization-controlled source per ecosystem; resolution from any other source is a reviewable change.
• Generate an SBOM (CycloneDX or SPDX) for each release and attach it to the artefact, so a newly disclosed CVE can be mapped to shipped releases without a rebuild.
• Sign every released artefact on protected infrastructure with a short-lived signing identity, and verify the signature before promoting or deploying the artefact.
• Least-privilege permissions: on every CI workflow. Never run pull_request_target with secrets without an explicit approval gate: a fork PR runs attacker-controlled code with the base repo's token.

env:
  GOFLAGS: "-mod=readonly"
on:
  pull_request:
    paths:
      - '**/go.mod'
      - '**/go.sum'

Using Known Vulnerable Components¶

Read OWASP A06:2021, Vulnerable and Outdated Components for why this is a top-ranked risk, and consult NVD and Exploit-DB to assess a specific component's exposure. The operational scanning workflow (CLI versus Maven-plugin usage, suppression-file format, NVD sync intervals, and the report walkthrough) lives in Dependency Vulnerability Analysis. This section covers the engineering rules and the governance gates around it.

Introducing a new dependency

• Select the most up-to-date version of the component, then scan that version, and all transitive dependencies it pulls in, for known vulnerabilities with OWASP Dependency Check before proposing it.
• Attach the generated Dependency Check report to the Approval Request and copy the request to the Security Leads Group.
• If the latest version still carries a known vulnerability and the component is no longer actively developed, prefer a maintained alternative over the vulnerable library.

Handling a vulnerability found in a current dependency

When a scan flags an existing dependency, do not jump straight to a suppression. Triage it:

1. Open a thread on the Security Group mailing list with the subject Dependency Vulnerability - [DependencyName] - [DependencyVersion] - [CVE].
2. Analyze whether WSO2's actual usage of the component is reachable by the vulnerability.
   • Reachable, fix available: migrate to a version with no known vulnerability.
   • Reachable, no fixed version: nullify the impact in WSO2's usage path with additional validation or security checks (this hardening is itself approval-gated, below).
   • Not reachable in WSO2's usage: document the reasoning on the thread and request approval to record it in the Dependency Check suppression file. Suppress only genuine non-exploitable findings after this per-vulnerability analysis; never blanket-suppress to make a build pass.

Unsafe consumption of upstream APIs¶

Read OWASP API10:2023, Unsafe Consumption of APIs for the test cases; the failure mode is trusting a third-party or partner API more than direct user input. Every upstream response is untrusted.

• Validate the response before using it: check the HTTP status, assert the Content-Type, parse against an expected schema, and bound the body size before decoding so a hostile or runaway upstream cannot exhaust memory.
• Apply the outbound TLS rules from Cryptographic Failures to every outbound call: verify the chain and hostname; never disable verification to "make it work".
• Bound every call with a connect/read timeout and wrap it in a circuit breaker so a slow or failing upstream cannot cascade into your own request threads.
• Treat the JWKS (or any key/trust-material) endpoint as configured trust. Resolve it from a value you control in configuration, not from a URL, kid, or Location the token or upstream supplies at runtime. Letting the caller name where to fetch the verification key defeats the signature check.
• Never forward an upstream redirect (Location), error body, or supplied URL into a server-side request without allow-list validation: that is the SSRF path (see Broken Access Control for redirect/forward allow-listing).

Cryptographic Failures¶

Cryptographic failures cover weak or misused algorithms, mishandled keys, broken transport, forgeable tokens, and sensitive material left readable in memory. Most of this is net-new relative to the upstream guideline, so the canonical reading lives outside WSO2; the WSO2 rules are about where crypto lives in product code and which deviations need approval.

Read these for the parameters; do not restate them in code or comments, reference the current version at implementation time:

• NIST SP 800-131A. Read it for the approved-algorithm list and the transition schedule. Anything NIST currently marks legacy or disallowed (MD5, SHA-1, 3DES, RC4, RSA without padding, AES without an authenticated mode) is banned in WSO2 product code.
• NIST SP 800-52 Rev. 2. Read it for the TLS protocol and cipher selection rules that apply to government-grade deployments.
• OWASP Cryptographic Storage Cheat Sheet. Read it for symmetric/asymmetric primitive choice, nonce/IV handling, and key lifecycle.
• OWASP Password Storage Cheat Sheet. Read it for the current Argon2id / scrypt / bcrypt / PBKDF2 work-factor parameters. These move over time: use the values current at implementation time, store the algorithm name and parameters alongside the hash so they can be migrated, and re-evaluate every release.
• Mozilla TLS configuration generator. Generate the cipher suite, protocol, OCSP, and HSTS config for the terminator from the "Intermediate" or "Modern" profile and pin to it rather than hand-rolling.
• RFC 8725: JWT BCP. Read it for algorithm allow-listing, the alg-confusion attack, kid/jwk header handling, and required claim validation.

WSO2 rules that apply on top of the external baselines:

• Centralize crypto behind the platform facade; do not hand-roll. Product code that encrypts or decrypts a secret (refresh tokens, IdP credentials, vault-managed configuration) goes through the platform crypto facade, not a raw Cipher / crypto/aes call scattered through a component. Centralizing keeps algorithm, mode, and key selection in one auditable place that can be upgraded when NIST guidance moves.
• A JWT algorithm allow-list is data, not code. Each verifier accepts an explicit, configured set of algorithms. Reject alg: none, and reject HMAC algorithms where the verifier holds an asymmetric (public) key: that is the alg-confusion attack RFC 8725 describes.
• Never honor an inline jwk (or jku) header. Resolve keys by kid against a JWKS pinned to the trusted issuer. An inline key in the token lets the sender choose their own verification key.
• Hardcoded TLS-verification bypasses are defects. A literal hostname-verification or certificate-verification disable in a production path fails review. An operator-configurable bypass is acceptable only with a secure default of "verify" and a deployment-time warning when it is switched off (see the approval gate below).

JWSAlgorithm alg = signedJWT.getHeader().getAlgorithm();
if (alg == null
        || !ALLOWED_ALGORITHMS.contains(alg)          // e.g. RS256/RS384/RS512
        || JWSAlgorithm.NONE.equals(alg)) {
    throw new SecurityException("Unsupported or disallowed JWT algorithm");
}
// resolve the verification key by kid from the issuer's pinned JWKS - never an inline jwk header

func encryptAESGCM(key, plaintext []byte) ([]byte, error) {
    block, err := aes.NewCipher(key)
    if err != nil {
        return nil, fmt.Errorf("create AES cipher: %w", err)
    }
    aesgcm, err := cipher.NewGCM(block)
    if err != nil {
        return nil, fmt.Errorf("create GCM mode: %w", err)
    }
    nonce := make([]byte, aesgcm.NonceSize())
    if _, err := rand.Read(nonce); err != nil { // crypto/rand
        return nil, fmt.Errorf("generate nonce: %w", err)
    }
    return aesgcm.Seal(nonce, nonce, plaintext, nil), nil
}

token, err := jwt.ParseWithClaims(raw, claims, func(t *jwt.Token) (any, error) {
    switch t.Method.Alg() {
    case "RS256", "RS384", "ES256": // explicit allow-list; "none" never reaches here
    default:
        return nil, fmt.Errorf("unsupported alg %q", t.Method.Alg())
    }
    kid, _ := t.Header["kid"].(string)
    return jwks.GetKey(kid) // pinned issuer JWKS - never an inline jwk header
})

Random Number Generation¶

Security-sensitive values (tokens, salts, IVs, nonces, session IDs, password prefixes) must come from a cryptographically secure PRNG. The risk is low available entropy at PRNG initialization, which makes some output values more likely than others. Read the OWASP guidance referenced in the upstream guideline for the failure modes. In containers this is sharper: entropy gathering takes significant time at instance spawn.

Heap Inspection¶

If a password or key is left in memory after use, an attacker with a memory dump (or similar access) can read it. This is a heap inspection attack. Hold secrets in a mutable type and zero them as soon as the operation that needs them completes, before the variable goes out of scope. (See also the OWASP Cryptographic Storage Cheat Sheet for in-memory key handling.)

func clearSensitiveData(data []byte) {
    for i := range data {
        data[i] = 0
    }
}

Securing Cookies¶

External: read the OWASP Session Management Cheat Sheet: Cookies for the attribute rationale and test cases.

Sensitive cookies such as JSESSIONID are stolen over insecure networks or through an XSS vulnerability when their attributes are weak. WSO2 baseline for every session and authentication cookie:

• Secure: set it so the browser only sends the cookie over HTTPS. Java: cookie.setSecure(true). Go: Secure: true on the http.Cookie.
• HttpOnly: set it so client-side JavaScript cannot read the cookie, mitigating XSS-driven session theft. Java: cookie.setHttpOnly(true). Go: HttpOnly: true on the http.Cookie.
• SameSite=Lax (or Strict for high-sensitivity flows) to blunt CSRF.
• Path set to the narrowest scope that works; Domain only when cross-subdomain sharing is genuinely required.
• No expires / max-age: a sensitive cookie must be a session cookie so it dies with the browser session.

Wiring response headers (and HSTS at the terminator) is in HTTP Security Headers: Configuration Reference.

Injection¶

External: OWASP A03 · Injection Prevention Cheat Sheet · Input Validation Cheat Sheet.

Input validation¶

The general rules (allow-list not deny-list, length caps, format validation, canonicalization before validation, refuse unknown JSON fields, bound parser cost) are in the OWASP Input Validation Cheat Sheet. Read it for the canonical allow-list/canonicalization order; below is what to do in WSO2 code.

Validation must run server-side; front-end validation is for UX only and is trivially bypassed. In Carbon 4 based products, input validation is given a lower priority and is performed only on essential screens, so it cannot be the line of defense on its own. Treat output encoding and output sanitization (see Cross-Site Scripting) as mandatory and treat parameterization/escaping at each sink (see the subsections below) as the primary control. Input validation is defense in depth, not the boundary.

type CreateAppRequest struct {
    Name        string   `json:"name"        validate:"required,min=1,max=128,alphanumunicode"`
    Description string   `json:"description" validate:"omitempty,max=4096"`
    Scopes      []string `json:"scopes"      validate:"max=32,dive,oneof=read write admin"`
}

SQL Injection¶

External: OWASP SQL Injection Prevention Cheat Sheet. Read it for parameterized queries (Defense Option 1) and the allow-list input validation pattern for dynamic identifiers (Defense Option 4), which has the worked code shapes.

WSO2 rule: use a compiled/prepared statement with bind variables for every value. SQL identifiers (table names, column names, an ORDER BY column, sort direction, offset) cannot be bound as parameters; an ORDER BY column name in particular is not a legal PreparedStatement parameter. Where the query needs a dynamic identifier, restructure the method so it does not accept the raw identifier from the caller; map a fixed set of user-facing keys to real column/table names through a static allow-list and reject anything not in the set. Concatenating an identifier into the query string is injectable even when every other value is bound.

// Values - always bound
try (PreparedStatement ps = conn.prepareStatement(
        "SELECT id, name FROM users WHERE tenant_id = ? AND user_id = ?")) {
    ps.setInt(1, tenantId);
    ps.setString(2, userId);
    try (ResultSet rs = ps.executeQuery()) { /* ... */ }
}

// Identifier - allow-list, never concatenated raw
private static final Map<String, String> VALID_ORDER_COLUMNS = Map.of(
        "name", "NAME", "created", "CREATED_AT");
String column = VALID_ORDER_COLUMNS.get(orderColumn);   // user-facing key
if (column == null) { throw new IllegalArgumentException("invalid sort column"); }
String direction = "DESC".equalsIgnoreCase(orderDirection) ? "DESC" : "ASC";
String sql = "SELECT id, name FROM users WHERE tenant_id = ? ORDER BY " + column + " " + direction;

// Value - always a placeholder
row := db.QueryRowContext(ctx,
    "SELECT id, name FROM users WHERE tenant = $1 AND id = $2",
    tenantID, userID)

// Identifier - allow-list with comma-ok, never concatenated raw
var validOrderColumns = map[string]string{
    "name": "NAME", "created": "CREATED_AT",
}
column, ok := validOrderColumns[orderColumn]
if !ok { return fmt.Errorf("invalid sort column %q", orderColumn) }
direction := "ASC"
if strings.ToUpper(orderDirection) == "DESC" { direction = "DESC" }
query := "SELECT id, name FROM users WHERE tenant = $1 ORDER BY " + column + " " + direction

LDAP Injection¶

External: OWASP LDAP Injection Prevention Cheat Sheet. Read it for the search-filter character set that must be escaped (*, (, ), \, NUL) and the separate distinguished-name character set (different rules: filter escaping and DN escaping are not interchangeable).

WSO2 rule: every user input appended to an LDAP filter or DN must pass through a proper LDAP encoding function before it reaches the search request. Building a filter with String.format / fmt.Sprintf / string concatenation on raw input is a security defect even when the input "looks like" a username.

// Anti-pattern - raw value in the filter
searchFilter.replace("?", role);
// Safe - escaped before substitution
searchFilter.replace("?", escapeSpecialCharactersForFilter(role));

import "github.com/go-ldap/ldap/v3"

// Anti-pattern - raw value in the filter
f := strings.Replace(searchFilter, "?", role, -1)
// Safe - escaped
f := strings.Replace(searchFilter, "?", ldap.EscapeFilter(role), -1)

OS Command Injection¶

External: OWASP OS Command Injection Defense Cheat Sheet.

WSO2 products and applications should not construct OS commands from user input at all. The guideline gives no "safe" sanitization recipe for running a user-derived command: the prescribed control is to avoid it. If a use case genuinely requires execution, pass a fixed program with arguments as an argument array so no shell parses the input. Never the single-string form; never sh -c "…" with interpolated input.

// Anti-patterns - reject in code review
Runtime.getRuntime().exec("convert " + userFilename + " out.png");
new ProcessBuilder("/bin/sh", "-c", "convert " + userFilename + " out.png").start();

// If execution is unavoidable (after SC Team approval): argument array, no shell
new ProcessBuilder("convert", userFilename, "out.png")
        .redirectErrorStream(true).start();

// Anti-pattern - reject in code review
exec.CommandContext(ctx, "sh", "-c", "convert "+userFilename+" out.png")

// If execution is unavoidable (after SC Team approval): argument slots, no shell
cmd := exec.CommandContext(ctx, "convert", userFilename, "out.png")
cmd.Stdin = nil
out, err := cmd.CombinedOutput()

Cross-Site Scripting (XSS)¶

External: OWASP XSS Prevention Cheat Sheet · OWASP DOM-based XSS Prevention Cheat Sheet. Pair output encoding with a strict CSP; see HTTP Security Headers.

Three controls, applied per field by whether the field is meant to carry HTML:

• Output encoding: for output that should not contain HTML (e.g. an API description field), convert special characters to HTML entity references at the output context.
• Output sanitization: for output that is expected to contain HTML (e.g. API documentation content), allow a safe subset of tags/attributes and strip dangerous ones (<script>, event-handler attributes).
• Browser-level protection: the legacy X-XSS-Protection header is deprecated and the browser XSS auditor it controlled is gone from modern browsers (removed from Chrome in v78, never implemented in Firefox) and could itself introduce vulnerabilities. Do not rely on it. Send X-XSS-Protection: 0 (or omit it) and rely on a strict Content-Security-Policy together with output encoding/sanitization. Wire CSP and the rest of the header set through HTTP Security Headers.

In Carbon 4 based products, input validation is low-priority, so output encoding and sanitization are mandatory; do not rely on input validation to stop XSS.

HTTP Response Splitting (CRLF Injection)¶

External: OWASP HTTP Response Splitting. Read it for how a CR/LF (%0d/%0a) smuggled into a header lets an attacker emit a second, attacker-controlled response (cache poisoning, reflected XSS).

For Carbon 4 based products, Apache Tomcat handles this internally by disallowing CR and LF in header names and values, so application code on the Tomcat transport does not need its own filter. If HTTP responses are generated by a different component or transport implementation, confirm it performs equivalent CR/LF filtering; if it does not, a central filter must read all headers and sanitize them before the response reaches the transport.

// Anti-pattern - untrusted value straight into a cookie
http.SetCookie(w, &http.Cookie{Name: "author", Value: r.URL.Query().Get("author")})
// Safe - validate first, reject on failure
author := r.URL.Query().Get("author")
if err := validateAuthorInput(author); err != nil {
    http.Error(w, "Invalid author input", http.StatusBadRequest)
    return
}
http.SetCookie(w, &http.Cookie{Name: "author", Value: author})

Log Injection / Log Forging¶

External: OWASP Log Injection. Read it for how CR/LF in a logged value forges separate log entries, which matters when logs feed reconciliation or other automated action.

Strip CR/LF from any user-controlled value before logging it; never log raw user input via string concatenation (e.g. log.info("payment to author: " + author)). See Logging and Alerting Failures for the broader logging controls.

Server-Side Template Injection (SSTI)¶

For the attack pattern across template engines, read OWASP SSTI for how a user-controlled template string reaches the engine's expression evaluator.

Substitute user input only into pre-defined parameters of an already-compiled template, never into the template source. Anti-pattern: engine.evaluate(userSuppliedTemplate, context) or any path where user input is parsed as template syntax. Treat any feature that lets users supply template text as a risky exception: deny by default, and route it through the Security and Compliance Team before release. Re-check authorization at the data layer for any data the template can reach, since SSTI escalates to data disclosure and RCE.

NoSQL and XPath injection¶

For test cases and payloads, read OWASP: Testing for NoSQL Injection and OWASP XPath Injection for the operator-injection and predicate-injection shapes specific to each.

Build queries with the driver's structured API (MongoDB filters / BSON documents, an XPath API with bound variables), never by concatenating user input into a query string or by passing raw user input where the driver accepts query operators. Keep every lookup scoped to the caller's tenant/organization identity from the request context, and re-check that scope at the data layer; a missing tenant filter is the same class of defect as a missing WHERE clause.

Regex denial of service (ReDoS)¶

For how catastrophic backtracking arises, read OWASP ReDoS for the vulnerable pattern shapes (nested quantifiers, overlapping alternations).

Never compile a user-supplied regex pattern. Cap input length before matching any pattern against user input.

Email header injection¶

For the attack pattern, read OWASP Email Injection for how CR/LF in a value substituted into an RFC 5322 header (To, Subject, From) lets an attacker add headers or recipients.

Code that sends email must build headers programmatically through a mail library rather than formatting raw header strings, and must strip CR/LF and validate per-header on any user-controlled value. Treat header values as deny-by-default: reject anything outside the expected character set for that header field.

Insecure Design¶

For the threat-modeling method and proactive design controls, read OWASP A04 for the failure class, OWASP Threat Modeling Process for the STRIDE workflow, and OWASP Proactive Controls for the control catalog to design against. Run a design review through your team's normal design-review process before code review begins.

Insecure Design is a missing-control problem, not a coding bug. A perfectly coded feature can still be insecure if the design never accounted for abuse. Design review therefore happens before code review, not after.

Design rules that apply across stacks:

• Model state explicitly. Workflow and resource lifecycles are an enum plus a transition table, checked at the service layer before persistence. Never derive the next state from caller input or infer it from the current request: an attacker who can name the target state can skip the steps that guard it (approval, payment, ownership check).
• Enforce idempotency at the data layer. Use an atomic database operation (a unique constraint or an upsert) rather than a SELECT-then-INSERT window that two concurrent requests can both pass.
• Rate-limit everything that does work. Apply layered budgets: per-user and per-IP and global. A single global limit lets one tenant exhaust the budget for all.
• Name and enforce trust boundaries. Carry tenant identity in the request context and re-check it at the data layer, never trust it from a header or path parameter alone. Make the default deny: enumerate the paths that are public and treat everything else as protected.

Pagination, list limits, and resource ceilings¶

For the resource-consumption attack pattern and its test cases, see OWASP API4:2023.

An unbounded list endpoint is a denial-of-service primitive: a caller asking for everything forces an expensive scan and a large response, and one tenant's request degrades the service for all. Controls:

• Server-enforced maximum page size. The handler clamps or rejects any limit= above the configured ceiling; never honor a client-supplied page size unconditionally. Pick a default page size and a hard maximum, and apply both at the handler before the query is built.
• Avoid expensive total counts. Return a hasMore flag and let callers page until the result is empty, rather than running a COUNT(*) over a large table on every request. Reserve total counts for tables small enough to scan cheaply.
• Per-tenant ceilings. Cap queries-per-minute, maximum stored objects, and maximum attachment size per tenant so one tenant cannot exhaust shared capacity. Resolve the tenant from context (see the trust-boundary rule above), not from caller input.
• Gate unbounded operations. Any operation that could legitimately touch unbounded data (full export, bulk re-index) requires an admin role or a deliberate, separately-rate-limited batch path, not the ordinary list endpoint.

Reject the anti-pattern of "the client passed limit=1000000, so we returned a million rows": the maximum is a server property, enforced server-side, regardless of what the client asks for.

Sensitive business flows and anti-automation¶

For how attackers automate high-value flows and the controls that frustrate them, see OWASP API6:2023.

The first step is identification: during threat modeling, enumerate the flows where automated, high-volume invocation has business cost. Typical sensitive flows include signup, password reset, OTP send, MFA enrollment, gift-code or coupon redemption, refund initiation, and free-tier resource creation. For each, decide the abuse budget and the layered controls before the flow ships.

Controls to layer (no single one suffices):

• Layered budgets: per-user, per-device, per-IP, per-tenant, and global. An attacker rotating IPs is still bounded by the per-account and global limits; an attacker hammering one account is bounded by the per-user limit.
• Behavioral friction: escalate after the first few failures (a CAPTCHA or step-up challenge), and use device fingerprinting where the flow warrants it. Apply friction progressively so legitimate users are not penalized on the first attempt.
• State-changing requests are POST-only and CSRF-protected. For the synchronizer-token, cookie, and multipart-form integration, see OWASP CSRFGuard.
• Observability: every invocation of a sensitive flow emits an audit event, so velocity anomalies are detectable, and the highest-value flows have alerts wired into the deployment's security monitoring. A flow you cannot observe is a flow you cannot defend.

Unrestricted File Upload¶

For the full set of upload checks and known bypasses, see the OWASP File Upload Cheat Sheet. Use it as the bypass checklist your validation must survive.

Unrestricted file upload occurs when the server accepts an upload without adequately validating the file's name, type, content, and size. The risk taxonomy:

• Overwriting critical files: an upload named after an existing critical file replaces it.
• Arbitrary file placement: if the path is also attacker-influenced (directory traversal), a malicious script or executable lands in a sensitive directory.
• Backdoor installation: a web shell stored where the server will execute it gives persistent, code-level control.

Enforce the checks in this order, and stop at the first failure (each check assumes the previous one passed, so order matters; reject by size before you spend cycles parsing content):

1. Container size limit: cap the request body at the container/transport layer so an oversized upload is refused before it reaches your handler.
2. Handler size limit: re-assert the size cap in the handler; the container limit may be looser or absent in some deployments.
3. Content-type allow-list, validated against the bytes: allow only specific types, and confirm the type by inspecting the file content (magic bytes), not the client-supplied Content-Type header or the filename extension. The Content-Type header is attacker-controlled and the extension proves nothing.
4. Filename sanitization: normalize the filename and assign a unique stored name; never persist the client-supplied name verbatim (overwrite risk).
5. Storage outside any web-served directory: store uploads outside the webroot, with no execute permission and least-privilege filesystem permissions, so a stored file can never be requested and run.

Log all upload activity for monitoring.

Serving files back: serve user-uploaded content from a separate hostname (or, at minimum, a separate path with no server-side execution), grant no execute permission, and set the Content-Type explicitly. Send X-Content-Type-Options: nosniff so the browser does not MIME-sniff an upload into an executable type; this header is part of the mandatory set in HTTP Security Headers.

void checkMetaData(File f, String expectedContentType) throws FileUploadException {
    BodyContentHandler handler = new BodyContentHandler();
    Metadata metadata = new Metadata();
    metadata.set(TikaCoreProperties.RESOURCE_NAME_KEY, f.getName());
    Parser parser = new AutoDetectParser();
    try (InputStream stream = new FileInputStream(f)) {
        parser.parse(stream, handler, metadata, new ParseContext());
    } catch (SAXException | TikaException | IOException e) {
        throw new FileUploadException("Unable to inspect file content", e);
    }
    if (!expectedContentType.equals(metadata.get(HttpHeaders.CONTENT_TYPE))) {
        throw new FileUploadException("File content does not match the expected type");
    }
}

func validateFileContent(file multipart.File, expectedType string) error {
    buffer := make([]byte, 512)
    if _, err := file.Read(buffer); err != nil {
        return err
    }
    if _, err := file.Seek(0, io.SeekStart); err != nil {
        return err
    }
    contentType := http.DetectContentType(buffer)
    if !strings.HasPrefix(contentType, expectedType) {
        return fmt.Errorf("file content does not match expected type %s", expectedType)
    }
    return nil
}

Reject these anti-patterns regardless of stack: trusting client-side file-type checks or the Content-Type header; persisting the client-supplied filename without sanitization; storing uploads inside the webroot or with execute permission; and accepting uploads with no size limit.

Authentication Failures¶

The authoritative guideline does not prescribe a fixed set of authentication rules, so this section points at the canonical sources and gives general WSO2 engineering guidance for building against them. Read these for the threat model and the rules; do not reimplement what they specify, implement against them:

• NIST SP 800-63B. Read for memorized-secret (password) length, lifecycle, recovery, and MFA assurance levels, and for which legacy rules it now disallows (mandatory composition, routine forced rotation). Take the actual length floor and breached-password expectations from the current text, not from a number hard-coded here.
• OWASP Authentication Cheat Sheet and Session Management Cheat Sheet. Read for the operational rules and the test cases each control must pass.
• RFC 9700: OAuth 2.0 Security BCP. Read for the required OAuth posture: PKCE (S256 only), exact redirect_uri matching, refresh-token rotation, public-client constraints, and prohibited grant types.
• OWASP Top 10 A07. Read for the broader threat model and the failure categories to test against.

General WSO2 engineering guidance for building authentication on top of those sources:

• Carry tenant identity in the request context and key every credential, lock-state, and session lookup by it, so one tenant can never observe or affect another tenant's authentication.
• Keep policy parameters in configuration, not in code. Password length floor, hashing parameters, lockout thresholds, and breached-password behavior should be config-as-code so they can be tuned and reviewed without a code change, and the chosen algorithm/parameters stored alongside each hash so they can evolve without breaking verification.
• Deny by default. An authentication or authorization decision that cannot be made affirmatively must fail closed; never treat an absent or unrecognized result as "allow".
• Make the authentication decision live below the UI. Re-check the account-lock and authorization decision at the data/credential layer, not only in the interactive login flow, so OAuth, token, and provisioning paths inherit the same decision rather than each re-implementing it.
• For breached-password checking, never let the secret leave the boundary. If you consult an external corpus, use a k-anonymity range query (send only a hash prefix) or a locally hosted mirror; never send the full password or its full hash off-box.
• Treat OWASP/NIST controls (breached-password rejection, MFA factor strength, token storage on clients) as the authority. Browsers should keep refresh tokens in HttpOnly; Secure; SameSite cookies or behind a backend-for-frontend, never in localStorage/sessionStorage; mobile clients should use the platform secret store. These are the cheat-sheet rules, not WSO2-specific inventions.

type otpSession struct {
    Recipient string
    Channel   string
    OTPHash   []byte // SHA-256 of the OTP; never the plaintext
    ExpiresAt int64
}
sum := sha256.Sum256([]byte(otp))
sess := otpSession{Recipient: recipient, Channel: channel, OTPHash: sum[:], ExpiresAt: expiresAt}
// sign sess into a short-lived, single-use token; the server never stores the plaintext OTP

if codeChallengeMethod != CodeChallengeMethodS256 {
    return ErrInvalidChallengeMethod
}

Session Hijacking¶

A session is recognized by a token carried in a cookie; in WSO2 products the session ID is a cookie communicated over HTTP headers. Hijacking compromises that token by sniffing it on the wire, a man-in-the-middle, predicting it, or stealing it client-side (XSS). Read the OWASP Session Management Cheat Sheet for the full control set.

What to do:

• Transport. Emit HSTS so a conformant browser refuses plain HTTP to the domain (defeats SSLStrip and stops a session cookie leaking over an HTTP link to an HTTPS site). Where certificate pinning is in scope, pin the server key (TOFU) to blunt a compromised-CA MITM. The header values, and how to wire them on Carbon/Tomcat, Go services, the API Gateway, reverse proxies, and ingresses, are in HTTP Security Headers: Configuration Reference.
• Cookie attributes. Set HttpOnly; Secure; SameSite so the session cookie cannot travel over an unencrypted channel or be read by script; see Securing Cookies for the WSO2 baseline.
• Unpredictable tokens. See Session Prediction.
• Client-side theft. Defeat the XSS that steals tokens; see Injection output-encoding rules.

<!-- correct: session-bearing cookie is HttpOnly + Secure, set by the container -->

store := sessions.NewCookieStore([]byte(secretKey))
store.Options = &sessions.Options{
    Path:     "/",
    MaxAge:   86400,
    HttpOnly: true,
    Secure:   true,
    SameSite: http.SameSiteStrictMode,
}

Session Fixation¶

If the application keeps the same session ID across the authentication boundary, an attacker who plants a known guest session ID on the victim can ride the session once the victim logs in. The fix is the same on every stack: issue a brand-new session on login and destroy the session on logout.

session.invalidate();
session = request.getSession();   // fresh session
session.setAttribute(AUTHENTICATED, true);

session.invalidate();             // not session.removeAttribute(...)

session.Options.MaxAge = -1       // invalidate the pre-auth session
session.Save(r, w)
session, _ = store.New(r, "session-name")
session.Values["authenticated"] = true
session.Save(r, w)

session.Options.MaxAge = -1       // not delete(session.Values, "authenticated")
session.Save(r, w)

Session Prediction¶

If session IDs are derived from usernames, timestamps, or client IPs, or merely base64-encoded, an attacker who collects a few can reconstruct the generator and forge a valid ID; weak generators are also brute-forceable. Read the OWASP Session Management Cheat Sheet for the entropy and generation requirements.

What to do: use a long random session key with at least 128 bits of entropy, from a CSPRNG. Reject the anti-pattern of building an ID from predictable inputs or encoding instead of randomness.

func GenerateSessionID() (string, error) {
    b := make([]byte, 16) // >= 128 bits
    if _, err := rand.Read(b); err != nil {
        return "", err
    }
    return base64.URLEncoding.EncodeToString(b), nil
}

Password AutoComplete¶

Help the user's password manager identify credential fields by tagging them with the semantic autocomplete tokens: current-password on login forms and new-password on registration and password-change forms.

<!-- login form -->
<input type="password" name="password" autocomplete="current-password"/>

<!-- registration / password-change form -->
<input type="password" name="new-password" autocomplete="new-password"/>

Do not set autocomplete="off" on credential fields. All major browsers deliberately ignore autocomplete="off" for password inputs so that password managers keep working, so the attribute does not suppress storage or autofill; it only fights the password manager and works against WCAG 2.2 SC 1.3.5. Enabling password-manager support is the secure default; OWASP and modern scanners (ZAP, PortSwigger) no longer treat a missing autocomplete="off" as a finding, and disabling autocomplete on credential fields is no longer a recognized security control. This is a front-end control and applies to every rendered authentication form; see also the React secure-coding guidance for component-level forms.

Heap Inspection¶

A password or key left in memory after use can be read from a heap dump. The defense is the same as for any sensitive value: hold it in a mutable buffer (char[] in Java, []byte in Go), never an immutable String, and zero the buffer as soon as the credential operation completes. The clearing helpers and the full rationale live with the rest of the secret-handling rules in Cryptographic Failures.

Software and Data Integrity Failures¶

Integrity failures are about trusting code, configuration, or data whose provenance was never verified: an unsigned release, an image pulled by mutable tag, a CI job with more privilege than it needs, a serialized object that reconstructs into a gadget chain. Read OWASP A08:2021 for the threat model, SLSA for the build-provenance levels to target, and sigstore / cosign for the keyless signing workflow used below. Dependency pinning, single-source resolution, and SBOM generation are integrity controls too, but they live in Software Supply Chain Failures; this section covers what happens to an artefact after it is built and what you accept across a trust boundary at runtime.

WSO2-specific operational rules:

• Sign every release artefact (JAR, container image, Helm chart, OS package) on protected infrastructure with a short-lived signing identity. Publish the signature next to the artefact, a SHA-256 checksum in the release notes, and the verification steps in the install guide.
• Deployment manifests reference container images by digest (@sha256:...), never by mutable tag. A tag can be repointed under you; a digest cannot.
• Every CI workflow declares an explicit minimum permissions: block. A pull_request_target trigger that exposes secrets runs only behind an approval step: untrusted PR code must never reach a secret-bearing job unreviewed.
• Subresource Integrity (SRI) on any third-party JS or CSS loaded from a CDN, so a tampered asset fails to load rather than executing.
• Sensitive write endpoints carry replay protection: a request-level jti or nonce that the server rejects on reuse within a bounded window, combined with a short request expiry.

- name: Sign release artefacts
  run: |
    for f in dist/*.zip; do
      cosign sign-blob --yes --bundle "${f}.cosign.bundle" "${f}"
      sha256sum "${f}" > "${f}.sha256"
    done
    cosign sign --yes "ghcr.io/.../${IMAGE}:${VERSION}"

mac := hmac.New(sha256.New, sharedSecret)
mac.Write(rawBody)
expected := mac.Sum(nil)
got, err := hex.DecodeString(r.Header.Get("X-Hub-Signature-256"))
if err != nil || !hmac.Equal(expected, got) {
    http.Error(w, "invalid signature", http.StatusUnauthorized)
    return
}

Insecure Deserialization¶

Deserialization rebuilds an object from a byte or text stream. When that stream is attacker-controlled, a weak deserializer can be coerced into constructing arbitrary types, the classic route to remote code execution and data tampering. Read the OWASP Deserialization Cheat Sheet for the gadget-chain mechanics and the per-language defenses; the controls below are what to apply in WSO2 code.

Two rules apply regardless of stack: never hand an untrusted stream to a generic decoder, and treat a deserialization failure as a security event. Add an integrity check (a digital signature or HMAC) over any serialized payload that crosses a trust boundary, and log every deserialization failure: an unexpected type or a thrown exception is a signal worth alerting on, not swallowing.

@Override
protected Class<?> resolveClass(ObjectStreamClass osc)
        throws IOException, ClassNotFoundException {
    if (!ALLOWED_CLASSES.contains(osc.getName())) {
        throw new InvalidClassException("Unauthorized deserialization attempt",
                                        osc.getName());
    }
    return super.resolveClass(osc);
}

ObjectInputStream ois = new ObjectInputStream(untrustedInputStream);
String message = (String) ois.readObject(); // no class filtering - RCE surface

dec := json.NewDecoder(io.LimitReader(r.Body, 1<<20)) // 1 MB cap
dec.DisallowUnknownFields()
var in LoginRequest // a defined struct, not interface{}
if err := dec.Decode(&in); err != nil {
    http.Error(w, "invalid payload", http.StatusBadRequest)
    return
}
if err := in.Validate(); err != nil { // re-check after decode
    http.Error(w, "invalid payload", http.StatusBadRequest)
    return
}

var data map[string]interface{}
json.Unmarshal(untrustedInput, &data) // unvalidated, untyped

gob.NewDecoder(r.Body).Decode(&anyValue) // gob on untrusted input

Logging and Alerting Failures¶

Insufficient logging and weak integration with incident response let an attacker pivot and persist for weeks or months before detection, and high-value transactions without tamper-evident trails can be altered or deleted after the fact. The controls below make security-relevant events observable, attributable, and trustworthy.

Read these for the canonical model, then apply the WSO2 rules that follow:

• OWASP Logging Cheat Sheet. Read it for the audit-event field schema, the "what to log" / "what never to log" lists, and the retention and integrity model.
• OWASP Logging Vocabulary Cheat Sheet. Read it for the canonical event-name registry (auth.login, iam.role.grant, key.rotate, …). Use these names verbatim in WSO2 audit events so events correlate across products and SIEM rules.
• OWASP Top 10 A09. Read it for the threat model behind this section.

What the WSO2 guideline requires¶

These four controls are the load-bearing WSO2 requirements for this section. Everything else below is general engineering guidance layered on top of them.

• Log the security-relevant events. All login events, access-control failures, and server-side input-validation failures must be capable of being logged, with sufficient user context to identify a suspicious or malicious account.
• Make logs consumable by centralized log management. Generate logs in a format a centralized log management solution can ingest directly, never free-text prose a regex has to reconstruct.
• Retain for delayed forensic analysis. Keep security-relevant logs long enough that an investigation opened well after the fact still has the evidence it needs.
• Protect high-value transactions with an integrity-controlled audit trail. High-value transactions must have an audit trail with integrity controls to prevent tampering or deletion, for example append-only database tables or an equivalent append-only sink.

Reject these as explicit anti-patterns:

• Insufficient or absent logging of login events, access-control failures, and input-validation failures, and no integration with incident response: events that reach a file nobody watches are not monitoring.
• Audit trails without integrity controls: mutable or deletable logs for high-value transactions, where a record can be silently rewritten or removed.

What every security event must capture¶

Build each audit event so it satisfies the "sufficient user context" requirement above.

• Every audit event carries: the canonical event name, an outcome (success/failure/deny), the authenticated principal, the tenant identity, a correlation/request id, the client source IP, and a timestamp. Make events machine-parseable (structured key/value or JSON).
• Tenant id comes from the authenticated context, never from request input, the same rule applied throughout the Carbon stack. Resolve it from the established server context, not from a header, query parameter, or body field an attacker controls.
• Re-establish who and what tenant at the point you write the audit record, so an event cannot be attributed to the wrong principal by a request that changed identity mid-flight.

Operational logs and audit logs are different sinks¶

Operational logs and audit logs serve different consumers and must not share a sink.

• Operational logs: short retention, the standard log aggregator, free to carry stack traces and framework chatter for debugging.
• Audit logs: long retention, an append-only sink, a stable schema that downstream SIEM rules parse, and no stack traces or framework noise. This is where the integrity-controlled audit trail for high-value transactions lives: append-only storage so records cannot be silently tampered with or deleted.

Resolving the client source IP behind proxies¶

WSO2 products typically sit behind load balancers, gateways, and reverse proxies, so the immediate TCP peer is rarely the real client. Getting the client IP right is standard stack technique plus operator configuration, not a guideline-defined WSO2 control.

• Never trust the raw X-Forwarded-For header. It is attacker-controllable and can be spoofed or padded with bogus hops, so a forged value will be attributed to the wrong client and can poison alerting.
• Resolve the client IP via a proxy-aware extraction against a trusted-proxy list: walk the forwarded chain and accept only hops you trust, taking the first untrusted address as the client. This is your framework's or proxy tier's standard capability, not a documented Carbon helper.
• Make the trusted-proxy list operator-configurable in your product's deployment config and document it. A control that depends on an unset list silently falls back to either the raw header or the proxy address; neither is the client.
• For the actual header set involved (which headers the proxy tier emits and consumes), see the companion HTTP Security Headers doc referenced under Companion configuration below; that is where the header set is wired per platform.

Mask or hash sensitive values¶

Audit events frequently need to reference something sensitive (a token, a key id, a credential-bearing field) for correlation. Reference it without disclosing it.

• Where a value is needed only for correlation, log its hash or a truncated prefix with an explicit ellipsis (abcd1234…), never the full value.
• Never log passwords, full tokens or session ids, private keys, or PII, neither in audit events nor in operational logs. The OWASP Logging Cheat Sheet "what never to log" list is the baseline; treat it as mandatory.
• Redact at the call site: pass already-masked values into the logger, never interpolate a raw secret into a message string and rely on a downstream filter to catch it. Reviewers reject ad-hoc redactors; extend the shared masking helpers your product already ships rather than hand-rolling one per call site.

Integrity and tamper evidence¶

An audit trail an attacker can rewrite is not evidence. This is the integrity-controls requirement from the WSO2 guideline made concrete.

• Forward audit events to a dedicated, append-only sink separate from operational logs, with retention long enough for security investigation and any applicable compliance horizon.
• Consider signing or hash-chaining log batches so a removed or altered record is detectable.
• Log forging via CR/LF is an integrity attack on the log itself. Strip CR/LF from any user-controlled value before it reaches a log statement, and prefer structured fields over string concatenation so injected newlines cannot fabricate a second event. For the per-entry UUID tamper-evidence control, see Injection: Log Injection / Log Forging.

logger.ErrorContext(ctx, "token validation failed",
    slog.String("tenant", tenantID),
    slog.String("request_id", traceID),
    slog.Any("cause", err),
)

Recommended high-signal events to monitor¶

Beyond the OWASP Logging Cheat Sheet baseline, the following are recommended high-signal events to wire into whatever monitors the deployment. This is general detection guidance (pick the ones your product can actually produce), not an enumerated set of WSO2 product features.

• Cross-tenant deny attempts: a strong signal of probing or a broken-isolation bug.
• Refresh-token reuse, where the deployment detects it: a strong signal of a stolen token being replayed.
• Read of a privileged key.
• Change to a security-relevant setting: CORS allow-list, lockout thresholds, JWT issuers, federated IdPs, MFA enforcement.
• N authentication failures from one source or one principal within a window: the lockout-rate / credential-stuffing signal.

An event nobody watches is not monitoring. Wire these into the incident-response pipeline rather than letting them sit in a file; the WSO2 guideline calls out lack of integration with incident response as an anti-pattern.

Companion configuration¶

The header set your code emits (and which headers feed client-IP resolution at the proxy tier) is wired per platform in HTTP Security Headers.

Mishandling of Exceptional Conditions¶

For the error-handling failure modes (swallowed exceptions, fail-open security decisions, and information leakage through error responses), read OWASP Improper Error Handling · CWE-703: Improper Check or Handling of Exceptional Conditions for the catalog of failure modes the controls below defend against.

Three rules cut across every stack:

• Fail secure. When an exception interrupts a security decision (authentication, authorization, signature or token validation, policy evaluation), the outcome must default to deny. Initialize the decision variable to the safe value before the try; never assign the permissive value inside catch.
• Catch the exception you can handle, not the one you can't. Catch typed exceptions, not the broad Exception/Throwable (Java) or a blanket recover() (Go). A broad catch hides the unexpected failures (NullPointerException, OutOfMemoryError, programming bugs) that should surface, not be silently absorbed into a security path.
• Sanitize at the boundary. Internal failure detail (stack traces, file paths, SQL fragments, class names, framework identifiers, host/port reachability) must never reach a client. Map exceptions to a sanitized response at every external boundary, and keep error messages indistinguishable so a response cannot be used as an oracle.

The last rule connects to SSRF, the canonical WSO2 example of the no-oracle rule: there, strict error handling means returning an identical generic error whether a back-channel request failed or returned invalid data, so the response cannot be used as an open/closed-port oracle. The same discipline applies to every error path: distinguishable errors leak structure.

The complement of the no-oracle rule is log the cause: the client gets nothing distinguishing, but the server must record why the failure happened. The Insecure Deserialization control to log deserialization exceptions and failures (an incoming type that is not the expected type, or deserialization throwing) is a concrete instance: deny the operation, return a generic error, and log the real cause so the failed attempt is investigable.

Fail-secure security decisions¶

A catch block sits on the failure path of a security check. If control reaches it, the check did not complete, which means you do not know the answer, which means the answer is deny.

boolean isAuthorized = false;                 // safe default, set before try
try {
    isAuthorized = authorizationManager.isUserAuthorized(user, resource, action);
} catch (UserStoreException e) {              // typed, not Exception/Throwable
    log.error("Authorization check failed for user " + maskedUser(user)
              + " on resource " + resource, e);
    // isAuthorized stays false - fail secure
}
if (!isAuthorized) {
    throw buildForbiddenException(resource, id);   // e.g. RestApiUtil helper
}

allowed, err := authz.IsUserAuthorized(ctx, user, resource, action)
if err != nil {
    log.GetLogger().Error("authorization check failed",
        log.String("user", maskedUser(user)),
        log.String("resource", resource),
        log.Any("error", err),
    )
    return false, fmt.Errorf("authorization check failed: %w", err)
}
return allowed, nil

Anti-patterns reviewers must reject (both stacks):

• The decision variable initialized to the permissive value (boolean allowed = true; / returning true from an error branch): fail open.
• catch (Exception ignored) {} / a bare recover() that swallows and continues a security path.
• A lossy log that drops the cause (log.error("Something failed: " + e.getMessage()) without the throwable; logging only err.Error() without wrapping context).

Catching the right exceptions¶

try {
    URITemplate uriTemplate = new URITemplate(uri);
} catch (URITemplateException e) {            // the exception this call declares
    String msg = "Error parsing URI " + uri;
    log.error(msg, e);                        // include the throwable
    throw new APIManagementException(msg, e); // domain exception, cause preserved
}

defer func() {
    if p := recover(); p != nil {
        stack := string(debug.Stack())
        log.GetLogger().Error("panic during transaction",
            log.String("dbName", t.dbName),
            log.Any("panic", p),
            log.String("stack", stack),     // stack goes to the log, never to the client
        )
        if rbErr := tx.Rollback(); rbErr != nil {
            switch v := p.(type) {
            case error:
                err = errors.Join(fmt.Errorf("transaction aborted: %w", v), rbErr)
            default:
                err = errors.Join(fmt.Errorf("transaction aborted: %v", v), rbErr)
            }
        }
    }
}()

Centralized exception mapping at the boundary¶

Every external boundary (REST, SOAP, gRPC, JMS, scheduled jobs) needs a single place that turns an exception into a client-safe response. Scattering try/catch with hand-built error responses across handlers guarantees that one of them eventually leaks a stack trace.

The pattern: a centralized mapper at the boundary that (1) maps the exception to a canonical error envelope (a stable error code, a safe human-readable message, an optional correlation/trace id), (2) decides server-side whether to log the full stack, and logs it to the server log, never the response, and (3) returns only the sanitized envelope to the caller. The client gets the code and the correlation id; the operator gets the stack trace in the log, keyed by that id.

Resource and tenant cleanup on the exception path¶

The exception path is exactly where cleanup gets skipped, and skipped cleanup of security-scoped state is a vulnerability, not just a leak. Cleanup must run whether the body succeeds or throws.

try (Connection conn = getConnection();
     PreparedStatement ps = conn.prepareStatement(SQL_ORGANIZATION_EXISTS)) {
    ps.setString(1, orgId);
    try (ResultSet rs = ps.executeQuery()) {
        return rs.next();
    }
} catch (SQLException e) {
    throw new APIManagementException("Failed to look up organization", e);
}

// illustrative - confirm the exact API against your PrivilegedCarbonContext version
PrivilegedCarbonContext.startTenantFlow();
try {
    // set the tenant scope on the thread-local carbon context, then do tenant-scoped work
} finally {
    PrivilegedCarbonContext.endTenantFlow();   // runs even if the body throws - scope torn down
}

tx, err := r.db.Begin()
if err != nil {
    return err
}
defer tx.Rollback()   // safe: Rollback is a no-op after a successful Commit