We are pleased to offer runtime malware protection for our customers! Virus checking is available in two flavors - VirusTotal and Generic malware verification.

Both forms of virus scanning will only scan files downloaded from an external source during the package installation process. Packages which embed the software binaries will not have their binaries scanned by Chocolatey during installation.

Usage

When a binary is not flagged:

When a binary is flagged:

VirusTotal

We’ve teamed up with the amazing VirusTotal to offer a second opinion to your built-in anti-virus solution. When your packages download content from the internet, Chocolatey CLI will automatically check the executables prior to running any content. If a certain number of positives have been identified (configurable), Chocolatey CLI will fail the install automatically (but can be overridden).

VirusTotal scans binaries against over 50 different anti-virus scanners. Chocolatey CLI will use the information based on sending a SHA256 checksum of the binary to VirusTotal and evaluating what the scans have determined.

By default, the virus scanner is already enabled and set to VirusTotal for Pro licenses. Organizations are usually more wary about reaching out to the internet, so the feature is set to Generic and the virus scanner may not be enabled by default (because it needs configuration). If you need to configure the virus scanner to use VirusTotal, please run the following two commands:

WARNING

If package contents are not recognized by VirusTotal they may be uploaded to be scanned, and be viewable in public. If you package internal components we do not recommend you enable this feature with the VirusTotal virusScannerType.

• choco config set --name virusScannerType --value VirusTotal
• choco feature enable --name virusCheck

Because some scanners can be quite aggressive and may falsely identify a binary as a false positive for malware, Chocolatey CLI doesn’t flag a binary until a certain number of scanners have identified the binary as malware. This number defaults to 5 in the configuration. This means 5 anti-virus scanners need to flag the binary for Chocolatey CLI to stop and fail the install or upgrade. You can adjust this value in two ways, by adjusting the configuration and per Chocolatey CLI command.

To adjust the configuration value, which will globally set the number, please run the following replacing ## with the value you want as a minimum:

• choco config set --name virusCheckMinimumPositives --value ##

If you need to override the minimum number of positives just for one install or upgrade, you can do that by passing --virus-positives-minimum=VALUE with your install or upgrade commands.

Generic

If you are an organization, and you do not want to reach out to the internet for virus scan verification, you will want to take advantage of hooking Chocolatey CLI up to your existing AV solution.

Chocolatey CLI will just need to know the full path to the anti-virus command line executable, the arguments to pass, and valid exit codes (comma separated). Then you will get the same benefit of runtime virus checking as an added benefit on top of the protection it is already providing.

If you need to configure the virus scanner to use your built-in anti-virus solution, please run the following two commands:

• choco config set --name virusScannerType --value Generic
• choco config set --name genericVirusScannerPath --value "full path to av command line"
• choco config set --name genericVirusScannerArgs --value "[[File]]"
• choco config set --name genericVirusScannerValidExitCodes --value "0, ##"
• choco feature enable --name virusCheck

The genericVirusScannerPath should be the full path to the anti-virus command line executable. What we are looking for is the command line interface to the scanner.

In genericVirusScannerArgs, these are the arguments that Chocolatey CLI will pass to the anti-virus console. Chocolatey CLI will automatically replace [[File]] with the full path to the binary that it is scanning.

In genericVirusScannerValidExitCodes, these are exit codes that indicate that a binary is okay. This defaults to 0, but you can configure this with as many exit codes as necessary by adding them to the configuration as comma separated values.

Windows Defender Example Configuration

choco config set --name="'virusScannerType'" --value="'Generic'"
choco config set --name="'genericVirusScannerPath'" --value="'C:\Program Files\Windows Defender\MpCmdRun.exe'"
choco config set --name="'genericVirusScannerArgs'" --value="-Scan -ScanType 3 -File '[[File]]'"
choco config set --name="'genericVirusScannerValidExitCodes'" --value="'0'"
choco feature enable --name="'virusCheck'"

See It In Action

NOTE

To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b.

Options And Switches

The following options are added to install and upgrade commands.

    --svc, --skipvirus, --skip-virus, --skipviruscheck, --skip-virus-check
     Skip Virus Check - Skip the virus check for downloaded files on this ru-
       n. Overrides the default feature 'virusCheck' set to 'True'. Licensed 
       versions only.

     --virus, --viruscheck, --virus-check
     Virus Check - check downloaded files for viruses. Overrides the default
       feature 'virusCheck' set to 'True'. Licensed versions only.

     --viruspositivesmin, --virus-positives-minimum=VALUE
     Virus Check Minimum Scan Result Positives - the minimum number of scan
       result positives required to flag a package.  Used when
       virusScannerType is VirusTotal.  Overrides the default configuration
       value 'virusCheckMinimumPositives' set to '5'. Licensed versions only.

FAQ

How do I take advantage of this feature?

You must have a licensed edition of Chocolatey (Pro, Business, or MSP). Pro is a personal, named license that costs about the price of a lunch outing per month and comes with several other features. Business editions are great for organizations that need to manage the total software management lifecycle. MSP editions contain a subset of the Business edition features. MSPs are only able to use the Generic Virus Scanner.

I’m a licensed customer, now what?

WARNING

If package contents are not recognized by VirusTotal they may be uploaded to be scanned, and be viewable in public. If you package internal components we do not recommend you enable this feature with the VirusTotal virusScannerType.

When you install a package that download content, those items will automatically be verified if the feature is turned on (it is automatically turned on for Pro users). We don’t turn it on automatically in Business editions because many organizations are wary about reaching out to the internet and the generic virus scanner requires additional configuration.

How do I turn this feature on?

WARNING

If package contents are not recognized by VirusTotal they may be uploaded to be scanned, and be viewable in public. If you package internal components we do not recommend you enable this feature with the VirusTotal virusScannerType.

• Globally - choco feature enable --name virusCheck
• Per command - use the switch --virus-check with install/upgrade commands.

You need to provide additional configuration if you are using the Generic virus scanner.

How do I turn this feature off?

• Globally - choco feature disable --name virusCheck
• Per command - use the switch --skip-virus-check with install/upgrade commands.

How do I override the minimum number of positives?

• Globally - choco config set --name virusCheckMinimumPositives --value <value>
• Per command - use the option --virus-positives-minimum=<value> with install/upgrade commands.

How does the VirusTotal integration work?

• After a download, Chocolatey CLI will check a file against Virus Total’s scan engines to determine how safe the file is as a secondary check to the virus scanner you may already have running.
• If there are existing scan results, it will determine based on the number of positives whether the file is likely safe or not (you can adjust the minimum positives number up or down).
• If the number is over the minimum positives, it will require you to make the determination on the safety of the file. In other words, it will protect you by failing the install, but it will give you instructions on how to override Chocolatey CLI.
• If Chocolatey CLI doesn’t find a virus scan has been completed before, it will ask you if you want to upload the file. It will default to no (some users will have things they don’t want pushed publicly).
• Whether or not you choose to upload a file when no scan is found, the virus check will fail the install as a matter of protection. Chocolatey CLI will not make the determination if you got the file you were supposed to get from the source you thought you were getting it from, so it errors on the side of caution.
• A scan across all the engines can take a while, so it will fail with an error and notes on how you can move forward immediately if you trust the file. Virus scans can take up to 15 minutes, so it will request you try again in about 15 minutes.

How does VirusTotal verify the binary?

Chocolatey CLI gets the binary’s signature by getting a SHA256 checksum of the binary. A SHA256 checksum is extremely secure and accurate, SHA256 has not been broken. It then submits that value to VirusTotal to see if there are pre-existing results. If there are, due to the checksum, the file is the exact same binary. Then Chocolatey CLI inspects the results and determines if the file is safe or if it should fail.

What if VirusTotal doesn’t have results for a binary?

Chocolatey CLI will ask if you want the binary submitted to VirusTotal to be scanned (if the file is under 500MB). Then it will upload the binary their servers, ask you to try the install again in 15 minutes and fail the install. If this is running as a script, the question will time out after 30 seconds and default to no upload.

Do you have plans to offer better integration with particular anti-virus scanners?

Yes! If you are considering or have a business edition of Chocolatey, please let us know what you need, and we can get that scanner on the list. There are so many virus checking solutions and a generic scanner provides the best opportunity to serve all of them.