From 98b3e04180289270936ecd061bbe22cee3501e64 Mon Sep 17 00:00:00 2001 From: Tofik Hasanov Date: Fri, 24 Apr 2026 09:59:21 -0400 Subject: [PATCH] docs(cloud-tests): align AWS, Azure, GCP guides with actual connection flow Rewrites the Cloud Tests docs so they match the real product: - AWS: cross-account IAM role + External ID via AWS CloudShell script; replaces the old (incorrect) IAM user + access key walkthrough and fixes the malformed capabilities table and the copy-paste "Azure" references in the Support section. - Azure: Microsoft OAuth as the primary flow with the service principal flow preserved as an alternative; updates required roles to Reader + Security Reader + Monitoring Reader. - GCP: Google OAuth with auto-setup of required APIs and IAM roles; removes the outdated service-account JSON key flow. - Index: fixes broken links that pointed to /integrations/* instead of /cloud-tests/*, and adds a capability matrix and CardGroup for the three providers. All four pages now use the Mintlify components (``, ``, ``, ``) already used elsewhere in the docs. Co-Authored-By: Claude Opus 4.7 (1M context) --- packages/docs/cloud-tests/aws.mdx | 154 ++++++++++-------- packages/docs/cloud-tests/azure.mdx | 234 +++++++++++++++------------- packages/docs/cloud-tests/gcp.mdx | 218 ++++++++++++-------------- packages/docs/cloud-tests/index.mdx | 63 ++++---- 4 files changed, 346 insertions(+), 323 deletions(-) diff --git a/packages/docs/cloud-tests/aws.mdx b/packages/docs/cloud-tests/aws.mdx index a4c338c49d..6d8b90739a 100644 --- a/packages/docs/cloud-tests/aws.mdx +++ b/packages/docs/cloud-tests/aws.mdx @@ -1,93 +1,117 @@ --- title: "AWS Cloud Tests" -description: "AWS Cloud Tests allows you to connect your AWS infrastructure to Comp AI for automated security testing using Security Hub, compliance monitoring, and risk assessment." +description: "Connect your AWS account to Comp AI using a read-only IAM role and External ID to run continuous cloud security checks." --- -# Setup Process +## About the AWS integration -### Prerequisites +Comp AI connects to your AWS account using a **cross-account IAM role** with an **External ID**. No long-lived access keys are created, and all access is scoped to read-only unless you also opt in to auto-remediation with a separate role. -Before setting up the integration, ensure you have: +Once connected, Comp AI scans the regions you select and produces findings mapped to common frameworks (SOC 2, ISO 27001, CIS AWS Foundations, PCI DSS, HIPAA). -1. An AWS account with administrator access -2. Admin access to your Comp AI workspace -3. IAM permissions to create and manage roles, policies, and trust relationships + + Comp AI assumes your role from a dedicated AWS principal. You control the trust policy, so you can revoke access at any time by deleting the role. + -### Configuration Steps +## How access works -1. **Log into your AWS Management Console** -2. **Enable Security Hub** - - Navigate to **Security Hub** in the AWS Console - - Click **Get Started** - - Enable Security Hub in your **desired regions** - - Optionally, enable **default security standards** (like CIS AWS Foundations) -3. **Choose a Region Code** - - Decide which AWS region you want Comp AI to use (e.g., `us-east-1`, `us-west-2`) - - Copy this region code — you’ll need it in the Comp AI UI -4. **Create an IAM User for Comp AI** - - Go to **IAM \> Users**, then click **Add user** - - Enter a name like `CompAIIntegrationUser` - - Choose **Programmatic access** (this generates the Access Key ID & Secret) -5. **Set Permissions** - - On the permissions screen, click **Attach policies directly** - - Attach the following AWS managed policies: - - `SecurityAudit` - - `AmazonEC2ReadOnlyAccess & AWSSecurityHubReadOnlyAccess` +- **Auth model**: AWS STS `AssumeRole` from a Comp AI–managed principal into a role in your account +- **External ID**: Required in the trust policy so only a specific Comp AI organization can assume the role +- **Permissions**: `SecurityAudit` + `ViewOnlyAccess` managed policies, plus two small inline policies for Cost Explorer reads and SSM document metadata +- **Optional auto-remediation**: A separate role (`CompAI-Remediator`) can be created to enable auto-fix actions — this role is **only used when you explicitly trigger a fix**. The audit role stays read-only. - _(Or use a custom least-privilege policy — see example below)_ -6. **Create the User** - - Click **Next**, then **Create user** - - Copy and securely store the **Access Key ID** and **Secret Access Key** - - You will only see the secret once! -7. **Connect AWS to Comp AI** - - Go to **Settings \> Integrations** in your Comp AI dashboard - - Click **Connect** next to the AWS integration card - - Paste the **Access Key ID**, **Secret Access Key**, and **Region Code** - - Click **Save and Connect** +## Prerequisites -## Capabilities +Before you begin, make sure you have: -### Security Tests +1. An AWS account with permission to create IAM roles +2. Your Comp AI **organization ID** (used as the External ID — Comp AI's connection form pre-fills this for you) +3. Admin access to your Comp AI workspace -The AWS integration performs the following security assessments: +## Connect AWS -| Test Category | Description | IAM Misconfigurations | Detects overly permissive roles, users, or policies | S3 Bucket Security | Checks for public access, encryption, and versioning | EC2 Instance | Analysis Reviews security group rules, instance metadata access | Security Hub | Findings Integrates AWS Security Hub findings for real-time insights | CloudTrail | Configuration Verifies CloudTrail logging and monitoring | Config & Compliance Checks | Audits AWS Config rules and compliance state +The Comp AI UI walks you through the full flow and displays the exact CloudShell script to run. The summary below is for reference. -### Compliance Frameworks + + + Go to **Cloud Tests → AWS → Connect**. Comp AI displays a CloudShell script pre-filled with your External ID. + + + Open [AWS CloudShell](https://console.aws.amazon.com/cloudshell) in the account you want to scan and paste the script. It: + + - Creates an IAM role named `CompAI-Auditor` + - Attaches `SecurityAudit` and `ViewOnlyAccess` managed policies + - Adds small inline policies for `ce:GetCostAndUsage` and `ssm:GetDocument` / `ssm:DescribeDocument` / `ssm:ListDocuments` + - Sets a trust policy that only allows Comp AI to assume the role when the correct External ID is supplied + - Prints the new **Role ARN** + + + Copy the Role ARN from the script output and paste it into the Comp AI connection form. Choose the regions you want scanned. The External ID is already filled in. + + + If you want Comp AI to be able to apply fixes, run the second CloudShell script shown in the UI. It creates a separate `CompAI-Remediator` role with narrower write permissions for the specific services that support auto-fix. + + + Click **Save and Connect**. Comp AI validates the role, then queues an initial scan across all selected regions. + + + +## What gets scanned + +The AWS integration evaluates findings across a wide set of AWS services, including: + +| Area | Services | +| ------------- | ------------------------------------------------------------------------------- | +| Identity | IAM, IAM Access Analyzer, Cognito | +| Storage | S3, EBS, EFS, DynamoDB, RDS, Redshift, OpenSearch, ElastiCache | +| Compute | EC2 & VPC, Lambda, ECS & EKS, EMR, Elastic Beanstalk, CodeBuild, Step Functions | +| Network | VPC, ELB/ALB, CloudFront, API Gateway, Route 53, WAF, Network Firewall, Shield | +| Data security | KMS, Secrets Manager, ACM, Macie, Inspector | +| Observability | CloudTrail, CloudWatch, AWS Config, GuardDuty, Security Hub | +| Messaging | SNS, SQS, Kinesis, EventBridge, MSK | +| Other | Backup, ECR, Glue, Athena, SageMaker, Systems Manager, Transfer Family, AppFlow | + +The **Services** tab inside each connection lets you enable or disable specific checks per service. + +## Compliance frameworks + +Findings are mapped to the controls used by: -- The integration checks compliance against: - CIS AWS Foundations Benchmark - SOC 2 -- HIPAA (where applicable) -- PCI DSS -- GDPR - ISO 27001 +- PCI DSS +- HIPAA (where applicable) -## Managing Access - -### Access Control - -Comp AI uses a cross-account IAM role with read-only permissions and a required external ID to ensure secure, scoped access. This approach follows AWS best practices for secure third-party integrations. +## Security model -### Permissions +- **Read-only by default** — the audit role cannot create, modify, or delete resources +- **External ID enforced** — Comp AI refuses to connect unless the External ID in your trust policy matches the one stored against your Comp AI organization +- **No static credentials** — Comp AI never stores AWS access keys; short-lived credentials are issued by STS on each scan +- **Revocable at any time** — deleting the IAM role in your account immediately cuts off access -The IAM role created for integration has permissions to: +## Troubleshooting -- Describe resources (EC2, S3, IAM, etc.) -- Read configuration and audit logs -- Access Security Hub and CloudTrail -- List AWS Config and resource statuses -- The integration does NOT have permissions to: + + The most common cause is an External ID mismatch. Confirm the value in your role's trust policy matches the External ID shown in the Comp AI connection form. If you recently rotated it, re-run the CloudShell script. + -Modify any resources + + Comp AI expects an ARN in the form `arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME`. Make sure you copied the role ARN from the CloudShell output, not the account or user ARN. + -- Create or delete resources -- Write to S3 or other services + + Check that: + 1. The role has `SecurityAudit` + `ViewOnlyAccess` attached (the script attaches both) + 2. The region is enabled on your connection + 3. The service is turned on in the **Services** tab for this connection + -### Support + + Auto-remediation requires the separate `CompAI-Remediator` role. Run the second CloudShell script shown in the UI, then paste its Role ARN into the **Remediation Role ARN** field. + -For additional assistance with your Azure integration: +## Support -1. Check our [Knowledge Base](https://help.trycomp.ai/azure-integration) -2. Contact support at [support@trycomp.ai](mailto:support@trycomp.ai) -3. Join our [Discord community](https://discord.gg/compai) for peer support \ No newline at end of file +1. Email [support@trycomp.ai](mailto:support@trycomp.ai) +2. Join our [Discord community](https://discord.gg/compai) diff --git a/packages/docs/cloud-tests/azure.mdx b/packages/docs/cloud-tests/azure.mdx index fe6ff06776..1f2facfe33 100644 --- a/packages/docs/cloud-tests/azure.mdx +++ b/packages/docs/cloud-tests/azure.mdx @@ -1,128 +1,148 @@ --- title: "Azure Cloud Tests" -description: "Connect Azure to Comp AI for cloud security testing" +description: "Connect Microsoft Azure to Comp AI over OAuth (or a service principal) to run continuous cloud security checks against Microsoft Defender for Cloud." --- -# Azure Cloud Test - -The Azure Cloud Test enables you to connect your Microsoft Azure cloud environment to Comp AI for comprehensive security testing, compliance monitoring, and risk assessment using Microsoft Defender for Cloud - -## Setup Process - -### Prerequisites - -Before setting up the integration, ensure you have: - -1. Azure subscription with Owner or Contributor access -2. Admin access to your Comp AI workspace -3. Permissions to register applications in Azure AD - -### Configuration Steps - -1. **Log into your Azure Portal** - - Visit https://portal.azure.com -2. **Enable Microsoft Defender for Cloud** - - In the left-hand menu, search for and select **Microsoft Defender for Cloud** - - Click **Getting started** - - Select the subscription(s) you want to onboard - - Enable **Microsoft Defender plans** (especially for relevant services like Compute, Storage, SQL, etc.) - - Wait for the provisioning to complete (this may take a few minutes) -3. **Register an Application in Azure AD** - - Navigate to **Azure Active Directory \> App registrations** - - Click **\+ New registration** - - Name the app (e.g., `CompAIIntegrationApp`) - - Choose **Accounts in this organizational directory only** - - Click **Register** -4. **Get the Client ID and Tenant ID** - - After registration, go to the app's **Overview** page - - Copy the **Application (client) ID** - - Copy the **Directory (tenant) ID** -5. **Create a Client Secret** - - In the app menu, go to **Certificates & secrets** - - Under **Client secrets**, click **\+ New client secret** - - Add a description and set an expiration - - Click **Add** - - Copy the **Client secret value** — you won’t be able to see it again! -6. **Assign the Application Access to a Subscription** - - Go to **Subscriptions** in the Azure portal - - Select the subscription you want to integrate - - Copy the **Subscription ID** - - Click **Access control (IAM)** - - Click **\+ Add \> Add role assignment** - - Select role: **Reader** (or **Security Reader** for enhanced visibility) - - Assign access to: **User, group, or service principal** - - Select your registered application -7. **Connect Azure to Comp AI** - - Go to **Settings \> Integrations** in your Comp AI dashboard - - Click **Connect** next to the Azure integration card - - Paste the following values: - - **Client ID** - - **Client Secret** - - **Tenant ID** - - **Subscription ID** - - Click **Save and Connect** - -## Capabilities - -### Security Tests - -The Azure Cloud Test performs the following security assessments: - -| Test Category | Description | -| ----------------- | ------------------------------------------------------------------------- | -| IAM Analysis | Review Azure AD roles and custom RBAC assignments | -| Storage Security | Identify improperly configured storage account permissions and encryption | -| VM Security | Analyze NSGs, VM configurations, and patch status | -| Database Security | Check Azure SQL, Cosmos DB, and other database security settings | -| Activity Logs | Verify proper logging and monitoring configuration | -| Key Vault | Validate secret management and key rotation policies | -| Network | Assess VNet configurations, NSGs, and service endpoints | - -### Compliance Frameworks - -The Cloud Test checks compliance against: +## About the Azure integration + +Comp AI connects to Microsoft Azure to pull security posture, identity, network, and compliance data from **Microsoft Defender for Cloud** and related services. All access is read-only. + +The recommended connection method is **Microsoft OAuth** — you sign in with an Azure AD account that has the required roles, and Comp AI auto-detects your subscription. A **service principal** flow is also supported for customers who prefer to provision a dedicated identity. -- Microsoft Cloud Security Benchmark -- SOC 2 -- HIPAA (where applicable) -- PCI DSS -- GDPR -- ISO 27001 + + Comp AI only ever issues `GET`/`list` API calls. It does not create, modify, or delete Azure resources, even when connected with a user that has write permissions. + + +## How access works + +- **Primary flow**: OAuth 2.0 against `login.microsoftonline.com` using the `user_impersonation` scope on Azure Management API. Comp AI acts on behalf of the signed-in user, constrained by their Azure RBAC assignments. +- **Alternative flow**: An Azure AD App Registration (service principal) with a client secret, assigned the required roles on a subscription. +- **Scope**: A single Azure subscription per connection. Connect additional subscriptions by adding more connections. + +## Prerequisites + +Before connecting Azure, make sure you have: + +1. An **Azure subscription** you want to monitor +2. A user (or service principal) with the following roles on that subscription: + - **Reader** — read resource metadata + - **Security Reader** — read Microsoft Defender for Cloud findings + - **Monitoring Reader** — read activity logs, alerts, and metrics +3. **Microsoft Defender for Cloud** enabled on the subscription (the free tier is sufficient for most checks) +4. Admin access to your Comp AI workspace + +## Connect with OAuth (recommended) + + + + In Comp AI, go to **Cloud Tests → Azure → Connect**. Click **Sign in with Microsoft**. + + + Sign in with an Azure AD account that has the roles listed above on the target subscription. Approve the consent screen. + + + Comp AI automatically detects the subscriptions your account can access. The setup guide then runs checks for: + + - **Subscription detected** + - **Required role assignments** + - **Defender for Cloud enabled** -## Managing Access + Any blocking issue is shown with a link to the exact Azure portal blade to fix it. + + + When all required steps pass, the first scan starts automatically. You can re-run it any time from the connection's page. + + -### Access Control + + Microsoft OAuth uses the RBAC roles on your account. Granting **Reader + Security Reader + Monitoring Reader** is enough — you do **not** need Contributor or Owner. + -Comp AI requires read-only access to your Azure environment. The integration uses Azure's built-in Reader role or custom roles with specific permissions that follow the principle of least privilege. +## Connect with a service principal (alternative) -### Permissions +Use this flow if you want a dedicated non-human identity or your tenant restricts user OAuth consent. -The Azure application/service principal has permissions for: + + + In the Azure portal, go to **Microsoft Entra ID → App registrations → New registration**. Name it something like `comp-security-audit` and register. + + + In the app, open **Certificates & secrets → New client secret**. Copy the secret **value** immediately — it is only shown once. + + + Open your target subscription, go to **Access control (IAM) → Add role assignment**, and assign each of these roles to the app registration: -- Reading resource configurations -- Listing resources and their attributes -- Viewing diagnostic settings + - **Reader** + - **Security Reader** + - **Monitoring Reader** + + + From the Azure portal, copy: -The integration does NOT have permissions to: + - **Tenant ID** — Microsoft Entra ID → Overview + - **Client ID** — App registration → Overview (Application ID) + - **Client Secret** — the value from the previous step + - **Subscription ID** — Subscriptions → your subscription + + + In the Azure connection form, switch to the service principal option and paste the four values. Click **Save and Connect**. + + -- Modify any resources -- Create new resources -- Delete existing resources +## What gets scanned + +The Azure integration evaluates findings across services including: + +| Area | Services | +| ------------- | ----------------------------------------------------------------- | +| Posture | Microsoft Defender for Cloud (assessments + alerts) | +| Identity | Microsoft Entra ID | +| Governance | Azure Policy | +| Data security | Key Vault, Storage Accounts, SQL Database, Cosmos DB | +| Compute | Virtual Machines, App Service, AKS, Container Registry | +| Network | Network Watcher (NSGs, flow logs) | +| Observability | Azure Monitor (activity logs, diagnostic settings) | + +The **Services** tab inside the connection lets you enable or disable specific checks. + +## Compliance frameworks + +Findings are mapped to the controls used by: + +- Microsoft Cloud Security Benchmark +- SOC 2 +- ISO 27001 +- PCI DSS +- HIPAA (where applicable) + +## Security model + +- **Read-only** — Comp AI makes no write calls, regardless of the roles you assign +- **Scoped to one subscription per connection** — a connection cannot read data outside the subscription it was created for +- **Secrets stay encrypted** — client secrets and refresh tokens are stored in an encrypted vault and never returned to the UI +- **Revocable at any time** — remove the role assignments in the Azure portal, or delete the connection in Comp AI ## Troubleshooting -### Common Issues + + Defender for Cloud must be enabled on the subscription. Open the **Microsoft Defender for Cloud** blade, select the subscription, and confirm at least the free tier is turned on. Initial data can take up to 24 hours to appear. + + + + For OAuth: make sure your account still has the three required roles on the subscription — `User_impersonation` scope alone is not enough. -**Issue**: Failed to connect Azure subscription\ -**Solution**: Verify service principal credentials and role assignments + For service principal: confirm the client secret has not expired and the app registration has not been disabled. + -**Issue**: Authentication errors\ -**Solution**: Ensure the service principal hasn't expired and secret is valid + + Comp AI only sees subscriptions your signed-in account has access to. If you manage multiple subscriptions, sign in with an account that has **Reader** on the one you want to monitor, or use the service principal flow to target it explicitly. + -### Support + + Check that the service is enabled under the **Services** tab for this connection. Some services also require Defender plans beyond the free tier — for example, Defender for Servers, SQL, or Containers. + -For additional assistance with your Azure Cloud Tests: +## Support -1. Check our [Knowledge Base](https://help.trycomp.ai/azure-integration) -2. Contact support at [support@trycomp.ai](mailto:support@trycomp.ai) -3. Join our [Discord community](https://discord.gg/compai) for peer support \ No newline at end of file +1. Email [support@trycomp.ai](mailto:support@trycomp.ai) +2. Join our [Discord community](https://discord.gg/compai) diff --git a/packages/docs/cloud-tests/gcp.mdx b/packages/docs/cloud-tests/gcp.mdx index e4d2bb6780..167faacdbb 100644 --- a/packages/docs/cloud-tests/gcp.mdx +++ b/packages/docs/cloud-tests/gcp.mdx @@ -1,148 +1,124 @@ --- title: "GCP Cloud Tests" -description: "Connect Google Cloud Platform to Comp AI for cloud security testing" +description: "Connect Google Cloud Platform to Comp AI over OAuth so findings from Security Command Center flow into your compliance posture." --- -# Google Cloud Platform Cloud Test +## About the GCP integration -The Google Cloud Platform (GCP) Cloud Test allows you to connect your GCP projects to Comp AI for automated compliance monitoring, and risk assessment. +Comp AI connects to Google Cloud Platform over **OAuth 2.0** and reads findings from **Security Command Center (SCC)**. No service account JSON key is uploaded — you sign in with a Google account that has access to the organization and projects you want to monitor. -## Setup Process - -### Prerequisites - -Before setting up the Cloud Test, ensure you have: - -1. GCP project with Owner or Editor access -2. Admin access to your Comp AI workspace -3. Permissions to create service accounts +After you connect, Comp AI auto-detects your organization, lets you pick projects, then runs a setup step that enables the required APIs and verifies IAM access. Findings are mapped to common frameworks (SOC 2, ISO 27001, CIS GCP Foundations, PCI DSS, HIPAA). - Security Command Center must be enabled on your GCP account. - - GCP Console =\> Security =\> Risk Overview + Security Command Center is where all GCP findings originate. If SCC is not enabled at the organization, Comp AI cannot read findings regardless of connection method. -### Configuration Steps - -1. Navigate to **Cloud Tests** in your Comp AI dashboard -2. Click on **Connect** next to the GCP integration card -3. Link Service Account - - In a Project, go to the [GCP Console → IAM & Admin → Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) - - Click **“Create Service Account”** and give it a name like `comp-ai-integration` - - Click **Continue**, then grant the following roles: - - `Security Center Findings Viewer` (`roles/securitycenter.findingsViewer`) - - `Service Usage Consumer` - - `Viewer` (`roles/viewer`) - - Complete the service account creation - - Copy the Service Account Email that was generated (this will be needed for the next step) - - Screenshot 2025-11-18 at 10.40.02 AM.png - - After creating the service account: - - Go to the **“Keys”** tab - - Click **“Add Key” → “Create new key”**, select **JSON**, then click **Create** - - Download the key — you’ll use this in the next step - - Go to the [API Library](https://console.cloud.google.com/apis/library) and enable: - - **Security Command Center API** - - **Cloud Resource Manager API** -4. At the Org level, go to the GCP Console → IAM & Admin → IAM - - Grant access - - Add the Service account email from the last step - - Grant the following role: - - `Security Center Findings Viewer` (`roles/securitycenter.findingsViewer`) - -Screenshot 2025-11-18 at 10.50.37 AM.png - -4. Add Credentials to GCP Cloud Test in Comp AI app - 1. Copy & Paste the Organization Id (Not the project Id) from Google Cloud into the **Organization ID** field in the Comp AI connection form - 1. Open the downloaded JSON file, and copy its entire contents - 2. Paste it into the **Service Account Key** field in the Comp AI connection form - - Screenshot 2025-11-20 at 9.31.56 AM.png -1. Click Connect GCP - -## Capabilities - -### Security Tests - -The GCP Cloud Test performs the following security assessments: - -| Test Category | Description | -| ----------------- | --------------------------------------------------------------------- | -| IAM Analysis | Review IAM roles and service account permissions | -| GCS Security | Identify improperly configured bucket permissions and encryption | -| Compute Security | Analyze firewall rules, instance configurations, and patch status | -| Database Security | Check Cloud SQL, Firestore, and other database security settings | -| Cloud Logging | Verify proper logging and monitoring configuration | -| KMS | Validate encryption key usage and rotation policies | -| Network | Assess VPC configurations, firewall rules, and load balancer settings | - -### Compliance Frameworks - -The Cloud Test checks compliance against: - -- CIS GCP Foundation Benchmark -- SOC 2 -- HIPAA (where applicable) -- PCI DSS -- GDPR -- ISO 27001 +## How access works -## Managing Access +- **Auth model**: OAuth 2.0 with Google, using the `cloud-platform` scope plus `openid`, `email`, `profile` for account identification. Refresh tokens are stored so scans can run without re-prompting. +- **Real permissions**: The OAuth scope only enables API calls — actual access is gated by the **IAM roles** assigned to the signed-in account. Comp AI only makes read calls. +- **Required role**: `roles/securitycenter.findingsViewer` on the **organization** (needed to read SCC findings). Project-level `roles/viewer` is also recommended. +- **Scope**: Comp AI scans the projects you select inside the organization the signed-in account belongs to. -### Access Control +## Prerequisites -Comp AI requires read-only access to your GCP environment. The Cloud Test uses a service account with specific IAM roles that follow the principle of least privilege. +Before connecting GCP, make sure you have: -### Permissions +1. A **GCP organization** with **Security Command Center** enabled — confirm at **GCP Console → Security → Risk Overview** +2. A Google account with: + - `roles/securitycenter.findingsViewer` on the organization + - `roles/viewer` (or equivalent) on the projects you want to scan +3. Permission to enable APIs on at least one project in the organization (so Comp AI's setup step can enable SCC, Cloud Resource Manager, and Service Usage APIs if they are not already on) +4. Admin access to your Comp AI workspace -The service account has the following roles: + + If Security Command Center is not yet enabled, enable it first at [console.cloud.google.com/security/command-center](https://console.cloud.google.com/security/command-center). + -- Viewer (roles/viewer) at project level -- Security Reviewer (roles/iam.securityReviewer) -- Storage Object Viewer (roles/storage.objectViewer) +## Connect GCP + + + + In Comp AI, go to **Cloud Tests → GCP → Connect**. Click **Sign in with Google**. + + + Sign in with a Google account that meets the prerequisites above and approve the consent screen. Comp AI stores the resulting refresh token (never the password) so it can run scheduled scans. + + + Comp AI auto-detects your organization and lists the projects that account can access. Pick the ones you want scanned — findings are scoped to those projects. + + + Comp AI's setup guide runs automatically and shows a checklist: + + - Connected via OAuth + - Organization detected + - Required APIs enabled (Security Command Center, Cloud Resource Manager, Service Usage) + - `roles/securitycenter.findingsViewer` granted at the organization level + + Any step that fails is shown with a one-click **Resolve** button or a link to the exact GCP console page plus the `gcloud` command you can run to fix it manually. + + + When all required steps pass, the first scan starts automatically. You can re-run it any time from the connection's page. + + + +## What gets scanned + +Comp AI consumes findings from Security Command Center across services including: + +| Area | Services | +| ------------- | ----------------------------------------------------- | +| Identity | IAM (over-privileged accounts, service account keys) | +| Storage | Cloud Storage (ACLs, public access, encryption) | +| Compute | Compute Engine, GKE | +| Network | VPC Network (firewall rules, flow logs), Cloud Armor | +| Data | Cloud SQL, BigQuery, Pub/Sub | +| Cryptography | Cloud KMS | +| Observability | Cloud Logging, Cloud Monitoring | +| DNS | Cloud DNS (DNSSEC) | + +The **Services** tab inside the connection lets you enable or disable specific check categories. + +## Compliance frameworks + +Findings are mapped to the controls used by: + +- CIS GCP Foundations Benchmark +- SOC 2 +- ISO 27001 +- PCI DSS +- HIPAA (where applicable) -The integration does NOT have permissions to: +## Security model -- Modify any resources -- Create new resources -- Delete existing resources +- **Read-only in practice** — Comp AI only issues read API calls against SCC and resource manager +- **IAM-bounded** — access is limited to what the signed-in account's IAM roles permit +- **Token storage** — refresh tokens are stored in an encrypted vault; they are never returned to the UI +- **Revocable at any time** — remove the IAM role, revoke the token at [myaccount.google.com/permissions](https://myaccount.google.com/permissions), or delete the connection in Comp AI ## Troubleshooting -### Common Issues + + Confirm SCC is enabled at the organization level (not just one project). Open **GCP Console → Security → Risk Overview** and check that the organization shows findings. + -**Issue**: Failed to connect GCP project\ -**Solution**: Verify organization id and service account key and IAM permissions + + The signed-in account does not have permission to manage IAM at the organization level. Ask a GCP organization admin to grant `roles/securitycenter.findingsViewer` to the account (or service account) you connected with. Copy the email shown in the setup guide — that is exactly who needs the role. + -**Issue**: Missing scan results for specific services\ -**Solution**: Check IAM permissions for those specific services + + The signed-in account lacks the `serviceusage.services.enable` permission on the target project. Either sign in with an account that has `roles/serviceusage.serviceUsageAdmin` on the project, or enable the three APIs manually from the [API Library](https://console.cloud.google.com/apis/library): -**Issue**: Authentication errors\ -**Solution**: Ensure the service account key is valid and not expired + - Security Command Center API + - Cloud Resource Manager API + - Service Usage API + -### Support + + Comp AI only lists projects the signed-in account has IAM access to. Sign in with a different Google account, or ask an admin to add your account as `roles/viewer` on the relevant projects. + -For additional assistance with your GCP integration: +## Support -1. Check our [Knowledge Base](https://help.trycomp.ai/gcp-integration) -2. Contact support at [support@trycomp.ai](mailto:support@trycomp.ai) -3. Join our [Discord community](https://discord.gg/compai) for peer support \ No newline at end of file +1. Email [support@trycomp.ai](mailto:support@trycomp.ai) +2. Join our [Discord community](https://discord.gg/compai) diff --git a/packages/docs/cloud-tests/index.mdx b/packages/docs/cloud-tests/index.mdx index 55ac974b83..42926ecb43 100644 --- a/packages/docs/cloud-tests/index.mdx +++ b/packages/docs/cloud-tests/index.mdx @@ -1,45 +1,48 @@ --- title: "Cloud Tests" -description: "Comp AI Cloud Tests Guide" +description: "Continuously assess your cloud posture by connecting AWS, Azure, and GCP to Comp AI." --- -## Supported Cloud Tests +## What Cloud Tests do -Comp AI offers several Cloud Tests with third-party services to enhance your experience: +Cloud Tests connect your cloud accounts to Comp AI and continuously evaluate them against security and compliance controls. Each finding is mapped to the frameworks you track (SOC 2, ISO 27001, CIS, PCI DSS, HIPAA), so cloud misconfigurations show up directly in your compliance posture. -### Cloud Provider Integrations +All connections are **read-only by default**. Comp AI only makes `GET` / `list` calls against each cloud provider unless you explicitly opt in to auto-remediation (AWS). -Comp AI integrates with major cloud providers to facilitate cloud security testing and compliance monitoring: +## Supported providers -#### AWS Cloud Test + + + Cross-account IAM role with External ID. No access keys stored. + + + Sign in with Microsoft OAuth, or provision a service principal. + + + Sign in with Google OAuth. Findings flow from Security Command Center. + + -- **Purpose**: Perform security tests and compliance checks on AWS infrastructure -- **Features**: - - IAM policy analysis - - S3 bucket security assessment - - EC2 instance compliance monitoring - - CloudTrail audit log analysis +## How connections are authorized -For setup instructions, see the [AWS Cloud Tests Guide](/integrations/aws). +| Provider | Connection method | What you provide | +| -------- | ------------------------------------------- | ------------------------------------------------------------ | +| AWS | Cross-account IAM role (STS AssumeRole) | Role ARN + External ID (pre-filled in the UI) | +| Azure | OAuth 2.0 (primary) or service principal | Microsoft sign-in, or Tenant + Client ID + Secret + Sub ID | +| GCP | OAuth 2.0 | Google sign-in; org + projects auto-detected after consent | -#### Azure Cloud Test +## Common capabilities -- **Purpose**: Perform security tests and compliance checks on Azure infrastructure -- **Features**: - - Resource group security assessment - - Azure AD configuration analysis - - Storage account compliance checks - - Network security evaluation +Regardless of provider, each connection supports: -For setup instructions, see the [Azure Cloud Tests Guide](/integrations/azure). +- **Continuous scanning** on a schedule, with on-demand re-scans +- **Per-service toggles** so you can enable only the checks you care about +- **Findings mapped to frameworks** (SOC 2, ISO 27001, CIS, PCI DSS, HIPAA) +- **Evidence collection** that plugs directly into the compliance module +- **Multiple connections per provider** so you can monitor multiple accounts, subscriptions, or orgs separately -#### GCP Cloud Test +## Next steps -- **Purpose**: Perform security tests and compliance checks on Google Cloud Platform -- **Features**: - - IAM role analysis - - GCS bucket security assessment - - Compute Engine compliance monitoring - - Cloud logging audit analysis - -For setup instructions, see the [GCP Cloud Tests Guide](/integrations/gcp). \ No newline at end of file +- [Set up AWS](/cloud-tests/aws) +- [Set up Azure](/cloud-tests/azure) +- [Set up GCP](/cloud-tests/gcp)