mig/doc/api.rst

=======
MIG API
=======
:Author: Julien Vehent <jvehent@mozilla.com>

.. sectnum::
.. contents:: Table of Contents

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.