Documentation Command-Line Interface
Description
ImunifyAV(+) command-line interface (CLI) makes working with ImunifyAV(+) basics and features from your terminal even simpler.
Note
CLI commands are available only for cPanel and DirectAdmin control panels. Plesk and ISPmanager CLI support is coming soon.
Usage
For access to the ImunifyAV agent features from the command-line interface, use the following command:
imunify-antivirus
Basic usage:
imunify-antivirus [command] [--option1] [--option2]...
Options
The following options are available for all commands.
-h, --help | show this help message and exit |
--console-log-level {ERROR,WARNING,INFO,DEBUG} | level of logging input to the console |
--json | returns data in JSON format |
--verbose, -v | allows to return data in good-looking view if option --json is used |
Examples
- This command allows to show help for the
startcommand:imunify-antivirus start [-h]
Available commands:
add-sudouser | add a user with root privileges |
checkdb | check database integrity |
check-domains | send domain list check |
config update | update configuration file via CLI |
delete-sudouser | remove a user with root privileges |
doctor | collect info about the system and send it to ImunifyAV(+) |
infected-domains | returns infected domain list |
feature-management | manage ImunifyAV(+) features available for users |
hooks | hooks-related operations |
malware | malware-related operations |
notifications-config | allows to update notifications in the configuration file via CLI |
register | register the agent |
rstatus | send a query to server to the check if the license is valid |
start | start the agent |
submit false-positive/false-negative | allows to submit a file as false positive/false negative |
unregister | unregister the agent |
update | update malware signatures |
update-license | force license update |
version | show version |
Add-sudouser
This command adds a user with root privileges to the server.
Usage:
imunify-antivirus add-sudouser <userID> [--optional arguments]
Example:
This command adds the user 11XXX111 with root privileges to the server:
imunify-antivirus add-sudouser 11XXX111
OK
Checkdb
Checks database integrity. In case database is corrupt, then this command saves backup copy of the database at /var/imunifyav and tries to restore integrity of the original database.
Note
If this command cannot restore database integrity, then it will destroy the original broken database.
Usage:
imunify-antivirus checkdb [--optional arguments]
Example:
The following command checks the database integrity:
imunify-antivirus checkdb
Check-domains
Allows to send domains list to check on ImunifyAV central server. This command requires cPanel. After domains checked, the results is available via the infected-domains command.
Note
check-domains command may take a few minutes to complete.
Usage:
imunify-antivirus check-domains [--optional arguments]
Example:
The following command sends the domains list for a check to the Imunify central server. In case there are no infected domains found on the server, you will see no output. If there are any, you will get the following output:
imunify-antivirus check-domains
'domain1.com'
'domain2.com'
Config update
Allows to update configuration file via CLI.
Usage:
imunify-antivirus config update [configuration options]
You can find instructions on how to apply configuration changes from CLI here and configuration options can be taken from the /etc/sysconfig/imunify360/imunify360.config file.
Example:
Set the MALWARE_SCAN_INTENSITY.cpu = 5 configuration option from a command line:
imunify-antivirus config update '{"MALWARE_SCAN_INTENSITY": {"cpu": 5}}'
The successful output should display the configuration file content.
Delete-sudouser
This command removes a user with root privileges from the server.
Usage:
imunify-antivirus delete-sudouser <userID> [--optional arguments]
Example:
The following command removes the user 11XXX111 with root privileges from the server.
imunify-antivirus delete-sudouser 11XXX111
OK
Doctor
This command collects information about ImunifyAV state, generates the report and sends it to the ImunifyAV Support Team. This command can be used in case of any troubles or issues with ImunifyAV. This command will generate a key to be sent to the ImunifyAV Support Team. With that key the ImunifyAV Support Team can help with any problem as fast as possible.
Usage:
imunify-antivirus doctor [--optional arguments]
The successful output will contain the unique set of symbols, for example:
imunify-antivirus doctor
Please, provide this key:
SSXX11xXXXxxxxXX.1a1bcd1e-222f-33g3-hi44-5551k5lmn555
to Imunify360 Support Team
Infected-domains
Allows to retrieve infected domains list.
Usage:
imunify-antivirus infected-domains [-h] [--optional arguments]
Optional arguments for list:
--limit | Limits the output with the specified number of domains. Must be a number greater than zero. By default, equals 100. |
--offset | Offset for pagination. By default, equals 0. |
Example:
The following command displays the results of the check-domains command. In case there are no infected domains found on the server, you will see no output. If there are any, you will get the following output:
imunify-antivirus infected-domains
'domain1.com'
'domain2.com'
Feature-management
Allows to manage ImunifyAV features available for users.
Usage:
imunify-antivirus feature-management [command] [--optional argument]...
Command can be one of the following:
defaults | show the default value for each feature that is applied for newly created user |
disable | disable a feature for some or all users |
enable | enable a feature for some or all users |
get | obtains the status of all available features for a USER |
list | list all available features |
Optional argument for the enable/disable commands can be one of the following:
[--feature av] | enable/disable Malware Cleanup |
[--feature proactive] | enable/disable Proactive Defense |
[--users [USERS [USERS ...]]] | specifies the list of users which will be affected, otherwise the default value will be changed |
The mandatory argument for the get command:
[--user USER] | specifies a user name to obtain the status of features for |
Example:
The following command enables malware cleanup feature for the user1. If the operation is successful for the user user1, you will receive the following reply:
imunify-antivirus feature-management enable --feature av --users user1
failed: []
succeeded:
- user1
Hooks Deprecated
Warning!
You can use a new notification system via CLI.
You can read more about hooks here.
This command allows to manage hooks.
Usage:
imunify-antivirus hook [command] --event [event_name|all] [--path </path/to/hook_script>]
command can be one of the following:
add | register a new event handler |
delete | unregister existing event handler |
list | show existing event handlers |
add-native | register a new native event handler |
--event [event_name|all] | defines a particular event that invokes a registered handler as opposed to all keyword |
--path </path/to/hook_script> | shall contain a valid path to a handler of the event, it shall be any executable or Python Native event handlers that agent will run upon a registered event |
Example:
The following command shows existing event handlers. If you have any hooks configured, the output will include something similar to this:
imunify-antivirus hook list --event all
Event: malware-detected, Path: /root/directory/IMAVscannereventhooks/malware_detected.py
Login
Allows to get a token which can be used for authentication in stand-alone Imunify UI.
Usage:
imunify-antivirus login [command] [--optional arguments]
command can be one of the following:
get | returns a token for USERNAME (must be executed by root) |
pam | uses PAM to check the provided credential and returns a token for USERNAME if PASSWORD is correct |
Optional arguments for get:
--username USERNAME |
Optional arguments for pam:
--username USERNAME |
--password PASSWORD |
Example:
You can use the login get command to implement your own authorization mechanism for stand-alone ImunifyAV.
For example, you can generate tokens for users which are already authorized in your system/panel, and redirect to stand-alone Imunify UI with ?token=<TOKEN> in URL. (You can also set it in localStorage: localStorage.setItem('I360_AUTH_TOKEN', '<TOKEN>');)
imunify-antivirus login get --username my-user1
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MDAyNDQwMTAuMDk5MzE5LCJ1c2VyX3R5cGUiOiJjbGllbnQiLCJ1c2VybmFtZSI6ImNsdGVzdCJ9.V_Q03hYw4dNLX5cewEb_h46hOw96KWBWP0E0ChbP3dA
Malware
Allows to manage malware options.
Usage:
imunify-antivirus malware [command] [--optional arguments]
Available commands:
ignore | malware Ignore List operations |
malicious | malware Malicious List operations |
on-demand | on-demand Scanner operations |
suspicious | malware Suspicious List operations |
cleanup status | show the status of the cleanup process |
history list | lists the complete history of all malware-related incidents/actions (optional arguments available) |
rebuild patterns | allows to save changes after editing the excluded patterns for Malware Scanner. See details here |
user | allows to perform Malware Scanner operations for a user |
Optional arguments:
--limit LIMIT | Limits the output with the specified number of domains. Must be a number greater than zero. By default, equals 100. |
--offset OFFSET | Offset for pagination. By default, equals 0. |
--since SINCE | Start date. |
--to TO | End date. |
--user USER | Returns results for a chosen user. |
--order-by [ORDER_BY [ORDER_BY ...]] | Sorting order. |
--by-status [BY_STATUS [BY_STATUS ...]] | Return items with selected status. |
--by-scan-id BY_SCAN_ID | Return items with selected ID. |
--items ITEMS | Return selected items. |
--search SEARCH | Search query. |
action is the second positional argument for ignore and can be one of the following:
add | add file PATHS to the Ignore List |
delete | delete file PATHS from the Ignore List |
list | shows Ignore List entries (optional arguments apply) |
where PATHS are the absolute paths to files or folders divided by a whitespace.
command2 is the second positional argument for the malicious command and can be one of the following:
cleanup | clean up infected ITEMS for a USER |
cleanup-all | clean up all files that have been detected as infected for all users |
restore-original | restore the original (malicious/infected) file to its original location |
list | list malicious/infected files |
move-to-ignore | move a Malicious List entry to the (malware) Ignore List |
remove-from-list | remove malicious/infected files from the Malicious List |
restore-from-backup | restore a clean version of infected file from backup |
action is the second positional argument for on-demand and can be one of the following:
list | list all on-demand scans performed |
start --path PATH | starts an on-demand scan for a specified PATH |
status | show the on-demand malware scanner status |
stop | stop on-demand malware scanner process |
queue put | put file PATHS to the queue for on-demand scan |
queue remove | remove scans from the queue for on-demand scan |
The optional arguments for on-demand start and on-demand queue put are:
--ignore-mask IGNORE_MASK |
--follow-symlinks |
--no-follow-symlinks |
--file-mask FILE_MASK |
--intensity-cpu {1 to 7} 1 means the lowest intensity, 7 means the highest intensity |
--intensity-io {1 to 7} 1 means the lowest intensity, 7 means the highest intensity |
action is the second positional argument for suspicious and can be one of:
list | obtain the list of Suspicious List entries |
move-to-ignore | move a Suspicious List entry to the (malware) Ignore List |
action is the second positional argument for user and can be one of the following:
cleanup USER | clean all infected files for a user |
restore-original USER | restore all original files for a user |
list | list all users and their current infection status |
scan | scan all users |
Examples
- The following command starts on-demand scanner for the path specified after the
startcommand:
imunify-antivirus malware on-demand start --path /home/<username>/public_html/
- The following command shows the example of the
ignore-maskusage when you have to scan alld*folders except for thedixon77w.comanddunnrrr.com:
imunify-antivirus malware on-demand start --path='/var/www/vhosts/d*' --ignore-mask='/var/www/vhosts/dixon77w.com/*,/var/www/vhosts/dunnrrr.com/*'
- The following command adds on-demand scans for the selected path(s) to the scan queue
imunify-antivirus malware on-demand queue put "/home/user1/some folder" "/home/user2" --file-mask="*.php"
- The following command removes the selected scans from the scan queue
imunify-antivirus malware on-demand list # get scan_ids for the selected scans from the malicious list
imunify-antivirus malware on-demand queue remove 84f043211dc045ae8e6d641f3b9fdb0a 8c4ee39d4d8f43e296e893940c8e791a
- The following command stops the on-demand Malware Scanner process
imunify-antivirus malware on-demand stop
- The following command stops the on-demand Malware Scanner process and clears the scan queue
imunify-antivirus malware on-demand stop --all
- The following command shows how to get an extended list of malicious files for a particular user. By default, a limit value equals to 50
imunify-antivirus malware malicious list --user cltest --limit 500
CLEANED_AT CREATED EXTRA_DATA FILE HASH ID MALICIOUS SCAN_ID SCAN_TYPE SIZE STATUS TYPE USERNAME
None 1599955297 {} /home/cltest/public_html/test/TsMeJD.php 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f 1627 True 1996cd86e6b14b12a1c165e79e3540d9 background 68 found SMW-SA-05057-eicar.tst-4 cltest
None 1599955297 {} /home/cltest/public_html/test/TZlfnU.php 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f 1628 True 1996cd86e6b14b12a1c165e79e3540d9 background 68 found SMW-SA-05057-eicar.tst-4 cltest
None 1599955297 {} /home/cltest/public_html/test/Ke7V8n.php 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f 1629 True 1996cd86e6b14b12a1c165e79e3540d9 background 68 found SMW-SA-05057-eicar.tst-4 cltest
None 1599955297 {} /home/cltest/public_html/yoUq0L.php 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f 1630 True 1996cd86e6b14b12a1c165e79e3540d9 background 68 found SMW-SA-05057-eicar.tst-4 cltest
None 1599955297 {} /home/cltest/public_html/test/PKiuhY.php 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f 1631 True 1996cd86e6b14b12a1c165e79e3540d9 background 68 found SMW-SA-05057-eicar.tst-4 cltest
None 1599955297 {} /home/cltest/public_html/public_html/Zqrsvh.php 275a021bbfb6489e54d471899f7db9d1663fc695
- The following command adds the specified path to the Ignore List
imunify-antivirus malware ignore add /home/user1/public_html/ "/home/some user/public_html/index.php"
- The following command lists all users and their current infection status
imunify-antivirus malware user list
The successful initiation/stopping of a scanning process or adding of ignore directories/files should give you OK in the output.
Notifications config
Allows administrators to execute custom scripts on events execution.
Usage:
imunify-antivirus notifications-config [command] [configuration options]
command can be:
show | returns the full config as a JSON |
update | updates the config (partial update is supported) and returns the full updated config as a JSON |
We advise administrators to use the notifications-config show to get the full config, pick what they want to edit, and feed it to the notifications-config update.
The general structure of the imunify-antivirus notifications-config show command output:
{
"rules": {
"USER_SCAN_FINISHED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"USER_SCAN_MALWARE_FOUND": {
"SCRIPT": {
"scripts": [],
"enabled": False
},
"ADMIN": {
"admin_emails": [],
"enabled": False
}
},
"USER_SCAN_STARTED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"CUSTOM_SCAN_STARTED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"CUSTOM_SCAN_FINISHED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"CUSTOM_SCAN_MALWARE_FOUND": {
"SCRIPT": {
"scripts": [],
"enabled": False
},
"ADMIN": {
"admin_emails": [],
"enabled": False
}
}
},
"admin": {
"notify_from_email": None,
"default_emails": []
}
}
Let's review all the options.
Rules:
- USER_SCAN_FINISHED – occurs immediately after the user scanning has finished, regardless the malware has found or not.
- USER_SCAN_MALWARE_FOUND – occurs when the malware scanning process of a user account has finished and malware found.
- USER_SCAN_STARTED – occurs immediately after the user scanning has started.
- CUSTOM_SCAN_STARTED – occurs immediately after on-demand (manual) scanning has started.
- CUSTOM_SCAN_FINISHED – occurs immediately after on-demand (manual) scanning has finished, regardless the malware has found or not.
- CUSTOM_SCAN_MALWARE_FOUND – occurs when the on-demand scanning process has finished and malware found.
Admin:
- default_emails – specify the default list of emails used for all enabled admin email notifications.
- notify_from_email – specify a sender of all emails sent by the Hooks.
Examples:
- Update admin default emails:
imunify-antivirus notifications-config update '{"admin": {"default_emails": ["email1@email.com", "email2@email.com"]}}'
After the successful execution, the imunify-antivirus notifications-config update command returns the full config with changes.
The imunify-antivirus notifications-config show command output after applying the example 1:
{
"rules": {
"USER_SCAN_FINISHED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"USER_SCAN_MALWARE_FOUND": {
"ADMIN": {
"admin_emails": [],
"enabled": False
},
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"CUSTOM_SCAN_STARTED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"USER_SCAN_STARTED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"CUSTOM_SCAN_FINISHED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"CUSTOM_SCAN_MALWARE_FOUND": {
"ADMIN": {
"admin_emails": [],
"enabled": False
},
"SCRIPT": {
"scripts": [],
"enabled": False
}
}
},
"admin": {
"notify_from_email": None,
"default_emails": ["email1@email.com", "email2@email.com"]
}
}
More examples:
- Run the custom script on the USER_SCAN_FINISHED event occurrence:
imunify-antivirus notifications-config update '{"rules": {"USER_SCAN_FINISHED": {"SCRIPT": {"scripts": ["/script/my-handler.py"], "enabled": true}}}}'
After the successful execution, the imunify-antivirus notifications-config update command returns the full config with changes.
The imunify-antivirus notifications-config show command output after applying the example 2:
{
"rules": {
"CUSTOM_SCAN_MALWARE_FOUND": {
"SCRIPT": {
"scripts": [],
"enabled": False
},
"ADMIN": {
"enabled": False,
"admin_emails": []
}
},
"USER_SCAN_STARTED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"CUSTOM_SCAN_FINISHED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"CUSTOM_SCAN_STARTED": {
"SCRIPT": {
"scripts": [],
"enabled": False
}
},
"USER_SCAN_MALWARE_FOUND": {
"SCRIPT": {
"scripts": [],
"enabled": False
},
"ADMIN": {
"enabled": False,
"admin_emails": []
}
},
"USER_SCAN_FINISHED": {
"SCRIPT": {
"scripts": ['/script/my-handler.py'],
"enabled": True
}
}
},
"admin": {
"notify_from_email": None,
"default_emails": ["email1@email.com", "email2@email.com"]
}
}
Example of script to create custom scripts to use with notifications-config
There are two script examples you can download:
You can use these scripts as a reference and customize them.
Note
Set the +x bits to your script file to make it executable. Your script also has to be readable by the special _imunify user, so make sure of setting group's permission accordingly:
chown root:_imunify hook_script.sh
Python script description
The agent generates messages of different types on hook events. The ‘if chain’ in the script calls the particular method corresponding to type of the event that came from the agent.
To unblock user sites which were scanned as clean, you can use the handle_user_scan_finished method.
Add your path to the related hook (or multiple hooks) and implement the custom logic of blocking and unblocking sites.
Also in this script you could find the way to parse JSON that come from ImunifyAV(+) and description of this JSON schema in every possible case. Such descriptions are provided by docstring of the handle methods.
Register
Allows to register and activate ImunifyAV. You can use it in case if ImunifyAV was not activated during installation process or in case if activation key of the ImunifyAV was changed for any reason. If you do not know what is an activation key or have any problem with it then, please, read Installation Guide or contact our support team.
Usage:
imunify-antivirus register [--optional arguments] [KEY]
KEY is a positional argument:
KEY | register with activation key (use IPL to register by IP) |
If you will use this command without the KEY argument, then it will try to register and activate current activation key.
Example 1: The following command will register and activate Imunify360 with the provided activation key:
imunify-antivirus register IMAV250jjRRjowbjk56dGN
OK
Example 2:
If you have an IP-based license, you can use IPL argument to register and activate ImunifyAV:
imunify-antivirus register IPL
OK
Rstatus
Allows to check if ImunifyAV server license is valid.
Usage:
imunify-antivirus rstatus [--optional arguments]
An extended variation (otherwise, you receive OK if everything is fine with the license registered):
imunify-antivirus rstatus --json -v
{
"expiration": null,
"id": "SSXX11xXXXxxxxXX",
"ip_license": false,
"license": {
"expiration": null,
"id": "SSXX11xXXXxxxxXX",
"ip_license": false,
"license_type": "imunify-antivirus",
"message": " ",
"status": true,
"upgrade_url": " ",
"user_count": 100,
"user_limit": 2147483647
},
"license_type": "imunify-antivirus",
"message": " ",
"status": true,
"upgrade_url": " ",
"user_count": 100,
"user_limit": 2147483647,
"version": "5.1.2-1"
}
Submit false-positive/false-negative
To submit file as false positive for analysis (if ImunifyAV considers file as a malicious but it actually isn't), you can use the following command (please make sure to specify the file name along with full path):
imunify-antivirus submit false-positive <file>
To submit file as false negative for analysis (if ImunifyAV considers file as a non-malicious but it actually does), you can use the following command (please make sure to specify the file name along with full path):
imunify-antivirus submit false-negative <file>
Optional arguments:
-h, --help | show this help message and exit |
Unregister
Allows to unregister and disable ImunifyAV on the server.
Usage:
imunify-antivirus unregister [--optional arguments]
OK
Update
This command allows updating ImunifyAV malware signatures.
Usage:
imunify-antivirus update sign
OK
Update-license
This command force updating the ImunifyAV license.
Usage:
imunify-antivirus update-license [--optional arguments]
OK
Version
Allows to show the actual ImunifyAV version installed on the server.
Usage:
imunify-antivirus version [--optional arguments]
5.1.2-1
How to apply changes from CLI
In order to apply changes via command-line interface (CLI), you can use the following command:
imunify-antivirus config update '{"SECTION": {"parameter": value}}'
For example, if you want to set MALWARE_SCAN_INTENSITY.cpu = 5 from a command line, then you should execute the following command:
imunify-antivirus config update '{"MALWARE_SCAN_INTENSITY": {"cpu": 5}}'
imunify-antivirus config update '{"MALWARE_SCANNING": {"rapid_scan": true}}'
It is also possible to apply several parameters at once.
For example:
imunify-antivirus config update '{"MALWARE_SCAN_INTENSITY": {"cpu": 5, "io": 7}}'
