VirusTotal Action

Features
- VirusTotal Badges
Inputs
- Permissions
Outputs
Examples
Tags
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.

Tip

A new Documentation site is currently being developed:
https://actions.cssnr.com/virustotal/

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
Option to specify the Release ID

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.

Note

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

VirusTotal Badges

We are also working on a Badge Server (similar to shields.io) that supports VirusTotal Badges.
For more details see the Website, the README.md or the Discussion in this repo.

These badges may be eventually added to this action as an option for release notes. Any feedback is helpful during this phase of development.

Inputs

Input Name	Default Value	Description of the Input Value
`vt_api_key`	Required	VirusTotal API Key ⤵️
`file_globs`	-	File Globs to Process ⤵️
`rate_limit`	`4`	API Calls Per Minute ⤵️
`release_id`	-	Release ID to Process ⤵️
`sha256`	`false`	Calculate File SHA256 ⤵️
`update_release`	`true`	Update the Release Notes
`release_heading`	see below	Release Notes Heading ⤵️
`collapsed`	`false`	Show Links Collapsed. ⤵️
`file_name`	`name`	File Name Display: [`name`, `id`] ⤵️
`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.

release_id

If provided, will process the corresponding release. The release ID can be generated from a previous step. By providing a release ID, this action does not need to run on a release event to process a release.

sha256

If enabled this will calculate the file's SHA256 hash, and include it in the output.

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": "MGM1YTkxMzc5OGU3Y2UyNjViNTkxYzY5OTZmNTg3NjI6MTc2MDEyMzYzOA==",
    "name": "README.md",
    "link": "https://www.virustotal.com/gui/file-analysis/MGM1YTkxMzc5OGU3Y2UyNjViNTkxYzY5OTZmNTg3NjI6MTc2MDEyMzYzOA==",
    "sha256": "75f762919859572abf753008cc5a1f5b75e05e9d0876080c0d28b2338ca46c26"
  },
  {
    "id": "ZmIzNTcyMDI5NTAxN2VkYzRiZmRmMTg4NzhjNWJjY2Y6MTc2MDEyMzYzOQ==",
    "name": ".gitignore",
    "link": "https://www.virustotal.com/gui/file-analysis/ZmIzNTcyMDI5NTAxN2VkYzRiZmRmMTg4NzhjNWJjY2Y6MTc2MDEyMzYzOQ==",
    "sha256": "4c534768e93cc21269fecf0dea55eb9191ab649cb2fff8952f40cbf7a21057fe"
  }
]

README.md/MGM1YTkxMzc5OGU3Y2UyNjViNTkxYzY5OTZmNTg3NjI6MTc2MDEyMzYzOA==
.gitignore/ZmIzNTcyMDI5NTAxN2VkYzRiZmRmMTg4NzhjNWJjY2Y6MTc2MDEyMzYzOQ==

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

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.

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

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.

Example Release Notes

🛡️ 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	CSV String of `file/id`
json	JSON Object Results List

Web links can be generated by appending the ID or SHA256 to these URL:

results

README.md/MGM1YTkxMzc5OGU3Y2UyNjViNTkxYzY5OTZmNTg3NjI6MTc2MDEyMzYzOA==,.gitignore/ZmIzNTcyMDI5NTAxN2VkYzRiZmRmMTg4NzhjNWJjY2Y6MTc2MDEyMzYzOQ==

json

Note: The sha256 is only included if you set the input sha256: true.

[
  {
    "id": "MGM1YTkxMzc5OGU3Y2UyNjViNTkxYzY5OTZmNTg3NjI6MTc2MDEyMzYzOA==",
    "name": "README.md",
    "link": "https://www.virustotal.com/gui/file-analysis/MGM1YTkxMzc5OGU3Y2UyNjViNTkxYzY5OTZmNTg3NjI6MTc2MDEyMzYzOA==",
    "sha256": "75f762919859572abf753008cc5a1f5b75e05e9d0876080c0d28b2338ca46c26"
  },
  {
    "id": "ZmIzNTcyMDI5NTAxN2VkYzRiZmRmMTg4NzhjNWJjY2Y6MTc2MDEyMzYzOQ==",
    "name": ".gitignore",
    "link": "https://www.virustotal.com/gui/file-analysis/ZmIzNTcyMDI5NTAxN2VkYzRiZmRmMTg4NzhjNWJjY2Y6MTc2MDEyMzYzOQ==",
    "sha256": "4c534768e93cc21269fecf0dea55eb9191ab649cb2fff8952f40cbf7a21057fe"
  }
]

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@v5

      - name: 'Build'
        uses: Minionguyjpro/[email protected]
        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

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

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:

❔ Unpublished Actions

These actions are not published on the Marketplace, but may be useful.

cssnr/draft-release-action - Keep a draft release ready to publish.
cssnr/env-json-action - Convert env file to json or vice versa.
cssnr/push-artifacts-action - Sync files to a remote host with rsync.
smashedr/update-release-notes-action - Update release notes.
smashedr/combine-release-notes-action - Combine release notes.

📝 Template Actions

These are basic action templates that I use for creating new actions.

js-test-action - JavaScript
py-test-action - Python
ts-test-action - TypeScript
docker-test-action - Docker Image

Note: The docker-test-action builds, runs and pushes images to GitHub Container Registry.

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

Name		Name	Last commit message	Last commit date
Latest commit History 41 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!

Uh oh!

Repository files navigation

VirusTotal Action

Features

Planned

VirusTotal Badges

Inputs

vt_api_key

file_globs

rate_limit

release_id

sha256

summary

Release Notes

update_release

release_heading

collapsed

file_name

Example Release Notes

Permissions

Outputs

results

json

Examples

Tags

Support

Contributing

About

Uh oh!

Releases 14

Sponsor this project

Uh oh!

Uh oh!

Contributors 2

Uh oh!

Languages

Uh oh!

License

cssnr/virustotal-action

Folders and files

Latest commit

History

Repository files navigation

VirusTotal Action

Features

Planned

VirusTotal Badges

Inputs

vt_api_key

file_globs

rate_limit

release_id

sha256

summary

Release Notes

update_release

release_heading

collapsed

file_name

Example Release Notes

Permissions

Outputs

results

json

Examples

Tags

Support

Contributing

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 14

Sponsor this project

Uh oh!

Uh oh!

Contributors 2

Uh oh!

Languages