Merge 6bc123503e into fa8e8c6dbb

CHANGELOG.md

@@ -110,7 +110,7 @@ since 0.4.1, and this project adheres to [Semantic Versioning](https://semver.or
 - Removed the python shebang from some files
 
 
-## Dangerzone 0.6.1
+## 0.6.1
 
 ### Added
 
@@ -134,14 +134,14 @@ since 0.4.1, and this project adheres to [Semantic Versioning](https://semver.or
 - Use the newest reimplementation of the PyMuPDF rendering engine (`fitz`) ([issue #700](https://github.com/freedomofpress/dangerzone/issues/700))
 - Development: Build Dangerzone using the latest Wix 3.14 release ([#746](https://github.com/freedomofpress/dangerzone/pull/746)
 
-## Dangerzone 0.6.0
+## 0.6.0
 
 ### Added
 
 - Platform support: Fedora 39 ([issue #606](https://github.com/freedomofpress/dangerzone/issues/606))
 - Add new file formats: epub svg and several image formats (BMP, PNM, BPM, PPM) ([issue #697](https://github.com/freedomofpress/dangerzone/issues/697))
 
-## Fixed
+### Fixed
 
 - Fix mismatched between between original document and converted one ([issue #626](https://github.com/freedomofpress/dangerzone/issues/)). This does not affect the quality of the final document.
 - Capitalize "dangerzone" on the application as well as on the Linux desktop shortcut, thanks to [@sudwhiwdh](https://github.com/sudwhiwdh) [#676](https://github.com/freedomofpress/dangerzone/pull/676)
@@ -163,7 +163,7 @@ since 0.4.1, and this project adheres to [Semantic Versioning](https://semver.or
 - Removed timeouts ([issue #687](https://github.com/freedomofpress/dangerzone/issues/687))
 - Platform support: Drop Ubuntu 23.04 (Lunar Lobster), since it's end-of-life ([issue #705](https://github.com/freedomofpress/dangerzone/issues/705))
 
-## Dangerzone 0.5.1
+## 0.5.1
 
 ### Fixed
 
@@ -185,7 +185,7 @@ since 0.4.1, and this project adheres to [Semantic Versioning](https://semver.or
   officially communicated on the advisory date and is only included here since
   this is the first release since it was announced.
 
-## Dangerzone 0.5.0
+## 0.5.0
 
 ### Added
 
@@ -235,7 +235,7 @@ since 0.4.1, and this project adheres to [Semantic Versioning](https://semver.or
 
 - Do not allow attackers to show error or log messages to Qubes users ([issue #456](https://github.com/freedomofpress/dangerzone/issues/456))
 
-## Dangerzone 0.4.2
+## 0.4.2
 
 ### Added
 
@@ -271,7 +271,7 @@ since 0.4.1, and this project adheres to [Semantic Versioning](https://semver.or
 - Sanitize potentially unsafe characters from strings that are shown in the
   GUI/terminal ([PR #491](https://github.com/freedomofpress/dangerzone/pull/491))
 
-## Dangerzone 0.4.1
+## 0.4.1
 
 ### Added
 
@@ -324,7 +324,7 @@ since 0.4.1, and this project adheres to [Semantic Versioning](https://semver.or
 
 - Bug fix: Do not print debug logs in end-user executables ([issue #316](https://github.com/freedomofpress/dangerzone/issues/316))
 
-## Dangerzone 0.4.0
+## 0.4.0
 
 - Platform support: Re-add Fedora 37 support
 - Platform support: Add Debian Bookworm (12) support ([issue #172](https://github.com/freedomofpress/dangerzone/issues/172))
@@ -342,60 +342,60 @@ since 0.4.1, and this project adheres to [Semantic Versioning](https://semver.or
 - Bug fix: (macOS) quit Dangerzone when main window is closed ([issue #271](https://github.com/freedomofpress/dangerzone/issues/271))
 
 
-## Dangerzone 0.3.2
+## 0.3.2
 - Bug fix: some non-ascii characters like “ would prevent Dangerzone from working  ([issue #144](https://github.com/freedomofpress/dangerzone/issues/144))
 - Bug fix: error where Dangerzone would show "permission denied: '/tmp/input_file'" ([issue #157](https://github.com/freedomofpress/dangerzone/issues/157))
 - Bug fix: remove containers after use, enabling Dangerzone to run after 1000+ converted docs ([issue #197](https://github.com/freedomofpress/dangerzone/pull/197))
 - Security: limit container capabilities, run in container as non-root and limit privilege escalation ([issue #169](https://github.com/freedomofpress/dangerzone/issues/169))
 
 
-## Dangerzone 0.3.1
+## 0.3.1
 
 - Bug fix: Allow converting documents on different mounted filesystems than the container volume
 - Bug fix: In GUI mode, don't always OCR document
 - Bug fix: In macOS, fix "open with" Dangerzone so documents are automatically selected
 - Windows: Change packaging to avoid anti-virus false positives
 
-## Dangerzone 0.3
+## 0.3
 
 - Removes the need for internet access by shipping the Dangerzone container image directly with the software
 - Friendly user experience with a progress bar
 - Support for Macs with M1 chips
 
-## Dangerzone 0.2.1
+## 0.2.1
 
 - Switch from Docker to Podman for Linux
 - Improve CLI colors
 
-## Dangerzone 0.2
+## 0.2
 
 - Command line support and improved terminal output
 - Additional container hardening
 - Fix macOS crash on quit
 - Fix --custom-container CLI argument
 
-## Dangerzone 0.1.5
+## 0.1.5
 
 - Add support for macOS Big Sur
 - Drop support for Ubuntu 19.10
 
-## Dangerzone 0.1.4
+## 0.1.4
 
 - Suppress confusing stderr output, and fix bug when converting specific documents
 - Switch from PyQt5 to PySide2
 - Improve Windows and Mac packaging
 - Add support for Fedora 32
 
-## Dangerzone 0.1.3
+## 0.1.3
 
 - Add support for Ubuntu 20.04 LTS (#79)
 - Prevent crash in macOS if specific PDF viewers are installed (#75)
 
-## Dangerzone 0.1.2 (Linux only)
+## 0.1.2 (Linux only)
 
 - Add support for Ubuntu 18.04 LTS
 
-## Dangerzone 0.1.1
+## 0.1.1
 
 - Fix macOS bug that caused a crash on versions earlier than Catalina
 - Fix macOS app bundle ODF extensions (`.ods .odt`)
@@ -405,6 +405,6 @@ since 0.4.1, and this project adheres to [Semantic Versioning](https://semver.or
 - Allow opening `.docm` files
 - Allow using a custom container for testing
 
-## Dangerzone 0.1
+## 0.1
 
 - First release

Makefile

@@ -66,6 +66,10 @@ build-macos-arm: build-clean
 build-linux: build-clean
 	doit -n 8 fedora_rpm debian_deb
 
+.PHONY: docs
+develop-docs: ## Compile the documentation
+	poetry run sphinx-autobuild docs docs/_build/html
+
 # Makefile self-help borrowed from the securedrop-client project
 # Explaination of the below shell command should it ever break.
 # 1. Set the field separator to ": ##" and any make targets that might appear between : and ##

docs/advisories/2023-12-07.md

@@ -1,4 +1,4 @@
-Security Advisory 2023-12-07
+# Security Advisory 2023-12-07
 
 In Dangerzone, a security vulnerability was detected in the quarantined
 environment where documents are opened. Vulnerabilities like this are expected
@@ -8,7 +8,7 @@ document may be able to breach the security of Dangerzone. We are not aware of
 any container escapes that affect Dangerzone. **To reduce that risk, you are
 strongly advised to update Dangerzone to the latest version**.
 
-# Summary
+## Summary
 
 A security vulnerability in GhostScript (CVE-2023-43115) affects the
 **contained** environment where the document rendering takes place. If one
@@ -18,12 +18,12 @@ Office documents, which means that you cannot avoid a specific extension. Other
 programs that open Office documents, such as LibreOffice, are also affected,
 unless the system has been upgraded in the meantime.
 
-# How does this impact me?
+## How does this impact me?
 
 The expectation is that malicious code will run in a container without Internet
 access, meaning that it won't be able to infect the rest of the system.
 
-# What do I need to do?
+## What do I need to do?
 
 You are **strongly** advised to update your Dangerzone installation to 0.5.1 as
 soon as possible.

docs/advisories/2024-12-24.md

@@ -1,4 +1,4 @@
-Security Advisory 2024-12-24
+# Security Advisory 2024-12-24
 
 In Dangerzone, a security vulnerability was detected in the quarantined
 environment where documents are opened. Vulnerabilities like this are expected
@@ -8,7 +8,7 @@ document may be able to breach the security of Dangerzone. We are not aware of
 any container escapes that affect Dangerzone. **To reduce that risk, you are
 strongly advised to update Dangerzone to the latest version**.
 
-# Summary
+## Summary
 
 A series of vulnerabilities in gst-plugins-base (CVE-2024-47538, CVE-2024-47607
 and CVE-2024-47615) affects the **contained** environment where the document
@@ -20,14 +20,14 @@ look like regular Office documents, which means that you cannot avoid a specific
 extension. Other programs that open Office documents, such as LibreOffice, are
 also affected, unless the system has been upgraded in the meantime.
 
-# How does this impact me?
+## How does this impact me?
 
 The expectation is that malicious code will run in a container without Internet
 access, meaning that it won't be able to infect the rest of the system.
 
 If you are running Dangerzone via the Qubes OS, you are not impacted.
 
-# What do I need to do?
+## What do I need to do?
 
 You are **strongly** advised to update your Dangerzone installation to 0.8.1 as
 soon as possible.

docs/changelog.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/conf.py

@@ -0,0 +1,89 @@
+# -*- coding: utf-8 -*-
+#
+# Dangerzone documentation build configuration file.
+
+import sphinx_rtd_theme
+import os
+
+extensions = ["sphinx_rtd_theme", "myst_parser"]
+
+myst_enable_extensions = [
+    "colon_fence",
+]
+
+myst_enable_checkboxes = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+source_suffix = {".md": "markdown"}
+master_doc = "index"
+project = "Dangerzone"
+copyright = "2025, Freedom of the Press Foundation"
+author = "Dangerzone Team and Contributors"
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ["_build"]
+
+pygments_style = "sphinx"
+
+
+html_theme = "sphinx_rtd_theme"
+
+html_context = {
+    "display_github": True,
+    "github_user": "freedomofpress",
+    "github_repo": "dangerzone",
+    "github_version": "main",
+    "conf_py_path": "/docs/",
+    "source_suffix": source_suffix,
+}
+
+html_theme_options = {
+    "style_external_links": True,
+    "flyout_display": "hidden",
+    "version_selector": True,
+    # Toc options
+    "collapse_navigation": True,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+    "includehidden": True,
+    "titles_only": False,
+}
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "Dangerzonedoc"
+
+man_pages = [(master_doc, "dangerzone", "Dangerzone Documentation", [author], 1)]
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (
+        master_doc,
+        "Dangerzone",
+        "Dangerzone Documentation",
+        author,
+        "Dangerzone",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
+]
+
+linkcheck_retries = 3
+linkcheck_workers = 32
+
+linkcheck_ignore = [
+    r"http://127\.0\.0\.1(:\d+)?/?",
+    r"http://localhost(:\d+)?/?",
+]

docs/developer/build.md

@@ -4,13 +4,8 @@
 
 Install dependencies:
 
-<table>
+:::{admonition} Read this section if you are on Ubuntu 22.04 (Jammy).</i></summary>
-  <tr>
+:collapsible: closed
-      <td>
-<details>
-  <summary><i>:memo: Expand this section if you are on Ubuntu 22.04 (Jammy).</i></summary>
-  </br>
-
 The `conmon` version that Podman uses and Ubuntu Jammy ships, has a bug
 that gets triggered by Dangerzone
 (more details in https://github.com/freedomofpress/dangerzone/issues/685).
@@ -27,11 +22,7 @@ Install dependencies:
 following [instructions](https://github.com/freedomofpress/maint-dangerzone-conmon/tree/ubuntu/jammy/fpf).
 Alternatively, you can install a `conmon` version higher than `v2.0.25` from
 any repo you prefer.
-
+:::
-</details>
-    </td>
-  </tr>
-</table>
 
 
 ```sh
@@ -156,9 +147,9 @@ poetry shell
 ./dev_scripts/dangerzone
 ```
 
-> [!NOTE]
+:::{note}
-> Prefer running the following command in a Fedora development environment,
+Prefer running the following command in a Fedora development environment, created by `./dev_script/env.py`. You can read more about how to do that [here](./environments).
-> created by `./dev_script/env.py`.
+:::
 
 Create a .rpm:
 
@@ -169,11 +160,12 @@ Create a .rpm:
 ## Qubes OS
 
 
-> :warning: Native Qubes support is in beta stage, so the instructions below
+:::{warning}
-> require switching between qubes, and are subject to change.
+Native Qubes support is in beta stage, so the instructions below require
->
+switching between qubes, and are subject to change. If you want to build
-> If you want to build Dangerzone on Qubes and use containers instead of disposable
+Dangerzone on Qubes and use containers instead of disposable qubes, please
-> qubes, please follow the instructions of Fedora / Debian instead.
+follow the instructions of Fedora / Debian instead.
+:::
 
 
 ### Initial Setup
@@ -293,9 +285,11 @@ QUBES_CONVERSION=1 poetry run ./dev_scripts/dangerzone
 
 And when creating a `.rpm` you'll need to enable the `--qubes` flag.
 
-> [!NOTE]
+:::{note}
-> Prefer running the following command in a Fedora development environment,
+Prefer running the following command in a Fedora development environment,
-> created by `./dev_script/env.py`.
+created by `./dev_script/env.py`.
+You can read more about how to do that [here](./environments).
+:::
 
 ```sh
 ./install/linux/build-rpm.py --qubes
@@ -442,16 +436,16 @@ Install the WiX UI extension. You may need to open a new terminal in order to us
 wix extension add --global WixToolset.UI.wixext/5.0.2
 ```
 
-> [!IMPORTANT]
+:::{important}
-> To avoid compatibility issues, ensure the WiX UI extension version matches the version of the WiX Toolset.
+To avoid compatibility issues, ensure the WiX UI extension version matches the version of the WiX Toolset.
->
+Run `wix --version` to check the version of WiX Toolset you have installed and replace `5.x.y` with the full version number without the Git revision.
-> Run `wix --version` to check the version of WiX Toolset you have installed and replace `5.x.y` with the full version number without the Git revision.
+:::
 
 ### If you want to sign binaries with Authenticode
 
 You'll need a code signing certificate.
 
-## To make a .exe
+### To make a .exe
 
 Open a command prompt, cd into the dangerzone directory, and run:
 

docs/developer/gvisor.md

@@ -1,10 +1,5 @@
 # gVisor integration
 
-> [!NOTE]
-> **Update on 2025-01-13:** There is no longer a copied container image under
-> `/home/dangerzone/dangerzone-image/rootfs`. We now reuse the same container
-> image both for the inner and outer container. See
-> [#1048](https://github.com/freedomofpress/dangerzone/issues/1048).
 
 Dangerzone has relied on the container runtime available in each supported
 operating system (Docker Desktop on Windows / macOS, Podman on Linux) to isolate
@@ -27,6 +22,13 @@ as **untrusted**, and the computation and output of the second container as
 trusted. For this reason, and because we are about to remove the need for the
 second container, our integration plan will focus on the first container.
 
+:::{versionchanged} 0.9.0
+There is no longer a copied container image under
+`/home/dangerzone/dangerzone-image/rootfs`. We now reuse the same container
+image both for the inner and outer container. See
+[#1048](https://github.com/freedomofpress/dangerzone/issues/1048).
+:::
+
 ## Design overview
 
 Our integration goals are to:

docs/developer/reproducibility.md

@@ -2,7 +2,7 @@
 
 We want to improve the transparency and auditability of our build artifacts, and
 a way to achieve this is via reproducible builds. For a broader understanding of
-what reproducible builds entail, check out https://reproducible-builds.org/.
+what reproducible builds entail, check out [reproducible-builds.org](https://reproducible-builds.org)
 
 Our build artifacts consist of:
 * Container images (`amd64` and `arm64` architectures)

docs/index.md

@@ -0,0 +1,119 @@
+# Dangerzone
+
+Take potentially dangerous PDFs, office documents, or images and convert them to a safe PDF.
+
+
+| ![Settings](./assets/screenshot1.png) | ![Converting](./assets/screenshot2.png)
+|--|--|
+
+Dangerzone works like this: You give it a document that you don't know if you can trust (for example, an email attachment). Inside of a sandbox, Dangerzone converts the document to a PDF (if it isn't already one), and then converts the PDF into raw pixel data: a huge list of RGB color values for each page. Then, outside of the sandbox, Dangerzone takes this pixel data and converts it back into a PDF.
+
+_Read more about Dangerzone on the [official site](https://dangerzone.rocks/about/)._
+
+```{toctree}
+:caption: Getting started
+:hidden:
+
+install
+changelog
+security
+```
+
+```{toctree}
+:caption: Developper docs
+:hidden:
+
+developer/build
+developer/environments
+developer/testing
+
+```
+
+```{toctree}
+:caption: Design docs
+:hidden:
+developer/gvisor
+developer/reproducibility
+developer/updates
+````
+
+
+```{toctree}
+:caption: Release
+:hidden:
+release/index
+release/qa
+
+```
+
+## Getting started
+
+Follow the instructions for each platform:
+
+* [macOS](install.md#macos)
+* [Windows](https://github.com/freedomofpress/dangerzone/blob/v0.8.1//INSTALL.md#windows)
+* [Ubuntu Linux](https://github.com/freedomofpress/dangerzone/blob/v0.8.1/INSTALL.md#ubuntu-debian)
+* [Debian Linux](https://github.com/freedomofpress/dangerzone/blob/v0.8.1/INSTALL.md#ubuntu-debian)
+* [Fedora Linux](https://github.com/freedomofpress/dangerzone/blob/v0.8.1/INSTALL.md#fedora)
+* [Qubes OS (beta)](https://github.com/freedomofpress/dangerzone/blob/v0.8.0/INSTALL.md#qubes-os)
+* [Tails](https://github.com/freedomofpress/dangerzone/blob/v0.8.1/INSTALL.md#tails)
+
+## Some features
+
+- Sandboxes don't have network access, so if a malicious document can compromise one, it can't phone home
+- Sandboxes use [gVisor](https://gvisor.dev/), an application kernel written in Go, that implements a substantial portion of the Linux system call interface.
+- Dangerzone can optionally OCR the safe PDFs it creates, so it will have a text layer again
+- Dangerzone compresses the safe PDF to reduce file size
+- After converting, Dangerzone lets you open the safe PDF in the PDF viewer of your choice, which allows you to open PDFs and office docs in Dangerzone by default so you never accidentally open a dangerous document
+
+Dangerzone can convert these types of document into safe PDFs:
+
+- PDF (`.pdf`)
+- Microsoft Word (`.docx`, `.doc`)
+- Microsoft Excel (`.xlsx`, `.xls`)
+- Microsoft PowerPoint (`.pptx`, `.ppt`)
+- ODF Text (`.odt`)
+- ODF Spreadsheet (`.ods`)
+- ODF Presentation (`.odp`)
+- ODF Graphics (`.odg`)
+- Hancom HWP (Hangul Word Processor) (`.hwp`, `.hwpx`)
+  * Not supported on
+    [Qubes OS](https://github.com/freedomofpress/dangerzone/issues/494)
+- EPUB (`.epub`)
+- Jpeg (`.jpg`, `.jpeg`)
+- GIF (`.gif`)
+- PNG (`.png`)
+- SVG (`.svg`)
+- other image formats (`.bmp`, `.pnm`, `.pbm`, `.ppm`)
+
+Dangerzone was inspired by [Qubes trusted PDF](https://blog.invisiblethings.org/2013/02/21/converting-untrusted-pdfs-into-trusted.html), but it works in non-Qubes operating systems. It uses containers as sandboxes instead of virtual machines (using Docker for macOS and Windows, and [podman](https://podman.io/) on Linux).
+
+Set up a development environment by following [these instructions](build.md).
+
+
+## License and Copyright
+
+Licensed under the AGPLv3: [https://opensource.org/licenses/agpl-3.0](https://opensource.org/licenses/agpl-3.0)
+
+Copyright (c) 2022-2024 Freedom of the Press Foundation and Dangerzone contributors
+Copyright (c) 2020-2021 First Look Media
+
+## See also
+
+* [GIJN Toolbox: Cutting-Edge — and Free — Online Investigative Tools You Can Try Right Now](https://gijn.org/stories/cutting-edge-free-online-investigative-tools/)
+* [When security matters: working with Qubes OS at the Guardian](https://www.theguardian.com/info/2024/apr/04/when-security-matters-working-with-qubes-os-at-the-guardian)
+
+## FAQ
+
+### Has Dangerzone received a security audit?
+
+Yes, Dangerzone received its [first security audit](https://freedom.press/news/dangerzone-receives-favorable-audit/) by [Include Security](https://includesecurity.com/) in December 2023. The audit was generally favorable, as it didn't identify any high-risk findings, except for 3 low-risk and 7 informational findings.
+
+### I'm experiencing an issue while using Dangerzone.
+
+Dangerzone gets updates to improve its features _and_ to fix problems. So, updating may be the simplest path to resolving the issue which brought you here. Here is how to update:
+
+1. Check which version of Dangerzone you are currently using: run Dangerzone, then look for a series of numbers to the right of the logo within the app. The format of the numbers will look similar to `0.4.1`
+2. Now find the latest available version of Dangerzone: go to the [download page](https://dangerzone.rocks/#downloads). Look for the version number displayed. The number will be using the same format as in Step 1.
+3. Is the version on the Dangerzone download page higher than the version of your installed app? Go ahead and update.
+

docs/install.md

@@ -1,23 +1,39 @@
+# Install Dangerzone
+
 ## MacOS
 
 - Download [Dangerzone 0.8.1 for Mac (Apple Silicon CPU)](https://github.com/freedomofpress/dangerzone/releases/download/v0.8.1/Dangerzone-0.8.1-arm64.dmg)
 - Download [Dangerzone 0.8.1 for Mac (Intel CPU)](https://github.com/freedomofpress/dangerzone/releases/download/v0.8.1/Dangerzone-0.8.1-i686.dmg)
 
-You can also install Dangerzone for Mac using [Homebrew](https://brew.sh/): `brew install --cask dangerzone`
+You can also install Dangerzone for Mac using [Homebrew](https://brew.sh/):
 
-> **Note**: you will also need to install [Docker Desktop](https://www.docker.com/products/docker-desktop/).
+```bash
-> This program needs to run alongside Dangerzone at all times, since it is what allows Dangerzone to
+brew install --cask dangerzone
-> create the secure environment.
+```
+
+
+:::{note}
+
+You will also need to install [Docker Desktop](https://www.docker.com/products/docker-desktop/).
+This program needs to run alongside Dangerzone at all times, since it is what allows Dangerzone to
+create the secure environment.
+
+:::
 
 ## Windows
 
 - Download [Dangerzone 0.8.1 for Windows](https://github.com/freedomofpress/dangerzone/releases/download/v0.8.1/Dangerzone-0.8.1.msi)
 
-> **Note**: you will also need to install [Docker Desktop](https://www.docker.com/products/docker-desktop/).
+:::{note}
-> This program needs to run alongside Dangerzone at all times, since it is what allows Dangerzone to
+
-> create the secure environment.
+You will also need to install [Docker Desktop](https://www.docker.com/products/docker-desktop/).
+This program needs to run alongside Dangerzone at all times, since it is what allows Dangerzone to
+create the secure environment.
+
+:::
 
 ## Linux
+
 On Linux, Dangerzone uses [Podman](https://podman.io/) instead of Docker Desktop for creating
 an isolated environment. It will be installed automatically when installing Dangerzone.
 
@@ -36,25 +52,13 @@ Dangerzone is available for:
 
 ### Ubuntu, Debian
 
-<table>
+:::{admonition} Backport notice for Ubuntu 22.04 (Jammy) users regarding the `conmon` package
-  <tr>
+:collapsible: closed
-    <td>
-<details>
-  <summary><i>:information_source: Backport notice for Ubuntu 22.04 (Jammy) users regarding the <code>conmon</code> package</i></summary>
-  </br>
 
-  The `conmon` version that Podman uses and Ubuntu Jammy ships, has a bug
+The `conmon` version that Podman uses and Ubuntu Jammy ships, has a bug that gets triggered by Dangerzone (more details in https://github.com/freedomofpress/dangerzone/issues/685). To fix this, we provide our own `conmon` package through our APT repo, which was built with the following [instructions](https://github.com/freedomofpress/maint-dangerzone-conmon/tree/ubuntu/jammy/fpf).
-  that gets triggered by Dangerzone
+
-  (more details in https://github.com/freedomofpress/dangerzone/issues/685).
+This package is essentially a backport of the `conmon` package [provided](https://packages.debian.org/source/oldstable/conmon) by Debian Bullseye.
-  To fix this, we provide our own `conmon` package through our APT repo, which
+:::
-  was built with the following [instructions](https://github.com/freedomofpress/maint-dangerzone-conmon/tree/ubuntu/jammy/fpf).
-  This package is essentially a backport of the `conmon` package
-  [provided](https://packages.debian.org/source/oldstable/conmon) by Debian
-  Bullseye.
-</details>
-    </td>
-  </tr>
-</table>
 
 First, retrieve the PGP keys.
 
@@ -98,12 +102,8 @@ sudo apt update
 sudo apt install -y dangerzone
 ```
 
-<table>
+:::{admonition} Security notice on third-party Debian repos</i></summary>
-  <tr>
+:collapsible: closed
-    <td>
-<details>
-  <summary><i>:memo: Expand this section for a security notice on third-party Debian repos</i></summary>
-  </br>
 
 This section follows the official instructions on configuring [third-party
 Debian repos](https://wiki.debian.org/DebianRepository/UseThirdParty).
@@ -115,10 +115,7 @@ sudo apt install -y dangerzone
 Aside from these protections, the user needs to be aware that Debian packages
 run as `root` during the installation phase, so they need to place some trust
 on our signed Debian packages. This holds for any third-party Debian repo.
-</details>
+:::
-    </td>
-  </tr>
-</table>
 
 ### Fedora
 
@@ -132,12 +129,8 @@ sudo dnf install dangerzone
 
 ##### Verifying Dangerzone GPG key
 
-<table>
+:::{admonition} Importing GPG key 0x22604281: ... Is this ok [y/N]:
-  <tr>
+:collapsible: closed
-    <td>
-<details>
-<summary>Importing GPG key 0x22604281: ... Is this ok [y/N]:</summary>
-</br>
 
 After some minutes of running the above command (depending on your internet speed) you'll be asked to confirm the fingerprint of our signing key. This is to make sure that in the case our servers are compromised your computer stays safe. It should look like this:
 
@@ -151,34 +144,32 @@ Importing GPG key 0x22604281:
  From       : /etc/pki/rpm-gpg/RPM-GPG-dangerzone.pub
 Is this ok [y/N]:
 ```
+:::
 
-> **Note**: If it does not show this fingerprint confirmation or the fingerprint does not match, it is possible that our servers were compromised. Be distrustful and reach out to us.
+:::{note}
+If it does not show this fingerprint confirmation or the fingerprint does not match, it is possible that our servers were compromised. Be distrustful and reach out to us.
+:::
 
 The `Fingerprint` should be `DE28 AB24 1FA4 8260 FAC9 B8BA A7C9 B385 2260 4281`. For extra security, you should confirm it matches the one at the bottom of our website ([dangerzone.rocks](https://dangerzone.rocks)) and our [Mastodon account](https://fosstodon.org/@dangerzone) bio.
 
 After confirming that it matches, type `y` (for yes) and the installation should proceed.
 
-</details>
-    </td>
-  </tr>
-</table>
-
 ### Qubes OS
 
-> [!WARNING]
+:::{warning}
-> This section is for the beta version of native Qubes support. If you
+This section is for the beta version of native Qubes support. If you
-> want to try out the stable Dangerzone version (which uses containers instead
+want to try out the stable Dangerzone version (which uses containers instead
-> of virtual machines for isolation), please follow the Fedora or Debian
+of virtual machines for isolation), please follow the Fedora or Debian
-> instructions and adapt them as needed.
+instructions and adapt them as needed.
->
+**If you followed these instructions before October 25, 2023, please read [this security advisory](docs/advisories/2023-10-25.md).**
-> **If you followed these instructions before October 25, 2023, please read [this security advisory](docs/advisories/2023-10-25.md).**
+This notice will be removed with the 1.0.0 release of Dangerzone.
-> This notice will be removed with the 1.0.0 release of Dangerzone.
+:::
 
-
+:::{important}
-> [!IMPORTANT]
+This section will install Dangerzone in your **default template**
-> This section will install Dangerzone in your **default template**
+(`fedora-40` as of writing this). If you want to install it in a different
-> (`fedora-40` as of writing this). If you want to install it in a different
+one, make sure to replace `fedora-40` with the template of your choice.
-> one, make sure to replace `fedora-40` with the template of your choice.
+:::
 
 The following steps must be completed once. Make sure you run them in the
 specified qubes.
@@ -238,7 +229,7 @@ for Tails users.
 
 ## Build from source
 
-If you'd like to build from source, follow the [build instructions](BUILD.md).
+If you'd like to build from source, follow the [build instructions](build.md).
 
 ## Verifying PGP signatures
 

docs/release/index.md

@@ -75,24 +75,25 @@ Once we are confident that the release will be out shortly, and doesn't need any
   ```
   **Note**: release candidates are suffixed by `-rcX`.
 
-> [!IMPORTANT]
+:::{important}
-> Because we don't have [reproducible builds](https://github.com/freedomofpress/dangerzone/issues/188)
+Because we don't have [reproducible builds](https://github.com/freedomofpress/dangerzone/issues/188)
-> yet, building the Dangerzone container image in various platforms would lead
+yet, building the Dangerzone container image in various platforms would lead
-> to different container image IDs / hashes, due to different timestamps. To
+to different container image IDs / hashes, due to different timestamps. To
-> avoid this issue, we should build the final container image for x86_64
+avoid this issue, we should build the final container image for x86_64
-> architectures on **one** platform, and then copy it to the rest of the
+architectures on **one** platform, and then copy it to the rest of the
-> platforms, before creating our .deb / .rpm / .msi / app bundles.
+platforms, before creating our .deb / .rpm / .msi / app bundles.
+:::
 
 ### macOS Release
 
-> [!TIP]
+:::{tip}
-> You can automate these steps from your macOS terminal app with:
+You can automate these steps from your macOS terminal app with:
->
+```
-> ```
+export APPLE_ID=<email>
-> export APPLE_ID=<email>
+make build-macos-intel  # for Intel macOS
-> make build-macos-intel  # for Intel macOS
+make build-macos-arm    # for Apple Silicon macOS
-> make build-macos-arm    # for Apple Silicon macOS
+```
-> ```
+:::
 
 The following needs to happen for both Silicon and Intel chipsets.
 
@@ -274,9 +275,10 @@ repo, by sending a PR. Follow the instructions in that repo on how to do so.
 
 #### Fedora
 
-> **NOTE**: This procedure will have to be done for every supported Fedora version.
+:::{note}
->
+This procedure will have to be done for every supported Fedora version.
-> In this section, we'll use Fedora 41 as an example.
+In this section, we'll use Fedora 41 as an example.
+:::
 
 Create a Fedora development environment. You can [follow the
 instructions in our build section](https://github.com/freedomofpress/dangerzone/blob/main/BUILD.md#fedora),

docs/security.md

@@ -0,0 +1,11 @@
+# Security advisories
+
+Dangerzone being a privacy-focused tool, it is subject to security advisories. To be updated about future ones, you can follow [the news from the project blog](https://dangerzone.rocks/news/).
+
+```{toctree}
+:maxdepth: 1
+
+advisories/2024-12-24.md
+advisories/2023-12-07.md
+advisories/2023-10-25.md
+```

pyproject.toml

@@ -58,6 +58,13 @@ strip-ansi = "*"
 pytest-subprocess = "^1.5.2"
 pytest-rerunfailures = "^14.0"
 
+# Dependencies required for the documentation
+[tool.poetry.group.docs.dependencies]
+sphinx = "^7.4"
+sphinx-autobuild = "^2024.10.3"
+sphinx-rtd-theme = "^3.0.2"
+myst-parser = "^3.0.0"
+
 [tool.poetry.group.debian.dependencies]
 pymupdf = "^1.24.11"