Integrate eComscan with your existing dashboard

Want to integrate eComscan into your current dashboard or reporting? We will help you! As fellow software developers, we know how much more fun and easy your work is when vendors have a simple & stable API. This page will help you to get your integration up and running in no time.

About eComscan

eComscan is a standalone program that runs server-side. It scans components of popular eCommerce platforms and identifies malware and vulnerabilities. It has a number of output formats and channels.

Read more: a technical description how eComscan works behind the scenes.

Requirements

• Your stores are running on Linux servers
• An internet connection to fetch the latest signatures upon start. Signatures are kept in memory and not written to disk.
• Disk write access to self-update (optional)
• Disk write access to store details of the last scan run, when run in monitoring mode.
• Database read access (TCP or unix socket) to tables, triggers and stored procedures (if any).
• File read access to the eCommerce installation paths
• At least 200 MB free RAM memory to load signatures and the scanning engine

Command line invocation

eComscan is written in Go to optimize scan speed. It can be invoked by your application and will return structured information about the performed scan. See ecomscan --help for regular command line options. For an API integration, these are the most relevant command line flags:

--format=json produces a single JSON report, as outlined below. Other output formats are csv and jsonline but they contain fewer details.

--key=KEY your eComscan site license key can be provided as command line option, but we recommend to set an environment variable ECOMSCAN_KEY instead. This ensures your key will not show up in process listings and such.

--skip-symlinks to not follow symbolic links outside of the scan path. If you want to exclude (media) links to NFS partitions instead, it is better use the next option

--one-file-system will not cross filesystem boundaries (similar to -x for most Unix tools)

--deep will scan all files, as opposed to executable files (JS/PHP) only. We recommend to NOT use this for monitoring, and only for manual investigations. It generally does not produce significant extra information, but increases the scanning time

JSON data description

The --format=json will produce a data structure listing all of the checks results and found detections. A check result can have zero (null) detections, which means the check passed.

• NB. The full JSON output may contain more fields than the ones listed here (to support future functionality). The fields listed here are guaranteed to be stable.

A sample report for a Magento 2 scan:

{
  "check_results": [
    {
      "name": "Global file scan",
      "moreinfo": "https://sansec.io/support/solutions/articles/44001699403",
      "detections": [
        {
          "name": "eicar_test_file_33958",
          "class": "malware",
          "source": "file:/var/www/magento2/app/mw1.php",
          "snippet": "X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*",
          "confidence": 100,
          "meta": {
            "file_ctime": "2020-03-15T14:05:12Z",
            "file_mtime": "2020-03-15T14:05:12Z"
          }
        }
      ]
    },
    {
      "name": "Exposed database managers",
      "moreinfo": "https://sansec.io/support/solutions/articles/44001710048-database-manager-risk",
      "detections": null
    },
    {
      "name": "Magento SQL injection flaw",
      "moreinfo": "https://sansec.io/support/solutions/articles/44001710051-magento-1-2-sql-injection-flaw",
      "detections": null
    },
    {
      "name": "Magento 2 database scan",
      "moreinfo": "https://sansec.io/support/solutions/articles/44001699403",
      "detections": [
        {
          "name": "burner_domain_mage_storage_pw_5e53b",
          "class": "malware",
          "source": "db:information_schema.triggers.sales_flat_order",
          "snippet": "mage-storage.pw",
          "confidence": 100
        }
      ]
    }
  ],
  "ctx": {
    "target": "[email protected]",
    "scan_date": "2020-03-18 14:58:32 UTC",
    "scan_path": "/var/www/magento2",
    "scan_issues": 2,
    "scan_cli": "ecomscan --format=json /var/www/magento2/",
    "scan_version": "1.1.0",
    "scan_min_confidence": 50,
    "scan_interactive": true
  }
}

• ctx contains the runtime environment of the specific scan. target contains the user name of the account running the scan.
• check_results contains a list of 1 or more performed checks. Each check has a name and a moreinfo URL which describes the problem and a solution for the end user. Each check_result has a detections field which is null or has 1 or more detection objects.
• Each detection object has:
  • name of our internal signature
  • class which can be malware or vulnerability
  • source is the namespace (file, db ...) and the path where the detection was found
  • snippet is the matched string that lead to the detection (not necessarily our signature)
  • confidence denotes the trust as a number from 1 to 100. By default, eComscan only reports issues with trust 50 and up. Anything below 100 may be a false positive.
  • moreinfo URL with specific information, if available.
  • meta may contain different fields, especially (for file-based detections) file_ctime and file_mtime. These are usually helpful in constructing a DFIR timeline.

Call generic webhook

The following script may be used to post alerts (if any) to your own webhook:

ecomscan --format=json --newonly --key=<key> <path> | ifne curl -X -H 'Content-Type: application/json' -d@- <webhookURL>

Testing your integration

To test whether your eComscan copy actually finds malware, you can use the EICAR test virus string, either in a PHP/JS file or in a relevant database table (such as cms_block).

X5O!P%@AP[4\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*

Keeping a scan log

eComscan does not have explicit support for logging, but it can be trivially accomplished by using this cron command:

ecomscan --newonly --key <key> --format=csv <path> |\
  tee -a /var/log/ecomscan.log | ifne mail -s "eComscan Alert" [email protected]

eComscan --newonly will only report delta results. The standard Linux utility ifne (from moreutils) only executes the mail command if there was any output from the scanner.

Version management

When eComscan has write permissions for the directory where it is installed, it will automatically check online for newer binary releases and performs a self-update. These binary releases are rare (on average: once per month). It is recommended to stay up to date with these releases, as they may contain additional detection logic, performance improvements etcetera.

If you typically run eComscan as a different user, or from a readonly file share, we recommed to install a daily cron (using the proper user and/or writeable mount point).

/path/to/ecomscan --self-update 2>&1 >/dev/null

Performance implications

eComscan runs at the lowest CPU and disk I/O priorities, so should not affect store performance.

Common issues

Database server reachable?

eComscan will connect to database servers that are found in store configuration files (eg env.php, local.xml, .env). When running the scan on your storage cluster, ensure that you have access to your customer's database servers from there.

Run eCosmcan as root?

It is not necessary to run eComscan as root, but it will not hurt either. If you are scanning multiple sites at the same time, it may be necessary to use elevated privileges, or eComscan would not be able to access all of the files.

Error reporting

eComscan will exit with a status code above 0 if a critical failure occurred.

Running on many servers

Each eComscan will download the latest signatures. If you have less than 500 servers, you don't need to cache these signatures locally.

Need help?

Please reach out to [email protected], we are eager to make this a success!