Skip to content
WebDecoy Docs

Authentication attack correlation

One failed login is usually ordinary. The same actor failing against many accounts, or several actors concentrating on one account, is a sequence worth investigating. WebDecoy correlates those sequences from a small authentication outcome reported by a trusted server or edge sensor.

Authentication correlation does not inspect passwords, tokens, form bodies, usernames, or email addresses. It does not change a request’s threat score or create a blocking rule.

Report a privacy-bounded outcome

Section titled “Report a privacy-bounded outcome”

Send auth_outcome at the top level of an authenticated, property-scoped SDK request:

{
  "request_metadata": {
    "method": "POST",
    "path": "/login",
    "ip": "203.0.113.10",
    "user_agent": "example-client"
  },
  "auth_outcome": {
    "schema_version": 1,
    "route_template": "/login",
    "outcome": "failure",
    "subject_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}

Compute subject_id as lowercase HMAC-SHA-256 of your local account identifier with a secret key dedicated to that WebDecoy property. Send the digest, never the username, email address, account ID, or HMAC key. A property-specific key prevents the same account from becoming a join key across sites.

Allowed outcomes are failure, success, and clearance_minted. route_template must be a stable route such as /login or /tenants/:tenant/login, without a query string or user-controlled path value. Set exclude_from_correlation to true for health checks, synthetic monitoring, or another route you intentionally exclude.

The contract rejects unknown fields. In particular, adding username, password, token, headers, or a request body makes the outcome invalid. Visitor-controlled headers cannot supply or replace it. Existing SDK versions do not automatically forward this new field; use an adapter that explicitly implements the contract until your SDK documents support.

A request without a trusted auth_outcome has unknown authentication coverage. WebDecoy does not infer failure or success from its path or status code, and the absence of a correlation finding is not proof that no authentication attack occurred.

Findings

Section titled “Findings”

WebDecoy evaluates each property in a 15-minute window:

Finding Minimum sequence Identity requirement
Password spray One actor fails against at least five distinct subject digests on the same route A strong, non-shared actor fingerprint
Distributed subject attack One subject receives failures from at least three distinct origins on the same route Strong actors count separately; each coarse shared-network fingerprint counts as one network group
Post-failure success risk A success or clearance mint follows at least five failures from at least three origins for one subject Property-scoped subject digest plus the distinct-origin rule above

The last finding means takeover risk, not proof that an account was compromised. A successful login can be legitimate, and shared network groups can contain unrelated clients. Confirm it against your own authentication and account audit logs.

Repeated retries against one subject from one origin do not meet these thresholds. A shared NAT cannot manufacture several origins by itself. Synthetic detections, unverified reporters, browser assertions, excluded routes, and malformed outcomes do not enter the correlation.

Retention and access

Section titled “Retention and access”

The keyed subject digest is retained with the detection and internal correlation evidence under the same organization, property, access controls, and retention policy as that detection. The HMAC key and original account identifier remain in your application.

The MCP correlation tools expose the rule, route template, outcome class, and bounded aggregate counts. They do not expose the subject digest or per-event authentication evidence. Use your own audit log to resolve an investigation to an account.

Section titled “Related”