Relevant source files
The following files were used as context for generating this wiki page:
- apps/api/src/cloud-security/cloud-security.service.ts
- apps/api/src/cloud-security/providers/azure-security.service.ts
- apps/api/src/cloud-security/providers/aws-security.service.ts
- apps/api/src/cloud-security/cloud-security.controller.ts
- apps/api/src/cloud-security/providers/gcp-security.service.ts
- 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, apps/api/src/cloud-security/cloud-security.service.ts:20-30, apps/api/src/cloud-security/cloud-security.controller.ts:13-16
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<string, unknown>? | 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
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
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
Credential Management
The service dynamically handles credential retrieval based on the integration provider's authentication type.
Sources: apps/api/src/cloud-security/cloud-security.service.ts:60-99
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 arun-cloud-security-scantask. This returns arunIdto 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
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.
// 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
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.
@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
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:
- Assumes an internal
SECURITY_HUB_ROLE_ASSUMER_ARNrole. - Using the credentials from the first hop, assumes the customer's specified
customerRoleArnwith anexternalId.
Sources: apps/api/src/cloud-security/providers/aws-security.service.ts:133-184
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
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
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_DENIEDerrors, suggesting the "Security Center Findings Viewer" role.
Sources: apps/api/src/cloud-security/providers/gcp-security.service.ts:20-109
On This Page
Architecture OverviewData StructuresSecurityFindingScanResultCloud Security Service (CloudSecurityService)Scan Process (scan method)Credential ManagementTriggering and Monitoring ScansStoring Findings (storeFindings method)Cloud Security Controller (CloudSecurityController)Cloud Security ModuleProvider-Specific Security ServicesAWS Security Service (AWSSecurityService)Key Features:IAM Role Assumption FlowFinding MappingAzure Security Service (AzureSecurityService)Key Features:GCP Security Service (GCPSecurityService)Key Features: