Custom Rules

Ward allows you to write custom security rules in YAML format. Drop .yaml files into ~/.ward/rules/ and Ward automatically loads them on the next scan.

Quick Start

Custom rules are automatically loaded from:

~/.ward/rules/ — Your personal rules directory (created by ward init)
Additional directories — Configured via rules.custom_dirs in config.yaml

All .yaml and .yml files in these directories are loaded and merged with the built-in rules.

Rule File Structure

Each rule file contains a rules array with one or more rule definitions:

rules:
  - id: TEAM-001
    title: "Hardcoded internal service URL"
    description: "Detects hardcoded URLs to internal services."
    severity: medium
    category: Configuration
    enabled: true
    patterns:
      - type: regex
        target: php-files
        pattern: 'https?://internal-service\.\w+'
    remediation: |
      Use environment variables:
        $url = env('INTERNAL_SERVICE_URL');
    references:
      - https://laravel.com/docs/configuration#environment-variables

Rule Definition Fields

Required Fields

string

required

Unique identifier for the rule. Must be unique across all loaded rules.Naming convention: Use a prefix like TEAM-, CUSTOM-, or your organization code.Example: TEAM-001, ACME-SEC-042

title

string

required

Short, descriptive title for the finding. Displayed in reports and TUI.Example: "Hardcoded database credentials"

description

string

required

Detailed explanation of what the rule detects and why it’s a security concern.Example:

description: |
  Database credentials should never be hardcoded in source files.
  Use environment variables via the .env file instead.

severity

string

required

Severity level for findings from this rule.Valid values: critical, high, medium, low, infoExample: severity: high

Optional Fields

remediation

string

Guidance on how to fix the finding. Supports multi-line text.Example:

remediation: |
  Replace hardcoded credentials with environment variables:
    $password = env('DB_PASSWORD');
  
  Add the real password to your .env file:
    DB_PASSWORD=your-secure-password

references

array

List of URLs for additional documentation or context.Example:

references:
  - https://laravel.com/docs/configuration
  - https://owasp.org/www-community/vulnerabilities/Hardcoded_Password

Pattern Types

Each pattern in the patterns array must specify a type, target, and pattern.

Regex Pattern

Matches a regular expression against file contents line-by-line.

patterns:
  - type: regex
    target: php-files
    pattern: '\$password\s*=\s*["\']\w+["\']'

Regex patterns use Go’s RE2 syntax. Backslashes must be escaped in YAML strings (\\ for literal backslash).

Contains Pattern

Matches an exact substring in file contents.

patterns:
  - type: contains
    target: blade-files
    pattern: '{!! $userInput !!}'

File-Exists Pattern

Checks whether a file matching the glob pattern exists.

patterns:
  - type: file-exists
    target: .env.production
    pattern: ''

Pattern Targets

The target field specifies which files to search.

Built-in Targets

Target	Files Matched
`php-files`	All `.php` files (recursive, skips `vendor/`)
`blade-files`	`resources/views/*/.blade.php`
`config-files`	`config/*.php`
`env-files`	`.env`, `.env.*`
`routes-files`	`routes/*.php`
`migration-files`	`database/migrations/*.php`
`js-files`	`resources/js/*/.{js,ts,jsx,tsx}`

Custom Glob Patterns

You can also use any custom glob pattern as a target:

patterns:
  - type: regex
    target: 'app/Services/**/*.php'
    pattern: 'curl_exec\('

Advanced Pattern Options

Negative Patterns

Set negative: true to trigger when a pattern is absent. Useful for “must have X” checks.

rules:
  - id: CUSTOM-001
    title: "Missing CSRF directive in form"
    description: "Blade forms must include @csrf directive."
    severity: high
    category: Configuration
    enabled: true
    patterns:
      - type: contains
        target: blade-files
        pattern: '<form'
      - type: contains
        target: blade-files
        pattern: '@csrf'
        negative: true  # fire if @csrf is NOT found
    remediation: |
      Add @csrf inside every Blade form:
        <form method="POST" action="/profile">
            @csrf
            ...
        </form>

Exclude Pattern

Use exclude_pattern to skip matches that also match a secondary pattern. Reduces false positives.

patterns:
  - type: regex
    target: php-files
    pattern: 'DB::raw\('
    exclude_pattern: '// safe: audited'  # skip lines with this comment

Custom Rule Example

Here’s a complete example from ~/.ward/rules/custom-example.yaml:

custom-example.yaml

rules:
  - id: MY-001
    title: "Example: Hardcoded internal URL"
    description: "Detects hardcoded internal URLs that should use configuration."
    severity: low
    category: Configuration
    enabled: false
    patterns:
      - type: regex
        target: php-files
        pattern: 'https?://localhost:\d{4}'
    remediation: |
      Replace hardcoded URLs with environment variables:
        $url = env('INTERNAL_SERVICE_URL');

  - id: MY-002
    title: "Example: Missing CSRF directive in Blade form"
    description: >
      A <form> tag in a Blade template does not include @csrf.
      This rule uses the 'negative' option — it triggers when @csrf is absent
      from a file that contains a <form> tag.
    severity: medium
    category: Configuration
    enabled: false
    patterns:
      - type: contains
        target: blade-files
        pattern: "<form"
      - type: contains
        target: blade-files
        pattern: "@csrf"
        negative: true
    remediation: |
      Add @csrf inside every Blade form:
        <form method="POST" action="/profile">
            @csrf
            ...
        </form>

Loading Custom Rule Directories

To load rules from additional directories (e.g., team-wide or project-specific rules), add them to your config.yaml:

config.yaml

rules:
  custom_dirs:
    - /path/to/team-rules
    - ./project-specific-rules

Ward will recursively load all .yaml and .yml files from these directories (internal/config/rules.go:54-82).

Rule Loading Process

Ward loads rules in the following order (internal/config/rules.go:86-113):

Built-in rules — Embedded in the binary from internal/config/defaults/rules/
User rules — From ~/.ward/rules/
Custom directories — From rules.custom_dirs in config.yaml
Overrides applied — rules.disable and rules.override from config.yaml

Testing Custom Rules

After creating a custom rule:

Save the .yaml file in ~/.ward/rules/
Run ward scan /path/to/test-project
Check the report for findings from your rule ID

Set enabled: false initially and test with a small project to verify pattern accuracy before enabling in production.

Common Use Cases

Detect Missing Authorization Checks

rules:
  - id: TEAM-AUTH-001
    title: "Controller method missing authorization"
    description: "Public controller methods should call $this->authorize()."
    severity: high
    category: Authorization
    enabled: true
    patterns:
      - type: regex
        target: 'app/Http/Controllers/**/*.php'
        pattern: 'public function (?!__construct)'
      - type: regex
        target: 'app/Http/Controllers/**/*.php'
        pattern: '\$this->authorize\('
        negative: true

Detect Unsafe File Uploads

rules:
  - id: TEAM-FILE-001
    title: "File upload without validation"
    description: "File uploads should validate MIME type and extension."
    severity: medium
    category: Security
    enabled: true
    patterns:
      - type: regex
        target: php-files
        pattern: '->store\(|->storeAs\('
      - type: regex
        target: php-files
        pattern: 'mimes:|mimetypes:'
        negative: true

Detect Hardcoded Team URLs

rules:
  - id: ACME-001
    title: "Hardcoded Acme Corp internal URL"
    description: "Use env('ACME_SERVICE_URL') instead."
    severity: low
    category: Configuration
    enabled: true
    patterns:
      - type: regex
        target: php-files
        pattern: 'https?://[a-z-]+\.acme\.internal'

Configuration File — Main config.yaml structure
Rule Overrides — Disabling and customizing rules
Rules Scanner — Default rules included with Ward

Get Started

Core Concepts

Command Reference

Configuration

Guides

Scanners

Custom Rules

Quick Start

Rule File Structure

Rule Definition Fields

Required Fields

Optional Fields

Pattern Types

Regex Pattern

Contains Pattern

File-Exists Pattern

Pattern Targets

Built-in Targets

Custom Glob Patterns

Advanced Pattern Options

Negative Patterns

Exclude Pattern

Custom Rule Example

Loading Custom Rule Directories

Rule Loading Process

Testing Custom Rules

Common Use Cases

Detect Missing Authorization Checks

Detect Unsafe File Uploads

Detect Hardcoded Team URLs

Build docs developers (and LLMs) love

Get Started

Core Concepts

Command Reference

Configuration

Guides

Scanners

Documentation Index

​Quick Start

​Rule File Structure

​Rule Definition Fields

​Required Fields

​Optional Fields

​Pattern Types

​Regex Pattern

​Contains Pattern

​File-Exists Pattern

​Pattern Targets

​Built-in Targets

​Custom Glob Patterns

​Advanced Pattern Options

​Negative Patterns

​Exclude Pattern

​Custom Rule Example

​Loading Custom Rule Directories

​Rule Loading Process

​Testing Custom Rules

​Common Use Cases

​Detect Missing Authorization Checks

​Detect Unsafe File Uploads

​Detect Hardcoded Team URLs

​Related Pages

Build docs developers (and LLMs) love

Quick Start

Rule File Structure

Rule Definition Fields

Required Fields

Optional Fields

Pattern Types

Regex Pattern

Contains Pattern

File-Exists Pattern

Pattern Targets

Built-in Targets

Custom Glob Patterns

Advanced Pattern Options

Negative Patterns

Exclude Pattern

Custom Rule Example

Loading Custom Rule Directories

Rule Loading Process

Testing Custom Rules

Common Use Cases

Detect Missing Authorization Checks

Detect Unsafe File Uploads

Detect Hardcoded Team URLs

Related Pages