🗒️Security Detailed Explanation

Summary of Client and Server Interaction:

• Client-Side: The client uses SecurityClient.TriggerSecure to trigger events securely. The system checks if the event is whitelisted or blacklisted, and prevents triggering if necessary.

• Server-Side: The server registers secure events using Security.RegisterSecureEvent, which enforces rate-limiting, permission checks, and event logging. The server also uses Security.EnableGlobalEventGuard to manage event whitelisting and blacklisting globally.

1. Global Event Guard 🔒:

The GlobalEventGuard section is responsible for handling whitelisting and blacklisting of events.

• Whitelist ✅: If an event is in the whitelist, it can be triggered by the client without any issue. You simply add the event name to the whitelist table like this:

  ["allowed_event"] = true

• Blacklist ❌: If an event is in the blacklist, it will be blocked from triggering and will not reach the server. Example:

  ["malicious_event"] = true

Example:

If you want to allow the event player_spawn and block the event hack_attempt, you would configure your file like this:

CodexCore_CFG.Security.GlobalEventGuard = {
    whitelist = {
        ["player_spawn"] = true, 
    },
    blacklist = {
        ["hack_attempt"] = true, 
    },
}

2. Rate-Limiting ⏱️:

Rate-limiting helps to prevent abuse by restricting how many times an event can be triggered in a specific time frame. This is set under RateLimit.

• maxCalls: The maximum number of times an event can be triggered by a player within the set time frame.

• perSeconds: The time frame (in seconds) that maxCalls applies to.

Example:

If you want to allow a player to trigger an event no more than 5 times in 10 seconds, you would set:

CodexCore_CFG.Security.RateLimit = {
    maxCalls = 5, 
    perSeconds = 10, 
}

3. Logs and False Bans 🚫:

The security module provides logging features to help track suspicious activities and any blocked or failed attempts. If an event is blocked due to being blacklisted or rate-limited, the event will be logged.

Example Logs 📋:

• If a whitelisted event is triggered, no logs will be created.

• If a blacklisted event is triggered, you’ll see a log entry like this:

  [Security] Blocked blacklisted event: hack_attempt from source 1

• If a rate limit is exceeded, the log entry will be:

  [Security] Rate limit hit: player_move from source 1

Handling False Bans or Log Misinterpretations ⚠️:

False Bans / False Positives:

Sometimes legitimate events may be mistakenly flagged as malicious or triggering rate-limits. This can happen if an event is frequently called within a short period or if the whitelist/blacklist is not properly configured.

To resolve this:

1. Review the Event Logs 📋: Review the logs to determine if the event was blocked correctly or if the player was incorrectly flagged.

2. Adjust the Rate-Limit 🔄: If legitimate events are being rate-limited, adjust the maxCalls and perSeconds values to allow for more frequent triggers, or add specific events to the whitelist.

3. Update the Whitelist/Blacklist 🔧: Ensure that valid events are included in the whitelist and malicious events are accurately blacklisted.

Log Example 📑:

In the case of a legitimate event being falsely flagged, you might see:

[Security] Blocked blacklisted event: player_move from source 2

This means that the event player_move was attempted by source 2 but was blocked due to being blacklisted. If you know this event should be allowed, you can remove it from the blacklist and ensure it’s properly whitelisted.

How to Use the Security System 🔐:

• Whitelisting ✅: Add any event name you want to allow in the whitelist table.

• Blacklisting ❌: Add any event name you want to block in the blacklist table.

• Rate-Limiting ⏱️: Adjust the rate-limiting values (maxCalls, perSeconds) to control how often events can be triggered by players.

Common Usage Scenarios ⚙️:

1. Blocking Malicious Events: Add the event malicious_event to the blacklist to prevent hackers from exploiting it.

   CodexCore_CFG.Security.GlobalEventGuard.blacklist = {
       ["malicious_event"] = true,
   }

2. Allowing Custom Events: Add the event custom_event to the whitelist to make sure it's not blocked by the global event guard.

   CodexCore_CFG.Security.GlobalEventGuard.whitelist = {
       ["custom_event"] = true,
   }

3. Preventing Spam: Limit how often a player can use the send_message event by setting a rate limit of 3 calls in 10 seconds.

   CodexCore_CFG.Security.RateLimit = {
       maxCalls = 3,
       perSeconds = 10,
   }

Conclusion 🏁:

By using the configuration settings in CodexCore_CFG, you can easily manage which events are allowed, blocked, or rate-limited. The security module will handle the rest, ensuring that your server is protected from malicious events and overuse of specific actions.