---
title: "Cloud Security"
description: "The Cloud Security module provides functionality to scan various cloud providers (AWS, Azure, GCP) for security findings. It integrates with the system's credential management to securely access cl..."
last_updated: "2026-05-06T07:29:41.656037+00:00"
canonical_url: "https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/technical/section-5/cloud-security"
---
Relevant source files
The following files were used as context for generating this wiki page:
- [apps/api/src/cloud-security/cloud-security.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.service.ts)
- [apps/api/src/cloud-security/providers/azure-security.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/azure-security.service.ts)
- [apps/api/src/cloud-security/providers/aws-security.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/aws-security.service.ts)
- [apps/api/src/cloud-security/cloud-security.controller.ts](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.controller.ts)
- [apps/api/src/cloud-security/providers/gcp-security.service.ts](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/gcp-security.service.ts)
- [apps/api/src/cloud-security/cloud-security.module.ts](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.module.ts)
The Cloud Security module provides functionality to scan various cloud providers (AWS, Azure, GCP) for security findings. It integrates with the system's credential management to securely access cloud resources, orchestrates scan tasks, and stores the collected security findings in the database. This module is crucial for maintaining a continuous security posture across integrated cloud environments.
At a high level, the module exposes API endpoints to trigger and monitor security scans. The core logic handles authentication, delegates to provider-specific services for actual scanning, and then processes and persists the results.
## Architecture Overview
The Cloud Security module is structured around a central `CloudSecurityService` which orchestrates the scanning process, and provider-specific services (`AWSSecurityService`, `AzureSecurityService`, `GCPSecurityService`) that handle the unique API interactions for each cloud platform. The `CloudSecurityController` exposes the external API for initiating and monitoring scans.
Sources: [apps/api/src/cloud-security/cloud-security.module.ts:1-17](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.module.ts#L1-L17), [apps/api/src/cloud-security/cloud-security.service.ts:20-30](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.service.ts#L20-L30), [apps/api/src/cloud-security/cloud-security.controller.ts:13-16](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.controller.ts#L13-L16)
## Data Structures
The module defines key interfaces for representing security findings and scan results.
### SecurityFinding
The `SecurityFinding` interface represents a single security issue identified during a scan.
| Field | Type | Description |
| :------------- | :----------------------------------- | :------------------------------------------------------------------------ |
| `id` | `string` | Unique identifier for the finding. |
| `title` | `string` | A brief title for the finding. |
| `description` | `string` | Detailed description of the finding. |
| `severity` | `'info' \| 'low' \| 'medium' \| 'high' \| 'critical'` | The severity level of the finding. |
| `resourceType` | `string` | The type of cloud resource affected (e.g., `EC2 Instance`, `Storage Account`). |
| `resourceId` | `string` | The identifier of the affected resource. |
| `remediation` | `string?` | Optional steps to remediate the finding. |
| `evidence` | `Record?` | Optional additional context or raw data related to the finding. |
| `createdAt` | `string` | Timestamp when the finding was created or observed. |
| `passed` | `boolean?` | Indicates if this is a passing check (default: `false`). |
Sources: [apps/api/src/cloud-security/cloud-security.service.ts:10-20](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.service.ts#L10-L20)
### ScanResult
The `ScanResult` interface encapsulates the outcome of a security scan for a given connection.
| Field | Type | Description |
| :---------- | :------------------- | :--------------------------------------------- |
| `success` | `boolean` | Indicates if the scan completed successfully. |
| `provider` | `string` | The cloud provider that was scanned. |
| `findings` | `SecurityFinding[]` | An array of security findings discovered. |
| `scannedAt` | `string` | Timestamp when the scan was performed. |
| `error` | `string?` | Optional error message if the scan failed. |
Sources: [apps/api/src/cloud-security/cloud-security.service.ts:22-29](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.service.ts#L22-L29)
## Cloud Security Service (`CloudSecurityService`)
The `CloudSecurityService` is the core service responsible for orchestrating cloud security scans. It handles connection validation, credential retrieval (including OAuth token refresh), delegation to provider-specific scanning logic, and persistence of scan results.
### Scan Process (`scan` method)
The `scan` method initiates a security scan for a given `connectionId` and `organizationId`.
Sources: [apps/api/src/cloud-security/cloud-security.service.ts:32-167](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.service.ts#L32-L167)
#### Credential Management
The service dynamically handles credential retrieval based on the integration provider's authentication type.
```mermaid
sequenceDiagram
participant CloudSecurityService
participant CredentialVaultService
participant OAuthCredentialsService
participant IntegrationPlatform
CloudSecurityService->>IntegrationPlatform: getManifest(providerSlug)
alt If OAuth2
CloudSecurityService->>OAuthCredentialsService: getCredentials(providerSlug, orgId)
OAuthCredentialsService-->>CloudSecurityService: oauthCreds
CloudSecurityService->>CredentialVaultService: getValidAccessToken(connectionId, oauthConfig)
CredentialVaultService-->>CloudSecurityService: accessToken
CloudSecurityService->>CredentialVaultService: getDecryptedCredentials(connectionId)
CredentialVaultService-->>CloudSecurityService: decryptedCreds
CloudSecurityService->>CloudSecurityService: Combine decryptedCreds + accessToken
else If Non-OAuth
CloudSecurityService->>CredentialVaultService: getDecryptedCredentials(connectionId)
CredentialVaultService-->>CloudSecurityService: decryptedCreds
CloudSecurityService->>CloudSecurityService: Use decryptedCreds directly
end
CloudSecurityService-->>CloudSecurityService: Credentials ready for provider scan
```
Sources: [apps/api/src/cloud-security/cloud-security.service.ts:60-99](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.service.ts#L60-L99)
### Triggering and Monitoring Scans
The `CloudSecurityService` also provides methods to trigger scans asynchronously and monitor their status using `@trigger.dev/sdk`.
- **`triggerScan(connectionId: string, organizationId: string)`**: Initiates an asynchronous scan by triggering a `run-cloud-security-scan` task. This returns a `runId` to track the task's progress.
- **`getRunStatus(runId: string, connectionId: string, organizationId: string)`**: Retrieves the status of a previously triggered scan run. It verifies the connection's ownership and fetches the run status from the `@trigger.dev/sdk`.
The `triggerScan` method leverages an external task orchestration system (`@trigger.dev/sdk`) to execute the scan asynchronously. This prevents long-running HTTP requests and allows for more robust background processing.
Sources: [apps/api/src/cloud-security/cloud-security.service.ts:170-218](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.service.ts#L170-L218)
### Storing Findings (`storeFindings` method)
After a scan, the `storeFindings` private method persists the `SecurityFinding` objects into the database. It creates an `IntegrationCheckRun` record and then `IntegrationCheckResult` records for each finding within a database transaction to ensure data consistency.
```typescript
// Example of storing findings
await db.$transaction(async (tx) => {
const scanRun = await tx.integrationCheckRun.create({
data: {
connectionId,
checkId: `${provider}-security-scan`,
// ... other run details
},
});
if (findings.length > 0) {
await tx.integrationCheckResult.createMany({
data: findings.map((finding) => ({
checkRunId: scanRun.id,
passed: finding.passed ?? false,
// ... other finding details
})),
});
}
});
```
Sources: [apps/api/src/cloud-security/cloud-security.service.ts:220-256](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.service.ts#L220-L256)
## Cloud Security Controller (`CloudSecurityController`)
The `CloudSecurityController` exposes the REST API endpoints for interacting with the Cloud Security module.
| Method | Path | Guard | Description ---
### Cloud Security Module
The `CloudSecurityModule` is responsible for setting up the Cloud Security feature. It imports necessary modules, registers controllers, and provides the services required for cloud security scanning.
```typescript
@Module({
imports: [IntegrationPlatformModule, AuthModule],
controllers: [CloudSecurityController],
providers: [
CloudSecurityService,
GCPSecurityService,
AWSSecurityService,
AzureSecurityService,
],
exports: [CloudSecurityService],
})
export class CloudSecurityModule {}
```
Sources: [apps/api/src/cloud-security/cloud-security.module.ts:6-17](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/cloud-security.module.ts#L6-L17)
## Provider-Specific Security Services
Each cloud provider has a dedicated service to handle its unique API interactions for security scanning.
### AWS Security Service (`AWSSecurityService`)
The `AWSSecurityService` is responsible for scanning AWS environments for security findings, primarily leveraging AWS Security Hub.
#### Key Features:
- **Credential Handling**: Supports both IAM Role assumption (two-hop process) and direct Access Key authentication.
- **Region Awareness**: Scans multiple AWS regions, determined from connection credentials or variables, defaulting to `us-east-1`.
- **Security Hub Integration**: Fetches findings from AWS Security Hub.
- **Error Tolerance**: Handles per-region failures gracefully (e.g., Security Hub not enabled in a region) by logging warnings and continuing with other regions.
#### IAM Role Assumption Flow
When using IAM Role authentication, the service performs a two-hop role assumption:
1. Assumes an internal `SECURITY_HUB_ROLE_ASSUMER_ARN` role.
2. Using the credentials from the first hop, assumes the customer's specified `customerRoleArn` with an `externalId`.
```mermaid
sequenceDiagram
participant AppService as CloudSecurityService
participant STSClientBase as AWS STS (Base)
participant STSClientAssumer as AWS STS (Assumer)
participant CustomerAWS as Customer AWS Account
AppService->>STSClientBase: AssumeRoleCommand (RoleAssumer ARN)
STSClientBase-->>AppService: Temp Creds (for RoleAssumer)
AppService->>STSClientAssumer: AssumeRoleCommand (Customer Role ARN, External ID)
STSClientAssumer-->>AppService: Temp Creds (for Customer Role)
AppService->>CustomerAWS: Perform Security Hub Scan (using Customer Role Temp Creds)
CustomerAWS-->>AppService: Security Findings
```
Sources: [apps/api/src/cloud-security/providers/aws-security.service.ts:133-184](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/aws-security.service.ts#L133-L184)
#### Finding Mapping
AWS Security Hub findings are mapped to the generic `SecurityFinding` interface, including severity mapping and region appending to the title for clarity.
Sources: [apps/api/src/cloud-security/providers/aws-security.service.ts:230-267](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/aws-security.service.ts#L230-L267)
### Azure Security Service (`AzureSecurityService`)
The `AzureSecurityService` focuses on collecting security alerts and assessments from Azure subscriptions.
#### Key Features:
- **OAuth2 Authentication**: Obtains an access token using client credentials flow (`tenantId`, `clientId`, `clientSecret`).
- **Microsoft Defender for Cloud Integration**: Fetches security alerts and assessments.
- **Pagination**: Handles paginated API responses to retrieve all available findings.
- **Permission Handling**: Provides specific remediation advice if 403 (AuthorizationFailed) errors are encountered, suggesting the "Security Reader" role.
Sources: [apps/api/src/cloud-security/providers/azure-security.service.ts:32-192](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/azure-security.service.ts#L32-L192)
### GCP Security Service (`GCPSecurityService`)
The `GCPSecurityService` integrates with Google Cloud Security Command Center to retrieve security findings.
#### Key Features:
- **OAuth2 Authentication**: Requires an access token (obtained via the `CloudSecurityService`'s credential flow).
- **Organization-Level Scan**: Scans findings at the GCP organization level.
- **Security Command Center Integration**: Queries the Security Command Center API for active findings.
- **Pagination**: Iterates through paginated results to collect all findings.
- **Permission Handling**: Provides specific remediation advice for `PERMISSION_DENIED` errors, suggesting the "Security Center Findings Viewer" role.
Sources: [apps/api/src/cloud-security/providers/gcp-security.service.ts:20-109](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/gcp-security.service.ts#L20-L109)
When integrating with cloud providers, correct permissions are critical. The services are designed to provide specific feedback for common permission-related issues:
- **AWS**: If Security Hub is not enabled in a region or `AccessDenied` errors occur, the service logs a warning and skips that region. For role assumption, ensure the `SECURITY_HUB_ROLE_ASSUMER_ARN` is configured and the customer's IAM role trust policy allows assumption by the `roleAssumer`.
Sources: [apps/api/src/cloud-security/providers/aws-security.service.ts:109-112](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/aws-security.service.ts#L109-L112), [apps/api/src/cloud-security/providers/aws-security.service.ts:140-143](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/aws-security.service.ts#L140-L143)
- **Azure**: For 403 or `AuthorizationFailed` errors when fetching alerts or assessments, the service adds a `SecurityFinding` indicating "Unable to access Security Alerts/Assessments" with a remediation step: "Assign the 'Security Reader' role to your App Registration on the subscription."
Sources: [apps/api/src/cloud-security/providers/azure-security.service.ts:80-92](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/azure-security.service.ts#L80-L92), [apps/api/src/cloud-security/providers/azure-security.service.ts:133-145](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/azure-security.service.ts#L133-L145)
- **GCP**: For `ACCESS_TOKEN_SCOPE_INSUFFICIENT` or `PERMISSION_DENIED` (403) errors, the service throws errors with specific messages: "OAuth scopes insufficient. Please disconnect and reconnect the GCP integration." or "Permission denied. Grant the 'Security Center Findings Viewer' role to your Google account at the organization level."
Sources: [apps/api/src/cloud-security/providers/gcp-security.service.ts:80-93](https://github.com/blade47/comp/blob/main/apps/api/src/cloud-security/providers/gcp-security.service.ts#L80-L93)
## Sitemap
See the full [sitemap](https://www.doc0.dev/docs/49c89830-117b-4def-8edc-b5bcc50766e0/llms.txt) for all pages in this wiki.