From 134a7c470bc4e0bc9cfb893999a3aeeeabf79221 Mon Sep 17 00:00:00 2001 From: yyc12345 Date: Sat, 22 Aug 2020 16:15:04 +0800 Subject: [PATCH] finish readme --- README.md | 75 +++++++++++++++++++++++++++++----------------------- README_ZH.md | 24 +++++++++++++---- 2 files changed, 61 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index a1dfa91..6758576 100644 --- a/README.md +++ b/README.md @@ -13,11 +13,11 @@ The project consist of two parts: 1. SuperScriptMaterializer - Custom Virtools Interface Plugin that allows you to export all scripts/schematics into a SQLite database file 2. SuperScriptViewer - a python parser that creates a web page based on the exported databases to view the schematic in Behavior Graph mode similar to how Virtools Dev displays. -The purpose of the project is to allow users to have a backup graph of their scripts from Virtools while providing support for analyzing `--Script Hidden--` scripts by decoding the bytecode of `.NMS` virtools files from `.CMO` and `.VMO`. +The purpose of the project is to allow users to have a backup graph of their scripts from Virtools while providing support for analyzing `--Script Hidden--` scripts by generating relation among each script component. The inspiration came from: - [BearKidsTeam/Script-Materializer](https://github.com/BearKidsTeam/Script-Materializer) - Allows exporting specific scripts into a JSON file - - [BearKidsTeam/VirtoolsScriptDeobfuscation](https://github.com/BearKidsTeam/VirtoolsScriptDeobfuscation) - A custom interface plugin that loads `.CMO` files with hidden scripts and makes them visible and editable. + - [BearKidsTeam/VirtoolsScriptDeobfuscation](https://github.com/BearKidsTeam/VirtoolsScriptDeobfuscation) - A custom interface plugin that loads Virtools files with hidden scripts and makes them visible and editable. **NOTE:** @@ -27,11 +27,50 @@ The inspiration came from: ## Requirements - - Virtools Dev 5.0 with SDK (May work for others, Virtools 4 has been tested and can be compiled and run without any modification) +### Use + + - Virtools Dev 5.0 - Python 3.0 with Flask module - Common browsers (except Safari) + +### Compile + +For compile or debug this project, follwing tools also are necessary. + + - Virtools Dev 5.0 SDK (May work for others, Virtools 4 has been tested and can be compiled and run without any modification) - Visual Studio 2015 with at least v140 toolset +## Usage + +### Exporting Scripts from Virtools + + 1. Make Sure Virtools Dev is closed. + 2. Copy compiled SuperScriptMaterializer.dll into Virtools's InterfacePlugins folder. Copy `sqlite3.dll` you downloaded into Virtool's base folder (where `devr.exe` exist). If you use the packaged file on the Release page, just decompress it directly in the root directory of Virtools and allow folder merging and file overwriting. + 3. Open Virtools and load a Virtools document of your choice. + 4. Go to the menu bar and click `Super Script Materializer` and `Export all script`. Name it `export.db` and save it into `SuperScriptViewer` folder + 5. Go to the menu bar and click `Super Script Materializer` and `Export environment`. Name it `env.db` and save it into `SuperScriptViewer` folder + +### Viewing Exported Databases + + 1. Run the viewer by `python3 SuperScriptViewer.py` + 2. It will generate a unique decorated database (`decorated.db`) used for viewing based on `export.db` and `env.db` + 3. Once generated, a webpage will be hosted (default 127.0.0.1:5000) to view all graphs. + +There is advanced command line switches if needed for the SuperScriptViewer + - `-i filename.db` specify an input file to be used as `export.db` + - `-e filename.db` specify an input file to be used as `env.db` + - `-o filename.db` specify an output file to generate `decorated.db`. If it already exists, it will used that instead of generating a new one. + - `-c encoding_name` specify database encoding. The list of supported encodings can be viewed [here](https://docs.python.org/3/library/codecs.html#standard-encodings) + - `-f` forces the output database to be regenerated (useful if you are unsure if decorated.db matches what export.db and env.db used) + - `-d` enable debugging mode. Directly raise exceptions instead of outputting to the console after capture, which is convenient for debugging + +A document instructing you how to use the SuperScriptViewer is built into the SuperScriptViewer and can be viewed from the Help page. + +## Troubleshooting + + - If `SuperScriptViewer.py` displays `TEXT` type decoding error, you will need to use switch `-c` to whatever encoding system your OS uses since Virtools uses multi-byte encoding and depends on your system's locale. It should be noted that the specified encoding is not the current code page of your computer, but the code page of the author who made this Virtools document. + - If Virtools or SuperScriptViewer show an error window or message, please create an issues page noting what Virtools version you have, a link to your file you used to export and the error message. + ## Build 1. Download repository. @@ -50,36 +89,6 @@ The inspiration came from: - Linker -> Debugging -> Generate Program Database File 8. Clean and Build as Release -## Usage - -### Exporting Scripts from Virtools - - 1. Make Sure Virtools Dev is closed. - 2. Copy compiled SuperScriptMaterializer.dll into Virtools's InterfacePlugins folder. Copy `sqlite3.dll` you downloaded into Virtool's base folder (where `devr.exe` exist). If you use the packaged file on the Release page, just decompress it directly in the root directory of Virtools and allow folder merging and file overwriting. - 3. Open Virtools and load a `.CMO` of your choice. - 4. Go to the menu bar and click `Super Script Materializer` and `Export all script`. Name it `export.db` and save it into `SuperScriptViewer` folder - 5. Go to the menu bar and click `Super Script Materializer` and `Export environment`. Name it `env.db` and save it into `SuperScriptViewer` folder - -### Viewing Exported Databases - - 1. Run the viewer by `python3 SuperScriptViewer.py` - 2. It will generate a unique decorated database (`decorated.db`) used for viewing based on `export.db` and `env.db` - 3. Once generated, a webpage will be hosted (default 127.0.0.1:5000) to view all graphs. - -There is advanced command line switches if needed for the SuperScriptViewer - - `-i filename.db` specify an input file to be used as `export.db` - - `-e filename.db` specify an input file to be used as `env.db` - - `-o filename.db` specify an output file to generate `decorated.db`. If it already exists, it will used that instead of generating a new one. - - `-c encoding_name` specify database encoding. The list of supported encodings can be viewed [here](https://docs.python.org/3/library/codecs.html#standard-encodings) - - `-f` forces the output database to be regenerated (useful if you are unsure if decorated.db matches what export.db and env.db used) - -A document instructing you how to use the SuperScriptViewer is built into the SuperScriptViewer and can be viewed from the Help page. - -## Troubleshooting - - - If `SuperScriptViewer.py` displays `TEXT` type decoding error, you will need to use switch `-c` to whatever encoding system your OS uses since Virtools uses multi-byte encoding and depends on your system's locale. It should be noted that the specified encoding is not the current code page of your computer, but the code page of the author who made this Virtools document. - - If Virtools or SuperScriptViewer show an error window or message, please create an issues page noting what Virtools version you have, a link to your file you used to export and the error message. - ## Development plan In subsequent versions, the following features will be gradually added: diff --git a/README_ZH.md b/README_ZH.md index 26a49e0..373115c 100644 --- a/README_ZH.md +++ b/README_ZH.md @@ -10,15 +10,31 @@ 超级Virtools脚本物化器（机翻（确信）） +本项目分为2个部分，`SuperScriptMaterializer`是一个C++工程，将生成一个Virtools界面插件用于导出初步数据，`SuperScriptViewer`是一个Python工程，将解析导出的数据，然后使用Flask提供一个本地Web界面进行脚本查看。 + 将Virtools文档中的所有脚本导出成一个SQLite数据库文件，然后经过Python进行排布处理，最后提供一个本地Web前端查看脚本。这同样适用于`Script Hidden`的Virtools脚本，也适用于其中含有不可展开的`Behavior Graph`的脚本。 物化器不能完全恢复脚本的原有排布，无论原有排布是否存在，物化器都将重新自动生成脚本中的各个元素的位置。某些结构的关系可能会改变（例如Export parameter），亦或者是与Virtools中的呈现不同，但是逻辑思路将不会改变。同时物化器不能将已经生成的结构回写成Virtools可接受的格式，因此物化器只能提供无视脚本隐藏的分析功能。 本工程代码源于另两个工程：[BearKidsTeam/Script-Materializer](https://github.com/BearKidsTeam/Script-Materializer)（该工程用于将指定脚本导出为JSON文档）和[BearKidsTeam/VirtoolsScriptDeobfuscation](https://github.com/BearKidsTeam/VirtoolsScriptDeobfuscation)（该工程能够在Virtools 3.5中提供内置的隐藏脚本解析功能，将解析结果解析为可以被Virtools识别的格式） -本项目分为2个部分，`SuperScriptMaterializer`是一个C++工程，将生成一个Virtools界面插件用于导出初步数据，`SuperScriptViewer`是一个Python工程，将解析导出的数据，然后使用Flask提供一个本地Web界面进行脚本查看。 +**注意事项** -当前最新的commit并不一定可以稳定使用，请访问Release界面获取可以稳定使用的版本。且本程序的开发周期很长，如果您使用了第一个正式版之前的版本，那么您需要重新构建所有数据，因为之前的版本与正式版本不兼容。 +* 当前最新的commit并不一定可以稳定使用，请访问Release界面获取可以稳定使用的版本。 +* 如果您更换了使用的版本（包括第一个稳定版本之前的版本），则需要重新构建所有数据，因为各个版本之间的数据可能彼此不兼容。 + +### 使用 + + - Virtools Dev 5.0 + - 至少Python 3.0，且需要安装Flask库 + - 常见浏览器（除了Safari） + +### 编译 + +为了编译或者调试这个项目，以下工具也是必须的。 + + - Virtools Dev 5.0 SDK（在其他版本上或许也能工作，已测试Virtools 4可以无修改编译并运行） + - Visual Studio 2015（至少VC++ v140的工具集） ## 使用方法 @@ -35,6 +51,7 @@ - `-e`：指定输入的`env.db`，环境数据库 - `-c`：指定数据库编码，可用的编码表可以在[这里](https://docs.python.org/3/library/codecs.html#standard-encodings)查看 - `-f`：无参数，用于强制重新生成输出数据库，无论输出数据库是否存在 +- `-d`：无参数，启用调试模式，直接抛出异常，而不是捕获后在控制台输出，方便调试 以上选项在基本使用中应该不会用到，因此按上述规则直接放置好文件直接运行即可。 @@ -42,11 +59,8 @@ ### 使用注意 -- 您需要先安装Virtools 5, Python和任意一种浏览器才能使用本工程。Python需要先安装`Flask`库。浏览器建议使用Chrome或Firefox，本程序不支持Safari浏览器。 -- 导出插件目前只支持Virtools 5，但Virtools 4已经过测试可以无修改编译运行。 - 导出插件选择完文件后弹出错误，或者Python交互界面弹出错误，请附带您引起bug的文件以及错误窗口的内容提交bug - 如果Python交互界面提示数据库`TEXT`类型解码失败，或者解析的字符出现乱码，那么可能您需要手动使用`-c`开关指定数据库文本解码方式。因为Virtools使用多字节编码，依赖于当前操作系统的代码页，`SuperScriptMaterializer`做了特殊获取以保证大多数计算机可以直接运行，但仍然不能排除一些特殊情况。需要注意的是，指定的编码不是你计算机当前的代码页，而是制作这个Virtools文档的作者的计算机的代码页。 -- 如果您使用本工程的Release页面中提供的已编译好的Virtools界面插件，您需要放入的`sqlite3.dll`版本应为`sqlite-dll-win32-x86-3310100` ## 编译