bulkReports — Bulk download reports

The bulkReports method pulls scan status, risk score, internal scan (SMART File Scan), and external scan (Site Scan) reports from the SiteLock servers. SiteLock keeps up to three reports, generated in the past 72 hours.

Large data sets are pulled in chunks. The row limit per file is 1,000,000.

This method is available for partners as an opt-in. Contact your SiteLock account manager to have all or individual reports enabled for you.

The reports are CSV files with the header row definition on the first chunk, served as gzip compressed HTTP content with an HTTP header determining if more content must be pulled.

The general flow of downloading a report is as follows:

  1. Send a request with 1 as the value of file_counter.

  2. Write the received content to a file.

    While the returned X-Sitelock-Next-File-Id header is not equal to EOF, continue appending the returned content to the file. In further requests, set the file_counter element to the value of X-Sitelock-Next-File-Id.

  3. Extract the content of the file using the gunzip command.

Data may change without notice. Make sure to read the header and reference the rows using the header as a guide.

The API endpoint is:

https://api.sitelock.com/v2/partner/bulkreports

Request format

  • JSON

  • XML

curl https://api.sitelock.com/v2/partner/bulkreports \
    -H 'Content-Type: application/json' \
    -H 'Accept-Encoding: gzip' \
    -H 'X-Sitelock-Login: <partner_username>' \
    -H 'X-Sitelock-Password: <partner_password>' \
    -d '{"report": {
        "type":"<report_type>",
        "file_period":"<file_period>",
        "file_counter":"<file_id>",
        "group_resellers":"<yes/no>"
        }
    }' \
    -o <filename>.csv.gz
curl https://api.sitelock.com/v2/partner/bulkreports \
    -H 'Content-Type: application/xml' \
    -H 'Accept-Encoding: gzip' \
    -H 'X-Sitelock-Login: <partner_username>' \
    -H 'X-Sitelock-Password: <partner_password>' \
    -d '<report>
            <type>report_type</type>
            <file_period>date</file_period>
            <file_counter>file_id</file_counter>
            <group_resellers>yes/no</group_resellers>
        </report>'\
    -o <filename>.csv.gz

The following list describes the parameters in a request:

  • X-Sitelock-Login: The partner’s API username

  • X-Sitelock-Password: The partner’s API password

  • report: The details of the report to download

    • type: The name of the report to download. The possible values are:

      • test: A test report consisting of two files for use in a non-production environment to test chunked file download

      • scan_status: The most recent scan status report

      • risk_score: The most recent risk score

      • internal_scan: The most recent internal scan

      • external_scan: The most recent external scan

    • file_period: The approximate time the report was generated in the format YYYYMMDDHH. The report is generated once a day at midnight. For example, 2023071100.

      SiteLock keeps up to three reports, generated in the past 72 hours.

    • file_counter: Pass the value 1 to this parameter on the first call. If the report is too large to fit a single file or to be transferred in a single response, you’ll get the name of the second file in the X-Sitelock-Next-File-Id header, which you can pass as file_counter in subsequent calls.

      The row limit per file is 1,000,000.

    • group_resellers: Specifies whether to group resellers into a single report if multiple reseller IDs are used. The possible values are yes and no. The default value is no.

Example request

  • JSON

  • XML

curl https://api.sitelock.com/v2/partner/bulkreports \
    -H 'Content-Type: application/json' \
    -H 'Accept-Encoding: gzip' \
    -H 'X-Sitelock-Login: daisyhost' \
    -H 'X-Sitelock-Password: host_123' \
    -d '{"report": {
        "type":"internal_scan",
        "file_period":"2023072500",
        "file_counter":"1",
        "group_resellers":"no"
        }
    }' \
    -o <filename>.csv.gz
curl https://api.sitelock.com/v2/partner/bulkreports \
    -H 'Content-Type: application/xml' \
    -H 'Accept-Encoding: gzip' \
    -H 'X-Sitelock-Login: daisyhost' \
    -H 'X-Sitelock-Password: host_123' \
    -d '<report>
            <type>internal_scan</type>
            <file_period>2023072500</file_period>
            <file_counter>1</file_counter>
            <group_resellers>no</group_resellers>
        </report>'\
    -o <filename>.csv.gz

Response format

A successful call returns a 200 HTTP response and gzipped data. Additionally, it contains two headers:

  • X-Sitelock-Gen-Time: The approximate time the report was generated in the format YYYYMMDDHH. The report is generated once a day at midnight. For example, 2022071100.

  • X-Sitelock-Next-File-Id: The string that should be sent in the next method call. For example, 2. The value will be "EOF" if all data has been returned.

In the case of an error the API will respond with a 500 HTTP response and a JSON or XML payload that includes an error element describing the issue.

Scan status report

This report is a snapshot of the most recent scan statuses and their results at the time of report generation:

  • verified: The scan found no issues. The Trust Seal is displayed.

  • pending: The scan hasn’t run yet or the site doesn’t have this product. The Trust Seal is displayed.

  • warning: The scan found issues, but the user is still within the 3-day grace period to resolve them. The Trust Seal is displayed.

  • noncompliant: The scan found that at least one issue remains unresolved after the 3-day grace period (the status was warning before). The Trust Seal isn’t displayed.

The header row in a CSV file includes the following:

  • reseller_login: The reseller’s API username

  • partner: The partner brand specified during provisionAccount

  • account_id: The user’s account ID

  • site_id: The user’s site ID

  • advisories: The status of the Risk Score Scan

  • advisories_issues: The number of issues found during the Risk Score Scan

  • malware: The status of the Webpage Scan

  • malware_issues: The number of issues found during the Webpage Scan

  • malware_link_issues: The number of malicious links found during the Webpage Scan

  • platform: The status of the Platform Scan

  • platform_issues: The number of issues found during the Platform Scan

  • spam: The status of the Email Reputation Scan

  • spam_issues: The number of issues found during the Email Reputation Scan

  • smart: The status of the SMART File Scan

  • smart_issues: The number of issues found during the SMART File Scan

  • smart_db: The status of the SMART Database Scan

  • smart_db_issues: The number of issues found during the SMART Database Scan

  • smart_patch: The status of the SMART Patch Scan

  • smart_patch_issues: The number of issues found during the SMART Patch Scan

  • sql_injection: The status of the SQL Injection Scan

  • sql_injection_issues: The number of issues found during the SQL Injection Scan

  • xss: The status of the Cross-Site Scripting Scan

  • xss_issues: The number of issues found during the Cross-Site Scripting Scan

Sample scan status report
reseller_login,partner,account_id,site_id,advisories,advisories_issues,malware,malware_issues,malware_link_issues,platform,platform_issues,spam,spam_issues,smart,smart_issues,smart_db,smart_db_issues,smart_patch,smart_patch_issues,sql_injection,sql_injection_issues,xss,xss_issues
daisyhost,Daisyhost,8036274,15752721,verified,,verified,,,verified,,verified,,warning,18,verified,,noncompliant,8,verified,,verified,
daisyhost,Daisyhost,16378562,34275058,verified,12,warning,18,,verified,3,verified,,warning,139,verified,,noncompliant,32,verified,,verified,
daisyhost,Daisyhost,16378562,34275064,verified,14,warning,20,,warning,3,verified,,warning,0,warning,,noncompliant,32,verified,,verified,

Risk score report

This report is a snapshot of the most recent risk score scans at the time of report generation.

The header row in a CSV file includes the following:

  • reseller_login: The reseller’s API username

  • partner: The partner brand specified during provisionAccount

  • account_id: The user’s account ID

  • site_id: The user’s site ID

  • risk_score: The risk score on a scale from 1 to 3 (low to high)

  • website: The risk score determined by the complexity of the website, measured on a scale from 0 to 100

  • popularity: The risk score determined by the popularity of the website, measured on a scale from 0 to 100

  • complexity: The risk score determined by the structure and composition of the website, on a scale from 0 to 100

Sample risk score report
reseller_login,partner,account_id,site_id,risk_score,website,popularity,complexity
daisyhost,Daisyhost,83573,81541,1,100,0,0
daisyhost,Daisyhost,83886,81793,1,100,0,0
daisyhost,Daisyhost,84106,81981,1,100,0,0

Internal scan report

SMART File Scans search for malware in a site’s files and database. This report is a snapshot of the most recent SMART File Scans at the time of report generation.

SMART File Scan and SMART Patch Scan will always have the same scan date.

The header row in a CSV file includes the following:

  • reseller_login: The reseller’s API username

  • partner: The partner brand specified during provisionAccount

  • account_id: The user’s account ID

  • site_id: The user’s site ID

  • site_name: The user’s domain name

  • billing_authority: The owner of the billing relationship (partner or SiteLock)

  • has_smart: Specifies whether the site has the SMART feature provisioned. The possible values are (Y) and (N).

  • ftp_configured_status: Specifies whether the user provided the FTP credentials. The possible values are:

    • active: The user provided the FTP credentials and SiteLock was able to connect to the FTP server.

    • inactive: The user didn’t provide the FTP credentials or SiteLock couldn’t connect to the FTP server.

  • ftp_active_working: Specifies whether SiteLock was able to connect and has write access to the user’s FTP server. The possible values are (Y) and (N).

  • last_ftp_message: Errors encountered during read/write operations through FTP

  • smart_issues: The number of issues found during the SMART File Scan

  • smart_issues_remediated: The number of SMART issues fixed

  • smart_db_issues: The number of issues found during the SMART Database Scan

  • smart_db_issues_remediated: The number of SMART Database Scan issues fixed

  • smart_patch_issues: The number of issues found during the SMART Patch Scan

  • smart_patch_issues_remediated: The number of SMART Patch Scan issues fixed

  • smart_db_configured: Specifies whether SMART DB is configured. The possible values are Y, N, and NA (not provisioned).

  • plan_id: A partner-specific plan ID that identifies the product

  • plan_name: The name of the plan

  • smart_scanned_at: The time of the SMART File Scan or SMART Patch Scan in the format YYYY-MM-DD HH-MM-SS.

    SMART File Scan and SMART Patch Scan will always have the same scan date.

  • smart_db_scanned_at: The time of the SMART DB scan in the format YYYY-MM-DD-HH-MM-SS

Sample internal scan report
reseller_login,partner,account_id,site_id,site_name,billing_authority,has_smart,ftp_configured_status,ftp_active_working,last_ftp_message,smart_issues,smart_issues_remediated,smart_db_issues,smart_db_issues_remediated,smart_patch_issues,smart_patch_issues_remediated,smart_db_configured,plan_id,plan_name,smart_scanned_at,smart_db_scanned_at
daisyhost,Daisyhost,1003,10983,geeksupplies.com,partner,N,active,Y,,,,,,,N,26716,"SiteLock Infinity","2023-10-01 15:31:53",
daisyhost,Daisyhost,1008,4264757,exercisedaily.com,SiteLock,Y,active,Y,,,,,,,N,26716,"SiteLock Infinity","2023-10-01 15:31:53",

External scan report

Site scans examine the website externally from the Internet, using a web crawler. This report is a snapshot of the most recent externals scans at the time of report generation.

The header row in a CSV file includes the following:

  • reseller_login: The reseller’s API username

  • partner: The partner brand specified during provisionAccount

  • account_id: The user’s account ID

  • site_id: The user’s site ID

  • site_name: The user’s domain name

  • billing_authority: The owner of the billing relationship (partner or SiteLock)

  • last_scan_run: The date of the last scan in the format YYYY-MM-DD

  • plan_id: A partner-specific plan ID that identifies the product

  • plan_name: The name of the plan

  • num_page_scanned: The number of pages scanned

  • risk_score: The risk score on a scale from 1 to 3 (low to high)

  • website: The risk score determined by the complexity of the website, measured on a scale from 0 to 100

  • popularity: The risk score determined by the popularity of the website, measured on a scale from 0 to 100

  • complexity: The risk score determined by the structure and composition of the website, measured on a scale from 0 to 100

  • cms_type: The type of platform the website runs on, such as wordpress, joomla, or drupal

  • cms_version: The version of the platform the website runs on

  • malware_issues: The number of issues found during the Webpage Scan

  • malware_critical_issues: The number of critical issues found during the Webpage Scan

  • platform_issues: The number of issues found during the Platform Scan

  • platform_critical_issues: The number of critical issues found during the Platform scan

  • spamhaus: Specifies whether the domain name was found on the blacklist/spam list in the Spamhaus dataset. The possible values are 1 and 0.

  • surbl: Specifies whether the domain name was found on the blacklist/spam list in the SURBL dataset. The possible values are 1 and 0.

  • ssl_status: The status of the SSL/TLS certificate installed on the website. The possible values are active, cn_mismatch, expired, and no_cert.

  • sqli_issues: The number of issues found during the SQLi Scan

  • xss_issues: The number of issues found during the XSS Scan

  • site_health_score: The site health score is determined by calculating a weighted score of product features and severity of issues found on the website. The score is measured from 0.00 to 100.00, with 0.00 indicating the site is in good health, and 100.00 indicating the site is completely compromised.

  • site_health_status: The site health status on a scale from 0 to 3 (low to high). The value is tied to the site_health_score:

    • 3: The site health score is between 66.66 and 100.00.

    • 2: The site health score is between 33.33 and 66.65.

    • 1: The site health score is between 0.01 and 33.32.

    • 0: The site health score is 0.00.

  • malware_medium_issues: The number of medium severity issues found during the Webpage Scan

  • wp_outdated: Specifies whether the website is running on an outdated version of WordPress. The possible values are:

    • 1: The website is using an outdated version of WordPress.

    • 0: The website is using the latest version of WordPress.

    • An empty value means the website is running on a different CMS or we couldn’t recognize the WordPress version.

Sample external scan report
reseller_login,partner,account_id,site_id,site_name,billing_authority,last_scan_run,plan_id,plan_name,num_page_scanned,risk_score,website,popularity,complexity,cms_type,cms_version,malware_issues,malware_critical_issues,platform_issues,platform_critical_issues,spamhaus,surbl,ssl_status,sqli_issues,xss_issues,site_health_score,site_health_status,malware_medium_issues,wp_outdated
greenhost,JustHost,1003,10983,geeksupplies.com,partner,2023-07-25,9,456,1,10,20,30,wordpress,6.2,,,,,1,,active,,
daisyhost,Daisyhost,1008,4264757,exercisedaily.com,SiteLock,2023-07-25,71,564,1,20,30,20,joomla,4.3.3,,,,,1,,active,,33.32,1,10,1

Example error response

  • JSON

  • XML

{
    "status": "error",
    "message": "Invalid type"
}
<Bulkreports>
  <status>error</status>
  <message>Invalid type</message>
</Bulkreports>

Data types

The following tables describe the data types and length of the fields in external and internal scan reports.

External scan report

Field Name Data Type Max Lengh Note

reseller_login

VARCHAR

255

partner

VARCHAR

255

account_id

INT

11

site_id

INT

11

site_name

VARCHAR

255

billing_authority

VARCHAR

8

The possible values are SiteLock and partner.

last_scan_run

DATE

The format is YYYY-MM-DD.

plan_id

INT

11

plan_name

VARCHAR

255

num_page_scanned

INT

11

risk_score

TINYINT

1

The possible values are 1, 2, and 3.

website

INT

100

popularity

INT

100

The value can be NULL.

complexity

INT

100

The value can be NULL.

cms_type

VARCHAR

255

The possible values are concrete5, coppermine, drupal, joomla, mediawiki, moodle, oscommerce, phpbb, phpnuke, shoppingcarts - bigcommerce, shoppingcarts - shopify, smf, sugarcrm, webbuilders - dudamobile, webbuilders - opencms, webbuilders - sharepoint, webbuilders - sitecore, wordpress.

cms_version

VARCHAR

100

7 characters should be enough.

malware_issues

INT

7 digits should be enough.

malware_critical_issues

INT

7 digits should be enough.

platform_issues

INT

7 digits should be enough.

platform_critical_issues

INT

7 digits should be enough.

spamhaus

TINYINT

1

The possible values are 1 and 0.

surbl

TINYINT

1

The possible values are 1 and 0.

ssl_status

VARCHAR

40

The possible values are active, cn_mismatch, expired, and no_cert.

sqli_issues

INT

7 digits should be enough.

xss_issues

INT

7 digits should be enough.

site_health_score

FLOAT

5 digits (with 2 decimal places) should be enough.

site_health_status

TINYINT

1

The possible values are 0, 1,2, and 3.

malware_medium_issues

INT

7 digits should be enough.

wp_outdated

TINYINT

1

The possible values are 0 and 1.

Internal scan report

Field Name Data Type Max Lengh Note

reseller_login

VARCHAR

255

partner

VARCHAR

255

account_id

INT

11

site_id

INT

11

site_name

VARCHAR

255

billing_authority

VARCHAR

8

The possible values are SiteLock and partner.

has_smart

CHAR

1

The possible values are Y and N.

ftp_configured_status

VARCHAR

10

The possible values are active and inactive.

ftp_active_working

VARCHAR

1

The possible values are Y and N.

last_ftp_message

VARCHAR

1000

smart_issues

INT

7 digits should be enough.

smart_issues_remediated

INT

7 digits should be enough.

smart_db_issues

INT

7 digits should be enough.

smart_db_issues_remediated

INT

7 digits should be enough.

smart_patch_issues

INT

7 digits should be enough.

smart_patch_issues_remediated

INT

7 digits should be enough.

smart_db_configured

VARCHAR

2

The possible values are Y, N, and NA.

plan_id

INT

11

plan_name

VARCHAR

255

smart_scanned_at

DATETIME

19

The format is YYYY-MM-DD HH-MM-SS.

smart_db_scanned_at

DATETIME

19

The format is YYYY-MM-DD HH-MM-SS.