VirusTotal Action

• Inputs
• Outputs
• Examples
• Tags
• Planned Features
• Support
• Contributing

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

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	required	default	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 Release Notes *
summary	-	true	Add Summary to Job *
github_token	-	github.token	Only for using a PAT

For additional 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.

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

👀 View Release Notes Update Example

---

🛡️ VirusTotal Results:

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

---

summary - Will add result details to the job summary in the workflow

👀 View Job Summary Example

---

File	ID
README.md	ZWFkNTUwMDlhYTM4MTU3MzljYWE1NWRlMjQ5MzE5Y2E6MTc0MDE3NDA5Ng==
.gitignore	ZTM4MjBkOGFhYmRhNjBiMTY0MTEwZjZkNDE1YjViODc6MTc0MDE3NDA5Ng==

Outputs

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

README.md/ZWFkNTUwMDlhYTM4MTU3MzljYWE1NWRlMjQ5MzE5Y2E6MTc0MDE3NDA5Ng==
.gitignore/ZTM4MjBkOGFhYmRhNjBiMTY0MTEwZjZkNDE1YjViODc6MTc0MDE3NDA5Ng==

Inputs

Input	Value
file_globs	README.md,.gitignore
rate_limit	4
update_release	true
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
    summary: true

See the Examples section for more options.

Outputs

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

install-linux.deb/ZDAzY2M2ZGQzZmEwZWEwZTI2NjQ5NmVjZDcwZmY0YTY6MTcxNzU2NzI3Ng==,install-macos.pkg/YTkzOGFjMDZhNTI3NmU5MmI4YzQzNzg5ODE3OGRkMzg6MTcxNzU2NzI3OA==,install-win.exe/M2JhZDJhMzRhYjcyM2Y0MDFkNjU1OGZlYjFkNjgyMmY6MTcxNzU2NzI4MA==

Example json output.

[
  {
    "id": "ZDAzY2M2ZGQzZmEwZWEwZTI2NjQ5NmVjZDcwZmY0YTY6MTcxNzU2NzI3Ng==",
    "name": "install-linux.deb",
    "link": "https://www.virustotal.com/gui/file-analysis/ZDAzY2M2ZGQzZmEwZWEwZTI2NjQ5NmVjZDcwZmY0YTY6MTcxNzU2NzI3Ng=="
  }
]

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

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
    summary: true

Simple workflow example

name: 'VirusTotal Example'

on:
  release:
    types: [published]

jobs:
  test:
    name: 'Test'
    runs-on: ubuntu-latest
    timeout-minutes: 5

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

Full workflow example

name: 'VirusTotal Example'

on:
  release:
    types: [published]

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

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

      - 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 Scan'
    runs-on: ubuntu-latest
    needs: [windows]
    timeout-minutes: 5
    if: ${{ github.event_name == 'release' }}

    steps:
      - name: 'VirusTotal'
        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

Tags

The following rolling tags are maintained.

Tag	Example	Target	Bugs	Feat.	Description
	vN	vN.x.x	✅	✅	Includes new features but is always backwards compatible.
	vN.N	vN.N.x	✅	❌	Only receives bug fixes. This is the most stable tag.
	vN.N.N	vN.N.N	❌	❌	Not a rolling tag. Not recommended.

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

Planned Features

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

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:

• 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

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