nixbitcoin · nixbitcoin · Jan 22, 2022 · Feb 14, 2022 · Feb 20, 2022 · Feb 21, 2022
diff --git a/README.md b/README.md
@@ -49,6 +49,9 @@ Get started
 
 Docs
 ---
+Hint: To show a table of contents, click the button (![Github TOC button](docs/img/github-table-of-contents.svg)) in the
+top left corner of the documents.
+
 * [Hardware requirements](docs/hardware.md)
 * [Installation](docs/install.md)
 * [Configuration and maintenance](docs/configuration.md)
@@ -66,17 +69,19 @@ NixOS modules ([src](modules/modules.nix))
   * [clightning](https://github.com/ElementsProject/lightning) with support for announcing an onion service\
     Available plugins:
     * [clboss](https://github.com/ZmnSCPxj/clboss): automated C-Lightning Node Manager
+    * [commando](https://github.com/lightningd/plugins/tree/master/commando): control your node over lightning
     * [helpme](https://github.com/lightningd/plugins/tree/master/helpme): walks you through setting up a fresh c-lightning node
-    * [monitor](https://github.com/renepickhardt/plugins/tree/master/monitor): helps you analyze the health of your peers and channels
+    * [monitor](https://github.com/lightningd/plugins/tree/master/monitor): helps you analyze the health of your peers and channels
     * [prometheus](https://github.com/lightningd/plugins/tree/master/prometheus): lightning node exporter for the prometheus timeseries server
     * [rebalance](https://github.com/lightningd/plugins/tree/master/rebalance): keeps your channels balanced
     * [summary](https://github.com/lightningd/plugins/tree/master/summary): print a nice summary of the node status
     * [zmq](https://github.com/lightningd/plugins/tree/master/zmq): publishes notifications via ZeroMQ to configured endpoints
-  * [lnd](https://github.com/lightningnetwork/lnd) with support for announcing an onion service
+  * [clightning-rest](https://github.com/Ride-The-Lightning/c-lightning-REST): REST server for clightning
+  * [lnd](https://github.com/lightningnetwork/lnd) with support for announcing an onion service and [static channel backups](https://github.com/lightningnetwork/lnd/blob/master/docs/recovery.md)
     * [Lightning Loop](https://github.com/lightninglabs/loop)
     * [Lightning Pool](https://github.com/lightninglabs/pool)
     * [charge-lnd](https://github.com/accumulator/charge-lnd): policy-based channel fee manager
-    * [lndconnect](https://github.com/LN-Zap/lndconnect) via a REST onion service
+  * [lndconnect](https://github.com/LN-Zap/lndconnect): connect your wallet to lnd or clightning via a REST onion service
   * [Ride The Lightning](https://github.com/Ride-The-Lightning/RTL): web interface for `lnd` and `clightning`
   * [spark-wallet](https://github.com/shesek/spark-wallet)
   * [electrs](https://github.com/romanz/electrs)
@@ -93,6 +98,10 @@ NixOS modules ([src](modules/modules.nix))
 
 Security
 ---
+See [SECURITY.md](SECURITY.md) for the security policy and how to report a vulnerability.
+
+nix-bitcoin aims to achieve a high degree of security by building on the following principles:
+
 * **Simplicity:** Only services enabled in `configuration.nix` and their dependencies are installed, support for [doas](https://github.com/Duncaen/OpenDoas) ([sudo alternative](https://lobste.rs/s/efsvqu/heap_based_buffer_overflow_sudo_cve_2021#c_c6fcfa)), code is continuously reviewed and refined.
 * **Integrity:** The Nix package manager guarantees that all dependencies are exactly specified, packages can be built from source to reduce reliance on binary caches, nix-bitcoin merge commits are signed, all commits are approved by multiple nix-bitcoin developers, upstream packages are cryptographically verified where possible, we use this software ourselves.
 * **Principle of Least Privilege:** Services operate with least privileges; they each have their own user and are restricted further with [systemd features](pkgs/lib.nix), [RPC whitelisting](modules/bitcoind-rpc-public-whitelist.nix) and [netns-isolation](modules/netns-isolation.nix). There's a non-root user *operator* to interact with the various services.

diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,103 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+To report security issues send an encrypted email to the following nix-bitcoin developers or contact them via [matrix](https://matrix.org/).
+
+| Name          | GPG Fingerprint                                    | Email                   | Matrix                                                                             |
+|---------------|----------------------------------------------------|-------------------------|------------------------------------------------------------------------------------|
+| Jonas Nick    | 36C7 1A37 C9D9 88BD E825  08D9 B1A7 0E4F 8DCD 0366 | [email protected]   | [@nickler:nixbitcoin.org](https://matrix.to/#/@nickler:nixbitcoin.org)             |
+| Erik Arvstedt | 4E28 0A8C 1B33 4C86 C26B  C134 3331 2B94 4DD9 7846 | [email protected] | [@erikarvstedt:matrix.org](https://matrix.to/#/@erikarvstedt:matrix.org)           |
+| nixbitcoindev | 577A 3452 7F3E 2A85 E80F  E164 DD11 F9AD 5308 B3BA | [email protected]  | [@nixbitcoindev:nixbitcoin.org](https://matrix.to/#/@nixbitcoindev:nixbitcoin.org) |
+
+You can import a GPG key by running the following command with that individual’s fingerprint: `gpg --keyserver hkps://keys.openpgp.org --recv-keys "<fingerprint>"`. Ensure that you put quotes around fingerprints containing spaces.
+
+[Responsible disclosures](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure) may qualify for a reward from the nix-bitcoin security fund (see [below](#nix-bitcoin-security-fund)).
+
+## Wall of Fame
+
+*empty*
+
+
+## nix-bitcoin security fund
+
+The nix-bitcoin security fund is a collection of funds held on the following 2/3
+bitcoin multisig address which is used to reward security researchers who
+discover and report vulnerabilities in nix-bitcoin or its upstream dependencies.
+Rewards are paid out as percentages of the total fund, rather than as fixed
+amounts.
+
+```
+bc1qrpnz05n0yznaj6yw82wy8dhwuqz86s87vdlhq4cu92fus9qal25s555wsy
+```
+([View balance](https://mempool.nixbitcoin.org/address/bc1qrpnz05n0yznaj6yw82wy8dhwuqz86s87vdlhq4cu92fus9qal25s555wsy))
+
+The nix-bitcoin developers [listed above](#reporting-a-vulnerability) each hold
+one key to the multisig address and collectively form the nix-bitcoin developer
+quorum:
+
+### Eligible Vulnerabilities
+
+The following types of vulnerabilities qualify for rewards, to the exclusion of
+all other security vulnerabilities.
+
+| Type | Description | Examples |
+| :-: | :-: | :-: |
+| Outright Vulnerabilities | Vulnerabilities in nix-bitcoin specific tooling (except CI tooling) | privilege escalation in SUID binary `netns-exec`, improper release signature verification through `fetch-release` |
+| Violations of [PoLP](https://en.wikipedia.org/wiki/Principle_of_least_privilege) | nix-bitcoin services are given too much privilege over the system or unnecessary access to other nix-bitcoin services, or one of the nix-bitcoin isolation measures is incorrectly implemented | `netns-isolation` doesn't work, spark-wallet has access to bitcoin RPC interface or files |
+| Vulnerabilities in Dependencies | A vulnerability in any dependency of a nix-bitcoin installation with a configuration consisting of any combination of the following services: bitcoind, clightning, lnd, electrs, joinmarket, btcpayserver, liquidd.<br />**Note:** The vulnerability must first be reported to and handled by the maintainers of the dependency before it qualifies for a reward| Compromised NixOS expression pulls in malicious package, JoinMarket pulls in a python dependency with a known severe vulnerability |
+| Bad Documentation | Our documentation suggests blatantly insecure things | `install.md` tells you to add our SSH keys to your root user |
+| Compromise of Signing Key | Compromise of the nix-bitcoin signing key, i.e., `0xB1A70E4F8DCD0366` | Leaking the key, managing to sign something with it |
+
+### Reward
+
+Researchers qualify for a maximum reward[^1] of 10% of the total fund holdings for
+reporting any vulnerability that matches the above eligibility requirements. If
+a vulnerability or any combination of a number of vulnerabilities that meet the
+above-described eligibility requirements can lead to a realistic attack on
+nix-bitcoin users, researchers qualify for a higher maximum reward[^1] depending
+the final outcome of the attack scenario:
+
+| Outcome | Description | Maximum Reward of Total Fund[^1] |
+| :-: | :-: | :-: |
+| Loss of Funds | Attack allows stealing or destroying user's funds | 50 % |
+| Loss of Privacy | Attack allows exfiltrating sensitive information or otherwise attributing a user's real world identity to his nix-bitcoin node or funds held/managed thereon without the user specifically opting-in to this (e.g., by disabling the `secure-node` preset) | 25 % |
+| Denial of Service | Attack allows crashing a service or otherwise denying a user service from his node | 25 % |
+
+All other reported vulnerabilities which meet the above requirements without a
+clear and plausible attack scenario receive a maximum reward[^1] of 10% of the
+fund.
+
+[^1]: Rewards are subject to a discount at the discretion of the nix-bitcoin
+developer quorum for reasons such as insignificance of the vulnerability or
+obscurity of the victim's required configuration, as well as simple mitigation
+(i.e.  the attack should have been mitigated anyway by common-sense security
+measures) or complex/unlikely attack execution.
+
+### Policy
+
+* Vulnerabilities must be [responsibly
+  disclosed](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure).
+* E2EE: Vulnerabilities must be disclosed via end-to-end encrypted communication
+  methods, such as PGP E-Mail or Matrix.
+* Wall of Fame: In addition to the above rewards, security researchers will also
+  be added to the Wall of Fame, unless, of course, they wish to remain
+  anonymous.
+* First come, first serve: Rewards are awarded strictly on a first come, first
+  serve basis from the date they were responsibly disclosed in their entirety.
+  Multiple reports from the same researcher can either be bundled for a higher
+  likelihood of receiving the full maximum reward or rewarded individually,
+  proportional to the remaining amount.
+* Exclusion of dependencies with existing bug bounty programms: Software which
+  is covered by an existing bug bounty program is not eligible for rewards under
+  the "Vulnerabilities in Dependencies" category.
+* Exclusion of dependencies with known vulnerabilities that are in the process
+  of being patched: Software with a known vulnerability where there is reason to
+  believe that the patch is still under development or simply has not yet been
+  ported to NixOS, due to the relative recency of the patch, is not eligible for
+  rewards under the "Vulnerabilities in Dependencies" category.
+* Termination: The fund can be terminated at any time by the quorum of key
+  holders in which case the holdings are donated to non-profit organizations.
+* This document may be updated over time to ensure smooth and purposeful
+  operation of the fund as an incentive for security researchers to investigate
+  and report vulnerabilities in the nix-bitcoin ecosystem.
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -22,8 +22,7 @@ This fetches the latest release, verifies its signatures and updates `nix-bitcoi
 ## Get started with Nix
 
 See [Nix - A One Pager](https://github.com/tazjin/nix-1p) for a short guide
-to Nix, the language used in `configuration.nix`.
-
+to Nix, the language used in `configuration.nix`.\
 You can follow along this guide by running command `nix repl` which allows you to interactively
 evaluate Nix expressions.
 
@@ -178,7 +177,7 @@ Some services require extra steps:
 
 # Use bitcoind from another node
 
-Use a bitcoind instance running on another node within a nix-bitcoin config.
+Here's how to use a bitcoind instance running on another node within a nix-bitcoin config:
 
 ```nix
 imports = [ <nix-bitcoin/modules/presets/bitcoind-remote.nix> ];
@@ -226,7 +225,7 @@ $secretsDir/bitcoin-rpcpassword-public
 ```
 See: [Secrets dir](#secrets-dir)
 
-Restart `bitcoind` after updating the secrets: `systemctl restart bitcoind`.
+Afterwards, restart `bitcoind`: `systemctl restart bitcoind`.
 
 # Temporarily disable a service
 

diff --git a/docs/img/github-table-of-contents.svg b/docs/img/github-table-of-contents.svg
diff --git a/docs/services.md b/docs/services.md
@@ -44,6 +44,61 @@ You can find the `<onion-address>` with command `nodeinfo`.
 The default password location is `$secretsDir/rtl-password`.
 See: [Secrets dir](./configuration.md#secrets-dir)
 
+# Use LND or clightning with Zeus (mobile wallet) via Tor
+1. Install [Zeus](https://zeusln.app)
+
+2. Edit your `configuration.nix`
+
+   ##### For lnd
+
+   Add the following config:
+   ```
+   services.lnd.lndconnectOnion.enable = true;
+   ```
+
+   ##### For clightning
+
+   Add the following config:
+   ```
+   services.clightning-rest = {
+     enable = true;
+     lndconnectOnion.enable = true;
+   };
+   ```
+
+3. Deploy your configuration
+
+3. Run the following command on your node (as user `operator`) to create a QR code
+   with address and authentication information:
+
+   ##### For lnd
+   ```
+   lndconnect-onion
+   ```
+
+   ##### For clightning
+   ```
+   lndconnect-onion-clightning
+   ```
+
+4. Configure Zeus
+   - Add a new node
+   - Select `Scan lndconnect config` (at the bottom) and scan the QR code
+   - For clightning: Set `Node interface` to `c-lightning-REST`
+   - Click `Save node config`
+   - Start sending and stacking sats privately
+
+### Additional lndconnect features
+Create plain text URLs or QR code images:
+```
+lndconnect-onion --url
+lndconnect-onion --image
+``````
+Create a QR code for a custom hostname:
+```
+lndconnect-onion --host=mynode.org
+```
+
 # Connect to spark-wallet
 ### Requirements
 * Android phone
@@ -87,42 +142,6 @@ See: [Secrets dir](./configuration.md#secrets-dir)
     Done
     ```
 
-# Connect to LND with Zeus
-### Requirements
-* Android phone
-* [Orbot](https://guardianproject.info/apps/orbot/) installed from
-  [F-Droid](https://guardianproject.info/fdroid) (recommended) or
-  [Google Play](https://play.google.com/store/apps/details?id=org.torproject.android&hl=en)
-* [Zeus](https://zeusln.app/) installed from
-  [F-Droid](https://f-droid.org/en/packages/app.zeusln.zeus/) (recommended) or
-  [Google Play](https://play.google.com/store/apps/details?id=app.zeusln.zeus)
-
-1. Enable `restOnionService` in `configuration.nix`
-
-    Change
-    ```
-    # services.lnd.restOnionService.enable = true;
-    ```
-    to
-    ```
-    services.lnd.restOnionService.enable = true;
-    ```
-
-2. Deploy new `configuration.nix`
-
-3. Run command `lndconnect-rest-onion` (under `operator` user) to create a QR code for
-   connecting to LND via the REST onion service.
-
-4. Enable Orbot VPN for Zeus
-    ```
-    Open Orbot app
-    Turn on "VPN Mode"
-    Select Gear icon under "Tor-Enabled Apps"
-    Toggle checkbox under Zeus icon
-    ```
-
-5. Scan the QR code with your Zeus wallet and start sending Satoshis privately
-
 # Connect to electrs
 ### Requirements Android
 * Android phone

diff --git a/examples/configuration.nix b/examples/configuration.nix
@@ -53,6 +53,17 @@
   # == Plugins
   # See ../README.md (Features → clightning) for the list of available plugins.
   # services.clightning.plugins.prometheus.enable = true;
+  #
+  # == REST server
+  # Set this to create a clightning REST onion service.
+  # This also adds binary `lndconnect-onion-clightning` to the system environment.
+  # This binary creates QR codes or URLs for connecting applications to clightning
+  # via the REST onion service (see ../docs/services.md).
+  #
+  # services.clightning-rest = {
+  #   enable = true;
+  #   lndconnectOnion.enable = true;
+  # };
 
   ### LND
   # Set this to enable lnd, a lightning implementation written in Go.
@@ -68,10 +79,10 @@
   # nix-bitcoin.onionServices.lnd.public = true;
   #
   # Set this to create an lnd REST onion service.
-  # Adds binary `lndconnect-rest-onion` to the system environment.
-  # This binary generates QR codes or URIs for connecting applications to lnd via the
-  # REST onion service.
-  # services.lnd.restOnionService.enable = true;
+  # This also adds binary `lndconnect-onion` to the system environment.
+  # This binary generates QR codes or URLs for connecting applications to lnd via the
+  # REST onion service (see ../docs/services.md).
+  # services.lnd.lndconnectOnion.enable = true;
   #
   ## WARNING
   # If you use lnd, you should manually backup your wallet mnemonic
@@ -83,24 +94,26 @@
   # You should also backup your channel state after opening new channels.
   # This will allow you to recover off-chain funds, by force-closing channels.
   #   scp bitcoin-node:/var/lib/lnd/chain/bitcoin/mainnet/channel.backup ./backups/lnd/
+  #
+  # Alternatively, you can have these files backed up by services.backups below.
 
   ### RIDE THE LIGHTNING
   # Set this to enable RTL, a web interface for lnd and clightning.
   # services.rtl.enable = true;
   #
   # Set this to add a clightning node interface.
   # Automatically enables clightning.
-  # services.rtl.nodes.clightning = true;
+  # services.rtl.nodes.clightning.enable = true;
   #
   # Set this to add a lnd node interface.
   # Automatically enables lnd.
-  # services.rtl.nodes.lnd = true;
+  # services.rtl.nodes.lnd.enable = true;
   #
   # You can enable both nodes simultaneously.
   #
   # Set this option to enable swaps with lightning-loop.
   # Automatically enables lightning-loop.
-  # services.rtl.loop = true;
+  # services.rtl.nodes.lnd.loop = true;
 
   ### SPARK WALLET
   # Set this to enable spark-wallet, a minimalistic wallet GUI for
@@ -201,6 +214,11 @@
   # Set this to enable the JoinMarket order book watcher.
   # services.joinmarket-ob-watcher.enable = true;
 
+  ### MEMPOOL
+  # Set this to enable mempool, a fully featured Bitcoin visualizer, explorer, and
+  # API service.
+  # services.mempool.enable = true;
+
   ### Backups
   # Set this to enable nix-bitcoin's own backup service. By default, it
   # uses duplicity to incrementally back up all important files in /var/lib to
@@ -261,10 +279,10 @@
   # compatible, in order to avoid breaking some software such as database
   # servers. You should change this only after NixOS release notes say you
   # should.
-  system.stateVersion = "21.05"; # Did you read the comment?
+  system.stateVersion = "21.11"; # Did you read the comment?
 
   # The nix-bitcoin release version that your config is compatible with.
   # When upgrading to a backwards-incompatible release, nix-bitcoin will display an
   # an error and provide hints for migrating your config to the new release.
-  nix-bitcoin.configVersion = "0.0.65";
+  nix-bitcoin.configVersion = "0.0.70";
 }
diff --git a/examples/flakes/flake.nix b/examples/flakes/flake.nix
@@ -1,7 +1,7 @@
 {
   description = "A basic nix-bitcoin node";
 
-  inputs.nix-bitcoin.url = "github:fort-nix/nix-bitcoin";
+  inputs.nix-bitcoin.url = "github:fort-nix/nix-bitcoin/release";
 
   outputs = { self, nix-bitcoin }: {