Merge pull request #41 from pierwill/edit-readme

Edit README.md

README.md

@@ -2,12 +2,21 @@
 
 [![CircleCI](https://circleci.com/gh/freedomofpress/securedrop-proxy.svg?style=svg)](https://circleci.com/gh/freedomofpress/securedrop-proxy)
 
-This implements a Qubes RPC <-> HTTP proxy, used to forward requests
-from the [securedrop workstation
-client](https://github.com/freedomofpress/securedrop-client) to the
-[securedrop server](https://github.com/freedomofpress/securedrop).
+`securedrop-proxy` is part of the [SecureDrop
+Workstation](https://github.com/freedomofpress/securedrop-workstation) project.
 
-### try it out
+The code in this repository implements a proxy across two APIs: the [Qubes RPC
+protocol](https://www.qubes-os.org/doc/qrexec3/) and the [SecureDrop
+API](https://docs.securedrop.org/en/latest/development/journalist_api.html).
+This proxy is used to forward requests from the securedrop workstation client to
+the securedrop server.
+
+This code is still in development, and not quite ready for integration with the
+rest of the Securedrop Workstation project. However, it is ready to be poked at
+and demonstrated. Feel free to explore and contribute! You'll need a machine
+running [Qubes OS](https://qubes-os.org).
+
+### How It Works
 
 The proxy works by reading a JSON object from STDIN, generating an
 HTTP request from that JSON, making that request against the remote
@@ -16,22 +25,18 @@ server's response to STDOUT. For discussion about the shape of the
 request and response objects, see
 https://github.com/freedomofpress/securedrop-workstation/issues/107.
 
-This is still development code, not quite ready for integration with the
-rest of the securedrop-workstation project. However, it is ready to
-be poked at and demonstrated.
-
-#### install requirements
+#### Installation Requirements
 
-To try the proxy script, first use `venv` to create an environment
-and install requirements. In the root of the project directory, run
+To try the proxy script, create a virtual environment and install the
+requirements. In the root of the project directory, run
 
 ```
 virtualenv .venv
 source .venv/bin/activate
 pip install --require-hashes -r dev-requirements.txt
 ```
 
-#### Update dependencies
+#### Update Dependencies
 
 If you're adding or updating a dependency, you need to:
 
@@ -53,8 +58,7 @@ the updated dependency to our pip mirror (you can request this in the PR).
 3. You should confirm via a manual debian package build and manual testing in Qubes that there are no regressions (this is limited pre-release QA).
 4. Once your PR is approved, you can add a tag and push: `git tag $new_version_number`.
 
-
-#### configuration
+#### Configuration
 
 The proxy script must be run with the path to its configuration file
 as its first argument. This repo includes an example configuration
@@ -67,7 +71,6 @@ following values:
 - `dev` - A boolean, where `True` indicates we're running in development mode, any other value (or not set) indicates we're running in production. See below for what that means.
 - `target_vm` - The name of the VM we should `qvm-move` non-JSON responses to. Must be set if dev is not True.
 
-
 #### dev vs prod
 
 Configuration includes a "dev" attribute. At this point, the only
@@ -78,11 +81,11 @@ mode, the file is not moved off the VM, but is saved as a temporary
 file in `/tmp`. In both cases, the response written to STDOUT includes
 the name of the new file.
 
-#### tests
+#### Tests
 
-Unit tests can be run with `make test`
+Unit tests can be run with `make test`.
 
-#### running
+#### Example Commands
 
 The following commands can be used to demonstrate the proxy.
 
@@ -97,13 +100,13 @@ read at that name under `/tmp`.
 
     $ cat examples/html.json | ./sd-proxy.py ./config-example.yaml
 
-Finally, this demonstrates some error handling. The request contains
-invalid JSON. The proxy detects that, and prints an error message
-(still a valid proxy response).
+Finally, this demonstrates some error handling. The request contains invalid
+JSON. The proxy detects the malformed request, and prints an error message.
+(The error message itself is considered a valid proxy response).
 
     $ cat examples/bad.json | ./sd-proxy.py ./config-example.yaml
 
-#### Qubes integration
+#### Qubes Integration
 
 Until we determine how we wish to package and install this script,
 demonstrating the proxy in a Qubes environment is a somewhat manual
@@ -117,12 +120,12 @@ this documentation, we assume the client is running in
 
 Edit `qubes/securedrop.Proxy` to reflect the path to `entrypoint.sh`
 in this repo. Also edit the directory to this repo code in `entrypoint.sh`.
-Next, run `sudo cp qubes/securedrop.Proxy /etc/qubes-rpc/securedrop.Proxy`, which will move `securedrop.Proxy`
-(the qubes-rpc "server path definition" file) into place in
-`/etc/qubes-rpc/`.
+Next, run `sudo cp qubes/securedrop.Proxy /etc/qubes-rpc/securedrop.Proxy`.
+This will move `securedrop.Proxy` (the qubes-rpc "server path definition" file)
+into place in `/etc/qubes-rpc/`.
 
-On `dom0`, create the file `/etc/qubes-rpc/policy/securedrop.Proxy`
-with the contents:
+In `dom0`, create the file `/etc/qubes-rpc/policy/securedrop.Proxy`
+with the contents
 
     securedrop-client securedrop-proxy allow
     $anyvm $anyvm deny
@@ -140,14 +143,15 @@ names for your environment). This allows non-JSON responses to be
 moved to the client VM using Qubes' native inter-VM file copy service.
 
 Copy `config-example.yaml` to `config.yaml`, and edit it to reflect
-your situation- check that `target_vm` is set to the correct client VM
-name, and assure that `dev` is `False`. This documentation assumes
+your situation. Ensure that `target_vm` is set to the correct client VM
+name, and that `dev` is `False`. This documentation assumes
 you've left `host` set to `jsonplaceholder.typicode.com`.
 
-Now on the client VM you should be able to do (again replacing `securedrop-proxy` with the name of your proxy AppVM):
+At this point, in the client VM you should be able to do
 
     $ echo '{"method":"GET","path_query":"/posts?userId=1"}' | /usr/lib/qubes/qrexec-client-vm securedrop-proxy securedrop.Proxy
 
+(again replacing `securedrop-proxy` with the name of your proxy AppVM)
 You should see a successful JSON response as returned by the remote server.
 
 Try now
@@ -162,11 +166,11 @@ response which include a `body` which looks like:
     }
 
 If you look in `~/QubesIncoming/securedrop-proxy`, you should see a
-new file with that name. The content of that file will be the content
+new file with that name. The content of that file will reflect the content
 returned by the remote server.
 
-Finally, try invoking an error. Provide an invalid JSON request, and
-notice you receive a `400` response from the proxy:
+Finally, try invoking an error by providing an invalid JSON request.
+Notice that you receive a `400` response from the proxy:
 
     $ echo '[INVALID' | /usr/lib/qubes/qrexec-client-vm securedrop-proxy securedrop.Proxy
     {"body": "{\"error\": \"Invalid JSON in request\"}", "version": "0.1.1", "status": 400, "headers": {"Content-Type": "application/json"}}