Skip to content

Commit a3cf37a

Browse files
michaelcretzmanAnilm3nizoxmargheritadonnicimaycmlee
authored
Revised API Inventory topic for new explorers (#32859)
* Revised API Inventory topic for new explorers - expanded API Endpoints section, including new AWS Gateway data source - added sections for Services, and API Findings * Apply suggestions from code review Co-authored-by: Anil Mahtani <[email protected]> Co-authored-by: Nicolas Vivet <[email protected]> * incorp tech review * minor edits * Apply suggestion from @Anilm3 Co-authored-by: Anil Mahtani <[email protected]> * Apply suggestions from code review Co-authored-by: Margherita <[email protected]> Co-authored-by: Nicolas Vivet <[email protected]> * minor edits * adding info on shadow and orphan APIs * Apply suggestions from code review incorp peer edit Co-authored-by: May Lee <[email protected]> --------- Co-authored-by: Anil Mahtani <[email protected]> Co-authored-by: Nicolas Vivet <[email protected]> Co-authored-by: Margherita <[email protected]> Co-authored-by: May Lee <[email protected]>
1 parent 874c182 commit a3cf37a

File tree

1 file changed

+142
-37
lines changed
  • content/en/security/application_security/api-inventory

1 file changed

+142
-37
lines changed

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

Lines changed: 142 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -6,31 +6,61 @@ further_reading:
66
text: "Mitigate the primary risks to API security"
77
---
88

9-
## Overview
9+
API security relies on visibility. The biggest failure mode in most applications isn't missed vulnerabilities, it's missed APIs.
1010

11-
[API Security Inventory][7] monitors your API traffic to provide visibility into the security posture of your APIs, including:
11+
[API Security Inventory][7] provides a comprehensive, up-to-date catalog and risk assessment of all API endpoints and services in your environment.
12+
13+
**Inventory** is comprised of explorers that correspond to distinct layers in the API security lifecycle:
14+
15+
1. **API Endpoints:** *What APIs exist, and what risk do they expose?*
16+
17+
Each API endpoint is a unique entry point where data or functionality can be accessed. The API Endpoints explorer enables shadow API (undocumented endpoints with no API definition and not detected from Amazon API Gateway) and orphan API (documented endpoints without traffic) detection, asset management, and risk prioritization at the granularity attackers exploit.
18+
19+
2. **Services:** *Where do risky APIs live, who owns them, and how severe is their collective risk?*
20+
21+
A service groups multiple endpoints into a logical or deployed component (typically aligned with a microservice, app, or backend system).
22+
3. **API Findings:** *Which API weaknesses, attacks or misconfigurations require investigation or remediation?*
23+
24+
API Findings are security detections and policy evaluation results tied to endpoints. These represent known or inferred weaknesses or threats in API behavior or configuration.
25+
26+
These explorers correspond to the common API security operational flow:
27+
28+
1. **Discover:** Identify what endpoints exist using **API Endpoints**.
29+
2. **Contextualize:** Identify ownership and dependencies using **Services**.
30+
3. **Detect and respond:** See where misconfigurations are, and where attacks could occur, using **API Findings**.
31+
32+
## API Endpoints
33+
34+
API Endpoints monitors your API traffic to provide visibility into the security posture of your APIs, including:
1235

1336
- **Authentication**: Whether the API enforces authentication.
1437
- **Authentication Method**: Type of authentication used, such as Basic Auth and API key.
1538
- **Public Exposure**: Whether the API is processing traffic from the internet.
1639
- **Sensitive data flows**: Sensitive data handled by the API and flows between APIs.
17-
- **Attack Exposure**: If the endpoint is targeted by attacks (powered by [App and API Protection][2]).
40+
- **Attack Exposure**: If the endpoint is targeted by attacks.
1841
- **Business Logic**: Business logic and associated business logic suggestions for this API.
1942
- **Vulnerabilities**: If the endpoint contains a vulnerability (powered by [Code Security][8] and [Software Composition Analysis][3]).
20-
- **Findings**: Security findings found on this API.
43+
- **Findings**: Security findings identified on this API.
2144
- **Dependencies**: APIs and Databases the API depends on.
2245

23-
Using the API Security Inventory you can:
46+
Using API Endpoints you can:
2447

25-
- See at a glance which endpoints process sensitive data, are authenticated, have vulnerabilities or findings, or are publicly available.
48+
- See which endpoints process sensitive data, are authenticated, have vulnerabilities or findings, or are publicly available.
2649
- See which endpoints are at risk, and pivot directly into the [Threat Monitoring and Protection][2] service for further investigation or response.
2750
- See which endpoints are associated to your business's logic, and find business logic suggestions based on your endpoint's traffic history.
2851

29-
<!-- {{< img src="security/application_security/api/api_endpoints_revamp.png" alt="API Security Inventory main page">}} -->
52+
### Configuration
53+
54+
To view API Endpoints on your services, **you must have App and API Protection Threats Protection enabled**.
55+
56+
For Amazon Web Services (AWS) API Gateway integration, you must set up the following:
57+
58+
- [Amazon Web Services][9]
59+
- [Amazon API Gateway Integration][10]
3060

31-
## Configuration
61+
API Endpoints are discovered from the Datadog Software Catalog and specifically from API definitions [uploaded to Datadog][13].
3262

33-
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.
63+
For information on what library versions are compatible with API Security Inventory, see [Enabling App and API Protection][11]. [Remote Configuration][1] is required.
3464

3565
|Technology|Minimum tracer version| Support for sensitive data scanning |
3666
|----------|----------|----------|
@@ -45,49 +75,58 @@ To use API Security on your services, **you must have AAP Threats Protection ena
4575

4676
**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.
4777

48-
## How it works
78+
### How it works
79+
80+
API Endpoints gathers security metadata about API traffic by leveraging the Datadog tracing library with App and API Protection enabled, alongside configurations from Amazon API Gateway and uploaded API Definitions. This data includes the discovered API schema, the types of sensitive data (PII) processed, and the authentication scheme in use. The API information is continuously evaluated, ensuring a comprehensive and up-to-date view of your entire API attack surface.
81+
82+
API Endpoints uses [Remote Configuration][1] to manage and configure scanning rules that detect sensitive data and authentication.
83+
84+
The following risks are calculated for each endpoint.
85+
86+
### Data sources
87+
88+
In the **API Endpoints** explorer, the **Data Sources** show where visibility originates.
89+
90+
The following data sources are explored.
91+
92+
#### Amazon API Gateway
93+
94+
The Amazon API Gateway service formally defines your API structure. Datadog AWS integration reads this pre-defined configuration from the Amazon API Gateway, and then Datadog uses this configuration to create API endpoint entries in **Inventory**.
95+
96+
Use **AWS API Gateway** in **Data Source** to gain visibility into these exposed endpoints. You can also use the query `datasource:aws_apigateway`.
97+
98+
#### Software Catalog
4999

50-
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.
100+
The **Software Catalog** data source shows API endpoints that Datadog learned about from the formal specification uploaded to Datadog. The API specification is attached to, or registered as, a dedicated API component within the IDP service entity.
51101

52-
API Inventory Security uses [Remote Configuration][1] to manage and configure scanning rules that detect sensitive data and authentication.
102+
This source ensures that your API inventory is complete by including all planned and formally documented endpoints.
53103

54-
The following risks are calculated for each endpoint:
104+
#### APM traces
55105

56-
### Security trace activity
106+
The **Spans** data source shows real traffic and data exposure. Remediation should be performed in code, config, or access controls immediately.
57107

58-
See the number of [attacks][2] your API experienced within the last week.
108+
What actions you take depend on each of the attack surfaces:
109+
110+
- **Vulnerabilities:** Patch any vulnerable libraries surfaced by SCA or Runtime Code Analysis, then redeploy the service.
111+
- **API findings discovered:** Review each issue in context of the traced service, fix any code or configurations, and then validate using new traces.
112+
- **Processing sensitive data:** Confirm data handling complies with policy, sanitize or encrypt PII, and limit access to necessary services.
113+
- **Unauthenticated endpoint:** If the endpoint is not intentionally public, enforce authentication and update service configurations.
59114

60115
### Processing sensitive data
61116

62-
[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.
117+
[App and API Protection][2] matches known patterns for sensitive data in API requests and responses. If it finds a match, the endpoint is tagged with the type of sensitive data processed.
63118

64119
The matching occurs within your application, and none of the sensitive data is sent to Datadog.
65120

66121
#### Supported data types
67122

68-
| Category | Category facet | Type facet |
69-
|---------------------------------------------------|------------------|-------------------|
70-
| Canadian social insurance numbers | `pii` | `canadian_sin` |
71-
| United States social security numbers | `pii` | `us_ssn` |
72-
| UK national insurance numbers | `pii` | `uk_nin` |
73-
| US vehicle identification numbers | `pii` | `vin` |
74-
| Passport numbers | `pii` | `passport_number` |
75-
| E-mail addresses | `pii` | `email` |
76-
| American Express card number | `payment` | `card` |
77-
| Diners Club card number | `payment` | `card` |
78-
| JCB card number | `payment` | `card` |
79-
| Maestro card number | `payment` | `card` |
80-
| Mastercard card number | `payment` | `card` |
81-
| VISA card number | `payment` | `card` |
82-
| IBAN bank account number | `payment` | `iban` |
123+
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.
83124

84125
### Business logic
85126

86-
These tags are determined by the presence of business logic traces, associated to the endpoint.
87-
88-
#### Suggested business logic
127+
These tags (`(users.login.success`, `users.login.failure`, etc.) are determined by the presence of business logic traces associated with the endpoint.
89128

90-
We can suggest a business logic tag for your endpoint based on its HTTP method, response status codes, and URL.
129+
<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>
91130

92131
### Publicly accessible
93132

@@ -108,7 +147,7 @@ Authentication is determined by:
108147
- The presence of a user ID within the trace (for example, the `@usr.id` APM attribute).
109148
- The request has responded with a 401 or 403 status code.
110149

111-
Datadog reports the type of authentication when available in a header through the Authentication Method facet.
150+
When the type of authentication is available, Datadog reports it in a header through the **Authentication Method** facet.
112151

113152
#### Supported authentication methods
114153

@@ -119,13 +158,79 @@ Datadog reports the type of authentication when available in a header through th
119158
| Basic Authentication | `basic_auth` |
120159
| Digest access authentication | `digest_auth` |
121160

161+
162+
## Services
163+
164+
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.
165+
166+
Review your services for the following:
167+
168+
- **Vulnerability risk:** The **Vulnerability Risk** column shows aggregated SCA and IAST results for each service. Vulnerable services have components needing patching or upgrading.
169+
- **Signals and attacks:** Click a service to see charts showing ongoing detections for active exploit attempts or recurring attack patterns.
170+
- **Sensitive data exposure:** Services processing PII (such as SSNs or emails) demand stricter controls and monitoring.
171+
- **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.
172+
- **Trend graphs:** The **Trend** column indicates activity and attack frequency over time.
173+
174+
### Coverage
175+
176+
The **Coverage** column shows the active protection and analysis capabilities for each service. Use **Coverage** to measure the completeness of your protection stack.
177+
178+
For example, here are some use cases for **Coverage**:
179+
180+
- **Runtime protection coverage with App and API Protection**:
181+
- Identify the services in **Monitoring** or **Blocking** mode.
182+
- Move ready-to-block services into blocking mode to actively stop attacks.
183+
- Investigate inactive services to see if instrumentation or configuration gaps are leaving APIs exposed.
184+
- **Software Composition Analysis (SCA) coverage**:
185+
- Track the services with analyzed open source dependencies.
186+
- Enable SCA for unscanned services to detect vulnerable libraries early.
187+
- Prioritize patching inactive services with high dependency risk.
188+
- **Runtime Code Analysis (IAST) coverage**:
189+
- Pinpoint where code-level vulnerability detection is missing.
190+
- Enable IAST for production or high-risk apps to uncover exploitable issues in live traffic.
191+
- Use results to confirm whether library vulnerabilities are actually reachable in code.
192+
193+
## API Findings
194+
195+
**API Findings** provides a central triage view of all detected API risks across definitions, gateways, and live traffic. It provides a set of default rules to detect common vulnerabilities and misconfigurations. You can also set up [custom rules][12] to adapt to specific use cases.
196+
197+
**API Findings** columns:
198+
199+
- **Severity:** Each issue is ranked by risk.
200+
- **Endpoints:** Shows how many endpoints are affected and their services.
201+
- **Status and Ticketing:** `Open` or `In Progress` tracks remediation progress and workflow integration.
202+
203+
Use the **Service** facet to see each service's endpoints to identify ownership and prioritize by business impact.
204+
205+
### Common operations
206+
207+
Click a finding to view its details and perform a workflow such as Validate > Investigate > Fix > Track:
208+
209+
1. Validate:
210+
- Review **What Happened** and **Detected In** to ensure the detection is accurate (service, endpoint, method).
211+
- In **Next Steps**, choose whether to **Mute**, **Create Ticket**, or **Run Workflow** depending on ownership and impact.
212+
2. Investigate:
213+
- Use the **Context** tab to examine the endpoint snapshot and attributes (method, path, authentication flags, tags).
214+
- **Dectected In** provides information for routing ownership and remediation.
215+
- In **Detection Rule Query**, you can edit an API finding rule by clicking **See Detection Rule**.
216+
3. Fix:
217+
- Follow the guidance under **Remediation**.
218+
4. Track:
219+
- Use **Create Ticket** to link the issue to your tracking system.
220+
- Use **Reference Links** for developer education or code review.
221+
122222
## Further reading
123223

124224
{{< partial name="whats-next/whats-next.html" >}}
125225

126226
[1]: /tracing/guide/remote_config/
127-
[2]: /security/workload_protection/
227+
[2]: /security/application_security/
128228
[3]: /security/code_security/software_composition_analysis/
129229
[6]: /security/application_security/policies/library_configuration/#configuring-a-client-ip-header
130230
[7]: https://app.datadoghq.com/security/appsec/inventory/apis
131231
[8]: /security/code_security/iast/
232+
[9]: /integrations/amazon-web-services
233+
[10]: /integrations/amazon-api-gateway
234+
[11]: /security/application_security/setup/
235+
[12]: /security/application_security/policies/custom_rules/
236+
[13]: /internal_developer_portal/software_catalog/entity_model/native_entities/?tab=api#native-entity-types

0 commit comments

Comments
 (0)