SecureDrop Workstation Development

This project’s development requires different workflows for working on provisioning components and working on submission-handling scripts.

For developing salt states and other provisioning components, work is done in a development VM and changes are made to individual state and top files there. In the dom0 copy of this project:

make clone is used to build a new version of the RPM and copy the contents of your working directory (including the RPM) from your development VM to dom0
make <vm-name> can be used to rebuild an individual VM
make dev installs the latest locally present RPM and performs the full installation.

Note that make clone requires two environment variables to be set: SECUREDROP_DEV_VM must be set to the name of the VM where you’ve been working on the code, the SECUREDROP_DEV_DIR should be set to the directory where the code is checked out on your development VM.

For work on components such as the SecureDrop Client, see their individual readmes in the securedrop-client repository:

Testing

Tests should cover two broad domains. First, we should assert that all the expected VMs exist and are configured as we expect (with the correct NetVM, with the expected files in the correct place). Second, we should end-to-end test the document handling scripts, asserting that files present in the sd-proxy VM correctly make their way to the sd-app AppVM, and are opened correctly in disposable VMs.

Configuration Tests

These tests assert that expected scripts and configuration files are in the correct places across the VMs. These tests can be found in the tests/ directory. They can be run from the project’s root directory on dom0 with:

make test

Note that since tests confirm the states of provisioned VMs, they should be run after all the VMs have been built with make dev.

Individual tests can be run with make <test-name>, where test-name is one of test-base, test-app, test-proxy, test-whonix or test-gpg.

Be aware that running tests will power down running SecureDrop VMs, and may result in data loss. Only run tests in a development / testing environment.

Automatic updates

Double-clicking the “SecureDrop” desktop icon will launch a preflight updater that applies any necessary updates to VMs, and may prompt a reboot. In a development environment, this will install the latest nightly packages (unless a package with a higher version number is available on apt-test in main), and the latest RPM published to yum-test.

Manually updating dom0 code

To update code in dom0 manually, e.g., to a specific branch or tag of this repository, use the sd-dev AppVM that was created during the install. For example, to build a specific tag, from your checkout directory, run the following commands (replace <tag> with the tag of the release you are working with):

git fetch --tags
git tag -v <tag>
git checkout <tag>

In dom0:

make clone
make dev

The make clone command will build a new version of the RPM package that contains the provisioning logic in your development VM (e.g., sd-dev) and copy it to dom0.

Building workstation Debian packages

Debian packages for the SecureDrop Workstation components are maintained in a separate repository: https://github.com/freedomofpress/securedrop-client/

Building workstation RPM packages

make build-rpm

The build runs in a container and requires either Docker or Podman to be installed.