docs: add deployment best practices to manual

Signed-off-by: Terri Oda <[email protected]>

doc/MANUAL.md

@@ -3,6 +3,12 @@
 - [CVE Binary Tool User Manual](#cve-binary-tool-user-manual)
   - [How it works](#how-it-works)
   - [Installing](#installing)
+  - [Deployment best practices](#deployment-best-practices)
+    - [Use user-level permissions with appropriate file system access](#use-user-level-permissions-with-appropriate-file-system-access)
+    - [Use restrictions on system temp files](#use-restrictions-on-system-temp-files)
+    - [Schedule data updates separately when running parallel scans](#schedule-data-updates-separately-when-running-parallel-scans)
+    - [Using cve-bin-tool within a throaway environment](#using-cve-bin-tool-within-a-throaway-environment)
+    - [Don't scan arbitrary binary files without additional sandboxing](#dont-scan-arbitrary-binary-files-without-additional-sandboxing)
   - [Fixing Known Issues / What should I do if it finds something?](#fixing-known-issues--what-should-i-do-if-it-finds-something)
   - [Data Sources](#data-sources)
     - [National Vulnerability Database (NVD)](#national-vulnerability-database-nvd)
@@ -47,6 +53,7 @@
     - [-c CVSS, --cvss CVSS](#-c-cvss---cvss-cvss)
     - [--epss-percentile](#--epss-percentile)
     - [--epss-probability](#--epss-probability)
+    - [Automatic Metrics Activation](#automatic-metrics-activation)
     - [-S {low,medium,high,critical}, --severity {low,medium,high,critical}](#-s-lowmediumhighcritical---severity-lowmediumhighcritical)
     - [-A \[\<distro\_name\>-\<distro\_version\_name\>\], --available-fix \[\<distro\_name\>-\<distro\_version\_name\>\]](#-a-distro_name-distro_version_name---available-fix-distro_name-distro_version_name)
     - [-b \[\<distro\_name\>-\<distro\_version\_name\>\], --backport-fix \[\<distro\_name\>-\<distro\_version\_name\>\]](#-b-distro_name-distro_version_name---backport-fix-distro_name-distro_version_name)
@@ -79,7 +86,9 @@
     - [Go](#go)
     - [Swift](#swift)
     - [Python](#python)
+      - [Support for Version Range (`~=`) in `requirements.txt`](#support-for-version-range--in-requirementstxt)
     - [Perl](#perl)
+    - [PHP](#php)
   - [Feedback \& Contributions](#feedback--contributions)
   - [Security Issues](#security-issues)
 
@@ -317,6 +326,48 @@ Windows has `ar` and `Expand` installed in default, but `7z` in particular might
 If you wan to run our test-suite or scan a zstd compressed file, We recommend installing this [7-zip-zstd](https://github.com/mcmilk/7-Zip-zstd)
 fork of 7zip. We are currently using `7z` for extracting `jar`, `apk`, `msi`, `exe` and `rpm` files.
 
+## Deployment best practices
+
+CVE binary tool was expected to be used by developers wishing to track known vulnerabilities against their own code and their dependencies.  We expect many users to use continuous integration systems such as Github Actions, and we have our own [cve-bin-tool GitHub Action](https://github.com/intel/cve-bin-tool-action) available to make that easy.  You can also run it within your existing build/test environments.  
+
+We usually assume that the people providing the binaries for scanning will be the same people who set up and control the environment in which they are run.  For example, a normal use case would be an open source project scanning their own generated files as a build check.  We don't really expect people to use this as a forensics tool on a compromised system. (Although if you use it that way, we'd love to hear how that worked for you!)
+
+### Use user-level permissions with appropriate file system access
+
+You should give cve-bin-tool minimal, user-level permissions. The user for cve-bin-tool will need access to the following things:
+
+- Read/write access to a cache directory for storing and reading the vulnerability data (`~/.cache/cve-bin-tool/`).  
+  - Write access is only needed during data updates, which typically run once a day and can be scheduled separately.
+- Read access to the file/directory to be scanned
+- Write access to the system temp directory if extracting files.  
+- Write access to a directory/file for reports, if you want the report in a file and not just printed to the console
+
+You should not run cve-bin-tool as root, not even in a sandbox, container, or virtual machine. You *definitely* do not want to give cve-bin-tool permission to over-write the system binaries it uses for scanning or extracting files such as `strings` or `rpm2cpio`, as those could be used to greatly increase the risk/severity of any issue found in cve-bin-tool or its dependencies.
+
+### Use restrictions on system temp files
+
+CVE-bin-tool will extract a number of different archives into the system temp directory (using the built-in python `tempfile` library) so that it can then examine strings for signature matching.    Although cve-bin-tool parses strings from binaries and doesn't execute code, you may wish to check that your system temp directory has appropriate permissions and behaviours set to limit risk of another process using the extracted file.  As well as basic file permissions, some systems may use namespaces and other tools to further restrict temporary files.
+
+### Schedule data updates separately when running parallel scans
+
+By default cve-bin-tool will check the data sources and update if they are older than 24 hours.  This is fine for a single process but can cause unnecessary churn if multiple processes are being run at the same time.
+
+You can read more information in the how-to guide [Best practices for running multiple scans at once](how_to_guides/multiple_scans_at_once.md).
+
+The update job can be further constrained to have only access to the database cache directory, if you so choose.
+
+### Using cve-bin-tool within a throaway environment
+
+CVE-bin-tool was intended for use as part of continuous integration testing, and many such systems use throwaway containers or virtual machines to mitigate risk.  If you're intending to do this, you will probably want to find a way to store and re-use the vulnerability data, probably by copying it into the "fresh" environment.  
+
+In Github Actions, you can use `actions/cache` to do this.  You can see how we handle caching in [our GitHub Actions cache job](https://github.com/intel/cve-bin-tool/blob/main/.github/workflows/update-cache.yml).  If you're not using Github Actions, you may find it useful to look at the instructions for [using cve-bin-tool offline](how_to_guides/offline.md) as they show the process for separating the download of data and the scan.
+
+### Don't scan arbitrary binary files without additional sandboxing
+
+Periodically, someone suggests creating a service which runs cve-bin-tool and allows users to upload random binaries to the system for analysis.  We don't really recommend this, as getting random binaries from the internet never ends well.  But if you were going to do it, be aware that you'd likely need additional protections similar to any other setup for testing unknown-and-potentially-malicious binaries.  You may want to look at what others have written on how to build a malware analysis lab if you're not sure what sort of protections are needed.
+
+In general, we want people to control their own services for scanning their own binaries.  So rather than running a cve-bin-tool web service for the whole world, we encourage individuals to use the [cve-bin-tool GitHub Action](https://github.com/intel/cve-bin-tool-action) or run it as a check in your existing build/test environment.  
+
 ## Fixing Known Issues / What should I do if it finds something?
 
 The most recommended way to fix a given CVE is to upgrade the package to a