Merge pull request #11 from levno-710/develop

Author: levno-710

doc/README.md

@@ -6,4 +6,4 @@ description: Prometheus is an Lua Obfuscator, that is written in pure Lua.
 
 Prometheus can obfuscate Lua51 as well as Roblox's LuaU, which is an optionally typed superset of Lua51.
 
-NOTE: This documentation is currently being developed, so do not expect a full documentation yet.
+Show Prometheus on [github](https://github.com/levno-710/Prometheus).

doc/SUMMARY.md

@@ -5,7 +5,20 @@
 ## Getting Started
 
 * [Installation](getting-started/installation.md)
+* [Obfuscating your first script](getting-started/obfuscating-your-first-script.md)
+* [Command Line Options](getting-started/command-line-options.md)
+* [Writing a custom Config File](getting-started/writing-a-custom-config-file.md)
+* [The Config Object](getting-started/the-config-object.md)
 
-***
+## Steps
 
-* [Obfuscating your first script](obfuscating-your-first-script.md)
+* [WrapInFunction](steps/wrapinfunction.md)
+* [Vmify](steps/vmify.md)
+* [SplitStrings](steps/splitstrings.md)
+* [ProxifyLocals](steps/proxifylocals.md)
+* [LocalsToTable](steps/localstotable.md)
+* [ConstantArray](steps/constantarray.md)
+
+## advanced
+
+* [Using Prometheus in your Lua Application](advanced/using-prometheus-in-your-lua-application.md)

doc/advanced/using-prometheus-in-your-lua-application.md

@@ -0,0 +1,31 @@
+# Using Prometheus in your Lua Application
+
+Prometheus can also be used as a library for your custom Lua Applications instead of using it's cli tool. 
+
+In order to do that you'll first need to clone the github repo:
+
+```batch
+git clone "https://github.com/levno-710/Prometheus.git"
+```
+
+After that, you'll need to copy everything within the src folder to your project. Let's say you created a folder named `prometheus`, where all the Prometheus files are located. You can the use the following code to obfuscate a string:
+
+{% code title="use_prometheus.lua" %}
+```lua
+local Prometheus = require("prometheus.prometheus")
+
+-- If you don't want console output
+Prometheus.Logger.logLevel = Prometheus.Logger.LogLevel.Error
+
+-- Your code
+local code = 'print("Hello, World!")'
+
+-- Create a Pipeline using the Strong preset
+local pipeline = Prometheus.Pipeline:fromConfig(Prometheus.Presets.Strong)
+
+-- Apply the obfuscation and print the result
+print(pipeline:apply(code));
+```
+{% endcode %}
+
+Instead of passing the Strong preset you could also pass a custom [Config Object](../getting-started/the-config-object.md).

doc/getting-started/command-line-options.md

@@ -0,0 +1,10 @@
+# Command Line Options
+
+The following table provides a brief overview over the command line options:
+
+| Option                        | Usage                                    |   |
+| ----------------------------- | ---------------------------------------- | - |
+| --preset \[name]; --p \[path] | Specify the config preset to be used     |   |
+| --config \[path]; --c \[path] | Specify the path to a custom config file |   |
+| --out \[path]; --o \[path]    | Specify the path of the output file      |   |
+| --nocolors                    | Disable ansi colors escape sequences     |   |

doc/getting-started/installation.md

@@ -9,3 +9,5 @@ git clone "https://github.com/levno-710/Prometheus.git"
 Alternatively you can download the Sources [here](https://github.com/levno-710/Prometheus/archive/refs/heads/master.zip).
 
 Prometheus also Requires LuaJIT or Lua51 in order to work. The Lua51 binaries can be downloaded [here](https://sourceforge.net/projects/luabinaries/files/5.1.5/Tools%20Executables/).
+
+There is also a bundled release for windows, which includes the luajit runtime. This may be usefull for adding prometheus to %PATH% and then directly using it as a command. It can be downloaded [here](https://github.com/levno-710/prometheus/releases).

doc/obfuscating-your-first-script.md …started/obfuscating-your-first-script.mddoc/obfuscating-your-first-script.md renamed to doc/getting-started/obfuscating-your-first-script.md doc/obfuscating-your-first-script.md renamed to doc/getting-started/obfuscating-your-first-script.md

@@ -18,6 +18,8 @@ Now run the following command inside of the Prometheus directory:
 lua ./cli.lua ./hello_world.lua
 ```
 
+When using the windows release `lua ./cli.lua` must be substituted by `prometheus.exe`.
+
 You may notice, that the console output looks weird. If that is the case, your terminal does not support ansi color escape sequences. You should add the `--nocolors` option:
 
 ```batch

doc/getting-started/the-config-object.md

@@ -0,0 +1,58 @@
+# The Config Object
+
+Prometheus takes a configuration objetct. In this object there can be many properties applied.   \
+The following table provides an overview:
+
+| Property      | type    | possible values                              | default           |
+| ------------- | ------- | -------------------------------------------- | ----------------- |
+| LuaVersion    | string  | "Lua51", "LuaU"                              | "Lua51"           |
+| PrettyPrint   | boolean | true, false                                  | false             |
+| VarNamePrefix | string  | any                                          | ""                |
+| NameGenerator | string  | "Mangled", "MangledShuffled", "Il", "Number" | "MangledShuffled" |
+| Seed          | number  | any                                          | 0                 |
+| Steps         | table   | StepConfig\[]                                | {}                |
+
+As this table shows, all properties in the config object are optional as they have a default value.
+
+As an example, here is the code for the minify preset:
+
+```lua
+{
+        -- The default LuaVersion is Lua51
+        LuaVersion = "Lua51";
+        -- For minifying no VarNamePrefix is applied
+        VarNamePrefix = "";
+        -- Name Generator for Variables
+        NameGenerator = "MangledShuffled";
+        -- No pretty printing
+        PrettyPrint = false;
+        -- Seed is generated based on current time
+        Seed = 0;
+        -- No obfuscation steps
+        Steps = {
+        
+        }
+    };
+```
+
+### Steps
+
+The most important property is the Steps property. This property must be a table of so called Step Configs. A Step in Prometheus describes a single transformation applied to your script by the Prometheus obfuscation pipeline. A StepConfiguration consists of the Name of the Step as well as settings for the step. All Steps will later be applied in the order they are defined. A single Step can be defined twice and will then be applied twice.
+
+```lua
+-- Obfuscation steps
+Steps = {
+    {
+        -- This obfuscation step puts all constants into an array at the beginning of the code
+        Name = "ConstantArray";
+        Settings = {
+            -- Apply to Strings only
+            StringsOnly = true;
+            -- Apply to all Constants, 0.5 would only affect 50% of strings
+            Treshold    = 1;
+        }
+    },
+}
+```
+
+Under [Steps](broken-reference), you can find all current Steps, their names as well as the possible options.

doc/getting-started/writing-a-custom-config-file.md

@@ -0,0 +1,56 @@
+# Writing a custom Config File
+
+Configuration Files for Prometheus are just lua modules, that return a single object, which contains the configuration. Let's say we have the following config file:
+
+{% code title="config.lua" %}
+```lua
+return {
+        -- The default LuaVersion is Lua51
+        LuaVersion = "Lua51"; -- or "LuaU"
+        -- All Variables will start with this prefix
+        VarNamePrefix = "";
+        -- Name Generator for Variables that look like this: b, a, c, D, t, G
+        NameGenerator = "MangledShuffled";
+        -- No pretty printing
+        PrettyPrint = false;
+        -- Seed is generated based on current time 
+        -- When specifying a seed that is not 0, you will get the same output every time
+        Seed = 0;
+        -- Obfuscation steps
+        Steps = {
+            {
+                -- This obfuscation step puts all constants into an array at the beginning of the code
+                Name = "ConstantArray";
+                Settings = {
+                    -- Apply to Strings only
+                    StringsOnly = true;
+                    -- Apply to all Constants, 0.5 would only affect 50% of strings
+                    Treshold    = 1;
+                }
+            },
+        }
+    }
+```
+{% endcode %}
+
+One can now obfuscate a script using this configuration by running:
+
+```batch
+lua ./cli.lua --config config.lua hello_world.lua
+```
+
+You should get the following output:
+
+{% code title="hello_world.obfuscated.lua" %}
+```lua
+local N={"Hello, World!"}local function k(k)return N[k+40058]end print(k(-40057))
+```
+{% endcode %}
+
+As you can see, the only transformation that was applied to our Hello World example was putting all strings (in this case only `"Hello, World!"` into an array and creating a wrapper function for retrieving the value.
+
+### How does the Config File work?
+
+The config file is simply a lua file, that returns the configuration object. Please note that this lua file is sandboxed by Prometheus when loading the configuration, meaning that you can't use any predefined functions like `tostring` or libraries like `math`.
+
+See [The Config Object](the-config-object.md) to learn what this configuration object consists of.

doc/steps/constantarray.md

@@ -0,0 +1,71 @@
+---
+description: >-
+  This Step will Extract all Constants and put them into an Array at the
+  beginning of the script
+---
+
+# ConstantArray
+
+### Settings
+
+| Name                 | type    | description                                                                                                  |
+| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
+| Treshold             | number  | The relative amount of nodes that will be affected"                                                          |
+| StringsOnly          | boolean | Wether to only Extract Strings                                                                               |
+| Shuffle              | boolean | Wether to shuffle the order of Elements in the Array                                                         |
+| Rotate               | boolean | Wether to rotate the String Array by a specific (random) amount. This will be undone on runtime.             |
+| LocalWrapperTreshold | number  | The relative amount of nodes functions, that will get local wrappers                                         |
+| LocalWrapperCount    | number  | The number of Local wrapper Functions per scope. This only applies if LocalWrapperTreshold is greater than 0 |
+| LocalWrapperArgCount | number  | The number of Arguments to the Local wrapper Functions                                                       |
+| MaxWrapperOffset     | number  | The Max Offset for the Wrapper Functions                                                                     |
+
+### Example
+
+{% code title="in.lua" %}
+```lua
+print("1")
+print("2")
+print("3")
+print("4")
+```
+{% endcode %}
+
+{% code title="out.lua" %}
+```lua
+-- LocalWrapperCount    = 3
+-- LocalWrapperArgCount = 5
+local F = {"4", "3", "2", "1"}
+do
+    local y, G = 1, 4
+    while y < G do
+        F[y], F[G] = F[G], F[y]
+        y, G = y + 1, G - 1
+    end
+    y, G = 1, 3
+    while y < G do
+        F[y], F[G] = F[G], F[y]
+        y, G = y + 1, G - 1
+    end
+    y, G = 4, 4
+    while y < G do
+        F[y], F[G] = F[G], F[y]
+        y, G = y + 1, G - 1
+    end
+end
+local function y(y)
+    return F[y + 440]
+end
+local G = {cb = function(F, G, R, p, b)
+        return y(G - 2277)
+    end, n = function(F, G, R, p, b)
+        return y(p + 47178)
+    end, B = function(F, G, R, p, b)
+        return y(F + 31775)
+    end}
+print(G.cb(1575, 1840, 2367, 1293, 1280))
+print(G.B(-32213, -31781, -31538, -32780, -32728))
+print(G.B(-32214, -33004, -31973, -32125, -31855))
+print(G.B(-32211, -31884, -31217, -32222, -31210))
+
+```
+{% endcode %}

doc/steps/localstotable.md

@@ -0,0 +1,33 @@
+---
+description: >-
+  This Step will wrap all Locals in each scope into a table. (Not recommended
+  due to memory issues)
+---
+
+# LocalsToTable
+
+### Settings
+
+| Name         | type    | description                                                                                                            |
+| ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Treshold     | number  | The relative amount of scopes that will be affected                                                                    |
+| RemapIndices | boolean | When this option is set to true, new table indices will be generated instead of using the id's generated by the parser |
+
+### Example
+
+{% code title="in.lua" %}
+```lua
+local a, b, c = 1, 2, 3
+print(a + b + c)
+```
+{% endcode %}
+
+{% code title="out.lua" %}
+```lua
+-- Treshold = 1
+-- RemapIndices = true
+local G = {}
+G[3], G[1], G[2] = 1, 2, 3
+print(G[3] + (G[1] + G[2]))
+```
+{% endcode %}