Skip to main content
doc0blade47/compdocumentation home
Sign in

Cloud Security

Last updated Oct 11, 2026
Relevant source files

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.

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.

FieldTypeDescription
idstringUnique identifier for the finding.
titlestringA brief title for the finding.
descriptionstringDetailed description of the finding.
severity'info' | 'low' | 'medium' | 'high' | 'critical'The severity level of the finding.
resourceTypestringThe type of cloud resource affected (e.g., EC2 Instance, Storage Account).
resourceIdstringThe identifier of the affected resource.
remediationstring?Optional steps to remediate the finding.
evidenceRecord<string, unknown>?Optional additional context or raw data related to the finding.
createdAtstringTimestamp when the finding was created or observed.
passedboolean?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.

FieldTypeDescription
successbooleanIndicates if the scan completed successfully.
providerstringThe cloud provider that was scanned.
findingsSecurityFinding[]An array of security findings discovered.
scannedAtstringTimestamp when the scan was performed.
errorstring?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 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.
Asynchronous Scan

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:

  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.

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_DENIED errors, suggesting the "Security Center Findings Viewer" role.

Sources: apps/api/src/cloud-security/providers/gcp-security.service.ts:20-109

Was this page helpful?