Merge pull request #823 from jaredhendrickson13/next_minor

v2.7.0 Fixes & Features

Author: jaredhendrickson13

docs/INSTALL_AND_CONFIG.md

@@ -8,7 +8,7 @@ Overall, the REST API package is designed to be as lightweight as possible and s
 run pfSense. It's recommended to follow Netgate's [minimum hardware requirements](https://docs.netgate.com/pfsense/en/latest/hardware/minimum-requirements.html).
 
 !!! Warning
-    - The package is currently not compatible with 32-bit builds of pfSense. It is recommended to use the [legacy v1 package](https://github.com/jaredhendrickson13/pfsense-api/tree/legacy) for 32-bit systems.
+    - The package is currently not supported on 32-bit architectures like the Netgate 3100 (SG-3100).
     - While the package should behave identically on 64-bit architectures other than amd64, automated testing only covers amd64
     builds of pfSense CE. Support on other architectures is not guaranteed.
 

docs/QUERIES_FILTERS_AND_SORTING.md

@@ -52,6 +52,15 @@ value array contains a given value for array fields.
 - Name: `contains`
 - Example: `https://pfsense.example.com/api/v2/examples?fieldname__contains=example`
 
+### In (in)
+
+Search for objects whose field value is within a given array of values (when the filter value is an array), or search
+for objects whose field value is a substring of a given string (when the filter value is a string).
+- Name: `in`
+- Examples: 
+  - `https://pfsense.example.com/api/v2/examples?fieldname__in=example`
+  - `https://pfsense.example.com/api/v2/examples?fieldname__in[]=example1&fieldname__in[]=example2`
+
 ### Less Than (lt)
 
 Search for objects whose field value is less than a given integer.

docs/SECURING_API_ACCESS.md

@@ -0,0 +1,141 @@
+# Securing API Access
+
+In the age of network automation, APIs on network appliances unlocks incredible efficiency and potential, but it also 
+can also create a high-stakes attack vector. Unlike standard web applications, a compromised firewall doesn't just leak 
+data; it can grant attackers administrative control over your network's perimeter, allowing them to rewrite traffic rules 
+and bypass your defenses entirely. The REST API package includes several built-in security features to help protect
+API access and ensure that only authorized users and systems can interact with your pfSense instances.
+
+## Step 1: Follow Netgate's Best Practices for Remote Access
+
+If you need access to the pfSense REST API from outside your local network, it is critical that you follow Netgate's
+[Allowing Remote Access to the GUI¶](https://docs.netgate.com/pfsense/en/latest/recipes/remote-firewall-administration.html) 
+guide to ensure that your pfSense instance is properly secured against unauthorized access. This includes:
+
+- Enabling HTTPS for the web GUI to encrypt traffic between clients and the pfSense instance.
+- Using a VPN to connect to your pfSense instance remotely, rather than exposing the web GUI directly to the internet.
+- Configuring strong firewall rules to restrict access to the webConfigurator.
+
+## Step 2: Choose an Appropriate Authentication Method
+
+The authentication method you choose for API access will depend on your specific use case and security requirements
+for your environment. The pfSense REST API package supports several different authentication methods, and allows
+multiple methods to be enabled simultaneously. The three main authentication methods supported are:
+
+### Basic Authentication (Local Database)
+
+[Basic authentication](AUTHENTICATION_AND_AUTHORIZATION.md#basic-authentication-local-database) allows you to authenticate
+with the same username and password you use to log into the pfSense web GUI. This method is the default authentication
+method for the REST API package as it allows for out-of-the-box functionality without any additional configuration. 
+However, basic authentication is less secure than other methods and should only be used in trusted environments and
+over secure connections (e.g., HTTPS or VPN).
+
+**Pros**:
+
+- Easy to set up and use.
+- No additional configuration required.
+
+**Cons**:
+
+- Less secure than other methods.
+- Credentials are sent with each request, increasing the risk of interception, especially if not using HTTPS.
+- Credentials may also allow web GUI and/or SSH access, which may not be desirable for API-only users.
+
+!!! Note
+    Basic authentication is not inherently insecure. In fact, with the proper user account management, strong passwords,
+    and secure transport (HTTPS), basic authentication can be just as secure as key-based authentication methods.
+    
+
+### JWT Authentication
+
+[JWT authentication](AUTHENTICATION_AND_AUTHORIZATION.md#json-web-token-jwt-authentication) allows you to authenticate 
+using JSON Web Tokens. These are short-lived, digitially signed tokens that can be used to authenticate API requests without
+sending a username and password with each request. JWT authentication is more secure than basic authentication and is
+recommended for production environments who need session-based or short-lived authentication. This is especially useful
+for front-end applications or scripts that need to make multiple API requests over a short period of time.
+
+**Pros**:
+
+- More secure than basic authentication.
+- Tokens can be short-lived, reducing the risk of compromise.
+- Tokens do not expose pfSense user credentials with each request.
+
+**Cons**:
+
+- Requires additional configuration to set up.
+- Tokens need to be refreshed before they expire.
+
+### Key Authentication
+
+[Key authentication](AUTHENTICATION_AND_AUTHORIZATION.md#api-key-authentication) allows you to authenticate using
+dedicated API keys. These keys are created specifically for API access and never require a username or password to 
+be sent with requests. Key authentication is the most secure method and is recommended for production environments
+where security is a top priority. This method is especially useful for automated systems or services that need to
+make API requests without human intervention.
+
+**Pros**:
+
+- Most secure authentication method.
+- API keys can be easily revoked or rotated without affecting user accounts.
+- Does not expose pfSense user credentials with requests.
+- Supports configurable key-lengths and hashing algorithms for purpose-specific security needs.
+
+**Cons**:
+ 
+- Requires additional configuration to set up.
+- API keys need to be securely stored and managed.
+
+## Step 3: Use API-specific user accounts
+
+Regardless of the authentication method you choose, the REST API package uses pfSense's built-in privilege system to
+control access to API endpoints. This means that all credentials used for API access must belong to a pfSense user account
+who has been granted the appropriate API privileges. Each endpoint has its own privileges for each HTTP method supported
+by that endpoint. It is highly recommended that you create dedicated user accounts specifically for API access, rather 
+than using existing user accounts that may have broader access. This helps to limit the potential impact of a 
+compromised account and allows for better tracking of API activity. It is also highly recommended to follow the principle
+of least privilege when assigning API privileges to user accounts. Only grant the minimum privileges necessary for the
+intended use case.
+
+!!! Warning
+    The `page-all` privilege grants unrestricted access to all API endpoints and methods. Avoid assigning this privilege
+    to user accounts unless absolutely necessary, as it significantly increases the risk of unauthorized access and 
+    potential misuse of the API.
+
+## Step 4: Restrict API access to specific interfaces
+
+By default, the pfSense REST API package allows requests received on any interface IP to respond to API requests. However,
+you can restrict the API to only respond to requests received on specific interfaces if desired. This can help limit the
+exposure of the API to only trusted networks or systems beyond just setting firewall rules. To configure which 
+interfaces the API will respond to, navigate to `System` > `REST API` > `Settings` > `Allowed Interfaces` and select 
+the desired interfaces.
+
+!!! Warning
+    This setting is not a replacement for proper firewall rules. This setting should be used in addition to firewall rules
+    to provide a layered approach to security. Ensure that you have proper firewall rules in place to restrict access to the API
+    to only trusted networks or systems, then ensure the API is configured to only respond on those same interfaces.
+
+## Step 5: Configure API access lists
+
+The REST API package includes an API access list feature that allows you to restrict API access based on source IP,
+network, time-of-day, and/or user. This provides an additional layer of security by allowing you to define specific rules for who 
+can access the API, when they can access it, and from where. To configure API access lists, navigate to `System` > `REST API` >
+`Access Lists` and create the desired access list rules. When designing your access list rules, consider the following best practices:
+
+- Only allow IPs you trust and have a legitimate use case for accessing the API.
+- Only allow the relevant users to access the API from their respective IPs or networks.
+- If possible, configure and apply a schedule to apply to the access list rules to limit access to only when necessary.
+
+!!! Warning
+    This access control list is not a replacement for proper firewall rules. This setting should be used in addition to 
+    firewall rules to provide a layered approach to security. Ensure that you have proper firewall rules in place to 
+    restrict access to the API to only trusted networks or systems, then use the access list to further restrict access 
+    based on your specific requirements.
+
+## Step 6: Update Regularly
+
+Ensure that you are running the latest version of the pfSense REST API package to benefit from the latest security
+patches and features. Regularly check for updates and apply them as soon as possible to minimize the risk of vulnerabilities.
+
+!!! Tip
+    If you are using Prometheus for monitoring in your environment, consider using the [official pfREST Prometheus exporter](https://github.com/pfrest/pfsense_exporter)
+    to monitor for outdated pfSense REST API package versions across your fleet of pfSense instances!

mkdocs.yml

@@ -13,6 +13,7 @@ nav:
       - Working with HATEOAS: WORKING_WITH_HATEOAS.md
       - Common Control Parameters: COMMON_CONTROL_PARAMETERS.md
       - GraphQL: GRAPHQL.md
+      - Securing API Access: SECURING_API_ACCESS.md
       - Limitations & FAQs: LIMITATIONS_AND_FAQS.md
       - API Reference: https://pfrest.org/api-docs/
   - Advanced Topics:

pfSense-pkg-RESTAPI/files/pkg-install.in

@@ -1,8 +1,15 @@
 #!/bin/sh
+
 if [ "${2}" != "POST-INSTALL" ]; then
 	exit 0
 fi
 
+# Warn users installing on 32-bit systems
+ARCH_BITS=$(/usr/bin/getconf LONG_BIT)
+if [ "${ARCH_BITS}" = "32" ]; then
+  echo "!!! WARNING: This package is not supported on 32-bit systems. !!!"
+fi
+
 # Make this package known to pfSense
 /usr/local/bin/php -f /etc/rc.packages %%PORTNAME%% ${2}
 

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/.resources/scripts/manage.php

@@ -426,7 +426,7 @@ function delete(): void {
  */
 function rotate_server_key(): void {
     $pkg_index = RESTAPISettings::get_pkg_id();
-    config_set_path("installedpackages/package/$pkg_index/conf/keys", []);
+    Model::set_config("installedpackages/package/$pkg_index/conf/keys", []);
     echo 'Rotating REST API server key... ';
     RESTAPIJWT::init_server_key(rotate: true);
     echo 'done.' . PHP_EOL;

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Core/Auth.inc

@@ -294,6 +294,10 @@ class Auth {
             # If this Auth class is being requested by the remote client, set the matched auth and break the loop
             if ($auth->is_requested()) {
                 $matched_auth = $auth;
+                self::log(
+                    level: LOG_DEBUG,
+                    message: "Client from $auth->ip_address is attempting to authenticate using $auth->verbose_name.",
+                );
                 break;
             }
         }

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Core/BaseTraits.inc

@@ -3,27 +3,30 @@
 namespace RESTAPI\Core;
 
 use ReflectionClass;
+use RESTAPI\Models\RESTAPISettings;
 use function RESTAPI\Core\Tools\get_classes_from_namespace;
 
 /**
  * Defines a standard set of traits for all classes defined by this package. When class use this trait they will
  * automatically inherit all resources included.
  */
 trait BaseTraits {
+    private static int $__log_level;
+
     /**
      * Obtains the shortname of the called class.
      * @return string The shortname for this object's class.
      */
-    public function get_class_shortname(): string {
-        return (new ReflectionClass($this))->getShortName();
+    public static function get_class_shortname(): string {
+        return (new ReflectionClass(static::class))->getShortName();
     }
 
     /**
      * Obtains the fully qualified name of the called class.
      * @return string The FQN for this object's class.
      */
-    public function get_class_fqn(): string {
-        return (new ReflectionClass($this))->getName();
+    public static function get_class_fqn(): string {
+        return (new ReflectionClass(static::class))->getName();
     }
 
     /**
@@ -35,11 +38,32 @@ trait BaseTraits {
     }
 
     /**
-     * Logs an error to the syslog.
-     * @param string $message The error message to write to the syslog
+     * Writes a log entry to the applicable log file
+     * @param int $level The log level to write. This should be one of the LOG_* constants defined by syslog.
+     * @param string $message The message to write to the log file.
+     * @param string $logfile The log file to write to. This must be a valid logging facility defined in the package's
+     * info.xml file.
      */
-    public static function log_error(string $message): void {
-        # Call the pfSense `log_error` function
-        log_error($message);
+    public static function log(int $level, string $message, string $logfile = 'restapi'): void {
+        # If this is a system log, use the pfSense 'log_error' function instead
+        if ($logfile === 'system') {
+            log_error($message);
+            return;
+        }
+
+        # If the log level has not been set yet, obtain it
+        if (!isset(self::$__log_level)) {
+            self::$__log_level = constant(RESTAPISettings::get_pkg_config()['log_level']) ?? 4;
+        }
+
+        # Do not log if the incoming level is higher than the configured log level
+        if ($level > self::$__log_level) {
+            return;
+        }
+
+        # Otherwise, write to the applicable log file
+        openlog($logfile, flags: LOG_PID, facility: LOG_LOCAL0);
+        syslog(priority: $level, message: $message);
+        closelog();
     }
 }

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Core/Dispatcher.inc

@@ -275,15 +275,6 @@ class Dispatcher {
         sleep(30);
     }
 
-    /**
-     * Logs an error to the syslog.
-     * @param string $message The error message to write to the syslog
-     */
-    public static function log_error(string $message): void {
-        # Call the pfSense `log_error` function
-        log_error($message);
-    }
-
     /**
      * Configures this Dispatcher to run on a schedule if the `schedule` property is set.
      * @return CronJob|null Returns the CronJob created for this Dispatcher if a `schedule` is defined. Returns `null`

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Core/Endpoint.inc

@@ -412,14 +412,6 @@ class Endpoint {
                 );
             }
         }
-
-        # Do not allow `many` Endpoints that are assigned a Model with a parent Model
-        if ($this->many and $this->model->parent_model_class) {
-            throw new ServerError(
-                message: 'Endpoints cannot enable `many` when the assigned Model has a parent Model',
-                response_id: 'ENDPOINT_MANY_WHEN_MODEL_HAS_PARENT',
-            );
-        }
     }
 
     /**
@@ -633,13 +625,19 @@ class Endpoint {
     private function check_acl(): void {
         # Allow the API call if the ignore_acl flag is set
         if ($this->ignore_acl) {
+            $this->log(level: LOG_DEBUG, message: "Ignoring REST API ACL for $this->url as ignore_acl is set.");
             return;
         }
 
         # Check if the client is allowed to access this Endpoint according to the REST API Access List
         if (
             !RESTAPIAccessListEntry::is_allowed_by_acl(ip: $this->client->ip_address, username: $this->client->username)
         ) {
+            $this->log(
+                level: LOG_WARNING,
+                message: "Denied {$this->client->username}@{$this->client->ip_address} access to $this->url for REST " .
+                    'API access list violation.',
+            );
             throw new ForbiddenError(
                 message: 'The requested action is not allowed by admin policy',
                 response_id: 'ENDPOINT_CLIENT_NOT_ALLOWED_BY_ACL',
@@ -651,7 +649,10 @@ class Endpoint {
      * Checks if the API is enabled before allowing the call.
      */
     private function check_enabled(): void {
+        $client_ip = $_SERVER['REMOTE_ADDR'];
+
         if (!$this->restapi_settings->enabled->value and !$this->ignore_enabled) {
+            $this->log(level: LOG_WARNING, message: "Denied $client_ip access to $this->url as REST API is disabled.");
             throw new ServiceUnavailableError(
                 message: 'The REST API is currently not enabled.',
                 response_id: 'ENDPOINT_REST_API_IS_NOT_ENABLED',
@@ -665,6 +666,7 @@ class Endpoint {
     private function check_interface_allowed(): void {
         # Variables
         $server_ip = $_SERVER['SERVER_ADDR'];
+        $client_ip = $_SERVER['REMOTE_ADDR'];
         $allowed_interfaces = $this->restapi_settings->allowed_interfaces->value;
 
         # Allow any interface if the allowed interfaces is empty or the ignore_interfaces flag is set
@@ -678,25 +680,27 @@ class Endpoint {
         }
 
         # Loop through each allowed interface and check if the server IP is allowed to answer API calls
-        foreach (
-            $this->restapi_settings->allowed_interfaces->get_related_models()->model_objects
-            as $allowed_interface
-        ) {
+        foreach ($this->restapi_settings->allowed_interfaces->get_related_models()->model_objects as $allowed_if) {
             # Allow the server IP if it matches the current interface's IPv4 or IPv6 address
-            if ($server_ip === $allowed_interface->get_current_ipv4()) {
+            if ($server_ip === $allowed_if->get_current_ipv4()) {
                 return;
             }
-            if ($server_ip === $allowed_interface->get_current_ipv6()) {
+            if ($server_ip === $allowed_if->get_current_ipv6()) {
                 return;
             }
 
             # Check if this interface has a virtual IP that matches the server IP that accepted the API call
-            $vip_q = VirtualIP::query(interface: $allowed_interface->represented_as(), subnet: $server_ip);
+            $vip_q = VirtualIP::query(interface: $allowed_if->represented_as(), subnet: $server_ip);
             if ($vip_q->exists()) {
                 return;
             }
         }
+
         # Throw a forbidden error if this API call was made to a non-API enabled interface
+        $this->log(
+            level: LOG_WARNING,
+            message: "Denied $client_ip access to $this->url as interface IP $server_ip is not allowed to respond.",
+        );
         throw new ForbiddenError(
             message: 'The requested action is not allowed by admin policy',
             response_id: 'ENDPOINT_INTERFACE_NOT_ALLOWED',