Admin users new page

administrative_users.rst

@@ -0,0 +1,189 @@
+.. _administrative_users-section:
+
+====================
+Administrative users
+====================
+
+NethSecurity allows local users to be granted administrative access to the web interface. Administrative users should be personal accounts assigned to individual operators, so that actions can be attributed to a specific user in the logs.
+
+This page explains how administrative users work, how MFA applies to administrators, how administrative actions are logged, and how to reconstruct administrator activity for troubleshooting and audit purposes.
+
+Administrative account types
+============================
+
+NethSecurity uses the following administrative account types:
+
+* ``root``: local system account. It should be reserved for emergency or recovery operations whenever possible.
+* Administrative users: local users with the **Administrator user** option enabled. They can access the NethSecurity UI and perform administrative operations.
+* Non-administrative users: local or remote users used for services such as VPN or authentication, without access to the NethSecurity UI.
+
+.. note::
+
+   Administrative access should be granted only to trusted operators.
+
+Creating administrative users
+-----------------------------
+
+Administrative users are created from the local users database.
+
+To create an administrative user:
+
+1. Create a local user.
+2. Set a password for the user.
+3. Enable the **Administrator user** option.
+4. Save the configuration.
+
+For general information about local and remote user databases, see :ref:`users_databases-section`.
+
+.. _2fa-section:
+
+NethSecurity UI 2FA
+===================
+
+Protecting your NethSecurity administrator account is crucial, and Two-Factor Authentication (2FA) adds an extra layer of security beyond just a password.
+2FA requires two verification steps when logging in. Instead of just a password, you'll also need a temporary code generated by a separate app on
+your smartphone or tablet. This significantly reduces the risk of unauthorized access even if your password is compromised.
+
+Enabling 2FA on NethSecurity UI:
+
+- Log in to your NethSecurity web interface
+- Click on the user icon in the top right corner and select ``Account settings``
+- Find the Two-factor authentication option and click :guilabel:`Configure 2FA`
+
+Setting up your authenticator app:
+
+- Download an authenticator app on your smartphone or tablet. Popular options include FreeOTP, Google Authenticator, and Microsoft Authenticator.
+- Open the app and scan the QR code displayed on the NethSecurity web interface. This will add your NethSecurity account to the authenticator app.
+- Enter the 6-digit code displayed by your authenticator app in the One-Time Password (OTP) field on the NethSecurity web interface.
+
+The system will also provide you with a set of backup codes. These codes can be used to log in if you lose your smartphone or authenticator app.
+Store these codes securely, preferably offline.
+
+Disable 2FA via the web interface
+---------------------------------
+
+If the administrator can still log in to the web interface:
+
+1. Click the user icon in the top-right corner and select ``Account settings``.
+2. Scroll to the ``Two-factor authentication`` section.
+3. Click ``Revoke 2FA``.
+4. A confirmation dialog appears warning that the security level will be reduced.
+   Click ``Revoke 2FA`` to confirm.
+5. If prompted, enter your current password to authorize the change.
+
+After the confirmation the status badge changes to disabled and the next login will no
+longer require an OTP.
+
+Disable 2FA from the command line (emergency recovery)
+-------------------------------------------------------
+
+If an administrator has lost both the OTP device and the recovery codes and can no
+longer log in to the web interface, 2FA can be reset directly from the shell as ``root``
+over SSH.
+
+Run the following commands, replacing `<username>` with the administrator account name
+(use ``root`` for the default administrator): ::
+
+  SECRETS_DIR=/etc/ns-api-server
+  USERNAME=root   # change to the affected username
+
+  rm -f  "${SECRETS_DIR}/${USERNAME}/secret"
+  rm -f  "${SECRETS_DIR}/${USERNAME}/codes"
+  printf '0' > "${SECRETS_DIR}/${USERNAME}/status"
+
+After these commands the user can log in with just their password.  2FA can be
+re-enabled at any time from the web interface.
+
+.. note::
+
+  Only the ``root`` account has SSH access by default.  Non-root administrators
+  cannot be recovered from SSH by the affected user themselves; an existing ``root``
+  session is required to run the commands above on their behalf.
+
+
+Root and emergency access
+=========================
+
+The ``root`` account is the main local system account, it should be treated as an emergency or recovery account and should not be used for ordinary administrative activity when personal administrative users are available.
+Use personal administrative accounts for daily operations, so that actions can be attributed to individual users in the logs.
+
+Administrative activity logging
+===============================
+
+NethSecurity logs administrative activity performed through the web interface in ``/var/log/messages``.
+Administrative logs can support troubleshooting, incident analysis, and audit reconstruction.
+
+Where to find administrative logs
+---------------------------------
+
+Logs are written in ``/var/log/messages`` and rotated on a weekly base, they are visible from the UI in their dedicated section.
+To see administrative UI events use the filter ``nethsecurity-api``.
+
+For long-term retention and centralized audit, configure persistent log storage, remote syslog forwarding, Controller log forwarding, or Cloud Log Manager. For details, see :ref:`logs-section`.
+
+Reconstructing administrator actions
+------------------------------------
+
+To reconstruct administrator activity, start from the login event and then review the following UI/API authorization and commit events for the same user, the logs allow to answer questions such as:
+
+* who logged in;
+* when the administrator accessed the firewall;
+* which UI pages or API functions were used;
+* which configuration areas were changed;
+* which values were submitted;
+* whether a change was committed;
+* whether the action was followed by service errors or security events.
+
+Every time an administrator logs in to the NethSecurity UI, the system logs the event, inside the `/var/log/messages` file.
+Example of login event for user `goofy`: ::
+
+  Jun 21 09:43:19 NethSec nethsecurity-api[5376]: nethsecurity_api 2024/06/21 09:43:19 middleware.go:78: [INFO][AUTH] authentication success for user goofy
+  Jun 21 09:43:19 NethSec nethsecurity-api[5376]: nethsecurity_api 2024/06/21 09:43:19 middleware.go:186: [INFO][AUTH] login response success for user o
+
+Example of logout event for user `goofy`: ::
+
+  Jun 21 09:46:13 NethSec nethsecurity-api[5376]: nethsecurity_api 2024/06/21 09:46:13 middleware.go:214: [INFO][AUTH] logout response success for user goofy
+
+
+Also every action performed by an administrator inside the NethSecurity UI is logged inside the `/var/log/messages` file.
+Example of action performed by user `goofy`: ::
+
+  Jun 21 09:43:19 NethSec nethsecurity-api[5376]: nethsecurity_api 2024/06/21 09:43:19 middleware.go:170: [INFO][AUTH] authorization success for user goofy. POST /api/ubus/call {"path":"ns.dashboard","method":"service-status","payload":{"service":"internet"}}
+
+Audit and compliance recommendations
+------------------------------------
+
+For audit-oriented deployments:
+
+* create a personal administrative account for each operator;
+* avoid shared administrative accounts;
+* enable MFA for all administrative users;
+* reserve ``root`` for emergency or recovery operations whenever possible;
+* use strong passwords and protect recovery codes;
+* configure persistent log storage or remote log forwarding;
+* forward logs to a remote syslog server, SIEM, Controller, or Cloud Log Manager;
+* verify that log forwarding is working correctly;
+* ensure that date, time, and timezone are correct, preferably using NTP;
+* define log retention according to the organization security policy;
+* protect remote logs from unauthorized access or deletion;
+* periodically review administrative access and configuration change logs.
+
+NethSecurity logs can support audit reconstruction and incident analysis. 
+Organizational processes such as change approval, periodic review, incident classification, and evidence preservation remain the responsibility of the organization operating the firewall.
+
+Current limitations
+-------------------
+
+Administrative activity logs are technical logs intended to support troubleshooting and audit reconstruction.
+
+Administrators should be aware of the following limitations:
+
+* NethSecurity does not currently provide a full local RBAC model for web administrators;
+* a dedicated local read-only administrator role is not currently available;
+* administrative users should therefore be assigned only to trusted operators;
+* some log entries may require correlation with configuration commit logs or related service logs;
+* an authorization event means that the API request was allowed, but related logs should be checked to confirm the final effect of the operation;
+* not every log entry necessarily contains the same fields;
+* local in-memory logs may be lost after reboot or rotation unless persistent storage or remote forwarding is configured.
+
+For long-term audit requirements, use remote log forwarding or Cloud Log Manager in addition to local logs.

index.rst

@@ -65,6 +65,7 @@ NethSecurity administrator manual
    :caption: Users and objects
 
    users_databases
+   administrative_users
    objects
 
 .. toctree::
@@ -97,6 +98,12 @@ NethSecurity administrator manual
    ipsec_tunnels
    wireguard
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Logs
+
+   logs
+
 .. toctree::
    :maxdepth: 2
    :caption: High Availability
@@ -115,7 +122,6 @@ NethSecurity administrator manual
    smtp
    snmp
    custom_openvpn_tunnel
-   logs
    speedtest
    ups
    wol

logs.rst

@@ -4,21 +4,56 @@
 Logs
 ====
 
-Logs are initially written to a temporary in-memory directory to prevent potential errors on the root file system in case of a failure.
+Logs are used for troubleshooting, operational monitoring, incident analysis, and audit reconstruction.
+Depending on the installation type and available services, logs can be **stored on persistent local storage** and/or **forwarded to external systems** for centralized collection, retention, and analysis, such as:
 
-1. **Local Storage**: Logs can be written directly to storage. This can be configured from the UI, see the :ref:`storage-section`.
+* remote syslog server
+* NethSecurity Controller
+* Nethesis Cloud Log Manager
+
 
-2. **Remote Controller**: Logs can be automatically forwarded to a :ref:`remote controller <controller_logs-section>`.
+For audit, troubleshooting, and long-term retention, persistent storage or remote log forwarding is recommended.
 
-3. **Custom Syslog Forwarder**: Logs can be sent to a remote syslog server.
+Log storage
+===========
 
-4. **Cloud Log Manager**: Logs can be forwarded to the Nethesis Cloud Log Manager (CLM) service.
+NethSecurity can store logs in different ways depending on the installation type and the available storage.
+
+Physical appliances
+-------------------
+
+On NethSecurity physical appliances, **persistent storage is configured automatically** and used to store logs.
+When persistent storage is available, logs are saved on disk and managed by log rotation. 
+
+Virtual machines
+----------------
+
+On virtual machines, persistent storage must be configured explicitly.
+For audit, troubleshooting, and long-term retention, it is recommended to attach and configure a dedicated virtual disk for logs. 
+
+For details about how to set and verify storage configuration see the storage section :ref:`storage-section`.
+
+In-memory logs
+--------------
+
+If persistent storage is not configured, logs are written to a temporary in-memory directory. 
+This prevents potential errors on the root file system in case of failure, but it is not suitable for long-term retention.
+In-memory logs are useful for short-term troubleshooting only. For audit-oriented deployments, configure persistent storage or remote log forwarding.
+
+OpenVPN connection history 
+==========================
+
+OpenVPN connection history is permanently saved on all systems equipped with persistent storage.
+This allows administrators to review historical OpenVPN connection activity on systems with storage. 
+OpenVPN connection logs can be useful to reconstruct VPN access history, support troubleshooting, and provide evidence during audit or incident analysis.
 
-The next paragraphs will explain how to configure these latter options.
 
 Forwarding to a remote server
 =============================
 
+NethSecurity can forward logs to a remote syslog server.
+Remote log forwarding is recommended when logs must be centralized, retained for a longer period, protected from local deletion, or integrated with a SIEM or external monitoring system.
+
 It is sufficient to configure the UCI database with the desired options, then commit the changes, and finally restart the service. 
 Temporary logs will continue to be visible in ``/var/log/messages`` and will also be sent to the remote server. 
 
@@ -119,15 +154,24 @@ To stop and disable the forwarder: ::
 
 .. _log-rotation-section:
 
-Log rotation
-============
+
+
+Log rotation and retention
+==========================
 
 Logs are rotated to manage disk space and ensure that log files do not grow indefinitely.
 
+Storage log rotation
+--------------------
+
+When using persistent storage, log rotation is managed by the ``logrotate`` utility, which is configured to rotate logs weekly and keep a maximum of 52 weeks (1 year) of logs.
+After rotation, the logs are compressed using gzip and stored in the same directory with a naming convention that includes the date of rotation (e.g., ``/mnt/data/log/messages-20260315.gz``).
+
+
 In-memory log rotation
 ----------------------
 
-The ``/var/log/messages`` log file is stored in RAM and it's rotated based on size.
+If a storage is not present the ``/var/log/messages`` log file is stored in RAM and it's rotated based on size.
 Once it reaches a predefined size limit, the log is rotated and compressed to conserve space. 
 The rotated log is saved as ``/var/log/messages.1.gz`` in gzip format. The system retains only two versions of the log: the active log file and the latest rotated, compressed file. 
 From version 1.4.0, by default, the log rotation threshold is set to 10% of the tmpfs filesystem mounted at ``/tmp``.
@@ -171,13 +215,31 @@ All changes to the log rotation size are directly written in the Rsyslog configu
 
 .. _storage-log-rotation-section:
 
-Storage log rotation
---------------------
 
-When using persistent storage, log rotation is managed by the ``logrotate`` utility, which is configured to rotate logs weekly and keep a maximum of
-52 weeks (1 year) of logs.
-After rotation, the logs are compressed using gzip and stored in the same directory with a naming convention that includes the date of rotation
-(e.g., ``/mnt/data/log/messages-20260315.gz``).
 
-The configuration file for logrotate is located at ``/etc/logrotate.d/data.conf`` and can be modified to change the rotation frequency and retention period as needed.
-The configuration file is automatically added to the backup and preserved during upgrades, so any custom settings persist.
+Audit and compliance recommendations
+====================================
+
+For audit and compliance-oriented deployments, use persistent storage or remote log forwarding.
+
+Recommended setup:
+
+* on physical appliances, use the automatically configured storage;
+* on virtual machines, configure a dedicated virtual disk for log storage;
+* configure remote syslog forwarding, Controller forwarding, or Cloud Log Manager when centralized retention is required;
+* verify that system time is synchronized with NTP;
+* define a retention policy aligned with the organization security requirements;
+* protect remote logs from unauthorized access or deletion;
+* periodically verify that logs are correctly collected and forwarded;
+* periodically review administrative access, configuration changes, VPN access, and relevant security events.
+
+Local persistent storage provides useful historical information, but for stronger audit requirements it is recommended to forward logs to an external system such as a syslog server, SIEM, Controller, or Cloud Log Manager.
+
+Related information
+-------------------
+
+Administrative actions performed through the NethSecurity UI are logged in `/var/log/messages`.
+For details about administrative users, administrative audit logs, and how to reconstruct administrator activity, see the Administrative users section :ref:`administrative_users-section`.
+
+
+