System Architecture
Core Features
Data Management
Frontend Components
Extensibility
The following files were used as context for generating this wiki page:
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.
The Cloud Security module is structured around a central CloudSecurityService which orchestrates the scanning process, and provider-specific services (AWSSecurityService, , ) that handle the unique API interactions for each cloud platform. The exposes the external API for initiating and monitoring scans.
AzureSecurityServiceGCPSecurityServiceCloudSecurityControllerSources: 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
The module defines key interfaces for representing security findings and scan results.
The SecurityFinding interface represents a single security issue identified during a scan.
The ScanResult interface encapsulates the outcome of a security scan for a given connection.
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 method)The scan method initiates a security scan for a given connectionId and organizationId.
The service dynamically handles credential retrieval based on the integration provider's authentication type.
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.
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
})),
});
}
});CloudSecurityController)The CloudSecurityController exposes the REST API endpoints for interacting with the Cloud Security module.
| Method | Path | Guard | Description ---
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 {}Each cloud provider has a dedicated service to handle its unique API interactions for security scanning.
AWSSecurityService)The AWSSecurityService is responsible for scanning AWS environments for security findings, primarily leveraging AWS Security Hub.
us-east-1.When using IAM Role authentication, the service performs a two-hop role assumption:
SECURITY_HUB_ROLE_ASSUMER_ARN role.customerRoleArn with an externalId.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
AzureSecurityService)The AzureSecurityService focuses on collecting security alerts and assessments from Azure subscriptions.
tenantId, clientId, clientSecret).GCPSecurityService)The GCPSecurityService integrates with Google Cloud Security Command Center to retrieve security findings.
CloudSecurityService's credential flow).PERMISSION_DENIED errors, suggesting the "Security Center Findings Viewer" role.