Security Scanners

Scanner Overview

Ward includes 4 built-in scanner types that run independently during the Scanners stage of the pipeline. Each scanner focuses on a specific security domain:

env-scanner

Checks .env files for misconfigurations and leaked secrets

config-scanner

Analyzes config/*.php for hardcoded credentials and insecure settings

dependency-scanner

Live CVE lookup via OSV.dev for all Composer packages

rules-scanner

Pattern-based checks from YAML rules (40 default rules)

How Scanners Work

All scanners implement the same interface and follow a consistent pattern: Source: internal/models/scanner.go

type Scanner interface {
    Name() string
    Description() string
    Scan(ctx context.Context, project ProjectContext, emit func(Finding)) ([]Finding, error)
}

Scanner Execution

Receive shared context — Scanners get the ProjectContext built by resolvers
Perform checks — Each scanner runs its domain-specific security analysis
Emit findings — Real-time via callback for TUI updates
Return results — All findings as a slice
Independence — Scanners don’t depend on each other; if one fails, others continue

Scanners are stateless and independent. They could run in parallel (though currently sequential) because they only read from the shared immutable ProjectContext.

env-scanner

Source: internal/scanner/env/scanner.go

Description

Checks .env and .env.example files for security misconfigurations, weak credentials, and accidentally committed secrets.

Checks Performed (8 rules)

ENV-001: Missing .env file

Severity: InfoDetects when no .env file exists in the project root.Why it matters: While valid in containerized deployments, missing .env may indicate misconfiguration.Remediation:

cp .env.example .env
php artisan key:generate

ENV-002: APP_DEBUG is enabled

Severity: HighDetects APP_DEBUG=true in .env.Why it matters: Debug mode exposes stack traces, database queries, and environment variables to end users. Critical information disclosure in production.Code check:

if val, ok := envVars["APP_DEBUG"]; ok && strings.EqualFold(val, "true") {
    // Create finding
}

Remediation:

APP_DEBUG=false

ENV-003: Empty or missing APP_KEY

Severity: CriticalDetects when APP_KEY is missing or empty.Why it matters: Laravel uses APP_KEY to encrypt cookies, sessions, and passwords. Without it, all encrypted data is insecure.Remediation:

php artisan key:generate

ENV-004: Weak or default APP_KEY

Severity: CriticalDetects common weak keys like base64:AAAAAAA..., SomeRandomString, or keys shorter than 20 characters.Code check:

func isWeakKey(val string) bool {
    lower := strings.ToLower(val)
    if strings.HasPrefix(lower, "base64:aaaaaaa") {
        return true
    }
    if lower == "somerandomstring" {
        return true
    }
    if strings.HasPrefix(val, "base64:") && len(val) < 20 {
        return true
    }
    return false
}

ENV-005: Non-production APP_ENV

Severity: MediumDetects APP_ENV set to local, development, or dev.Why it matters: Non-production environments may skip optimizations and enable debugging features.Remediation:

APP_ENV=production

ENV-006: Empty database password

Severity: LowDetects DB_PASSWORD= (empty value).Why it matters: While valid for local development with trust authentication, it’s a risk in production.

ENV-007: File sessions in production

Severity: LowDetects SESSION_DRIVER=file when APP_ENV=production.Why it matters: File sessions don’t scale across multiple servers and are slower than Redis/Memcached.Remediation:

SESSION_DRIVER=redis

ENV-008: Real credentials in .env.example

Severity: MediumDetects non-placeholder values in .env.example for sensitive keys:

DB_PASSWORD
MAIL_PASSWORD
AWS_SECRET_ACCESS_KEY
REDIS_PASSWORD
PUSHER_APP_SECRET

Why it matters: .env.example is typically committed to version control. Real credentials here are exposed in Git history.Code check:

// Skip obvious placeholders
if lower == "null" || lower == "password" || lower == "changeme" {
    continue
}
// Flag values longer than 6 chars that don't look like placeholders
if len(val) > 6 {
    // Create finding
}

Implementation Details

File parsing:

func readEnvFile(path string) (map[string]string, error) {
    // Read line by line
    // Skip comments and empty lines
    // Parse KEY=VALUE pairs
    // Strip quotes from values
}

Line number tracking:

func findLine(path, key string) int {
    // Re-read file to find exact line number
    // Enables code navigation in IDEs via SARIF
}

config-scanner

Source: internal/scanner/configscan/scanner.go

Description

Analyzes all config/*.php files for hardcoded credentials, insecure defaults, and missing security flags.

Files Analyzed

config/app.php          # Debug mode, encryption cipher
config/auth.php         # Password reset token expiry
config/session.php      # Cookie flags (HttpOnly, Secure, SameSite)
config/mail.php         # Hardcoded mail credentials
config/cors.php         # CORS wildcard origins
config/database.php     # Hardcoded DB credentials
config/broadcasting.php # Hardcoded Pusher keys
config/logging.php      # Hardcoded Slack webhooks

Checks Performed (13 rules)

CFG-001: Debug mode hardcoded to true

Severity: HighFile: config/app.phpPattern: 'debug' => trueWhy it matters: Bypasses the .env setting, forcing debug mode even in production.Remediation:

'debug' => env('APP_DEBUG', false),

CFG-002: Non-standard encryption cipher

Severity: MediumFile: config/app.phpPattern: 'cipher' => '(?!AES-256-CBC)...'Remediation:

'cipher' => 'AES-256-CBC',

CFG-003: Password reset token expiry too long

Severity: LowFile: config/auth.phpPattern: 'expire' => \d{3,} (≥100 minutes)Remediation:

'expire' => 60, // 60 minutes

CFG-004: Session cookie missing HttpOnly flag

CFG-005: Session cookie missing Secure flag

Severity: MediumFile: config/session.phpPattern: 'secure' => falseWhy it matters: Cookies are sent over HTTP, allowing session hijacking via network sniffing.Remediation:

'secure' => env('SESSION_SECURE_COOKIE', true),

CFG-006: Session cookie SameSite set to none

Severity: MediumFile: config/session.phpPattern: 'same_site' => 'none'Why it matters: Weakens CSRF protection by allowing cross-site cookie transmission.Remediation:

'same_site' => 'lax', // or 'strict'

CFG-007: Session lifetime excessively long

Severity: LowFile: config/session.phpPattern: 'lifetime' => \d{4,} (≥1000 minutes)

CFG-008: Mail password hardcoded

Severity: HighFile: config/mail.phpPattern: 'password' => '[^']{4,}' (not using env())Code check:

if line, n := findPattern(lines, `'password'\s*=>\s*'[^']{4,}'`); n > 0 {
    if !strings.Contains(line, "env(") {
        // Create finding
    }
}

CFG-009: CORS allows all origins

Severity: MediumFile: config/cors.phpPattern: 'allowed_origins' => ['*']Remediation:

'allowed_origins' => [env('FRONTEND_URL')],

CFG-010: CORS credentials with wildcard origin

Severity: HighFile: config/cors.phpWhy it matters: Combining supports_credentials => true with wildcard origins allows any website to make authenticated requests to your API.Remediation: Never use wildcard origins with credentials enabled.

CFG-011: Database password hardcoded

Severity: HighFile: config/database.phpPattern: 'password' => '[^']{4,}' (not using env())

CFG-012: Broadcasting secret/key hardcoded

Severity: MediumFile: config/broadcasting.phpPattern: '(secret|key)' => '[a-zA-Z0-9]{10,}' (not using env())

CFG-013: Slack webhook URL hardcoded

Severity: MediumFile: config/logging.phpPattern: hooks.slack.com/services (not using env())

Implementation Details

Pattern matching:

func findPattern(lines []string, pattern string) (string, int) {
    re := regexp.Compile(pattern)
    for i, line := range lines {
        if re.MatchString(line) {
            return strings.TrimSpace(line), i + 1
        }
    }
    return "", 0
}

Value masking:

func maskConfigValue(line string) string {
    // Replace 'password' => 'secret123' with 'password' => 'se****23'
    re := regexp.MustCompile(`=> '([^']{4,})'`)
    return re.ReplaceAllStringFunc(line, func(match string) string {
        val := extract(match)
        return "=> '" + val[:2] + "****" + val[len(val)-2:] + "'"
    })
}

dependency-scanner

Source: internal/scanner/dependency/scanner.go

Description

Performs live CVE database lookups via OSV.dev for all packages in composer.lock. This scanner requires network access.

How It Works

Read composer.lock

Extract all installed packages with exact versions from the ProjectContext.InstalledPackages map (populated by the Package Resolver).

Batch query OSV.dev

Send packages to OSV.dev’s batch endpoint in groups of 100:

const batchSize = 100
const osvBatchURL = "https://api.osv.dev/v1/querybatch"

for i := 0; i < len(allQueries); i += batchSize {
    batch := allQueries[i:i+batchSize]
    // POST to OSV.dev
}

Request format:

{
  "queries": [
    {
      "package": {"name": "symfony/http-kernel", "ecosystem": "Packagist"},
      "version": "6.4.2"
    }
  ]
}

Identify vulnerable packages

OSV.dev returns which packages have known vulnerabilities. Ward extracts these for detailed queries.

Fetch full vulnerability details

For each affected package, query the full vulnerability data:

vulns, err := s.queryPackage(ctx, packageName, version)

Response includes:

CVE ID and aliases
Severity (Critical, High, Medium, Low)
Affected version ranges
Fixed version
Advisory URLs

Generate findings

Convert each vulnerability to a Ward finding with:

CVE ID as the finding ID
Severity mapping from OSV data
Remediation with upgrade command
Reference links to advisories

Finding Format

Example finding:

models.Finding{
    ID:          "CVE-2024-28859",
    Title:       "[CVE-2024-28859] symfony/http-kernel@6.4.2 — RCE via serialized objects",
    Description: "Symfony HttpKernel vulnerable to remote code execution...",
    Severity:    models.SeverityHigh,
    Category:    "Dependencies",
    Scanner:     "dependency-scanner",
    File:        "composer.lock",
    Remediation: "Upgrade symfony/http-kernel to 6.4.4 or later:\n  composer require symfony/http-kernel:^6.4.4",
    References: [
        "https://github.com/advisories/GHSA-...",
        "https://nvd.nist.gov/vuln/detail/CVE-2024-28859",
    ],
}

Severity Mapping

Source: dependency/scanner.go:306-319

func parseSeverity(s string) models.Severity {
    switch strings.ToUpper(s) {
    case "CRITICAL":
        return models.SeverityCritical
    case "HIGH":
        return models.SeverityHigh
    case "MODERATE", "MEDIUM":
        return models.SeverityMedium
    case "LOW":
        return models.SeverityLow
    default:
        return models.SeverityMedium // default to medium for unknown
    }
}

Performance Optimizations

Batch Queries

Sends up to 100 packages per request instead of individual queries, reducing HTTP overhead.

Two-Phase Lookup

First identifies which packages are vulnerable (lightweight), then fetches full details only for affected packages.

Version Normalization

Skips dev branches (dev-main) that OSV.dev can’t match:

if strings.HasPrefix(v, "dev-") {
    return ""
}

Timeout Protection

Uses 30-second HTTP timeout to prevent hanging on slow networks.

Network Requirements

This scanner requires outbound HTTPS access to api.osv.dev. In air-gapped environments, disable it:

scanners:
  disable:
    - dependency-scanner

rules-scanner

Source: internal/scanner/rules/scanner.go

Description

Executes pattern-based security checks defined in YAML rule files. Ward ships with 40 default rules and supports custom rules.

Rule Execution

Load rules

Rules are loaded from:

~/.ward/rules/*.yaml (default rules)
Custom directories specified in config

Only enabled rules are executed.

Resolve targets

For each rule pattern, determine which files to scan based on the target field:Predefined targets:

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:

target: "app/Http/Controllers/**/*.php"

Scan files

For each file:

Read line by line
Match against the pattern (regex or substring)
Exclude lines matching exclude_pattern if specified
Record line number and code snippet

Handle negative patterns

If negative: true, the rule triggers when the pattern is NOT found (useful for “must have X” checks).

Generate findings

Create a finding for each match with:

Rule metadata (ID, title, description, severity, category)
File path and line number
Code snippet (truncated to 200 chars)
Remediation and references from rule definition

Pattern Types

regex
contains
file-exists

Regular expression matching (line-by-line).Example:

patterns:
  - type: regex
    target: php-files
    pattern: 'DB::raw\s*\(\s*["\'].*\$'

Matches SQL injection via string interpolation in DB::raw().

Exact substring matching.Example:

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

Matches unescaped Blade output with user variables.

Checks if files matching a glob pattern exist.Example:

patterns:
  - type: file-exists
    pattern: '.env.backup'

Detects backup .env files that shouldn’t be committed.

Negative Patterns

Use case: Enforce that certain code patterns must be present. Example:

patterns:
  - type: contains
    target: blade-files
    pattern: '@csrf'
    negative: true  # Trigger if @csrf is NOT found

This creates a finding for Blade forms missing CSRF protection.

Exclude Patterns

Use case: Reduce false positives by excluding safe contexts. Example:

patterns:
  - type: regex
    target: php-files
    pattern: 'password.*='
    exclude_pattern: 'env\(|config\('  # Ignore env() and config() calls

Implementation Details

File walking with exclusions:

func skipDir(name string) bool {
    switch name {
    case "vendor", "node_modules", ".git", "storage", ".idea", ".vscode":
        return true
    }
    return false
}

Pattern matching:

func scanFile(path string, pat config.PatternDef, re *regexp.Regexp) []match {
    scanner := bufio.NewScanner(file)
    lineNum := 0
    for scanner.Scan() {
        lineNum++
        line := scanner.Text()
        
        var matched bool
        switch pat.Type {
        case "regex":
            matched = re.MatchString(line)
        case "contains":
            matched = strings.Contains(line, pat.Pattern)
        }
        
        // Skip if exclude pattern matches
        if matched && excludeRe != nil && excludeRe.MatchString(line) {
            matched = false
        }
        
        if matched {
            matches = append(matches, match{line: lineNum, text: line})
        }
    }
    return matches
}

Default Rules Summary

Ward ships with 40 rules across 7 categories:

Secrets (7 rules)

Hardcoded passwords in code
AWS credentials
API keys and tokens
JWT secrets
Database credentials

Injection (6 rules)

SQL injection via DB::raw() with interpolation
Command injection via exec(), shell_exec()
Code injection via eval()
Unsafe deserialization with unserialize()

XSS (4 rules)

Unescaped Blade output {!! $var !!}
JavaScript injection in Blade
echo with user input

Debug (6 rules)

dd() and dump() calls
var_dump(), print_r()
phpinfo()
Laravel Debugbar in production

Crypto (5 rules)

MD5/SHA1 for password hashing
rand() instead of random_bytes()
Deprecated mcrypt functions
Base64 mistaken for encryption

Security Config (7 rules)

CORS wildcards
SSL verification disabled
CSRF middleware missing
Mass assignment $guarded = []
Unsafe file upload extensions

Auth (5 rules)

Missing authentication middleware
Missing rate limiting
loginUsingId() without validation
Hardcoded admin checks

Scanner Configuration

Disable Scanners

File: ~/.ward/config.yaml

scanners:
  disable:
    - dependency-scanner  # Skip CVE checks
    - rules-scanner       # Skip YAML pattern rules

Disable Individual Rules

rules:
  disable:
    - DEBUG-001  # Allow dd() calls
    - AUTH-002   # Allow missing rate limiting

Override Rule Severity

rules:
  override:
    DEBUG-002:
      severity: low  # Downgrade dump() from medium to low
    CRYPTO-001:
      severity: critical  # Upgrade MD5 hashing from high to critical

Add Custom Rule Directories

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

Scanner Independence

Scanners are fully independent and don’t communicate with each other. This design provides several benefits:

Reliability: If one scanner fails, others continue
Parallelization: Scanners could run concurrently (future enhancement)
Modularity: Easy to add/remove scanners without affecting others
Testing: Each scanner can be unit tested in isolation

Shared Dependencies

Scanners only depend on:

The immutable ProjectContext (built by resolvers)
The emit callback (for real-time updates)
The context.Context (for cancellation)

They do not depend on:

Other scanners’ results
Filesystem state (all paths are in ProjectContext.RootPath)
Global state

Adding Custom Scanners

To create a new scanner:

Implement the Scanner interface

package myscanner

import (
    "context"
    "github.com/eljakani/ward/internal/models"
)

type MyScanner struct{}

func New() *MyScanner { return &MyScanner{} }

func (s *MyScanner) Name() string {
    return "my-scanner"
}

func (s *MyScanner) Description() string {
    return "My custom security checks"
}

func (s *MyScanner) Scan(ctx context.Context, pc models.ProjectContext, emit func(models.Finding)) ([]models.Finding, error) {
    var findings []models.Finding
    
    // Your scan logic here
    f := models.Finding{
        ID:          "CUSTOM-001",
        Title:       "Custom check failed",
        Description: "Details...",
        Severity:    models.SeverityHigh,
        Category:    "Custom",
        Scanner:     s.Name(),
        File:        "some-file.php",
        Line:        42,
    }
    
    findings = append(findings, f)
    emit(f)  // Emit in real-time
    
    return findings, nil
}

File: internal/orchestrator/orchestrator.go

scanners := []models.Scanner{
    envscanner.New(),
    configscanner.New(),
    depscanner.New(),
    myscanner.New(),  // Add your scanner
}

Rebuild and test

make build
ward scan ./test-project

Architecture

System architecture and design principles

Scan Pipeline

How scanners fit into the 5-stage pipeline

Custom Rules

Writing YAML rules for the rules-scanner

Configuration

Scanner configuration options

Documentation Index

​Scanner Overview

env-scanner

config-scanner

dependency-scanner

rules-scanner

​How Scanners Work

​Scanner Execution

​env-scanner

​Description

​Checks Performed (8 rules)

​Implementation Details

​config-scanner

​Description

​Files Analyzed

​Checks Performed (13 rules)

​Implementation Details

​dependency-scanner

​Description

​How It Works

​Finding Format

​Severity Mapping

​Performance Optimizations

Batch Queries

Two-Phase Lookup

Version Normalization

Timeout Protection

​Network Requirements

​rules-scanner

​Description

​Rule Execution

​Pattern Types

​Negative Patterns

​Exclude Patterns

​Implementation Details

​Default Rules Summary

​Scanner Configuration

​Disable Scanners

​Disable Individual Rules

​Override Rule Severity

​Add Custom Rule Directories

​Scanner Independence

​Shared Dependencies

​Adding Custom Scanners

​Related Pages

Architecture

Scan Pipeline

Custom Rules

Configuration

Scanner Overview

How Scanners Work

Scanner Execution

env-scanner

Description

Checks Performed (8 rules)

Implementation Details

config-scanner

Description

Files Analyzed

Checks Performed (13 rules)

Implementation Details

dependency-scanner

Description

How It Works

Finding Format

Severity Mapping

Performance Optimizations

Network Requirements

rules-scanner

Description

Rule Execution

Pattern Types

Negative Patterns

Exclude Patterns

Implementation Details

Default Rules Summary

Scanner Configuration

Disable Scanners

Disable Individual Rules

Override Rule Severity

Add Custom Rule Directories

Scanner Independence

Shared Dependencies

Adding Custom Scanners

Related Pages