Document ASM Overview page

[flo-c]

What does this PR do? What is the motivation?

APPSEC-68271

Reworks the App and API Protection (AAP) overview documentation to match the product's three overview pages:

• Splits the existing single overview page into three: API Posture, Threat Protection, and Attack Summary.
• _index.md becomes a high-level landing page introducing all three pages, and describes the Customize Page feature for API Posture and Threat Protection.
• Moves the existing Attack Summary content (and its aliases) into a dedicated attack_summary.md.
• Adds api_posture.md and threat_protection.md documenting each page section by section.
• Adds left-nav menu entries for the three pages under the Overview section.

Merge instructions

Merge readiness:

• Ready for merge

Additional notes

[github-actions]

Preview links (active after the build_preview check completes)

New or renamed files

• https://docs-staging.datadoghq.com/florian.chatre/APPSEC-68271-aap-overview-documentation/security/application_security/api_posture/overview
• https://docs-staging.datadoghq.com/florian.chatre/APPSEC-68271-aap-overview-documentation/security/application_security/threat_protection/overview

Renamed files

• https://docs-staging.datadoghq.com/florian.chatre/APPSEC-68271-aap-overview-documentation/security/application_security/attack_summary

[domalessi]

Thanks for the PR! A few inline comments, and then some general feedback/Qs:

• Nav duplication: "API Posture" and "Threat Protection" now exist twice in the left nav (once under Overview, once as top-level App and API Protection children) pointing to different pages. Worth confirming this is intentional and clarifying the distinction.
• "Overview" naming: Consider renaming this section to something more specific (e.g., "Dashboards") rather than repositioning it — this resolves both the vague-heading issue and its odd mid-nav placement (odd to have an "Overview" section in the middle of the left-nav).
• Screenshots: All three pages describe specific UI dashboards but include none. Recommend stating this explicitly and adding screenshots. This would also let some of the prose that narrates UI labels be trimmed.
• Minor consistency: Attack Summary's structure differs from its two new siblings (lower priority, can be a follow-up); a duplicate paragraph appears twice within _index.md itself.

Let me know if you have any questions, and ping me for another look when ready.

[domalessi]

This introduces "Threat Management" undefined on a page titled "Threat Protection" — the similarity in names risks confusing readers about whether these are the same thing. Consider linking "Threat Management" to where it's defined, or adding a short clarifying phrase distinguishing it from "Threat Protection."

[flo-c]

I added a link to a section in a page where "Threat Management" is defined.

[domalessi]

https://datadoghq.atlassian.net/browse/DOCS-15013 for tracking

[flo-c]

Thanks for the PR! A few inline comments, and then some general feedback/Qs:

• Nav duplication: "API Posture" and "Threat Protection" now exist twice in the left nav (once under Overview, once as top-level App and API Protection children) pointing to different pages. Worth confirming this is intentional and clarifying the distinction.
• "Overview" naming: Consider renaming this section to something more specific (e.g., "Dashboards") rather than repositioning it — this resolves both the vague-heading issue and its odd mid-nav placement (odd to have an "Overview" section in the middle of the left-nav).
• Screenshots: All three pages describe specific UI dashboards but include none. Recommend stating this explicitly and adding screenshots. This would also let some of the prose that narrates UI labels be trimmed.
• Minor consistency: Attack Summary's structure differs from its two new siblings (lower priority, can be a follow-up); a duplicate paragraph appears twice within _index.md itself.

Let me know if you have any questions, and ping me for another look when ready.

@domalessi

• I have changed "Overview" to "Overview Pages". All these pages are under the Overview menu in App & API Protection and they provide an overview of the security aspects of the application and the APIs.
• So now, under "Overview Pages", "API Posture" is now "API Posture Overview" and "Threat Protection" si now "Threat Protection Overview".
• I added a screenshot for "API Posture Overview" and a screenshot for "Threat Protection Overview".
• I removed the duplicated paragraphs. The feature that was described in these paragraphs is also described in the siblings pages.

[domalessi]

Hey, @flo-c ! Reaching out to you about this PR: #37857. It’s looking a lot better! Thanks for the updates!

I’m trying to think through the information architecture for this one, and I have some Qs. In particular, what I’m seeing in the UI doesn’t seem to match up with what the PR describes.

In the app today, the App & API Protection overview experience looks like this:

• Summary — a single page (“Protect your applications and APIs”) with three collapsible sections: API posture, Attack coverage, and Attack exposure.
• Protection — a separate page showing the WAF → Traces → Detection Rules → Signals flow, plus “Recommended Security Actions.”
• Dashboards — Attack Summary, Account Takeover, OWASP API Top 10. Attack Summary appears to be a dashboard and not an overview page.

The PR is built around three coequal overview pages (API Posture, Threat Protection, Attack Summary), which doesn’t quite line up with the above:

• “API Posture Overview” maps to the API posture section of the Summary page, not a standalone page.
• “Threat Protection Overview” seems split across the Attack coverage + Attack exposure sections of Summary, and doesn’t match the actual Protection page (WAF flow + Recommended Actions), which the PR doesn’t document.
• “Attack Summary” is documented as an overview page, but in the UI it’s a dashboard.
• The Ask Bits panel and Customize Page sections described in api_posture.md and threat_protection.md don’t appear in the current Summary/Protection views.

Before I do a full editorial pass, could you confirm:

1. Is this documenting the current overview UI or an upcoming redesign? If a redesign, roughly when does it ship?
2. Where do Ask Bits and Customize Page appear? I can’t find them today.
3. Should the Protection page (WAF flow + Recommended Security Actions) be documented here too?

[flo-c]

Hey, @flo-c ! Reaching out to you about this PR: #37857. It’s looking a lot better! Thanks for the updates!

I’m trying to think through the information architecture for this one, and I have some Qs. In particular, what I’m seeing in the UI doesn’t seem to match up with what the PR describes.

In the app today, the App & API Protection overview experience looks like this:

• Summary — a single page (“Protect your applications and APIs”) with three collapsible sections: API posture, Attack coverage, and Attack exposure.
• Protection — a separate page showing the WAF → Traces → Detection Rules → Signals flow, plus “Recommended Security Actions.”
• Dashboards — Attack Summary, Account Takeover, OWASP API Top 10. Attack Summary appears to be a dashboard and not an overview page.

The PR is built around three coequal overview pages (API Posture, Threat Protection, Attack Summary), which doesn’t quite line up with the above:

• “API Posture Overview” maps to the API posture section of the Summary page, not a standalone page.
• “Threat Protection Overview” seems split across the Attack coverage + Attack exposure sections of Summary, and doesn’t match the actual Protection page (WAF flow + Recommended Actions), which the PR doesn’t document.
• “Attack Summary” is documented as an overview page, but in the UI it’s a dashboard.
• The Ask Bits panel and Customize Page sections described in api_posture.md and threat_protection.md don’t appear in the current Summary/Protection views.

Before I do a full editorial pass, could you confirm:

1. Is this documenting the current overview UI or an upcoming redesign? If a redesign, roughly when does it ship?
2. Where do Ask Bits and Customize Page appear? I can’t find them today.
3. Should the Protection page (WAF flow + Recommended Security Actions) be documented here too?

Hello @domalessi

1. This is documenting the upcoming redesign (currently protected behind the feature flag aap_overview_repeat_usecase. I want to rollout the new design tomorrow (3rd July 2026)
2. The Ask Bits panel and the Customize Page button appear at the top of the page (below the filters). You can have a look to the screenshot below
3. The Protection page will not be displayed anymore after the rollout.

[domalessi]

Hi @florian.chatre — I pushed a commit to this branch (f89f48e) that restructures the overview docs. Wanted to explain the reasoning so nothing's a surprise.

What changed: Instead of a standalone "Overview Pages" section, each overview page now lives inside its existing product pillar:

• overview/api_posture.md → api_posture/overview.md (first entry under API Posture)
• overview/threat_protection.md → threat_protection/overview.md (first entry under Threat Protection)
• Attack Summary is back as the standalone overview/_index.md page it was before
• Top-level nav order is now API Posture → Threat Protection → Attack Summary, matching the new UI

Why: The redesigned UI's two areas are named API Posture and Threat Protection — the same as our existing doc pillars. A separate Overview section would have produced two "API Posture" and two "Threat Protection" entries in the left nav. Our docs also already group by concept (API Inventory and Findings live under the API Posture pillar), so the overview pages fit that same precedent.

Editorial fixes in the same commit: fixed a broken further_reading link (/overview-pages/), a missing serial comma, Powerpacks capitalization, changed "Threat Management" → "Threat Protection" for term consistency, and two small clarity tweaks. I left the section headings in title case to match the UI labels.

[domalessi]

Sanity-checked the preview, and everything looks good! As long as the build passes, we're all set!