title: ClairV4 v0.1 language_tabs:

  • python: Python
  • go: Golang
  • javascript: Javascript language_clients:
  • python: ""
  • go: ""
  • javascript: "" toc_footers: [] includes: [] search: false highlight_theme: darkula headingLevel: 2

ClairV4 v0.1

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

ClairV4 is a set of cooperating microservices which scan, index, and match your container's content with known vulnerabilities.

Email: Clair Team Web: Clair Team License: Apache License 2.0

Notifier

DeleteNotification

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.delete('/notifier/api/v1/notification/{notification_id}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("DELETE", "/notifier/api/v1/notification/{notification_id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}


const headers = {
  'Accept':'application/json'
};

fetch('/notifier/api/v1/notification/{notification_id}',
{
  method: 'DELETE',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE notifier/api/v1/notification/{notification_id}

Issues a delete of the provided notification id and all associated notifications. After this delete clients will no longer be able to retrieve notifications.

Parameters

NameInTypeRequiredDescription
notification_idpathstringfalseA notification ID returned by a callback

Example responses

400 Response

{
  "code": "string",
  "message": "string"
}

Responses

StatusMeaningDescriptionSchema
200OKOKNone
400Bad RequestBad RequestError
405Method Not AllowedMethod Not AllowedError
500Internal Server ErrorInternal Server ErrorError

Retrieve a paginated result of notifications for the provided id.

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/notifier/api/v1/notification/{notification_id}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/notifier/api/v1/notification/{notification_id}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}


const headers = {
  'Accept':'application/json'
};

fetch('/notifier/api/v1/notification/{notification_id}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET notifier/api/v1/notification/{notification_id}

By performing a GET with a notification_id as a path parameter, the client will retrieve a paginated response of notification objects.

Parameters

NameInTypeRequiredDescription
notification_idpathstringfalseA notification ID returned by a callback
page_sizequeryintfalseThe maximum number of notifications to deliver in a single page.
nextquerystringfalseThe next page to fetch via id. Typically this number is provided

Detailed descriptions

page_size: The maximum number of notifications to deliver in a single page.

next: The next page to fetch via id. Typically this number is provided on initial response in the page.next field. The first GET request may omit this field.

Example responses

200 Response

{
  "page": {
    "size": 100,
    "next": "1b4d0db2-e757-4150-bbbb-543658144205"
  },
  "notifications": [
    {
      "id": "5e4b387e-88d3-4364-86fd-063447a6fad2",
      "manifest": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
      "reason": "added",
      "vulnerability": {
        "name": "CVE-2009-5155",
        "fixed_in_version": "v0.0.1",
        "links": "http://link-to-advisory",
        "description": "In the GNU C Library (aka glibc or libc6) before 2.28,\nparse_reg_exp in posix/regcomp.c misparses alternatives,\nwhich allows attackers to cause a denial of service (assertion\nfailure and application exit) or trigger an incorrect result\nby attempting a regular-expression match.\"\n",
        "normalized_severity": "Unknown",
        "package": {
          "id": "10",
          "name": "libapt-pkg5.0",
          "version": "1.6.11",
          "kind": "binary",
          "normalized_version": "",
          "arch": "x86",
          "module": "",
          "cpe": "",
          "source": {
            "id": "9",
            "name": "apt",
            "version": "1.6.11",
            "kind": "source",
            "source": null
          }
        },
        "distribution": {
          "id": "1",
          "did": "ubuntu",
          "name": "Ubuntu",
          "version": "18.04.3 LTS (Bionic Beaver)",
          "version_code_name": "bionic",
          "version_id": "18.04",
          "arch": "",
          "cpe": "",
          "pretty_name": "Ubuntu 18.04.3 LTS"
        },
        "repository": {
          "id": "string",
          "name": "string",
          "key": "string",
          "uri": "string",
          "cpe": "string"
        }
      }
    }
  ]
}

Responses

StatusMeaningDescriptionSchema
200OKA paginated list of notificationsPagedNotifications
400Bad RequestBad RequestError
405Method Not AllowedMethod Not AllowedError
500Internal Server ErrorInternal Server ErrorError

Indexer

Index the contents of a Manifest

Code samples

import requests
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json'
}

r = requests.post('/indexer/api/v1/index_report', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Content-Type": []string{"application/json"},
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/indexer/api/v1/index_report", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

const inputBody = '{
  "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
  "layers": [
    {
      "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
      "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36\n",
      "headers": {
        "property1": [
          "string"
        ],
        "property2": [
          "string"
        ]
      }
    }
  ]
}';
const headers = {
  'Content-Type':'application/json',
  'Accept':'application/json'
};

fetch('/indexer/api/v1/index_report',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST indexer/api/v1/index_report

By submitting a Manifest object to this endpoint Clair will fetch the layers, scan each layer's contents, and provide an index of discovered packages, repository and distribution information.

Body parameter

{
  "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
  "layers": [
    {
      "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
      "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36\n",
      "headers": {
        "property1": [
          "string"
        ],
        "property2": [
          "string"
        ]
      }
    }
  ]
}

Parameters

NameInTypeRequiredDescription
bodybodyManifesttruenone

Example responses

201 Response

{
  "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
  "state": "IndexFinished",
  "packages": {
    "10": {
      "id": "10",
      "name": "libapt-pkg5.0",
      "version": "1.6.11",
      "kind": "binary",
      "normalized_version": "",
      "arch": "x86",
      "module": "",
      "cpe": "",
      "source": {
        "id": "9",
        "name": "apt",
        "version": "1.6.11",
        "kind": "source",
        "source": null
      }
    }
  },
  "distributions": {
    "1": {
      "id": "1",
      "did": "ubuntu",
      "name": "Ubuntu",
      "version": "18.04.3 LTS (Bionic Beaver)",
      "version_code_name": "bionic",
      "version_id": "18.04",
      "arch": "",
      "cpe": "",
      "pretty_name": "Ubuntu 18.04.3 LTS"
    }
  },
  "environments": {
    "10": [
      {
        "package_db": "var/lib/dpkg/status",
        "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
        "distribution_id": "1"
      }
    ]
  },
  "success": true,
  "err": ""
}

Responses

StatusMeaningDescriptionSchema
201CreatedIndexReport CreatedIndexReport
400Bad RequestBad RequestError
405Method Not AllowedMethod Not AllowedError
500Internal Server ErrorInternal Server ErrorError

Retrieve an IndexReport for the given Manifest hash if exists.

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/indexer/api/v1/index_report/{manifest_hash}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/indexer/api/v1/index_report/{manifest_hash}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}


const headers = {
  'Accept':'application/json'
};

fetch('/indexer/api/v1/index_report/{manifest_hash}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET indexer/api/v1/index_report/{manifest_hash}

Given a Manifest's content addressable hash an IndexReport will be retrieved if exists.

Parameters

NameInTypeRequiredDescription
manifest_hashpathDigesttrueA digest of a manifest that has been indexed previous to this

Detailed descriptions

manifest_hash: A digest of a manifest that has been indexed previous to this request.

Example responses

200 Response

{
  "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
  "state": "IndexFinished",
  "packages": {
    "10": {
      "id": "10",
      "name": "libapt-pkg5.0",
      "version": "1.6.11",
      "kind": "binary",
      "normalized_version": "",
      "arch": "x86",
      "module": "",
      "cpe": "",
      "source": {
        "id": "9",
        "name": "apt",
        "version": "1.6.11",
        "kind": "source",
        "source": null
      }
    }
  },
  "distributions": {
    "1": {
      "id": "1",
      "did": "ubuntu",
      "name": "Ubuntu",
      "version": "18.04.3 LTS (Bionic Beaver)",
      "version_code_name": "bionic",
      "version_id": "18.04",
      "arch": "",
      "cpe": "",
      "pretty_name": "Ubuntu 18.04.3 LTS"
    }
  },
  "environments": {
    "10": [
      {
        "package_db": "var/lib/dpkg/status",
        "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
        "distribution_id": "1"
      }
    ]
  },
  "success": true,
  "err": ""
}

Responses

StatusMeaningDescriptionSchema
200OKIndexReport retrievedIndexReport
400Bad RequestBad RequestError
404Not FoundNot FoundError
405Method Not AllowedMethod Not AllowedError
500Internal Server ErrorInternal Server ErrorError

Report the indexer's internal configuration and state.

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/indexer/api/v1/index_state', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/indexer/api/v1/index_state", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}


const headers = {
  'Accept':'application/json'
};

fetch('/indexer/api/v1/index_state',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET indexer/api/v1/index_state

The index state endpoint returns a json structure indicating the indexer's internal configuration state.

A client may be interested in this as a signal that manifests may need to be re-indexed.

Example responses

200 Response

{
  "state": "aae368a064d7c5a433d0bf2c4f5554cc"
}

Responses

StatusMeaningDescriptionSchema
200OKIndexer StateState
304Not ModifiedIndexer State UnchangedNone

Response Headers

StatusHeaderTypeFormatDescription
200EtagstringEntity Tag

Matcher

Retrieve a VulnerabilityReport for a given manifest's content

addressable hash.

Code samples

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('/matcher/api/v1/vulnerability_report/{manifest_hash}', headers = headers)

print(r.json())

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/matcher/api/v1/vulnerability_report/{manifest_hash}", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}


const headers = {
  'Accept':'application/json'
};

fetch('/matcher/api/v1/vulnerability_report/{manifest_hash}',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET matcher/api/v1/vulnerability_report/{manifest_hash}

Given a Manifest's content addressable hash a VulnerabilityReport will be created. The Manifest must have been Indexed first via the Index endpoint.

Parameters

NameInTypeRequiredDescription
manifest_hashpathDigesttrueA digest of a manifest that has been indexed previous to this

Detailed descriptions

manifest_hash: A digest of a manifest that has been indexed previous to this request.

Example responses

201 Response

{
  "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
  "packages": {
    "10": {
      "id": "10",
      "name": "libapt-pkg5.0",
      "version": "1.6.11",
      "kind": "binary",
      "normalized_version": "",
      "arch": "x86",
      "module": "",
      "cpe": "",
      "source": {
        "id": "9",
        "name": "apt",
        "version": "1.6.11",
        "kind": "source",
        "source": null
      }
    }
  },
  "distributions": {
    "1": {
      "id": "1",
      "did": "ubuntu",
      "name": "Ubuntu",
      "version": "18.04.3 LTS (Bionic Beaver)",
      "version_code_name": "bionic",
      "version_id": "18.04",
      "arch": "",
      "cpe": "",
      "pretty_name": "Ubuntu 18.04.3 LTS"
    }
  },
  "environments": {
    "10": [
      {
        "package_db": "var/lib/dpkg/status",
        "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
        "distribution_id": "1"
      }
    ]
  },
  "vulnerabilities": {
    "356835": {
      "id": "356835",
      "updater": "",
      "name": "CVE-2009-5155",
      "description": "In the GNU C Library (aka glibc or libc6) before 2.28,\nparse_reg_exp in posix/regcomp.c misparses alternatives,\nwhich allows attackers to cause a denial of service (assertion\nfailure and application exit) or trigger an incorrect result\nby attempting a regular-expression match.\"\n",
      "links": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-5155\nhttp://people.canonical.com/~ubuntu-security/cve/2009/CVE-2009-5155.html\nhttps://sourceware.org/bugzilla/show_bug.cgi?id=11053\nhttps://debbugs.gnu.org/cgi/bugreport.cgi?bug=22793\nhttps://debbugs.gnu.org/cgi/bugreport.cgi?bug=32806\nhttps://debbugs.gnu.org/cgi/bugreport.cgi?bug=34238\nhttps://sourceware.org/bugzilla/show_bug.cgi?id=18986\"\n",
      "severity": "Low",
      "normalized_severity": "Low",
      "package": {
        "id": "0",
        "name": "glibc",
        "version": "",
        "kind": "",
        "source": null,
        "package_db": "",
        "repository_hint": ""
      },
      "dist": {
        "id": "0",
        "did": "ubuntu",
        "name": "Ubuntu",
        "version": "18.04.3 LTS (Bionic Beaver)",
        "version_code_name": "bionic",
        "version_id": "18.04",
        "arch": "",
        "cpe": "",
        "pretty_name": ""
      },
      "repo": {
        "id": "0",
        "name": "Ubuntu 18.04.3 LTS",
        "key": "",
        "uri": ""
      },
      "issued": "2019-10-12T07:20:50.52Z",
      "fixed_in_version": "2.28-0ubuntu1"
    }
  },
  "package_vulnerabilities": {
    "10": [
      "356835"
    ]
  }
}

Responses

StatusMeaningDescriptionSchema
201CreatedVulnerabilityReport CreatedVulnerabilityReport
400Bad RequestBad RequestError
404Not FoundNot FoundError
405Method Not AllowedMethod Not AllowedError
500Internal Server ErrorInternal Server ErrorError

Schemas

Page

{
  "size": 1,
  "next": "1b4d0db2-e757-4150-bbbb-543658144205"
}

Page

Properties

NameTypeRequiredRestrictionsDescription
sizeintfalsenoneThe maximum number of elements in a page
nextstringfalsenoneThe next id to submit to the api to continue paging

PagedNotifications

{
  "page": {
    "size": 100,
    "next": "1b4d0db2-e757-4150-bbbb-543658144205"
  },
  "notifications": [
    {
      "id": "5e4b387e-88d3-4364-86fd-063447a6fad2",
      "manifest": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
      "reason": "added",
      "vulnerability": {
        "name": "CVE-2009-5155",
        "fixed_in_version": "v0.0.1",
        "links": "http://link-to-advisory",
        "description": "In the GNU C Library (aka glibc or libc6) before 2.28,\nparse_reg_exp in posix/regcomp.c misparses alternatives,\nwhich allows attackers to cause a denial of service (assertion\nfailure and application exit) or trigger an incorrect result\nby attempting a regular-expression match.\"\n",
        "normalized_severity": "Unknown",
        "package": {
          "id": "10",
          "name": "libapt-pkg5.0",
          "version": "1.6.11",
          "kind": "binary",
          "normalized_version": "",
          "arch": "x86",
          "module": "",
          "cpe": "",
          "source": {
            "id": "9",
            "name": "apt",
            "version": "1.6.11",
            "kind": "source",
            "source": null
          }
        },
        "distribution": {
          "id": "1",
          "did": "ubuntu",
          "name": "Ubuntu",
          "version": "18.04.3 LTS (Bionic Beaver)",
          "version_code_name": "bionic",
          "version_id": "18.04",
          "arch": "",
          "cpe": "",
          "pretty_name": "Ubuntu 18.04.3 LTS"
        },
        "repository": {
          "id": "string",
          "name": "string",
          "key": "string",
          "uri": "string",
          "cpe": "string"
        }
      }
    }
  ]
}

PagedNotifications

Properties

NameTypeRequiredRestrictionsDescription
pageobjectfalsenoneA page object informing the client the next page to retrieve.
If page.next becomes "-1" the client should stop paging.
notifications[Notification]falsenoneA list of notifications within this page

Callback

{
  "notification_id": "269886f3-0146-4f08-9bf7-cb1138d48643",
  "callback": "http://clair-notifier/notifier/api/v1/notifications/269886f3-0146-4f08-9bf7-cb1138d48643"
}

Callback

Properties

NameTypeRequiredRestrictionsDescription
notification_idstringfalsenonethe unique identifier for this set of notifications
callbackstringfalsenonethe url where notifications can be retrieved

VulnSummary

{
  "name": "CVE-2009-5155",
  "fixed_in_version": "v0.0.1",
  "links": "http://link-to-advisory",
  "description": "In the GNU C Library (aka glibc or libc6) before 2.28,\nparse_reg_exp in posix/regcomp.c misparses alternatives,\nwhich allows attackers to cause a denial of service (assertion\nfailure and application exit) or trigger an incorrect result\nby attempting a regular-expression match.\"\n",
  "normalized_severity": "Unknown",
  "package": {
    "id": "10",
    "name": "libapt-pkg5.0",
    "version": "1.6.11",
    "kind": "binary",
    "normalized_version": "",
    "arch": "x86",
    "module": "",
    "cpe": "",
    "source": {
      "id": "9",
      "name": "apt",
      "version": "1.6.11",
      "kind": "source",
      "source": null
    }
  },
  "distribution": {
    "id": "1",
    "did": "ubuntu",
    "name": "Ubuntu",
    "version": "18.04.3 LTS (Bionic Beaver)",
    "version_code_name": "bionic",
    "version_id": "18.04",
    "arch": "",
    "cpe": "",
    "pretty_name": "Ubuntu 18.04.3 LTS"
  },
  "repository": {
    "id": "string",
    "name": "string",
    "key": "string",
    "uri": "string",
    "cpe": "string"
  }
}

VulnSummary

Properties

NameTypeRequiredRestrictionsDescription
namestringfalsenonethe vulnerability name
fixed_in_versionstringfalsenoneThe version which the vulnerability is fixed in. Empty if not fixed.
linksstringfalsenonelinks to external information about vulnerability
descriptionstringfalsenonethe vulnerability name
normalized_severitystringfalsenoneA well defined set of severity strings guaranteed to be present.
packagePackagefalsenoneA package discovered by indexing a Manifest
distributionDistributionfalsenoneAn indexed distribution discovered in a layer. See
https://www.freedesktop.org/software/systemd/man/os-release.html
for explanations and example of fields.
repositoryRepositoryfalsenoneA package repository

Enumerated Values

PropertyValue
normalized_severityUnknown
normalized_severityNegligible
normalized_severityLow
normalized_severityMedium
normalized_severityHigh
normalized_severityCritical

Notification

{
  "id": "5e4b387e-88d3-4364-86fd-063447a6fad2",
  "manifest": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
  "reason": "added",
  "vulnerability": {
    "name": "CVE-2009-5155",
    "fixed_in_version": "v0.0.1",
    "links": "http://link-to-advisory",
    "description": "In the GNU C Library (aka glibc or libc6) before 2.28,\nparse_reg_exp in posix/regcomp.c misparses alternatives,\nwhich allows attackers to cause a denial of service (assertion\nfailure and application exit) or trigger an incorrect result\nby attempting a regular-expression match.\"\n",
    "normalized_severity": "Unknown",
    "package": {
      "id": "10",
      "name": "libapt-pkg5.0",
      "version": "1.6.11",
      "kind": "binary",
      "normalized_version": "",
      "arch": "x86",
      "module": "",
      "cpe": "",
      "source": {
        "id": "9",
        "name": "apt",
        "version": "1.6.11",
        "kind": "source",
        "source": null
      }
    },
    "distribution": {
      "id": "1",
      "did": "ubuntu",
      "name": "Ubuntu",
      "version": "18.04.3 LTS (Bionic Beaver)",
      "version_code_name": "bionic",
      "version_id": "18.04",
      "arch": "",
      "cpe": "",
      "pretty_name": "Ubuntu 18.04.3 LTS"
    },
    "repository": {
      "id": "string",
      "name": "string",
      "key": "string",
      "uri": "string",
      "cpe": "string"
    }
  }
}

Notification

Properties

NameTypeRequiredRestrictionsDescription
idstringfalsenonea unique identifier for this notification
manifeststringfalsenoneThe hash of the manifest affected by the provided vulnerability.
reasonstringfalsenonethe reason for the notifcation, [added
vulnerabilityVulnSummaryfalsenoneA summary of a vulnerability

Environment

{
  "package_db": "var/lib/dpkg/status",
  "introduced_in": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
  "distribution_id": "1"
}

Environment

Properties

NameTypeRequiredRestrictionsDescription
package_dbstringtruenoneThe filesystem path or unique identifier of a package database.
introduced_inDigesttruenoneA digest string with prefixed algorithm. The format is described here:
https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests

Digests are used throughout the API to identify Layers and Manifests.
distribution_idstringtruenoneThe distribution ID found in an associated IndexReport or
VulnerabilityReport.

IndexReport

{
  "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
  "state": "IndexFinished",
  "packages": {
    "10": {
      "id": "10",
      "name": "libapt-pkg5.0",
      "version": "1.6.11",
      "kind": "binary",
      "normalized_version": "",
      "arch": "x86",
      "module": "",
      "cpe": "",
      "source": {
        "id": "9",
        "name": "apt",
        "version": "1.6.11",
        "kind": "source",
        "source": null
      }
    }
  },
  "distributions": {
    "1": {
      "id": "1",
      "did": "ubuntu",
      "name": "Ubuntu",
      "version": "18.04.3 LTS (Bionic Beaver)",
      "version_code_name": "bionic",
      "version_id": "18.04",
      "arch": "",
      "cpe": "",
      "pretty_name": "Ubuntu 18.04.3 LTS"
    }
  },
  "environments": {
    "10": [
      {
        "package_db": "var/lib/dpkg/status",
        "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
        "distribution_id": "1"
      }
    ]
  },
  "success": true,
  "err": ""
}

IndexReport

Properties

NameTypeRequiredRestrictionsDescription
manifest_hashDigesttruenoneA digest string with prefixed algorithm. The format is described here:
https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests

Digests are used throughout the API to identify Layers and Manifests.
statestringtruenoneThe current state of the index operation
packagesobjecttruenoneA map of Package objects indexed by Package.id
» additionalPropertiesPackagefalsenoneA package discovered by indexing a Manifest
distributionsobjecttruenoneA map of Distribution objects keyed by their Distribution.id
discovered in the manifest.
» additionalPropertiesDistributionfalsenoneAn indexed distribution discovered in a layer. See
https://www.freedesktop.org/software/systemd/man/os-release.html
for explanations and example of fields.
environmentsobjecttruenoneA map of lists containing Environment objects keyed by the
associated Package.id.
» additionalProperties[Environment]falsenone[The environment a particular package was discovered in.]
successbooleantruenoneA bool indicating succcessful index
errstringtruenoneAn error message on event of unsuccessful index

VulnerabilityReport

{
  "manifest_hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
  "packages": {
    "10": {
      "id": "10",
      "name": "libapt-pkg5.0",
      "version": "1.6.11",
      "kind": "binary",
      "normalized_version": "",
      "arch": "x86",
      "module": "",
      "cpe": "",
      "source": {
        "id": "9",
        "name": "apt",
        "version": "1.6.11",
        "kind": "source",
        "source": null
      }
    }
  },
  "distributions": {
    "1": {
      "id": "1",
      "did": "ubuntu",
      "name": "Ubuntu",
      "version": "18.04.3 LTS (Bionic Beaver)",
      "version_code_name": "bionic",
      "version_id": "18.04",
      "arch": "",
      "cpe": "",
      "pretty_name": "Ubuntu 18.04.3 LTS"
    }
  },
  "environments": {
    "10": [
      {
        "package_db": "var/lib/dpkg/status",
        "introduced_in": "sha256:35c102085707f703de2d9eaad8752d6fe1b8f02b5d2149f1d8357c9cc7fb7d0a",
        "distribution_id": "1"
      }
    ]
  },
  "vulnerabilities": {
    "356835": {
      "id": "356835",
      "updater": "",
      "name": "CVE-2009-5155",
      "description": "In the GNU C Library (aka glibc or libc6) before 2.28,\nparse_reg_exp in posix/regcomp.c misparses alternatives,\nwhich allows attackers to cause a denial of service (assertion\nfailure and application exit) or trigger an incorrect result\nby attempting a regular-expression match.\"\n",
      "links": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-5155\nhttp://people.canonical.com/~ubuntu-security/cve/2009/CVE-2009-5155.html\nhttps://sourceware.org/bugzilla/show_bug.cgi?id=11053\nhttps://debbugs.gnu.org/cgi/bugreport.cgi?bug=22793\nhttps://debbugs.gnu.org/cgi/bugreport.cgi?bug=32806\nhttps://debbugs.gnu.org/cgi/bugreport.cgi?bug=34238\nhttps://sourceware.org/bugzilla/show_bug.cgi?id=18986\"\n",
      "severity": "Low",
      "normalized_severity": "Low",
      "package": {
        "id": "0",
        "name": "glibc",
        "version": "",
        "kind": "",
        "source": null,
        "package_db": "",
        "repository_hint": ""
      },
      "dist": {
        "id": "0",
        "did": "ubuntu",
        "name": "Ubuntu",
        "version": "18.04.3 LTS (Bionic Beaver)",
        "version_code_name": "bionic",
        "version_id": "18.04",
        "arch": "",
        "cpe": "",
        "pretty_name": ""
      },
      "repo": {
        "id": "0",
        "name": "Ubuntu 18.04.3 LTS",
        "key": "",
        "uri": ""
      },
      "issued": "2019-10-12T07:20:50.52Z",
      "fixed_in_version": "2.28-0ubuntu1"
    }
  },
  "package_vulnerabilities": {
    "10": [
      "356835"
    ]
  }
}

VulnerabilityReport

Properties

NameTypeRequiredRestrictionsDescription
manifest_hashDigesttruenoneA digest string with prefixed algorithm. The format is described here:
https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests

Digests are used throughout the API to identify Layers and Manifests.
packagesobjecttruenoneA map of Package objects indexed by Package.id
» additionalPropertiesPackagefalsenoneA package discovered by indexing a Manifest
distributionsobjecttruenoneA map of Distribution objects indexed by Distribution.id.
» additionalPropertiesDistributionfalsenoneAn indexed distribution discovered in a layer. See
https://www.freedesktop.org/software/systemd/man/os-release.html
for explanations and example of fields.
environmentsobjecttruenoneA mapping of Environment lists indexed by Package.id
» additionalProperties[Environment]falsenone[The environment a particular package was discovered in.]
vulnerabilitiesobjecttruenoneA map of Vulnerabilities indexed by Vulnerability.id
» additionalPropertiesVulnerabilityfalsenoneA unique vulnerability indexed by Clair
package_vulnerabilitiesobjecttruenoneA mapping of Vulnerability.id lists indexed by Package.id.
» additionalProperties[string]falsenonenone

Vulnerability

{
  "id": "356835",
  "updater": "",
  "name": "CVE-2009-5155",
  "description": "In the GNU C Library (aka glibc or libc6) before 2.28,\nparse_reg_exp in posix/regcomp.c misparses alternatives,\nwhich allows attackers to cause a denial of service (assertion\nfailure and application exit) or trigger an incorrect result\nby attempting a regular-expression match.\"\n",
  "links": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-5155\nhttp://people.canonical.com/~ubuntu-security/cve/2009/CVE-2009-5155.html\nhttps://sourceware.org/bugzilla/show_bug.cgi?id=11053\nhttps://debbugs.gnu.org/cgi/bugreport.cgi?bug=22793\nhttps://debbugs.gnu.org/cgi/bugreport.cgi?bug=32806\nhttps://debbugs.gnu.org/cgi/bugreport.cgi?bug=34238\nhttps://sourceware.org/bugzilla/show_bug.cgi?id=18986\"\n",
  "severity": "Low",
  "normalized_severity": "Low",
  "package": {
    "id": "0",
    "name": "glibc",
    "version": "",
    "kind": "",
    "source": null,
    "package_db": "",
    "repository_hint": ""
  },
  "dist": {
    "id": "0",
    "did": "ubuntu",
    "name": "Ubuntu",
    "version": "18.04.3 LTS (Bionic Beaver)",
    "version_code_name": "bionic",
    "version_id": "18.04",
    "arch": "",
    "cpe": "",
    "pretty_name": ""
  },
  "repo": {
    "id": "0",
    "name": "Ubuntu 18.04.3 LTS",
    "key": "",
    "uri": ""
  },
  "issued": "2019-10-12T07:20:50.52Z",
  "fixed_in_version": "2.28-0ubuntu1",
  "x-widdershins-oldRef": "#/components/examples/Vulnerability/value"
}

Vulnerability

Properties

NameTypeRequiredRestrictionsDescription
idstringtruenoneA unique ID representing this vulnerability.
updaterstringtruenoneA unique ID representing this vulnerability.
namestringtruenoneName of this specific vulnerability.
descriptionstringtruenoneA description of this specific vulnerability.
linksstringtruenoneA space separate list of links to any external information.
severitystringtruenoneA severity keyword taken verbatim from the vulnerability source.
normalized_severitystringtruenoneA well defined set of severity strings guaranteed to be present.
packagePackagefalsenoneA package discovered by indexing a Manifest
distributionDistributionfalsenoneAn indexed distribution discovered in a layer. See
https://www.freedesktop.org/software/systemd/man/os-release.html
for explanations and example of fields.
repositoryRepositoryfalsenoneA package repository
issuedstringfalsenoneThe timestamp in which the vulnerability was issued
rangestringfalsenoneThe range of package versions affected by this vulnerability.
fixed_in_versionstringtruenoneA unique ID representing this vulnerability.

Enumerated Values

PropertyValue
normalized_severityUnknown
normalized_severityNegligible
normalized_severityLow
normalized_severityMedium
normalized_severityHigh
normalized_severityCritical

Distribution

{
  "id": "1",
  "did": "ubuntu",
  "name": "Ubuntu",
  "version": "18.04.3 LTS (Bionic Beaver)",
  "version_code_name": "bionic",
  "version_id": "18.04",
  "arch": "",
  "cpe": "",
  "pretty_name": "Ubuntu 18.04.3 LTS",
  "x-widdershins-oldRef": "#/components/examples/Distribution/value"
}

Distribution

Properties

NameTypeRequiredRestrictionsDescription
idstringtruenoneA unique ID representing this distribution
didstringtruenonenone
namestringtruenonenone
versionstringtruenonenone
version_code_namestringtruenonenone
version_idstringtruenonenone
archstringtruenonenone
cpestringtruenonenone
pretty_namestringtruenonenone

SourcePackage

{
  "id": "10",
  "name": "libapt-pkg5.0",
  "version": "1.6.11",
  "kind": "binary",
  "normalized_version": "",
  "arch": "x86",
  "module": "",
  "cpe": "",
  "source": {
    "id": "9",
    "name": "apt",
    "version": "1.6.11",
    "kind": "source",
    "source": null
  },
  "x-widdershins-oldRef": "#/components/examples/Package/value"
}

SourcePackage

Properties

NameTypeRequiredRestrictionsDescription
idstringtruenoneA unique ID representing this package
namestringtruenoneName of the Package
versionstringtruenoneVersion of the Package
kindstringfalsenoneKind of package. Source
sourcestringfalsenonenone
normalized_versionVersionfalsenoneVersion is a normalized claircore version, composed of a "kind" and an
array of integers such that two versions of the same kind have the
correct ordering when the integers are compared pair-wise.
archstringfalsenonenone
modulestringfalsenonenone
cpestringfalsenoneA CPE identifying the package

Package

{
  "id": "10",
  "name": "libapt-pkg5.0",
  "version": "1.6.11",
  "kind": "binary",
  "normalized_version": "",
  "arch": "x86",
  "module": "",
  "cpe": "",
  "source": {
    "id": "9",
    "name": "apt",
    "version": "1.6.11",
    "kind": "source",
    "source": null
  },
  "x-widdershins-oldRef": "#/components/examples/Package/value"
}

Package

Properties

NameTypeRequiredRestrictionsDescription
idstringtruenoneA unique ID representing this package
namestringtruenoneName of the Package
versionstringtruenoneVersion of the Package
kindstringfalsenoneKind of package. Source
sourceSourcePackagefalsenoneA source package affiliated with a Package
normalized_versionVersionfalsenoneVersion is a normalized claircore version, composed of a "kind" and an
array of integers such that two versions of the same kind have the
correct ordering when the integers are compared pair-wise.
archstringfalsenoneThe package's target system architecture
modulestringfalsenoneA module further defining a namespace for a package
cpestringfalsenoneA CPE identifying the package

Repository

{
  "id": "string",
  "name": "string",
  "key": "string",
  "uri": "string",
  "cpe": "string"
}

Repository

Properties

NameTypeRequiredRestrictionsDescription
idstringfalsenonenone
namestringfalsenonenone
keystringfalsenonenone
uristringfalsenonenone
cpestringfalsenonenone

Version

"pep440:0.0.0.0.0.0.0.0.0"

Version

Properties

NameTypeRequiredRestrictionsDescription
VersionstringfalsenoneVersion is a normalized claircore version, composed of a "kind" and an
array of integers such that two versions of the same kind have the
correct ordering when the integers are compared pair-wise.

Manifest

{
  "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
  "layers": [
    {
      "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
      "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36\n",
      "headers": {
        "property1": [
          "string"
        ],
        "property2": [
          "string"
        ]
      }
    }
  ]
}

Manifest

Properties

NameTypeRequiredRestrictionsDescription
hashDigesttruenoneA digest string with prefixed algorithm. The format is described here:
https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests

Digests are used throughout the API to identify Layers and Manifests.
layers[Layer]truenone[A Layer within a Manifest and where Clair may retrieve it.]

Layer

{
  "hash": "sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3",
  "uri": "https://storage.example.com/blob/2f077db56abccc19f16f140f629ae98e904b4b7d563957a7fc319bd11b82ba36\n",
  "headers": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Layer

Properties

NameTypeRequiredRestrictionsDescription
hashDigesttruenoneA digest string with prefixed algorithm. The format is described here:
https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests

Digests are used throughout the API to identify Layers and Manifests.
uristringtruenoneA URI describing where the layer may be found. Implementations
MUST support http(s) schemes and MAY support additional
schemes.
headersobjecttruenonemap of arrays of header values keyed by header
value. e.g. map[string][]string
» additionalProperties[string]falsenonenone

Error

{
  "code": "string",
  "message": "string"
}

Error

Properties

NameTypeRequiredRestrictionsDescription
codestringfalsenonea code for this particular error
messagestringfalsenonea message with further detail

State

{
  "state": "aae368a064d7c5a433d0bf2c4f5554cc"
}

State

Properties

NameTypeRequiredRestrictionsDescription
statestringtruenonean opaque identifier

Digest

"sha256:fc84b5febd328eccaa913807716887b3eb5ed08bc22cc6933a9ebf82766725e3"

Digest

Properties

NameTypeRequiredRestrictionsDescription
DigeststringfalsenoneA digest string with prefixed algorithm. The format is described here:
https://github.com/opencontainers/image-spec/blob/master/descriptor.md#digests

Digests are used throughout the API to identify Layers and Manifests.