nixpkgs: allow packages to be marked insecure

If a package's meta has `knownVulnerabilities`, like so:

    stdenv.mkDerivation {
      name = "foobar-1.2.3";

      ...

      meta.knownVulnerabilities = [
        "CVE-0000-00000: remote code execution"
        "CVE-0000-00001: local privilege escalation"
      ];
    }

and a user attempts to install the package, they will be greeted with
a warning indicating that maybe they don't want to install it:

    error: Package ‘foobar-1.2.3’ in ‘...default.nix:20’ is marked as insecure, refusing to evaluate.

    Known issues:

     - CVE-0000-00000: remote code execution
     - CVE-0000-00001: local privilege escalation

    You can install it anyway by whitelisting this package, using the
    following methods:

    a) for `nixos-rebuild` you can add ‘foobar-1.2.3’ to
       `nixpkgs.config.permittedInsecurePackages` in the configuration.nix,
       like so:

         {
           nixpkgs.config.permittedInsecurePackages = [
             "foobar-1.2.3"
           ];
         }

    b) For `nix-env`, `nix-build`, `nix-shell` or any other Nix command you can add
    ‘foobar-1.2.3’ to `permittedInsecurePackages` in
    ~/.config/nixpkgs/config.nix, like so:

         {
           permittedInsecurePackages = [
             "foobar-1.2.3"
           ];
         }

Adding either of these configurations will permit this specific
version to be installed. A third option also exists:

  NIXPKGS_ALLOW_INSECURE=1 nix-build ...

though I specifically avoided having a global file-based toggle to
disable this check. This way, users don't disable it once in order to
get a single package, and then don't realize future packages are
insecure.

1 files changed, 173 insertions, 43 deletions

diff --git a/doc/configuration.xml b/doc/configuration.xml
index 12e3b8ae851..064c72a7630 100644
--- a/doc/configuration.xml
+++ b/doc/configuration.xml
@@ -4,83 +4,213 @@
 
 <title>Global configuration</title>
 
-<para>Nix packages can be configured to allow or deny certain options.</para>
+<para>Nix comes with certain defaults about what packages can and
+cannot be installed, based on a package's metadata. By default, Nix
+will prevent installation if any of the following criteria are
+true:</para>
 
-<para>To apply the configuration edit
-<filename>~/.config/nixpkgs/config.nix</filename> and set it like
+<itemizedlist>
+  <listitem><para>The packages is thought to be broken, and has had
+  its <literal>meta.broken</literal> set to
+  <literal>true</literal>.</para></listitem>
+
+  <listitem><para>The package's <literal>meta.license</literal> is set
+  to a license which is considered to be unfree.</para></listitem>
+
+  <listitem><para>The package has known security vulnerabilities but
+  has not or can not be updated for some reason, and a list of issues
+  has been entered in to the package's
+  <literal>meta.knownVulnerabilities</literal>.</para></listitem>
+</itemizedlist>
 
+<para>Each of these criteria can be altering the nixpkgs
+configuration.</para>
+
+<para>The nixpkgs configuration for a NixOS system is set in the
+<literal>configuration.nix</literal>, as in the following example:
+<programlisting>
+{
+  nixpkgs.config = {
+    allowUnfree = true;
+  };
+}
+</programlisting>
+However, this does not allow unfree software for individual users.
+Their configurations are managed separately.</para>
+
+<para>A user's of nixpkgs configuration is stored in a user-specific
+configuration file located at
+<filename>~/.config/nixpkgs/config.nix</filename>. For example:
 <programlisting>
 {
   allowUnfree = true;
 }
 </programlisting>
+</para>
 
-and will allow the Nix package manager to install unfree licensed packages.</para>
+<section xml:id="sec-allow-broken">
+  <title>Installing broken packages</title>
 
-<para>The configuration as listed also applies to NixOS under
-<option>nixpkgs.config</option> set.</para>
 
-<itemizedlist>
+  <para>There are two ways to try compiling a package which has been
+  marked as broken.</para>
 
-  <listitem>
-    <para>Allow installing of packages that are distributed under
-    unfree license by setting <programlisting>allowUnfree =
-    true;</programlisting> or deny them by setting it to
-    <literal>false</literal>.</para>
+  <itemizedlist>
+    <listitem><para>
+      For allowing the build of a broken package once, you can use an
+      environment variable for a single invocation of the nix tools:
 
-    <para>Same can be achieved by setting the environment variable:
+      <programlisting>$ export NIXPKGS_ALLOW_BROKEN=1</programlisting>
+    </para></listitem>
 
-<programlisting>
-$ export NIXPKGS_ALLOW_UNFREE=1
-</programlisting>
+    <listitem><para>
+      For permanently allowing broken packages to be built, you may
+      add <literal>allowBroken = true;</literal> to your user's
+      configuration file, like this:
+
+      <programlisting>
+{
+  allowBroken = true;
+}</programlisting>
+    </para></listitem>
+  </itemizedlist>
+</section>
+
+<section xml:id="sec-allow-unfree">
+  <title>Installing unfree packages</title>
 
-    </para>
-  </listitem>
+  <para>There are several ways to tweak how Nix handles a package
+  which has been marked as unfree.</para>
 
-  <listitem>
-    <para>Whenever unfree packages are not allowed, single packages
-    can still be allowed by a predicate function that accepts package
-    as an argument and should return a boolean:
+  <itemizedlist>
+    <listitem><para>
+      To temporarily allow all unfree packages, you can use an
+      environment variable for a single invocation of the nix tools:
 
+      <programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting>
+    </para></listitem>
+
+    <listitem><para>
+      It is possible to permanently allow individual unfree packages,
+      while still blocking unfree packages by default using the
+      <literal>allowUnfreePredicate</literal> configuration
+      option in the user configuration file.</para>
+
+      <para>This option is a function which accepts a package as a
+      parameter, and returns a boolean. The following example
+      configuration accepts a package and always returns false:
 <programlisting>
-allowUnfreePredicate = (pkg: ...);
+{
+  allowUnfreePredicate = (pkg: false);
+}
 </programlisting>
+      </para>
 
-    Example to allow flash player and visual studio code only:
+      <para>A more useful example, the following configuration allows
+      only allows flash player and visual studio code:
 
 <programlisting>
-allowUnfreePredicate = with builtins; (pkg: elem (parseDrvName pkg.name).name [ "flashplayer" "vscode" ]);
+{
+  allowUnfreePredicate = (pkg: elem (builtins.parseDrvName pkg.name).name [ "flashplayer" "vscode" ]);
+}
 </programlisting>
+    </para></listitem>
 
-    </para>
-  </listitem>
+    <listitem>
+      <para>It is also possible to whitelist and blacklist licenses
+      that are specifically acceptable or not acceptable, using
+      <literal>whitelistedLicenses</literal> and
+      <literal>blacklistedLicenses</literal>, respectively.
+      </para>
 
-  <listitem>
-    <para>Whenever unfree packages are not allowed, packages can still
-    be whitelisted by their license:
+      <para>The following example configuration whitelists the
+      licenses <literal>amd</literal> and <literal>wtfpl</literal>:
 
 <programlisting>
-whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];
+{
+  whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];
+}
 </programlisting>
-    </para>
-  </listitem>
+      </para>
 
-  <listitem>
-    <para>In addition to whitelisting licenses which are denied by the
-    <literal>allowUnfree</literal> setting, you can also explicitely
-    deny installation of packages which have a certain license:
+      <para>The following example configuration blacklists the
+      <literal>gpl3</literal> and <literal>agpl3</literal> licenses:
 
 <programlisting>
-blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];
+{
+  blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];
+}
 </programlisting>
-    </para>
-  </listitem>
+      </para>
+    </listitem>
+  </itemizedlist>
+
+  <para>A complete list of licenses can be found in the file
+  <filename>lib/licenses.nix</filename> of the nixpkgs tree.</para>
+</section>
 
-</itemizedlist>
 
-<para>A complete list of licenses can be found in the file
-<filename>lib/licenses.nix</filename> of the nix package tree.</para>
+<section xml:id="sec-allow-insecure">
+  <title>
+    Installing insecure packages
+  </title>
 
+  <para>There are several ways to tweak how Nix handles a package
+  which has been marked as unfree.</para>
+
+  <itemizedlist>
+    <listitem><para>
+      To temporarily allow all insecure packages, you can use an
+      environment variable for a single invocation of the nix tools:
+
+      <programlisting>$ export NIXPKGS_ALLOW_INSECURE=1</programlisting>
+    </para></listitem>
+
+    <listitem><para>
+      It is possible to permanently allow individual insecure
+      packages, while still blocking other insecure packages by
+      default using the <literal>permittedInsecurePackages</literal>
+      configuration option in the user configuration file.</para>
+
+      <para>The following example configuration permits the
+      installation of the hypothetically insecure package
+      <literal>hello</literal>, version <literal>1.2.3</literal>:
+<programlisting>
+{
+  permittedInsecurePackages = [
+    "hello-1.2.3"
+  ];
+}
+</programlisting>
+      </para>
+    </listitem>
+
+    <listitem><para>
+      It is also possible to create a custom policy around which
+      insecure packages to allow and deny, by overriding the
+      <literal>allowInsecurePredicate</literal> configuration
+      option.</para>
+
+      <para>The <literal>allowInsecurePredicate</literal> option is a
+      function which accepts a package and returns a boolean, much
+      like <literal>allowUnfreePredicate</literal>.</para>
+
+      <para>The following configuration example only allows insecure
+      packages with very short names:
+
+<programlisting>
+{
+  allowInsecurePredicate = (pkg: (builtins.stringLength (builtins.parseDrvName pkg.name).name) &lt;= 5);
+}
+</programlisting>
+      </para>
+
+      <para>Note that <literal>permittedInsecurePackages</literal> is
+      only checked if <literal>allowInsecurePredicate</literal> is not
+      specified.
+    </para></listitem>
+  </itemizedlist>
+</section>
 
 <!--============================================================-->