VirusTotal GitHub Action

To scan assets through the VirusTotal Monitor endpoint, enable vt_monitor and specify a monitor_path. The monitor_path is a path relative to your current monitor user root folder.

- name: VirusTotal Scan
  uses: crazy-max/ghaction-virustotal@v5
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}
    vt_monitor: true
    monitor_path: /ghaction-virustotal
    files: |
      ./foo-win32.exe
      ./foo-win64.exe

Use this action to upload and scan specific local files from your repository using your VirusTotal API key. The files input accepts a newline-delimited list of path globs or patterns.

- name: VirusTotal Scan
  uses: crazy-max/ghaction-virustotal@v5
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}
    files: |
      ./foo-win32.exe
      ./foo-win64.exe

You can trigger a scan automatically when a GitHub release is published.

Requirements:

1. The workflow must trigger on the release event.
2. If you want to append analysis links to the release body using update_release_body: true, you must provide a github_token and ensure the job has contents: write permissions.
3. If using update_release_body, the github_token is required to authenticate with the GitHub API.

name: released

permissions:
  contents: read

on: release:
    types: [published]

jobs:
  virustotal:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: VirusTotal Scan
        uses: crazy-max/ghaction-virustotal@v5
        with:
          vt_api_key: ${{ secrets.VT_API_KEY }}
          update_release_body: true
          github_token: ${{ secrets.GITHUB_TOKEN }}
          files: |
            .exe$

The action automatically switches its logic based on the github.context.eventName:

Local Files Mode

Triggered by any event other than release.

• It uses context.resolvePaths(inputs.files) to find files on the runner.
• It iterates through files and uploads them using vt.files(filepath) or vt.monitorItems(filepath, inputs.monitorPath).

Release Assets Mode

Triggered by a release event.

• It fetches the release and its assets using octokit.
• It downloads assets to a temporary directory.
• It uploads them to VirusTotal.
• It can append the results to the release description if update_release_body is set to true.

When running during a release event, you can automatically append the VirusTotal analysis links to the GitHub Release description.

To enable this, set the update_release_body input to true.

Formatting logic:

• If there are 5 or fewer assets, the links are appended as a simple list.
• If there are more than 5 assets, the links are wrapped in a <details> HTML tag to keep the release body clean.

To use the VirusTotal Monitor feature instead of standard file uploads, set the vtMonitor input to true. When this is enabled, the action uses the monitorItems method which requires a monitorPath input.

Inputs required:

• vtMonitor: true
• monitorPath: The path used for monitoring items.

The following outputs are available from the action.

| Name | Type | Description |
|---------------|----------------|----------------------------------------------------------------------------|
| `analysis` | String | Analysis results formatted as `<filename>=<analysisURL>` (comma separated) |

The VirusTotal class provides an interface to interact with the VirusTotal API v3. You can instantiate it with an API key and use it to upload files for analysis or to the VirusTotal Monitor.

import { VirusTotal } from './virustotal';

const vt = new VirusTotal('YOUR_API_KEY');

// Upload a file for standard analysis
const uploadData = await vt.files('path/to/file.exe');
console.log(uploadData.url); // https://www.virustotal.com/gui/file-analysis/${uploadData.id}/detection

// Upload a file to VirusTotal Monitor
const monitorData = await vt.monitorItems('path/to/file.exe', '/expected/path');
console.log(monitorData.url); // https://www.virustotal.com/monitor/analyses/item:${monitorData.id}

When calling files() or monitorItems(), the returned UploadData object contains the following fields:

• id: The unique identifier for the upload/analysis.
• type: The type of the upload.
• url: A direct link to the VirusTotal web interface for viewing the results.

interface UploadData {
  id: string;
  type: string;
  url: string;
}