.havoc.yml Reference

HAVOC reads configuration from a .havoc.yml file in your project root. Run havoc init to generate a starter config. All settings are optional — HAVOC uses sensible defaults if no config file exists.

Full example

# .havoc.yml
version: 1

# Project settings
project:
  name: "My Laravel App"
  framework: laravel  # Auto-detected if omitted

# Scan settings
scan:
  paths:
    - app/
    - routes/
  exclude:
    - "app/Console/**"
    - "tests/**"
    - "database/**"
    - "vendor/**"
  follow_symlinks: false

# Analyzer configuration
analyzers:
  enabled: all  # 'all' or list of analyzer IDs
  # Or use explicit list:
  # enabled:
  #   - authorization-coverage
  #   - mass-assignment
  #   - xss-blade
  disabled:
    - credential-exposure  # If you handle credentials differently

  # Per-analyzer overrides
  authorization-coverage:
    exclude_methods:
      - "__construct"
      - "middleware"
      - "redirectIfAuthenticated"
    count_middleware_as_covered: true

  mass-assignment:
    severity_override: medium  # Downgrade from high

# Thresholds
thresholds:
  fail_on: high        # critical | high | medium | low | never
  min_coverage: 80     # Fail if authorization coverage drops below %
  max_findings: ~      # Optional: fail if finding count exceeds N

# Ignore specific findings
ignore:
  # By finding ID (suppress across all files)
  - id: HAVOC-103
    reason: "Known false positive in legacy admin controller"

  # By file + line range
  - file: app/Http/Controllers/Admin/LegacyController.php
    lines: 45-60
    reason: "Pre-auth endpoint, no authorization needed"

  # By rule + file pattern
  - rule: xss-blade
    path: "resources/views/email/**"
    reason: "Email templates are not user-facing HTML"

# Output configuration
output:
  format: text         # text | json | sarif | github
  show_context: true   # Show code context around findings
  group_by: severity   # severity | file | rule

# Cloud sync
cloud:
  enabled: true        # Requires HAVOC_TOKEN env var
  project_id: ~        # Auto-set from token if omitted

Top-Level Options

Key	Type	Default	Description
version	integer	1	Config file schema version. Currently only version 1 is supported.
project.name	string	directory name	Display name for this project in HAVOC Cloud
project.framework	string	auto-detect	Framework: `laravel`, `rails` (future), `django` (future)

Analyzers

Key	Type	Default	Description
analyzers.enabled	string or list	all	Use `all` or explicit list of analyzer IDs
analyzers.disabled	list	[]	Analyzer IDs to disable (takes precedence over enabled)
analyzers.{id}.severity_override	string	—	Override default severity for an analyzer
analyzers.authorization-coverage.exclude_methods	list	[]	Method names to exclude from coverage calculation
analyzers.authorization-coverage.count_middleware_as_covered	boolean	true	Count route middleware as an authorization check

Analyzer IDs

ID	Description	Default Severity
authorization-coverage	Missing authorize() / Gate:: checks	high
mass-assignment	Unguarded fillable properties	high
xss-blade	Unescaped {{ vs {!! output	medium
sql-injection	Raw DB queries with user input	critical
idor	Direct object reference without ownership check	high
policy-parity	Policy methods missing for model actions	medium
privilege-escalation	Role/permission assignments without checks	high
state-machine	State transitions without guards	medium
credential-exposure	Keys/secrets in code or config	critical

Thresholds

Key	Type	Default	Description
thresholds.fail_on	string	high	Exit code 1 if findings at this severity or above exist
thresholds.min_coverage	integer	—	Exit code 3 if authorization coverage is below this %
thresholds.max_findings	integer	—	Exit code 1 if total findings exceed this count

Ignoring Rules

Use the ignore section to suppress known false positives or accepted risks. Every ignore entry requires a reason — this is enforced to prevent silent suppression.

ignore:
  # Suppress by finding ID
  - id: HAVOC-103
    reason: "Legacy endpoint, scheduled for removal in Q2"

  # Suppress a rule for a file pattern
  - rule: xss-blade
    path: "resources/views/admin/raw-html/**"
    reason: "Content is sanitized by DOMPurify on the client"

  # Suppress a line range in a specific file
  - file: app/Http/Controllers/WebhookController.php
    lines: 10-45
    reason: "Webhook endpoint uses HMAC verification instead of OAuth"

Audit trail: All ignored findings are logged in HAVOC Cloud with the reason, author, and timestamp. They appear as "Suppressed" in the dashboard and count against your coverage grade.

Output

Key	Options	Default	Description
output.format	text, json, sarif, github	text	Output format. `github` uses GitHub Actions annotation syntax.
output.show_context	boolean	true	Show 3 lines of code context around each finding
output.group_by	severity, file, rule	severity	How to group findings in text output