# Resource Discovery

Resource discovery is a tool that automatically scans your cloud environments and identifies infrastructure resources that can be managed by StrongDM. You can run [nodes](https://docs.strongdm.com/admin/networking/gateways-and-relays) in your public cloud, grant them the appropriate scanning permissions, and then configure connectors. This updates a list in StrongDM of resources within that cloud and provides a way to onboard supported resource types easily, adding them to your StrongDM organization as managed resources. Resource discovery helps your organization to understand what exists across large or multi-account environments and onboard resources into StrongDM safely and consistently.

Discovery supports AWS, Azure, and GCP cloud providers.

* The AWS resources supported for discovery at this time are EC2, RDS, and EKS.
* The GCP resources supported for discovery at this time are GCE, Cloud SQL, and GKE.
* The Azure resources supported for discovery at this time are Virtual Machines, SQL servers, and AKS instances.

## How Discovery Works

Discovery runs from StrongDM nodes and uses cloud provider APIs to list infrastructure resources such as compute instances, databases, and container platforms.

The following is a high-level summary of how discovery works:

1. You configure a discovery connector for a cloud provider.
2. The connector authenticates to the cloud using one of the following options:
   * OIDC workload identity federation (recommended), or
   * Cloud credentials (IAM roles, service principals, or service accounts)
3. StrongDM periodically scans the configured scope (that is, accounts, subscriptions, or projects).
4. Discovered resources appear in the StrongDM Admin UI, where you can review and onboard them.

## Authentication Models for Discovery

### OIDC-Based Discovery

StrongDM uses workload identity federation to authenticate a StrongDM node (relay, gateway, or proxy worker) as part of the StrongDM workload, enabling that node to scan your cloud using cloud provider APIs.

OIDC discovery is the recommended authentication model, as it eliminates long-lived cloud credentials and enables scanning across multiple environments. With OIDC discovery, there are no static API keys or secrets to manage; you can still enforce least-privilege permissions; and there is support for scanning multiple AWS accounts, Azure subscriptions, and GCP projects.

### Credential-Based Discovery

You may also configure discovery using traditional cloud credentials:

* AWS IAM roles
* Azure service principals
* GCP service accounts

Credential-based discovery is still supported but does not provide the same flexibility or hierarchy support as OIDC-based discovery. In this model, you must ensure that the nodes you choose to scan from have the proper credentials and cloud permissions, and that you maintain their relationship to your StrongDM connector as you cycle nodes.

## Scanning Details by Cloud Provider

This section generally describes how scanning works for each supported cloud provider and what StrongDM admins need to configure.

### AWS: Multi-Account Scanning

With OIDC, a single AWS discovery connector can scan multiple AWS accounts. As a prerequisite, you configure an IAM trust policy in each target account that establishes AWS trust in StrongDM as an OIDC identity provider. This policy allows AWS to accept a StrongDM-issued OIDC JWT and permit the bearer to assume a specified IAM role.

During each scan, StrongDM issues an OIDC token and sends the scan request to the node. The node then uses the token to assume the configured IAM role in each target account and perform the scan.

You configure a list of AWS Account IDs to scan, along with an IAM role that trusts StrongDM’s OIDC provider.

### Azure: Subscription-Level Scanning

Azure discovery supports scanning across multiple subscriptions. StrongDM issues OIDC tokens compatible with Entra ID, and tokens are exchanged for access scoped to specific subscriptions.

You configure one or more Azure Subscription IDs, an Entra ID app registration configured for workload identity federation, and reader-level access (at minimum).

### GCP: Project-Level Scanning

GCP discovery supports scanning across multiple projects using workload identity federation. StrongDM issues OIDC tokens, and GCP Workload Identity Pools trust StrongDM’s OIDC issuer.

You configure one or more GCP Project IDs, a Workload Identity Pool and Provider, and IAM bindings that grant viewer permissions.

## How to Set up Discovery

There are a couple approaches for setting up discovery: Terraform and the StrongDM Admin UI. For most organizations, using Terraform is the easiest way. Both ways are described in this section.

### Use Terraform to Configure Discovery

Terraform is the recommended way to configure OIDC-based discovery, especially for multi-account, multi-subscription, or multi-project environments.

For complete Terraform configuration instructions, please see the StrongDM Terraform provider discovery setup examples and modules on GitHub:

* [StrongDM Discovery - AWS Terraform Configuration](https://github.com/strongdm/terraform-provider-sdm-examples/tree/master/10_discovery_setup/aws)
* [StrongDM Discovery - Azure Terraform Configuration](https://github.com/strongdm/terraform-provider-sdm-examples/tree/master/10_discovery_setup/azure)
* [StrongDM Discovery - GCP Terraform Configuration](https://github.com/strongdm/terraform-provider-sdm-examples/tree/master/10_discovery_setup/gcp)

The Terraform examples and modules help you to automate the following:

* Cloud-side trust configuration (workload identity federation)
* Least-privilege permissions for discovery scans
* StrongDM discovery connector creation
* Hierarchy scope configuration:
  * AWS: Account IDs
  * Azure: Subscription IDs
  * GCP: Project IDs

{% hint style="info" %}
If you prefer to configure connectors in the Admin UI, you can still use Terraform just for the cloud-side trust and permission setup, and then enter the hierarchy scope in the connector form.
{% endhint %}

### Use the Admin UI to Configure Discovery

When using the Admin UI, setting up discovery consists of three main steps:

1. Configure cloud authentication (OIDC recommended).
2. Deploy StrongDM nodes.
3. Create a discovery connector.

The flow is the same across AWS, Azure, and GCP. The main difference is how the connector authenticates to the cloud.

#### 1. Configure Cloud Authentication

Discovery requires read-only access to your cloud environment so StrongDM can list supported resources.

StrongDM supports two authentication models: OIDC-based discovery (recommended) and credential-based discovery.

**OIDC-based discovery**

StrongDM acts as an OIDC identity token issuer and uses workload identity federation to authenticate discovery scans. OIDC-based discovery improves reliability by removing static credentials and reducing configuration drift between StrongDM and cloud IAM.

OIDC discovery:

* Eliminates long-lived credentials
* Supports least-privilege permissions
* Enables scanning across multiple environments

With OIDC, a single connector can scan:

* Multiple AWS accounts
* Multiple Azure subscriptions
* Multiple GCP projects

When using OIDC:

* Public OIDC discovery and JWKS endpoints are exposed per organization.
* Signing keys are rotated automatically.

You must configure your cloud provider to trust StrongDM’s OIDC issuer and grant read-only permissions in each target account, subscription, or project. Cloud-specific federation setup steps are available through [StrongDM’s Terraform provider discovery setup modules and examples](https://github.com/strongdm/terraform-provider-sdm-examples/tree/master/10_discovery_setup), which make the discovery setup process much easier.

**Credential-based discovery**

You may also configure discovery using traditional cloud credentials:

* AWS IAM roles
* Azure service principals
* GCP service accounts

Credential-based discovery is still supported but does not provide hierarchical scanning or the operational simplicity of OIDC.

### 2. Set up Nodes

In this step, choose or create the StrongDM node(s) you wish to use to scan your cloud infrastructure. Nodes are gateways, relays, or proxy workers.

Node setup requirements are the same whether you use OIDC-based or credential-based discovery. Nodes must:

* Have network access to cloud provider APIs.
* Run StrongDM CLI version 50.15.0 or greater.
* Have appropriate read access to your cloud infrastructure.

{% hint style="info" %}
If you use OIDC, you set up such access when you set up the OIDC trust relationship. This is one of the reasons why OIDC is the recommended approach.
{% endhint %}

Although you can run nodes outside your cloud, we recommend running nodes inside the cloud organization you wish to scan. Note that nodes only scan and report resources visible to them; if you limit a node's read permissions in your cloud, it will scan only the resources that you allow read access to.

Select one of the following tabs to view node setup instructions for AWS, GCP, or Azure.

{% tabs %}
{% tab title="AWS" %}
In AWS, there are a variety of ways to host StrongDM nodes (gateways, relays, or workers) that can conduct scans.

In AWS, nodes are commonly hosted on EC2 instances. As such, the following configuration example assumes that you are using an EC2 instance within the same organization.

The permissions listed are those useful to scan for all resource types supported currently by StrongDM (EC2, RDS, and EKS clusters).

1. Log in to the AWS Management Console for your organization.
2. Create an IAM role and add these polices:
   * The managed policy `AmazonEC2ReadOnly`
   * The managed policy `AmazonRDSReadOnly`
   * A custom policy that you create to provide [read-only access to list EKS clusters](https://docs.aws.amazon.com/eks/latest/userguide/security-iam-id-based-policy-examples.html#policy-example2) because there is not a managed policy for this
3. Ensure that your new role is attached to your EC2 instance(s) that you run the chosen node(s) on.
4. Continue [node](https://docs.strongdm.com/admin/networking/gateways-and-relays) setup as necessary.
   {% endtab %}

{% tab title="GCP" %}
In GCP, there are a variety of ways to host StrongDM nodes (gateways, relays, or workers) that can conduct scans.

The following configuration example assumes that you are using a GCE instance within the same organization.

The permissions listed are those useful to scan for all resource types supported currently by StrongDM (GCE, Cloud SQL, and GKE clusters).

1. Log in to the Google Cloud console for your organization.
2. Identify or create a Compute Engine (GCE) to run your node. Ensure that this instance has the cloud-platform OAuth Scope. If you are creating a new GCE instance, specify `--scopes=https://www.googleapis.com/auth/cloud-platform` in the `gcloud compute instances create ...` command.
3. Create a custom IAM role with the following permissions:
   * `resourcemanager.projects.list`
   * `compute.zones.list`
   * `compute.instances.list`
   * `cloudsql.instances.list`
   * `container.clusters.list`
4. Assign the custom role to the service account of the Cloud Compute Engine where the StrongDM node is running.
5. Continue [node](https://docs.strongdm.com/admin/networking/gateways-and-relays) setup as necessary.

As an alternative to the custom role, you can instead assign the GCE instance the following built-in roles:

* `roles/resourcemanager.projectBrowser`
* `roles/cloudsql.viewer`
* `roles/container.clusterViewer`
* `roles/compute.viewer`
  {% endtab %}

{% tab title="Azure" %}
In Azure, there are a variety of ways to host StrongDM nodes (gateways, relays, or workers) that can conduct scans.

The following configuration example assumes that you are using an Azure VM within the same organization. The permissions listed are those useful to scan for all resource types supported currently by StrongDM (VMs, SQL servers, and AKS clusters).

If you are using Azure, hosting your scanning node(s) in Azure VMs within the same organization, and scanning for VMs, SQL servers, and AKS clusters, the following steps are required:

1. Log in to the Azure portal for your organization.
2. Navigate to the VM hosting your node.
3. Select **Security** > **Identity**.
4. Click **Azure role assignments**.
5. Add the `Reader` role for the Subscription scope. Alternatively, you can create and use a custom role with the following permissions:
   1. `Microsoft.ContainerService/managedClusters/read`
   2. `Microsoft.Compute/virtualMachines/read`
   3. `Microsoft.Sql/servers/read`
   4. `Microsoft.Network/networkInterfaces/read`
6. Lastly, set the following environment variables on your node:
   1. `AZURE_TENANT_ID`
   2. `AZURE_SUBSCRIPTION_ID`\
      These values can be acquired in the Azure Portal (see the [Microsoft documentation](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id) for more details on these values), and should be set in the `sdm-proxy` file where you set StrongDM environment variables on your node. For gateways and relays, this is usually `/etc/sysconfig/sdm-proxy` , and for proxy cluster workers, it is usually `/etc/sysconfig/sdm-proxy` .
      {% endtab %}
      {% endtabs %}

### 3. Create a Connector

Connectors are a collection of selected nodes and configuration for how they can discover information about your resources, when, and from where. You can create connectors by using Terraform as part of your discovery setup or manually through the StrongDM Admin UI.

A discovery connector defines the following:

* Cloud provider
* Authentication method (OIDC or credential-based)
* The hierarchy scope (accounts, subscriptions, or projects)
* Nodes that perform scans
* Scan frequency and filters

Each connector can scan multiple child environments, eliminating the need to create one connector per account or project.

With OIDC, connector forms include the following fields. The connector form dynamically adjusts based on the selected cloud and authentication method.

* AWS: Account IDs
* Azure: Subscription IDs
* GCP: Project IDs

You can get started with connectors by following these steps.

1. In the StrongDM Admin UI, go to [**Settings** > **Connectors**](https://app.strongdm.com/app/settings/connectors). This page displays a list of current connectors.
2. Click **Add Connector**.
3. Select a **Cloud**.
4. Enter a **Name** for the connector. Ideally, the name indicates which cloud account or environment you wish to discover resources in.
5. Optionally add a **Description** to provide further context. 
6. Select a value for **Crawl interval** to alter the frequency at which the connector crawls your cloud infrastructure and updates your discovered resources list.
7. For **Node to cloud identity configuration**, select one of the following:
   1. **OIDC (best for most organizations):** If selected, also enter the appropriate values for the **Assumed identity settings** that are shown.
      1. For AWS, enter the ID(s) of the AWS accounts to be scanned and the role name.
      2. For Azure, enter the ID(s) of the Azure subscriptions to be scanned, the Client ID, and the Tenant ID.
      3. For GCP, enter the ID(s) of the GCP projects to be scanned, the workload project number, workload project ID, workload provider ID, and workload pool ID. 
   2. **Manual auth configuration:** If selected, no additional settings are shown.
8. Under **Node Selection**, select one or more of your nodes from the **Node(s)** menu.\
   \
   If you are *not* using OIDC, these should be the nodes that you configured to have read access to your cloud infrastructure in step 1.\
   \
   Selecting them here tags them with a **Connector Tag** (`sdm__connector_id`). The value of this tag is what is used to determine which nodes run a given scan.

{% hint style="info" %}
If you cycle the nodes you want to use for scanning, make sure to add the connector tag to the newly created node so it is relinked to the connector after your cycle.
{% endhint %}

9. Under **Advanced settings**, you can optionally filter your scan results with **Resource Matching** options:
   1. You can include or exclude tags on the resource (cloud provider tags, not StrongDM tags) in order to include only resources with particular tags, or to exclude resources with particular tags.
   2. You can choose a **Resource Type** to limit the scan results to only resources of the selected type.

Now the connector is set up. It specifies which nodes to use to run the scan and against which type of cloud. The nodes have been configured with the access they need. Your scans run automatically at whatever period of time you set your **Crawl interval** to be.

This is the primary way to update your discovered resources list, but you can run a manual scan if you don't want to wait. To run a manual scan, select **Actions** > **Run Scan**. A green checkmark briefly appears in the bottom right corner of the Admin UI if the scan started successfully. A red `<CONNECTOR_NAME> failed` message appears if it fails to start.

The connector shows a failure message if you start a manual scan while a scan is already running. You can view a connector's scan history by clicking on the connector name to display the connector details page.

## How to View Discovered Resources

Discovered resources are the infrastructure within your cloud provider that are discovered by scans that you run with connectors.

After scans are complete, you can view discovered resources in the Admin UI in **Resources > Discovered Resources**. They are shown in a list with their name, tags, and status:

* **Name**: External name of this discovered resource in the cloud provider (not a StrongDM resource name)
* **Cloud**: Cloud provider that this resource was discovered in
* **Kind**: Type of cloud resource discovered
* **Tags**: Tags associated with this discovered resource in the cloud provider. You may overwrite these tags when creating a managed resource from the discovered resource
* **Status**:
  * **Managed** (onboarded as one or more resource(s) in StrongDM)
  * **Unmanaged** (discovered but not yet onboarded into StrongDM)
* **First Seen**: Date/time stamp of when this resource was first seen in a scan
* **Last Seen**: Date/time stamp of when this resource was last seen in a scan

{% hint style="info" %}
Currently, the discovery feature does not automatically reconcile discovered resources with existing managed resources in StrongDM. Instead, StrongDM moves discovered resources from the **Unmanaged** to the **Managed** status when you use the onboarding feature to manage a discovered resource manually. For instance, consider the following example scenarios.

**Scenario 1: Existing managed resource**

You discover Virtual Machine A from the cloud and use the **Manage** button to onboard it as a managed resource. Virtual Machine A changes status to **Managed**. On subsequent scans of your cloud, Virtual Machine A continues to be seen/discovered, and it continues to show as a managed resource.

**Scenario 2: No existing managed resource**

You were already using Virtual Machine B as a resource in StrongDM before using the discovery feature. When you scan your cloud, Virtual Machine B shows in the scan results in the **Unmanaged** status until you use the **Manage** action to onboard it as a new managed resource. The discovery process does not reconcile discovered resources with existing StrongDM resources unless [tag based linking](#automatically-link-managed-and-newly-discovered-resources) is performed.

**Scenario 3: Deleted and rediscovered managed resource**

You discover Virtual Machine C from the cloud, use the **Manage** button to onboard it as a managed resource, and then later delete both the managed resource in StrongDM and the Virtual Machine in your cloud provider. If you then recreate the Virtual Machine and a new StrongDM scan picks it up, it shows up as a discovered, unmanaged resource, with no connection to the previously managed resource.
{% endhint %}

### Onboard a discovered resource

When viewing the discovered resource details, you can onboard the discovered resource to make it a managed resource in StrongDM.

1. Select **Manage Resource** to begin onboarding the discovered resource.
2. The resulting modal has the **Display Name** of the resource in StrongDM prefilled to be the name of the discovered resource. You are prompted to select a **Resource Type**.

{% hint style="info" %}
Although the type of resource has already been detected in the scan, choosing a StrongDM resource type is still necessary. This is because for many kinds of infrastructure there are multiple StrongDM resource types available, each reflecting a different kind of connection or authentication.
{% endhint %}

3. Once you select a resource type, you are brought to the view to fill in the resource’s configuration. Some fields are auto-filled based on discovered information about the resource. Fill in the rest of the fields appropriately. See the StrongDM resource configuration guides for more details on those fields.
   1. AWS
      1. RDS ([RDS PostgreSQL](https://docs.strongdm.com/admin/resources/datasources/rds-postgresql-iam))
      2. EKS ([EKS](https://docs.strongdm.com/admin/resources/clusters/eks) or [EKS (Instance Profile)](https://docs.strongdm.com/admin/resources/clusters/eks-instance-profile))
      3. EC2 ([various SSH server resource types](https://docs.strongdm.com/admin/resources/servers))
   2. GCP
      1. Cloud SQL ([various SQL datasource resource types](https://docs.strongdm.com/admin/resources/datasources))
      2. GKE ([GKE](https://docs.strongdm.com/admin/resources/clusters/gke))
      3. GCE ([various SSH server resource types](https://docs.strongdm.com/admin/resources/servers))
   3. Azure
      1. Azure SQL ([Microsoft SQL server (Entra ID)](https://docs.strongdm.com/admin/resources/datasources/microsoft-sql-server-azure-ad))
      2. AKS ([AKS](https://docs.strongdm.com/admin/resources/clusters/aks))
      3. Azure VM ([various SSH server resource types](https://docs.strongdm.com/admin/resources/servers))
4. Once the resource configuration is complete, select **Save**.

Once the resource is created, you are able to view it in **Resources** > **Managed Resources**.

In the **Discovered Resources** detail view for this item, under the **Resources** tab, there is a link to the managed resource within StrongDM.

### Links between discovered and managed resources

When an admin creates a managed resource from a discovered resource, a tag is added to the managed resource in the format `sdm__cloud_id=<PROVIDER_IDENTITY>`. The `PROVIDER_IDENTITY` is dependent upon the cloud provider.<br>

* For Azure resources, this is the Resource ID.
* For GCP resources, this is the Resource ID.
* This feature is not yet offered for AWS resources, but is coming soon.

When StrongDM discovers a resource, it checks your existing managed resources for one that has a matching ID tag formatted as above, and if one exists, links them together so that you can see that the resource has already been onboarded as one or more StrongDM resources.

### Automatically link managed and discovered resources

StrongDM allows you to automatically link managed and discovered resources. Many organizations use StrongDM to secure cloud resources and want to know if any cloud resources are created outside of those resources managed and protected in StrongDM. Setting up automatic linking allows you to know when an unprotected resource is added within the scope of your discovery scans. You can set up automatic linking by adding a tag to the managed resource in StrongDM that contains the resource's ID from the cloud provider. This ensures that the managed resource is matched to the discovered resource during a scan, and leaves you with a more accurate list of resources that are not yet secured through StrongDM.

To set up automatic linking, follow these steps:

1. For each cloud resource that you already manage in StrongDM, get the resource ID from your cloud provider and tag the resource in StrongDM. The tag should be in the format `sdm__cloud_id=<PROVIDER_IDENTITY>` with `PROVIDER_IDENTITY` replaced by the resource ID from your cloud provider.
   1. For Azure resources, this is the Resource ID.
   2. For GCP resources, this is the Resource ID.
   3. This feature is not yet offered for AWS resources, but is coming soon.
2. Run a scan when you set up a connector to your cloud provider in **Settings** > **Connectors**. When StrongDM scans your cloud, it matches an incoming discovered resource to any managed resource(s) that have a `sdm__cloud_id=<PROVIDER_IDENTITY>` tag whose `<PROVIDER_IDENTITY>` matches the ID of the discovered resource.
3. In the scan results, the automatically linked resources show up as managed. Due to the tag linking, the list of unmanaged resources now excludes all of the resources that are discovered but already existed in StrongDM, leaving you with a clear picture of what resources are currently not managed through StrongDM.

{% hint style="info" %}
If you manually remove the link between a discovered and managed resource, StrongDM removes the tag on the managed resource so that it isn't linked in future scans
{% endhint %}

### Discovered resource considerations

* Items in the **Discovered Resources** view can’t be deleted through StrongDM, as they are simply the latest information gathered by scans of your infrastructure.
* Discovered resource data in StrongDM is not authoritative. StrongDM is not the source of truth for what exists in your infrastructure, and the information that is captured is only regarding the resources that were running and that you’ve given your StrongDM nodes permission to see.
* One discovered resource can be onboarded into many StrongDM managed resources, preserving the ability to make many resources with different credentials and permissions to provide varying levels of access to the same cloud resource.
* Currently, there is no way to automatically delete a resource in StrongDM when the linked “discovered resource” is decommissioned in the cloud and no longer visible from scans.
* The link between a scanned (discovered) resource and an onboarded resource indicates only the *origin* of the latter. The link is not maintained as changes to the underlying cloud resource occur. If you, for example, change the hostname of a cloud resource to something different than what was discovered originally, that item in the **Discovered Resources** view remains linked to the StrongDM resource. This also means that resources that are taken offline, removed from the list, and then added again in later scans are added as new, unlinked discovered resources (unless the managed resources are tagged as indicated in the section on [automatic linking with tags](#automatically-link-managed-and-newly-discovered-resources)).
* If you manually unlink a managed resource from the discovered resource that it was attached to, the ID tag on the managed resource is removed.

## Logs

The following logs are recorded in StrongDM regarding resource discovery:

* Admin activities are logged when connectors are created, updated, or deleted.
* Admin activities are logged when a discovered resource is onboarded to a StrongDM resource.
* Node logs record events with the results of scans that they run against your cloud infrastructure. Currently, there is no Admin UI activity for scan results.

## Troubleshooting

1. Find the node(s) in the Admin UI at **Networking** > **Gateways** or **Networking** > **Relays** and check if it is healthy.
2. Make sure that your IAM role is attached to your node.
3. Check that the IAM role has the required read permissions for the resource types you intend to scan for.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.strongdm.com/admin/resources/discovery.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.