modifySMART — Setting SMART File Scan configuration settings

The modifySMART method configures the SMART settings for a site.

The API endpoint is:

https://api.sitelock.com/v1/partner

Request format

SiteLockOnlineRequest: This element is used to delineate the full API request.
- authentication: The partner’s username, password, and branding
  - username: The partner’s API username
  - password: The partner’s API password
  - partner: (Optional) The brand name to use in messaging
- modifySMART: The method name
  - site_id: The ID of the site
  - docroot: The directory where the web files are located. When using the FTP or FTPS protocols, the docroot directory should be relative to the home directory of the FTP account. When using SFTP, we recommend you use the full path from the system root directory to the specific web file directory.
  - exclude_dirs: (Optional, repeatable) The directory to exclude from the scan The directory can exist anywhere in the path under docroot. No forward slash (/) needed.
  - exclude_exts: The types of files to exclude from the scan
  - exclude_files: The files to exclude from the scan by name
  - frequency: The frequency of the scan. The possible values are daily, weekly, monthly, quarterly, continuous, and never.
  - ftp_host: The hostname or IP address of the FTP server
  - ftp_timeout: The number of seconds the scan should try to download files before it stops trying and times out.
  - ftp_user: The FTP username for the file download process
  - ftp_pw: The FTP password. If you’re using SSH key authentication, pass gen_ssh_key instead.
  - gen_ssh_key: Specifies whether to generate an SSH key pair for access through the SFTP protocol. You can omit this element if a key pair already exists. If you’re using password authentication, pass ftp_pw instead. The possible values are:
    
    yes: Generate a new SSH key pair.
    
    no: (Optional) Use an existing SSH key pair. This value is retained for backwards compatibility.
  - methods: The methods used to download files
    
    ftp: Standard FTP download of files
  - protocol: The file transfer protocol. The possible values are ftp, ftps, and sftp.
  - port: Specify this if FTP/FTPS/SFTP is running on a non-default port (port 21 for FTP/FTPS, port 22 for SFTP).
  - parallel: The number of FTP threads allowed to run in parallel
  - auto_fix: Specifies whether SiteLock SMART should automatically fix the malware that it finds, or just alert the user via the dashboard. The possible values are:
    
    fix: Automatically removes malware from infected files and alerts the user
    
    warn: Files containing malware are identified, and the user is alerted. However, the malware isn’t removed automatically.
  - status: The state of the SMART File Scan. The possible values are:
    
    active: Enables the scan after you have disabled it for the site.
    
    inactive: Disables the scan for the site.
    
    911: Runs the scan at an increased frequency. This value requires a qualifying plan or add-on. The response returns the SMART status to the appropriate value after the user’s site is clean, and a certain period has elapsed. Partners aren’t required to return the state of the SMART File Scan to a different value.

Example request

<SiteLockOnlineRequest>
    <authentication>
        <user>Username</user>
        <password>Password</password>
    </authentication>
    <modifySMART>
        <site_id>10900</site_id>
        <docroot>public_html</docroot>
        <exclude_dirs>stats</exclude_dirs>
        <exclude_exts>gz</exclude_exts>
        <exclude_exts>tgz</exclude_exts>
        <exclude_exts>tar</exclude_exts>
        <exclude_files>test.php</exclude_files>
        <frequency>daily</frequency>
        <ftp_host>ftp.ipower.com/</ftp_host>
        <ftp_pw>doe_124</ftp_pw>
        <ftp_timeout>1800</ftp_timeout>
        <ftp_user>john_doe</ftp_user>
        <methods>
            <ftp>1</ftp>
        </methods>
        <parallel>1</parallel>
        <port>21</port>
        <protocol>ftp</protocol>
        <status>active</status>
    </modifySMART>
</SiteLockOnlineRequest>

Response format

SiteLockOnlineResponse: This element is used to delineate the full API response.
- modifySMART: The method name
  - msg: This element is present when the request is successful. The message refers to what was done to the SMART settings record for this site. The possible values are added and updated.
  - connection_msg: This field is deprecated but retained in for historical reasons.
  - error: This element is present if the request failed. The possible values are:
    
    no_dir: The requested directory wasn’t found on the FTP server.
    
    bad_conn_max_retries: SiteLock reached the maximum number of connection retry attempts.
    
    get_pass_failed: SiteLock couldn’t get access to the FTP server because of invalid credentials.
    
    bad_name: SiteLock couldn’t find the FTP server or connect to it.
    
    access_denied: SiteLock was denied access to the FTP server.
    
    cannot_upload_file: SiteLock doesn’t have the write permission on the FTP server.
  - warning: This element is present if modifySMART returned an error and the site has Backup product. The possible values are:
    
    no_dir: The requested directory wasn’t found on the FTP server.
    
    bad_conn_max_retries: SiteLock reached the maximum number of connection retry attempts.
    
    get_pass_failed: SiteLock couldn’t get access to the FTP server because of invalid credentials.
    
    bad_name: SiteLock couldn’t find the FTP server or connect to it.
    
    access_denied: SiteLock was denied access to the FTP server.
    
    cannot_upload_file: SiteLock doesn’t have the write permission on the FTP server.

Example success response

<SiteLockOnlineResponse>
    <modifySMART>
        <msg>updated</msg>
        <connection_msg>ok</connection_msg>
    </modifySMART>
</SiteLockOnlineResponse>

Example error response

<SiteLockOnlineResponse>
    <modifySMART>
        <warning>backup_files - cannot_upload_file</warning>
        <error>cannot_upload_file</error>
        <connection_msg>cannot_upload_file</connection_msg>
    </modifySMART>
</SiteLockOnlineResponse>

Example request modifySMART with gen_ssh_key set to yes

SMART uses ssh key, partner needs to follow three steps:

Call modifySMART with <gen_ssh_key>yes</gen_ssh_key>.
Add ssh_pub_key to the user on your server.
Call modifySMART with <gen_ssh_key>no</gen_ssh_key> (to validate SiteLock can connect using the ssh key).

<SiteLockOnlineRequest>
    <authentication>
        <user>reseller_login</user>
        <password>Password</password>
        <partner>Brand</partner>
    </authentication>
    <modifySMART>
        <site_id>12345</site_id>
        <docroot>/home/user/public_html</docroot>
        <ftp_host>123.123.123.123</ftp_host>
        <ftp_user>username</ftp_user>
        <auto_fix>fix</auto_fix>
        <protocol>sftp</protocol>
       <ftp_timeout>4280</ftp_timeout>
       <gen_ssh_key>yes</gen_ssh_key>
    </modifySMART>
    </SiteLockOnlineRequest>

Minimum values required to successfully configure SMART

The following elements must be specified in the request to successfully configure SMART:

site_id
docroot
ftp_host
ftp_user
ftp_pw

The following defaults will be used for other fields:

exclude_files: NULL
exclude_exts: NULL
exclude_dirs: NULL
methods: ftp
parallel: 1
php_retries: 5
php_timeout: 30 (minutes)
ftp_timeout: 3600 (seconds)
frequency: daily
auto_fix: warn
status: active
exclude_exts: A generic list of binary files are excluded by default, for example: mp4,m4v,eps,mov,wmv,tar,jpa,mp3,flv,zip,gz,sql,jpg,tgz,pptx,doc,docx,pdf,gif,rar,avi,wav,png,mpeg,omf,tif

Configuring SMART for multiple sites in one call

You may combine the modifySMART calls for up to 250 sites in one call by wrapping bulkModifySMART tags around repeated modifySMART nodes.

SiteLock loops through and processes each modifySMART node individually, so the contents of this node and the rules that govern them are identical to the modifySMART call. You may use it to specify every setting, or to specify just the ftp user, password and docroot.

Example request

<SiteLockOnlineRequest>
    <authentication>
        <user>Username</user>
        <password>Password</password>
    </authentication>
    <bulkModifySMART>
        <modifySMART>
            <site_id>100005112</site_id>
            <ftp_pw>pw_string_1</ftp_pw>
            <ftp_user>ftu_user_1</ftp_user>
            <docroot>./public_html</docroot>
        </modifySMART>
        <modifySMART>
            <site_id>100005110</site_id>
            <ftp_pw>pw_string_2</ftp_pw>
            <ftp_user>ftp_user_2</ftp_user>
            <docroot>./public_html</docroot>
        </modifySMART>
        <modifySMART>
            <site_id>100005111</site_id>
            <ftp_pw>pw_string_3</ftp_pw>
            <ftp_user>ftp_user_3</ftp_user>
            <docroot>./public_html</docroot>
        </modifySMART>
    </bulkModifySMART>
</SiteLockOnlineRequest>

Example response

The bulkModifySMART node in the response XML wraps a corresponding number of modifySMART nodes. The modifySMART nodes are identical to the modifySMART nodes in the XML response to the modifySMART call.

<SiteLockOnlineResponse>
    <bulkModifySMART>
        <modifySMART>
            <account_id>100000587</account_id>
            <msg>updated</msg>
            <site_id>100005112</site_id>
        </modifySMART>
        <modifySMART>
            <account_id>100000587</account_id>
            <msg>updated</msg>
            <site_id>100005110</site_id>
        </modifySMART>
        <modifySMART>
            <account_id>100000587</account_id>
            <msg>updated</msg>
            <site_id>100005111</site_id>
        </modifySMART>
    </bulkModifySMART>
</SiteLockOnlineResponse>

Turning off SMART for a user

The value of the status element must be inactive to turn SMART off, and active to turn it back on. SMART is active by default when it’s configured. The request to make it active again is only required if you have previously deactivated SMART on the site.

Possible values status:

inactive
active
911

Example request

<SiteLockOnlineRequest>
    <authentication>
        <user>Username</user>
        <password>Password</password>
    </authentication>
    <modifySMART>
        <site_id>10900</site_id>
        <status>inactive</status>
    </modifySMART>
</SiteLockOnlineRequest>