Merge pull request #670 from jaredhendrickson13/next_minor

v2.4.0 Fixes & Features

Author: jaredhendrickson13

.github/workflows/schedule_weekly.yml

@@ -0,0 +1,26 @@
+name: Weekly Schedule
+
+on:
+  workflow_dispatch: # Enable manual triggering
+  schedule:
+    - cron: "0 18 * * 1"
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    env:
+      DAYS_BEFORE_STALE: 60
+    steps:
+      - uses: actions/stale@v9
+        with:
+          stale-issue-message: |
+            This issue has been automatically marked as stale because it has had no recent activity in the last ${{ env.DAYS_BEFORE_STALE }} days.
+          stale-pr-message: |
+            This pull request has been automatically marked as stale because it has had no recent activity in the last ${{ env.DAYS_BEFORE_STALE }} days.
+          days-before-stale: ${{ env.DAYS_BEFORE_STALE }}
+          days-before-close: 0
+          exempt-issue-labels: "feature request,enhancement,bug"

README.md

@@ -8,7 +8,7 @@
 ![Docs](https://img.shields.io/website?url=https%3A%2F%2Fpfrest.org&label=Documentation)
 
 The pfSense REST API package is an unofficial, open-source REST and GraphQL API for pfSense CE and pfSense Plus
-firewalls.It is designed to be light-weight, fast, and easy to use. This guide will help you get started with the REST
+firewalls. It is designed to be light-weight, fast, and easy to use. This guide will help you get started with the REST
 API package and provide you with the information you need to configure and use the package effectively.
 
 ## Key Features

docs/INSTALL_AND_CONFIG.md

@@ -47,7 +47,9 @@ pkg-static -C /dev/null add https://github.com/jaredhendrickson13/pfsense-api/re
       the [releases page](https://github.com/jaredhendrickson13/pfsense-api/releases) to find the package built for
       your version of pfSense.
     - When updating pfSense, **you must reinstall this package afterward** as pfSense removes unofficial packages during
-      system updates and has no way to automatically reinstall them.
+      system updates and has no way to automatically reinstall them. 
+    - If you're looking for a method of programmatically installing the package without SSH, check out 
+      [pfsense-vshell](https://github.com/jaredhendrickson13/pfsense-vshell)!
 
 ## Configuring the package
 
@@ -70,16 +72,60 @@ pfsense-restapi delete
 
 ## Updating the package
 
+Before updating the package, it is recommended to enable the REST API's 'Keep Backup' setting to ensure that your
+REST API configurations, keys and access lists are not lost during the update process. It is also highly recommended to
+read and understand both the release change notes on GitHub and the [versioning policy](#versioning-policy) to ensure
+you do not unintentionally introduce breaking changes to your environment.
+
+!!! Tip
+    While the package is updating, the REST API may be unavailable for a short period of time. Updates typically complete
+    within a minute, but may vary depending on network environment and conditions. It is recommended to
+    schedule updates during off-peak hours to minimize impact to your integrations. In the event that the update fails,
+    or takes an excessive amount of time, it is recommended to uninstall and reinstall the package.
+
+### From the pfSense webConfigurator
+
+You can easily update or revert the package version from the pfSense webConfigurator by navigating to 'System' -> 
+'REST API' -> 'Updates' and select the desired version. Click 'Save' to apply the desired version. 
+
+### From the API
+
+You can update or revert the package to a specified version by sending a request to the [PATCH 
+/api/v2/system/restapi/version](https://pfrest.org/api-docs/#/SYSTEM/patchSystemRESTAPIVersionEndpoint) endpoint.
+Simply set the `install_version` field to the desired version and send the request.
+
+### From the command line
+
 You can update the package to latest version available to your pfSense version by running the following command:
 
 ```bash
 pfsense-restapi update
 ```
 
-## Reverting the package to a specific version
-
-If you need to revert or upgrade the package to a specific version, you can do so by running the following command:
+If you need to revert or upgrade the package to a _specific_ version, you can do so by running the following command:
 
 ```bash
 pfsense-restapi revert <version>
 ```
+
+## Versioning policy
+
+The REST API package loosely follows [Semantic Versioning](https://semver.org/). The versioning policy is as follows:
+
+- Major version changes (e.g. 1.x.x to 2.x.x) may include major breaking changes and are not guaranteed to be backwards
+  compatible. Major changes will often include significant changes to the framework, endpoints, schemas, and/or behavior.
+- Minor version changes (e.g. 2.0.x to 2.1.x) may include new features, bug fixes, and/or minor breaking changes. Breaking
+  changes will be isolated to specific endpoints and will be documented in the release notes.
+- Patch version changes (e.g. 2.0.0 to 2.0.1) will only include bug fixes and very small enhancements. Patches will
+  never contain breaking changes or significant new features that could impact existing functionality.
+
+### Pre-release versions
+
+Pre-release versions are occasionally made available to the public to allow for testing of new features and fixes. 
+Pre-releases will be notated as such on GitHub and are not considered as release candidates within the REST API package's
+update features by default. You may opt-in to pre-release updates by enabling the 'Allow Pre-releases' setting in the
+REST API settings.
+
+!!! Warning
+    Pre-release versions may contain breaking changes, bugs, and/or incomplete features. It is recommended to only use
+    pre-release versions in testing environments and never in production.

docs/SECURITY.md

@@ -1,21 +1,29 @@
 # Security Policy
 
-## Supported Versions
+Security is a top priority for this project. The REST API package is designed to be secure and provide granular controls
+to help admins implement a multi-layered security approach to API access. This document outlines the security policy 
+for the project and provides information on how to report a security vulnerability.
 
-Below are versions that are currently supported and will receive security updates when available.
+## Supported Versions
 
-| Version | Supported          |
-|---------| ------------------ |
-| 2.2.x   | :white_check_mark: |
-| 1.7.x   | :white_check_mark: |
-| <=1.6.x | :x:                |
+Currently, there are two supported versions of the package: the v2 package (pfSense-pkg-RESTAPI) and the legacy v1 
+package (pfSense-pkg-API). The v2 package is the latest version of the package and is actively developed and fully 
+maintained. The legacy v1 package is no longer actively developed and is only receiving compatibility fixes and critical
+security updates when necessary. It is highly recommended to regularly update to the latest version of the package to 
+ensure you are receiving important bug fixes and security updates.
 
 ## Reporting a Vulnerability
 
-Should you discover a vulnerability in the pfSense-API code, please report the issue in one of the following ways:
+Should you discover a vulnerability in the codebase, please report the issue using the order of preference below:
 
 1. A pull request with code that fixes the discovered vulnerability
 2. A private email to either the project owner or the respective code owner
 3. As a last resort, you may open a public issue on the repository
 
-Please note this is an independent and open-source project and no bug bounty or reward can be granted.
+Please do not disclose the details of the vulnerability publicly until it has been addressed by the maintainers. 
+The maintainers will work to address the vulnerability as quickly as possible and will provide updates on the issue 
+as they become available.
+
+!!! Notice
+    This is an open-source project and is developed and maintained by members of the pfSense community. No bug bounty
+    can be offered for reported vulnerabilities.

docs/index.md

@@ -40,9 +40,9 @@ opening a pull request.
 - <a href="https://github.com/jaredhendrickson13"><img src="https://github.com/jaredhendrickson13.png" alt="Jared Hendrickson" title="Jared Hendrickson" width="30" height="30"/> Jared Hendrickson</img></a> - github@jaredhendrickson.com
 
 !!! Important
-    Unless your inquiry is regarding a security vulnerability or other sensitive matter, please do not contact the
-    maintainers directly. Instead, please [open an issue](https://github.com/jaredhendrickson13/pfsense-api/issues/new/choose)
-    to report a bug or request a feature. For general questions or help requests, please [open a discussion](https://github.com/jaredhendrickson13/pfsense-api/discussions/new/choose).
+    Unless your inquiry is regarding a [security vulnerability](SECURITY.md) or other sensitive matter, please do not 
+    contact the maintainers directly. Instead, please [open an issue](https://github.com/jaredhendrickson13/pfsense-api/issues/new/choose) to report a bug or request a feature. For 
+    general questions or help requests, please [open a discussion](https://github.com/jaredhendrickson13/pfsense-api/discussions/new/choose).
 
 ## Disclaimers
 

mkdocs.yml

@@ -17,6 +17,7 @@ nav:
   - Advanced Topics:
       - Introduction: ADVANCED_TOPICS_INTRO.md
       - Contributing & Development: CONTRIBUTING.md
+      - Security Policy: SECURITY.md
       - Building Custom Authentication: BUILDING_CUSTOM_AUTH_CLASSES.md
       - Building Custom Query Filters: BUILDING_CUSTOM_QUERY_FILTER_CLASSES.md
       - Building Custom Models: BUILDING_CUSTOM_MODEL_CLASSES.md

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

@@ -1147,8 +1147,10 @@ class Endpoint {
      * Creates a new object for the assigned Model using the data submitted in a POST request.
      */
     protected function post(): Model|ModelSet {
-        # POST request cannot include an ID, strip the ID if present
-        unset($this->request_data['id']);
+        # POST requests cannot include an ID unless auto_create_id is off
+        if ($this->model->auto_create_id) {
+            unset($this->request_data['id']);
+        }
 
         # Construct the model from representation using the client's request data
         $this->model->from_representation(data: $this->request_data);

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

@@ -89,6 +89,15 @@ class Model {
      */
     public string $id_type = 'integer';
 
+    /**
+     * @var bool $auto_create_id
+     * Enables or disables automatic creation of an ID for this Model object when the `create()` method is called. If
+     * set to `true`, the ID will be automatically generated. If set to `false`, an ID must be provided before the
+     * `create()` method is called. This applies exclusively to Models with $many enabled and is usually only
+     * relevant to Model classes that use an internal callable method.
+     */
+    public bool $auto_create_id = true;
+
     /**
      * @var mixed $parent_id
      * For Models acting as children to a different Model class, this property will contain the ID of the parent model
@@ -2036,7 +2045,7 @@ class Model {
      */
     final public function create(bool $apply = false): Model {
         # Ensure all object Fields and validations succeed for proceeding.
-        if ($this->validate(create_id: true)) {
+        if ($this->validate(requires_id: !$this->auto_create_id, create_id: $this->auto_create_id)) {
             # Check if creating this object would put the total number of objects over the $many_maximum
             $this->check_many_maximum();
 

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Endpoints/ServicesDHCPRelayEndpoint.inc

@@ -0,0 +1,22 @@
+<?php
+
+namespace RESTAPI\Endpoints;
+
+require_once 'RESTAPI/autoloader.inc';
+
+use RESTAPI\Core\Endpoint;
+
+/**
+ * Defines an Endpoint for interacting with the DHCPRelay Model object at /api/v2/services/dhcp_relay.
+ */
+class ServicesDHCPRelayEndpoint extends Endpoint {
+    public function __construct() {
+        # Set Endpoint attributes
+        $this->url = '/api/v2/services/dhcp_relay';
+        $this->model_name = 'DHCPRelay';
+        $this->request_method_options = ['GET', 'PATCH'];
+
+        # Construct the parent Endpoint object
+        parent::__construct();
+    }
+}

pfSense-pkg-RESTAPI/files/usr/local/pkg/RESTAPI/Endpoints/ServicesHAProxyFrontendCertificateEndpoint.inc

@@ -0,0 +1,23 @@
+<?php
+
+namespace RESTAPI\Endpoints;
+
+require_once 'RESTAPI/autoloader.inc';
+
+use RESTAPI\Core\Endpoint;
+
+/**
+ * Defines an Endpoint for interacting with a singular HAProxyFrontendCertificate Model object at
+ * /api/v2/services/haproxy/frontend/certificate.
+ */
+class ServicesHAProxyFrontendCertificateEndpoint extends Endpoint {
+    public function __construct() {
+        # Set Endpoint attributes
+        $this->url = '/api/v2/services/haproxy/frontend/certificate';
+        $this->model_name = 'HAProxyFrontendCertificate';
+        $this->request_method_options = ['GET', 'POST', 'PATCH', 'DELETE'];
+
+        # Construct the parent Endpoint object
+        parent::__construct();
+    }
+}