box.js

A utility to analyze malicious JavaScript.

Installation

Simply install box-js from npm:

npm install box-js --global

box-js is also available:

• as a Cuckoo module (see the integrations directory and Nwinternights/Cuckoo_Boxjs);
• as a Dockerfile (see integrations/README.md);
• as a package in distros for security professionals (REMnux, BlackArch);
• as part of open source applications (Intel Owl);
• as part of commercial third-party services (any.run).

Usage

Let's say you have a sample called sample.js: to analyze it, simply run

box-js sample.js

Chances are you will also want to download any payloads; use the flag --download to enable downloading. Otherwise, the engine will simulate a 404 error, so that the script will be tricked into thinking the distribution site is down and contacting any fallback sites.

Box.js will emulate a Windows JScript environment, print a summary of the emulation to the console, and create a folder called sample.js.results (if it already exists, it will create sample.js.1.results and so on). This folder will contain:

• analysis.log, a log of the analysis as it was printed on screen;
• a series of files identified by UUIDs;
• snippets.json, a list of pieces of code executed by the sample (JavaScript, shell commands, etc.);
• urls.json, a list of URLs contacted;
• active_urls.json, a list of URLs that seem to drop active malware;
• resources.json, the ADODB streams (i.e. the files that the script wrote to disk) with file types and hashes;
• IOC.json, a list of behaviours identified as IOCs (Indicators of Compromise). These include registry accesses, written files, HTTP requests and so on.

You can analyze these by yourself, or you can automatically submit them to Malwr, VirusTotal or a Cuckoo sandbox: for more information, run box-export --help.

For further isolation, it is recommended to run the analysis in a temporary Docker container. Consult integrations/README.md for more information.

If you wish to automate the analysis, you can use the return codes - documented in integrations/README.md - to distinguish between different types of errors.

Analysis Fails Due to Missing 'document' Object or Other Objects/Functions

The box-js repository from git includes a boilerplate.js file. This file defines some stubbed versions of common browser objects such as document. Try rerunning your analysis with the --prepended-code=DIR/boilerplate.js option, where DIR is the directory of the cloned box-js repository or with --prepended-code=default. The --prepended-code option tells box-js to prepend the JavaScript in the given file to the sample being analyzed.

Note that you can copy boilerplate.js and add your own stubbed classes, objects, etc. as needed. Use the --prepended-code=show-default command line option to print the full path to the default box-js boilerplate.js file.

Batch usage

While box.js is typically used on single files, it can also run batch analyses. You can simply pass a list of files or folders to analyse:

box-js sample1.js sample2.js /var/data/mySamples ...

By default box.js will process samples in parallel, running one analysis per core. You can use a different setting by specifying a value for --threads: in particular, 0 will remove the limit, making box-js spawn as many analysis threads as possible and resulting in very fast analysis but possibly overloading the system (note that analyses are usually CPU-bound, not RAM-bound).

You can use --loglevel=warn to silence analysis-related messages and only display progress info.

After the analysis is finished, you can extract the active URLs like this:

cat ./*.results/active_urls.json | sort | uniq

Flags