VirusTotal Action

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

Upload Release Assets or Specified File Globs to VirusTotal and Optionally Update Release Notes with Links.

You can now customize the 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.

Note

Please submit a Feature Request for new features or Open an Issue if you find any bugs.

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

Inputs

Input Name	Req.	Default Value	Input Description
`vt_api_key`	Yes	-	VirusTotal API Key *
`file_globs`	-	-	File Globs to Process *
`rate_limit`	-	`4`	API Calls Per Minute *
`update_release`	-	`true`	Update the Release Notes
`release_heading`	-	see below	Release Notes Heading ⤵️
`summary`	-	`true`	Add Summary to Job *
`github_token`	-	`github.token`	For use with a PAT

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.

👀 View Job Summary Example

File	ID
README.md	YmFmZTVlZjIzMDRkMjRlMTcwNjk1Yzg0MTgyN2FmMmM6MTc0MjExMjY5Mw==
.gitignore	ZTM4MjBkOGFhYmRhNjBiMTY0MTEwZjZkNDE1YjViODc6MTc0MjExMjY5Mw==

Outputs

[
  {
    "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==

Config

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).

With no inputs this will automatically process release assets.

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

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.

Release Notes

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:**

Example Release Notes Update

🛡️ VirusTotal Results:

Permissions

This action requires the following permissions to edit releases notes:

permissions:
  contents: write

Permissions documentation for Workflows and Actions.

Outputs

Output	Output Description
results	Comma Seperated String of `file/id`
json	JSON Object List Results String

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

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

Example Results

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

Example JSON

[
  {
    "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 }}

Examples

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

Process release assets

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

Customize release notes heading

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

Only run on a release event

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

Using file globs

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

Multiple file globs

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

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

Simple workflow example

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 }}

Note: the permissions are applied to the individual job here.

Full workflow example

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

Note: the permissions are applied to the entire workflow here.

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

Features

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

Planned

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.

Support

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.

Contributing

Currently, the best way to contribute to this project is to star this project on GitHub.

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

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
.github		.github
dist		dist
src		src
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
commit-checklist.json		commit-checklist.json
eslint.config.mjs		eslint.config.mjs
package-lock.json		package-lock.json
package.json		package.json

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

VirusTotal Action

Inputs

Release Notes

Example Release Notes Update

Permissions

Outputs

Examples

Tags

Features

Planned

Support

Contributing

About

Uh oh!

Releases 8

Uh oh!

Languages

License

cssnr/virustotal-action

Folders and files

Latest commit

History

Repository files navigation

VirusTotal Action

Inputs

Release Notes

Example Release Notes Update

Permissions

Outputs

Examples

Tags

Features

Planned

Support

Contributing

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 8

Uh oh!

Languages