diff --git a/cloud/integrations.mdx b/cloud/integrations.mdx index 7e86520..c8e22ef 100644 --- a/cloud/integrations.mdx +++ b/cloud/integrations.mdx @@ -927,153 +927,416 @@ If all checks out, ProjectDiscovery is now actively monitoring your AWS environm Click here to open the GCP integration configuration page in the ProjectDiscovery Cloud platform -ProjectDiscovery's GCP integration allows the platform to automatically discover and monitor cloud assets across your GCP account. The integration supports **two discovery approaches** to accommodate different organizational structures and permission models. +ProjectDiscovery's GCP integration automatically discovers and monitors cloud assets across your GCP environment. The integration has two independent configuration choices — **enumeration scope** (what gets discovered) and **authentication method** (how you connect). + +**Supported GCP Services:** + +| Service | Description | +|:---|:---| +| [Cloud DNS](https://cloud.google.com/dns) | DNS zones and records | +| [Kubernetes Engine](https://cloud.google.com/kubernetes-engine) | GKE cluster endpoints | +| [Compute Engine](https://cloud.google.com/products/compute) | VM instances and public IPs | +| [Cloud Storage](https://cloud.google.com/storage) | Buckets | +| [Cloud Functions](https://cloud.google.com/functions) | Serverless function endpoints | +| [Cloud Run](https://cloud.google.com/run) | Container service URLs | + +#### Enumeration Scope + +Enumeration scope determines **what gets discovered**. This applies regardless of which authentication method you choose. + + + + Discovers resources across all GCP projects where the service account has been granted access. + + **When to use:** Scope discovery to one or more specific projects. + + **Configuration:** Leave the `Organization ID` field **empty**. + + + Discovers resources across **all projects under your organization** using the Cloud Asset Inventory API. + + **When to use:** Full visibility across your entire GCP organization. + + **Configuration:** Provide your numeric `Organization ID` (e.g. `123456789012`). + + + + +**Multi-Organization Support** — Monitor multiple GCP organizations by creating separate integrations with different organization IDs for consolidated asset discovery across all your environments. + + + + + Your Organization ID is a numeric value (e.g. `123456789012`). + + + + 1. Go to the [Google Cloud Console](https://console.cloud.google.com/) + 2. Click the **project selector** in the top navigation + 3. Click the **All** tab — your Organization ID is displayed next to your organization name + + Or go directly to [IAM & Admin > Settings](https://console.cloud.google.com/iam-admin/settings). + + + ```bash + gcloud organizations list + ``` + + + Navigate to [Organization Policies](https://console.cloud.google.com/iam-admin/orgpolicies) — your Organization ID is displayed in the URL and page header. + + + + + + Organization-level enumeration requires roles bound at the **organization level**. If you provide an Organization ID but only have project-level permissions, enumeration will fail with a **permission denied** error. See the required roles in the [Grant Permissions](#service-account-key) step of your chosen authentication method. + + + +--- + +#### Authentication Methods + +ProjectDiscovery supports two methods to authenticate with GCP. Both methods work with either enumeration scope. + + + + Traditional JSON key file. Simpler to set up, but requires managing long-lived credentials. + + + Short-lived OIDC tokens. No credentials to manage or rotate. Recommended for security. + + + +--- + +#### Service Account Key GCP Integration Screen -Supported GCP Services: - -- [Cloud DNS](https://cloud.google.com/dns) -- [Kubernetes Engine](https://cloud.google.com/kubernetes-engine) -- [Compute Engine](https://cloud.google.com/products/compute) -- [Bucket](https://cloud.google.com/storage) -- [Cloud Functions](https://cloud.google.com/functions) -- [Cloud Run](https://cloud.google.com/run) - -**GCP Integration Methods:** - -1. **Organization-Level Asset API** (Recommended for Enterprises) - - Uses Google Cloud's **Asset Inventory API** for comprehensive organization-wide discovery - - Discovers assets across entire GCP organization with a single configuration - - Requires organization-level permissions: `roles/cloudasset.viewer` and `roles/resourcemanager.viewer` - - Ideal for large organizations with multiple projects - -2. **Individual Service APIs** (Default) - - Uses individual GCP service APIs for project-specific discovery - - Faster execution with detailed resource metadata - - Requires project-level permissions for each service - - Ideal for focused, single-project discovery - -### Multi-Organization Support - -ProjectDiscovery supports monitoring **multiple GCP organizations simultaneously**. Simply configure multiple integrations with different organization IDs to get consolidated asset discovery across all your GCP environments (e.g., production, staging, development organizations). - -### Finding Your Organization ID - -1. **Via Google Cloud Console:** - - Go to the [Google Cloud Console](https://console.cloud.google.com/) - - In the top navigation, click on the **project selector** (next to "Google Cloud Platform") - - Click **All** tab to view all resources - - Look for your organization name - the **Organization ID** is displayed next to it - - Alternatively, go to [IAM & Admin > Settings](https://console.cloud.google.com/iam-admin/settings) - your Organization ID will be shown at the top - -2. **Via gcloud CLI:** - ```bash - # List all organizations you have access to - gcloud organizations list - - # Get current organization (if configured) - gcloud config get-value project - gcloud projects describe $(gcloud config get-value project) --format="value(parent.id)" - ``` - -3. **Via Organization Policies Page:** - - Navigate to [Organization Policies](https://console.cloud.google.com/iam-admin/orgpolicies) in the Console - - Your Organization ID will be displayed in the URL and page header - -### Checking Your Permissions - -Before setting up the integration, verify you have the necessary permissions: - -1. **For Organization-Level Integration:** - ```bash - # Check if you can list organization assets - gcloud organizations list - - # Check if you have the required roles - gcloud organizations get-iam-policy YOUR_ORG_ID --flatten="bindings[].members" --format="table(bindings.role)" --filter="bindings.members:user:YOUR_EMAIL" - ``` - -2. **For Project-Level Integration:** - ```bash - # Check project permissions - gcloud projects get-iam-policy YOUR_PROJECT_ID --flatten="bindings[].members" --format="table(bindings.role)" --filter="bindings.members:user:YOUR_EMAIL" - ``` - -## Step-by-Step Setup Instructions - -### Option 1: Organization-Level Asset API Setup - -1. **Verify Organization Access:** - - Ensure you have `roles/cloudasset.viewer` and `roles/resourcemanager.viewer` at the organization level - - You can check this in [IAM & Admin > IAM](https://console.cloud.google.com/iam-admin/iam) by switching to your organization scope - -2. **Create Service Account:** - - Navigate to any project within your organization - - Go to [IAM & Admin > Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) - - Click **Create Service Account** - - Name it something like `projectdiscovery-org-scanner` - - Click **Create and Continue** - -3. **Grant Organization-Level Permissions:** - - Go to [IAM & Admin > IAM](https://console.cloud.google.com/iam-admin/iam) - - Switch to your **Organization** scope (not project) - - Click **Grant Access** - - Enter your service account email: `projectdiscovery-org-scanner@YOUR_PROJECT_ID.iam.gserviceaccount.com` - - Assign these roles: - - `Cloud Asset Viewer` - - `Organization Viewer` - - Click **Save** - -4. **Generate Service Account Key:** - - Return to [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) - - Click on your service account - - Go to **Keys** tab - - Click **Add Key > Create New Key** - - Choose **JSON** format - - Download and securely store the key file - -### Option 2: Individual Service APIs Setup - -1. **Select Target Project:** - - Choose the specific project you want to monitor - - Note the **Project ID** (not the display name) - -2. **Create Service Account:** - - Navigate to [IAM & Admin > Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) in your target project - - Click **Create Service Account** - - Name it something like `projectdiscovery-scanner` - - Click **Create and Continue** - -3. **Grant Project-Level Permissions:** - - On the same page, assign these roles: - - `Compute Viewer` - - `DNS Reader` - - `Storage Object Viewer` - - `Cloud Run Viewer` - - `Cloud Functions Viewer` - - `Kubernetes Engine Viewer` - - `Browser` (for basic project access) - - Click **Continue** and then **Done** - -4. **Generate Service Account Key:** - - Click on your service account - - Go to **Keys** tab - - Click **Add Key > Create New Key** - - Choose **JSON** format - - Download and securely store the key file +Authenticate using a downloaded JSON key file from a GCP service account. This is the simpler setup but requires you to manage and rotate the key. +**Prerequisites:** +- A GCP project where you can create service accounts +- `Owner` or `IAM Admin` role on the project -References: +**Step 1: Create a Service Account** + +```bash +gcloud iam service-accounts create projectdiscovery-scanner \ + --project="YOUR_PROJECT_ID" \ + --display-name="ProjectDiscovery Scanner" +``` + +Or via the [Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts): click **Create Service Account**, name it `projectdiscovery-scanner`, and click **Create and Continue**. + +**Step 2: Grant Permissions** + +Grant the required roles based on your [enumeration scope](#enumeration-scope). + + + + + | Role | Role ID | + |---|---| + | 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.viewer` | + | Browser | `roles/browser` | + + Grant these roles via the [Cloud Console IAM page](https://console.cloud.google.com/iam-admin/iam) or using `gcloud`: + + ```bash + for role in roles/compute.viewer roles/dns.reader roles/storage.bucketViewer roles/run.viewer roles/cloudfunctions.viewer roles/container.viewer roles/browser; do + gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ + --member="serviceAccount:projectdiscovery-scanner@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="$role" + done + ``` + + Repeat for each project you want to enumerate. + + + + | Role | Role ID | + |---|---| + | Cloud Asset Viewer | `roles/cloudasset.viewer` | + | Organization Viewer | `roles/resourcemanager.organizationViewer` | + | Folder Viewer | `roles/resourcemanager.folderViewer` | + | Browser | `roles/browser` | + + Find your Organization ID: + ```bash + gcloud organizations list + ``` + + 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 + gcloud organizations add-iam-policy-binding YOUR_ORG_ID \ + --member="serviceAccount:projectdiscovery-scanner@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="$role" + done + ``` + + + +**Step 3: Generate Service Account Key** + +```bash +gcloud iam service-accounts keys create key.json \ + --iam-account="projectdiscovery-scanner@YOUR_PROJECT_ID.iam.gserviceaccount.com" +``` + +Or via the [Cloud Console](https://console.cloud.google.com/iam-admin/serviceaccounts): click on your service account, go to **Keys** tab, click **Add Key > Create New Key**, choose **JSON** format, and download the key file. + +**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. + +Click **Verify** to confirm the connection, then **Create & Start Discovery**. + +--- + +#### Workload Identity Federation + + +**Recommended.** Workload Identity Federation (WIF) eliminates long-lived service account keys. ProjectDiscovery's OIDC identity provider exchanges short-lived tokens (1 hour) with GCP for each enumeration — no credentials are stored or need rotation. + + +GCP Workload Identity Federation Integration Screen + +**Benefits over service account keys:** +- No long-lived credentials to manage or rotate +- Tokens are short-lived (1 hour) and scoped per-enumeration +- Audit trail in GCP shows federated identity access +- Follows GCP security best practices + +**Prerequisites:** +- A GCP project with billing enabled +- `Owner` or `IAM Admin` role on the project (to create WIF resources) +- The Cloud IAM API enabled on your project + +**Step 1: Create a Workload Identity Pool** + +```bash +gcloud iam workload-identity-pools create projectdiscovery-pool \ + --project="YOUR_PROJECT_ID" \ + --location="global" \ + --display-name="ProjectDiscovery Pool" +``` + +**Step 2: Add ProjectDiscovery as an OIDC Provider** + +```bash +gcloud iam workload-identity-pools providers create-oidc projectdiscovery-oidc \ + --project="YOUR_PROJECT_ID" \ + --location="global" \ + --workload-identity-pool="projectdiscovery-pool" \ + --display-name="ProjectDiscovery OIDC" \ + --issuer-uri="https://oidc.projectdiscovery.io" \ + --attribute-mapping="google.subject=assertion.sub,attribute.sub=assertion.sub" +``` + +**Step 3: Create a Service Account** + +```bash +gcloud iam service-accounts create pd-cloudlist-reader \ + --project="YOUR_PROJECT_ID" \ + --display-name="ProjectDiscovery Cloud Reader" +``` + +**Step 4: Grant Permissions** + +Grant the required roles based on your [enumeration scope](#enumeration-scope). + + + + + | Role | Role ID | + |---|---| + | 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.viewer` | + | Browser | `roles/browser` | + + Grant these roles via the [Cloud Console IAM page](https://console.cloud.google.com/iam-admin/iam) or using `gcloud`: + + ```bash + for role in roles/compute.viewer roles/dns.reader roles/storage.bucketViewer roles/run.viewer roles/cloudfunctions.viewer roles/container.viewer roles/browser; do + gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \ + --member="serviceAccount:pd-cloudlist-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="$role" + done + ``` + + Repeat for each project you want to enumerate. + + + + | Role | Role ID | + |---|---| + | Cloud Asset Viewer | `roles/cloudasset.viewer` | + | Organization Viewer | `roles/resourcemanager.organizationViewer` | + | Folder Viewer | `roles/resourcemanager.folderViewer` | + | Browser | `roles/browser` | + + Find your Organization ID: + ```bash + gcloud organizations list + ``` + + 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 + gcloud organizations add-iam-policy-binding YOUR_ORG_ID \ + --member="serviceAccount:pd-cloudlist-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com" \ + --role="$role" + done + ``` + + + +**Step 5: Allow WIF to Impersonate the Service Account** + +Bind the service account to your ProjectDiscovery workspace using an attribute condition on the `sub` claim. Replace `YOUR_TEAM_ID` with your Team ID from the ProjectDiscovery platform. + +```bash +gcloud iam service-accounts add-iam-policy-binding \ + pd-cloudlist-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com \ + --project="YOUR_PROJECT_ID" \ + --role="roles/iam.workloadIdentityUser" \ + --member="principalSet://iam.googleapis.com/projects/YOUR_PROJECT_NUMBER/locations/global/workloadIdentityPools/projectdiscovery-pool/attribute.sub/YOUR_TEAM_ID" +``` + + +**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 + + + +`YOUR_PROJECT_NUMBER` is the numeric project number, not the project ID. Find it with: +```bash +gcloud projects describe YOUR_PROJECT_ID --format='value(projectNumber)' +``` + + +**Step 6: Get the Provider Resource Path** + +```bash +gcloud iam workload-identity-pools providers describe projectdiscovery-oidc \ + --project="YOUR_PROJECT_ID" \ + --location="global" \ + --workload-identity-pool="projectdiscovery-pool" \ + --format='value(name)' +``` + +This returns a path like: +``` +projects/123456789012/locations/global/workloadIdentityPools/projectdiscovery-pool/providers/projectdiscovery-oidc +``` + +**Step 7: Configure in ProjectDiscovery** + +In the ProjectDiscovery platform, create a new GCP integration and select **Workload Identity Federation** as the authentication method. Provide: + +| Field | Value | +|---|---| +| **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 | + +Click **Verify** to confirm the connection, then **Create & Start Discovery**. + +--- + +#### GCP Troubleshooting + +**"Google Cloud denied access" with Organization ID set** + +The service account does not have permissions at the org level. Ensure all four org-level roles are granted: `roles/cloudasset.viewer`, `roles/resourcemanager.organizationViewer`, `roles/resourcemanager.folderViewer`, and `roles/browser`. See the Organization-Level tab in the [Grant Permissions](#service-account-key) step for details. + +**"GCP token exchange failed"** (WIF only) +- Verify the Workload Identity Provider path is correct (check for typos) +- Ensure the OIDC provider issuer URI is `https://oidc.projectdiscovery.io` +- Check the attribute mapping includes `google.subject=assertion.sub,attribute.sub=assertion.sub` in the OIDC provider configuration + +**"GCP service account impersonation failed"** (WIF only) +- Verify `roles/iam.workloadIdentityUser` binding exists on the service account +- Ensure the `attribute.sub` value in the member principal matches your Team ID +- Ensure you used the correct project **number** (not project ID) in the member principal +- Check that the service account email is correct + +**"Workload Identity Pool configuration error"** (WIF only) + +The provider path must follow this exact format: +``` +projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID +``` + +**Verifying permissions** + +```bash +# Check organization-level roles +gcloud organizations get-iam-policy YOUR_ORG_ID \ + --flatten="bindings[].members" \ + --format="table(bindings.role)" \ + --filter="bindings.members:serviceAccount:YOUR_SA_EMAIL" + +# Check project-level roles +gcloud projects get-iam-policy YOUR_PROJECT_ID \ + --flatten="bindings[].members" \ + --format="table(bindings.role)" \ + --filter="bindings.members:serviceAccount:YOUR_SA_EMAIL" +``` + +**Verifying WIF impersonation binding** + +```bash +gcloud iam service-accounts get-iam-policy YOUR_SA_EMAIL \ + --format="yaml" \ + --filter="bindings.role:roles/iam.workloadIdentityUser" +``` + +Confirm the output contains a member with your Team ID in the `attribute.sub` path. + + +**Security Notes:** +- ProjectDiscovery only requires **read-only** access to enumerate your cloud assets +- With WIF, tokens are short-lived (1 hour max) and automatically expire after each enumeration — no credentials are stored +- You can revoke access at any time by removing IAM bindings or (for WIF) deleting the Workload Identity Pool + + +**References:** 1. https://cloud.google.com/iam/docs/service-account-overview 2. https://cloud.google.com/iam/docs/keys-create-delete#creating 3. https://cloud.google.com/asset-inventory/docs/overview +4. https://cloud.google.com/iam/docs/workload-identity-federation ### Azure diff --git a/images/GCP_Integration_wip_screen.png b/images/GCP_Integration_wip_screen.png new file mode 100644 index 0000000..2a33c32 Binary files /dev/null and b/images/GCP_Integration_wip_screen.png differ diff --git a/images/pdcp-teamid.png b/images/pdcp-teamid.png new file mode 100644 index 0000000..37ab8c4 Binary files /dev/null and b/images/pdcp-teamid.png differ