Qt-based client for working with SecureDrop submissions on the SecureDrop Qubes Workstation. In Qubes, this application runs within a VM that has no direct network access, and files open in individual, non-networked, disposable VMs. API requests and responses to and from the SecureDrop application server are sent through an intermediate VM using the Qubes SecureDrop proxy. For additional background, see the main SecureDrop Workstation repository, and read about the user research and design work that informs this work.
IMPORTANT: This project is in alpha and should not be used in production environments. There are known bugs which can be found in this project’s issue tracker.
This client is under active development and currently supports a minimal feature set. Major supported features include:
- the download and decryption of files, messages, and replies (using Qubes split-gpg)
- the display of decrypted messages and replies in a new conversation view
- the opening of all files in individual, non-networked, Qubes disposable VMs
- replying to sources
- deleting sources
- exporting files to LUKS-encrypted USB drives
- printing to supported printers
The quickest way to get started with running the client is to use the developer environment that runs against a test server running in a local docker container. This differs from a staging or production environment where the client receives and sends requests over Tor. Things are a lot snappier in the developer environment and can sometimes lead to a much different user experience, which is why it is important to do end-to-end testing in Qubes using the staging environment, especially if you are modifying code paths involving how we handle server requests and responses.
For reproducing production bugs or running demos, we recommend using the Production Environment that will allow you to test a nightly build of the client.
We support running the developer environment on a non-Qubes OS for developer convenience. If this is your preferred environment, keep in mind that you, or a PR reviewer, will need to run tests in Qubes if you modify code paths involving any of the following:
- cryptography
- opening of files in VMs
- network (via the RPC service) traffic
- fine tuning of the graphical user interface
In order to login, or take other actions involving network access, you will need to run the client against a SecureDrop server. If you don't have a production server or want to test against a test server, you can install a SecureDrop server inside a dev container by following the instructions in the SecureDrop documentation.
The client uses the SecureDrop SDK to interact with the SecureDrop Journalist API. After you run the server container, the journalist interface API will be running on 127.0.0.1:8081
with a test journalist, admin, and test sources and replies.
To ensure that file decryption works, please import this test private key into your GnuPG keyring. Submissions in the SecureDrop server dev environment can be decrypted with this test key.
Running the client in a developer environment will use a temporary directory as its configuration directory, instead of ~/.securedrop_client
. A development gpg private key inside a gpg keychain is stored in the temporary configuration directory, which will be used to decrypt messages sent from the server running in the local docker container.
The SecureDrop client will open or export file submissions within disposable AppVms.
Tor is not used in the developer environment. If you want to use a Tor connection between the client and server, then you'll need to follow the staging environment instructions instead.
-
Open a terminal in the
sd-app
AppVM in Qubes -
Run a SecureDrop server in a local docker container
See SecureDrop docs for setup instructions, including post-installation steps for allowing docker to be run as a non-root user, which is a requirement on Qubes.
- In a new terminal tab, clone the SecureDrop Client repo and set up its virtual environment
git clone git@github.com:freedomofpress/securedrop-client.git
cd securedrop-client
virtualenv --python=python3.7 .venv
source .venv/bin/activate
pip install --require-hashes -r requirements/dev-requirements.txt
- Run SecureDrop Client
./run.sh
Or, if you want to persist data across restarts, you will need to run the client with:
./run.sh --sdc-home /path/to/my/configuration/directory
Running the client in a developer environment will use a temporary directory as its configuration directory, instead of ~/.securedrop_client
. A development gpg private key inside a gpg keychain is stored in the temporary configuration directory, which will be used to decrypt messages.
If you want to be able to open or export file submissions in a disposable AppVM, then you'll need to follow the instructions for running this in a developer environment in Qubes.
Tor is not used in the developer environment. If you want to use a Tor connection between the client and server, then you'll need to follow the staging environment instructions instead.
-
Open a terminal from your non-Qubes OS
-
Run a SecureDrop server in a local docker container
See SecureDrop docs for setup instructions.
- In a new terminal tab, clone the SecureDrop Client repo and set up its virtual environment
git clone git@github.com:freedomofpress/securedrop-client.git
cd securedrop-client
virtualenv --python=python3.7 .venv
source .venv/bin/activate
pip install --require-hashes -r requirements/dev-requirements.txt
- Run SecureDrop Client
./run.sh
Or, if you want to persist data across restarts, you will need to run the client with:
./run.sh --sdc-home /path/to/my/configuration/directory
Running the SecureDrop client in a staging environment will use a ~/.securedrop_client
as its configuration directory. The gpg key in the sd-gpg
AppVM configured during make all
will be used to decrypt messages.
The SecureDrop client will open or export file submissions within disposable AppVms.
Requests and responses between the client and server use a Tor connection, which are proxied via the securedrop-proxy
AppVM's RPC service.
- Run a SecureDrop staging server
See SecureDrop docs on setting up a staging server or SecureDrop docs on setting up a staging server in Qubes
-
Open a terminal in
dom0
in Qubes -
Create a
config.json
file
cd securedrop-worksation
cp config.json.example config.json
vi config.json
config.json.example
already contains the staging server's submission key fingerprint (and sd-journalist.sec
already contains the staging server's private submission key) so all you need to do is update the hidserv hostname and key in config.json
. To find this information, you can run sudo cat /var/lib/tor/services/journalist/hostname
on you staging server.
-
Run
make all
to configure the AppVms -
Open a terminal in the
sd-app
AppVM -
Initialize the SecureDrop Client database by running the installed client (e.g. nightly build) once by running:
securedrop-client
Or manually initialize the SecureDrop Client database.
- To run a different version of the client, first add a NetVM (
sys-firewall
) tosd-app
via its Qubes Settings so you can clone the client repository, and then follow these steps:
git clone git@github.com:freedomofpress/securedrop-client.git
cd securedrop-client
virtualenv --python=python3.7 .venv
source .venv/bin/activate
pip install --require-hashes -r requirements/dev-requirements.txt
- Run the client
python -m securedrop_client
Running the SecureDrop client in a production environment will use a ~/.securedrop_client
as its configuration directory. The gpg key in the sd-gpg
AppVM configured during make all
will be used to decrypt messages.
The SecureDrop client will open or export file submissions within disposable AppVms.
Requests and responses between the client and server use a Tor connection, which are proxied via the securedrop-proxy
AppVM's RPC service.
- Run a SecureDrop server
See SecureDrop docs on setting up a server
-
Open a terminal in
dom0
in Qubes -
Create a
config.json
file
cd securedrop-worksation
cp config.json.example config.json
vi config.json
Update the hidserv hostname and key in config.json
. To find this information, you can run sudo cat /var/lib/tor/services/journalist/hostname
on you staging server. Update the Submission Key fingerprint as well.
- Create an
sd-journalist.sec
file
Create sd-journalist.sec
in the securedrop-workstation
directory in dom0
and copy your server's private submission key to this file. You can find this key in ~/Persistent/securedrop/install_files/ansible-base
on the Tails drive you used to set up your SecureDrop server.
- Run the nightly build of the client by double-clicking the SecureDrop shortcut on your Qubes Desktop
securedrop-client
# install Homebrew https://brew.sh/
brew install pyenv
# follow step 3 onwards of https://github.com/pyenv/pyenv#basic-github-checkout
# install and select the latest version of python 3.7.x
pyenv install 3.7.x
pyenv local 3.7.x
pip install virtualenv
virtualenv --python=python3.7 .venv
source .venv/bin/activate
pip install --require-hashes -r requirements/dev-mac-requirements.txt
We have several dependency files: dev-requirements.txt
(Linux), dev-mac-requirements.txt
(macOS) and requirements.txt
point to python software foundation hashes, and build-requirements.txt
points to our builds of the wheels from our own pip mirror (https://pypi.securedrop.org/). Whenever a dependency in build-requirements.txt
changes, our team needs to manually review the code in the dependency diff with a focus on spotting vulnerabilities.
If you're adding or updating a dependency, you need to:
-
Modify either
requirements.in
ordev-requirements.in
(depending on whether it is prod or dev only) and then runmake update-pip-requirements
. This will generatedev-requirements.txt
andrequirements.txt
. -
For building a debian package from this project, we use the requirements in
build-requirements.txt
which uses our pip mirror, i.e. the hashes in that file point to wheels on our pip mirror. A maintainer will need to add the updated dependency to our pip mirror (you can request this in the PR). -
Once the pip mirror is updated, you should checkout the securedrop-debian-packaging repo and run
make requirements
. Commit thebuild-requirements.txt
that results and add it to your PR.
rm -f svs.sqlite
sqlite3 svs.sqlite .databases > /dev/null
alembic upgrade head
alembic revision --autogenerate -m "describe your revision here"
An AppArmor profile is available for mandatory access control. When installing securedrop-client from a .deb package, the AppArmor profile will automatically be copied and enforced. Below are instructions to use the profile in non-production scenarios.
-
The entrypoint for the application must be through
/usr/bin/securedrop-client
with application code in/opt/venvs/securedrop-client
. -
The kernel must support AppArmor (running
sudo aa-status
will return zero if AppArmor is supported). -
The
apparmor-utils
package is installed (sudo apt install apparmor-utils
in Debian).
-
Copy
files/usr.bin.securedrop-client
to/etc/apparmor.d/
. -
sudo aa-enforce /etc/apparmor.d/usr.bin.securedrop-client/
. -
sudo aa-status
and observe securedrop-client profile is being enforced.
-
Update the profile in
/etc/apparmor.d/usr.bin.securedrop-client
. -
sudo aa-teardown
. -
sudo service apparmor restart
. -
Once you've made all the changes necessary (e.g.: no apparmor errors in
/var/log/syslog
) you can copy/etc/apparmor.d/usr.bin.securedrop-client
intofiles/usr.bin.securedrop-client
in this repository and commit the changes.
In order to run the test suite you should also install the xvfb
package (to make the xvfb-run
command available): apt install xvfb
. You may also need to install the sqlite3
command: apt install sqlite3
.
To run all tests and checks, run:
make check
To only run unit tests, run:
make test
To run unit tests in random order, run:
make test-random
To only run integration tests, run:
make test-integration
To only run functional tests, run:
make test-functional
When functional tests are run, they replay recorded API request and response data instead of making actual API calls to a server. This is why tests can pass even when there is no server running. If you want to add new tests that make API calls or if the SDK ever changes its API, then you'll need to record new request and response data by following the steps outlined in Generating new cassettes.
We use qtbot
, bundled with the pytest-qt package, for UI interaction within our functional tests.
We use vcrpy to record and replay API calls. Each request made from a test and response from the server is stored in a "cassette" yaml file in the tests/functional/cassettes
directory.
If the SDK changes its API, then you'll see the following warning indicating that a request failed to be found in an existing cassette and that you'll need to regenerate cassettes:
Can't overwrite existing cassette ('<path-to-cassette-for-a-functional-test>') in your current record mode ('once').
To set up a local dev server and generate cassettes, follow these steps:
- Bypass TOTP verification so that we can use the TOTP value of
123456
hard-coded intests/conftest.py
. You can do this by applying the following patch to the server code:
https://gist.github.com/creviera/8793d5ec4d28f034f2c1e8320a93866a
-
Start the server in a docker container by running:
NUM_SOURCES=0 make dev
-
Create two new sources, each with one submission that contains both a file and a message. The message should be set to
this is the message
. The file should be calledhello.txt
and contain a single line of text:hello
. -
Delete the cassettes you wish to regenerate or just delete the entire directory by running:
rm -r tests/functional/cassettes
-
Regenerate cassettes by running:
make test-functional
Note: One of the functional tests deletes a source, so you may need to add it back in between test runs where you are generating new cassettes.
- Update versions:
./update_version.sh $new_version_number
and add a new entry in the changelog. - Commit the changes with commit message
securedrop-client $new_version_number
and make a PR. - 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).
- Once your PR is approved, you can add a tag:
git tag -a $new_version_number
. - Perform the release signing ceremony on the tag. Push the tag.
- The signer should create the source tarball via
python3 setup.py sdist
. - Add a detached signature (with the release key) for the source tarball.
- Submit the source tarball and signature via PR into this repository along with the debian changelog addition. This tarball and changelog will be used by the package builder.
To use pdb
, add these lines:
from PyQt5.QtCore import pyqtRemoveInputHook; pyqtRemoveInputHook()
import pdb; pdb.set_trace()
Then you can use pdb
commands as normal.
Logs can be found in the {sdc-home}/logs
. If you are debugging a version of this application installed from a deb package in Qubes, you can debug issues by looking at the log file in ~/.securedrop_client/logs/client.log
. You can also add additional log lines in the running code in
/opt/venvs/securedrop-client/lib/python3.7/site-packages/securedrop_client/
.