box-js - A tool for studying JavaScript malware.

项目说明

box.js
======

![npm]() ![Build Status]() ![paypal]()

A utility to analyze malicious Ja.

Installation

Simply install box-js from npm:

>box-js is also a:
> - 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

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 en, 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 (Ja, shell commands, etc.);
* urls.json, a list of URLs contacted;
* acti.json, a list of URLs that seem to drop acti;
* 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 beha 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, 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 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 Ja 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:

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 o 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:

Flags

<!--START_FLAGS-->
NAME DESCRIPTION
-h, --help Show the help text and quit
- Show the package and quit
--license Show the license and quit
--debug Die when an emulation error occurs, even in "batch mode", and pass on the exit
code.
--loglevel Logging level (debug, , info, warning, error - default "info")
--threads When running in batch mode, how many analyses to run at the same time (0 =
unlimited, default: as many as the number of CPU cores)
--download Actually download the payloads
--encoding Encoding of the input sample (will be automatically detected by default)
--timeout The script will timeout after this many seconds (default 10)
--output-dir The location on disk to write the results files and folders to (defaults to the
current directory)
--preprocess Preprocess the original source code (makes reverse engineering easier, but takes
a few seconds)
--unsafe-preprocess More aggressi. Often results in better code, but can break on
some edge cases (eg. redefining prototypes)
--prepended-code Input file or directory containing code that should be prepended to the JS
file(s) we're analyzing. If directory is given, prepends contents of all files
in the directory. If 'default' is given use the default boilerplate.js that
comes with box-js. if 'show-default' is given just print path of boilerplate.js
and exit (useful if you want to copy and modify default boilerplate code).
--fake-script-engine The script engine to report in WScript.FullName and WScript.Name (ex.
'cscript.exe', 'wscript.exe', or 'node'). Default is wscript.exe.
--fake-cl-args Fake script command line arguments. In the string these should be comma
separated.
--fake-sample-name Fake file name to use for the sample being analyzed. Can be a full path or just
the file name to use. If you have '\' in the path escape them as '\\' in this
command line argument value (ex. --fake-sample-name=C:\\foo\\bar.js).
--fake-language Specify the language code to return for Win32_OperatingSystem.OSLanguage.
Supported are 'spanish', 'english', and 'portuguese'.
--fake-domain Specify the user domain to return for WScript.Network.UserDomain.
--fake-download Fake that HTTP requests work and have them return a fake payload
--no-kill Do not kill the application when runtime errors occur
--no-echo When the script prints data, do not print it to the console
--no-rewrite Do not rewrite the source code at all, other than for support
--no-catch-rewrite Do not rewrite try..catch clauses to make the exception global-scoped
--no-cc_on-rewrite Do not rewrite /* <...>@*/ to <...>
--no-e Do not rewrite eval so that its argument is rewritten
--no-file-exists Return false for Scripting.FileSystemObject.FileExists(x)
--limit-file-checks Switch default value for folder/file exists checks if many checks are performed
(try to break infinite file check loops).
--no-folder-exists Return false for Scripting.FileSystemObject.FileExists(x)
--function-rewrite Rewrite function calls in order to catch e
--no-rewrite-prototype Do not rewrite expressions like function A.prototype.B() as A.prototype.B =
function()
--no-hoist-prototype Do not hoist expressions like function A.prototype.B() (implied by
no-rewrite-prototype)
--no-shell-error Do not throw a fake error when executing WScriptShell.Run (it throws a fake
error by default to pretend that the distribution sites are down, so that the
script will attempt to poll every site)
--no-typeof-rewrite Do not rewrite typeof (e.g. typeof Acti, which must return
'unknown' in the JScript standard and not 'object')
--proxy [experimental] Use the specified proxy for downloads. This is not relevant if
the --download flag is not present.
--windows-xp Emulate Windows XP (influences the value of en )
--dangerous-vm Use the vm module, rather than vm2. This sandbox can be broken, so **don't
use this** unless you're 100% sure of what you're doing. Helps with debugging by
giving correct stack traces.
--rewrite-loops Rewrite some types of loops to make analysis faster
--throttle-writes Throttle reporting and data tracking of file writes that write a LOT of data
--throttle-commands Stop the analysis if a LOT of the same commands have been run
--extract-conditional-code Pull the actual code to analyze from JScript conditional comments (/*@if(...).
--loose-script-name Rewrite == checks so that comparisons of the current script name to a hard coded
script name always return true.
--real-script-name Return the real file name of the currently analyzed script rather than a fake
name.
--acti Logs All Acti as IOC's and tries to determine if the call is obfuscated
in the JS source.
--ignore-wscript-quit Ignore calls to WSCript.Quit() and continue execution.
--ignore-rewrite-errors Analyze original sample if any sample rewrites fail.
<!--END_FLAGS-->

Analyzing the output

Console output

The first source of information is the console output. On a succesful analysis, it will typically print something like this:

In this case, we are seeing a dropper that downloads a file from , setting the HTTP header User-Agent to Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.0). Then, it proceeds to decode it, and write the result to disk (a PE32 executable). Finally, it runs some command in the Windows shell.

* sample.js.results/a0af1253-597c-4eed-9e8f-5b633ff5f66a will contain the payload as it was downloaded from
* sample.js.results/f8df7228-7e0a-4241-9dae-c4e1664dc5d8 will contain the actual payload (PE executable);
* sample.js.results/d241e130-346f-4c0c-a698-f925dbd68f0c will contain the command that was run in the Windows shell.

JSON logs

Every HTTP request is both printed on the terminal and logged in urls.json. Duplicate URLs aren't inserted (i.e. requesting the same URL twice will result in only one line in urls.json).

acti.json contains the list of URLs that e resulted in an executable payload. This file is the most interesting, if you're looking to take down distribution sites.

snippets.json contains every piece of code that box-js came across, either Ja, a cmd.exe command or a PowerShell script.

resources.json contains every file written to disk by the sample. For instance, if the application tried to save Hello world! to $PATH/foo.txt, the content of resources.json would be:

The resources.json file is also important: watch out for any executable resource (eg. with "type": "PE32 executable (GUI) Intel 80386, for MS Windows").

Patching

Some scripts in the wild have been observed to use new Date().getYear() where new Date().getFullYear(). If a sample isn't showing any suspicious behaviour, watch out for Date checks.

--------

If you run into .JSE files, compile the decoder and run it like this:

Expanding

You may occasionally run into unsupported components. In this case, you can file an issue on GitHub, or emulate the component yourself if you know Ja.

The error will typically look like this (line numbers may be different):

You can see that the exception was raised in Proxy.Acti, which looks like this:

Add a new case "winhttp.winhttprequest.5.1" (note the lowercase!), and have it return an ES6 Proxy object (eg. ProxiedWinHttpRequest). This is used to catch unimplemented features as soon as they're requested by the malicious sample:

Rerun the analysis: it will fail again, telling you what exactly was not implemented.

Emulate WinHttpRequest.open as needed:

and iterate until the code emulates without errors.

Contributors

: Original de

-sayre-work: Maintainer

@da:

* npm packaging
* command-line help
* --output-directory
* bugfixes

:

* support for non-UTF8 encodings
* bug reporting

, @kzc

* advice on integrating UglifyJS in box-js
* improving the features of UglifyJS used in deobfuscation

:

* bugfixes

:

* bugfixes

项目信息

开发语言：JavaScript

Star 数：673

技术要点

该项目属于病毒分析方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A tool for studying JavaScript malware.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。