From dc431c22f34660746e7efa19d86cd846b1272b70 Mon Sep 17 00:00:00 2001 From: Jimmy Zelinskie Date: Tue, 23 Feb 2016 18:43:11 -0500 Subject: [PATCH] v1: add readme --- api/v1/README.md | 576 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 576 insertions(+) create mode 100644 api/v1/README.md diff --git a/api/v1/README.md b/api/v1/README.md new file mode 100644 index 00000000..0b33632f --- /dev/null +++ b/api/v1/README.md @@ -0,0 +1,576 @@ +# Clair v1 API + +- [Error Handling](#error-handling) +- [Layers](#layers) + - [POST](#post-layers) + - [GET](get-layersname) + - [DELETE](#delete-layersname) +- [Namespaces](#namespaces) + - [GET](#get-namespaces) +- [Vulnerabilities](#vulnerabilities) + - [POST](#post-namespacesnamevulnerabilities) + - [GET](#get-namespacesnsnamevulnerabilitiesvulnname) + - [PUT](#put-namespacesnsnamevulnerabilitiesvulnname) + - [DELETE](#delete-namespacesnsnamevulnerabilitiesvulnname) +- [Fixes](#fixes) + - [GET](#get-namespacesnsnamevulnerabilitiesvulnnamefixes) + - [PUT](#put-namespacesnsnamevulnerabilitiesvulnnamefixesfeaturename) + - [DELETE](#delete-namespacesnsnamevulnerabilitiesvulnnamefixesfeaturename) +- [Notifications](#notifications) + - [GET](#get-notificationsname) + - [DELETE](#delete-notificationname) + +## Error Handling + +###### Description + +Every route can optionally provide an `Error` property on the response object. +The HTTP status code of the response should indicate what type of failure occurred and how the client should reaction. + +###### Client Retry Behavior + +| Code | Name | Retry Behavior | +|------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| +| 400 | Bad Request | The body of the request invalid. The request must be changed before being retried. | +| 404 | Not Found | The requested resource could not be found. The request must be changed before being retried. | +| 422 | Unprocessable Entity | The request body is valid, but lacks a pre-condition. This request should be retried eventually, but retrying it immediately will yield no progress. | +| 500 | Internal Server Error | The server encountered an error while processing the request. This request should be retried without change. | + +###### Example Response + +```json +HTTP/1.1 400 Bad Request +Content-Type: application/json;charset=utf-8 +Server: clair + +{ + "Error": { + "Message": "example error message" + } +} +``` + +## Layers + +#### POST /layers + +###### Description + +The POST route for the Layers resource performs the indexing of a Layer from the provided path and displays the provided Layer with an updated `IndexByVersion` property. +This request blocks for the entire duration of the downloading and indexing of the layer. + +###### Example Request + +```json +POST http://localhost:6060/v1/layers HTTP/1.1 + +{ + "Layer": { + "Name": "523ef1d23f222195488575f52a39c729c76a8c5630c9a194139cb246fb212da6", + "Path": "/mnt/layers/523ef1d23f222195488575f52a39c729c76a8c5630c9a194139cb246fb212da6/layer.tar", + "ParentName": "140f9bdfeb9784cf8730e9dab5dd12fbd704151cf555ac8cae650451794e5ac2", + "Format": "Docker" + } +} +``` + +###### Example Response + +```json +HTTP/1.1 201 Created +Content-Type: application/json;charset=utf-8 +Server: clair + +{ + "Layer": { + "Name": "523ef1d23f222195488575f52a39c729c76a8c5630c9a194139cb246fb212da6", + "Path": "/mnt/layers/523ef1d23f222195488575f52a39c729c76a8c5630c9a194139cb246fb212da6/layer.tar", + "ParentName": "140f9bdfeb9784cf8730e9dab5dd12fbd704151cf555ac8cae650451794e5ac2", + "Format": "Docker", + "IndexedByVersion": 1 + } +} +``` + +#### GET /layers/`:name` + +###### Description + +The GET route for the Layers resource displays a Layer and optionally all of its features and vulnerabilities. + +###### Query Parameters + +| Name | Type | Required | Description | +|-----------------|------|----------|-------------------------------------------------------------------------------| +| features | bool | optional | Displays the list of features indexed in this layer and all of its parents. | +| vulnerabilities | bool | optional | Displays the list of vulnerabilities along with the features described above. | + +###### Example Request + +``` +GET http://localhost:6060/v1/layers/17675ec01494d651e1ccf81dc9cf63959ebfeed4f978fddb1666b6ead008ed52?features&vulnerabilities HTTP/1.1 +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Content-Type: application/json;charset=utf-8 +Server: clair + +{ + "Layer": { + "Name": "17675ec01494d651e1ccf81dc9cf63959ebfeed4f978fddb1666b6ead008ed52", + "Namespace": "debian:8", + "ParentName": "140f9bdfeb9784cf8730e9dab5dd12fbd704151cf555ac8cae650451794e5ac2", + "IndexedByVersion": 1, + "Features": [ + { + "Name": "coreutils", + "Namespace": "debian:8", + "Version": "8.23-4", + "Vulnerabilities": [ + { + "Name": "CVE-2014-9471", + "Namespace": "debian:8", + "Description": "The parse_datetime function in GNU coreutils allows remote attackers to cause a denial of service (crash) or possibly execute arbitrary code via a crafted date string, as demonstrated by the \"--date=TZ=\"123\"345\" @1\" string to the touch or date command.", + "Link": "https://security-tracker.debian.org/tracker/CVE-2014-9471", + "Severity": "Low", + "FixedBy": "9.23-5" + } + ] + } + ] + } +} +``` + +#### DELETE /layers/`:name` + +###### Description + +The DELETE route for the Layers resource removes a Layer and all of its children from the database. + +###### Example Request + +```json +DELETE http://localhost:6060/v1/layers/17675ec01494d651e1ccf81dc9cf63959ebfeed4f978fddb1666b6ead008ed52 HTTP/1.1 +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Server: clair +``` + + +## Namespaces + +#### GET /namespaces + +###### Description + +The GET route for the Namespaces resource displays a list of namespaces currently being managed. + +###### Example Request + +```json +GET http://localhost:6060/v1/namespaces HTTP/1.1 +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Content-Type: application/json;charset=utf-8 +Server: clair + +{ + "Namespaces": [ + "debian:8", + "debian:9" + ] +} +``` + +## Vulnerabilities + +#### POST /namespaces/`:name`/vulnerabilities + +###### Description + +The POST route for the Vulnerabilities resource creates a new Vulnerability. + +###### Example Request + +```json +POST /namespaces/debian%3A8/vulnerabilities HTTP/1.1 + +{ + "Vulnerability": { + "Name": "CVE-2014-9471", + "Namespace": "debian:8", + "Link": "https://security-tracker.debian.org/tracker/CVE-2014-9471", + "Description": "The parse_datetime function in GNU coreutils allows remote attackers to cause a denial of service (crash) or possibly execute arbitrary code via a crafted date string, as demonstrated by the \"--date=TZ=\"123\"345\" @1\" string to the touch or date command.", + "Severity": "Low", + "Metadata": { + "NVD": { + "CVSSv2": { + "Score": 7.5, + "Vectors": "AV:N/AC:L/Au:N/C:P/I:P" + } + } + }, + "FixedIn": [ + { + "Name": "coreutils", + "Namespace": "debian:8", + "Version": "8.23-1" + } + ] + } +} +``` + +###### Example Response + +```json +HTTP/1.1 201 Created +Content-Type: application/json;charset=utf-8 +Server: clair + +{ + "Vulnerability": { + "Name": "CVE-2014-9471", + "Namespace": "debian:8", + "Link": "https://security-tracker.debian.org/tracker/CVE-2014-9471", + "Description": "The parse_datetime function in GNU coreutils allows remote attackers to cause a denial of service (crash) or possibly execute arbitrary code via a crafted date string, as demonstrated by the \"--date=TZ=\"123\"345\" @1\" string to the touch or date command.", + "Severity": "Low", + "Metadata": { + "NVD": { + "CVSSv2": { + "Score": 7.5, + "Vectors": "AV:N/AC:L/Au:N/C:P/I:P" + } + } + }, + "FixedIn": [ + { + "Name": "coreutils", + "Namespace": "debian:8", + "Version": "8.23-1" + } + ] + } +} +``` + +#### GET /namespaces/`:nsName`/vulnerabilities/`:vulnName` + +###### Description + +The GET route for the Vulnerabilities resource displays the current data for a given vulnerability and optionally the features that fix it. + +###### Query Parameters + +| Name | Type | Required | Description | +|---------|------|----------|------------------------------------------------------------| +| fixedIn | bool | optional | Displays the list of features that fix this vulnerability. | + +###### Example Request + +```json +GET /namespaces/debian%3A8/vulnerabilities/CVE-2014-9471?fixedIn HTTP/1.1 +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Content-Type: application/json;charset=utf-8 +Server: clair + +{ + "Vulnerability": { + "Name": "CVE-2014-9471", + "Namespace": "debian:8", + "Link": "https://security-tracker.debian.org/tracker/CVE-2014-9471", + "Description": "The parse_datetime function in GNU coreutils allows remote attackers to cause a denial of service (crash) or possibly execute arbitrary code via a crafted date string, as demonstrated by the \"--date=TZ=\"123\"345\" @1\" string to the touch or date command.", + "Severity": "Low", + "Metadata": { + "NVD": { + "CVSSv2": { + "Score": 7.5, + "Vectors": "AV:N/AC:L/Au:N/C:P/I:P" + } + } + }, + "FixedIn": [ + { + "Name": "coreutils", + "Namespace": "debian:8", + "Version": "8.23-1" + } + ] + } +} +``` + +#### PUT /namespaces/`:nsName`/vulnerabilities/`:vulnName` + +###### Description + +The PUT route for the Vulnerabilities resource updates a given Vulnerability. +The "FixedIn" property of the Vulnerability must be empty or missing. +Fixes should be managed by the Fixes resource. +If this vulnerability was inserted by a Fetcher, changes may be lost when the Fetcher updates. + +###### Example Request + +```json +PUT http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471 + +{ + "Vulnerability": { + "Name": "CVE-2014-9471", + "Namespace": "debian:8", + "Link": "https://security-tracker.debian.org/tracker/CVE-2014-9471", + "Description": "The parse_datetime function in GNU coreutils allows remote attackers to cause a denial of service (crash) or possibly execute arbitrary code via a crafted date string, as demonstrated by the \"--date=TZ=\"123\"345\" @1\" string to the touch or date command.", + "Severity": "Low", + "Metadata": { + "NVD": { + "CVSSv2": { + "Score": 7.5, + "Vectors": "AV:N/AC:L/Au:N/C:P/I:P" + } + } + } + } +} +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Server: clair + +{ + "Vulnerability": { + "Name": "CVE-2014-9471", + "Namespace": "debian:8", + "Link": "https://security-tracker.debian.org/tracker/CVE-2014-9471", + "Description": "The parse_datetime function in GNU coreutils allows remote attackers to cause a denial of service (crash) or possibly execute arbitrary code via a crafted date string, as demonstrated by the \"--date=TZ=\"123\"345\" @1\" string to the touch or date command.", + "Severity": "Low", + "Metadata": { + "NVD": { + "CVSSv2": { + "Score": 7.5, + "Vectors": "AV:N/AC:L/Au:N/C:P/I:P" + } + } + } + } +} +``` + + +#### DELETE /namespaces/`:nsName`/vulnerabilities/`:vulnName` + +###### Description + +The DELETE route for the Vulnerabilities resource deletes a given Vulnerability. +If this vulnerability was inserted by a Fetcher, it may be re-inserted when the Fetcher updates. + +###### Example Request + +```json +GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471 HTTP/1.1 +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Server: clair +``` + +## Fixes + +#### GET /namespaces/`:nsName`/vulnerabilities/`:vulnName`/fixes + +###### Description + +The GET route for the Fixes resource displays the list of Features that fix the given Vulnerability. + +###### Example Request + +```json +GET http://localhost:6060/v1/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes HTTP/1.1 +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Content-Type: application/json;charset=utf-8 +Server: clair + +{ + "Features": [ + { + "Name": "coreutils", + "Namespace": "debian:8", + "Version": "8.23-1" + } + ] +} +``` + +#### PUT /namespaces/`:nsName`/vulnerabilities/`:vulnName`/fixes/`:featureName` + +###### Description + +The PUT route for the Fixes resource updates a Feature that is the fix for a given Vulnerability. + +###### Example Request + +```json +PUT http://localhost:6060/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes/coreutils HTTP/1.1 + +{ + "Feature": { + "Name": "coreutils", + "Namespace": "debian:8", + "Version": "4.24-9" + } +} +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Server: clair + +{ + "Feature": { + "Name": "coreutils", + "Namespace": "debian:8", + "Version": "4.24-9" + } +} +``` + +#### DELETE /namespaces/`:nsName`/vulnerabilities/`:vulnName`/fixes/`:featureName` + +###### Description + +The DELETE route for the Fixes resource removes a Feature as fix for the given Vulnerability. + +###### Example Request + +```json +DELETE http://localhost:6060/namespaces/debian%3A8/vulnerabilities/CVE-2014-9471/fixes/coreutils +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Server: clair +``` + +## Notifications + +#### GET /notifications/`:name` + +###### Description + +The GET route for the Notifications resource displays a notification that a Vulnerability has been updated. +This route supports simultaneous pagination for both the `Old` and `New` Vulnerabilities' `LayersIntroducingVulnerability` property which can be extremely long. + +###### Query Parameters + +| Name | Type | Required | Description | +|-------|--------|----------|---------------------------------------------------------------------------------------------------------------| +| page | string | optional | Displays the specific page of the "LayersIntroducingVulnerability" property on New and Old vulnerabilities. | +| limit | int | optional | Limits the amount of results in the "LayersIntroducingVulnerability" property on New and Old vulnerabilities. | + +###### Example Request + +```json +GET http://localhost:6060/v1/notifications/ec45ec87-bfc8-4129-a1c3-d2b82622175a?limit=2 HTTP/1.1 +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Content-Type: application/json;charset=utf-8 +Server: clair + +{ + "Notification": { + "Name": "ec45ec87-bfc8-4129-a1c3-d2b82622175a", + "Created": "1456247389", + "Notified": "1456246708", + "Limit": 2, + "Page": "gAAAAABWzJaC2JCH6Apr_R1f2EkjGdibnrKOobTcYXBWl6t0Cw6Q04ENGIymB6XlZ3Zi0bYt2c-2cXe43fvsJ7ECZhZz4P8C8F9efr_SR0HPiejzQTuG0qAzeO8klogFfFjSz2peBvgP", + "NextPage": "gAAAAABWzJaCTyr6QXP2aYsCwEZfWIkU2GkNplSMlTOhLJfiR3LorBv8QYgEIgyOvZRmHQEzJKvkI6TP2PkRczBkcD17GE89btaaKMqEX14yHDgyfQvdasW1tj3-5bBRt0esKi9ym5En", + "New": { + "Vulnerability": { + "Name": "CVE-TEST", + "Namespace": "debian:8", + "Description": "New CVE", + "Severity": "Low", + "FixedIn": [ + { + "Name": "grep", + "Namespace": "debian:8", + "Version": "2.25" + } + ] + }, + "LayersIntroducingVulnerability": [ + "3b59c795b34670618fbcace4dac7a27c5ecec156812c9e2c90d3f4be1916b12d.9673fdf7-b81a-4b3e-acf8-e551ef155449", + "523ef1d23f222195488575f52a39c729c76a8c5630c9a194139cb246fb212da6" + ] + }, + "Old": { + "Vulnerability": { + "Name": "CVE-TEST", + "Namespace": "debian:8", + "Description": "New CVE", + "Severity": "Low", + "FixedIn": [] + }, + "LayersIntroducingVulnerability": [ + "3b59c795b34670618fbcace4dac7a27c5ecec156812c9e2c90d3f4be1916b12d.9673fdf7-b81a-4b3e-acf8-e551ef155449", + "523ef1d23f222195488575f52a39c729c76a8c5630c9a194139cb246fb212da6" + ] + } + } +} +``` + +#### DELETE /notification/`:name` + +###### Description + +The delete route for the Notifications resource marks a Notification as read. +The time at which this Notification was marked as read can be seen in the `Notified` property of the response GET route for Notification. + +###### Example Request + +```json +DELETE http://localhost:6060/v1/notification/ec45ec87-bfc8-4129-a1c3-d2b82622175a HTTP/1.1 +``` + +###### Example Response + +```json +HTTP/1.1 200 OK +Server: clair +```