.. Reminder for header structure: Parts (H1) : #################### with overline Chapters (H2) : ******************** with overline Sections (H3) : ==================== Subsections (H4) : -------------------- Subsubsections (H5) : ^^^^^^^^^^^^^^^^^^^^ Paragraphs (H6) : """""""""""""""""""" .. meta:: :description: Presentation of the security principles in WAPT :keywords: Cybersecurity, WAPT, documentation .. |ok| image:: wapt-resources/icon-ok.png :scale: 15% :align: middle :alt: OK ############################################### Presentation of the security principles in WAPT ############################################### +------------------------+--------------------------------+ | Date | |today| | +------------------------+--------------------------------+ | Written by | Hubert TOUVET, Vincent Cardon | +------------------------+--------------------------------+ | Applicable for WAPT | >= 2.3.0.13180 | +------------------------+--------------------------------+ | Version of the Document| 2.3.0.0-0 | +------------------------+--------------------------------+ | Git hash | |git_hash| | +------------------------+--------------------------------+ .. figure:: wapt-resources/icon_cyber-security.png :align: center :alt: Logo Cybersecurity .. contents:: :local: Here are documented the advanced security principles included in WAPT. The reading of this portion of the documentation is not essential for your daily usage of WAPT; it is however recommended for you to better understand some architectural choices made by the developers of the software. .. _security_principles: ************************ Preamble and definitions ************************ .. attention:: The WAPT service operates as a **privileged** system account. .. hint:: the sub-components :program:`wapttray`, :program:`waptservice` and :program:`waptexit` of the WAPT Agent may be optionally deactivated according to usage context. ******************* Perimeter to secure ******************* The elements to secure and that strictly concern WAPT are: * **the WAPT Server** (*waptserver*); * **the WAPT Agents** (*wapt-get*) and its sub-components (*wapttray*, *waptservice* et *waptexit*); * **the WAPT management Console** (*waptconsole*); * **the network communications** between these different components. In complement to the elements listed above, an :term:`Organization` that uses WAPT will have to choose and follow a methodology that is adapted to her use case: * Insure the safe provisioning of all other files that are to be incorporated into a WAPT package. * Develop the WAPT package python :file:`setup.py` script so as to avoid any exploitable security or confidentiality defect. * Manage in a safe way the private keys for signing the packages. * Manage in a safe way the Authorities of Certification and Revocation for the SSL and HTTPS certificates. The safe management of these complementary elements is excluded from the perimeter of this documentation. ***************************************** Description of typical user roles in WAPT ***************************************** The following roles **MUST** be understood to evaluate the security principles incorporated into WAPT: * **User** A *User* is an individual/ user of a WAPT equipped end-device (**Enterprise** and **Discovery**). * **Package Deployer** A *Package Deployer* is an individual with the ability to sign packages that **DO NOT** contain python code (generally *group*, *host* and *unit* packages) and with the ability to upload the package to the main repository (**Enterprise**). * **Package Developer** A *Package Developer* is an individual with the ability to sign any package, may it include or not include python code, and to upload the package to the main repository (**Enterprise**); .. note:: The distinction between *Package Deployer* and *Package Developer* only exists in the **Enterprise** version of WAPT. * **SuperAdmin** The *SuperAdmin* is an individual with all rights within WAPT (**Enterprise** and **Discovery**). * **Local Administrator** A *Local Administrator* is an individual with local administration right of the WAPT equipped end-devices (**Enterprise** and **Discovery**). .. note:: Depending on the context within this documentation, an :term:`Administrator` will have the meaning of a :term:`Package Deployer`, a :term:`Package Developer` or a :term:`SuperAdmin`. .. note:: The :term:`Users` that are members of the Active Directory security group **waptselfservice** have access to all the packages of the wapt repository without any filtering. ******************************************* Description of the sensitive assets in WAPT ******************************************* By definition, a sensitive asset is a data (or a function) that is considered as having value to an attacker. Its value is estimated according to several security criteria (also called security needs): * availability; * integrity; * confidentiality; * authenticity. The sensitive assets to protect are as follows: Sensitive assets A1: communications =================================== Communications between the central WAPT Server and the WAPT Agents, as well as the communications between the WAPT Console and the WAPT Server are a sensitive asset and they must be protected. .. note:: Security needs for the communications: * integrity; * confidentiality; * authenticity. Sensitive asset A2: inventory data ================================== The informations on the state of deployment of the packages, as well as hardware and software configurations of the end-devices are a sensitive asset and they must be protected. .. note:: Security needs for the inventory data: * integrity; * confidentiality. Sensitive asset A3: log journals ================================ The logs generated by WAPT on the central WAPT Server and by the Agents are a sensitive asset and they must be protected. .. note:: Security needs for historical logs: * availability. Sensitive asset A4: configuration values ======================================== The configuration values (WAPT HTTPS Server keys, database access configuration, WAPT Server authentication configuration) are sensitive and they must be protected. .. note:: Security needs for configuration values: * integrity; * confidentiality. Sensitive asset A5: WAPT executables on the end-devices ======================================================= The WAPT executables installed on managed clients are a sensitive asset and they must be protected (i.e. the content of the :file:`` directory that includes the binaries, the configuration files and the local database). .. note:: Security needs for configuration values: * integrity. Sensitive asset A6: authentication ================================== Authentication to the WAPT Management Console as well as the authentication of the clients on the WAPT Server are a sensitive asset and they must be protected (public key of each WAPT Agent). .. note:: Security need for the authentication * integrity; * confidentiality. ******************************************************* Description of hypotheses on WAPT's working environment ******************************************************* By definition, the hypotheses are statements on WAPT's usage context or its working environment. The following hypotheses on WAPT's working environment must be considered: Hypothesis H1: the Administrators and the Package Deployers are trained ======================================================================= The :term:`Administrators` and the :term:`Package Deployers` are trained on WAPT usage. In particular, they must insure that their logins, passwords and private keys are kept secret. Hypothesis H2: the operating systems underlying WAPT are sane ============================================================= WAPT's underlying operating systems implement adequate protection mechanisms that are configured according to good practice (confinement, access control, etc). The underlying operating system are patched and up to date at the time of the installation of WAPT, they are free of viruses, trojan horses, etc. Hypothesis H3: the binaries necessary for WAPT to operate are sane ================================================================== All libraries and tools necessary to install WAPT are considered to be sane. Hypothesis H4: the WAPT packages are built in a safe manner =========================================================== The :term:`Administrator` and :term:`Package Developer` are responsible for insuring that the files to be incorporated into a WAPT package come from safe sources and are free of viruses, trojan horses, etc. Administrators are also responsible for writing and incorporating safe :file:`setup.py` scripts into the WAPT packages. Hypothesis H5: the Users of the end-devices are not Local Administrators ======================================================================== A :term:`User` must not have local administration rights on the WAPT equipped device. Otherwise, the :term:`User` must be considered a :term:`Local Administrator`. In particular, a :term:`User` must not have write access to WAPT's installation directory. Hypothesis H6: the Local Administrators are trained =================================================== The :term:`Local Administrator` of a device must be trained to use WAPT, or at minimum he must not make changes to files located in WAPT's installation folder. ************************************************* Description of threats on WAPT's sensitive assets ************************************************* By definition, a threat is an action or an event susceptible to bring prejudice to the security of the WAPT equipped device. The threat agents to be considered for evaluating security in WAPT are as follows: * **Unauthorized entities**: it is a human attacker or an entity that interacts with WAPT without legitimately having access to it. .. note:: :term:`Administrators`, :term:`Local Administrator`, :term:`Package Deployers`, :term:`Package Developers` are not considered to be attackers. The threats bearing on WAPT's sensitive assets defined above are as follow: Threat T1: installation of an unsafe software by an unauthorized entity ======================================================================= This threat corresponds to an attacker that would be able to use a component of the WAPT Agent to permanently install a malicious application, or to remove or deactivate a security component on the WAPT equipped device. Threat T2: modification of configuration values by an unauthorized entity ========================================================================= The threat corresponds to an attacker that would be able to modify a configuration element of WAPT that had been previously defined by a legitimate WAPT :term:`Administrator`. Threat T3: illegitimate access by an unauthorized entity ======================================================== This threat corresponds to an attacker that would be able to recover the login credentials of an :term:`Administrator`, or bypass the authentication mechanism in such a way to access or alter a sensitive asset stored on the WAPT Server. It also corresponds to an attacker being able to impersonate a WAPT Agent. Threat T4: network listening by an unauthorized entity ====================================================== This threat corresponds to an attacker being able to intercept and gain knowledge of network traffic between the WAPT Agents and the WAPT Server hosting WAPT. Threat T5: modification of network traffic by an unauthorized entity (type *Man In The Middle*) =============================================================================================== This threat corresponds to an attacker being able to alter network traffic between the WAPT Agents and the WAPT Server hosting WAPT, or between the WAPT Console and the WAPT Server. **************************************** Description of WAPT's security functions **************************************** By definition, security functions are the set of technical measures and mechanisms implemented to protect in a proportionate way the sensitive assets against identified threats. Security function F1: access authentication =========================================== .. _initial_host_registration: Security function F1A: authentication of a device on initial registration in the WAPT database ---------------------------------------------------------------------------------------------- .. versionadded:: 1.5 .. note:: The risks avoided are: * The registering of an illegitimate device in the database. * A denial-of-service attack by overloading the database. * The insertion of a fraudulent inventory in the database. Solution implemented ^^^^^^^^^^^^^^^^^^^^ To exist in the database and thus to appear in the WAPT management Console, a device must register with the WAPT Server using the :command:`register` command. The :command:`register` command may be executed automatically when installing or updating the WAPT Agent if the device has a kerberos host account that is correctly registered in the :term:`Organization`'s Active Directory domain. If a new device does not present to the WAPT Server a valid kerberos ticket, then the :command:`register` fails; When registering, the device generates a RSA keypair in local private directory, and sends to the server a certificate signing request along with the kerberos ticket. If the Kerberos ticket is valid, the WAPT Server registers the client in the database, signs the :abbr:`CSR (Certificate Signing Request)`, stores the certificate in its database and returns it to the client. In case a device is already registered, it can re-register itself without a kerberos ticket using its current server's signed certificate. If the kerberos authentication fails or is not available, the server sends an unauthorized status, and the client can ask the Local Administrator to enter credentials of a WAPT Server account having either *admin* privilege or *register_host* priviledge. The authentication of the account is performed server side using either *admin*, *passwd*, or *ldap* mechanisms. .. note:: The kerberos registration method assumes that the Active Directory server is responsive at the time of launch of the :command:`register` command. .. _HTTPS_certificate_verification: Security function F1B: verification of WAPT Server HTTPS certificates by the WAPT Agents ---------------------------------------------------------------------------------------- .. versionadded:: 1.5 .. note:: The risks avoided (notably MITM) are: * The sending of sensitive informations to an illegitimate and unauthorized WAPT Server. * The recovery of sensitive informations by an unauthorized entity. * The display of fake information in the WAPT management Console of the :term:`Administrator`. * An incorrect date to be sent upon a HEAD request, thus preventing future upgrades (request for a modified file date). * Sending the WAPT Console password to an illegitimate and unauthorized WAPT Server. Solution implemented ^^^^^^^^^^^^^^^^^^^^ For the secured version of WAPT to work correctly: * An option for verifying the WAPT Server HTTPS certificate is introduced in :file:`C:\\Program Files (x86)\\wapt\wapt-get.ini` on the WAPT Agents that will **force the verification of the WAPT Server certificate by the WAPT Agents**. * An option for verifying the WAPT Server HTTPS certificate is introduced in :file:`C:\\Program Files (x86)\\wapt\wapt-get.ini` on the WAPT Agents that will force the verification of the WAPT Server certificate by the **WAPT Console**. Technically, it may be implemented in two ways: * By using a certificate verification tool implemented in the configuration file of WAPT's :program:`Nginx` web server; this method is typically provided by a :term:`Certificate Authority` that is trusted by your network. * By using the *certificate pinning* method, which consists of providing the WAPT Agent a short list of trusted certificates that will be stored in :file:`C:\\Program Files (x86)\\wapt\\ssl\\server`. Security function F1C: no listening port on the WAPT Agents ----------------------------------------------------------- .. versionadded:: 1.5 .. note:: The risks avoided are: * An unauthorized entity using an open port fraudulently. Solution implemented ^^^^^^^^^^^^^^^^^^^^ The connections to the WAPT Server are initiated exclusively by the Agents, and the forced immediate actions are relayed through a permanent websocket initiated by the WAPT Agent (:command:`update`/ :command:`upgrade`/ :command:`install` ...). .. note:: if HTTPS is activated, then the WAPT Agent checks that the websocket is connecting to the rightful WAPT Server. .. _signing_inventory_updates: Security function F1D: signature of inventory return states ----------------------------------------------------------- .. versionadded:: 1.3.12.13 .. note:: The risks avoided are: * An unauthorized entity sending a fake inventory for a device that rightfully exists in the database. Solution implemented ^^^^^^^^^^^^^^^^^^^^ * On the first :command:`register`, each device generates a key/ certificate pair that is stored in :file:`C:\\Program Files (x86)\\wapt\\private`, only accessible in read-only mode to :term:`Local Administrators`. Once the device has successfully registered, the public key is sent to the WAPT Server. * When the inventory is updated, the new inventory status is sent along with the private key of the device. The new inventory is then deciphered with the public key stored in the database. * The WAPT Server will refuse any inventory that is signed with a wrong key. Security function F1E: verification of authorizations before launching of WAPT commands --------------------------------------------------------------------------------------- .. note:: The risks avoided are: * Avoid the execution of sensitive tasks on WAPT clients by unauthorized entities. Solution implemented ^^^^^^^^^^^^^^^^^^^^ The :term:`Users` interact with WAPT through WAPT user interfaces (:program:`wapt-get` in command line interface, :program:`wapttray`, :program:`waptexit`, :program:`waptselfservice`). The user interfaces then delegate the execution of the desired tasks to the local WAPT service running as system account. The following actions do not require to be authenticated with the WAPT service: * :command:`wapt-get update` (update the available list of packages). * :command:`wapt-get upgrade` (launch waiting upgrades). * :command:`wapt-get download-upgrade` (download waiting upgrades). * :command:`wapt-get clean` (remove packages left in cache after installation). * stop any running WAPT task. * stop / reload the WAPT service. The other actions require the :term:`User` be authenticated and the :term:`User` either be a member of the **waptselfservice** Active Directory security group, or be a :term:`Local Administrator`, they are: * :command:`wapt-get install`: requests the WAPT Agent to install a WAPT package flagged as **MISSING**. * :command:`wapt-get remove`: requests the WAPT Agent to remove a WAPT package. * :command:`wapt-get forget`: requests the WAPT Agent to forget the existence of a previously installed WAPT package without removing the software or the configuration. .. _WAPT_package_installation_process_integrity: Security function F2: protecting the integrity of the installation process of WAPT packages =========================================================================================== Security function F2A: signature of WAPT packages ------------------------------------------------- .. note:: The risks avoided are: * To avoid an unauthorized entity modifying the content or the behavior of a WAPT package. Solution implemented ^^^^^^^^^^^^^^^^^^^^ * When an :term:`Administrator` or a :term:`Package Deployer` builds a WAPT package, the file :file:`manifest.sha256` is created that lists the control sums of all files in the package. * A file :file:`signature.sha256` **encrypted** with the WAPT Agent's private key is then created in the folder :file:`WAPT`; it contains the control sum of the file :file:`manifest.sha256`. * The whole is then compressed and suffixed with a :mimetype:`.wapt` extension. * When a WAPT Agent downloads a WAPT package, the WAPT Agent checks that the file :file:`signature.sha256` has been signed with the private key that matches the certificate present in the folder :file:`WAPT`. * The WAPT Agent then checks that the certificate or the chain of certificates in the :mimetype:`.crt` file has been signed with a key matching one of the certificates present in the folder :file:`C:\\Program Files (x86)\\wapt\\ssl`. * The WAPT Agent then generates the control sum of all the files contained in the package (except the files :file:`signature.sha256` and :mimetype:`.crt` file) and verifies that it matches the file :file:`manifest.sha256` contained in the package. * If one of these steps does not pass, this means that a file has been modified/ added/ removed. The execution of the :file:`setup.py` is then canceled. * The altered package is then deleted from the local cache and the event is journalized in the logs of the WAPT Agent. Security function F2B: signature of the attributes in the control files ----------------------------------------------------------------------- .. versionadded:: 1.4 .. note:: The risks avoided are: * An unauthorized entity modifying WAPT dependencies on WAPT equipped devices by falsifying :file:`https://waptserver/wapt/Packages`. Solution implemented ^^^^^^^^^^^^^^^^^^^^ When a WAPT package is signed, the sensitive attributes of the WAPT package are listed inside the **signed_attributes** attribute of the :file:`control` file. .. note:: Example of a *signed_attributes* list: *package*, *version*, *architecture*, *section*, *priority*, *maintainer*, *description*, *depends*, *conflicts*, *maturity*, *locale*, *min_os_version*, *max_os_version*, *min_wapt_version*, *sources*, *installed_size*, *signer*, *signer_fingerprint*, *signature_date*, *signed_attributes*, The attributes listed in *signed_attributes* are signed with the private key of the :term:`Administrator` and stored in the attribute *signature* of the :file:`control` file. The certificate matching the private key is stored in :file:`WAPT\\certificate.crt` inside the WAPT package. On the WAPT Server, the index :file:`Packages` is regenerated when the :command:`wapt-scanpackages` command is triggered by adding or removing a WAPT package. The WAPT Server extracts from each WAPT package the certificate of the signer and adds it to the :file:`Packages` zip file in the directory :file:`ssl`. Each certificate is named after its hexadecimal encoded fingerprint. When the WAPT Agent launches an *update*, it downloads the :file:`Packages` index file that contains the signed attributes of all available packages and the certificates of the signers. If the signer's certificate is approved, which means that the certificate has been signed by a Trusted :term:`Certificate Authority` or that the certificate itself is trusted, AND if the signer's certificate can verify the attributes' signature, the package is added to the index of available packages. Otherwise it is ignored. Security function F2C: access restriction to the installation folder of the WAPT Agent -------------------------------------------------------------------------------------- .. note:: The risks avoided are: * An unauthorized entity modifying the behavior of a WAPT Agent. The installation folder :file:`C:\\Program Files (x86)\\wapt` is accessible in read-write mode: * To the :term:`Local Administrators` by direct access to the installation folder of the WAPT Agent on the device. * To the :term:`Administrators` through the deployment of WAPT Agent upgrades. Neither the :term:`Package Deployers`, nor the :term:`Users` have write-access to the WAPT Agent's installation folder. The access restrictions to the :file:`wapt` folder rely on the standard ACLs mechanism of the Operating system and are enforced during installation of the WAPT Agent. Security function F2D: total access restriction to the folder storing the key / certificate for inventory signing ----------------------------------------------------------------------------------------------------------------- .. note:: The risks avoided are: * An unauthorized entity falsifying an inventory status update. * An unauthorized entity impersonating the identity of a WAPT equipped device. No access right is granted to any :term:`User` to :file:`C:\\Program Files (x86)\\wapt\\private`, whomever he may be. Only the WAPT Agent has a write and read access to this folder. .. note:: This method for storing the key and the certificate results from a technical design choice that says that the WAPT equipped device would embed any and all information related to itself. Security function F3: securing the communications between the different components of WAPT ========================================================================================== .. _signing_actions_relayed_to_WAPT_agents: Security function F3A: signature of immediate action calls sent to the WAPT Agents ---------------------------------------------------------------------------------- .. versionadded:: 1.5 .. note:: The risks avoided are: * An unauthorized entity sending falsified requests to the WAPT Agents. Solution implemented ^^^^^^^^^^^^^^^^^^^^ The following commands amongst others are signed by the WAPT Console before being sent to the targeted WAPT Agents via the WAPT server and Websockets: * :command:`trigger package install`: requests the WAPT Agent to install a WAPT package that is marked as **MISSING**. * :command:`trigger package remove`: requests the WAPT Agent to remove a WAPT package. * :command:`trigger package forget`: requests the WAPT Agent to forget the existence of a previously installed WAPT package without removing the software or the configuration. * :command:`trigger host update-status`: requests the WAPT Agent to send its current inventory status to the WAPT Server. * :command:`trigger host upgrade`: requests the WAPT Agent to execute a package flagged as **NEED UPGRADE**. * :command:`trigger host update`: requests the WAPT Agent to update the list of available packages, and check whether the client should install, upgrade or remove WAPT packages, depending on the WAPT packages dependencies tree. All the attributes in the requests for immediate action are signed: * the device's :term:`UUID`; * the action (ex: :command:`wapt-get install`); * the arguments (ex: tis-firefox); * the timestamp of the requests. The certificate matching the signature is passed along: * Upon receiving a request, the WAPT Agent verifies that the request has been properly signed. * The WAPT Agent will the verify that the timestamp is within a one minute delay window. * Ultimately, the WAPT Agent will verify that the certificate is authorized to launch actions. .. _wapt_crypto_principles: *********************************************** Presentation of server authentication processes *********************************************** Kerberos authentication is: * *admin*: the user name and pbkdf2-sha256 hash derivation of the password are stored in the server's configuration. This is the primary WAPT Administrator authentication mechanism. * *passwd*: additional secondary user names and passwords hash are stored in :file:`htpasswd` style file server side. * *ldap*: if the passwd hash is not defined in :file:`htpasswd` file, a ldap server can de declared and used as authentication mechanism for wapt server secondary accounts. Valid ldap accounts are defined by a ldap base DN and a ldap list of groups. * *session*: when initially authenticated using one of *admin*, *passwd* or *ldap* mechanism, a session cookie can be used as a subsitute for subsequent server authentication. The session cookie has a default lifetime of 12h. ********************************************** Presentation of server authorization processes ********************************************** * After proper authentication, the server stores the associated priviledges in client sessions. * In the context of the current TOE, only the *admin* priviledge is evaluated. * *admin* priviledge is an alias for all priviledges. Once authenticated, the User gains access to all the available endpoints of the WAPT Server. * If not authenticated, the User has still access to the packages repository which is public by design. ***************** Coverage matrices ***************** Threats and sensitive assets ============================ The following matrix shows the coverage of threats to sensitive assets (the letters **D**, **I**, **C** and **A** represent **Availability**, **Integrity**, **Confidentiality** and **Authenticity** requirements respectively): .. list-table:: Threat coverage of sensitive assets :header-rows: 1 :widths: auto :align: center * - - A1.Communications - A2.Inventory data - A3.Logs - A4.Configuration - A5.Client computers - A6.Authentication * - T1.Installation of malware - I,C - - - - I - * - T2.Configuration alteration - - - - I - - * - T3.Illegitimate access - - I,C - D - I,C - I - I,C * - T4.Network listening - C - C - - - - * - T5.Network alteration - I,A - I,A - - - - Threats and security features ============================= The following matrix shows the coverage of threats by security functions: .. list-table:: Threat coverage by security functions :header-rows: 1 :widths: auto :align: center * - - F1.Authentication access control - F2.Data protection - F3.Secured communications - F4.Package signature * - T1.Installation of malware - |ok| - |ok| - - |ok| * - T2.Configuration alteration - |ok| - |ok| - - * - T3.Illegitimate access - |ok| - - - * - T4.Network listening - - - |ok| - * - T5.Network alteration - - - |ok| - |ok|