Configuration Examples

This page provides real-world configuration examples demonstrating Codeward's key features.

Understanding Rule Logic

Before diving into examples, remember: rules define what to search for, not requirements.

• { "field": "Severity", "type": "eq", "value": "CRITICAL" } searches for CRITICAL vulnerabilities
• When a match is found → creates a finding → triggers action
• All operators report when the condition is true:
  • eq reports when value equals target
  • gt reports when value is greater than target
  • not_exists reports when key does not exist
  • contains reports when value contains substring

See Policies for detailed explanation.

Complete Configuration Example

A comprehensive example showing all major features:

{
  "global": {
    "dependency_tree": true,
    "mode": "diff",
    "logging": {
      "level": "info",
      "format": "text",
      "show_timestamp": false,
      "summary": "standard"
    },
    "ignore": [
      {
        "name": "Ignore test directories",
        "description": "Skip all findings from test code",
        "paths": ["test/**", "**/test/**", "**/*_test.go", "**/*.test.js"]
      },
      {
        "name": "Ignore vendor dependencies",
        "description": "Skip findings from vendored code",
        "paths": ["vendor/**", "**/node_modules/**"]
      }
    ]
  },
  "vulnerability": [
    {
      "name": "block-critical-new",
      "actions": {"new": "block", "existing": "warn"},
      "rules": [
        {"field": "Severity", "type": "eq", "value": "CRITICAL"}
      ],
      "ignores": [
        {
          "name": "Accepted risk - CVE-2024-0001",
          "description": "Only affects Windows, we run Linux only",
          "author": "[email protected]",
          "operator": "AND",
          "rules": [
            {"field": "VulnerabilityID", "type": "eq", "value": "CVE-2024-0001"},
            {"field": "PkgName", "type": "eq", "value": "openssl"}
          ]
        }
      ],
      "outputs": [
        {
          "format": "markdown",
          "destination": "git:pr",
          "fields": ["VulnerabilityID", "PkgName", "Severity", "FixedVersion"],
          "changes": ["new"]
        }
      ]
    }
  ],
  "license": [
    {
      "name": "block-copyleft",
      "actions": {"new": "block"},
      "rules": [
        {"field": "Category", "type": "eq", "value": "Copyleft"}
      ],
      "outputs": [
        {
          "format": "markdown",
          "destination": "git:pr",
          "fields": ["Name", "Category", "PkgName"],
          "changes": ["new"]
        }
      ]
    }
  ]
}

Ignore Rules Examples

Global Ignore: Test Directories

Ignore all findings from test-related code:

{
  "global": {
    "ignore": [
      {
        "name": "Ignore test directories",
        "description": "Test code is not deployed to production",
        "paths": [
          "test/**",
          "**/test/**",
          "**/*_test.go",
          "**/*.test.js",
          "**/*.spec.ts",
          "**/tests/**"
        ]
      }
    ]
  }
}

Global Ignore: Vendor Dependencies

Ignore findings from third-party vendored code:

{
  "global": {
    "ignore": [
      {
        "name": "Ignore vendor dependencies",
        "description": "Vendored dependencies managed separately",
        "paths": [
          "vendor/**",
          "**/node_modules/**",
          "**/venv/**",
          "**/.bundle/**"
        ]
      }
    ]
  }
}

Global Ignore: Specific CVEs

Ignore known false positives across all files:

{
  "global": {
    "ignore": [
      {
        "name": "Known false positives",
        "description": "CVEs that don't apply to our environment",
        "targets": [
          "CVE-2023-1234",
          "CVE-2023-5678",
          "CVE-2024-0001"
        ]
      }
    ]
  }
}

Global Ignore: CVEs in Specific Path

Ignore specific CVEs only in vendored code:

{
  "global": {
    "ignore": [
      {
        "name": "Vendor-specific false positives",
        "description": "These CVEs only affect vendor code we don't use",
        "paths": ["vendor/**"],
        "targets": ["CVE-2024-0001", "CVE-2024-0002"]
      }
    ]
  }
}

Policy-Level Ignore: Specific Vulnerability in Package

Ignore a specific CVE in a specific package (precise control):

{
  "vulnerability": [{
    "name": "Critical vulnerabilities",
    "actions": {"new": "block"},
    "rules": [
      {"field": "Severity", "type": "eq", "value": "CRITICAL"}
    ],
    "ignores": [
      {
        "name": "Windows-only CVE in openssl",
        "description": "CVE-2024-0001 only affects Windows, we run Linux",
        "author": "[email protected]",
        "operator": "AND",
        "rules": [
          {"field": "VulnerabilityID", "type": "eq", "value": "CVE-2024-0001"},
          {"field": "PkgName", "type": "eq", "value": "openssl"}
        ]
      }
    ],
    "outputs": [...]
  }]
}

Policy-Level Ignore: Test Dependencies

Ignore vulnerabilities in test-only packages:

{
  "vulnerability": [{
    "name": "Production vulnerabilities",
    "actions": {"new": "block"},
    "rules": [
      {"field": "Severity", "type": "eq", "value": "HIGH"}
    ],
    "ignores": [
      {
        "name": "Test dependencies",
        "description": "Test packages are not deployed",
        "author": "[email protected]",
        "operator": "OR",
        "rules": [
          {"field": "PkgName", "type": "contains", "value": "-test"},
          {"field": "PkgName", "type": "contains", "value": "-mock"},
          {"field": "PkgName", "type": "hasSuffix", "value": "-dev"}
        ]
      }
    ],
    "outputs": [...]
  }]
}

Policy-Level Ignore: Multiple CVEs

Ignore multiple CVEs in a policy (OR logic):

{
  "vulnerability": [{
    "name": "High severity vulnerabilities",
    "actions": {"new": "warn"},
    "rules": [
      {"field": "Severity", "type": "eq", "value": "HIGH"}
    ],
    "ignores": [
      {
        "name": "False positives",
        "description": "Known false positives from security audit",
        "author": "[email protected]",
        "operator": "OR",
        "rules": [
          {"field": "VulnerabilityID", "type": "eq", "value": "CVE-2023-1111"},
          {"field": "VulnerabilityID", "type": "eq", "value": "CVE-2023-2222"},
          {"field": "VulnerabilityID", "type": "eq", "value": "CVE-2023-3333"}
        ]
      }
    ],
    "outputs": [...]
  }]
}

Environment Variables Examples

Basic Environment Setup

# Core configuration
export CODEWARD_GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export CODEWARD_GITHUB_REPOSITORY="my-app"
export CODEWARD_GITHUB_OWNER="my-org"

# Run scan
codeward-scan

CI/CD Environment

# GitHub Actions
export CODEWARD_MODE="diff"
export CODEWARD_GITHUB_TOKEN="${{ secrets.GITHUB_TOKEN }}"
export CODEWARD_GITHUB_PR_NUMBER="${{ github.event.number }}"
export CODEWARD_GITHUB_REPOSITORY="${{ github.event.repository.name }}"
export CODEWARD_GITHUB_OWNER="${{ github.repository_owner }}"

# Run with detailed logging
export CODEWARD_LOG_LEVEL="debug"
export CODEWARD_LOG_SUMMARY="detailed"
codeward-scan

Config File Override

Use config file for non-sensitive variables:

{
  "global": {
    "mode": "diff",
    "repo": {
      "github_repository": "my-staging-app"
    },
    "api": {
      "codeward_api": "https://staging.api.codeward.io"
    }
  }
}

# Tokens still from environment (sensitive)
export CODEWARD_GITHUB_TOKEN="ghp_xxxx"

# Config file provides non-sensitive overrides
codeward-scan

Environment Precedence Example

{
  "global": {
    "repo": {
      "github_repository": "repo-from-config"
    },
    "logging": {
      "level": "info"
    }
  }
}

# Environment variables override config file
export CODEWARD_GITHUB_REPOSITORY="repo-from-env"  # This wins
export CODEWARD_LOG_LEVEL="debug"  # This wins

# Result: Uses "repo-from-env" and "debug" level
codeward-scan

Logging Examples

Development Configuration

{
  "global": {
    "logging": {
      "level": "debug",
      "format": "text",
      "show_timestamp": true,
      "summary": "detailed"
    }
  }
}

Production Configuration

{
  "global": {
    "logging": {
      "level": "info",
      "format": "json",
      "show_timestamp": true,
      "summary": "standard"
    }
  }
}

Silent Mode

# Suppress all logs (only see scan results)
CODEWARD_LOG_LEVEL=silent codeward-scan

Debug with JSON Output

# Debug logging with structured JSON
CODEWARD_LOG_LEVEL=debug CODEWARD_LOG_FORMAT=json codeward-scan

Minimal Summary

# Minimal summary for quick scans
CODEWARD_LOG_SUMMARY=minimal codeward-scan

Detailed Summary

# Detailed summary with all information
CODEWARD_LOG_SUMMARY=detailed codeward-scan

Combined Patterns

Progressive Enforcement

Start with observation, gradually increase strictness:

Phase 1: Observe

{
  "vulnerability": [{
    "name": "observe-critical",
    "actions": {"new": "info", "existing": "info"},
    "rules": [{"field": "Severity", "type": "eq", "value": "CRITICAL"}],
    "outputs": [...]
  }]
}

Phase 2: Warn

{
  "vulnerability": [{
    "name": "warn-critical",
    "actions": {"new": "warn", "existing": "info"},
    "rules": [{"field": "Severity", "type": "eq", "value": "CRITICAL"}],
    "outputs": [...]
  }]
}

Phase 3: Block

{
  "vulnerability": [{
    "name": "block-critical",
    "actions": {"new": "block", "existing": "warn"},
    "rules": [{"field": "Severity", "type": "eq", "value": "CRITICAL"}],
    "outputs": [...]
  }]
}

Multi-Severity Policy

Different actions for different severity levels:

{
  "vulnerability": [
    {
      "name": "block-critical",
      "actions": {"new": "block", "existing": "warn"},
      "rules": [{"field": "Severity", "type": "eq", "value": "CRITICAL"}],
      "outputs": [...]
    },
    {
      "name": "warn-high",
      "actions": {"new": "warn", "existing": "info"},
      "rules": [{"field": "Severity", "type": "eq", "value": "HIGH"}],
      "outputs": [...]
    },
    {
      "name": "info-medium",
      "actions": {"new": "info"},
      "rules": [{"field": "Severity", "type": "eq", "value": "MEDIUM"}],
      "outputs": [...]
    }
  ]
}

Environment-Specific Configuration

Development (.codeward.dev.json)

{
  "global": {
    "logging": {"level": "debug", "summary": "detailed"},
    "ignore": [
      {"name": "Dev only", "paths": ["scripts/**"]}
    ]
  },
  "vulnerability": [{
    "actions": {"new": "warn"},
    "rules": [],
    "outputs": [...]
  }]
}

Production (.codeward.json)

{
  "global": {
    "logging": {"level": "info", "summary": "standard"},
    "ignore": [
      {"name": "Test dirs", "paths": ["test/**"]}
    ]
  },
  "vulnerability": [{
    "actions": {"new": "block"},
    "rules": [{"field": "Severity", "type": "eq", "value": "CRITICAL"}],
    "outputs": [...]
  }]
}

# Use different configs per environment
CODEWARD_CONFIG_PATH=".codeward.dev.json" codeward-scan  # Development
CODEWARD_CONFIG_PATH=".codeward.json" codeward-scan      # Production

Ignore Everything Except Production Code

Comprehensive ignore strategy:

{
  "global": {
    "ignore": [
      {
        "name": "Non-production code",
        "description": "Only scan production code paths",
        "paths": [
          "test/**",
          "**/test/**",
          "**/*_test.*",
          "**/*.test.*",
          "**/*.spec.*",
          "vendor/**",
          "**/node_modules/**",
          "docs/**",
          "examples/**",
          "scripts/**",
          "tools/**",
          "**/testdata/**"
        ]
      }
    ]
  }
}

Advanced Examples

Monorepo Configuration

Different policies for different services:

{
  "vulnerability": [
    {
      "name": "frontend-critical",
      "actions": {"new": "block"},
      "rules": [
        {"field": "Severity", "type": "eq", "value": "CRITICAL"},
        {"field": "Sources", "type": "contains", "value": "services/frontend"}
      ],
      "outputs": [...]
    },
    {
      "name": "backend-high",
      "actions": {"new": "block"},
      "rules": [
        {"field": "Severity", "type": "eq", "value": "HIGH"},
        {"field": "Sources", "type": "contains", "value": "services/backend"}
      ],
      "outputs": [...]
    }
  ]
}

Audit Mode

Log everything without blocking:

{
  "global": {
    "logging": {
      "level": "info",
      "format": "json",
      "summary": "detailed"
    }
  },
  "vulnerability": [{
    "name": "audit-all",
    "actions": {"new": "info", "existing": "info", "changed": "info", "removed": "info"},
    "rules": [],
    "outputs": [
      {
        "format": "json",
        "destination": "file:audit-report.json",
        "fields": ["VulnerabilityID", "PkgName", "Severity", "FixedVersion", "Sources"],
        "changes": ["new", "existing", "changed", "removed"]
      }
    ]
  }]
}

Compliance Mode

Strict blocking with full documentation:

{
  "global": {
    "dependency_tree": true,
    "logging": {"summary": "detailed"}
  },
  "vulnerability": [{
    "name": "compliance-critical-high",
    "actions": {"new": "block", "existing": "block"},
    "rules": [
      {"field": "Severity", "type": "eq", "value": "CRITICAL"},
      {"field": "Severity", "type": "eq", "value": "HIGH"}
    ],
    "ignores": [
      {
        "name": "Approved exception",
        "description": "Security team approved exception with compensating controls",
        "author": "[email protected]",
        "operator": "AND",
        "rules": [
          {"field": "VulnerabilityID", "type": "eq", "value": "CVE-2024-XXXX"},
          {"field": "PkgName", "type": "eq", "value": "approved-package"}
        ]
      }
    ],
    "outputs": [
      {
        "format": "markdown",
        "destination": "git:pr",
        "fields": ["VulnerabilityID", "PkgName", "Severity", "FixedVersion", "Description"],
        "changes": ["new", "existing"]
      },
      {
        "format": "json",
        "destination": "file:compliance-report.json",
        "changes": ["new", "existing"]
      }
    ]
  }],
  "license": [{
    "name": "compliance-copyleft",
    "actions": {"new": "block"},
    "rules": [
      {"field": "Category", "type": "eq", "value": "Copyleft"}
    ],
    "outputs": [...]
  }]
}

See Also

• Configuration Reference - Complete config documentation
• Policies - Policy types and rules
• Outputs - Output formats and destinations
• Quick Start - Getting started guide