GitHub Action Reference

The havoc-security/havoc-action GitHub Action runs HAVOC security scans as part of your CI/CD workflow. It posts inline PR comments, updates commit status, and optionally syncs results to HAVOC Cloud.

Setup

Minimal setup (free, no cloud account)

# .github/workflows/havoc.yml
name: HAVOC Security Scan
on:
  push:
    branches: [main]
  pull_request:

jobs:
  havoc:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write  # Required for PR comments
      statuses: write       # Required for commit status

    steps:
      - uses: actions/checkout@@v4
        with:
          fetch-depth: 0  # Full history for diff-aware scanning

      - uses: havoc-security/havoc-action@@v1
        with:
          token: {{ secrets.GITHUB_TOKEN }}

With HAVOC Cloud (recommended)

- uses: havoc-security/havoc-action@@v1
  with:
    token: {{ secrets.GITHUB_TOKEN }}
    havoc-token: {{ secrets.HAVOC_TOKEN }}  # From havoc.cloud dashboard
    fail-on: high

Get your HAVOC_TOKEN: Sign in to havoc.cloud → Settings → API Keys → Generate token. Add it to your repo's Settings → Secrets.

Inputs

Input	Required	Default	Description
token	Yes	—	GitHub token for PR comments and commit status. Use `{{ secrets.GITHUB_TOKEN }}`
havoc-token	No	—	HAVOC Cloud API token for syncing results. Required for cloud features.
path	No	`.`	Directory to scan relative to checkout root
fail-on	No	high	Fail the workflow if findings at or above this severity exist. Values: `critical`, `high`, `medium`, `low`, `never`
coverage-threshold	No	—	Fail if authorization coverage drops below this percentage (integer, 0-100)
min-severity	No	low	Minimum severity to include in PR comments
comment-on-pr	No	true	Post findings as PR comment on pull requests
upload-sarif	No	false	Upload SARIF results to GitHub Code Scanning
analyzers	No	all	Comma-separated list of analyzers to run
config	No	.havoc.yml	Path to HAVOC config file

Outputs

Output	Type	Description
finding-count	integer	Total number of findings
critical-count	integer	Number of critical findings
high-count	integer	Number of high findings
coverage	float	Authorization coverage percentage (e.g. 89.8)
scan-id	string	HAVOC Cloud scan ID (when havoc-token is set)
report-url	string	HAVOC Cloud report URL (when havoc-token is set)
passed	boolean	Whether the scan passed all thresholds

Examples

Fail on high severity, require 80% coverage

- uses: havoc-security/havoc-action@@v1
  with:
    token: {{ secrets.GITHUB_TOKEN }}
    havoc-token: {{ secrets.HAVOC_TOKEN }}
    fail-on: high
    coverage-threshold: 80

Upload to GitHub Code Scanning (SARIF)

- uses: havoc-security/havoc-action@@v1
  id: havoc
  with:
    token: {{ secrets.GITHUB_TOKEN }}
    upload-sarif: true

- uses: github/codeql-action/upload-sarif@@v3
  if: always()
  with:
    sarif_file: havoc-results.sarif

Use output in subsequent steps

- uses: havoc-security/havoc-action@@v1
  id: havoc
  with:
    token: {{ secrets.GITHUB_TOKEN }}

- name: Report coverage
  run: |
    echo "Authorization coverage: {{ steps.havoc.outputs.coverage }}%"
    echo "Total findings: {{ steps.havoc.outputs.finding-count }}"

Scan only on PRs targeting main

on:
  pull_request:
    branches: [main]
    types: [opened, synchronize, reopened]

Permissions reference

Permission	When needed
contents: read	Always — to checkout and read code
pull-requests: write	When comment-on-pr is true (default)
statuses: write	To update commit status checks
security-events: write	When upload-sarif is true