From 7aa65f4d22d388dbf1b2f7c2f3a78cdcd7bdf35e Mon Sep 17 00:00:00 2001
From: dlavigne <dru@freebsd.org>
Date: Mon, 28 Mar 2016 11:40:20 -0400
Subject: [PATCH] Doc the pkg_audit action.

---
 api/classes/pkg.rst | 58 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 54 insertions(+), 4 deletions(-)

diff --git a/api/classes/pkg.rst b/api/classes/pkg.rst
index 7faeba2..7b579f7 100644
--- a/api/classes/pkg.rst
+++ b/api/classes/pkg.rst
@@ -20,7 +20,7 @@ Every pkg class request contains the following parameters:
 | namespace                       | sysadm        |                                                                                                                      |
 |                                 |               |                                                                                                                      |
 +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
-| action                          |               | supported actions include "pkg_info", "pkg_search", "list_categories", "list_repos"                                  |
+| action                          |               | supported actions include "pkg_info", "pkg_search", "list_categories", "list_repos", "pkg_audit"                     |
 |                                 |               |                                                                                                                      |
 +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+
 
@@ -233,7 +233,7 @@ The "pkg_search" action searches the package database for pkgs which match the g
 
 .. code-block:: json
 
-PUT /sysadm/pkg
+ PUT /sysadm/pkg
  {
    "repo" : "pcbsd-major",
    "category" : "www",
@@ -401,8 +401,7 @@ PUT /sysadm/pkg
 List Categories
 ===============
 
-The "list_categories" action lists all the known categories within the specified repository or, if no repository is specified, the local repository. Note that just because a category is
-listed, it does not mean that any packages exist within that category.
+The "list_categories" action lists all the known, non-empty categories within the specified repository or, if no repository is specified, the local repository.
 
 **REST Request**
 
@@ -539,4 +538,55 @@ action are valid as the optional "repo" argument for the other pkg API actions.
   "id": "fooid",
   "name": "response",
   "namespace": "sysadm"
+ }
+ 
+.. index:: pkg_audit, pkg
+
+.. _Audit Packages:
+
+Audit Packages
+==============
+
+The "pkg_audit" action performs an audit of all installed packages and reports any packages with known vulnerabilities as well as other packages which are impacted by those vulnerabilities. 
+
+.. note:: the vulnerability information will be returned as a dispatcher event as this action just queues up the results of the :command:`pkg` operation. This is due to a limitation of
+   :command:`pkg`, as it only supports one process call at a time. Refer to the :ref:`Dispatcher Subsystem` for instructions on how to subscribe to and query dispatcher events.
+
+**REST Request**
+
+.. code-block:: json
+
+ PUT /sysadm/pkg
+ {
+   "action" : "pkg_audit"
+ }
+
+**WebSocket Request**
+
+.. code-block:: json
+
+ {
+   "args" : {
+      "action" : "pkg_audit"
+   },
+   "name" : "pkg",
+   "id" : "fooid",
+   "namespace" : "sysadm"
+ }
+
+**Response**
+
+.. code-block:: json
+
+ {
+  "args": {
+    "pkg_audit": {
+      "proc_cmd": "pkg audit -qr",
+      "proc_id": "sysadm_pkg_audit-{257cc46b-9178-4990-810a-12416ddfad79}",
+      "status": "pending"
+    }
+  },
+  "id": "fooid",
+  "name": "response",
+  "namespace": "sysadm"
  }
\ No newline at end of file