scanNow — Triggering one or more scans

The scanNow method runs one or more scans for a single site or all sites in a given account.

The API endpoint is:

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

For the following scan types, the domain must be verified before these scans can be run:

malware_scan
xss_scan
sqli_scan
vulnerability_scan

Make sure that the domain is verified before attempting to run these scans to ensure they can be queued successfully.

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
- scanNow: The method name
  - account_id: The ID of the account for which to scan all sites
    
    If both account_id and site_id are passed in, then site_id will be preferred.
    
    If only account_id is passed, then all scans that the account is eligible for will be queued for each of the sites that belong to this account.
  - site_id: The ID of the site for which to queue one or more scans
    
    If both account_id and site_id are passed, site_id will be preferred, and all scans that the account is eligible for will be queued for site_id.
  - scan_code: (Optional, repeatable) The scan type. If omitted, all available scan types will be queued. If provided, the element can have one or more of the following values:
    
    ssl_scan: The SSL Monitor
    
    malware_scan: This scan type includes the Webpage Scan, Cross-Site Scripting Scan, SQL Injection Scan, and Platform Scan, depending on the subscription.
    
    xss_scan: The Cross-Site Scripting Scan
    
    sqli_scan: The SQL Injection Scan
    
    vulnerability_scan: This scan type includes the Cross-Site Scripting Scan, SQL Injection Scan, and Platform Scan, depending on the subscription.
    
    spam_scan: The Email Reputation Scan
    
    smart_scan: The SMART File Scan

Example request

The following request triggers all available scan products for a specific site.

<SiteLockOnlineRequest>
    <authentication>
        <user>Username</user>
        <password>Password</password>
    </authentication>
    <scanNow>
        <site_id>12</site_id>
    </scanNow>
</SiteLockOnlineRequest>

Response format

The following are three types of response that you can get for a scanNow call.

Example successful response

SiteLockOnlineResponse: This element is used to delineate the full API response.
scanNow: The method name
- result: [attribute] - In case of success, the value will always be scans_queued_ok.
- sites: A list of sites
  - site: (Repeatable) The site that was queued for scan
    
    id: [attribute] - The ID of the site that was queued for scan
    
    scan (Repeatable) The scan details
    
    success: [attribute] - This attribute will always have the value scan_queued_ok.
    
    type: [attribute] - The type of scan that was queued. For a list of possible values, see the scan_code element in the request.

<SiteLockOnlineResponse>
    <scanNow result="scans_queued_ok">
        <sites>
            <site id="12">
                <scan success="scan_queued_ok" type="spam_scan" />
                <scan success="scan_queued_ok" type="ssl_scan" />
                <scan success="scan_queued_ok" type="malware_scan" />
                <scan success="scan_queued_ok" type="sqli_scan" />
                <scan success="scan_queued_ok" type="xss_scan" />
                <scan success="scan_queued_ok" type="vulnerability_scan" />
            </site>
        </sites>
    </scanNow>
</SiteLockOnlineResponse>

Example mixed response

Sometimes individual scans cannot be queued due to having been run too recently, or, for example, if an account has multiple sites with different subscriptions, and using a specific scan_code isn’t applicable to all sites.

If some scans were queued successfully while others were not, then a mixed response will be returned. A mixed response will still return a 200 HTTP status code.

As the mixed response doesn’t differ structurally from the success response, only the differences will be highlighted.

The result attribute of the scanNow element has the value mixed.
The site element may, instead of having child scan elements, have a second attribute - error, which is always no_scan_types_available if present. This indicates that the current subscription doesn’t feature any scan types, or that the current subscription is expired.
The scan element may, instead of having a success attribute, have an error attribute, which may have one of the following values:
- already_run: The scan has been run too recently to run again.
- feature_not_allowed: The scan code indicated isn’t valid for that site.
- No sslcert found: Only for ssl_scan

<SiteLockOnlineResponse>
    <scanNow result="mixed">
        <sites>
            <site id="12">
                <scan error="already_run" type="spam_scan" />
                <scan error="already_run" type="ssl_scan" />
                <scan error="already_run" type="malware_scan" />
                <scan error="already_run" type="sqli_scan" />
                <scan error="already_run" type="xss_scan" />
                <scan error="already_run" type="vulnerability_scan" />
            </site>
            <site id="13" error="no_scan_types_available" />
            <site id="14" error="no_scan_types_available" />
            <site id="15" error="no_scan_types_available" />
            <site id="16" error="no_scan_types_available" />
            <site id="17">
                <scan success="scan_queued_ok" type="spam_scan" />
                <scan error="No sslcert found" type="ssl_scan" />
                <scan success="scan_queued_ok" type="malware_scan" />
                <scan success="scan_queued_ok" type="sqli_scan" />
                <scan success="scan_queued_ok" type="xss_scan" />
                <scan success="scan_queued_ok" type="vulnerability_scan" />
            </site>
        </sites>
    </scanNow>
</SiteLockOnlineResponse>

Example error response

There are two types of error response. The first type indicates that, although correct information was given, no scans were able to be queued. The reasons will be given in a structure identical to the other types of messages, broken down by site and scan type. The result attribute of the scanNow element will have the value no_scans_queued.

<SiteLockOnlineResponse>
    <scanNow result="no_scans_queued">
        <sites>
            <site id="12">
                <scan error="already_run" type="spam_scan" />
                <scan error="already_run" type="ssl_scan" />
                <scan error="already_run" type="malware_scan" />
                <scan error="already_run" type="sqli_scan" />
                <scan error="already_run" type="xss_scan" />
                <scan error="already_run" type="vulnerability_scan" />
            </site>
        </sites>
    </scanNow>
</SiteLockOnlineResponse>

The second type indicates either that there was a problem with the information supplied, or an internal error occurred. The elements won’t have any attributes.

<SiteLockOnlineResponse>
    <scanNow>
        <error>account_site_mismatch</error>
    </scanNow>
</SiteLockOnlineResponse>

This type of response includes an error code, which can be one of the following:

account_site_mismatch: Both the account_id and site_id were specified, but the site_id doesn’t belong to the account_id.
account_not_found: The account_id is invalid or wasn’t found.
site_not_found: The site_id is invalid or wasn’t found.
no_id_given: Neither account_id nor site_id was specified.
bad_scan_code: The scan_code specified is unknown.
internal: A system error occurred, and the request should be attempted again.