Skip to main content

Python client API to access SecureDrop Journalist REST API

Project description

Python SDK for SecureDrop


This SDK provides a convenient Python interface to the SecureDrop Journalist Interface API. The development of the SDK was primarily motivated by the creation of the SecureDrop Workstation based on Qubes OS.

The SDK is currently used by the SecureDrop Client that is a component of the SecureDrop Workstation. When used in Qubes OS, the SDK uses the securedrop-proxy service, as the VM which runs the client does not have network access by design.

IMPORTANT: This project is still under active development. We do not recommend using it in any production context.


Quick Start

virtualenv --python=python3 .venv
source .venv/bin/activate
pip install --require-hashes -r dev-requirements.txt
make test

We cover all the API calls supported by the SecureDrop Journalist Interface API.


The tests are located in the tests directory. This project uses vcrpy to record and then reply the API calls so that developers will have repeatable results so that they may work offline. vcrpy stores YAML recordings of the API calls in the data directory.

To run all the test cases, use the following command.

make test

To run a single test, use this following command, replace the test case name at the end.

make test TESTS=tests/

To test against a live development server, you will need to run the SecureDrop developent container from the main SecureDrop repository on your host. This can be done via NUM_SOURCES=5 make -C securedrop dev.

In this repo, comment out the @vcr decorator of the setUp method in and execute which ever tests you want to run. If you want to re-run all tests against the API, remove all the .yml files in the data directory.

Generating test data for APIProxy

To test or to generate new test data file for the APIProxy class in file, you will have to setup QubesOS system.

There should be one VM (let us call it sd-journalist), where we can run latest securedrop server code from the development branch using NUM_SOURCES=5 make -C securedrop dev command. The same VM should also have securedrop-proxy project installed, either from the source by hand or using the latest Debian package from the FPF repository.

Below is an example configuration for proxy /etc/sd-proxy.yaml:

scheme: http
port: 8081
target_vm: sd-svs
dev: False

Then we can create our second developent VM called sd-svs, in which we can checkout/develop the securedrop-sdk project. The required configuration file is at /etc/sd-sdk.conf


We should also add a corresponding entry in /etc/qubes-rpc/policy/securedrop.Proxy file in dom0.

sd-svs sd-journalist allow
@anyvm @anyvm deny

The above mentioned setup can also be created using securedrop-workstation project.

Now, delete any related JSON file under data/ directory, or remove all of them, and then execute make test TEST=tests/ This is command will generate the new data files, which can be used in CI or any other system.

Note: Remember that file download checks don't read actual file path in the APIProxy tests as it requires QubesOS setup. You can manually uncomment those lines to execute them on QubesOS setup.


To make a release, you should:

  1. Create a branch named release/$new_version_number
  2. Update and
  3. Commit the changes.
  4. Create a PR and get the PR reviewed and merged into master.
  5. git tag $new_version_number and push the new tag.
  6. Checkout the new tag locally.
  7. Push the new release source tarball to the PSF's PyPI following this documentation.
  8. If you want to publish the new SDK release to the FPF PyPI mirror, Hop over to the the securedrop-debian-packaging repo and follow the build-a-package instructions to push the package up to our PyPI mirror:


Please read for details on our code of conduct, and the process for submitting pull requests to us.


We use SemVer for versioning. For the versions available, see the tags on this repository.


The Python SecureDrop SDK is licensed in the GPLv3. See LICENSE for more details.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for securedrop-sdk, version 0.0.13
Filename, size File type Python version Upload date Hashes
Filename, size securedrop_sdk-0.0.13-py3-none-any.whl (22.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size securedrop-sdk-0.0.13.tar.gz (24.1 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page