Policy Management

Overview

The Policy Management feature provides a Policy as Code approach to security governance. Define your security requirements in YAML or JSON, and CybeDefend will automatically evaluate every scan against your policies.

Hierarchical Policies

Organization → Team → Project hierarchy ensures policies cascade appropriately

Policy as Code

Version-controlled YAML/JSON policies that integrate with your GitOps workflow

Async Evaluation

Non-blocking BullMQ-based worker for fast policy evaluation

Compliance Tracking

Full audit trail and compliance history for governance reporting

Key Features

Policy Hierarchy

Policies are applied in a hierarchical manner, ensuring organizational standards cannot be bypassed:

Organization Policy (highest priority)
    ↓
Team Policy
    ↓
Project Policy (lowest priority)

A policy at a higher level cannot be disabled by a policy at a lower level. Lower-level policies can only add stricter rules.

Automatic Vulnerability Filtering

During policy evaluation, certain vulnerabilities are automatically ignored to focus on active security risks:

Status	Description
`resolved` / `fixed`	Already fixed in the source code
`ignored` / `accepted_risk`	Risks that have been formally accepted by the organization

Policy Configuration

Policies are defined in YAML format with complete metadata. Here’s a full example:

version: '1.0'
name: 'Production Security Policy'
description: 'Strict security policy for production deployments'
scope: PROJECT  # ORGANIZATION | TEAM | PROJECT
priority: 10    # 1-100 (lower = higher priority)
enabled: true

# For PROJECT scope - specify target projects
projectIds:
  - 550e8400-e29b-41d4-a716-446655440001

rules:
  - name: 'Block critical vulnerabilities'
    type: severity
    operator: eq
    value: CRITICAL
    action: block

  - name: 'Warn on high vulnerabilities'
    type: severity
    operator: eq
    value: HIGH
    action: warn

  - name: 'Block high CVSS scores'
    type: cvss_score
    operator: gt
    value: 9.0
    action: block

# Optional exclusions (max 30)
exclusions:
  - pattern: 'test/**'
    reason: 'Test files are not deployed to production'
  
  - pattern: '**/vendor/**'
    reason: 'Third-party code - tracked separately'
    expirationDate: '2026-06-30T00:00:00Z'

Policies require 1-15 rules and support a maximum of 30 exclusions.

Rule Types

Type	Description	Valid Values
`severity`	Vulnerability severity level	`critical`, `high`, `medium`, `low`, `info`
`cvss_score`	CVSS score (0-10)	Numeric value (e.g., `7.5`, `9.0`)
`cwe_check`	CWE identifier	String (e.g., `CWE-89`, `CWE-79`)
`owasp_category`	OWASP Top 10 category	String (e.g., `A01:2021`, `A03:2021`)
`scanner_type`	Type of scanner	`sast`, `secret`, `sca`, `container`, `iac`, `cicd`
`vulnerability_age_days`	Days since detection	Numeric value
`is_new_vulnerability`	Whether vulnerability is new	Boolean (`true`/`false`)
`branch`	Git branch name (supports glob)	String (e.g., `main`, `feature/*`)
`composite_and`	Combine rules with AND logic	Array of sub-rules
`composite_or`	Combine rules with OR logic	Array of sub-rules

Operators

Operator	Description	Example
`eq`	Equals (exact match)	`severity eq critical`
`neq`	Not equals	`severity neq info`
`gt`	Greater than	`cvss_score gt 7.0`
`lt`	Less than	`vulnerability_age_days lt 30`
`gte`	Greater than or equal	`cvss_score gte 9.0`
`lte`	Less than or equal	`vulnerability_age_days lte 7`
`in`	In list	`severity in [critical, high]`
`not_in`	Not in list	`cwe_check not_in [CWE-1, CWE-2]`

Actions

Action	Description	CI/CD Exit Code
`block`	Blocks the pipeline, creates violation record	`1`
`warn`	Creates violation record, doesn’t block	`0`

Composite Rules

Use composite rules to combine multiple conditions:

AND Logic (All conditions must match)

- name: 'Block Critical on Main Branch'
  type: composite_and
  action: block
  criteria:
    - type: severity
      operator: eq
      value: CRITICAL
    - type: branch
      operator: eq
      value: main

OR Logic (Any condition can match)

- name: 'Block dangerous patterns'
  type: composite_or
  action: block
  criteria:
    - type: cvss_score
      operator: gt
      value: 9.0
    - type: cwe_check
      operator: in
      value: ['CWE-89', 'CWE-78', 'CWE-94']

Exclusions

Exclusions allow you to skip policy evaluation for specific files or patterns:

exclusions:
  - pattern: 'test/**'
    reason: 'Test files are not deployed'  # Required

  - pattern: '**/node_modules/**'
    reason: 'Dependencies tracked via SCA'
    expirationDate: '2026-12-31T00:00:00Z'  # Optional expiration

Pattern matching uses glob patterns:

** matches any number of directories
* matches any characters except /
? matches a single character

Always set expiration dates on exclusions to prevent permanent security gaps.

Policy Examples

Branch-Based Policy (Production Protection)

version: '1.0'
name: 'Production Branch Policy'
description: 'Strict policy for production branches'
scope: PROJECT
priority: 5
enabled: true
projectIds:
  - 550e8400-e29b-41d4-a716-446655440001

rules:
  # Block ALL high/critical on main and release branches
  - name: 'Block critical on production branches'
    type: composite_and
    action: block
    criteria:
      - type: branch
        operator: in
        value: ['main', 'master', 'release-*', 'release/*']
      - type: severity
        operator: in
        value: [CRITICAL, HIGH]

  # Only warn on feature branches
  - name: 'Warn on feature branches'
    type: composite_and
    action: warn
    criteria:
      - type: branch
        operator: in
        value: ['feature/*', 'feat/*', 'develop']
      - type: severity
        operator: eq
        value: CRITICAL

  # Block secrets on any branch
  - name: 'Always block exposed secrets'
    type: composite_and
    action: block
    criteria:
      - type: scanner_type
        operator: eq
        value: SECRET
      - type: severity
        operator: in
        value: [CRITICAL, HIGH]

Multi-Scanner Organization Policy

version: '1.0'
name: 'Organization Security Policy'
description: 'Enterprise-wide policy for all scanners'
scope: ORGANIZATION
priority: 1
enabled: true

rules:
  # SAST Rules
  - name: 'SAST - Block critical vulnerabilities'
    type: composite_and
    action: block
    criteria:
      - type: scanner_type
        operator: eq
        value: sast
      - type: severity
        operator: eq
        value: CRITICAL

  # Secret Detection
  - name: 'Secrets - Block exposed secrets'
    type: composite_and
    action: block
    criteria:
      - type: scanner_type
        operator: eq
        value: secret
      - type: severity
        operator: in
        value: ['CRITICAL', 'HIGH']

  # Container Scanning
  - name: 'Container - Block high CVSS'
    type: composite_and
    action: block
    criteria:
      - type: scanner_type
        operator: eq
        value: container
      - type: cvss_score
        operator: gt
        value: 8.0

  # OWASP Categories
  - name: 'OWASP A01 - Broken Access Control'
    type: owasp_category
    operator: eq
    value: 'A01:2021'
    action: block

exclusions:
  - pattern: 'test/**'
    reason: 'Test files'
  - pattern: 'docs/**'
    reason: 'Documentation'

CI/CD Integration

GitHub Actions

Use the official CybeDefend GitHub Action with policy evaluation enabled:

name: CybeDefend Security Scan with Policy Enforcement

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Run CybeDefend Security Scan
        uses: CybeDefend/cybedefend-action@v1
        with:
          token: ${{ secrets.CYBEDEFEND_PAT }}
          project_id: ${{ secrets.CYBEDEFEND_PROJECT_ID }}
          branch: ${{ github.head_ref || github.ref_name }}
          # Policy evaluation options
          policy_check: true
          policy_timeout: 300
          show_policy_vulns: true
          show_all_policy_vulns: false

Policy Evaluation Options

Option	Default	Description
`policy_check`	`true`	Enable/disable policy evaluation after scan
`policy_timeout`	`300`	Timeout in seconds for policy evaluation
`show_policy_vulns`	`true`	Show affected vulnerabilities in output
`show_all_policy_vulns`	`false`	Show all vulnerabilities (no limit)

GitLab CI

Use the CybeDefend CLI directly with policy evaluation:

stages:
  - security

cybedefend-scan:
  stage: security
  image: ghcr.io/cybedefend/cybedefend-cli:v1.0.9
  variables:
    CYBEDEFEND_PAT: $CYBEDEFEND_PAT
    CYBEDEFEND_PROJECT_ID: $CYBEDEFEND_PROJECT_ID
  script:
    # Run scan with policy evaluation (enabled by default)
    - cybedefend scan --dir . --branch $CI_COMMIT_REF_NAME --ci
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

CLI Policy Flags

Flag	Default	Description
`--policy-check`	`true`	Enable/disable policy evaluation
`--policy-timeout`	`300`	Timeout in seconds for evaluation
`--show-policy-vulns`	`true`	Show affected vulnerabilities
`--show-all-policy-vulns`	`false`	Show all vulnerabilities without limit

Example Output

✓ Scan completed successfully
ℹ Checking policy evaluation status...
✓ Policy evaluation completed
ℹ Policy violations found: 2 BLOCK, 1 WARN

⛔ BLOCK Actions:
  ✗ No Critical Vulnerabilities (BLOCK)
    Affected: 3 vulnerabilities
      → [CRITICAL] SQL Injection - src/api/users.ts (L45-48)
        https://us.cybedefend.com/project/xxx/sast/issue/yyy
      → [CRITICAL] Path Traversal - src/utils/file.ts (L12)
        https://us.cybedefend.com/project/xxx/sast/issue/zzz

⚠️ WARN Actions:
  ⚠ Dependency Check (WARN)
    Affected: 1 vulnerability
      → [HIGH] Prototype Pollution - lodash@4.17.15
        https://us.cybedefend.com/project/xxx/sca/issue/aaa

✓ Acknowledged Violations (not blocking):
  ⚠ No High Vulnerabilities (BLOCK)
    ✓ Acknowledged: Risk accepted for legacy code

If any policy has a BLOCK action with violations, the CLI exits with code 1, failing the pipeline. WARN actions are informational only and don’t affect the exit code.

Managing Violations

When a policy violation occurs, you have two options to resolve it:

Change Vulnerability Status

Change the vulnerability status from “open” to “ignored” with a justification. The vulnerability will be excluded from future policy evaluations.

Fix the Vulnerability

Resolve the security issue directly in your source code and re-run the scan. The vulnerability will be marked as “resolved” and excluded from policy evaluations.

Both approaches create an audit trail. Changing status to “ignored” requires a comment explaining the risk acceptance decision.

Best Practices

Start with Warning-Only Mode

When rolling out policies, start with action: warn to understand the impact before switching to action: block.

Use Expiring Exclusions

Always set expiration dates on exclusions to prevent permanent security gaps:

exclusions:
  - pattern: 'src/legacy/**'
    reason: 'Technical debt - scheduled for Q2 refactor'
    expirationDate: '2026-06-30T00:00:00Z'

Layer Policies Appropriately

Organization level: Global security requirements (e.g., no exposed secrets)
Team level: Team-specific standards (e.g., frontend vs backend rules)
Project level: Project-specific exclusions only

Version Control Your Policies

Store policy YAML files in your repository:

repo/
├── .cybedefend/
│   ├── policies/
│   │   ├── sast-policy.yaml
│   │   ├── sca-policy.yaml
│   │   └── secret-policy.yaml
│   └── README.md

CybeDefend

Platform Overview

Getting Started

Agent & AI Integration

IDE Integrations

Code Scanning

Container Scanning

Managing Vulnerabilities

Issue Tracker Integrations

Notifications

Overview

Hierarchical Policies

Policy as Code

Async Evaluation

Compliance Tracking

Key Features

Policy Hierarchy

Automatic Vulnerability Filtering

Policy Configuration

Rule Types

Operators

Actions

Composite Rules

AND Logic (All conditions must match)

OR Logic (Any condition can match)

Exclusions

Policy Examples

Branch-Based Policy (Production Protection)

Multi-Scanner Organization Policy

CI/CD Integration

GitHub Actions

Policy Evaluation Options

GitLab CI

CLI Policy Flags

Example Output

Managing Violations

Best Practices

​Overview

Hierarchical Policies

Policy as Code

Async Evaluation

Compliance Tracking

​Key Features

​Policy Hierarchy

​Automatic Vulnerability Filtering

​Policy Configuration

​Rule Types

​Operators

​Actions

​Composite Rules

​AND Logic (All conditions must match)

​OR Logic (Any condition can match)

​Exclusions

​Policy Examples

​Branch-Based Policy (Production Protection)

​Multi-Scanner Organization Policy

​CI/CD Integration

​GitHub Actions

​Policy Evaluation Options

​GitLab CI

​CLI Policy Flags

​Example Output

​Managing Violations

​Best Practices

Overview

Key Features

Policy Hierarchy

Automatic Vulnerability Filtering

Policy Configuration

Rule Types

Operators

Actions

Composite Rules

AND Logic (All conditions must match)

OR Logic (Any condition can match)

Exclusions

Policy Examples

Branch-Based Policy (Production Protection)

Multi-Scanner Organization Policy

CI/CD Integration

GitHub Actions

Policy Evaluation Options

GitLab CI

CLI Policy Flags

Example Output

Managing Violations

Best Practices