Set up the antivirus scan

Note

To configure Content Hub, you must either be a superuser or have the necessary permissions granted to you through user group policies.

Sitecore Content Hub has an antivirus scan feature that activates when users upload assets through the Creation component or an Excel import. As part of an antivirus package, this feature scans files for viruses and harmful items.

Important

Our antivirus scan feature is not a standalone tool, but a component of an antivirus package. To use it, you must provision your own antivirus tool and integrate it with the antivirus scan in Content Hub.

When the antivirus feature is enabled and you upload an asset, the uploaded file is assigned a virus scan result value. This value is displayed on the System tab of the asset details page and can be any of the following:

Ok - the scan passed or the antivirus is disabled. Files can be downloaded.
Unknown - the antivirus feature is enabled but there is no external task configured. Files can be downloaded.
Pending - the antivirus scan is not yet completed. Depending on how the antivirus scan is configured, the rendition status for the related asset and the M.File entity definition might also be marked as Pending. Files cannot be downloaded.

Note

If an external processing task is improperly formatted, the request made by the external task is not successful, or the antivirus scan does not return a valid response to Content Hub, the virus scan result and the associated background processing job will remain in the Pending state, even if all the other tasks in the job have completed.
Malicious - a virus was detected. Files cannot be downloaded.
Error - the antivirus scan failed. Files cannot be downloaded.

This walkthrough describes how to:

Enable the antivirus scan
Create a media processing set
Set up an external web task
Configure the M.MediaMatrix entity
Complete the antivirus scan
Test the malicious file alert trigger

Enable the antivirus scan

To enable the antivirus scan:

On the menu bar, click Manage .
On the Manage page, click Settings.
On the Settings page, find and click AntivirusSetting.

In the AntivirusSetting section, change the Editor mode to true and then set the antivirusEnabled flag to true.

RequestResponse

{
  "antivirusEnabled": true,
  "renditionBagsToClear": [
    "Renditions",
    "ExtraRenditions"
  ],
  "renditionsToMarkMalicious": {
    "Renditions": [
      "thumbnail",
      "thumbnail_cropped",
      "preview"
    ],
    "ExtraRenditions": []
  },
  "flowOnly": false
}

Click Save.

Create a media processing set

To create a media processing set:

On the menu bar, click Manage .
On the Manage page, click Media processing.
On the Media processing page, click New set.
In the New set dialog, enter an appropriate name, for example, Antivirus.
Optionally, if you want to automatically apply this set to all new assets, turn on the Auto-run switch.
Click Create.

Set up an external web task

Because the antivirus scan functionality makes a call to an external service API, it requires a RunExternalWebTask processing task configured in the M.MediaMatrix entity for the related media flow.

Note

An external web task is a webhook that Content Hub uses in file processing to create predefined conversions known as renditions.

To set up an external web task:

On the menu bar, click Manage .
On the Manage page, click Media processing.
On the Media processing page, click the set you created (for example, Antivirus) and then click Add flow.
In the Flow settings dialog, enter a name in the Name field, for example, Antivirus.
If you want the flow to only scan specific types of files, enter those types in the File types field, such as zip, 7z, tar, or gz.
Click Save.
On the media processing set details page, click the new flow.
On the details page of the new flow, click the sign and, in the right-hand pane, click Run external web task.
On the Parameters tab, fill in the fields as follows:
- Name - enter Antivirus.
- Content type - leave blank.
- Content disposition - from the list, click Attachment.
- URL - enter a URL that points to the external antivirus scan service of your choice.
On the Outputs tab, to enable outputs, turn on the Store output switch and then fill in the fields as follows:
- Output type - click Property in the drop-down list.
- Property - click Virusscan result in the drop-down list.
Click Save task, then Save and Close.
Click Publish.

Configure the M.MediaMatrix entity

Before configuring the M.MediaMatrix entity, you must first retrieve the media set ID, which is displayed in the URL.

To retrieve the media set ID:

On the menu bar, click Manage .
On the Manage page, click Media processing.
On the Media processing page, click one of the media sets in the list.
Copy the ID that displays at the end of the URL. In the following example, for the Content media set, the ID is 1014.
RequestResponse
```
`https://<HOSTNAME>/en-us/admin/media-processing-mgmt?mediaMatrixManagementSelectedMatrix=1014`
```

To configure the M.MediaMatrix entity:

On the Manage page, click Entities.
To the Entities page URL, append /entity/ followed by the media set ID, and press Enter.
RequestResponse
```
https://<HOSTNAME>/en-us/admin/entitymgmt/entity/1014
```
On the Entity detail page, on the System tab, click Edit .
To change the conversion matrix JSON, in the Matrix section, from the drop-down list, click Text.

To set up antivirus for archives, for example, search for the Archives node and make sure that the following JSON code comes first under tasks:

RequestResponse

  "antivirus": {
    "type": "RunExternalWebTask",
    "do update": true,
    "input": "source",
    "output": "antivirus",
    "outputfileprovider": "local",
    "contentdisposition": "attachment",
    "url": "http://beeceptor.com/console/testsitecore-antivirus",
    "parameters": {},
    "headers": {}
  }

The same process applies to any other category for which you want to set up antivirus.

Add an antivirus dependency in the metadata entry of the Archives node as follows:
RequestResponse
```
"deps": [
  "antivirus"
]
```
Store the scan output in the antivirus property of the file as follows:
RequestResponse
```
"properties": {
  "VirusScanResult": "antivirus"
}
```
Click Save.

Complete the antivirus scan

To be complete, the antivirus scan needs to return a valid response to Content Hub. You can verify if this is the case by sending a POST request.

To complete the antivirus scan:

Upload an asset. This triggers the external web task, which sends a request with the following format in the body:
RequestResponse
```
{
    "callback": "https://callback-url",
    "sources": [ "https://blob-sas-url" ],
    "parameters": {}
}
```
Send a POST request containing the following request body to the callback URL:
RequestResponse
```
  {
    "value": "Malicious"
  }
```

The value in the request body can be any of the following:

Malicious - an issue was detected.
Ok - no issues were found.
Error - the antivirus scan failed.

If the POST request is successful, the antivirus is working as expected. If Content Hub doesn't receive a response to the POST request, the VirusScanResult and the associated processing job remain in the Pending state.

Note

When you upload an asset in the Content Hub interface through the Creation component or through an Excel import, if the file is considered malicious by the chosen antivirus service, the file details page displays a warning that downloads of the file are now disabled. When this happens, the file thumbnail and associated renditions are replaced by placeholders.

Test the malicious file alert trigger

Using an API call, you can test what happens when a file is flagged as malicious.

To test the malicious file alert trigger:

Set the URL to an API endpoint, such as http://beeceptor.com/console/testsitecore-antivirus.

Upload an asset to trigger the external web task. The request body has the following format:

RequestResponse

{
    "callback": "https://callback-url",
    "sources": [ "https://blob-sas-url" ],
    "parameters": {}
}

Copy the callback URL from the endpoint.
Send a POST request containing the following code to the callback URL:
RequestResponse
```
  {
    "value": "Malicious"
  }
```

Do you have some feedback for us?

If you have suggestions for improving this article,