Further elaboration of the advisory DB proposal

Author: david-christiansen

proposals/advisory-db.md

@@ -103,18 +103,53 @@ The `affected` table, if present, contains the following fields, all of which ar
  * `declarations`, a table that maps fully-qualified names from the package to Cabal v2.0 version ranges. These ranges must all be contained in the affected versions (specified later), and they specify that the given name is the source of the advisory in that sub-range. This allows one advisory to mention a function or datatype that is renamed at some point during development.
 The `versions` table contains a single mandatory key, `affected`, whose value is a string that contains a Cabal v2.0 version range.
 
-Cabal v2.0 version ranges are specified using the following grammar: TODO
+Cabal v2.0 version ranges are specified using the following grammar:
+
+```
+VersionNum ::= "0" | [1-9][0-9]{0-8}   -- Up to nine digits, no leading 0
+
+Version ::= VersionNum | VersionNum "." Version -- Any number of VersionNum, dot-separated
+
+VersionRange ::=
+  "==" Version |
+  ">" Version |
+  "<" Version |
+  "<=" Version |
+  ">=" Version |
+  "^>=" Version |
+  VersionRange "&&" VersionRange |
+  VersionRange "||" VersionRange |
+  "(" VersionRange ")"
+```
+
+In the above, `&&` binds more tightly than `||`, so `VersionRange1 && VersionRange2 || VersionRange3` is equivalent to `(VersionRange1 && VersionRange2) || VersionRange3`.
+
+Ordering (and thus equality) of version numbers is defined in the Haskell [Package Versioning Policy](https://pvp.haskell.org). Ordering is defined lexicographically with respect to the numeric values of version number components. This means, for instance, that `1.5.3.0 > 1.5.3`.
+
+The `^>=` operator defines both lower and upper bounds for a dependency according to the following desugaring:
+ * `^>= x ↝ >= x && < x.1`
+ * `^>= x.y ↝ >= x.y && < x.(y+1)`
+ * `^>= x.y.z ↝ >= x.y.z && < x.(y+1)`
+ * `^>= x.y.z.u ↝ >= x.y.z.u && < x.(y+1)`
+ * and so forth
+
 
-Tools that detect vulnerabilities will need to check whether advisory version ranges overlap with dependency version constraints. The algorithm for this is TODO.
 
 ### Recommendations Regarding Build/Freeze Files
 
-TODO: Which formats do we recommend they look in to start with? `.cabal`, `cabal.freeze`? Stack users' constraints mostly come from their snapshot - how can we make this work for people with no constraints in `.cabal` and a `stack.yaml` file?
+TODO: How do we actually let them look at cabal files? Common stanzas and conditionals make this fairly non-trivial.
+
+TODO - Recommendation will be to do the following:
+ * First process Cabal files
+ * Then do freeze files, which should allow processing Stackage resolver files as well
+ * Then read stack.yaml enough to get the resolver
 
 ### Governance and Administration
 
 The Haskell Foundation will be responsible for appointing the administrators of the database. Administrators are expected to be trusted community members who are willing to provide timely feedback in the repository. The Haskell Foundation should check from time to time that feedback is timely, and can serve as a final arbiter of disputes.
 
+To begin with, the HF executive team will assemble a group of five volunteers, who will be solicited from bodies such as the Core Libraries Committee and the Hackage trustees, asking for a one-year commitment. The HF will evaluate the size and composition of the group on an ongoing basis, and may make adjustments to membership. We will recruit a set of volunteers with knowledge of cryptography, low-level exploits such as buffer overflows, the GHC RTS, network security, and security organization best practices, as well as good communication skills, and will adjust the size of the volunteer group until these areas are covered.
+
 ## Resources
 
 This proposal requires the following:

proposals/advisory-db/README.txt

@@ -0,0 +1 @@
+This is a proof-of-concept parser and renderer for the advisory format. It accepts an advisory on stdin, and either fails or emits an HTML rendering on stdout.

proposals/advisory-db/advisory-proposal.cabal

@@ -0,0 +1,42 @@
+cabal-version:      2.4
+name:               advisory-proposal
+version:            0.1.0.0
+
+-- A short (one-line) description of the package.
+-- synopsis:
+
+-- A longer description of the package.
+-- description:
+
+-- A URL where users can report bugs.
+-- bug-reports:
+
+-- The license under which the package is released.
+-- license:
+author:             David Christiansen
+maintainer:         [email protected]
+
+-- A copyright notice.
+-- copyright:
+-- category:
+extra-source-files: CHANGELOG.md
+
+executable advisory-proposal
+    main-is:          Main.hs
+
+    -- Modules included in this executable, other than Main.
+    -- other-modules:
+
+    -- LANGUAGE extensions used by modules in this package.
+    -- other-extensions:
+    build-depends:    base ^>=4.14.3.0,
+                      commonmark ^>= 0.2.2,
+                      text ^>= 1.2,
+                      time ^>= 1.9,
+                      Cabal ^>= 3.6.3.0,
+                      mtl ^>= 2.2,
+                      unordered-containers,
+                      containers ^>= 0.6,
+                      toml-reader ^>= 0.1
+    hs-source-dirs:   app
+    default-language: Haskell2010