Revised API Inventory topic for new explorers

content/en/security/application_security/api-inventory/_index.md

@@ -6,9 +6,31 @@
   text: "Mitigate the primary risks to API security"
 ---
 
-## Overview
+API security relies on visibility. The biggest failure mode in most applications isn't missed vulnerabilities, it's missed APIs.
 
-[API Security Inventory][7] monitors your API traffic to provide visibility into the security posture of your APIs, including:
+[API Security Inventory][7] monitors your API traffic to provide visibility into the security posture of your APIs.
+
+**Inventory** is comprised of explorers that correspond to distinct layers in the API security lifecycle:
+
+1. **API Endpoints:** *What APIs exist, and what risk do they expose?*
+
+    Each API endpoint is a unique entry point where data or functionality can be accessed. The API Endpoints explorer enables shadow API detection, asset management, and risk prioritization at the granularity attackers exploit.
+2. **Services:** *Where do risky APIs live, who owns them, and how severe is their collective risk?*
+
+    A service groups multiple endpoints into a logical or deployed component (typically aligned with a microservice, app, or backend system).
+3. **API Findings:** *Which API weaknesses, attacks or misconfigurations require investigation or remediation?*
+
+    API Findings are security detections and policy evaluation results tied to endpoints or services. These represent known or inferred weaknesses or threats in API behavior or configuration.
+
+These explorers correspond to the common API security operational flow: 
+
+1. **Discover:** Identify what endpoints exist using **API Endpoints**.
+2. **Contextualize:** Identify ownership and dependencies using **Services**.
+3. **Detect and respond:** See where attacks or misconfigurations are occurring using **API Findings**.
+
+## API Endpoints
+
+API Endpoints monitors your API traffic to provide visibility into the security posture of your APIs, including:
 
 - **Authentication**: Whether the API enforces authentication.
 - **Authentication Method**: Type of authentication used, such as Basic Auth and API key.
@@ -17,20 +39,18 @@
 - **Attack Exposure**: If the endpoint is targeted by attacks (powered by [App and API Protection][2]).
 - **Business Logic**: Business logic and associated business logic suggestions for this API.
 - **Vulnerabilities**: If the endpoint contains a vulnerability (powered by [Code Security][8] and [Software Composition Analysis][3]).
-- **Findings**: Security findings found on this API.
+- **Findings**: Security findings identified on this API.
 - **Dependencies**: APIs and Databases the API depends on.
 
-Using the API Security Inventory you can:
+Using API Endpoints you can:
 
 - See at a glance which endpoints process sensitive data, are authenticated, have vulnerabilities or findings, or are publicly available.
 - See which endpoints are at risk, and pivot directly into the [Threat Monitoring and Protection][2] service for further investigation or response.
 - See which endpoints are associated to your business's logic, and find business logic suggestions based on your endpoint's traffic history.
 
-<!-- {{< img src="security/application_security/api/api_endpoints_revamp.png" alt="API Security Inventory main page">}} -->
+### Configuration
 
-## Configuration
-
-To use API Security on your services, **you must have AAP Threats Protection enabled**. The following library versions are compatible with API Security Inventory. [Remote Configuration][1] is required.
+To view the API Endpoints on your services, **you must have App and API Protection Threats Protection enabled**. The following library versions are compatible with API Security Inventory. [Remote Configuration][1] is required.
 
 |Technology|Minimum tracer version| Support for sensitive data scanning |
 |----------|----------|----------|
@@ -45,49 +65,67 @@
 
 **Note**: On .NET Core and .NET Fx tracers, you need to set the environment variable `DD_API_SECURITY_ENABLED=true` for API Security features to work properly.
 
-## How it works
-
-API Inventory leverages the Datadog tracing library with AAP enabled to gather security metadata about API traffic, including the API schema, types of sensitive data processed, and the authentication scheme. API information is evaluated per endpoint, every 30 seconds, which should ensure minimal performance impact.
+API Endpoints leverages the Datadog tracing library with App and API Protection enabled to gather security metadata about API traffic, including the API schema, types of sensitive data processed, and the authentication scheme. API information is evaluated per endpoint, every 30 seconds, which should ensure minimal performance impact.
 
-API Inventory Security uses [Remote Configuration][1] to manage and configure scanning rules that detect sensitive data and authentication.
+API Endpoints uses [Remote Configuration][1] to manage and configure scanning rules that detect sensitive data and authentication.
 
 The following risks are calculated for each endpoint:
 
-### Security trace activity
+### Data sources
+
+In the **API Endpoints** explorer, the **Data Sources** show where visibility originates.
+
+The following data sources are explored.
+
+#### AWS API Gateway
+
+The **AWS API Gateway** data source provides a per-endpoint risk view that confirms exposure, traces the source, and remediates at the service or API Gateway level.
+
+If there are active vulnerabilities, attacks, or sensitive data detected, do the following: 
+
+- **Vulnerabilities:** Review the linked SCA or Runtime Code Analysis results to patch the vulnerable library or dependency.
+- **Attacks:** Check the associated signals or traces to confirm exploit attempts, then block or tighten WAF rules at the API Gateway.
+- **Sensitive data:** Investigate the request payloads or services handling that data to ensure encryption, masking, and least-privilege access are enforced.
+
+#### API Definition
+
+Represents the designed endpoints used to detect spec drift or undocumented APIs.
+
+If risks appear for an API Definition data source, treat them as design or configuration flaws in the declared API contract. They likely exist before or outside runtime. 
+
+What actions you take depend on each of the risk surfaces:
+
+- **Vulnerabilities:** Review the spec or associated code to correct insecure defaults (weak auth, unvalidated parameters, etc.) and regenerate the API definition.
+- **Exposed to attacks:** If the defined endpoint is accessible externally by error, restrict it using gateway routing, network controls, or authentication.
+- **Sensitive data detected:** Inspect the schema fields defined as input/output, mask or encrypt sensitive attributes, or remove unnecessary exposure from the spec.
+- **Unauthenticated endpoint:** Verify if authentication was intended, and update the API Definition to enforce security schemes (OAuth, API key, IAM).
+
+#### Spans
+
+The Spans data source shows real traffic and data exposure. Remediation should be performed in code, config, or access controls immediately.
 
-See the number of [attacks][2] your API experienced within the last week.
+What actions you take depend on each of the attack surfaces:
+
+- **Vulnerabilities:** Patch any vulnerable libraries surfaced by SCA or Runtime Code Analysis, then redeploy the service.
+- **API findings discovered:** Review each issue in context of the traced service, fix any code or configurations, and then validate using new traces.
+- **Processing sensitive data:** Confirm data handling complies with policy, sanitize or encrypt PII and limit access to necessary services.
+- **Unauthenticated endpoint:** If the endpoint is not intentionally public, enforce authentication and update service configurations.
 
 ### Processing sensitive data
 
-[AAP][2] matches known patterns for sensitive data in API requests. If it finds a match, the endpoint is tagged with the type of sensitive data processed.
+[App and API Protection][2] matches known patterns for sensitive data in API request and responses. If it finds a match, the endpoint is tagged with the type of sensitive data processed.
 
 The matching occurs within your application, and none of the sensitive data is sent to Datadog.
 
 #### Supported data types
 
-| Category                                          | Category facet   | Type facet        |
-|---------------------------------------------------|------------------|-------------------|
-| Canadian social insurance numbers                 | `pii`            | `canadian_sin`    |
-| United States social security numbers             | `pii`            | `us_ssn`          |
-| UK national insurance numbers                     | `pii`            | `uk_nin`          |
-| US vehicle identification numbers                 | `pii`            | `vin`             |
-| Passport numbers                                  | `pii`            | `passport_number` |
-| E-mail addresses                                  | `pii`            | `email`           |
-| American Express card number                      | `payment`        | `card`            |
-| Diners Club card number                           | `payment`        | `card`            |
-| JCB card number                                   | `payment`        | `card`            |
-| Maestro card number                               | `payment`        | `card`            |
-| Mastercard card number                            | `payment`        | `card`            |
-| VISA card number                                  | `payment`        | `card`            |
-| IBAN bank account number                          | `payment`        | `iban`            |
+To see the supported data types, use the **Personal Information (PII)** facet. You can also see the data type used in the **Sensitive Data** column.
 
 ### Business logic
 
-These tags are determined by the presence of business logic traces, associated to the endpoint.
-
-#### Suggested business logic
+These tags `(users.login.success`, `users.login.failure`, etc.) are determined by the presence of business logic traces associated with the endpoint.
 
-We can suggest a business logic tag for your endpoint based on its HTTP method, response status codes, and URL.
+<div class="alert alert-tip">Datadog can suggest a business logic tag for your endpoint based on its HTTP method, response status codes, and URL.</div>
 
 ### Publicly accessible
 
@@ -119,6 +157,69 @@
 | Basic Authentication                              | `basic_auth`     |
 | Digest access authentication                      | `digest_auth`    |
 
+
+## Services
+
+The **Services** explorer shows where findings from API Endpoints, vulnerabilities, and runtime signals converge by service. Consider it the operational risk view of your applications.
+
+Review your services for the following:
+
+- **Vulnerability risk:** The **Vulnerability Risk** column shows aggregated SCA and IAST results for each service. Vulnerable services  have components needing patching or upgrading.
+- **Signals and attacks:** Click a service to see charts showing ongoing detections for active exploit attempts or recurring attack patterns.
+- **Sensitive data exposure:** Services processing PII (like SSNs or emails) demand stricter controls and monitoring.
+- **Coverage and mode:** Use the **App & API Protection In Monitoring Mode**, **App & API Protection In Blocking Mode**, and the **Inactive** facet to identify where App and API Protection is enabled and enforcing runtime protection.
+- **Trend graphs:** The **Trend** column indicates activity and attack frequency over time.
+
+### Coverage
+
+The **Coverage** column shows which protection and analysis capabilities are active for each service. Use the column to measure the completeness of your protection stack.
+
+For example, here are some use cases for **Coverage**:
+
+- **Runtime protection coverage with App and API Protection**: 
+  - Identify which services are in **Monitoring** or **Blocking** mode.
+  - Move ready-to-block services into blocking mode to actively stop attacks.
+  - Investigate inactive services to see if instrumentation or configuration gaps are leaving APIs exposed.
+- **Software Composition Analysis (SCA) coverage**:
+  - Track which services have their open source dependencies analyzed.
+  - Enable SCA for unscanned services to detect vulnerable libraries early.
+  - Prioritize patching in active services with high dependency risk.
+- **Runtime Code Analysis (IAST) coverage**:
+  - Pinpoint where code-level vulnerability detection is missing.
+  - Enable IAST for production or high-risk apps to uncover exploitable issues in live traffic.
+  - Use results to confirm whether library vulnerabilities are actually reachable in code.
+
+## API Findings
+
+<div class="alert alert-info">API Findings is In Preview. Contact <a href="https://www.datadoghq.com/support/">Datadog Support</a> for more information.</div>
+
+**API Findings** provides a central triage view of all detected API risks across definitions, gateways, and live traffic.
+
+**API Findings** columns:
+
+- **Severity:** Each issue is ranked by risk.
+- **Endpoints:** Shows how many endpoints are affected and their services.
+- **Status and Ticketing:** `Open` or `In Progress` tracks remediation progress and workflow integration.
+
+Use the **Service** facet see each service's endpoints to identify ownership and prioritize by business impact.
+
+### Common operations
+
+Click a finding to view its details and perform a workflow such as Validate > Investigate > Fix > Track:
+
+1. Validate:
+   - Review **What Happened** and **Detected In** to ensure the detection is accurate (service, endpoint, method).
+   - In **Next Steps**, choose whether to **Mute**, **Create Ticket**, or **Run Workflow** depending on ownership and impact.
+2. Investigate:
+   - Use the **Context** tab to examine the endpoint snapshot and attributes (method, path, authentication flags, tags).
+   - **Dectected In** provides information for routing ownership and remediation.
+   - In **Detection Rule Query**, if runtime data (from spans/traces) contributed to the finding, you can view those traces by clicking **See Detection Rule**.
+3. Fix: 
+   - Follow the guidance under **Remediation**.
+4. Track:
+   - Use **Create Ticket** to link the issue to your tracking system.
+   - Use **Reference Links** for developer education or code review.
+
 ## Further reading
 
 {{< partial name="whats-next/whats-next.html" >}}
@@ -128,4 +229,4 @@
 [3]: /security/code_security/software_composition_analysis/
 [6]: /security/application_security/policies/library_configuration/#configuring-a-client-ip-header
 [7]: https://app.datadoghq.com/security/appsec/inventory/apis
-[8]: /security/code_security/iast/
+[8]: /security/code_security/iast/