• If you haven’t read the introduction of this guide, you can check it out here
• If you haven’t read the previous part, you can check it out here
• You can check out the repository for this guide here

Introduction

When it comes to writing whitelist systems, the most vital step is to secure it. Without proper security measures, everything we have done up until this point can be easily bypassed, leaving your script vulnerable.

In this part of the guide, we will be securing our whitelist system by adding effective and necessary security measures. We will discuss common forms of attacks and how to prevent them.

Acknowledgements

• Don’t take this as a “one-size-fits-all” solution | You’re heavily advised to do your own research on other protection tactics.
• Be creative | You shouldn’t copy the methods I provide 1:1. Try to come up with your own methods for RNG sourcing and others.
• HTTP Spies are okay | As long as your whitelist system is secure, you shouldn’t worry about HTTP spies. They won’t do much (You can try and prevent them if you’d like).

Method 1 | Response Hooking

Response hooking is a method used to modify/spoof the server’s response, usually by using the hookfunction function to return a fake successful response.

How it works:

getgenv().whitelistKey = "InvalidKey"

hookfunction(http.request, function()
    return {
        StatusCode = 200,
        Body = game:GetService("HttpService"):JSONEncode({
            valid = true
        })
    }
end)

-- And our whitelist goes here

After doing that and running the script, you will realize that the response has been modified to always return a successful response.

In the majority of cases, an attacker would usually sniff the request and its response, then copy over the correct response.

The Fix: RNG Values

To prevent response hooking, we can generate sets of random values that the server will modify and send back to the client. The client will then verify the response using the same set of values.

How does that prevent anything? Well, the attacker will not be able to predict the random values generated by the client along with the arithmetic operations to verify the legitimacy of the response, making it nearly impossible to spoof it. If a mismatch exists between the generated client values and the server values, the client will know that the response has been tampered with.

Here’s how it works on a more theoretical level:

Our operations for numbers:

• You should be more creative with the modifications (there is a possibility they can be guessed) | Do NOT use irreversible functions

1. Function for newFirstValue:

$$f_1(x) = 2x - 32$$

• where $x$ represents the original value of rng1.

2. Function for newSecondValue:

$$f_2(x) = 5x + 256$$

• where $x$ represents the original value of rng2.

Inverse Functions:

• Inverse functions will be within the client, and they’re used to confirm that the server request is genuine, if the inverse of the operation was the same original value we got.

1. Inverse of $f_1(x)$

   $$f_1^{-1}(y) = \frac{y + 32}{2}$$
   • This gives us the original rng1 from the transformed newFirstValue.

2. Inverse of $f_2(x)$

   $$f_2^{-1}(y) = \frac{y - 256}{5}$$
   • This gives us the original rng2 from the transformed newSecondValue.

Client-side:

We will generate random values, like so:

-- src/client/client.luau

-- You should be creative with your RNG Sources
-- I'll provide 2 only for demonstration purposes | I'll also include how attackers can reverse those as well
local rng1 = math.random(1, 100000)
local rng2 = Random.new():NextInteger(1, 100000)

Then send over the values to the server, like so:

local rng1 = math.random(1, 100000)
local rng2 = Random.new():NextInteger(1, 100000)

local response = request({
    Url = "http://localhost:3000/whitelist",
    Method = "POST",
    Body = HttpService:JSONEncode({
        whitelistkey = key,
        firstValue = rng1,
        secondValue = rng2
    }),
    Headers = {
        ["Content-Type"] = "application/json"
    }
})

Server-side

Now, we can go ahead and parse these values in our backend.

• Keep track of the operations I do here, we will reverse those again in the client.

app.post('/whitelist', async (req, res) => {
  const { whitelistkey, firstValue, secondValue } = req.body;
  //...
  // You're free to put this in whatever scope
  // This is our fx 1 & fx 2
  const newFirstValue = (firstValue * 2) - 32
  const newSecondValue = (secondValue * 5) + 256

  // Once user is whitelisted, return the modified numbers back
  return res.json(
    { valid: true, newFirstValue: newFirstValue , newSecondValue: newSecondValue }
    );
})

Client-side

Now, with the returned values, we will reverse the operation and check if the result of the operation is equal to the number we had generated initially in the client.

if response.StatusCode == 200 then
    local body = HttpService:JSONDecode(response.Body)
    if body.valid then
        if (((body.newFirstValue + 32) / 2 ) == rng1) and ( ((body.newSecondValue - 256) / 5) == rng2) then
            print('Whitelisted')
        else 
            print("Incorrect data")
            LPH_CRASH()
        end
    else
        print("Not whitelisted")
        LPH_CRASH()
    end
else
    print(`Server not responding with code {response.StatusCode}`)
    LPH_CRASH()
end

RNG Hooking

If your RNG sources are weak/straightforward, it’s a big possibility that an attacker can modify these numbers aswell, meaning that they can simply hook the response again to return the modfied version of a static number they set.

• We will cover a way to detect RNG hooks on the server-side in Part 5 👀

With math.random

hookfunction(math.random, function()
  return 1
end)

With NextInteger

local default;

default = hookmetamethod(Random.new(), "__namecall", function(self, ...)

  if getnamecallmethod() == "NextInteger" and checkcaller() then
     return 1
  end

   return default(self, ...)
end)

VM Manipulation / Opcode Hooking

• I won’t go into detail about opcodes in general, if you want to learn how they really work, I reccomend doing external research on them here
• Everything I’ll explain here is theoretical, there won’t be any practical examples on what I do. If you wan’t to understand it in-depth and more practically, check this guide out
• For the full list of Lua 5.1 Opcodes, check out this page

In short, opcodes are short codes that denote low-level instructions that tell the VM what operation to do/perform.

Attackers can modify what instructions ran by modifying the bytecode-interpretter within the obfuscator’s VM | This can lead to many methods of bypassing whitelist checks which I’ll explain in more detail.

To visually demonstrate this, let’s create a sample lua file called sample.lua and disassemble it.

• We will use the same disassembled output for the rest of the guide

local x = 1
local y = 1

if (x == y) then
  print("Equal")
 else
  print("Not equal")
end

Once we’ve created our file, we can run the following in the terminal where our LuaBinaries are located (you can get them here) and then run the following:

luac5.1 -l -p sample.lua

Once you’ve done that, you should receive an output within the console which is our disassembled file.

Let’s write it here aswell, I’ll also denote what each column is for:

<Index>  [<Source Line>]   <Opcode>      <Operands>
    1        [1]            LOADK          0 -1    ; 1
    2        [2]            LOADK          1 -1    ; 1
    3        [4]            EQ             0 0 1
    4        [4]            JMP            4       ; to 9
    5        [5]            GETGLOBAL      2 -2    ; print
    6        [5]            LOADK          3 -3    ; "Equal"
    7        [5]            CALL           2 2 1
    8        [5]            JMP            3       ; to 12
    9        [7]            GETGLOBAL      2 -2    ; print
   10        [7]            LOADK          3 -4    ; "Not equal"
   11        [7]            CALL           2 2 1
   12        [8]            RETURN         0 1

Method 2 | Jump Attacks

Jump attacks revolve around the JMP Opcode | I’ll explain how it works (skip if you already know)

The JMP opcode works by updating the instruction pointer based on the sBx argument

// https://www.lua.org/source/5.1/lopcodes.h.html
/*----------------------------------------------------------------------
name                args   description
------------------------------------------------------------------------*/
OP_JMP,    /*       sBx     pc+=sBx                                 */

• sBx → An offset number that tells the VM how many instructions to jump forward or backward (I.E: 2 means 2 instructions forward, -2 means 2 backward).
• pc → Stands for Program Counter | This increases by 1 per instruction executed (Keep this in mind)

In our sample, we can see that the first JMP instruction at Index [4] has an operand value of 4.

This jump depends on the result of the previous EQ opcode:

• If EQ evaluates to true, execution continues to the “Equal” block skipping the JMP statement (PC increases by an extra 1).
• If EQ evaluates to false, execution reaches JMP, which skips 4 instructions forward to the “Not equal” block.

Enough the nerd stuff

The methods an attacker uses always varies from one script to another

An attacker can manipulate the operand value of a JMP statement (or even the EQ statement) by manipulating the sBx argument or the conditions leading to a jump (EQ result)

For instance, changing the operand of Index [4] from 4 → 1 would lead to the execution of the next instruction directly (Equal segment)

1st Fix | LPH_ENCFUNC

| “This macro will cryptographically encrypt the passed function with the provided encryption key and decrypt and load it at runtime with the passed decryption key. The encryption key must be a 64-length hex-encoded string. For security purposes, obfuscation will fail if the encryption key is encoded anywhere else in the script’s strings/constants.” — The luraph docs

TL;DR is, LPH_ENCFUNC decrypts the anonymous function you provided (in our case, this is going to be our whitelisted block) at runtime using a decryption key.

The way we are going to retreive the key is by having the server hand it to us on a successful authentication. And pass it to our macro.

But how does this help?

An attacker is not able to jump to the whitelised section of our code without retreiving the decryption key for it first, if the person attempts to jump towards an encrypted segment which hasn’t yet been decrypted, the code will not run at all, infact it will produce “undefined results” (as stated in the docs)

Enough talk, lets get to implementing:

• First of all, you have to generate a 64 character-long hex-encoded string, use any website for this (if you’re not one of them security freaks) or generate it locally:

$ openssl rand -hex 32

d5e03252767d767f6aab5730663c4563ae0e72625102cba812846c289ab46a74

Bla bla bla don’t use the same key as I do bla bla bla I’m sure you understand if you’ve reached this far.

Server-side:

Keep a small disclaimer here:

• We won’t be providing the full key for the client, instead, we will provide a portion of it (I.E first 32 characters) and the client has the other 32, you can do this in alot of varities.
  • This prevents people just sniffing out the full decryption key using an http spy, beating the whole purpose.

// Same as before, the key only gets sent in your sucessful response.
// For the sake of explanation, the server has the first 32 characters and the client has the rest 32
return res.json(
    { valid: true, newFirstValue: newFirstValue ,newSecondValue: newSecondValue, decKey: "d5e03252767d767f6aab5730663c4563" }
);

Client-side

  -- Place this after the RNG check
LPH_ENCFUNC(
    function()
        print("Whitelisted")
    end,
    "d5e03252767d767f6aab5730663c4563ae0e72625102cba812846c289ab46a74", body.decKey .. "ae0e72625102cba812846c289ab46a74" -- Concat our received key with a constant one here
)() -- Don't forget to call the function

And that’s about it. Now an attacker cannot directly jump into your whitelisted scope without having to decrypt the whitelisted function.

2nd Fix | Scope-counters

Also a fix for jump attacks, this is a very simple fix which involves setting a local variable that counts the steps in our authentication process, and check for them at the final scope.

Here’s how it works along with our final client code:

local JumpCounter = 0

if response.StatusCode == 200 then
    JumpCounter = JumpCounter + 1 -- 1
    local body = HttpService:JSONDecode(response.Body)
    if body.valid then
        JumpCounter = JumpCounter + 1 -- 2
        if (((body.newFirstValue + 32) / 2 ) == rng1) and ( ((body.newSecondValue - 256) / 5) == rng2) then
            JumpCounter = JumpCounter + 1 -- 3
            
            -- Jumpcounter will not be 3 if a sudden jump had happened
            -- An attacker can easily get around this, it's just the most straightforward fix.
            if JumpCounter ~= 3 then
                LPH_CRASH()
            end

            -- Place this after the RNG check
            LPH_ENCFUNC(
                function()
                    print("Whitelisted")
                end,
             "d5e03252767d767f6aab5730663c4563ae0e72625102cba812846c289ab46a74", body.decKey .. "ae0e72625102cba812846c289ab46a74" -- Concat our received key with a constant one here
            )() -- Don't forget to call the function
        else 
            print("Incorrect data")
            LPH_CRASH()
        end
    else
        print("Not whitelisted")
        LPH_CRASH()
    end
else
    print(`Server not responding with code {response.StatusCode}`)
    LPH_CRASH()
end

What about the rest? (CONCAT & EQ hooks)

For those two, you can simply add sanity checks all around the client (or write a custom function for equality), like so:

Client-side

local function Equals(a, b)
    -- nil: true --> table index is nil
	if ({ [tostring(a)] = true })["nil"] then
		return a == b
	end

    -- equality flipping
	if (a ~= a) or not (a == a) then
		LPH_CRASH()
	end

    -- Concat (string comparision only)
    if (a == a .. a) or (b == b .. b) then
        LPH_CRASH()
    end

	return ({ [a] = true })[b] or false
end

Conclusion

With that, we’ve learned how we can properly protect our whitelist system from potential attacks.

You are NOT 100% safe | As mentioned in the introduction, anything you do within the client can easily be negated once an attacker reverses your obfuscation.

But with what we have here, this covers all the basic stuff that you can do to effectively fend off 90% of attackers.

In the next part of the guide, we will be going over some extra tips & tricks for your whitelist system. You can check it out here