Merge pull request #233860 from rayne-wiselman/rayne-defenderapi

first draft of Defender for APIs docs

Author: American-Dipper

articles/defender-for-cloud/TOC.yml

@@ -95,6 +95,8 @@
     - name: Defender for Cloud support matrices
       displayName: coverage, supported platforms, cloud services, roles, permissions
       href: support-matrix-defender-for-cloud.md
+    - name: Defender for Cloud cloud support
+      href: support-matrix-cloud-environment.md
     - name: Defender for Servers support matrices
       displayName: coverage, machines, windows, linux, multicloud, supported features, endpoint protections
       href: support-matrix-defender-for-servers.md
@@ -160,6 +162,9 @@
       - name: External attack surface management (EASM)
         displayName: EASM, attack surface management
         href: concept-easm.md
+      - name: Agentless scanning
+        displayName: agentless, scanning, virtual, machines, freshness, snapshot, snapshots
+        href: concept-agentless-data-collection.md
   - name: Improve your data security posture
     items:
     - name: About data-aware security posture
@@ -182,6 +187,14 @@
     - name: Reference list of attack paths and cloud security graph components
       displayName: attack, paths, security, graph, components
       href: attack-path-reference.md
+    - name: Security alerts
+      items:
+      - name: About security alerts and incidents
+        displayName: security, alerts, classification, incident, threat, detection, analytics, 
+        href: alerts-overview.md
+      - name: Security alerts reference list
+        displayName: alerts, mitre
+        href: alerts-reference.md
   - name: Plan Defender for Servers deployment
     items:
     - name: Get started
@@ -195,22 +208,13 @@
       href: plan-defender-for-servers-select-plan.md
     - name: Review agents and extensions
       href: plan-defender-for-servers-agents.md
+    - name: Agentless scanning
+      displayName: agentless, scanning, virtual, machines, freshness, snapshot, snapshots
+      href: concept-agentless-data-collection.md
     - name: Scale a Defender for Servers deployment
       href: plan-defender-for-servers-scale.md
     - name: Common questions
       href: faq-defender-for-servers.yml
-  - name: Protect cloud workloads
-    items:
-    - name: Agentless scanning
-      displayName: agentless, scanning, virtual, machines, freshness, snapshot, snapshots
-      href: concept-agentless-data-collection.md
-    - name: Security alerts and incidents
-      displayName: security, alerts, classification, incident, threat, detection, analytics, 
-      href: alerts-overview.md
-    - name: Reference list of alerts
-      displayName: alets, mitre
-      href: alerts-reference.md
-
 - name: How-to guides
   items:
   - name: Cloud security posture
@@ -368,6 +372,18 @@
     - name: Working with the Log Analytics agent
       displayName: log analytics, agent
       href: working-with-log-analytics-agent.md
+  - name: Defender for APIs
+    items: 
+    - name: About Defender for APIs
+      href: defender-for-apis-introduction.md
+    - name: Support and prerequisites
+      href: defender-for-apis-prepare.md
+    - name: Onboard Defender for APIs
+      href: defender-for-apis-deploy.md
+    - name: Investigate findings, recommendations, alerts
+      href: defender-for-apis-posture.md
+    - name: Manage Defender for APIs
+      href: defender-for-apis-manage.md
   - name: Defender for Servers
     displayName: hybrid, arc, Defender for Servers
     items:

articles/defender-for-cloud/alerts-reference.md

@@ -739,8 +739,26 @@ VM_ThreatIntelCommandLineSuspectDomain | A possible connection to malicious loca
 VM_ThreatIntelSuspectLogon | A logon from a malicious IP has been detected | High
 VM_VbScriptHttpObjectAllocation| VBScript HTTP object allocation detected | High
 
+## Alerts for Defender for APIs
+
+**Alert (alert type)** | **Description** | **MITRE tactics** | **Severity**
+--- | --- | --- | ---
+**(Preview) Suspicious population-level spike in API traffic to an API endpoint**<br/> (API_PopulationSpikeInAPITraffic) | A suspicious spike in API traffic was detected at one of the API endpoints. The detection system used historical traffic patterns to establish a baseline for routine API traffic volume between all IPs and the endpoint, with the baseline being specific to API traffic for each status code (such as 200 Success). The detection system flagged an unusual deviation from this baseline leading to the detection of suspicious activity. | Impact | Medium
+**(Preview) Suspicious spike in API traffic from a single IP address to an API endpoint**<br/> (API_SpikeInAPITraffic) | A suspicious spike in API traffic was detected from a client IP to the API endpoint. The detection system used historical traffic patterns to establish a baseline for routine API traffic volume to the endpoint coming from a specific IP to the endpoint. The detection system flagged an unusual deviation from this baseline leading to the detection of suspicious activity. | Impact | Medium
+**(Preview) Unusually large response payload transmitted between a single IP address and an API endpoint**<br/> (API_SpikeInPayload) | A suspicious spike in API response payload size was observed for traffic between a single IP and one of the API endpoints. Based on historical traffic patterns from the last 30 days, Defender for APIs learns a baseline that represents the typical API response payload size between a specific IP and API endpoint. The learned baseline is specific to API traffic for each status code (e.g., 200 Success). The alert was triggered because an API response payload size deviated significantly from the historical baseline. | Initial access | Medium
+**(Preview) Unusually large request body transmitted between a single IP address and an API endpoint**<br/> (API_SpikeInPayload) | A suspicious spike in API request body size was observed for traffic between a single IP and one of the API endpoints. Based on historical traffic patterns from the last 30 days, Defender for APIs learns a baseline that represents the typical API request body size between a specific IP and API endpoint. The learned baseline is specific to API traffic for each status code (e.g., 200 Success). The alert was triggered because an API request size deviated significantly from the historical baseline. | Initial access | Medium
+**(Preview) Suspicious spike in latency for traffic between a single IP address and an API endpoint**<br/> (API_SpikeInLatency) | A suspicious spike in latency was observed for traffic between a single IP and one of the API endpoints. Based on historical traffic patterns from the last 30 days, Defender for APIs learns a baseline that represents the routine API traffic latency between a specific IP and API endpoint. The learned baseline is specific to API traffic for each status code (e.g., 200 Success). The alert was triggered because an API call latency deviated significantly from the historical baseline. | Initial access | Medium
+**(Preview) API requests spray from a single IP address to an unusually large number of distinct API endpoints**<br/>(API_SprayInRequests) | A single IP was observed making API calls to an unusually large number of distinct endpoints. Based on historical traffic patterns from the last 30 days, Defenders for APIs learns a baseline that represents the typical number of distinct endpoints called by a single IP across 20-minute windows. The alert was triggered because a single IP's behavior deviated significantly from the historical baseline. | Discovery | Medium
+**(Preview) Parameter enumeration on an API endpoint**<br/> (API_ParameterEnumeration) | A single IP was observed enumerating parameters when accessing one of the API endpoints. Based on historical traffic patterns from the last 30 days, Defender for APIs learns a baseline that represents the typical number of distinct parameter values used by a single IP when accessing this endpoint across 20-minute windows. The alert was triggered because a single client IP recently accessed an endpoint using an unusually large number of distinct parameter values. | Initial access | Medium
+**(Preview) Distributed parameter enumeration on an API endpoint**<br/> (API_DistributedParameterEnumeration) | The aggregate user population (all IPs) was observed enumerating parameters when accessing one of the API endpoints. Based on historical traffic patterns from the last 30 days, Defender for APIs learns a baseline that represents the typical number of distinct parameter values used by the user population (all IPs) when accessing an endpoint across 20-minute windows. The alert was triggered because the user population recently accessed an endpoint using an unusually large number of distinct parameter values. | Initial access | Medium
+**(Preview) Parameter value(s) with anomalous data types in an API call**<br/> (API_UnseenParamType) | A single IP was observed accessing one of your API endpoints and using parameter values of a low probability data type (e.g., string, integer, etc.). Based on historical traffic patterns from the last 30 days, Defender for APIs learns the expected data types for each API parameter. The alert was triggered because an IP recently accessed an endpoint using a previously low probability data type as a parameter input. | Impact | Medium
+**(Preview) Previously unseen parameter used in an API call**<br/> (API_UnseenParam) | A single IP was observed accessing one of the API endpoints using a previously unseen or out-of-bounds parameter in the request. Based on historical traffic patterns from the last 30 days, Defender for APIs learns a set of expected parameters associated with calls to an endpoint. The alert was triggered because an IP recently accessed an endpoint using a previously unseen parameter. | Impact | Medium
+**(Preview) Access from a Tor exit node to an API endpoint**<br/> (API_AccessFromTorExitNode) | An IP address from the Tor network accessed one of your API endpoints. Tor is a network that allows people to access the Internet while keeping their real IP hidden. Though there are legitimate uses, it is frequently used by attackers to hide their identity when they target people's systems online. | Pre-attack | Medium
+**(Preview) API Endpoint access from suspicious IP**<br/> (API_AccessFromSuspiciousIP) | An IP address accessing one of your API endpoints was identified by Microsoft Threat Intelligence as having a high probability of being a threat. While observing malicious Internet traffic, this IP came up as involved in attacking other online targets.  | Pre-attack | High
+**(Preview) Suspicious User Agent detected**<br/> (API_AccessFromSuspiciousUserAgent) | 
+The user agent of a request accessing one of your API endpoints contained anomalous values indicative of an attempt at remote code execution. This does not mean that any of your API endpoints have been breached, but it does suggest that an attempted attack is underway. | Execution | Medium
+
 ## Next steps
-To learn more about Microsoft Defender for Cloud security alerts, see the following:
 
 - [Security alerts in Microsoft Defender for Cloud](alerts-overview.md)
 - [Manage and respond to security alerts in Microsoft Defender for Cloud](managing-and-responding-alerts.md)

articles/defender-for-cloud/concept-cloud-security-posture-management.md

@@ -17,7 +17,8 @@ Defender for Cloud continually assesses your resources, subscriptions and organi
 - **Foundational CSPM capabilities** - None 
 - **Defender Cloud Security Posture Management (CSPM)** - Agentless scanning requires the **Subscription Owner** to enable the plan. Anyone with a lower level of authorization can enable the Defender CSPM plan but the agentless scanner won't be enabled by default due to lack of permissions. Attack path analysis and security explorer won't be populated with vulnerabilities because the agentless scanner is disabled. 
 
-For commercial and national cloud coverage, see the [features supported in different Azure cloud environments](support-matrix-defender-for-cloud.md#features-supported-in-different-azure-cloud-environments).
+For commercial and national cloud coverage, review [features supported in different Azure cloud environments](support-matrix-cloud-environment.md).
+
 
 ## Defender CSPM plan options
 

articles/defender-for-cloud/defender-for-apis-deploy.md

@@ -0,0 +1,72 @@
+---
+title: Enable Defender for APIs in Defender for Cloud 
+description: Learn about deploying the Defender for APIs plan in Defender for Cloud
+author: elazark
+ms.author: elkrieger
+ms.service: defender-for-cloud
+ms.topic: conceptual
+ms.date: 03/23/2023
+---
+# Onboard Defender for APIs
+
+This article describes how to deploy the [Microsoft Defender for APIs](defender-for-apis-introduction.md) plan in the Microsoft Defender for Cloud portal. Defender for APIs is currently in preview.
+
+## Before you start
+
+- Review [Defender for APIs support, permissions, and requirements](defender-for-apis-introduction.md) before you begin deployment.
+- Make sure that Defender for Cloud is enabled in your Azure subscription. You enable Defender for APIs at the subscription level.
+- Ensure that APIs you want to secure are published in [Azure API management](/azure/api-management/api-management-key-concepts). Follow [these instructions](/azure/api-management/get-started-create-service-instance) to set up Azure API Management.
+
+> [!NOTE]
+> This article describes how to enable and onboard the Defender for APIs plan in the Defender for Cloud portal. Alternately, you can [enable Defender for APIs within an API Management instance](../api-management/protect-with-defender-for-apis.md) in the Azure portal.
+
+## Enable the plan
+
+1. Sign into the [portal](https://portal.azure.com/), and in Defender for Cloud, select **Environment settings**.
+1. Select the subscription that contains the managed APIs that you want to protect.
+1. In the **APIs** plan, select **On**. Then select **Save**.
+
+    :::image type="content" source="media/defender-for-apis-deploy/enable-plan.png" alt-text="Screenshot that shows how to turn on the Defender for APIs plan in the portal." lightbox="media/defender-for-apis-deploy/enable-plan.png":::
+
+> [!NOTE]
+> After enabling Defender for APIs, onboarded APIs take up to 50 minutes to appear in the **Recommendations** tab. Security insights are available in the **Workload protections** > **API security** dashboard within 40 minutes of onboarding.
+
+## Onboard APIs
+
+1. In the Defender for Cloud portal, select **Recommendations**.
+1. Search for *Defender for APIs*.
+1. Under **Enable enhanced security features**, select the security recommendation **Azure API Management APIs should be onboarded to Defender for APIs**.
+
+    :::image type="content" source="media/defender-for-apis-deploy/api-recommendations.png" alt-text="Screenshot that shows how to turn on the Defender for APIs plan from the recommendation." lightbox="media/defender-for-apis-deploy/api-recommendations.png":::
+
+
+1. In the recommendation page, you can review the recommendation severity, update interval, description, and remediation steps.
+1. Review the resources in scope for the recommendations:
+    - **Unhealthy resources**: Resources that aren't onboarded to Defender for APIs.
+    - **Healthy resources**: API resources that are onboarded to Defender for APIs.
+    - **Not applicable resources**: API resources that aren't applicable for protection.
+
+1. In **Unhealthy resources**, select the APIs that you want to protect with Defender for APIs.
+1. Select **Fix**. 
+
+    :::image type="content" source="media/defender-for-apis-deploy/api-recommendation-details.png" alt-text="Screenshot that shows the recommendation details for turning on the plan." lightbox="media/defender-for-apis-deploy/api-recommendation-details.png":::
+
+1. In **Fixing resources**, review the selected APIs, and select **Fix resources**.
+
+    :::image type="content" source="media/defender-for-apis-deploy/fix-resources.png" alt-text="Screenshot that shows how to fix unhealthy resources." lightbox="media/defender-for-apis-deploy/fix-resources.png":::
+
+1. Verify that remediation was successful.
+
+    :::image type="content" source="media/defender-for-apis-deploy/fix-resources-confirm.png" alt-text="Screenshot that confirms that remediation was successful." lightbox="media/defender-for-apis-deploy/fix-resources-confirm.png":::
+
+## Track onboarded API resources
+
+After onboarding the API resources, you can track their status in the Defender for Cloud portal > **Workload protections** > **API security**.
+
+:::image type="content" source="media/defender-for-apis-deploy/track-resources.png" alt-text="Screenshot that shows how to track onboarded API resources." lightbox="media/defender-for-apis-deploy/track-resources.png":::
+
+
+## Next steps
+
+[Review](defender-for-apis-posture.md) API threats and security posture.
+