octoperf-auto-correlation

# OctoPerf — Auto-correlation workflow

When a recorded Virtual User (VU) fails its replay because dynamic
server-issued values become stale, **correlation** is the fix: extract
the new value from a response and inject it into the next request. This
skill drives that loop through the MCP tools without manually editing
the VU.

## When this applies

Apply this skill in one of two modes.

**Reactive** — when **all** of:

- The VU was imported (`import_har_virtual_user`, `upload_jmx_virtual_user`, `import_postman_virtual_user`, …) — not hand-written.
- A `validate_virtual_user` run finished with failures.
- The failures look like dynamic-value mismatches: HTTP 401/403 on the second+ request, server errors about "invalid token", "expired session", "CSRF mismatch", "signature verification failed", "nonce reused", or response bodies referencing IDs/keys that don't match what the request sent.

**Proactive** — validation is clean but a `run_scenario` is planned.
A 1-user validation often masks correlation gaps because JMeter's
`CookieManager` auto-handles session cookies — under concurrent load
the same VU can break (per-session token binding, race conditions,
WAF heuristics). Walk the VU with `get_virtual_user` and look for
hardcoded server-generated values still in place: long base64 / hex
strings, session ids in URL paths (`;jsessionid=...`), hidden form
tokens (`_sourcePage`, `__fp`, `__VIEWSTATE`, …), JWTs in headers.
Apply step 2 (framework presets) to harden, then re-validate.

If failures are about request *bodies* (wrong JSON shape), missing
variables, HTTP server config (wrong timeout / baseUrl), or 5xx server
errors unrelated to identity — this is **not** an auto-correlation
problem; use the validation-triage skill instead.

## Steps

### 0. Snapshot the VU before you rewrite it

Correlation rewrites the VU's action tree **in place**, and OctoPerf
has **no VU versioning** — `apply_correlations_to_virtual_user` and a
bad custom rule are hard to undo. Take a one-call backup first:

```
mcp__octoperf__backup_virtual_user(virtualUserId, label="pre-correlation")
```

This duplicates the VU in the same project (full action tree, recorded
bodies excluded) and tags the copy `backup` + `pre-correlation` so it's
easy to find. If a framework or rule mangles the tree, discard the
working VU and re-correlate from the copy instead of re-importing from
scratch. Skip it only when the VU is itself a throwaway import you can
trivially re-create.

### 1. Confirm the diagnosis on one failing request

Don't skip this. Correlation rewrites your VU; you want to be sure the
fix matches the symptom.

```
mcp__octoperf__get_virtual_user_validation_index(virtualUserId)
```

Pick the *first* failing action whose error category looks like
"identity / state". Then:

```
mcp__octoperf__get_validation_failure_detail(virtualUserId, actionId)
```

This returns the four HTTP entities: the request as **sent**, the
request as **received**, the response as **sent**, the response as
**received**. Look for a value that appears in the previous response
but is missing/stale in this request. Common shapes:

- A `Set-Cookie` header on response N that doesn't show up on request N+1.
- A hidden form input `<input name="__RequestVerificationToken" value="…">` in HTML, whose recorded value is sent back as a form field on the next POST.
- A JSON field `{ "sessionId": "…" }` echoed back in subsequent request bodies or query strings.
- An `Authorization: Bearer <jwt>` recorded at capture time, where the JWT's `exp` is now in the past.

If you spot one, you've confirmed correlation is the right fix.

### 2. Try a framework preset first

Frameworks are curated rule packs that catch the standard correlation
patterns of a given stack. They're the cheapest fix.

```
mcp__octoperf__list_correlation_frameworks()
```

Pick the one matching the target system. The lists below are the
exact extractor names each preset registers — match them against what
you see in the recorded traffic.

- **SAML** — federated SSO. Catches the request / response payloads
  (`SAMLRequest`, `SAMLResponse`), the signature material
  (`Signature`, `SignatureValue`, `DigestValue`, `X509Certificate`),
  assertion metadata (`AssertionID`, `nameid-format`, `IssueInstant`,
  `NotBefore`, `NotOnOrAfter`, `AuthenticationInstant`,
  `correlationId`), the context tokens (`ctx`, `wctx`), and the
  Azure-AD-flavored attributes that often live inside the assertion
  (`objectIdentifier`, `tenantId`, `puuid`, `name`,
  `authnmethodsreferences`). 22 extractors total.
- **OAuth** — OAuth 1.0a-style flows. Catches `oauth_token`,
  `oauth_state`, `oauth_timestamp` (plus the `…1` re-extracted
  variants for double-occurrence in the trace). For OAuth 2.0 with
  PKCE / authorization-code, use **AzureAD** if the IdP is Microsoft,
  otherwise build per-VU rules with `create_correlation_rule`.
- **Token** — generic CSRF / session tokens not tied to a stack.
  Catches `x-csrf-token`, `csrfToken`, `token`, `authtoken`, `pk`
  (with `…1` / `…2` re-extracted variants), and `ReturnURL` echoes.
  9 extractors total. **Note:** the ASP.NET anti-forgery
  `__RequestVerificationToken` is in **.NET**, not here.
- **.NET** — ASP.NET WebForms. Catches `__VIEWSTATE`,
  `__VIEWSTATEGENERATOR`, `__EVENTVALIDATION`, `__PREVIOUSPAGE`,
  `__REQUESTID`, and the anti-forgery `__RequestVerificationToken`,
  with `__VIEWSTATE1` / `__EVENTVALIDATION1` re-extracted variants for
  multi-form pages.
- **Java** — Java-server session bootstrap. Catches `sessionId` only.
  For JSF (`javax.faces.ViewState`) or Spring Security (`_csrf`),
  build per-VU rules with `create_correlation_rule` — they are *not*
  bundled here. **Session cookies** (`JSESSIONID`, `PHPSESSID`,
  `ASPSESSIONID`, …) are auto-handled by JMeter's `CookieManager`
  (it re-injects `Set-Cookie` → `Cookie` for you) — a custom rule is
  only needed when the value also appears in URL paths
  (`;jsessionid=...` URL rewriting fallback), in `Referer` headers