• Inputs
  • Release Notes
  • Permissions
• Outputs
• Examples
• Tags
• Features
  • Planned
• Support
• Contributing

Submit file globs or release assets to the VirusTotal API for scanning.

On release events the Release Notes will optionally be updated with links to the scan results.

You can now customize the links display and release notes heading. See the Features for more details.

The /files/ endpoint is used for files under 32MB, otherwise, the /files/upload_url/ endpoint is used providing support for files up to 650MB. Therefore, files over 32MB will consume 2 API calls.

With no inputs this will automatically process release assets.

- name: 'VirusTotal'
  uses: cssnr/virustotal-action@v1
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}

Make sure to review the Inputs and checkout more Examples.

This is a fairly simple action, for more details see src/index.js and src/vt.js.

For more details on inputs, see the VirusTotal API documentation.

vt_api_key: Get your API key from: https://www.virustotal.com/gui/my-apikey

file_globs: If provided, will process matching files instead of release assets.
For glob pattern, see examples and the docs.

rate_limit: Rate limit for file uploads. Set to 0 to disable if you know what you are doing.

summary: Will add result details to the job summary in the workflow.

[
  {
    "id": "YmFmZTVlZjIzMDRkMjRlMTcwNjk1Yzg0MTgyN2FmMmM6MTc0MjExMjY5Mw==",
    "name": "README.md",
    "link": "https://www.virustotal.com/gui/file-analysis/YmFmZTVlZjIzMDRkMjRlMTcwNjk1Yzg0MTgyN2FmMmM6MTc0MjExMjY5Mw=="
  },
  {
    "id": "ZTM4MjBkOGFhYmRhNjBiMTY0MTEwZjZkNDE1YjViODc6MTc0MjExMjY5Mw==",
    "name": ".gitignore",
    "link": "https://www.virustotal.com/gui/file-analysis/ZTM4MjBkOGFhYmRhNjBiMTY0MTEwZjZkNDE1YjViODc6MTc0MjExMjY5Mw=="
  }
]

README.md/YmFmZTVlZjIzMDRkMjRlMTcwNjk1Yzg0MTgyN2FmMmM6MTc0MjExMjY5Mw==
.gitignore/ZTM4MjBkOGFhYmRhNjBiMTY0MTEwZjZkNDE1YjViODc6MTc0MjExMjY5Mw==

files: ["README.md",".gitignore"]
rate: 4
update: true
heading: "🛡️ **VirusTotal Results:**"
summary: true

To view a workflow run, click on a recent Test job (requires login).

Example with all inputs:

- name: 'VirusTotal'
  uses: cssnr/virustotal-action@v1
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}
    file_globs: |
      file1
      release/*
    rate_limit: 4
    update_release: true
    release_heading: '🛡️ **VirusTotal Results:**'
    summary: true

See the Examples section for more options.

If run on a release event, the Release Notes are automatically updated with the results unless you set update_release to false. You can customize the heading or remove it by specifying an empty string.

update_release: If triggered from a release workflow, will update the release notes and append the results.

release_heading: Customize the Release Notes Heading.
Default: 🛡️ **VirusTotal Results:**

collapsed: Set to true to collapse the result links by default. Experimental.

file_name: Customize the Release Notes File Name Display. This can be one of name, or id.

🛡️ VirusTotal Results:

• install-linux.deb
• install-macos.pkg
• install-win.exe

This action requires the following permissions to edit releases notes:

permissions:
  contents: write

Permissions documentation for Workflows and Actions.

Web links can be generated by appending the ID to this URL:

https://www.virustotal.com/gui/file-analysis/

install-linux.deb/ODA3ZWUyN2E4YjhjMTJlODRlZTBmOTJjMmE5MzBlMmQ6MTcyNjg3MjQyMw==,install-macos.pkg/YTAwN2I4MWQwZjkzNDJjZTVmMWFhNzBjY2Y0ZGJkODE6MTcyNjg3MjQyNQ==,install-win.exe/N2JlODFiMWMwZGY1M2EzMzg5MWY1ZDQ0N2QyMWU0MWI6MTcyNjg3MjQyNw==

[
  {
    "id": "ODA3ZWUyN2E4YjhjMTJlODRlZTBmOTJjMmE5MzBlMmQ6MTcyNjg3MjQyMw==",
    "name": "install-linux.deb",
    "link": "https://www.virustotal.com/gui/file-analysis/ODA3ZWUyN2E4YjhjMTJlODRlZTBmOTJjMmE5MzBlMmQ6MTcyNjg3MjQyMw=="
  },
  {
    "id": "YTAwN2I4MWQwZjkzNDJjZTVmMWFhNzBjY2Y0ZGJkODE6MTcyNjg3MjQyNQ==",
    "name": "install-macos.pkg",
    "link": "https://www.virustotal.com/gui/file-analysis/YTAwN2I4MWQwZjkzNDJjZTVmMWFhNzBjY2Y0ZGJkODE6MTcyNjg3MjQyNQ=="
  },
  {
    "id": "N2JlODFiMWMwZGY1M2EzMzg5MWY1ZDQ0N2QyMWU0MWI6MTcyNjg3MjQyNw==",
    "name": "install-win.exe",
    "link": "https://www.virustotal.com/gui/file-analysis/N2JlODFiMWMwZGY1M2EzMzg5MWY1ZDQ0N2QyMWU0MWI6MTcyNjg3MjQyNw=="
  }
]

Using the outputs.

- name: 'VirusTotal'
  uses: cssnr/virustotal-action@v1
  id: vt
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}

- name: 'Echo Results'
  run: |
    echo results: ${{ steps.vt.outputs.results }}
    echo json: ${{ steps.vt.outputs.json }}

💡 Click on an example heading to expand or collapse the example.

- name: 'VirusTotal'
  uses: cssnr/virustotal-action@v1
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}

- name: 'VirusTotal'
  uses: cssnr/virustotal-action@v1
  if: ${{ github.event_name == 'release' }}
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}
    release_heading: '### Scan Results'

- name: 'VirusTotal'
  uses: cssnr/virustotal-action@v1
  if: ${{ github.event_name == 'release' }}
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}

- name: 'VirusTotal'
  uses: cssnr/virustotal-action@v1
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}
    file_globs: artifacts/*

- name: 'VirusTotal'
  uses: cssnr/virustotal-action@v1
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}
    file_globs: |
      artifacts/*
      assets/asset.zip

- name: 'VirusTotal'
  uses: cssnr/virustotal-action@v1
  with:
    vt_api_key: ${{ secrets.VT_API_KEY }}
    file_globs: |
      file1
      release/*
    rate_limit: 4
    update_release: true
    release_heading: '🛡️ **VirusTotal Results:**'
    summary: true

name: 'VirusTotal Example'

on:
  release:
    types: [published]

jobs:
  release:
    name: 'Release'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      contents: write

    steps:
      - name: 'VirusTotal Action'
        uses: cssnr/virustotal-action@v1
        with:
          vt_api_key: ${{ secrets.VT_API_KEY }}

name: 'VirusTotal Example'

on:
  release:
    types: [published]

permissions:
  contents: write

jobs:
  windows:
    name: 'Windows Build'
    runs-on: windows-latest
    timeout-minutes: 5

    steps:
      - name: 'Checkout'
        uses: actions/checkout@v4

      - name: 'Build'
        uses: Minionguyjpro/Inno-Setup-Action@v1.2.2
        with:
          path: client.iss
          options: '/DMyAppVersion=${{ github.ref_name }}'

      - name: 'Upload to Release'
        uses: svenstaro/upload-release-action@v2
        if: ${{ github.event_name == 'release' }}
        with:
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          file: out/*
          tag: ${{ github.ref }}
          overwrite: true
          file_glob: true

  virustotal:
    name: 'VirusTotal'
    runs-on: ubuntu-latest
    needs: [windows]
    timeout-minutes: 5
    if: ${{ github.event_name == 'release' }}

    steps:
      - name: 'VirusTotal Action'
        uses: cssnr/virustotal-action@v1
        with:
          vt_api_key: ${{ secrets.VT_API_KEY }}
          rate_limit: 4
          update_release: true

To see this used in a build/release/scan workflow, check out:
https://github.com/cssnr/hls-downloader-client/blob/master/.github/workflows/build.yaml

For more examples, you can check out other projects using this action:
https://github.com/cssnr/virustotal-action/network/dependents

The following rolling tags are maintained.

Version Tag	Rolling	Bugs	Feat.	Name	Target	Example
	✅	✅	✅	Major	vN.x.x	vN
	✅	✅	❌	Minor	vN.N.x	vN.N
	❌	❌	❌	Micro	vN.N.N	vN.N.N

You can view the release notes for each version on the releases page.

The Major tag is recommended. It is the most up-to-date and always backwards compatible. Breaking changes would result in a Major version bump. At a minimum you should use a Minor tag.

• Supports files up to 650MB
• Upload Release Assets or File Globs
• Automatically add Results to Release Notes
  • Customize Release Notes Heading
• Rate Limited for Free Accounts

• Add options to customize release update/output format (next on the roadmap).
• Add release body parsing to properly process new files on edited activity.
• Add option to apply file_globs to release assets.
• Refactor vt.js as a Class to clean up index.js.

Don't see your feature here, or want to see one implemented? Let us know in the Support section.

For general help or to request a feature see:

• Q&A Discussion: https://github.com/cssnr/virustotal-action/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/virustotal-action/discussions/categories/feature-requests

If you are experiencing an issue/bug or getting unexpected results you can:

• Report an Issue: https://github.com/cssnr/virustotal-action/issues
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY
• Provide General Feedback: https://cssnr.github.io/feedback/

For more information, see the CSSNR SUPPORT.md.

Please consider making a donation to support the development of this project and additional open source projects.

If you would like to submit a PR, please review the CONTRIBUTING.md.

Additionally, you can support other GitHub Actions I have published:

• Stack Deploy Action
• Portainer Stack Deploy
• VirusTotal Action
• Mirror Repository Action
• Update Version Tags Action
• Update JSON Value Action
• Parse Issue Form Action
• Cloudflare Purge Cache Action
• Mozilla Addon Update Action
• Docker Tags Action
• Package Changelog Action
• NPM Outdated Check Action

For a full list of current projects visit: https://cssnr.github.io/