lots of documentation added

maltfield · maltfield · commit 1c076f3d5868 · 2020-07-15T11:43:36.000+05:45
diff --git a/docs/attribution.rst b/docs/attribution.rst
@@ -27,3 +27,20 @@ This project would not have been possible without the following tools and servic
  * `QubesOS <https://www.qubes-os.org/>`_
  * `TAILS <https://tails.boum.org/install/index.en.html>`_
  * `Debian <https://www.debian.org/>`_ `GNU <http://www.gnu.org/>`_/`Linux <https://www.kernel.org/>`_
+
+Similar Projects
+----------------
+
+The reader may be interested to investigate the following similar projects:
+
+ * `USB Kill <https://github.com/hephaest0s/usbkill>`_
+ * `Silk Guardian <https://github.com/NateBrune/silk-guardian>`_
+ * `Day Tripper <https://github.com/maltfield/daytripper>`_
+ * `USBGuard <https://usbguard.github.io/>`_
+ * `suicideCrypt <https://github.com/MonolithInd/suicideCrypt>`_
+ * `panic_bcast <https://github.com/qnrq/panic_bcast>`_
+ * `Nuke My LUKS <https://github.com/juliocesarfort/nukemyluks>`_
+ * `luksAddNuke <http://lxer.com/module/newswire/view/103692/index.html>`_
+ * `cryptsetup-nuke-keys <https://gitlab.com/kalilinux/packages/cryptsetup-nuke-keys>`_
+ * `TAILS Memory Erasure <https://tails.boum.org/contribute/design/memory_erasure/>`_
+ * `TEDD (Transparent Emergency Data Destruction) <https://bitbucket.org/ausiv4/tedd/src/default/>`_
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -0,0 +1,6 @@
+.. _changelog:
+
+Changelog
+===========
+
+TODO: include repo's root CHANGELOG file
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -0,0 +1,68 @@
+.. _contributing:
+
+Contributing
+================
+
+Thank you for considering to help with the development of BusKill!
+
+As an open-source project, we depend on the work of volunteers to stay alive, and your time helping to improve our project is very much appreciated :)
+
+.. _wishlist:
+
+Wish List
+---------
+
+Below is a list of items on our TODO list. If you'd like to help us tackle these tasks, please `contact us <https://buskill.in/contact/>`_ as there may be someone already working on a given task that you may be able to collaborate with.
+
+Please be aware that any contributions you make will be made open-source. See :ref:`license` for more info.
+
+Software
+^^^^^^^^
+
+Here's some items on our wish list that you can help contribute to:
+
+#. Translating our app and this documentation to another language
+#. Testing our app on many :ref:`supported_platforms`
+#. Writing new auxillary triggers, such as
+
+   a. A self-destruct trigger for `Veracrypt <https://github.com/BusKill/veracrypt-self-destruct>`_
+   b. A self-destruct trigger for `BitLocker <https://en.wikipedia.org/wiki/BitLocker>`_
+   c. A self-destruct trigger for `FileVault <https://en.wikipedia.org/wiki/FileVault>`_
+
+#. `Fix PyInstaller <https://github.com/pyinstaller/pyinstaller/issues/4972>`_ to support `reproducible builds <https://github.com/BusKill/buskill-app/issues/3>`_ on MacOS and Windows
+
+#. Port BusKill to Android
+
+#. Port BusKill to iOS
+
+#. Update appimagetool to `include squashfs-tools v4.4 <https://github.com/AppImage/AppImageKit/issues/929>`_
+
+#. Create a video extension in sphinx that has a `graceful fallback on PDF <https://github.com/brechtm/rinohtype/issues/172>`_ and `printing to paper <https://stackoverflow.com/questions/62682412/video-fall-back-when-printing-to-paper-with-read-the-docs>`_
+
+#. Create a `spreadsheet extension in sphinx <https://stackoverflow.com/questions/62682095/how-to-add-a-spreadsheet-in-read-the-docs>`_ that converts LibreOffice Calc documents (with formulas in them) into csv format (using ``localc``) at build-time for creating `BOM <https://en.wikipedia.org/wiki/Bill_of_materials>`_ tables in reST documents.
+
+Hardware
+^^^^^^^^
+
+#. Open-source USB magnetic disconnect (`.stl <https://en.wikipedia.org/wiki/3D_printing>`_ file, `BOM <https://en.wikipedia.org/wiki/Bill_of_materials>`_ w/ link to USB components/magnets/`pogo <https://en.wikipedia.org/wiki/Pogo_pin>`_ connector, build instructions, etc)
+#. A simple-as-possible open-source USB peripheral that can send `USB hotplug events <http://libusb.sourceforge.net/api-1.0/group__libusb__hotplug.html#ga00e0c69ddf1fb1b6774dc918192e8dc7>`_ but doesn't have the ability to send data to the machine, including a low-tech guide to `verify the integrity <https://www.bunniestudios.com/blog/?p=5706>`_ of the device.
+
+
+Donate
+--------
+
+Running the BusKill project has many fees, including
+
+#. Server & domain infrastructure fees
+#. Code Signing Keys fees
+#. Developer account fees (ie: Apple)
+
+If you have more money than free time, you can also help BusKill by making a donation. We accept Bitcoin and Monero.
+
+::
+
+  BTC 1DXyJpmu2KQMw2v4QJVzzjZo6f87BBndu6
+
+  XMR 4B5ra5N1SN4d7BqDtkxAE5G5kGNz5mA5oCob41RzzoduM1uPAcr7QmNLzXtci5HvtkNXC7SowkxMjUUCXF2hm57MMS4jwkx
+
+Donations of any amount are **greatly** appreciated. Thank you!
diff --git a/docs/index.rst b/docs/index.rst
@@ -31,6 +31,8 @@ For information on using the BusKil App, see :ref:`software_usr`.
    software_dev/index
    security/index
    support
+   contributing
+   changelog
    license
    attribution
 
diff --git a/docs/security/index.rst b/docs/security/index.rst
@@ -8,6 +8,8 @@ This section will detail security-related aspects of the BusKill project.
 .. toctree::
    :maxdepth: 3
 
+   infrastructure
    pgpkeys
    tradeoffs
+   reporting
 
diff --git a/docs/security/infrastructure.rst b/docs/security/infrastructure.rst
@@ -0,0 +1,18 @@
+.. _security_infrastructure:
+
+Don't trust the infrastructure
+==============================
+
+This website is hosted on `GitHub Pages <https://pages.github.com/>`_. Therefore, it is largely outside of our control.
+
+We don’t consider this a problem, however, since we explicitly distrust the infrastructure. For this reason, we don’t think that anyone should place undue trust in the live version of this site on the Web.
+
+Instead, if you want to obtain your own, trustworthy copy of this website in a secure way, you should clone our `buskill-app repo <https://github.com/buskill/buskill-app>`_, verify the PGP signatures on the commits and/or tags, then either :ref:`render the site on your local machine <documentation_building>` or simply read the source.
+
+We intentionally write our documentation in ReStructuredText so it's readable as plain text for this very reason. We’ve gone to special effort to set all of this up so that no one has to trust the infrastructure and so that the contents of this website are maximally available and accessible.
+
+We believe the best solution is not to attempt to make the infrastructure trustworthy, but instead to concentrate on solutions that obviate the need to do so. We believe that many attempts to make the infrastructure appear trustworthy actually provide only the illusion of security and are ultimately a disservice to real users. Since we don’t want to encourage or endorse this, we make our distrust of the infrastructure explicit.
+
+.. note::
+
+  This was adapted from QubesOS's `distrust the infrastructure <https://www.qubes-os.org/faq/#what-does-it-mean-to-distrust-the-infrastructure>`_ philosophy.
diff --git a/docs/security/pgpkeys.rst b/docs/security/pgpkeys.rst
@@ -10,13 +10,13 @@ For more info, see:
 
 .. warning::
 
-  This documentation is hosted on GitHub Pages, and `you should not trust <https://www.qubes-os.org/faq/#should-i-trust-this-website>`_ its contents.
+  This documentation is hosted on GitHub Pages, and :ref:`you should not trust <security_infrastructure>` its contents.
 
   A wise user that's adding our keys to their keyring for the first-time would cross-validate the PGP fingerprint listed on this website against other sources, such as:
    * The `official BusKill project website <https://www.buskill.in/>`_
    * The `official BusKill keybase account <https://keybase.io/buskill/>`_
    * The `official BusKill mastodon account <https://mastodon.social/@buskillin>`_
-   * The `KEYS file <https://github.com/BusKill/buskill-app/blob/master/KEYS.md>`_ at the root of our GitHub repo
+   * The `KEYS file <keys_file_>`_ at the root of our GitHub repo
    * A popular `gpg keyserver <https://keys.openpgp.org/search?q=releases%40buskill.in>`_
    * Your `friends' keyrings <https://en.wikipedia.org/wiki/Web_of_trust>`_
 
@@ -47,11 +47,14 @@ If you're a developer and would like to include your pgp key in our org's ``KEYS
   gpg --list-sigs <your fingerprint>
   gpg --export --armor <your fingerprint>
 
-And then append the output to the `KEYS file <https://github.com/BusKill/buskill-app/blob/master/KEYS>`_.
+And then append the output to the `KEYS file <keys_file_>`_.
 
 KEYS
 ----
 
-Our repo's `KEYS file <https://github.com/BusKill/buskill-app/blob/master/KEYS>`_ is shown below
+Our repo's `KEYS file <keys_file_>`_ is shown below
 
 .. literalinclude:: ../../KEYS
+
+.. _keys_file: https://github.com/BusKill/buskill-app/blob/master/KEYS
+
diff --git a/docs/security/reporting.rst b/docs/security/reporting.rst
@@ -0,0 +1,20 @@
+.. _securityreports:
+
+Security-Related Bugs
+=====================
+
+Reporting Security Bugs
+-----------------------
+
+If you discover a security-related bug that affects the BusKill project, please `contact us <https://www.buskill.in/contact/>`_ ASAP.
+
+For privacy, please don't forget to encrypt your mail and to include your public key so that we can encrypt our response.
+
+.. note::
+
+  Please don't encrypt emails to our release PGP keys. Our email-specific PGP keys are available at the above link.
+
+Previous security incidents
+---------------------------
+
+For a list of previous security issues and their resolutions, see our :ref:`changelog`
diff --git a/docs/security/tradeoffs.rst b/docs/security/tradeoffs.rst
@@ -5,7 +5,7 @@ Trade-offs
 
 The BusKill app was created for convenience, providing the user with an easy-to-use method of arming, disarming, and configuring BusKill with an intuitive GUI that "just works" on Linux, Windows, and MacOS.
 
-Convenience is a trade-off that comes at a cost of reduced security. Using this app requires your computer to not only run hundreds of lines of our code, but also thousands of lines of code from dependant libraries.
+Convenience is a trade-off that comes at a cost of reduced security. Using the BusKill app requires your computer to not only run hundreds of lines of our code, but also thousands of lines of code from dependant libraries.
 
 The most secure way to run BusKill is using a simple udev config as described here:
 
diff --git a/docs/software_dev/autodoc.rst b/docs/software_dev/autodoc.rst
@@ -1,8 +1,13 @@
 .. _autodoc:
 
-Source Code
+buskill-app
 ===========
 
+This section documents the main BusKill app
+
+Source Code
+-----------
+
 This section documents the source code files and their classes/function using ``autodoc``.
 
 You can find the sourcecode that this document refers to in the ``src/`` directory on our `github-app repo on github.com <https://github.com/BusKill/buskill-app/tree/master/src>`_
diff --git a/docs/software_dev/contributing.rst b/docs/software_dev/contributing.rst
diff --git a/docs/software_dev/documentation.rst b/docs/software_dev/documentation.rst
@@ -0,0 +1,58 @@
+.. _documentation:
+
+Documentation
+=============
+
+This section documents how to update and build the documentation
+
+Continuous Documentation
+------------------------
+
+The BusKill project treats documentation-as-code. It is versioned, managed with ``git``, and automatically built and released with our `CI/CD GitHub Actions workflows <https://github.com/BusKill/buskill-app/blob/master/.github/workflows/docs_pages_workflow.yml>`_.
+
+Our documentation is written in `reStructuredText (reST) <https://en.wikipedia.org/wiki/ReStructuredText>`_ and built using `sphinx <https://www.sphinx-doc.org/en/master/>`_ with the `Read The Docs theme <https://github.com/readthedocs/sphinx_rtd_theme>`_. This has the following benefits:
+
+#. reST is human-readable plaintext. It plays nice with a VCS (like ``git``).
+
+   a. Plaintext is easier to review for PRs, making malicious PRs easier to detect.
+   b. It's not necessary to build in order to read. The cryptographically-signed git commit sources can be read directly.
+   c. Our documentation gets versioned exactly matching our code's release branches.
+
+#. It's trivial for Sphinx to export to `multiple formats <https://www.sphinx-doc.org/en/master/usage/builders/index.html>`_, such as HTML, PDF, EPUB, etc.
+
+#. reST is much more powerful than other human-readable markups.
+
+   a. We can define our own `extensions using python <https://www.sphinx-doc.org/en/master/development/tutorials/helloworld.html>`_ to do complex logic like `converting LibreOffice spreadsheets with calculations into tables <https://stackoverflow.com/questions/62682095/how-to-add-a-spreadsheet-in-read-the-docs>`_
+
+#. Sphinx has built-in support for documenting python sourcecode using `autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
+
+Updating
+--------
+
+If you'd like to update this documentation, you can `fork <https://docs.github.com/en/github/getting-started-with-github/fork-a-repo>`_ our `repo <https://github.com/buskill/buskill-app>`_, edit the files as-needed in the `docs directory <https://github.com/BusKill/buskill-app/tree/master/docs>`_, and `submit a PR <https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork>`_.
+
+To know which file to edit, click the ``Edit on GitHub`` link on the top-right of the page you wish to edit.
+
+.. _documentation_building:
+
+Building
+--------
+
+You can build our documentation on Debian 10 using the following commands
+
+::
+
+  apt-get update
+  apt-get -y install git firefox-esr python3-sphinx python3-sphinx-rtd-theme
+
+  git clone https://github.com/BusKill/buskill-app.git
+  cd buskill-app/docs
+
+  make clean
+  make html
+
+After executing the above commands, you should have a new ``docs/_build/html`` directory. You can open your locally-built documentation in firefox by executing
+
+::
+
+  firefox-esr docs/_build/html/index.html
diff --git a/docs/software_dev/index.rst b/docs/software_dev/index.rst
@@ -9,5 +9,5 @@ This section is intended for the developer who wants to modify the source code o
    :maxdepth: 3
 
    autodoc
+   documentation
    repo
-   contributing
diff --git a/docs/software_usr/index.rst b/docs/software_usr/index.rst
@@ -8,6 +8,7 @@ This section will describe how to use the BusKill App to arm, disarm, and config
 .. toctree::
    :maxdepth: 3
 
+   requirements
    download
    gui
    cli
diff --git a/docs/software_usr/requirements.rst b/docs/software_usr/requirements.rst
@@ -0,0 +1,27 @@
+.. _requirements:
+
+System Requirements
+===========================
+
+Our app is released as a self-contained executable, including the python interpreter and all other dependencies.
+
+You need about 50 MB of disk space to download the BusKill app, depending on the platform.
+
+.. _supported_platforms:
+
+Supported Platforms
+-------------------
+
+The below table shows which Operating Systems that the BusKill app has been tested on.
+
+You can help the BusKill project by testing the BusKill app on other platforms and editing this table. For more info, see :ref:`contributing` and :ref:`documentation`.
+
++------------+-----------------------------------+-------------------------------------------------------+
+| Platform   | Version                           | Remark                                                |
++============+===================================+=======================================================+
+| Windows    | 10                                | Supported                                             |
++------------+-----------------------------------+-------------------------------------------------------+
+| MacOS      | 10.15 (Catalina)                  | Supported                                             |
++------------+-----------------------------------+-------------------------------------------------------+
+| Linux      | Ubuntu 20.04 LTS (Focal Fossa)    | Supported                                             |
++------------+-----------------------------------+-------------------------------------------------------+
