From a03d4220ee460f3fc5e0bdc94a7acfb74cfed7cf Mon Sep 17 00:00:00 2001 From: Nathan Dyer Date: Fri, 17 May 2024 12:05:12 -0400 Subject: [PATCH 1/2] Fixes #556 by recommending sdconfig for most use cases. This commit minizes the use of manually editing the site-specific file, instead preferring the use of `securedrop-admin sdconfig` where applicable. As a result, this commit also restructures the flow of the OSSEC Guide, particularly during the sections related to installing SecureDrop. --- docs/admin/maintenance/ossec_alerts.rst | 115 +++++++++++------------- 1 file changed, 52 insertions(+), 63 deletions(-) diff --git a/docs/admin/maintenance/ossec_alerts.rst b/docs/admin/maintenance/ossec_alerts.rst index aea8a85bb..e51067234 100644 --- a/docs/admin/maintenance/ossec_alerts.rst +++ b/docs/admin/maintenance/ossec_alerts.rst @@ -7,27 +7,20 @@ Setting up OSSEC alerts ----------------------- OSSEC is an open source host-based intrusion detection system (IDS) that -we use to perform log analysis, file integrity checking, policy -monitoring, rootkit detection and real-time alerting. It is installed on +SecureDrop uses to perform log analysis, file integrity checking, policy +monitoring, rootkit detection, and real-time alerting. It is installed on the *Monitor Server* and constitutes that machine's main function. OSSEC -works in a server-agent scheme, that is, the OSSEC server extends its -existing functions to the *Application Server* through an agent installed on that -server, covering monitoring for both machines. +works in a server-agent scheme; that is, the OSSEC server extends its +existing functions to the *Application Server* through an agent installed +on that server, covering monitoring for both machines. In order to receive email alerts from OSSEC, you need to supply several settings to Ansible in the playbook for your environment. If you don't already have a working mail server or don't know what to do, then see the section below about using Gmail as a fallback option. We assume that you're working out of the 'securedrop' directory you cloned the code -into, and editing ``install_files/ansible-base/group_vars/all/site-specific`` -prior to installing SecureDrop. - -What you need: - -- The *OSSEC Alert Public Key* -- The email address that will receive alerts from OSSEC -- Information for your SMTP server or relay (hostname, port) -- Credentials for the email address that OSSEC will send alerts from +into, and that this configuration is happening prior to installing +SecureDrop. Receiving email alerts from OSSEC requires that you have an SMTP relay to route the emails. You can use an SMTP relay hosted internally, if one @@ -36,6 +29,18 @@ Gmail. The SMTP relay does not have to be on the same domain as the destination email address, i.e. smtp.gmail.com can be the SMTP relay and the destination address can be securedrop@freedom.press. +What you need: + +- The *OSSEC Alert Public Key* +- The fingerprint of the key used when encrypting OSSEC alerts +- The email address that will receive alerts from OSSEC +- The reachable hostname of your SMTP relay +- The secure SMTP port of your SMTP relay + (typically 25, 587, or 465. must support TLS encryption) +- An email username to authenticate to the SMTP relay +- The domain name of the email used to send OSSEC alerts +- The password of the email used to send OSSEC alerts + While there are risks involved with receiving these alerts, such as information leakage through metadata, we feel the benefit of knowing how the SecureDrop servers are functioning is worth it. If a third-party @@ -49,36 +54,23 @@ The SMTP relay that you use should support SASL authentication and SMTP TLS protocols TLSv1.2, TLSv1.1, and TLSv1. Most enterprise email solutions should be able to meet those requirements. -Below are the values you must specify to configure OSSEC correctly. -For first-time installs, you can use the -:ref:`configuration playbook`, or edit -``install_files/ansible-base/group_vars/all/site-specific`` manually. - -- *OSSEC Alert Public Key*: - ``ossec_alert_gpg_public_key`` -- Fingerprint of key used when encrypting OSSEC alerts: - ``ossec_gpg_fpr`` -- The email address that will receive alerts from OSSEC: - ``ossec_alert_email`` -- The reachable hostname of your SMTP relay: ``smtp_relay`` -- The secure SMTP port of your SMTP relay: ``smtp_relay_port`` - (typically 25, 587, or 465. must support TLS encryption) -- Email username to authenticate to the SMTP relay: ``sasl_username`` -- Domain name of the email used to send OSSEC alerts: ``sasl_domain`` -- Password of the email used to send OSSEC alerts: ``sasl_password`` +These values must be set in the +:ref:`configuration playbook` by running the +``securedrop-admin sdconfig`` command, which will prompt for each of the +items listed above. If you don't know what value to enter for one of these, please ask your organization's email admin for the full configuration before proceeding. It is better to get these right the first time rather than changing them after SecureDrop is installed. If you're not sure of the -correct ``smtp_relay_port`` number, you can use a simple mail client +correct SMTP relay port number, you can use a simple mail client such as Thunderbird to test different settings or a port scanning tool such as nmap to see what's open. You could also use telnet to make sure you can connect to an SMTP server, which will always transmit a reply code of 220 meaning "Service ready" upon a successful connection. -The ``smtp_relay`` mail server hostname is often, but not always, -different from the ``sasl_domain``, e.g. smtp.gmail.com and gmail.com. +The SMTP relay mail server hostname is often, but not always, +different from the SASL domain, e.g. smtp.gmail.com and gmail.com. In some cases, authentication or transport encryption mechanisms will vary and you may require later edits to the Postfix configuration @@ -90,8 +82,7 @@ although we've described some common scenarios in the If you have your *OSSEC Alert Public Key* public key handy, copy it to ``install_files/ansible-base`` and then specify the filename, e.g. -``ossec.pub``, in the ``ossec_alert_gpg_public_key`` line of -``group_vars/all/site-specific``. +``ossec.pub``, when prompted by ``securedrop-admin sdconfig``. If you don't have your GPG key ready, you can run GnuPG on the command line in order to find, import, and export your public key. It's best to copy the key @@ -133,24 +124,26 @@ installation: :: The fingerprint is a unique identifier for an encryption (public) key. The short and long key ids correspond to the last 8 and 16 hexadecimal digits of the -fingerprint, respectively, and are thus a subset of the fingerprint. The value -for ``ossec_gpg_fpr`` must be the full 40 hexadecimal digit GPG fingerprint for -this same key, with all capital letters and no spaces. The following command -will retrieve and format the fingerprint per our requirements: :: +fingerprint, respectively, and are thus a subset of the fingerprint. The full fingerprint +must be the entire 40 hexadecimal digit GPG fingerprint for this same key, with all capital +letters and no spaces. The following command will retrieve and format the fingerprint per our requirements: :: gpg --with-colons --fingerprint "" | grep "^fpr" | cut -d: -f10 -Next you specify the e-mail that you'll be sending alerts to, as -``ossec_alert_email``. This could be your work email, or an alias for a -group of IT admins at your organization. It helps for your mail -client to have the ability to filter the numerous messages from OSSEC -into a separate folder. +Next you must specify the e-mail that you'll be using to receive alerts. +This could be your work email, or an alias for a group of IT admins +at your organization. It helps for your mail client to have the ability +to filter the numerous messages from OSSEC into a separate folder. Now you can move on to the SMTP and SASL settings, which are straightforward. These correspond to the outgoing e-mail address used to send the alerts instead of where you're receiving them. If that e-mail -is ossec@news-org.com, the ``sasl_username`` would be OSSEC and -``sasl_domain`` would be news-org.com. +is ossec@news-org.com, the SASL Username would be OSSEC and +the SASL Domain would be news-org.com. + +After setting those values, ``securedrop-admin sdconfig`` will exit and return +you to the command line. In most cases, you will then be ready to +:ref:`proceed with the installation `. The Postfix configuration enforces certificate verification, and requires both a valid certificate and STARTTLS support on the SMTP @@ -163,10 +156,10 @@ new variable to ``group_vars/all/site-specific``: :: where ``MyOrg.crt`` is the filename. The file will be copied to the server in ``/etc/ssl/certs_local`` and the system CAs will be ignored -when validating the SMTP relay TLS certificate. +when validating the SMTP relay TLS certificate. Be sure to save +``group_vars/all/site-specific`` when you are finished. + -Save ``group_vars/all/site-specific``, exit the editor and :ref:`proceed with -the installation ` by running the playbooks. Using Gmail for OSSEC alerts ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -202,13 +195,12 @@ for the SMTP settings to enable OSSEC alerts. not allow mail to be sent. In order to be able to create an app password, you must have 2-Step Verification enabled on the Gmail account. -Once the account is created you can log out and provide the values for -``sasl_username`` as your new Gmail username (without the domain), -``sasl_domain``, which is typically gmail.com (or your custom Google -Apps domain), and ``sasl_passwd``. Remember to use the app password -generated from the 2-step config for ``sasl_passwd``, as the primary -account password won't work. The ``smtp_relay`` is smtp.gmail.com and -the ``smtp_relay_port`` is 587. +Once the account is created you can log out and run ``securedrop-admin sdconfig``, +setting the SASL username as your new Gmail username (without the domain), +the SASL domain to be either gmail.com or your custom Google +Apps domain, and then finally your SASL password. Remember to use the app password +generated from the 2-step config, as the primary account password won't work. The +SMTP relay will be smtp.gmail.com and the SMTP relay port is 587. Configuring fingerprint verification ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -302,12 +294,9 @@ After making changes to the Postfix configuration, you should run OSSEC service. .. tip:: If you change the SMTP relay port after installation for any - reason, you must update the ``smtp_relay_port`` variable in the - ``group_vars/all/site-specific`` file, then rerun the Ansible playbook. - As a general best practice, we recommend modifying and - rerunning the Ansible playbook instead of manually editing - the files live on the servers, since values like ``smtp_relay_port`` - are used in several locations throughout the config. + reason, you must update the SMTP relay port using + ``securedrop-admin sdconfig`` and deploy using + ``securedrop-admin install``. Useful log files for OSSEC ~~~~~~~~~~~~~~~~~~~~~~~~~~ From cb12ccf4a92ee0008d48f1f16f2ca8768d5c5ab5 Mon Sep 17 00:00:00 2001 From: Nathan Dyer Date: Fri, 24 May 2024 14:35:36 -0400 Subject: [PATCH 2/2] Small improvements to OSSEC guide. --- docs/admin/installation/install.rst | 4 ++-- docs/admin/maintenance/ossec_alerts.rst | 24 +++++++++++++----------- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/admin/installation/install.rst b/docs/admin/installation/install.rst index 0314a2986..e4adc54a5 100644 --- a/docs/admin/installation/install.rst +++ b/docs/admin/installation/install.rst @@ -33,8 +33,6 @@ on network speed and computing power. **not** as root. Contact the SecureDrop team if the package installation encounters repeated errors. -.. _configure_securedrop: - Localization of the *Source Interface* and *Journalist Interface* ----------------------------------------------------------------- @@ -52,6 +50,8 @@ parentheses. French to be available to read the documents and follow up in that language. +.. _configure_securedrop: + Configure the Installation -------------------------- diff --git a/docs/admin/maintenance/ossec_alerts.rst b/docs/admin/maintenance/ossec_alerts.rst index e51067234..b61a6a650 100644 --- a/docs/admin/maintenance/ossec_alerts.rst +++ b/docs/admin/maintenance/ossec_alerts.rst @@ -31,12 +31,11 @@ the destination address can be securedrop@freedom.press. What you need: -- The *OSSEC Alert Public Key* -- The fingerprint of the key used when encrypting OSSEC alerts +- The *OSSEC Alert Public Key* and its fingerprint - The email address that will receive alerts from OSSEC - The reachable hostname of your SMTP relay - The secure SMTP port of your SMTP relay - (typically 25, 587, or 465. must support TLS encryption) + (typically 25, 587, or 465; must support TLS encryption) - An email username to authenticate to the SMTP relay - The domain name of the email used to send OSSEC alerts - The password of the email used to send OSSEC alerts @@ -56,8 +55,11 @@ solutions should be able to meet those requirements. These values must be set in the :ref:`configuration playbook` by running the -``securedrop-admin sdconfig`` command, which will prompt for each of the -items listed above. +``./securedrop-admin sdconfig`` command, which will prompt for each of the +items listed above. Please note, this command updates the configuration, +but does not apply it to the servers. Any time you make changes to +the configuration it is necessary to deploy them with the +``./securedrop-admin install`` command. If you don't know what value to enter for one of these, please ask your organization's email admin for the full configuration before @@ -82,7 +84,7 @@ although we've described some common scenarios in the If you have your *OSSEC Alert Public Key* public key handy, copy it to ``install_files/ansible-base`` and then specify the filename, e.g. -``ossec.pub``, when prompted by ``securedrop-admin sdconfig``. +``ossec.pub``, when prompted by ``./securedrop-admin sdconfig``. If you don't have your GPG key ready, you can run GnuPG on the command line in order to find, import, and export your public key. It's best to copy the key @@ -141,8 +143,8 @@ send the alerts instead of where you're receiving them. If that e-mail is ossec@news-org.com, the SASL Username would be OSSEC and the SASL Domain would be news-org.com. -After setting those values, ``securedrop-admin sdconfig`` will exit and return -you to the command line. In most cases, you will then be ready to +After setting those values, ``./securedrop-admin sdconfig`` will exit and +return you to the command line. In most cases, you will then be ready to :ref:`proceed with the installation `. The Postfix configuration enforces certificate verification, and @@ -195,7 +197,7 @@ for the SMTP settings to enable OSSEC alerts. not allow mail to be sent. In order to be able to create an app password, you must have 2-Step Verification enabled on the Gmail account. -Once the account is created you can log out and run ``securedrop-admin sdconfig``, +Once the account is created you can log out and run ``./securedrop-admin sdconfig``, setting the SASL username as your new Gmail username (without the domain), the SASL domain to be either gmail.com or your custom Google Apps domain, and then finally your SASL password. Remember to use the app password @@ -295,8 +297,8 @@ OSSEC service. .. tip:: If you change the SMTP relay port after installation for any reason, you must update the SMTP relay port using - ``securedrop-admin sdconfig`` and deploy using - ``securedrop-admin install``. + ``./securedrop-admin sdconfig`` and deploy using + ``./securedrop-admin install``. Useful log files for OSSEC ~~~~~~~~~~~~~~~~~~~~~~~~~~