Further integrate SDW docs, initial work for Installation and Migration documentation, eliminate need to jump around docs#782
Further integrate SDW docs, initial work for Installation and Migration documentation, eliminate need to jump around docs#782ChumOfChance wants to merge 24 commits intomainfrom
Conversation
…oving other snippets where relevant.
…n sections. start migration section
I love this!
+1
Sounds reasonable, I'm sure I'll have nit-picky comments inline though
Thanks for catching those!
Nice!
This is brilliant and has needing doing for a while. I would caution us to be careful about scope creep here in this PR, though. We should do the minimum needed to get the structure right, then flesh it all out in a subsequent PR.
This seems reasonable, with the additional requisite complaining that I really don't like calling everything a Workstation and would almost prefer to ban that word from our vocabulary.
Perfect, that's squarely out of scope here I think. Great call! |
|
The OSSEC guide was one of the biggest "choose your own adventure" jumps around the documentation during the install process, so I think it really needed to be tackled here. |
… partial includes from other pages
ChumOfChance
changed the title
There was a problem hiding this comment.
Love this! I strongly agree that transforming Overview of 9 subsections into Introduction of 4 subsections is a major change for the better.
I’m not sure we've finalized how we'll use terminology like App and Workstation but I don't think it has to be perfect for this PR to go forward.
| @@ -1,4 +1,4 @@ | |||
| Working with submissions | |||
| Working with Submissions | |||
There was a problem hiding this comment.
Do we have a convention on sentence case vs title case in headings and page titles? I'm seeing a mix in the docs.
If there's not a convention, I'd suggest standardizing on sentence case, leaving "submissions" lower case.
|
|
||
| We consider the first two requirements and the last three preferred attributes. | ||
|
|
||
| This Admin Guide will walk you through the entire experience, from planning to installation, to deployment, to ongoing maintenance. |
There was a problem hiding this comment.
| This Admin Guide will walk you through the entire experience, from planning to installation, to deployment, to ongoing maintenance. | |
| This Admin Guide covers planning, installation, deployment, and ongoing maintenance of a SecureDrop installation. |
nathandyer
left a comment
nathandyer
left a comment
There was a problem hiding this comment.
Overall I really love these changes! I've made some in-line notes about typos, mixed casing, etc. On some of the brand new pages I didn't fully mark all the headings that need to be title-cased, but I would recommend going through and making sure they're all using it consistently.
One quick thought, I wonder if the specific firewall configuration guides should be nested one level under the firewall guide? Since that's kind of a branching path.
In any case, this is incredible work, and structure/content wise I think it's ready to land!
| Prepare email accounts | ||
| ====================== | ||
|
|
||
| Optional: Daily Journalist Alerts |
There was a problem hiding this comment.
Nitpick: should the OSSEC explainer go up top, and the section explaining the optional alerts go at the end?
| Using Gmail for OSSEC alerts | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| It's easy to get SecureDrop to use Google's servers to deliver the |
There was a problem hiding this comment.
Unrelated to your specific changes, but I think we should get rid of "it's easy to..." here. For one, we should avoiding saying things are easy as a matter of practice, because people who don't find it easy may get discouraged. And for another reason, it's actually a bit more difficult now than it used to be, with the transition to app-specific passwords and requiring 2FA to be enabled.
| @@ -1,22 +1,83 @@ | |||
| Install SecureDrop | |||
| ================== | |||
| Install SecureDrop on the servers | |||
There was a problem hiding this comment.
| Install SecureDrop on the servers | |
| Install SecureDrop on the Servers |
For consistency, this should probably be in Title Case
There was a problem hiding this comment.
It's fine to upcase this for consistency with the existing docs but, in my view, we should (sometime later) revisit this convention. FPF's style guide says:
Headlines and subheads use sentence case (initial capital, then lowercase)
Further, title case is considered distinctively American which I think cuts against our desire for SecureDrop to be an international tool.
There was a problem hiding this comment.
I agree with that, @jskinne3, and I'll also mention that I noticed after I left this review that our docs are already inconsistent as to whether they use title case or sentence case for headings (even those at the same level).
@ChumOfChance I don't think we can realistically resolve all of that in this PR, so feel free to disregard my title case suggestions in areas where you don't think it makes sense
| - Open the KeePassXC program |KeePassXC| in the `vault` VM | ||
| - Select **Database ▸ Open database**, and navigate to the location of | ||
| **~/Persistent/Passwords.kdbx**, select it, and click **Open** | ||
| **/path/to/Passwords.kdbx**, select it, and click **Open** |
There was a problem hiding this comment.
Using /path/to is probably okay for now but we need to be sure to update this once the admin tooling on Qubes is fully fleshed out and we know where the template lives.
|
|
||
| All access to the SecureDrop servers should be performed over SSH from the | ||
| *Admin Workstation*. To aid in troubleshooting, login via a physical keyboard | ||
| Primacy SecureDrop Workstation. To aid in troubleshooting, login via a physical keyboard |
There was a problem hiding this comment.
| Primacy SecureDrop Workstation. To aid in troubleshooting, login via a physical keyboard | |
| Primary SecureDrop Workstation. To aid in troubleshooting, login via a physical keyboard |
typo
| If you have any suggestions on how to further tune or improve the alerting, | ||
| you can open an issue on `GitHub <https://github.com/freedomofpress/securedrop/labels/goals%3A%20reduce%20IDS%20noise>`__. | ||
|
|
||
| Uncommon OSSEC alerts |
There was a problem hiding this comment.
| Uncommon OSSEC alerts | |
| Uncommon OSSEC Alerts |
| Uncommon OSSEC alerts | ||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Data integrity |
There was a problem hiding this comment.
| Data integrity | |
| Data Integrity |
|
|
||
| To resolve the issue, you can :ref:`clean them up <submission-cleanup>`. | ||
|
|
||
| Instance misconfigurations |
There was a problem hiding this comment.
| Instance misconfigurations | |
| Instance Misconfigurations |
| To resolve the issue, you can reinstate the standard iptables | ||
| rules by :ref:`updating the system configuration <update-system-configuration>`. | ||
|
|
||
| ``securedrop-admin`` commands |
There was a problem hiding this comment.
| ``securedrop-admin`` commands | |
| ``securedrop-admin`` Commands |
|
|
||
| .. _Networking Architecture: | ||
|
|
||
| SecureDrop Workstation networking architecture |
There was a problem hiding this comment.
| SecureDrop Workstation networking architecture | |
| SecureDrop Workstation Networking Architecture |
3 participants
This PR further integrates the SecureDrop Workstation docs with the current SecureDrop documentation looking towards the time where a Qubes-based SecureDrop Workstation is used for server administration (with
securedrop-adminrunning in asd-adminVM, or a similar arrangement ) in lieu of the current Tails-based "Admin Workstation", and the Tails-based workflow is depreciated (or at least not documented in these docs).In doing this there is a lot of consolidation of sections of the respective docs, and in some cases removal of redundant content. This primarily affects the Introductory and Installation materials. A major goal is #763, so whenever possible, I wanted the reader to not have to jump around the documentation. Also addresses #756 #776 and #72
I avoided writing new copy where possible. My intention is more to establish a structure. I expect there will be a lot of polish and rewriting to come.
Test plan
Checklist
This change accounts for:
Introduction
I moved and consolidated a lot of material from both docs to the Introduction section (and moved the files into a sub-folder for clarity).
I created a new Introduction page "Qubes OS and SecureDrop Workstation" which consolidates all the introductions of the architecture, isolation and networking of the SDW. I moved questions from the SDW Journalist FAQ moved here. Both journalists and administrators will be using the Qubes-based SDW, so there should be one page explaining the necessary bits.
In the spirit of #72, I created an "Appendices" section for reference material, much of which was previously in the Introduction section: long pages that aren't necessary to read for an installation, and the glossary (which there is some debate about keeping). This section could be renamed "Reference" or "Security", or something else as appropriate.
Installation
I reworked the previous "Admin Guide: Reference" pages "SecureDrop for Administrators" and "Responsibilities" into "Introduction for SecureDrop Administrators"
The "Installation Overview" page is now extremely comprehensive, combining the exceptions, how to track your progress, a technical summary of the steps, the minimum security requirements that should be considered before an installation. The "Passphrases" page here is updated for SDW and consolidates the "Passphrase Best Practices".
There is some vagueness around the final install process for setting up
securedrop-adminin ansd-adminVM on the SecureDrop Workstation. I have assumed there will be a separate step configuring this via salt distinct from runningsdw-admin --applybecause of the necessary order of operations for the entire install. I added placeholder sections where appropriate.The OSSEC guide has been cannabalized. A new page "Installation/Preparing Email Alerts" covers what's needed to set up e-mail accounts + keys + server credentials before installation. This page also introduces what's needed for the optional daily journalist alert emails.
The steps to configure the OSSEC alerts at install time are part of the install guide, inline. The troubleshooting OSSEC sections are moved to their own page at the end of the installation process (they are mostly related to troubleshooting during installation).
Other installation-related troubleshooting content is also inserted at the end of the "Installation" section. Troubleshooting pages could be moved in order to where they might be most likely encountered (in this case, right after installing Qubes), but I think at the end of the "Installation" section is acceptable. The steps for troubleshooting a bad
sdw-admin --applyrun are on the page where that step is run.Migration
A section for Migration (from Tails-based SecureDrop) was added. There is a reference at the start of the "Installation Overview" to skip to this section if applicable. I've tried a few implements of the
includestart-afterend-beforeto include partial sections of other pages, preferred over having users jump back and forth around the docs. A good example can be seen in the "Admin Migration" page, which reuses steps from the main documentation for preparing and installing a SecureDrop Workstation. I'd like to keep using this in future sections, e.g. for onboarding journalists/preparing additional SecureDrop WorkstationsReference
As noted above, some of the "Admin Guide Reference" pages were moved/consolidated to Installation pages. I also broke up the FAQ (a network troubleshooting question was moved to the Qubes network troubleshooting page).
Journalist Guide
Another big consolidation here of the two documentations. I tried to preserve useful general guidance we had in the SecureDrop docs and incorporate it into the SecureDrop Workstation guide to using the SecureDrop App on Qubes. I also broke up the FAQ, moving most of the questions about Qubes to the new "SecureDrop and Qubes OS" intro page.
Nomenclature
I've gone with "Primary SecureDrop Workstation" to refer to the first SecureDrop Workstation that is installed which must necessarily have the admin tooling on it. I didn't want to call this the Admin Workstation for two reasons:
We could come up with another name, I'm not particularly attached to and consider it a placeholder. In any case currently missing is an explanation of the difference between a SecureDrop Workstation used by an administrator and one used by a journalist.
I've referred to the SecureDrop App for the client that is used on the SecureDrop Workstation. I'm not sure if this has been decided on as the official name.
Other notes: