audit: Add docs

PR-URL: #20389
Credit: @iarna
Reviewed-By: @zkat

doc/cli/npm-audit.md

@@ -0,0 +1,43 @@
+npm-audit(1) -- Run a security audit
+====================================
+
+## SYNOPSIS
+
+    npm audit 
+
+## DESCRIPTION 
+
+The audit command submits a description of the dependencies configured in
+your project to your default registry and asks for a report of known
+vulnerabilities.  The report returned includes instructions on how to act on
+this information.
+
+## CONTENT SUBMITTED
+
+* npm_version
+* node_version
+* platform
+* node_env
+* A scrubbed version of your package-lock.json or npm-shrinkwrap.json
+
+### SCRUBBING
+
+In order to ensure that potentially sensitive information is not included in
+the audit data bundle, some dependencies may have their names (and sometimes
+versions) replaced with opaque non-reversible identifiers.  It is done for
+the following dependency types:
+
+* Any module referencing a scope that is configured for a non-default
+  registry has its name scrubbed.  (That is, a scope you did a `npm login --scope=@ourscope` for.)
+* All git dependencies have their names and specifiers scrubbed. 
+* All remote tarball dependencies have their names and specifiers scrubbed.
+* All local directory and tarball dependencies have their names and specifiers scrubbed.
+
+The non-reversible identifiers are a sha256 of a session-specific UUID and the
+value being replaced, ensuring a consistent value within the payload that is
+different between runs.
+
+## SEE ALSO
+
+* npm-install(1)
+* config(7)

doc/cli/npm-install.md

@@ -359,6 +359,9 @@ node source code so that npm can compile native modules.
 The `--only={prod[uction]|dev[elopment]}` argument will cause either only
 `devDependencies` or only non-`devDependencies` to be installed regardless of the `NODE_ENV`.
 
+The `--no-audit` argument can be used to disable sending of audit reports to
+the configured registries.  See `npm-audit(1)` for details on what is sent.
+
 See `npm-config(7)`.  Many of the configuration params have some
 effect on installation, since that's most of what npm does.
 
@@ -434,6 +437,7 @@ affects a real use-case, it will be investigated.
 
 * npm-folders(5)
 * npm-update(1)
+* npm-audit(1)
 * npm-link(1)
 * npm-rebuild(1)
 * npm-scripts(7)

doc/misc/npm-config.md

@@ -155,6 +155,15 @@ even for `GET` requests.
 When "dev" or "development" and running local `npm shrinkwrap`,
 `npm outdated`, or `npm update`, is an alias for `--dev`.
 
+### audit
+
+* Default: true
+* Type: Boolean
+
+When "true" submit audit reports alongside `npm install` runs to the default
+registry and all registries configured for scopes.  See the documentation
+for npm-audit(1) for details on what is submitted.
+
 ### auth-type
 
 * Default: `'legacy'`