diff --git a/cloud/integrations.mdx b/cloud/integrations.mdx index c8576b3..928a6ac 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 < +**Scanner role is still required.** Organization Discovery only automates finding account IDs — the scanner role (`PDScannerRole` from [Step 3](#step-3-create-a-scanner-role)) must still exist in every account you want to scan. Use [AWS CloudFormation StackSets](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/what-is-cfnstacksets.html), [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws/aws-iam-policy), or [AWS Organizations delegated admin](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_delegate_policies.html) to deploy the scanner role across all accounts automatically. -- **Check Asset Discovery:** In the ProjectDiscovery platform, navigate to the cloud assets or inventory section. After a successful integration, you should start seeing resources from your AWS account(s) listed (for example, EC2 instance IDs, S3 bucket names, etc., corresponding to the integrated accounts). It may take a short while for the initial discovery to complete. If you see those assets, the integration is working. -- **Test with a Known Resource:** As a quick test, pick a known resource (like a specific EC2 instance or S3 bucket in your AWS account) and search for it in ProjectDiscovery's asset inventory. If it appears, the connection is functioning and pulling data. -- **Troubleshooting Errors:** If the integration fails or some assets are missing, consider these common issues: - - _Incorrect Credentials:_ Double-check that the Access Key and Secret (if used) were entered correctly and correspond to an active IAM user. If you recently created the user, ensure you copied the keys exactly (no extra spaces or missing characters). - - _Insufficient Permissions:_ If certain services aren't showing up, the IAM policy might be missing permissions. For example, if S3 buckets aren't listed, confirm that the policy includes `s3:ListAllMyBuckets`. Refer back to the Required Permissions and make sure all relevant actions are allowed. You can also use AWS IAM Policy Simulator or CloudTrail logs to see if any **AccessDenied** errors occur when ProjectDiscovery calls AWS APIs. - - _Assume Role Failures:_ In multi-account or cross-account setups, a common issue is a misconfigured trust relationship. If ProjectDiscovery cannot assume a role, you might see an error in the UI or logs like "AccessDenied: Not authorized to perform sts:AssumeRole". In that case, check the following: - - The trust policy of the IAM role (in target account) trusts the correct principal (either your primary account's IAM user/role ARN for multi-account, or ProjectDiscovery's external account ID for cross-account) and the External ID if applicable. - - The role name or ARN in the ProjectDiscovery config exactly matches the one in AWS (spelling/case must match). - - The primary credentials (for multi-account) have permission to call `AssumeRole`. - - _External ID Mismatch:_ For cross-account roles, if the external ID in ProjectDiscovery and the one in the IAM role's trust policy do not match, AWS will deny the assume request. Ensure you didn't accidentally copy the wrong value or include extra spaces. It must be exact. -- **AWS CloudTrail Logs:** As an additional verification, you can check AWS CloudTrail in your account. When ProjectDiscovery connects, you should see events like `DescribeInstances`, `ListBuckets`, etc., being called by the IAM user or assumed role. For cross-account roles, you will see an `AssumeRole` event from ProjectDiscovery's AWS account ID, and subsequent calls under the assumed role's identity. This audit trail can confirm that the integration is working as intended and using only allowed actions. +Accounts where the scanner role is missing will be silently skipped — no error is shown. To avoid blind spots, ensure the scanner role is deployed to all accounts before enabling org discovery. + + +--- -If all checks out, ProjectDiscovery is now actively monitoring your AWS environment. New resources launched in AWS should be detected on the next scan cycle, and any changes to your cloud footprint will be reflected in the platform. Make sure to regularly review the integration and update the IAM permissions if you start using new AWS services. +#### AWS Troubleshooting + +| Error | Fix | +|---|---| +| `Not authorized to perform sts:AssumeRoleWithWebIdentity` | Check OIDC provider URL, WIF role trust policy `sub` condition (Team ID), and `aud` condition (`sts.amazonaws.com`) | +| `Access Denied` on AssumeRole | Check target role trust policy trusts `PDWorkloadIdentityRole`, and WIF role has `sts:AssumeRole` permission | +| `Access Denied` on resource enumeration | Check scanner permissions are on `PDScannerRole`, not the WIF role | + +--- #### API Setup @@ -1040,11 +1280,10 @@ The example above shows a minimal request. Refer to the [Create Enumeration API **References:** -1. https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_iam_read-only-console.html +1. https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html 2. https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html -3. https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html -4. https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html -5. https://docs.logrhythm.com/OCbeats/docs/aws-cross-account-access-using-sts-assume-role +3. https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html +4. https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts.html ### Google Cloud Platform (GCP)