Vulnerability History Project RESTful API (1.0.0)

Download OpenAPI specification:Download

License: MIT

This read-only API allows detailed access to the VHP data.

This documentation is a work-in-progress. If you want to contribute, see our issue on GitHub.

vulnerabilities

Putting the V in VHP.

These API calls are related to getting information about vulnerabilities, the files they impacted, and the ways we have categorized them.

/api/vulnerabilities

Returns a non-detailed list of all vulnerabilities

query Parameters

short_descriptions	boolean Should the descriptions be truncated? Mainly used in the VHP UI
limit	integer Limit the number of results
offset	integer Return a subset of the results, offset by this number

Responses

Response samples

200

Content type

application/json

[{"id": 1426,
"cve": "CVE-2017-5060",
"announced": "2017-04-19T00:00:00.000Z",
"upvotes": 50,
"nickname": "Omni-Puny",
"project_name": "Chromium",
"subdomain": "chromium",
"tag_json": [{"id": 27,
"importance": 1
},
{"id": 273,
"importance": 0.45
},
{"id": 257,
"importance": 0
},
{"id": 748,
"importance": 0
},
{"id": 750,
"importance": 0
},
{"id": 2,
"importance": 0
}
],
"description": "URL spoofing in Omnibox. Certain Cyrillic characters look incredibly similar\nto standard Roman Alphabet characters, so much so that certain fonts don't\ndistinguish between the two. Registering a domain with \"punycode\" escape\nsequences causes these characters to display in the browser.\n"
},
{"id": 1472,
"cve": "CVE-2017-5107",
"announced": "2017-01-27T00:00:00.000Z",
"upvotes": 50,
"nickname": "Convoluted",
"project_name": "Chromium",
"subdomain": "chromium",
"tag_json": [{"id": 62,
"importance": 1
},
{"id": 274,
"importance": 0.45
},
{"id": 257,
"importance": 0
},
{"id": 3,
"importance": 0
},
{"id": 2,
"importance": 0
},
{"id": 750,
"importance": 0
}
],
"description": "User information leak via SVG. By rendering a FeConvolveMatrix SVG filter over\na target iframe and timing its execution an attacking page can extract pixel\nvalues from a cross-origin page being iframe'd.\n"
}
]

/api/vulnerabilites/{cve}

Returns detailed information on a vulnerability with the specified ID

path Parameters

cve	string <Common Vulnerabilities Enumeration> ^CVE\-\d{4}\-\d+$ Example: CVE-2017-5638 The unique CVE identifier of the vulnerability

Responses

Response samples

200

Content type

application/json

{"id": 2427,
"cve": "CVE-2017-5638",
"project_id": 6,
"announced": "2017-03-02T00:00:00.000Z",
"description": "Apache Struts utilizes multipart parsers to handle HTTP POST requests,\nand there are two types available, Jakarta and Pell. The Jakarta\nMultiparser was the one that had the vulnerability, and it generates an\nexception when parsing the Content-Type. It raises this exception and\nincludes the invalid data in the error message, and does this by\nparsing the input and treating the parsed result as an OGNL expression.\nThis is potential for remote code execution.\n",
"short_desc": "Apache Struts utilizes multipart parsers to handle HTTP POST requests, and there are \ntwo types available, Jakarta and Pell",
"upvotes": 0,
"nickname": "The Equifax Breach"
}

/api/vulnerabilities/{cve}/events

Return all events for the specified vulnerability

path Parameters

cve	string <Common Vulnerabilities Enumeration> ^CVE\-\d{4}\-\d+$ Example: CVE-2017-5638 The unique CVE identifier of the vulnerability

Responses

Response samples

200

Content type

application/json

[{"id": 2438,
"title": "Vulnerability Announced for CVE-2017-5638",
"description": "The vulnerability was officially announced by the development team.",
"date": "2017-03-02T00:00:00.000Z",
"event_type": "announced",
"color": "#9DD5D5",
"icon": "bug_report",
"notes": { },
"start_hidden": false
},
{"id": 4378,
"title": "Fix for CVE-2017-5638: Uses default error key if specified key doesn't exist",
"description": "Our curators found that this vulnerability was fixed by this commit.\n\nThe commit had  lines changed.\n\n  * 9 insertions, and\n  * 12 deletions\n\nHere was the commit message.\n<blockquote>\nUses default error key if specified key doesn't exist\n</blockquote>\n\n[Learn more about this commit](/commits/6b8272ce47160036ed120a48345d9aa884477228)",
"date": "2017-03-06T10:17:38.000Z",
"event_type": "fix",
"color": "#9FE69F",
"icon": "lock",
"notes": { },
"start_hidden": false
},
{"id": 6995,
"title": "Vulnerability-contributing commit for CVE-2017-5638: WW-4636 - File upload error message always in default language",
"description": "A **vulnerability-contributing commit** (VCC) occurred here. This means that a curator identified this commit as (one of) the possible origins of this vulnerability.\n\nThis VCC had:\n\n  * 22 insertions, and\n  * 175 deletions\n\nThus it had a total raw churn of .\n\nHere was the commit message.\n<blockquote>\n:description:\n</blockquote>\n\n[Learn more about this commit](/commits/33ac7ac49aabfcf792d38fa44d271a93433ffe56)\n\n[Learn more about vulnerability-contributing commits.](/articles/vccs.md)",
"date": "2016-10-15T12:25:14.000Z",
"event_type": "vcc",
"color": "#ED6049",
"icon": "report_problem",
"notes": { },
"start_hidden": false
}
]

/api/filepaths/{filepath_id}/vulnerabilities

Returns a list of vulnerabilities fixed in this file.

path Parameters

filepath_id

string

The url-friendly identifier of a filepath.

Responses

Response samples

200

Content type

application/json

null

/api/corpus

Returns a list of vulnerabilities filtered by having written langauge in the description and mistakes fields. Also includes tag data too. Use for research purposes.

Responses

Response samples

200

Content type

application/json

[{"id": 1989,
"cve": "CVE-2014-0231",
"project_name": "httpd",
"description": "A CGI (Common Gateway Interface) is a protocol used by web servers that runs command-line interface scripts in response to client requests. Apache HTTP Server has a module \"mod_cgid\" which is responsible for running CGI scripts.\nCVE-2014-0231 was a vulnerability in Apache HTTP Server's mod_cgid module where users could create a denial of service attack by causing the process which ran these scripts to hang indefinitely. mod_cgid did not have any timeout feature. If an attacker found a request that caused one of a server's CGI scripts hosted in mod_cgid to halt, this would deny service to other users of the server's CGI scripts.",
"mistakes": "This is a particularly interesting case of finding a way to make the system fail gracefully. The issue - the process responsible for running CGI scripts hanging indefinitely - is an issue that occurs when a script fails to handle certain inputs properly. The failure to anticipate and handle this special case is what left open the opportunity for a DOS attack on the system.\nLack of unit testing is probably the most clear mistake here. The unit test suite for the project as a whole is relatively sparse, and an issue like this (a rare failure case) can be difficult to anticipate without thorough testing.",
"tag_list": [{"id": 2,
"tag": "cooks"
}
]
}
]

commits

Data for commits in the VHP database: fixes, vulnerability-contributing commits (VCCs), and any commit marked "interesting" by a curator.

/api/commits

Returns a non-detailed list of all commits in the database. These are VCCs, fixes, and interesting commits.

Responses

Response samples

200

Content type

application/json

[{"commit_hash": "639e20992a66d7a42fb59c974db91c8a0f730a1e",
"email": "foo@example.com",
"date_created": "2011-04-01T11:36:54.000Z",
"id": 0
},
{"commit_hash": "b7b5c63a932f6c1ea05f9b65ad9054247bb5af57",
"email": "foo@example.com",
"date_created": "2011-04-01T10:49:43.000Z",
"id": 1
},
{"commit_hash": "eae54419c6e196933998f63358367040edaa4a8c",
"email": "foo@example.com",
"date_created": "2006-07-20T12:50:34.000Z",
"id": 2
}
]

/api/commits/{sha}

Author of the given commit

path Parameters

sha	string <Git SHA-256> ^[\da-f]{40}$ Example: 011a54315e46acdf288003566b8570440f5ac985 The unique SHA hash string of a git commit

Responses

Response samples

200

Content type

application/json

{"id": 1,
"commit_hash": "639e20992a66d7a42fb59c974db91c8a0f730a1e",
"project_id": 8,
"author_id": 1,
"message": "Add additional configuration options to the DIGEST authenticator\nThis is the fix for CVE-2011-1184\n\ngit-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1087655 13f79535-47bb-0310-9956-ffa450edef68",
"date_created": "2011-04-01T11:36:54.000Z",
"notes": {"date": "2011-04-01 11:36:54 UTC",
"email": "foo@example.com",
"author": "Example Person",
"message": "Add additional configuration options to the DIGEST authenticator\nThis is the fix for CVE-2011-1184\n\ngit-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1087655 13f79535-47bb-0310-9956-ffa450edef68",
"deletions": 1068,
"filepaths": {"webapps/docs/changelog.xml": {"deletions": 4,
"insertions": 0
},
"webapps/docs/config/valve.xml": {"deletions": 34,
"insertions": 0
},
"java/org/apache/catalina/realm/RealmBase.java": {"deletions": 7,
"insertions": 2
}
}
}
}

/api/commits/{sha}/developer

Author of the given commit

path Parameters

sha	string <Git SHA-256> ^[\da-f]{40}$ Example: 011a54315e46acdf288003566b8570440f5ac985 The unique SHA hash string of a git commit

Responses

Response samples

200

Content type

application/json

{"id": 88,
"email": "foo@example.com",
"nickname": "Warren the Whale",
"notes": { }
}

/api/developers/{developer_id}/commits

List the commits for a developer

path Parameters

developer_id

integer <int32>

The internal primary key of the developer. Subject to change without notice.

Responses

Response samples

200

Content type

application/json

[{"commit_hash": "639e20992a66d7a42fb59c974db91c8a0f730a1e",
"message": "Add additional configuration options to the DIGEST authenticator\nThis is the fix for CVE-2011-1184\n\ngit-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1087655 13f79535-47bb-0310-9956-ffa450edef68",
"date_created": "2011-04-01T11:36:54.000Z",
"churn": 200,
"id": 1
},
{"commit_hash": "b7b5c63a932f6c1ea05f9b65ad9054247bb5af57",
"message": "Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=12428\nAdd optional support for preemptive authentication on a per context basis\nBased on a patch suggested by Werner Donn\nThis includes the fix for CVE-2011-1183\n\ngit-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1087643 13f79535-47bb-0310-9956-ffa450edef68",
"date_created": "2011-04-01T10:49:43.000Z",
"churn": 100,
"id": 2
}
]

/api/filepaths/{filepath_id}/commits

Returns a list of key commits to the file. Only includes VCCs, fixes, and interesting commits.

path Parameters

filepath_id

string

The url-friendly identifier of a filepath.

Responses

Response samples

200

Content type

application/json

null

developers

Data for developers who are authors of any commits in VHP.

These are not a comprehensive list of the developers in the project. Far from it. These are only the people who are involved in fixing, contributing, or otherwise directly related to code authorship involving a vulnerability.

/api/commits/{sha}/developer

Author of the given commit

path Parameters

sha	string <Git SHA-256> ^[\da-f]{40}$ Example: 011a54315e46acdf288003566b8570440f5ac985 The unique SHA hash string of a git commit

Responses

Response samples

200

Content type

application/json

{"id": 88,
"email": "foo@example.com",
"nickname": "Warren the Whale",
"notes": { }
}

/api/developers

Return a list of the developers who are authors of vulnerability-contributing commits, or fix commits.

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"email": "foo@example.org",
"nickname": "Pauline the Wren",
"notes": { }
},
{"id": 2,
"email": "foo2@example.org",
"nickname": "Harry the Sparrow",
"notes": { }
},
{"id": 3,
"email": "foo3@example.org",
"nickname": "Agnes the Bear",
"notes": { }
}
]

/api/developers/{developer_id}/commits

List the commits for a developer

path Parameters

developer_id

integer <int32>

The internal primary key of the developer. Subject to change without notice.

Responses

Response samples

200

Content type

application/json

[{"commit_hash": "639e20992a66d7a42fb59c974db91c8a0f730a1e",
"message": "Add additional configuration options to the DIGEST authenticator\nThis is the fix for CVE-2011-1184\n\ngit-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1087655 13f79535-47bb-0310-9956-ffa450edef68",
"date_created": "2011-04-01T11:36:54.000Z",
"churn": 200,
"id": 1
},
{"commit_hash": "b7b5c63a932f6c1ea05f9b65ad9054247bb5af57",
"message": "Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=12428\nAdd optional support for preemptive authentication on a per context basis\nBased on a patch suggested by Werner Donn\nThis includes the fix for CVE-2011-1183\n\ngit-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@1087643 13f79535-47bb-0310-9956-ffa450edef68",
"date_created": "2011-04-01T10:49:43.000Z",
"churn": 100,
"id": 2
}
]

/api/filepaths/{filepath_id}/developers

Returns a list of authors to the commits of the file. Only includes authors of commits in VHP.

path Parameters

filepath_id

string

The url-friendly identifier of a filepath.

Responses

Response samples

200

Content type

application/json

null

filepaths

Data on any filepath fixed for a vulnerability. A filepath is the name of a file combined with the directories its in, rooted at the top of the source code repository.

These are not a comprehensive list of files in the project. These are only files involved in a vulnerability in some way.

A subset of these files are known offenders, which are files that have been fixed for at least one vulnerability.

/api/filepaths

List all files touched by any commit in the database

query Parameters

offenders

boolean

Default: false

Only return "known offenders", which are files that are part of at least one vulnerability fix

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"filepath": "java/org/apache/catalina/authenticator/DigestAuthenticator.java",
"slug": "tomcat-java-org-apache-catalina-authenticator-digestauthenticator-java",
"dir": "java/org/apache/catalina/authenticator/",
"is_code": true,
"note": "",
"project_id": 8
},
{"id": 2,
"filepath": "java/org/apache/catalina/authenticator/LocalStrings.properties",
"slug": "tomcat-java-org-apache-catalina-authenticator-localstrings-properties",
"dir": "java/org/apache/catalina/authenticator/",
"is_code": true,
"note": "",
"project_id": 8
},
{"id": 3,
"filepath": "java/org/apache/catalina/authenticator/mbeans-descriptors.xml",
"slug": "tomcat-java-org-apache-catalina-authenticator-mbeans-descriptors-xml",
"dir": "java/org/apache/catalina/authenticator/",
"is_code": true,
"note": "",
"project_id": 8
}
]

/api/filepaths/{filepath_id}/developers

Returns a list of authors to the commits of the file. Only includes authors of commits in VHP.

path Parameters

filepath_id

string

The url-friendly identifier of a filepath.

Responses

Response samples

200

Content type

application/json

null

/api/filepaths/{filepath_id}/commits

Returns a list of key commits to the file. Only includes VCCs, fixes, and interesting commits.

path Parameters

filepath_id

string

The url-friendly identifier of a filepath.

Responses

Response samples

200

Content type

application/json

null

/api/filepaths/{filepath_id}/vulnerabilities

Returns a list of vulnerabilities fixed in this file.

path Parameters

filepath_id

string

The url-friendly identifier of a filepath.

Responses

Response samples

200

Content type

application/json

null

/api/tags/{tag_id}

Show details of a particular tag, including vulnerabilities that this tag has been applied to.

path Parameters

tag_id

string

The url-friendly slug of a tag

Responses

Response samples

200

Content type

application/json

null

/api/insights/tag-trends

Returns a set of nodes and links based off of the families passed in. The nodes are the tags, and the links are the number of vulnerabilities that have both tags. The nodes are sized by the number of vulnerabilities that have that tag. The links are sized by the number of vulnerabilities that have both tags.

query Parameters

family_list

required

string

A comma-separated string of tag families to common vulnerabilities with those tag families.

Responses

Response samples

200

Content type

application/json

[{"nodes": {"name": "project-xx"
},
"links": {"source": "project-xx",
"target": "language-d",
"value": 1
},
"trend_json": "{\"nodes\": [{ \"name\": \"project-xx\" },{ \"name\": \"bounty\" },{ \"name\": \"language-d\" },{ \"name\": \"lifetime-10\" }],\"links\": [{ \"source\": \"project-xx\", \"target\":\"language-d\", \"value\": 1 },{ \"source\": \"bounty\", \"target\": \"lifetime-10\", \"value\": 2 }]}"
}
]

projects

Data on the open source projects that these vulnerabilities originate from.

/api/projects

Returns the list of projects

Responses

Response samples

200

Content type

application/json

[{"id": 1,
"name": "Chromium",
"fullname": "Chromium Browser",
"subdomain": "chromium",
"fg_color": "#d9e1ed",
"bg_color": "#4587f4",
"project_url": "https://www.chromium.org/Home",
"logo": "chromium.png",
"git_commit_url_prefix": "https://github.com/chromium/chromium/commit/",
"github_search_url_prefix": "https://github.com/chromium/chromium/search?utf8=✓&q=",
"github_edit_cve_url_prefix": "https://github.com/andymeneely/chromium-vulnerabilities/edit/dev/cves/",
"description": "The Chromium Browser project is the open source project behind Google Chrome.\n\nThroughout the VHP, when we refer to Chromium, we are referring to the Browser. This study does not include ChromeOS.\n",
"vulnerabilities_description": "These vulnerabilities have been reported and confirmed\nby the Chromium team. Chromium typically releases this data on their [release\nblog](https://chromereleases.googleblog.com/).\n",
"developers_description": "The following is a list of developers who are involved\nin code that was found to be vulnerable. Specifically, developers end up here\nif they were the author of a commit to code that was, at some point in time, fixed\nfor a vulnerability. Note that this is NOT a comprehensive list, as Chromium has\n3,000+ contributors\n"
},
{"id": 2,
"name": "Django",
"fullname": "Django",
"subdomain": "django",
"fg_color": "#20AA76",
"bg_color": "#20AA76",
"project_url": "https://www.djangoproject.com/",
"logo": "django.png",
"git_commit_url_prefix": "https://github.com/django/django/commit/",
"github_search_url_prefix": "https://github.com/django/django/search?utf8=✓&q=",
"github_edit_cve_url_prefix": "https://github.com/VulnerabilityHistoryProject/django-vulnerabilities/edit/dev/cves/",
"description": "\"Django makes it easier to build better Web apps more quickly and\nwith less code.\" -https://www.djangoproject.com/\n",
"vulnerabilities_description": "These vulnerabilities are reported by the Django development\nteam [on their news feed](https://www.djangoproject.com/weblog/)\n",
"developers_description": "The following is a list of developers who are involved\nin code that was found to be vulnerable. Specifically, developers end up here\nif they were the author of a commit to code that was, at some point in time, fixed\nfor a vulnerability. Note that this is NOT a comprehensive list.\n"
},
{"id": 3,
"name": "FFmpeg",
"fullname": "FFmpeg",
"subdomain": "ffmpeg",
"fg_color": "#449D44",
"bg_color": "#449D44",
"project_url": "https://ffmpeg.org/",
"logo": "ffmpeg.png",
"git_commit_url_prefix": "https://github.com/FFmpeg/FFmpeg/commit/",
"github_search_url_prefix": "https://github.com/FFmpeg/FFmpeg/search?utf8=✓&q=",
"github_edit_cve_url_prefix": "https://github.com/VulnerabilityHistoryProject/ffmpeg-vulnerabilities/edit/dev/cves/",
"description": "\"FFmpeg is the leading multimedia framework, able to decode, encode,\ntranscode, mux, demux, stream, filter and play pretty much anything that humans\nand machines have created. It supports the most obscure ancient formats up to\nthe cutting edge. No matter if they were designed by some standards committee,\nthe community or a corporation. It is also highly portable: FFmpeg compiles, runs,\nand passes our testing infrastructure FATE across Linux, Mac OS X, Microsoft Windows,\nthe BSDs, Solaris, etc. under a wide variety of build environments, machine architectures,\nand configurations.\" -https://ffmpeg.org/\n",
"vulnerabilities_description": "These vulnerabilities are reported by the FFmpeg development\nteam [on their site](https://ffmpeg.org/security.html)\n",
"developers_description": "The following is a list of developers who are involved\nin code that was found to be vulnerable. Specifically, developers end up here\nif they were the author of a commit to code that was, at some point in time, fixed\nfor a vulnerability. Note that this is NOT a comprehensive list.\n"
}
]

overlaps

/api/tags/overlaps/array

Returns the vulnerabilities in common between the tags provided in decending order according to upvotes

query Parameters

overlaps

required

array of tag shortnames

The tags to find the overlaps of.

Responses

Response samples

200

Content type

application/json

null