[docs] Revise and restructure README.md #311
Conversation
- Add note in README on the risks of copying data to dom0 - Add suggestion for seeting up a dev VM
Also moves "Building the Templates" to Development heading and makes some other structural changes to headings
eloquence
changed the title
There was a problem hiding this comment.
Nice improvement to the docs!
I'm approving but I left some comments if you want to address them while I see if anyone is available to go through installation, configuration, and test. I think @rmol might be doing a fresh install, so perhaps they can make sure all the steps are correct.
All in all, lgtm!
|
|
||
| #### Qubes 4.0.1 | ||
|  |
There was a problem hiding this comment.
it might be difficult for someone to figure out that decr. sub in this data flow diagram means decrypted submissions but otherwise this diagram looks good
|
|
||
| After installing Qubes, you must update both dom0 and the base templates to include the latest versions of apt packages. | ||
| - `sd-proxy` is where the SecureDrop proxy resides, which allows the non-networked `sd-svs` vm to communicate with the *Journalist Interface* over Tor. | ||
| - `sd-svs` is a non-networked VM in which the *SecureDrop Client* runs used to store and explore submissions after they're unarchived and decrypted. Any files opened in this VM are opened in a disposable VM. |
There was a problem hiding this comment.
might be useful to link to the securedrop-client project here
|
|
||
| After installing Qubes, you must update both dom0 and the base templates to include the latest versions of apt packages. | ||
| - `sd-proxy` is where the SecureDrop proxy resides, which allows the non-networked `sd-svs` vm to communicate with the *Journalist Interface* over Tor. |
There was a problem hiding this comment.
link to the securedrop-proxy project and the journalist interface api might be useful here
| Open a terminal in `dom0` by clicking on the Qubes menu top-right of the screen and left-clicking on Terminal Emulator and run: | ||
| 1. Journalist uses the *SecureDrop Client* to access the *Journalist Interface* via the Journalist API. After logging in, the journalist clicks | ||
| on any submission of interest. | ||
| 2. The *SecureDrop Client* will use `sd-gpg` to decrypt the submission using Qubes' split-GPG functionality (decryption is done in a trusted, isolated VM, keeping GPG keys off of the system-wide DispVM). |
There was a problem hiding this comment.
I don't think there's been a definition of DispVM yet it might be clearer to say disposable VM
| on any submission of interest. | ||
| 2. The *SecureDrop Client* will use `sd-gpg` to decrypt the submission using Qubes' split-GPG functionality (decryption is done in a trusted, isolated VM, keeping GPG keys off of the system-wide DispVM). | ||
| 5. The decrypted submission is stored on the `sd-svs` *Secure Viewing Station VM*, where it's placed in a local database. | ||
| 6. Any file opened by the *SecureDrop Client* in the *Secure Viewing Station VM* is opened in a Disposable VM, largely mitigating attacks from malicious content. |
There was a problem hiding this comment.
I think it makes sense to add a note about how moving submissions is also restricted by the disposable Export VM, which only allows transfer to encrypted USB devices or supported printers (link needed, hopefully this exists already, but I think this restriction is due to the challenges of setting up a printer on the disposable vm)
|
|
||
| Qubes uses SaltStack internally for VM provisionining and configuration management (see https://www.qubes-os.org/doc/salt/), so it's natural for us to use it as well. The `dom0` directory contains salt `.top` and `.sls` files used to provision the VMs noted above. | ||
| - `Makefile` is used with the `make` command on `dom0` to build the Qubes/SecureDrop installation, and also contains some development and testing features. | ||
| - The [SecureDrop Client](https://github.com/freedomofpress/securedrop-client) is installed in `sd-svs` and will be used to access the SecureDrop server *Journalist Interface* via the SecureDrop proxy. |
There was a problem hiding this comment.
I think this should be moved from "What's in this repo" since the client and proxy are not in this repo, and you've already mentioned that the client is installed on sd-svs and the proxy is installed on sd-proxy in the Currently, the following VMs are provisioned: section (they just need links to repos there).
|
|
||
| ## Installation | ||
|
|
||
| Installing this project is involved. It requires an up-to-date Qubes 4.0 installation running on a machine with at least 12GB of RAM. You'll need access to a SecureDrop staging server as well. |
There was a problem hiding this comment.
You'll need access to a SecureDrop
stagingserver as well.
This PR is mostly a high-level reorganization of the material in this document. After the intro, the doc now begins with the rationale, architecture, and description of the repo. In the main text, technical material has been reordered and moved to four main sections: Installation, Development, Using the SecureDrop Client, and Distributing and Releasing. (The threat model section has not been changed at all.) There's also a table of contents.
Also makes some small edits, formatting, etc.