cPanel/ClamScanner
cPanel module

ClamScanner

6 functions, invoked through the cpanel_uapi tool.

scope cpanel:uapi
Call any function with cpanel_uapi(service_id, module="ClamScanner", function, params). Live availability depends on the cPanel features JetHost has enabled on your account — call list_cpanel_operations to see what is active.

check_disinfection_status GET#

Request disinfection process status

This function checks the status of the previously queued disinfection of infected files.

Note:

You must run the APIs in this order:

1. Run ClamScanner::start_scan to start the virus scan. 2. Run ClamScanner::get_scan_status in a loop until the scan is finished. 3. Run ClamScanner::list_infected_files to get a report of the complete list of infected files. 4. Decide how you want to handle each infected file. 5. Run ClamScanner::disinfect_files to queue the disinfection of the files. 6. Run ClamScanner::check_disinfection_status in a loop until you get a done status.

If you want to display the progress, you can render the ClamScanner::check_disinfection_status returned 'result{data}{details}' array where the type is step.

Each step record indicates the action taken on a specific file in the set being processed.

last_idintegerOptional
The unique id of the message you last received from this same log. The API will return only the records after the specified last_id. If this parameter is not provided, the entire log is returned. Note: For improved performance, we recommend applications include the last record ID (last_id) from a previous call to this API, so only messages since the previous API call are returned.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

detailsarray<any>
The list of events recorded in the log. If you pass the last_id parameter, only records in the log after that id are returned.
logstring
Path to the disinfection log file. The log file will contain a list of JSON objects one per line. If the last line includes "type":"done", the file disinfection is complete.
statusstring
done - The disinfection is finished. none - There is no disinfection scheduled. queued - The disinfection is queued. running - The disinfection is in progress.
One of: done queued running

disinfect_files POST#

Start disinfecting files with viruses

This function applies the disinfection option selected by the user for each infected file.

Note:

You must run the APIs in this order:

1. Run ClamScanner::start_scan to start the virus scan. 2. Run ClamScanner::get_scan_status in a loop until the scan is finished. 3. Run ClamScanner::list_infected_files to get a report of the complete list of infected files. 4. Decide how you want to handle each infected file. 5. Run ClamScanner::disinfect_files to queue the disinfection of the files. 6. Run ClamScanner::check_disinfection_status in a loop until you get a done status.

actionsobjectOptional
The user provides the actions to perform on each specific infected file found in the scan.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

logstring
Path to the disinfection log file. The log file will contain a list of JSON objects one per line. If the last line is: { "status": "done" } the requested files with viruses have be handled as requested. Use the /ClamScanner/check_disinfection_status API to check the status of a running or finished disinfection.
task_idstring
The Task Queue system's task ID number.

get_scan_paths GET#

Return virus scan types

This function gets the available local paths that a cPanel account is permitted to scan.

Note:

The system determines the available scan types based on what the system administrator has set in WHM's Configure ClamAV® page.

Note:

You must run the APIs in this order:

1. Run ClamScanner::start_scan to start the virus scan. 2. Run ClamScanner::get_scan_status in a loop until the scan is finished. 3. Run ClamScanner::list_infected_files to get a report of the complete list of infected files. 4. Decide how you want to handle each infected file. 5. Run ClamScanner::disinfect_files to queue the disinfection of the files. 6. Run ClamScanner::check_disinfection_status in a loop until you get a done status.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

idstring
The type of path home — The cPanel account's entire home directory. mail — The cPanel account's email directory. public_html — The cPanel account's web directory. public_ftp — The cPanel account's FTP directory.
One of: home mail public_html public_ftp
messagestring
Short description of the path

get_scan_status GET#

Request virus scan status

This function gets the status of a ClamAV® scan on a directory.

Note:

You must run the APIs in this order:

1. Run ClamScanner::start_scan to start the virus scan. 2. Run ClamScanner::get_scan_status in a loop until the scan is finished. 3. Run ClamScanner::list_infected_files to get a report of the complete list of infected files. 4. Decide how you want to handle each infected file. 5. Run ClamScanner::disinfect_files to queue the disinfection of the files. 6. Run ClamScanner::check_disinfection_status in a loop until you get a done status.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

current_filestring
The current file being scanned.
infected_filesarray<any>
List of files scanned and found to be infected.
scan_completeinteger
Whether the last scan has completed. 1 - scan has completed. 0 - scan has not completed.
One of: 0 1
scanned_file_countinteger
The number of files already scanned.
scanned_file_sizeinteger
The number of bytes of data scanned.
time_startedstring
The epoch timestamp of the beginning of the last scan.
total_file_countinteger
The total number of files found to scan.
total_file_size_MiBinteger
The total number of megabytes of data found to scan.

list_infected_files GET#

Return infected file list

This function lists infected files from a ClamAV® virus scan.

Note:

You must run the APIs in this order:

1. Run ClamScanner::start_scan to start the virus scan. 2. Run ClamScanner::get_scan_status in a loop until the scan is finished. 3. Run ClamScanner::list_infected_files to get a report of the complete list of infected files. 4. Decide how you want to handle each infected file. 5. Run ClamScanner::disinfect_files to queue the disinfection of the files. 6. Run ClamScanner::check_disinfection_status in a loop until you get a done status.

No parameters.

Response — normalized as { ok, data, errors[], warnings[] }; data is an array of:

filestring
An absolute path to the infected file on the system.
virus_typestring
A virus type.

start_scan GET#

Start virus scan

This function starts a ClamAV® scan on a directory.

Note:

You must run the APIs in this order:

1. Run ClamScanner::start_scan to start the virus scan. 2. Run ClamScanner::get_scan_status in a loop until the scan is finished. 3. Run ClamScanner::list_infected_files to get a report of the complete list of infected files. 4. Decide how you want to handle each infected file. 5. Run ClamScanner::disinfect_files to queue the disinfection of the files. 6. Run ClamScanner::check_disinfection_status in a loop until you get a done status.

scan_typemixedRequired
The type of directory to scan. home — User's entire home directory mail — User's email directory public_html — User's web directory public_ftp — User's ftp directory

Response — normalized as { ok, data, errors[], warnings[] }; data contains:

Payload varies by call.