feat(security): launch Penetration Tests epic across app, API lifecycle, and provider integration (#2193)

* feat(app): add security vulnerability report module

* fix(app): stabilize shell tooltip and menu ids

* fix(app): wrap shell tooltips in provider for hydration

* feat(security): add vulnerability reports checkout flow and report pages

* feat(security): add vulnerability reports module and checkout flow

* feat(security): gate security tab and routes behind feature flag

* feat(security): add vulnerability reports flow with mock checkout and Maced webhook reconciliation

* fix(security): address review feedback for vulnerability reports

* fix(app): correct vulnerability report api proxy imports

* fix(app): guard temporal ui url before window.open

* fix(app): resolve remaining vulnerability reports build type errors

* fix(app): address latest vulnerability reports review feedback

* fix(app): sync active organization before vulnerability report token

* refactor(app): remove vuln-report proxy routes and call Nest directly

* fix(api): stop forwarding comp org header to Maced

* fix(security): harden webhook handling and preserve checkout metadata

* feat(api): persist per-job webhook handshake for vuln reports

* feat(api): consume Maced-issued webhook tokens for vuln reports

* refactor(api): remove maced org mapping from vulnerability reports

* fix(security-reports): address remaining review threads

* chore(security): rebrand vulnerability reports UI as penetration tests

* fix(security-reports): enforce org ownership and harden report UI

* fix(api): satisfy build typing in vulnerability report parser

* docs: add public penetration tests guide

* chore(security): remove vulnerability report wording from shipped docs and metadata

* fix(api): enforce ownership persistence and early list short-circuit

* feat(security): rename penetration test routes and add run ownership table

* fix(security): harden pentest create flow and extract Maced client

* feat(security): validate Maced client contracts and fix checkout URL typing

* refactor(security): finalize penetration-tests naming and strict provider id contract

* chore(security): polish penetration-tests naming and config formatting

* fix(security): harden webhook handshake and reduce progress provider calls

* feat(api): reconcile penetration webhook by runId and drop orgId query

* fix(api): align webhook trust checks and run ownership migration

Author: claudfuen

apps/api/README.md

@@ -25,6 +25,11 @@
 
 [Nest](https://github.com/nestjs/nest) framework TypeScript starter repository.
 
+## Feature docs
+
+- Security penetration tests integration:
+  - `src/security-penetration-tests/README.md`
+
 ## Project setup
 
 ```bash

apps/api/src/app.module.ts

@@ -36,6 +36,7 @@ import { AssistantChatModule } from './assistant-chat/assistant-chat.module';
 import { OrgChartModule } from './org-chart/org-chart.module';
 import { TrainingModule } from './training/training.module';
 import { EvidenceFormsModule } from './evidence-forms/evidence-forms.module';
+import { SecurityPenetrationTestsModule } from './security-penetration-tests/security-penetration-tests.module';
 
 @Module({
   imports: [
@@ -84,6 +85,7 @@ import { EvidenceFormsModule } from './evidence-forms/evidence-forms.module';
     TrainingModule,
     OrgChartModule,
     EvidenceFormsModule,
+    SecurityPenetrationTestsModule,
   ],
   controllers: [AppController],
   providers: [

apps/api/src/security-penetration-tests/README.md

@@ -0,0 +1,40 @@
+# Security Penetration Tests (Maced Integration)
+
+This module exposes Comp API endpoints under `/v1/security-penetration-tests` and orchestrates report generation with Maced (`/v1/pentests`).
+
+## Endpoints
+
+- `GET /v1/security-penetration-tests`
+- `POST /v1/security-penetration-tests`
+- `GET /v1/security-penetration-tests/:id`
+- `GET /v1/security-penetration-tests/:id/progress`
+- `GET /v1/security-penetration-tests/:id/report`
+- `GET /v1/security-penetration-tests/:id/pdf`
+- `POST /v1/security-penetration-tests/webhook`
+
+## Required environment variables
+
+- `MACED_API_KEY`: Maced API key used by Nest API when calling provider endpoints.
+
+## Optional environment variables
+
+- `MACED_API_BASE_URL`: Defaults to `https://api.maced.ai`.
+- `SECURITY_PENETRATION_TESTS_WEBHOOK_URL`: Base callback URL for Comp webhook endpoint.
+
+## Webhook handshake model
+
+1. On create (`POST /v1/security-penetration-tests`), Maced issues a per-job `webhookToken` and returns it in the create response.
+2. Comp does not send a user-provided `webhookToken` upstream; the value is reserved for provider issuance.
+3. If callback target resolves to Comp webhook route and Maced returns `webhookToken`, Comp persists a handshake record in `secrets` using name:
+   - `security_penetration_test_webhook_<reportId>`
+4. On webhook receive, Comp:
+   - resolves org context (`X-Organization-Id` or `orgId`/`organizationId` query),
+   - resolves token (`webhookToken` query or `X-Webhook-Token` header),
+   - requires a persisted per-job handshake and verifies token hash match,
+   - tracks idempotency (`X-Webhook-Id`/`X-Request-Id`, plus payload hash fallback),
+   - returns `duplicate: true` for replayed webhook events.
+
+## Notes
+
+- Frontend should call Nest API only (no Next.js proxy routes for this feature).
+- Provider callbacks to non-Comp webhook URLs are passed through and are not forced to include Comp-specific webhook tokens.

apps/api/src/security-penetration-tests/dto/create-penetration-test.dto.ts

@@ -0,0 +1,80 @@
+import { IsBoolean, IsOptional, IsString, IsUrl } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreatePenetrationTestDto {
+  @ApiProperty({
+    description: 'Target URL for the penetration test scan',
+    example: 'https://app.example.com',
+  })
+  @IsUrl()
+  targetUrl!: string;
+
+  @ApiProperty({
+    description: 'Repository URL containing the target application code',
+    example: 'https://github.com/org/repo',
+    required: false,
+  })
+  @IsOptional()
+  @IsUrl()
+  repoUrl?: string;
+
+  @ApiPropertyOptional({
+    description: 'GitHub token used for cloning private repositories',
+    required: false,
+  })
+  @IsOptional()
+  @IsString()
+  githubToken?: string;
+
+  @ApiPropertyOptional({
+    description: 'Optional YAML configuration for the pentest run',
+    required: false,
+  })
+  @IsOptional()
+  @IsString()
+  configYaml?: string;
+
+  @ApiPropertyOptional({
+    description: 'Whether to enable pipeline testing mode',
+    required: false,
+    default: false,
+  })
+  @IsOptional()
+  @IsBoolean()
+  pipelineTesting?: boolean;
+
+  @ApiPropertyOptional({
+    description: 'Workspace identifier used by the pentest engine',
+    required: false,
+  })
+  @IsOptional()
+  @IsString()
+  workspace?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Set false to reject non-mocked checkout flows for strict behavior',
+    required: false,
+    default: true,
+  })
+  @IsOptional()
+  @IsBoolean()
+  mockCheckout?: boolean;
+
+  @ApiPropertyOptional({
+    description: 'Optional webhook URL to notify when report generation completes',
+    required: false,
+  })
+  @IsOptional()
+  @IsUrl()
+  webhookUrl?: string;
+
+  @ApiPropertyOptional({
+    description: 'Whether to run the pentest in simulation mode',
+    required: false,
+    default: false,
+  })
+  @IsOptional()
+  @IsBoolean()
+  testMode?: boolean;
+}