Upgrade DependencyCheck

Adds a FAQ and other documentation.

Closes #126

.github/ISSUE_TEMPLATE/bug.yml

@@ -48,8 +48,8 @@ body:
       label: Installation compliance
       description: 
       options:
-        - label: I have read again and made sure that I'm following **exactly** the instructions for my tool of choice ([Leiningen](https://github.com/rm-hull/nvd-clojure/tree/v2.13.0#leiningen), [Clojure CLI](https://github.com/rm-hull/nvd-clojure/tree/v2.13.0#clojure-cli), [Clojure CLI Tool](https://github.com/rm-hull/nvd-clojure/tree/v2.13.0#clojure-cli-tool)).
+        - label: I have read again and made sure that I'm following **exactly** the instructions for my tool of choice ([Leiningen](https://github.com/rm-hull/nvd-clojure/tree/v3.0.0#leiningen), [Clojure CLI](https://github.com/rm-hull/nvd-clojure/tree/v3.0.0#clojure-cli), [Clojure CLI Tool](https://github.com/rm-hull/nvd-clojure/tree/v3.0.0#clojure-cli-tool)).
           required: true
-        - label: I understand that false positives [can be skipped locally](https://github.com/rm-hull/nvd-clojure/tree/v2.13.0#configuration-options) and should be reported to [DependencyCheck](https://github.com/jeremylong/DependencyCheck).
+        - label: I understand that false positives [can be skipped locally](https://github.com/rm-hull/nvd-clojure/tree/v3.0.0#configuration-options) and should be reported to [DependencyCheck](https://github.com/jeremylong/DependencyCheck).
           required: false
 

.github/ISSUE_TEMPLATE/issue.yml

@@ -32,8 +32,8 @@ body:
       label: Installation compliance
       description: 
       options:
-        - label: I have read again and made sure that I'm following **exactly** the instructions for my tool of choice ([Leiningen](https://github.com/rm-hull/nvd-clojure/tree/v2.13.0#leiningen), [Clojure CLI](https://github.com/rm-hull/nvd-clojure/tree/v2.13.0#clojure-cli), [Clojure CLI Tool](https://github.com/rm-hull/nvd-clojure/tree/v2.13.0#clojure-cli-tool)).
+        - label: I have read again and made sure that I'm following **exactly** the instructions for my tool of choice ([Leiningen](https://github.com/rm-hull/nvd-clojure/tree/v3.0.0#leiningen), [Clojure CLI](https://github.com/rm-hull/nvd-clojure/tree/v3.0.0#clojure-cli), [Clojure CLI Tool](https://github.com/rm-hull/nvd-clojure/tree/v3.0.0#clojure-cli-tool)).
           required: true
-        - label: I understand that false positives [can be skipped locally](https://github.com/rm-hull/nvd-clojure/tree/v2.13.0#configuration-options) and should be reported to [DependencyCheck](https://github.com/jeremylong/DependencyCheck).
+        - label: I understand that false positives [can be skipped locally](https://github.com/rm-hull/nvd-clojure/tree/v3.0.0#configuration-options) and should be reported to [DependencyCheck](https://github.com/jeremylong/DependencyCheck).
           required: false
 

CHANGELOG.md

@@ -2,13 +2,14 @@
 
 * Introduce .edn configuration format.
   * .json files will remain working as-is indefinitely.
-  * If you wish to migrate to the .edn format, doing so is easy - please see [FAQ]().
+  * If you wish to migrate to the .edn format, doing so is easy - please see [FAQ](https://github.com/rm-hull/nvd-clojure/blob/v3.0.0/FAQ.md).
   * If you specify the blank string as the config file to be used, a useful, sample .edn file will be generated.
 * Automatically create a .xml suppression file when a `:suppression-file` is specified and no such file exists
   * In practice, this means that on the first run, if you specify the blank string as the config file to be used, two files will be created for you:
     * `nvd-clojure.edn`
     * `nvd_suppressions.xml`
   * After this automatic creation, you are free to tweak and version-control these files as desired.
+* Update `dependency-check-core`.
 
 ## Changes from 2.12.0 to 2.13.0
 

FAQ.md

@@ -0,0 +1,86 @@
+## FAQ
+
+### What versioning scheme does nvd-clojure use?
+
+nvd-clojure simply uses Semver. Breaking changes may happen because it is a security-sensitive tool: sometimes it is in best interest of security to leave unsafe details behind.
+
+It is part of nvd-clojure's API contract that its output will 'break' your CI build on the regular: it is precisely intended to do that (exit with a non-zero code whenever something needs attention).
+
+So breaking API changes aren't drastically different from the other changes that regular nvd-clojure use would imply.
+
+With that said, there is active effort to avoid superflous API changes. We do intend to keep whatever can be reasonably kept.
+
+### How do I migrate from the .json config format to .edn?
+
+The .json config file format is considered legacy now, although it will remain supported.
+
+If you wish to use .edn instead, please retain the map associated to the `"nvd"` key, discarding the surrounding data, and perform a simple conversion where string keys become keywords.
+
+Example:
+
+```diff
+-{"delete-config?": false,
+- "nvd": {"suppression-file": "nvd_suppressions.xml"}}
++{:suppression-file "nvd_suppressions.xml"}
+```
+
+...rename this file to nvd-clojure.edn and make sure to specify this new filename in any CLI/CI invocations.
+
+If the file is named nvd-clojure.edn (i.e. the default filename), you can specify the empty string `""` instead of typing the filename.
+
+This shorthand form has the advantage of producing a reusable command that if executed in some other project, will automatically create this .edn file when missing, including some useful contents and comments.
+
+### Why are there false positives?
+
+nvd-clojure uses [DependencyCheck](https://github.com/jeremylong/DependencyCheck) for doing most of its job. DependencyCheck checks dependencies against the NVD database.
+
+A given CVE is not expressed in a format that can be unmistakably matched with a single specific Maven artifact. That is outside of DependencyCheck's control, so it does a best effort at preventing false positives.
+
+### Why is it suggested that I install nvd-clojure by creating a project directory?
+
+For all usages other than Clojure Tools (e.g. Leiningen, or the Clojure CLI), the instructions suggest to create a directory containing a `project.clj` or `deps.edn` file.
+
+This would be technically a 'subproject' within your project. Some people might find this strange, however it's a drastically simpler approach than the alternatives, that is easy to understand and which has proven to rule out all sorts of issues that were historically present.
+
+You can think of this directory as not drastically different from a `.github` or `.circleci` directory. It's just a single directory with a single, "just data" piece of information.
+
+There are other approaches that can work, however our assessment is that they're not as robust and may break at some point. 
+
+### Why not distribute a .jar that can be invoked on any project?
+
+That .jar would be a uberjar, i.e. it not only would bundle nvd-clojure, but also all its dependencies.
+
+We believe bundling such a large, opaque blob would not be up to the standards of a security-sensitive project.
+
+### OSS Index flakiness
+
+If you experience HTTP errors from OSS Index while running nvd-clojure, setting `:ossindex-warn-only-on-remote-errors true` will prevent those from failing that run.
+
+(You can grep for that code in this repo for a precise example)
+
+However please be advised that doing that can cause false negatives.
+
+OSS Index is not expected to always be flaky, so if setting this, we would advise to schedule removing that setting, while keeping an eye on any issue report that might be publicly available.
+
+### How to remediate a CVE? Is it a good idea to automate remediation?
+
+CVEs can be remediated in a variety of ways:
+
+* Upgrading a direct dependency
+* Replacing a dependency for another one
+  * e.g. change the choice of JSON parser
+* Upgrading a managed dependency
+* Declaring transitive dependency, setting it to a newer version
+* Upgrading a transitive dependency
+* Removing a direct dependency
+* Adding `:exclusions` such that a transitive dependency will be removed
+* Adding an entry to `nvd-suppressions.xml`
+  * Fine-grained (exact)
+  * Coarse-grained (wildcard)
+  * Temporal (with an expiration date)
+
+Devising a sensible remediation for a specific scenario will depend on your project and its needs. Completing one of the choices outlined above might need application-level code changes.
+
+No automated program can possibly assess and apply the best possible choice. We strongly believe the simplest and safest remediation can only be devised by you!
+
+In general, we do try to encourage a thoughtful approach to security - CVE reports aren't simply a chore to be silenced in 'whatever way works'.

LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 
-Copyright (c) 2016-22 Richard Hull
+Copyright (c) 2016-23 Richard Hull
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

Makefile

@@ -2,7 +2,7 @@
 
 # Example usage:
 # copy a one-off Clojars token to your clipboard
-# GIT_TAG=v2.13.0 CLOJARS_USERNAME=$USER CLOJARS_PASSWORD=$(pbpaste) make deploy
+# GIT_TAG=v3.0.0 CLOJARS_USERNAME=$USER CLOJARS_PASSWORD=$(pbpaste) make deploy
 
 deploy: check-env
 	lein clean