Added support for \aikido\should_whitelist_request API + tests + docs (#404)

Author: tudor-timcu

docs/should_whitelist_request.md

@@ -0,0 +1,45 @@
+# Should whitelist request
+
+The `\aikido\should_whitelist_request` function allows the protected app to check whether the current request is whitelisted based on IP configuration. This can be used to skip custom security checks or apply special handling for requests coming from trusted or configured IPs.
+
+## Function signature
+
+```php
+AikidoWhitelistRequestStatus \aikido\should_whitelist_request()
+```
+
+Returns an `AikidoWhitelistRequestStatus` object with the following properties:
+
+| Property      | Type   | Description                                                         |
+|---------------|--------|---------------------------------------------------------------------|
+| `whitelisted` | bool   | Whether the request is whitelisted. Defaults to `false`.            |
+| `type`        | string | The type of whitelist that matched. Empty string if not whitelisted.|
+| `trigger`     | string | What triggered the whitelist (e.g., `"ip"`). Empty if not whitelisted. |
+| `description` | string | A human-readable description of why the request is whitelisted.     |
+| `ip`          | string | The IP address of the request. Empty if not whitelisted.            |
+
+## Whitelist types
+
+The function checks three conditions in order. The first match wins:
+
+1. **`endpoint-allowlist`** — The endpoint has a route-level IP allowlist configured and the request IP is in it. This indicates that IP-based access control is active for this route.
+2. **`bypassed`** — The request IP is in the global firewall bypass list.
+3. **`allowlist`** — The request IP is found in the global allowed IP list (e.g., geo-location allow lists).
+
+If none of the above conditions match, `whitelisted` is `false` and all other fields are empty strings.
+
+## Example
+
+```php
+<?php
+
+if (extension_loaded('aikido')) {
+    $decision = \aikido\should_whitelist_request();
+
+    if ($decision->whitelisted) {
+        // The request is whitelisted — skip custom security checks
+        // $decision->type contains the reason: "endpoint-allowlist", "bypassed", or "allowlist"
+        // $decision->description has a human-readable explanation
+    }
+}
+```

lib/API.h

@@ -10,6 +10,7 @@ enum EVENT_ID {
     EVENT_REGISTER_PARAM_MATCHER,
     EVENT_GET_AUTO_BLOCKING_STATUS,
     EVENT_GET_BLOCKING_STATUS,
+    EVENT_GET_WHITELISTED_STATUS,
     EVENT_GET_IS_IP_BYPASSED,
     EVENT_PRE_OUTGOING_REQUEST,
     EVENT_POST_OUTGOING_REQUEST,

lib/agent/go.mod

@@ -4,7 +4,7 @@ go 1.26.1
 
 require (
 	github.com/stretchr/testify v1.9.0
-	google.golang.org/grpc v1.79.2
+	google.golang.org/grpc v1.79.3
 	google.golang.org/protobuf v1.36.10
 )
 

lib/agent/go.sum

@@ -108,6 +108,8 @@ google.golang.org/grpc v1.79.1 h1:zGhSi45ODB9/p3VAawt9a+O/MULLl9dpizzNNpq7flY=
 google.golang.org/grpc v1.79.1/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
 google.golang.org/grpc v1.79.2 h1:fRMD94s2tITpyJGtBBn7MkMseNpOZU8ZxgC3MMBaXRU=
 google.golang.org/grpc v1.79.2/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
+google.golang.org/grpc v1.79.3 h1:sybAEdRIEtvcD68Gx7dmnwjZKlyfuc61Dyo9pGXXkKE=
+google.golang.org/grpc v1.79.3/go.mod h1:KmT0Kjez+0dde/v2j9vzwoAScgEPx/Bw1CYChhHLrHQ=
 google.golang.org/protobuf v1.36.4 h1:6A3ZDJHn/eNqc1i+IdefRzy/9PokBTPvcqMySR7NNIM=
 google.golang.org/protobuf v1.36.4/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=
 google.golang.org/protobuf v1.36.5 h1:tPhr+woSbjfYvY6/GPufUoYizxw1cF/yFoxJ2fmpwlM=

lib/php-extension/Action.cpp

@@ -41,6 +41,17 @@ ACTION_STATUS Action::executeStore(json &event) {
     return CONTINUE;
 }
 
+ACTION_STATUS Action::executeWhitelist(json &event) {
+    whitelisted = true;
+    type = event["type"];
+    trigger = event["trigger"];
+    description = event["description"];
+    if (trigger == "ip") {
+        ip = event["ip"];
+    }
+    return CONTINUE;
+}
+
 ACTION_STATUS Action::executeBypassIp(json &event) {
     AIKIDO_GLOBAL(isIpBypassed) = true;
     return CONTINUE;
@@ -73,6 +84,8 @@ ACTION_STATUS Action::Execute(std::string &event) {
         return executeWarningMessage(eventJson);
     } else if (actionType == "bypassIp") {
         return executeBypassIp(eventJson);
+    } else if (actionType == "whitelisted") {
+        return executeWhitelist(eventJson);
     }
     return CONTINUE;
 }
@@ -83,6 +96,7 @@ bool Action::IsDetection(std::string &event) {
 
 void Action::Reset() {
     block = false;
+    whitelisted = false;
     type = "";
     trigger = "";
     description = "";
@@ -98,6 +112,10 @@ bool Action::Block() {
     return block;
 }
 
+bool Action::Whitelisted() {
+    return whitelisted;
+}
+
 char *Action::Type() {
     return (char *)type.c_str();
 }

lib/php-extension/Aikido.cpp

@@ -5,12 +5,13 @@ ZEND_DECLARE_MODULE_GLOBALS(aikido)
 
 PHP_MINIT_FUNCTION(aikido) {
     LoadSystemEnvironment();
-    
+
     AIKIDO_GLOBAL(logger).Init();
 
     AIKIDO_LOG_INFO("MINIT started!\n");
 
     RegisterAikidoBlockRequestStatusClass();
+    RegisterAikidoWhitelistRequestStatusClass();
 
     if (AIKIDO_GLOBAL(disable) == true) {
         AIKIDO_LOG_INFO("MINIT finished earlier because AIKIDO_DISABLE is set to 1!\n");
@@ -74,7 +75,7 @@ static void aikido_do_request_shutdown() {
         AIKIDO_LOG_DEBUG("RSHUTDOWN finished earlier because AIKIDO_DISABLE is set to 1!\n");
         return;
     }
-    
+
     DestroyAstToClean();
     AIKIDO_GLOBAL(phpLifecycle).RequestShutdown();
 
@@ -100,22 +101,22 @@ PHP_RSHUTDOWN_FUNCTION(aikido) {
 }
 
 // PHP function: \aikido\worker_rinit()
-// Because FrankenPHP doesn't call RINIT for each request in worker mode, 
+// Because FrankenPHP doesn't call RINIT for each request in worker mode,
 // we need to call it manually at the start of each request.
 // Only works with FrankenPHP worker mode
 PHP_FUNCTION(worker_rinit) {
     ZEND_PARSE_PARAMETERS_NONE();
-    
+
     // Only allow this function in FrankenPHP worker mode
     if (std::string(sapi_module.name) != "frankenphp" || !AIKIDO_GLOBAL(isWorkerMode)) {
         zend_throw_exception(
             GetFirewallDefaultExceptionCe(),
             "aikido\\worker_rinit() can only be called in FrankenPHP worker mode", 0);
         RETURN_FALSE;
     }
-    
+
     aikido_do_request_init();
-    
+
     RETURN_TRUE;
 }
 
@@ -125,17 +126,17 @@ PHP_FUNCTION(worker_rinit) {
 // Only works with FrankenPHP worker mode
 PHP_FUNCTION(worker_rshutdown) {
     ZEND_PARSE_PARAMETERS_NONE();
-    
+
     // Only allow this function in FrankenPHP worker mode
     if (std::string(sapi_module.name) != "frankenphp" || !AIKIDO_GLOBAL(isWorkerMode)) {
         zend_throw_exception(
             GetFirewallDefaultExceptionCe(),
             "aikido\\worker_rshutdown() can only be called in FrankenPHP worker mode", 0);
         RETURN_FALSE;
     }
-    
+
     aikido_do_request_shutdown();
-    
+
     RETURN_TRUE;
 }
 
@@ -149,6 +150,7 @@ static const zend_function_entry ext_functions[] = {
     ZEND_NS_FE("aikido", set_user, arginfo_aikido_set_user)
     ZEND_NS_FE("aikido", should_block_request, arginfo_aikido_should_block_request)
     ZEND_NS_FE("aikido", auto_block_request, arginfo_aikido_auto_block_request)
+    ZEND_NS_FE("aikido", should_whitelist_request, arginfo_aikido_should_whitelist_request)
     ZEND_NS_FE("aikido", set_token, arginfo_aikido_set_token)
     ZEND_NS_FE("aikido", set_rate_limit_group, arginfo_aikido_set_rate_limit_group)
     ZEND_NS_FE("aikido", register_param_matcher, arginfo_aikido_register_param_matcher)
@@ -172,6 +174,7 @@ PHP_GINIT_FUNCTION(aikido) {
     aikido_globals->laravelEnvLoaded = false;
     aikido_globals->checkedAutoBlock = false;
     aikido_globals->checkedShouldBlockRequest = false;
+    aikido_globals->checkedWhitelistRequest = false;
     aikido_globals->isIpBypassed = false;
     aikido_globals->isWorkerMode = false;
     aikido_globals->globalAstToClean = nullptr;

lib/php-extension/HandleBypassedIp.cpp

@@ -15,8 +15,15 @@ void InitIpBypassCheck() {
     }
 }
 
+bool IsAikidoDisabled() {
+    return AIKIDO_GLOBAL(disable) == true;
+}
+
+bool IsIpBypassed() {
+    return AIKIDO_GLOBAL(isIpBypassed);
+}
 
 bool IsAikidoDisabledOrBypassed() {
-    return AIKIDO_GLOBAL(disable) == true || AIKIDO_GLOBAL(isIpBypassed);
+    return IsAikidoDisabled() || IsIpBypassed();
 }
 

lib/php-extension/HandleShouldBlockRequest.cpp

@@ -1,14 +1,7 @@
 #include "Includes.h"
 
 zend_class_entry *blockingStatusClass = nullptr;
-
-// The checkedAutoBlock module global variable is used to check if auto_block_request function
-// has already been called, in order to avoid multiple calls to this function.
-// Accessed via AIKIDO_GLOBAL(checkedAutoBlock).
-
-// The checkedShouldBlockRequest module global variable is used to check if should_block_request
-// function has already been called, in order to avoid multiple calls to this function.
-// Accessed via AIKIDO_GLOBAL(checkedShouldBlockRequest).
+zend_class_entry *whitelistStatusClass = nullptr;
 
 bool CheckBlocking(EVENT_ID eventId, bool& checkedBlocking) {
     if (checkedBlocking) {
@@ -31,6 +24,27 @@ bool CheckBlocking(EVENT_ID eventId, bool& checkedBlocking) {
     return false;
 }
 
+bool CheckWhitelist(EVENT_ID eventId, bool& checkedWhitelist) {
+    if (checkedWhitelist) {
+        return true;
+    }
+
+    ScopedTimer scopedTimer("check_whitelist", "aikido_op");
+
+    try {
+        auto& requestProcessorInstance = AIKIDO_GLOBAL(requestProcessorInstance);
+        auto& action = AIKIDO_GLOBAL(action);
+        std::string output;
+        requestProcessorInstance.SendEvent(eventId, output);
+        action.Execute(output);
+        checkedWhitelist = true;
+        return true;
+    } catch (const std::exception &e) {
+        AIKIDO_LOG_ERROR("Exception encountered in processing get whitelist status event: %s\n", e.what());
+    }
+    return false;
+}
+
 ZEND_FUNCTION(should_block_request) {
     if (AIKIDO_GLOBAL(sapi_name) == "cli") {
         AIKIDO_LOG_DEBUG("should_block_request called in CLI mode! Skipping...\n");
@@ -83,6 +97,43 @@ ZEND_FUNCTION(auto_block_request) {
     CheckBlocking(EVENT_GET_AUTO_BLOCKING_STATUS, AIKIDO_GLOBAL(checkedAutoBlock));
 }
 
+ZEND_FUNCTION(should_whitelist_request) {
+    if (AIKIDO_GLOBAL(sapi_name) == "cli") {
+        AIKIDO_LOG_DEBUG("should_whitelist_request called in CLI mode! Skipping...\n");
+        return;
+    }
+
+    if (!whitelistStatusClass) {
+        return;
+    }
+
+    if (IsAikidoDisabled()) {
+        return;
+    }
+
+    object_init_ex(return_value, whitelistStatusClass);
+
+    if (!CheckWhitelist(EVENT_GET_WHITELISTED_STATUS, AIKIDO_GLOBAL(checkedWhitelistRequest))) {
+        return;
+    }
+
+    #if PHP_VERSION_ID >= 80000
+        zend_object *obj = Z_OBJ_P(return_value);
+        if (!obj) {
+            return;
+        }
+    #else
+        zval *obj = return_value;
+    #endif
+
+    auto& action = AIKIDO_GLOBAL(action);
+    zend_update_property_bool(whitelistStatusClass, obj, "whitelisted", sizeof("whitelisted") - 1, action.Whitelisted());
+    zend_update_property_string(whitelistStatusClass, obj, "type", sizeof("type") - 1, action.Type());
+    zend_update_property_string(whitelistStatusClass, obj, "trigger", sizeof("trigger") - 1, action.Trigger());
+    zend_update_property_string(whitelistStatusClass, obj, "description", sizeof("description") - 1, action.Description());
+    zend_update_property_string(whitelistStatusClass, obj, "ip", sizeof("ip") - 1, action.Ip());
+}
+
 void RegisterAikidoBlockRequestStatusClass() {
     zend_class_entry ce;
     INIT_CLASS_ENTRY(ce, "AikidoBlockRequestStatus", NULL);  // Register class without methods
@@ -95,3 +146,15 @@ void RegisterAikidoBlockRequestStatusClass() {
     zend_declare_property_string(blockingStatusClass, "ip", sizeof("ip") - 1, "", ZEND_ACC_PUBLIC);
     zend_declare_property_string(blockingStatusClass, "user_agent", sizeof("user_agent") - 1, "", ZEND_ACC_PUBLIC);
 }
+
+void RegisterAikidoWhitelistRequestStatusClass() {
+    zend_class_entry ce;
+    INIT_CLASS_ENTRY(ce, "AikidoWhitelistRequestStatus", NULL);  // Register class without methods
+    whitelistStatusClass = zend_register_internal_class(&ce);
+
+    zend_declare_property_bool(whitelistStatusClass, "whitelisted", sizeof("whitelisted") - 1, 0, ZEND_ACC_PUBLIC);
+    zend_declare_property_string(whitelistStatusClass, "type", sizeof("type") - 1, "", ZEND_ACC_PUBLIC);
+    zend_declare_property_string(whitelistStatusClass, "trigger", sizeof("trigger") - 1, "", ZEND_ACC_PUBLIC);
+    zend_declare_property_string(whitelistStatusClass, "description", sizeof("description") - 1, "", ZEND_ACC_PUBLIC);
+    zend_declare_property_string(whitelistStatusClass, "ip", sizeof("ip") - 1, "", ZEND_ACC_PUBLIC);
+}

lib/php-extension/PhpLifecycle.cpp

@@ -23,6 +23,7 @@ void PhpLifecycle::RequestInit() {
     AIKIDO_GLOBAL(requestProcessorInstance).RequestInit();
     AIKIDO_GLOBAL(checkedAutoBlock) = false;
     AIKIDO_GLOBAL(checkedShouldBlockRequest) = false;
+    AIKIDO_GLOBAL(checkedWhitelistRequest) = false;
     AIKIDO_GLOBAL(isIpBypassed) = false;
     InitIpBypassCheck();
 }

lib/php-extension/Utils.cpp

@@ -48,6 +48,8 @@ const char* GetEventName(EVENT_ID event) {
             return "GetAutoBlockingStatus";
         case EVENT_GET_BLOCKING_STATUS:
             return "GetBlockingStatus";
+        case EVENT_GET_WHITELISTED_STATUS:
+            return "GetWhitelistedStatus";
         case EVENT_GET_IS_IP_BYPASSED:
             return "GetIsIpBypassed";
         case EVENT_PRE_OUTGOING_REQUEST: