[doc] API

doc/api.rst

@@ -1,12 +1,164 @@
 =======
 MIG API
 =======
+:Author: Julien Vehent <jvehent@mozilla.com>
 
 .. sectnum::
+.. contents:: Table of Contents
 
-The MIG API is a thin layer that allows interactions with the scheduler and
-database over HTTP. It is the primary endpoint used by all clients. The API is
-JSON based, and understand Action and Commands natively. It follows REST
-principle to some extend.
+Interactions between an investigator (a human being) and the MIG platform are
+performed through a REST API. The API exposes functions to create actions,
+retrieve results, and generally monitor the activity of the agents.
 
+The API follows the core principles of REST, and provides discoverable
+endpoints. The document format follows the `Collection+JSON - Hypermedia Type
+<http://amundsen.com/media-types/collection/>`_.
 
+API endpoints
+-------------
+
+The API root is at `/api/v1`. All the endpoints described below are reachable
+behind the root.
+
+GET /dashboard
+~~~~~~~~~~~~~~
+* Description: display a list of the last 10 scheduled actions, with links to
+  the corresponding commands.
+* Parameters: none
+* Example:
+
+.. code:: bash
+
+	$ curl http://localhost:1664/api/v1/dashboard
+
+GET /action
+~~~~~~~~~~~
+* Description: retrieve an action by its ID. Include links to related commands.
+* Parameters:
+	- `actionid`: a uint64 that identifies an action by its ID
+* Example:
+
+.. code:: bash
+
+	curl http://localhost:1664/api/v1/action?actionid=6019232215298562584
+
+GET /command
+~~~~~~~~~~~~
+* Description: retrieve a command by its ID. Include link to related action.
+* Parameters:
+	- `commandid`: a uint64 that identifies a command by its ID
+* Example:
+
+.. code:: bash
+
+	curl http://localhost:1664/api/v1/command?commandid=6019232259520546404
+
+GET /search
+~~~~~~~~~~~
+* Description: search for actions, commands or agents.
+* Parameters:
+	- `before`: return results recorded before this RFC3339 date
+	- `after`: return results recorded after this RFC3339 date"},
+	- `type`: type defines what the search is looking for. must be `action`,
+	  `command` or `agent`
+	- `report`: if set, return results in the given report format (valid for
+	  `command` type only)
+	- `agentname`: filter results on the agent name
+	- `actionname`: filter results on the action name (valid for `command` and
+	  `action` types only)
+	- `status`: filter on internal status (valid for `command` and `agent` only)
+	- `threatfamily`: filter results of the threat family of the action
+	- `limit`: limit the number of results to 10 by default
+
+* Examples:
+
+Generate a compliance report from `compliance` action ran over the last 24
+hours. For more information on the `compliance` format, see section 2.
+
+.. code:: bash
+
+	curl http://localhost:1664/api/v1/search?type=command&threatfamily=compliance&status=done&report=complianceitems&limit=100000&after=2014-05-30T00:00:00-04:00&before=2014-05-30T23:59:59-04:00
+
+List the agents that have sent a heartbeat in the last hour.
+
+.. code:: bash
+
+	curl http://localhost:1664/api/v1/search?type=agent&after=2014-05-30T15:00:00-04:00&limit=200
+
+Find actions ran between two dates (limited to 10 results as is the default).
+
+.. code:: bash
+
+	curl http://localhost:1664/api/v1/search?type=action&status=sent&after=2014-05-01T00:00:00-00:00&before=2014-05-30T00:00:00-00:00
+
+GET /agent/dashboard
+~~~~~~~~~~~~~~~~~~~~
+not implemented
+
+POST /action/create/
+~~~~~~~~~~~~~~~~~~~~
+* Description: send a signed action to the API for submission to the scheduler.
+* Parameters: (POST body)
+	- `action`: a signed action in JSON format
+
+* Example:
+
+.. code:: bash
+
+	./bin/linux/amd64/mig-action-generator -i examples/actions/linux-backdoor.json -k jvehent@mozilla.com -posturl=http://localhost:1664/api/v1/action/create/
+
+POST /action/cancel/
+~~~~~~~~~~~~~~~~~~~~
+not implemented
+
+POST /command/cancel/
+~~~~~~~~~~~~~~~~~~~~~
+not implemented
+
+Data transformation
+-------------------
+The API implements several data transformation functions between the base
+format of `action` and `command`, and reporting formats.
+
+Compliance Items
+~~~~~~~~~~~~~~~~
+The compliance item format is used to measure the compliance of a target with
+particular requirement. A single compliance item represent the compliance of
+one target (host) with one check (test + value).
+
+In MIG, an `action` can contain compliance checks. An `action` creates one
+`command` per `agent`. Upon completion, the agent stores the results in the
+`command.results`. To visualize the results of an action, an investigator must
+look at the results of each command generated by that action.
+
+To generate compliance items, the API takes the results from commands, and
+creates one item per result. Therefore, a single action that creates hundreds of
+commands could, in turn, generate thousands of compliance items.
+
+The format for compliance items is simple, to be easily graphed and aggregated.
+
+.. code:: javascript
+
+	{
+		"target": "server1.prod.example.net",
+		"policy": {
+			"level": "medium",
+			"name": "system",
+			"url": "https://link.to.compliance.reference/index.html"
+		},
+		"check": {
+			"description": "compliance check for openssh",
+			"location": "/etc/ssh/sshd_config",
+			"name": "check for verbose logging (logs fingerprints)",
+			"test": {
+				"type": "regex",
+				"value": "(?i)^loglevel verbose$"
+			}
+		},
+		"compliance": true,
+		"link": "http://localhost:1664/api/v1/command?commandid=6019232265601776819",
+		"timestamp": "2014-05-30T14:55:41.907745Z"
+	}
+
+When using the parameter `&report=complianceitems`, the `search` endpoint of the API
+will generate a list of compliance items from the results of the search.