Custom Security Policy

This release introduces scan-level custom security policies, allowing users to override group-level security configurations on a per-scan basis.

🎯 Key Features

1. Custom Security Policy Per Scan

• Define custom security policies when starting a new scan

• Override group-level policies for specific scanning requirements

• Policy automatically preserved during rescans

2. Intelligent Policy Management

• Workers prioritize custom policies over group defaults

• All policies (custom and group) are normalized based on organization plan

• Automatic policy inheritance for project rescans

3. Dual Editing Modes

• Form Mode: User-friendly interface for common configurations

• JSON Mode: Advanced editing with syntax validation

---

📦 Changes Summary

Backend Changes

1. Scan Creation Endpoint (POST /api/v2/scan)

File: app/handlers/scan.go

• Added custom_security_policy parameter to RequestPayloadScan struct

• Accepts dynamic JSON object (map[string]interface{})

• Conditionally stored in database only when provided

Request Schema:

{
  "git_uri": "string",
  "endpoint_url": "string",
  "branch": "string",               // optional
  "initiated": "string",             // optional
  "custom_security_policy": {        // optional
    "scanners": ["compliance", "sast", "securitron"],
    "severity_threshold": "high"
  }
}

2. Pending Scans API (GET /api/v2/admin/scans/pending)

File: app/handlers/scan_handler.go

• Enhanced CheckPendingScans function with conditional logic

• If scan has custom_security_policy → use it as security_policy

• If scan lacks custom policy → use group policy

• Both policies are normalized based on organization plan

Behavior:

Scenario	Security Policy Source	Plan-Based Normalization
Custom policy exists	custom_security_policy	✅ Applied
No custom policy	Group's security_policy	✅ Applied

Important

Plan-Based Scanner Enforcement: All security policies (custom and group) are now normalized based on the organization's subscription plan. This ensures that even custom policies respect plan tier restrictions:

• FREE: Only compliance, secret, pii scanners

• PREMIUM: Adds sast, sca, container, iac, api

• ULTIMATE: All scanners including malware, vibe, securitron

3. Project Scans Endpoint (GET /api/v2/project/:project_id)

File: app/datastores/projects.go

• Added custom_security_policy to response projection

• Returns custom policy in scan listings when available

Response Schema:

[
  {
    "_id": "...",
    "created_at": 1234567890,
    "branch": "main",
    "status": "COMPLETED",
    "metadata": { "git": { "sha": "..." } },
    "custom_security_policy": {
      "scanners": ["compliance", "sast", "securitron"]
    }
  }
]

---

Frontend Changes

1. New Component: Scan Security Policy Modal

File: scan-security-policy-modal.tsx

• Dedicated modal for customizing scan-level security policies

• Toggle between Form and JSON editing modes

• Real-time validation and syntax checking

• Apply/Reset functionality

Features:

• 📝 Form editor for common configurations

• 🔧 Advanced JSON editor with syntax highlighting

• ✅ Validation feedback

• 🔄 Reset to group defaults

2. Enhanced: New Scan Modal

File: new-scan-modal.tsx

Additions:

• "Custom Security Policy" button (bottom left)

• Auto-fetch group security policy on modal open

• Visual badge: "Custom Policy Applied" when customized

• Passes custom_security_policy to API payload

User Flow:

1. User clicks "Start Scan"

2. Optionally clicks "Custom Security Policy"

3. Customizes policy → Apply

4. Starts scan with custom configuration

3. Enhanced: Projects Component

File: projects-component.tsx

Modified Function: handleRescan()

Enhancements:

• Fetches project's last scan via ApiClient.getProject()

• Extracts custom_security_policy from last scan (if present)

• Automatically passes it to rescan API

Rescan Behavior:

Last Scan Had Custom Policy → Rescan uses same custom policy
Last Scan Used Group Policy → Rescan uses current group policy

---

🔄 User Workflows

Workflow 1: Create Scan with Custom Policy

1. Navigate to group → Click "Start Scan"

2. Fill in required fields (Git URI, endpoint, branch)

3. Click "Custom Security Policy" button

4. Customize scanners, thresholds, or other settings

5. Click "Apply" → Badge shows "Custom Policy Applied"

6. Start scan

Result: Scan runs with custom policy, bypassing group defaults.

---

Workflow 2: Rescan with Preserved Policy

1. Navigate to project with previous custom-policy scan

2. Click "Rescan"

3. System automatically fetches and applies last scan's custom policy

Result: Rescan maintains original custom configuration.

---

Workflow 3: Edit Custom Policy (JSON Mode)

1. Click "Custom Security Policy" → Toggle to "JSON" tab

2. Edit raw JSON configuration

3. Validate syntax in real-time

4. Apply changes

Result: Advanced users can define complex custom policies.

---

🔌 API Integration

Request Format

POST /api/v2/scan
Content-Type: application/json

{
  "git_uri": "https://github.com/org/repo",
  "endpoint_url": "https://api.example.com",
  "branch": "main",
  "custom_security_policy": {
    "scanners": ["compliance", "sast", "securitron"],
    "severity_threshold": "critical",
    "exclude_patterns": ["test/*", "*.md"]
  }
}

Response

{
  "scan_id": "507f1f77bcf86cd799439011"
}

---

🛡️ Technical Details

Database Schema

Custom policies are stored in the scans collection:

{
  _id: ObjectId("..."),
  git_uri: "https://github.com/org/repo",
  branch: "main",
  status: "NEW",
  custom_security_policy: {  // Optional field
    scanners: [...],
    severity_threshold: "high"
  },
  // ... other fields
}

Worker Integration

Workers receive enriched scan documents from /api/v2/admin/scans/pending:

{
  "id": "...",
  "security_policy": {  // Either custom or group policy
    "scanners": ["compliance", "sast", "securitron"],
    ...
  },
  "access_token": "...",
  ...
}

---

✅ Benefits

Benefit	Description
Flexibility	Different policies for different projects/scenarios
Consistency	Rescans preserve original configurations
Control	Fine-grained security policy management
Efficiency	No need to modify group policies temporarily
Transparency	Custom policies visible in scan metadata
Security	Plan-based enforcement ensures compliance with subscription tiers

---

🔧 Migration Notes

• Backward Compatible: Existing scans without custom policies continue using group policies

• No Breaking Changes: All existing API contracts maintained

• Optional Feature: Custom policies are opt-in; default behavior unchanged

---

📝 Files Modified

Backend

• app/handlers/scan.go - Scan creation with custom policy support

• app/handlers/scan_handler.go - Pending scans with policy prioritization

• app/datastores/projects.go - Project scans with custom policy in response

Frontend

• scan-security-policy-modal.tsx - New custom policy editor modal

• new-scan-modal.tsx - Custom policy integration for new scans

• projects-component.tsx - Rescan with preserved custom policies

---

🚀 Future Enhancements

• Policy templates library

• Policy versioning and history

• Audit logging for policy changes

• Policy validation rules engine

---

Release Date: 2026-02-09 Status: ✅ Production Ready