diff --git a/cloud/integrations.mdx b/cloud/integrations.mdx index c8e22ef..b7e1218 100644 --- a/cloud/integrations.mdx +++ b/cloud/integrations.mdx @@ -784,11 +784,12 @@ By covering these services, ProjectDiscovery can map out a broad range of AWS as **AWS Integration Methods** -ProjectDiscovery supports three methods to connect to AWS, each suited for different use cases and security preferences: +ProjectDiscovery supports four methods to connect to AWS, each suited for different use cases and security preferences: 1. **Single AWS Account (Access Key & Secret)** – Direct credential-based authentication using an IAM User's Access Key ID and Secret Access Key to connect one AWS account. Choose this for quick setups or single-account monitoring. 2. **Multiple AWS Accounts (Assume Role)** – Use one set of credentials to assume roles in multiple accounts. This method is ideal for organizations with multiple AWS accounts (e.g. dev, prod, etc.). You provide one account's credentials and the common role name that exists in all target accounts. -3. **Cross-Account Role (Role ARN)** – Use a dedicated IAM role with an External ID for third-party access. This option lets you create a cross-account IAM role in your AWS account and grant ProjectDiscovery access via that role's Amazon Resource Name (ARN). This is the most secure integration method, as it follows AWS best practices for third-party account access. +3. **Cross-Account Role (Role ARN)** – Use a dedicated IAM role with an External ID for third-party access. This option lets you create a cross-account IAM role in your AWS account and grant ProjectDiscovery access via that role's Amazon Resource Name (ARN). +4. **Workload Identity Federation (Recommended)** – Connect without storing any AWS credentials. ProjectDiscovery's OIDC identity provider exchanges short-lived tokens with AWS for each scan. This is the most secure method — no long-lived keys to manage, rotate, or risk leaking. **Prerequisites** @@ -847,25 +848,117 @@ The most secure method using ProjectDiscovery's service account: - Give the integration a unique name - Select the AWS services you want to monitor -**Required Permissions** +#### 4. Workload Identity Federation (Recommended) -ProjectDiscovery needs read-only access to your AWS assets. The following AWS-managed policies are recommended: + +**Recommended.** Workload Identity Federation (WIF) eliminates long-lived AWS credentials entirely. ProjectDiscovery's OIDC identity provider exchanges short-lived tokens with AWS STS for each scan — no access keys are stored or need rotation. + -- EC2 - AmazonEC2ReadOnlyAccess -- Route53 - AmazonRoute53ReadOnlyAccess -- S3 - AmazonS3ReadOnlyAccess -- Lambda - AWSLambda_ReadOnlyAccess -- ELB - ElasticLoadBalancingReadOnly -- Cloudfront - CloudFrontReadOnlyAccess +**Benefits over credential-based methods:** +- No long-lived access keys to manage or rotate +- Tokens are short-lived and scoped per-scan +- Audit trail in AWS CloudTrail shows federated identity access +- Trust is scoped to your specific ProjectDiscovery workspace ID +- Follows AWS security best practices for third-party integrations -Alternatively, you can use this custom policy for minimal permissions: +**Prerequisites:** +- An AWS account with IAM admin access +- AWS CLI configured (`aws configure`) +- Your ProjectDiscovery **Team ID** (found in the platform sidebar) -```json + +**Finding your Team ID** — In the ProjectDiscovery platform, click on your team name in the left sidebar to reveal your Team ID. Use the copy button to copy it. + +Finding your Team ID in ProjectDiscovery + + +**Step 1: Create the OIDC Identity Provider** + +Register ProjectDiscovery as a trusted OIDC provider in your AWS account. + +```bash +aws iam create-open-id-connect-provider \ + --url "https://oidc.projectdiscovery.io" \ + --client-id-list "sts.amazonaws.com" +``` + +Save the OIDC Provider ARN from the output (e.g., `arn:aws:iam::123456789012:oidc-provider/oidc.projectdiscovery.io`). + +**Step 2: Create the WIF Role** + +Create an IAM role that ProjectDiscovery can assume via OIDC token exchange. The trust policy restricts access to your specific workspace. + +```bash +ACCOUNT_ID="YOUR_AWS_ACCOUNT_ID" +TEAM_ID="YOUR_PROJECTDISCOVERY_TEAM_ID" +OIDC_PROVIDER="oidc.projectdiscovery.io" + +cat > trust-policy.json < scanner-trust-policy.json < scanner-policy.json < +For **multiple accounts**, repeat [Step 3](#step-3-create-a-scanner-role) in each account you want to scan — the role name must be the same (`PDScannerRole`) across all accounts. Use [AWS CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html), Terraform, or similar infrastructure-as-code tools to deploy the scanner role across all accounts at once. + + +**Step 4: Grant the WIF Role AssumeRole Permission** + +Allow the WIF role to assume scanner roles. Use a wildcard to cover all accounts, or list specific account ARNs. + +```bash +cat > assume-scanner-policy.json < +For a single account, enter just that account's ID. For multiple accounts, list all account IDs — the scanner role must exist in each one. + + +--- + +**Optional: Organization Discovery** + +Instead of listing account IDs manually, you can have ProjectDiscovery automatically discover all accounts in your AWS Organization. + +**Step 6: Create an Organization Discovery Role** + + +This role must be created in the **management (root) account** of your AWS Organization — only the management account has permission to call `organizations:ListAccounts`. If the WIF role already lives in the management account, use the same account ID for both variables. + + +```bash +MANAGEMENT_ACCOUNT_ID="YOUR_MANAGEMENT_ACCOUNT_ID" # AWS Organization management account (use the same value as ACCOUNT_ID if WIF is in the management account) +ACCOUNT_ID="YOUR_AWS_ACCOUNT_ID" # Account where WIF role lives + +cat > org-discovery-trust-policy.json < org-policy.json < assume-org-discovery-policy.json < + **Permission Inheritance:** Organization-level IAM roles automatically cascade to all projects and folders within the organization. This means granting these 10 roles at the org level provides access across your entire GCP environment without per-project configuration. + Find your Organization ID: ```bash @@ -1081,7 +1324,7 @@ Grant the required roles based on your [enumeration scope](#enumeration-scope). Grant these roles at the **organization level** via the [Cloud Console IAM page](https://console.cloud.google.com/iam-admin/iam) (switch to organization scope) or using `gcloud`: ```bash - for role in roles/cloudasset.viewer roles/resourcemanager.organizationViewer roles/resourcemanager.folderViewer roles/browser; do + for role in roles/cloudasset.viewer roles/resourcemanager.organizationViewer roles/resourcemanager.folderViewer roles/browser roles/compute.viewer roles/dns.reader roles/storage.bucketViewer roles/run.viewer roles/cloudfunctions.viewer roles/container.clusterViewer; do gcloud organizations add-iam-policy-binding YOUR_ORG_ID \ --member="serviceAccount:projectdiscovery-scanner@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ --role="$role" @@ -1101,10 +1344,26 @@ Or via the [Cloud Console](https://console.cloud.google.com/iam-admin/serviceacc **Step 4: Configure in ProjectDiscovery** -In the ProjectDiscovery platform, create a new GCP integration and select **Service Account Key** as the authentication method. Upload the JSON key file and optionally provide your Organization ID for org-level enumeration. +In the ProjectDiscovery platform, create a new GCP integration and select **Service Account Key** as the authentication method. Upload the JSON key file and optionally provide your Organization ID for org-level enumeration and an **optional Project IDs** list to limit discovery to specific projects (leave it empty to scan all projects). Click **Verify** to confirm the connection, then **Create & Start Discovery**. + + + The **Project IDs** field is optional. If you provide it, **only those projects will be scanned** (not all projects under the organization). + + To list the projects your service account can access: + + ```bash + # Authenticate as the service account + gcloud auth activate-service-account --key-file=PATH_TO_SA_KEY.json + + # List all projects the service account can see + gcloud projects list --format="value(projectId)" + ``` + + + --- #### Workload Identity Federation @@ -1197,6 +1456,16 @@ Grant the required roles based on your [enumeration scope](#enumeration-scope). | Organization Viewer | `roles/resourcemanager.organizationViewer` | | Folder Viewer | `roles/resourcemanager.folderViewer` | | Browser | `roles/browser` | + | Compute Viewer | `roles/compute.viewer` | + | DNS Reader | `roles/dns.reader` | + | Storage Bucket Viewer | `roles/storage.bucketViewer` | + | Cloud Run Viewer | `roles/run.viewer` | + | Cloud Functions Viewer | `roles/cloudfunctions.viewer` | + | Kubernetes Engine Viewer | `roles/container.clusterViewer` | + + + **Permission Inheritance:** Organization-level IAM roles automatically cascade to all projects and folders within the organization. This means granting these 10 roles at the org level provides access across your entire GCP environment without per-project configuration. + Find your Organization ID: ```bash @@ -1206,7 +1475,7 @@ Grant the required roles based on your [enumeration scope](#enumeration-scope). Grant these roles at the **organization level** via the [Cloud Console IAM page](https://console.cloud.google.com/iam-admin/iam) (switch to organization scope) or using `gcloud`: ```bash - for role in roles/cloudasset.viewer roles/resourcemanager.organizationViewer roles/resourcemanager.folderViewer roles/browser; do + for role in roles/cloudasset.viewer roles/resourcemanager.organizationViewer roles/resourcemanager.folderViewer roles/browser roles/compute.viewer roles/dns.reader roles/storage.bucketViewer roles/run.viewer roles/cloudfunctions.viewer roles/container.clusterViewer; do gcloud organizations add-iam-policy-binding YOUR_ORG_ID \ --member="serviceAccount:pd-cloudlist-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ --role="$role" @@ -1269,9 +1538,24 @@ In the ProjectDiscovery platform, create a new GCP integration and select **Work | **Workload Identity Provider** | Full provider path from Step 6 | | **Service Account Email** | `pd-cloudlist-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com` | | **Organization ID** | Your numeric org ID — leave empty for project-level enumeration | +| **Project IDs (Optional)** | Limit discovery to specific projects | Click **Verify** to confirm the connection, then **Create & Start Discovery**. + + + The **Project IDs** field is optional. If you provide it, **only those projects will be scanned** (not all projects under the organization). + + To list the projects you can access: + + ```bash + gcloud projects list --format="value(projectId)" + ``` + + Run this as an org admin (or a principal with org-level visibility) if you need the full list of projects. + + + --- #### GCP Troubleshooting @@ -1701,4 +1985,4 @@ Supported Services: References: 1. https://docs.digitalocean.com/reference/api/create-personal-access-token/ -2. https://docs.digitalocean.com/reference/api/ \ No newline at end of file +2. https://docs.digitalocean.com/reference/api/