Canary map.medium.stroke

API Docs

Hello!

Welcome to Appcanary. The purpose of this documentation is to show you how to connect to our service. This API and accompanying documentation is in beta, pending feedback from users just like you.

Please tell us what you think! You can email us at hello@appcanary.com.

Also, we will be careful and try to communicate this clearly when it happens but: this API is still in development and we may ship breaking changes.

Libraries

There is a Rubygem that implements parts of this API, and may be easier to use.


Authentication

GET https://appcanary.com/api/v3/status

All communication with our APIs require your API key to be included as an Authentication header. These can be set in curl like so:

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
     https://appcanary.com/api/v3/status

The status endpoint shown above will respond appropriately if your request is authenticated and your account is in good standing.





Check API

Request

POST https://appcanary.com/api/v3/check?platform=:platform&release=:release

Check your dependencies for vulnerabilities. For example, with Ruby:

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
 "https://appcanary.com/api/v3/check?platform=ruby" -X POST \
 -F file=@./Gemfile.lock
or
curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
 "https://appcanary.com/api/v3/check?platform=ubuntu&release=14.04" -X POST \
 -F file=@/var/lib/dpkg/status

Required URL query parameters

platform
The platform being checked. One of: ruby, ubuntu, centos, amzn.
release
Where appropriate, the specific release version being checked.
When the platform is:
ubuntu
15.10, 15.04, 14.04 or 12.04, etc
debian
8, 7, 6 or 5, etc
centos
7, or 6, or 5
alpine
3.6.0, or 3.5.2, or 3.5.1, etc
amzn
None, leave blank.
ruby
None, leave blank.
php
None, leave blank.

Required query parameters

file
The dependencies you want to check, form encoded.
When the platform is:
ubuntu
/var/lib/dpkg/status
debian
/var/lib/dpkg/status
centos
The output of: rpm -qa
amzn
The output of: rpm -qa
alpine
/lib/apk/db/installed
ruby
Your Gemfile.lock
php
Your composer.lock

The purpose of this endpoint is to show which vulnerabilities your app's dependencies are affected by.

At the moment we only accept requests with Content-Type: multipart/form-data with an embedded application/octet-stream. If you need to send data in a different format, please let us know.

Please note!

We cache requests. We strive to discard sensitive information but be mindful when submitting files containing credentials.

All requests are currently unmetered. This may change as appropriate.


Response

Successful requests will have a 200 OK response code containing application/json data.

All successful responses will be wrapped in a "data" container object and will have a "vulnerable" boolean field wrapped inside a "meta" object. This container object shall always contain an array, whether it's empty or not. This schema follows the jsonapi spec.

For example, if your dependency file does not have any known vulnerabilities, the response body will look like this:

{
  "data": [],
  "meta": {
    "vulnerable": false
  }
}

The response container object

However, if your app does have vulnerable dependencies, then the container object will consist of a series of package objects, and look like the following example response:

{
  "data": [
    {
      "id": "37495",
      "type": "packages",
      "attributes": {
        "name": "rack",
        "platform": "ruby",
        "release": null,
        "version": "1.6.0",
        "upgrade-to": [
          "1.6.2"
        ]
      },
      "relationships": {
        "vulnerabilities": {
          "data": [
            {
              "id": "2239",
              "type": "vulnerabilities"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "id": "2239",
      "type": "vulnerabilities",
      "attributes": {
        "title": "Potential Denial of Service Vulnerability in Rack\n",
        "description": "Carefully crafted requests can cause a `SystemStackError` and potentially \ncause a denial of service attack. \n\nAll users running an affected release should upgrade. \n",
        "criticality": "medium",
        "cvss": "5.2"
        "reference-ids": [
          "CVE-2015-3225"
        ]
      }
    }
  ],
  "meta": {
    "vulnerable": true
  }
}

Package container object

type
Describes the type of the resource - may only be "packages"
attributes
A nested series of attributes relating to the package.

Package attributes object

A Package may be thought of as a unique (name, platform, release, version) tuple.

name
The name of the package, dependency or artifact
platform
The name of the platform, ecosystem or environment this package belongs to.
release
The name or version string of the specific release of the platform, ecosystem or environment this package belongs to.
version
The specific version string of the package being discussed. Version string formats vary from platform to platform.
relationships
A array of objects describing the vulnerabilities that affect this specific Package. Due to the nature of this API endpoint, this array should never be empty.

Vulnerability object

title
A human readable summary of the vulnerability.
description
A human readable long form description of the vulnerability. May contain unescaped HTML or raw markdown - beware if injecting this into a web page
criticality
A subjective rating of how seriously of this vulnerability should be treated. May consist of unknown, negligible, low, medium, high or critical.
cvss
A CVSSv3 vulnerability score if we have it.
reference-ids
An array of strings containing CVE or other advisory ids. A given vulnerability may be related to multiple CVEs. If none are available, will present an empty array.




Monitor API

A monitor lets you register a set of packages for us to keep a watch on.

Send us information on packages on platforms we support, and we will email you updates whenever any of the packages listed have a known vulnerability. It's like registering a server using our agent, but you get complete control of what we're watching and how often it gets updated.

Create Request

POST https://appcanary.com/api/v3/monitors/:name?platform=:platform&release=:release

Every monitor has a name unique to your account. You must specify the monitor's name. Creates a monitor with a specified name. For example, with Ubuntu:

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
      -X POST -F file=@/var/lib/dpkg/status \
      "https://appcanary.com/api/v3/monitors/my-server?platform=ubuntu&release=12.04"

Required URL query parameters

name
The name of the monitor you want to create, form encoded.
platform
The platform being checked. One of: ruby, ubuntu, centos, amzn.
release
Where appropriate, the specific release version being checked.
When the platform is:
ubuntu
15.10, 15.04, 14.04 or 12.04, etc
debian
8, 7, 6 or 5, etc
centos
7, or 6, or 5
alpine
3.6.0, or 3.5.2, or 3.5.1, etc
amzn
None, leave blank.
ruby
None, leave blank.
php
None, leave blank.

Required query parameters

file
The dependencies you want to check, form encoded.
When the platform is:
ubuntu
/var/lib/dpkg/status
debian
/var/lib/dpkg/status
centos
The output of: rpm -qa
amzn
The output of: rpm -qa
alpine
/lib/apk/db/installed
ruby
Your Gemfile.lock
php
Your composer.lock

Create Response

Successful requests will have a 201 CREATED response code containing application/json data.

All successful responses will be wrapped in a "data" container object.

For example, a response body will look like this:

{
  "data": {
    "id": "717",
    "type": "monitors",
    "attributes": {
      "name": "my-server",
      "vulnerable": true,
      "created-at": "2016-10-03T20:33:08.889Z"
    }
  }
}

The response container object

data
A single object containing the data returned.
metadata
An array of metadata attributes largely meant for human consumption. A means of warning you of deprecation, or rate overages.

Monitor object

name
The user specified name of the monitor.
vulnerable
A boolean representing whether the monitor contains known vulnerabilities.



List Monitors

To list all of the monitors you have registered:

GET https://appcanary.com/api/v3/monitors

For example

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
      https://appcanary.com/api/v3/monitors/

List Monitors Response

Successful requests will have a 200 OK response code containing application/json data, which shall always contain an array.

All successful responses will be wrapped in a "data" container object.

For example, a response body will look like this:

{
  "data": [
    {
      "id": "717",
      "type": "monitors",
      "attributes": {
        "name": "my-server",
        "vulnerable": true,
        "created-at": "2016-10-03T20:33:08.889Z"
      }
    },
    {
      "id": "712",
      "type": "monitors",
      "attributes": {
        "name": "my-ruby-app",
        "vulnerable": true,
        "created-at": "2016-09-29T16:45:49.284Z"
      }
    }
  ]
}

The response container object

data
An array containing the data we're returning. May be empty if there is no data
metadata
An array of metadata attributes largely meant for human consumption. A means of warning you of deprecation, or rate overages.

Monitor object

name
The user specified name of the monitor.
vulnerable
A boolean representing whether the monitor contains known vulnerabilities.



Show Monitor

To show details about a specific monitor:

GET https://appcanary.com/api/v3/monitors/:name

For example

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
      https://appcanary.com/api/v3/monitors/my-server

Required path parameters

name
The name of the monitor you want to create, form encoded.
If unspecified, we will generate one for you.

Show Monitors Response

Successful requests will have a 200 OK response code containing application/json data.

All successful responses will be wrapped in a "data" container object.

For example, a response body will look like this:

{
  "data": {
    "id": "717",
    "type": "monitors",
    "attributes": {
      "name": "my-server",
      "vulnerable": true,
      "created-at": "2016-10-03T20:33:08.889Z"
    },
    "relationships": {
      "packages": {
        "data": [
          {
            "id": "37495",
            "type": "packages"
          }
        ]
      },
      "vulnerabilities": {
        "data": [
          {
            "id": "2239",
            "type": "vulnerabilities"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "37495",
      "type": "packages",
      "attributes": {
        "name": "rack",
        "platform": "ruby",
        "release": null,
        "version": "1.6.0",
        "upgrade-to": [
          "1.6.2"
        ]
      },
      "relationships": {
        "vulnerabilities": {
          "data": [
            {
              "id": "2239",
              "type": "vulnerabilities"
            }
          ]
        }
      }
    },
    {
      "id": "2239",
      "type": "vulnerabilities",
      "attributes": {
        "title": "Potential Denial of Service Vulnerability in Rack\n",
        "description": "Carefully crafted requests can cause a `SystemStackError` and potentially \ncause a denial of service attack. \n\nAll users running an affected release should upgrade. \n",
        "criticality": "medium",
        "cvss": "5.2",
        "reference-ids": [
          "CVE-2015-3225"
        ]
      }
    }
  ]
}
    

The response container object

data
A single object containing the data returned.
metadata
An array of metadata attributes largely meant for human consumption. A means of warning you of deprecation, or rate overages.

Monitor object

name
The user specified name of the monitor.
vulnerable
A boolean representing whether the monitor contains known vulnerabilities.

Package container object

type
Describes the type of the resource - may only be "packages"
attributes
A nested series of attributes relating to the package.

Package attributes object

A Package may be thought of as a unique (name, platform, release, version) tuple.

name
The name of the package, dependency or artifact
platform
The name of the platform, ecosystem or environment this package belongs to.
release
The name or version string of the specific release of the platform, ecosystem or environment this package belongs to.
version
The specific version string of the package being discussed. Version string formats vary from platform to platform.
relationships
A array of objects describing the vulnerabilities that affect this specific Package. Due to the nature of this API endpoint, this array should never be empty.

Vulnerability object

title
A human readable summary of the vulnerability.
description
A human readable long form description of the vulnerability. May contain unescaped HTML or raw markdown - beware if injecting this into a web page
criticality
A subjective rating of how seriously of this vulnerability should be treated. May consist of unknown, negligible, low, medium, high or critical.
cvss
A CVSSv3 vulnerability score if we have it.
reference-ids
An array of strings containing CVE or other advisory ids. A given vulnerability may be related to multiple CVEs. If none are available, will present an empty array.



Update a Monitor

Whenever a monitored server's or app's packages changes, you'll want to update the monitor.

PUT https://appcanary.com/api/v3/monitors/:name

Updates a monitor with the specified name with the contents of file. For example, with Ubuntu:

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
      -X PUT -F file=@/var/lib/dpkg/status \
      https://appcanary.com/api/v3/monitors/my-server

Note: if a monitor with the name does not exist yet, this method will create it. In that case, you can specify platform and release as query parameters, as in the create request.

Required path parameters

name
The name of the monitor you want to create, form encoded.
If unspecified, we will generate one for you.

Required query parameters

file
The dependencies you want to check, form encoded.
When the platform is:
ubuntu
/var/lib/dpkg/status
debian
/var/lib/dpkg/status
centos
The output of: rpm -qa
amzn
The output of: rpm -qa
alpine
/lib/apk/db/installed
ruby
Your Gemfile.lock
php
Your composer.lock

Update Monitor Response

Successful requests will have a 200 OK response code containing application/json data.

All successful responses will be wrapped in a "data" container object.

For example, a response body will look like this:

{
  "data": {
    "id": "717",
    "type": "monitors",
    "attributes": {
      "name": "my-server",
      "vulnerable": true,
      "created-at": "2016-10-03T20:33:08.889Z"
    }
  }
}

The response container object

data
A single object containing the data returned.
metadata
An array of metadata attributes largely meant for human consumption. A means of warning you of deprecation, or rate overages.

Monitor object

name
The user specified name of the monitor.
vulnerable
A boolean representing whether the monitor contains known vulnerabilities.



Delete Monitor

To delete a monitor you have previously registered

DELETE https://appcanary.com/api/v3/monitors/:name

For example

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
     -X DELETE \
     https://appcanary.com/api/v3/monitors/my-server

Delete Monitor Response

Successful requests will have a 204 NO CONTENT response code containing no data.





Server API

The server allows you to query information about servers that you register with our agents.

List Servers

To list all of the servers you have registered:

GET https://appcanary.com/api/v3/servers

For example

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
      https://appcanary.com/api/v3/servers

List Servers Response

Successful requests will have a 200 OK response code containing application/json data, which shall always contain an array.

All successful responses will be wrapped in a "data" container object.

For example, a response body will look like this:

{
  "data": [
    {
      "id": "479",
      "type": "servers",
      "attributes": {
        "name": "",
        "uuid": "576af72e-f8ea-4fd6-a117-6fdf26a2eacc",
        "hostname": "debian-jessie",
        "last-heartbeat-at": null
      },
      "relationships": {
        "monitors": {
          "data": [
            {
              "id": "717",
              "type": "monitors"
            }
          ]
        }
      }
    },
  ],
  "included": [
    {
      "id": "717",
      "type": "monitors",
      "attributes": {
        "name": "my-server",
        "vulnerable": true,
        "created-at": "2016-10-03T20:33:08.889Z"
      }
    }
  ]
}
    

The response container object

data
An array containing the data we're returning. May be empty if there is no data
metadata
An array of metadata attributes largely meant for human consumption. A means of warning you of deprecation, or rate overages.

Server object

name
A name of the server. Can be user specified.
uuid
A randomly generated identifier. Refer to this field when submitting support requests.
hostname
The server hostname
last-heartbeat-at
A timestamp representing the last time the server heartbeated
relationships
An array of Monitor objects

Monitor object

name
A name of the monitor. Can be user specified.
path
The path of the file the app corresponds to.
id
Refer to this field when submitting support requests.
vulnerable
A boolean representing whether the monitor contains known vulnerabilities.



Show Server

To show details about a specific server:

GET https://appcanary.com/api/v3/servers/:uuid

For example

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
      https://appcanary.com/api/v3/servers/576af72e-f8ea-4fd6-a117-6fdf26a2eacc

Required path parameters

uuid
The uuid of the server

Show Server Response

Successful requests will have a 200 OK response code containing application/json data.

All successful responses will be wrapped in a "data" container object.

For example, a response body will look like this:

{
  "data": {
    "id": "479",
    "type": "servers",
    "attributes": {
      "name": "",
      "uuid": "576af72e-f8ea-4fd6-a117-6fdf26a2eacc",
      "hostname": "debian-jessie",
      "last-heartbeat-at": null
    },
    "relationships": {
      "monitors": {
        "data": [
          {
            "id": "717",
            "type": "monitors"
          },
        ]
      }
    }
  },
  "included": [
    {
      "id": "717",
      "type": "monitors",
      "attributes": {
        "name": "my-server",
        "vulnerable": true,
        "created-at": "2016-10-03T20:33:08.889Z"
      },
      "relationships": {
        "packages": {
          "data": [
            {
              "id": "37495",
              "type": "packages"
            }
          ]
        },
        "vulnerabilities": {
          "data": [
            {
              "id": "2239",
              "type": "vulnerabilities"
            }
          ]
        }
      }
    },

    {
      "id": "37495",
      "type": "packages",
      "attributes": {
        "name": "rack",
        "platform": "ruby",
        "release": null,
        "version": "1.6.0",
        "upgrade-to": [
          "1.6.2"
        ]
      },
      "relationships": {
        "vulnerabilities": {
          "data": [
            {
              "id": "2239",
              "type": "vulnerabilities"
            }
          ]
        }
      }
    },
    {
      "id": "2239",
      "type": "vulnerabilities",
      "attributes": {
        "title": "Potential Denial of Service Vulnerability in Rack\n",
        "description": "Carefully crafted requests can cause a `SystemStackError` and potentially \ncause a denial of service attack. \n\nAll users running an affected release should upgrade. \n",
        "criticality": "medium",
        "cvss": "5.2",
        "reference-ids": [
          "CVE-2015-3225"
        ]
      }
    }
  ]
}
    

The response container object

data
A single object containing the data returned.
metadata
An array of metadata attributes largely meant for human consumption. A means of warning you of deprecation, or rate overages.

Server object

name
A name of the server. Can be user specified.
uuid
A randomly generated identifier. Refer to this field when submitting support requests.
hostname
The server hostname
last-heartbeat-at
A timestamp representing the last time the server heartbeated
relationships
An array of Monitor objects

Monitor object

name
A name of the monitor. Can be user specified.
path
The path of the file the app corresponds to.
id
Refer to this field when submitting support requests.
vulnerable
A boolean representing whether the monitor contains known vulnerabilities.

Package container object

type
Describes the type of the resource - may only be "packages"
attributes
A nested series of attributes relating to the package.

Package attributes object

A Package may be thought of as a unique (name, platform, release, version) tuple.

name
The name of the package, dependency or artifact
platform
The name of the platform, ecosystem or environment this package belongs to.
release
The name or version string of the specific release of the platform, ecosystem or environment this package belongs to.
version
The specific version string of the package being discussed. Version string formats vary from platform to platform.
relationships
A array of objects describing the vulnerabilities that affect this specific Package. Due to the nature of this API endpoint, this array should never be empty.

Vulnerability object

title
A human readable summary of the vulnerability.
description
A human readable long form description of the vulnerability. May contain unescaped HTML or raw markdown - beware if injecting this into a web page
criticality
A subjective rating of how seriously of this vulnerability should be treated. May consist of unknown, negligible, low, medium, high or critical.
cvss
A CVSSv3 vulnerability score if we have it.
reference-ids
An array of strings containing CVE or other advisory ids. A given vulnerability may be related to multiple CVEs. If none are available, will present an empty array.



Delete Server

To delete a server:

DELETE https://appcanary.com/api/v3/servers/:uuid

For example

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
     -X DELETE \
     https://appcanary.com/api/v3/servers/576af72e-f8ea-4fd6-a117-6fdf26a2eacc

Delete Server Response

Successful requests will have a 204 NO CONTENT response code containing no data.




Delete Inactive Servers

To delete all inactive servers (ones we haven't heard from in over 2 hours):

DELETE https://appcanary.com/api/v3/servers/inactive

For example

curl -H "Authorization: Token <YOUR_TOKEN_HERE>" \
     -X DELETE \
     https://appcanary.com/api/v3/servers/inactive

Delete Server Response

Successful requests will have a 204 NO CONTENT response code containing no data.





Errors

Occasionally, we won't be able to process your request. We'll try to give you meaningful hints. All responses shall have a 400 or 500 series status - most commonly one of: 400 Bad Request, 422 Unprocessable Entity or 500 Internal Server Error.

A sample error request looks like the following:

{
  "errors": [
    {
      "title": "Platform is invalid"
    }
  ]
}

When responding with an error, the API shall always omit the data container object and return instead an errors object, which shall always contain an array.

The error object

title
A human readable description of the problem.
details
A series of keys and values meant to provide clues or context as to what went wrong.

Questions? Feedback?

Let us know. Hit "Feedback" on the bar up top or contact us at hello@appcanary.com. Include as much detail or context as possible. Thanks!