[WAF] Improve managed rules troubleshooting: payload logging and malicious uploads

[zeinjaber]

Resolves DEE-3647.

Adds two pieces of guidance to the WAF managed rules troubleshooting page that were missing from the page:

• Payload logging (false positives): tells readers to use payload logging to see which part of a request matched a rule, and to configure it ahead of time so the payload is captured for the next investigation. Links to the payload logging overview and the dashboard configuration page. Notes it is Enterprise-only.
• Malicious uploads / binary content (false positives, Additional recommendations): explains that managed rulesets inspect standard HTTP content, that binary uploads can cause false positives, and points to Malicious uploads detection for scanning file uploads.

Intentionally not changed

The ticket also suggested adding WAF attack score guidance for false negatives and clarifying exception-vs-disable behavior. Both are already documented on this page (the Troubleshoot false negatives section already recommends WAF attack score, and the Troubleshoot false positives section already covers exceptions vs disabling rules), so they were left as-is to avoid duplication.

Notes

• Docs-only change; no product/runtime changes.
• All internal links verified against existing pages.

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/waf/	@danielegm, @worenga, @xmflsct, @cloudflare/appsec-reviewers, @cloudflare/firewall, @cloudflare/product-owners

[ask-bonk]

PR Review for #31683

Summary

This PR makes a clean, docs-only change to src/content/docs/waf/managed-rules/troubleshooting.mdx by adding two pieces of missing guidance:

1. Payload logging for false positives — A new paragraph under Troubleshoot false positives recommends enabling payload logging to identify the exact request content that triggered a managed rule. It links to the payload logging overview and dashboard configuration pages and notes the Enterprise plan restriction.
2. Binary uploads / Malicious uploads — A new bullet under Additional recommendations explains that binary uploads (e.g., file uploads) can cause false positives in managed rulesets, and points users to the Malicious uploads detection feature.

The additions are well-placed, the links are valid, and no new components or frontmatter changes are required.

Suggested Labels

• product:waf
• documentation

Issues Flagged

1. Minor technical inaccuracy — “encrypted with a key pair”
In the payload logging paragraph, the parenthetical says (encrypted with a key pair that you provide). In asymmetric cryptography, data is encrypted with the public key from the pair, not the pair itself. The existing payload logging overview already uses the phrasing “encrypted with a customer-provided public key”.

Suggested change: Update the wording to match the existing documentation.

src/content/docs/waf/managed-rules/troubleshooting.mdx (line 25)

To get more detail about which part of a request matched a managed rule, enable [payload logging](/waf/managed-rules/payload-logging/) for the affected managed ruleset. Payload logging records the specific string that triggered each rule (encrypted with a public key that you provide), which helps you confirm whether a match was a false positive. If you have not set it up yet, [configure payload logging](/waf/managed-rules/payload-logging/configure/) so that the matched payload is available the next time you investigate a false positive. Payload logging is available on Enterprise plans.

2. (Optional) Plan restriction formatting
The Enterprise plan requirement is stated inline: Payload logging is available on Enterprise plans. The style guide recommends using a :::note admonition for plan restrictions when they cannot be integrated into prose. Since it is integrated here, inline text is acceptable, but wrapping it in a note admonition would make it more prominent. This is optional and can be left to author/maintainer discretion.

3. (Optional) Link text for configuration page
The link text configure payload logging is a descriptive verb phrase. While this reads naturally, the style guide prefers link text that matches the target page title (Configure payload logging in the dashboard). Existing WAF docs do use both styles, so this is non-blocking.

---

Verdict: LGTM with the suggested wording fix for the encryption description. All links verified, frontmatter unchanged, and no build concerns identified.

github run

[cloudflare-docs-bot]

Review

⚠️ Part of the review could not complete in commit 579e6ec — it will retry on the next push.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

_{No code review issues found.}

Conventions

❌ This review could not complete this run; results may be incomplete. It will retry on the next push.

Style Guide Review

_{No style-guide issues found.}

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.
/rebase	Rebases the PR branch against production. On conflict, attempts to resolve automatically using AI. Stops with an explanation if confidence is not high enough.

[github-actions]

Preview URL: https://579e6ec5.preview.developers.cloudflare.com
Preview Branch URL: https://zein-dee-3647-managed-rules-troubleshooting.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/waf/managed-rules/troubleshooting/	https://zein-dee-3647-managed-rules-troubleshooting.preview.developers.cloudflare.com/waf/managed-rules/troubleshooting/

[github-actions]

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant).

[zeinjaber]

@elithrar @danielegm @hsaxenaCF - can you review this PR, please? Thanks

[github-actions]

Hey there, we've marked this pull request as stale because there's no recent activity on it. This label helps us identify PRs that might need updates (or to be closed out by our team if no longer relevant).

[zeinjaber]

@elithrar @danielegm - could you please review this PR? Thanks.

[zeinjaber]

/rebase

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://zein-dee-3647-managed-rules-troubleshooting.previews.developers.cloudflare.com (commit 579e6ec)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://787fcd42.previews.developers.cloudflare.com	579e6ec	2026-09-08T09:08:35.238Z	Visit the dashboard ↗
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://136617b6.previews.developers.cloudflare.com	6a3852a	2026-08-26T09:26:11.296Z	Visit the dashboard ↗

[zeinjaber]

/rebase