API
VulDB provides a simple, reliable and efficient API. This interface allows to initiate queries for single entries or collection of items. It does also support transactional bots which implement robotic business process automation (BPA). For example collecting data in Splunk and other correlation tools. You may find code examples and various tools in our official GitHub repository
API Version
The current version of the API is 3.x. Support for older API versions is always guaranteed and can be enforced by adding version=1
to a request. The same major release is always backwards compatible regarding minor releases. A parser for 1.0 is also able to work with extension 1.2. But major release changes like from 1.2 to 2.0 demand new or upgraded parsing mechanisms.
All examples in this document are shown with the latest API release. Please always use the latest API release and consider migrating older parsers to the newest release to regain full compatibility, reliability, and new possibilities.
⚠️ Important: For business critical environments please add the parameter version=3
to the API requests of your parser. This enforces the use of the specific major release. Otherwise always the latest API version will be used (which unlocks the latest features automatically). If you are pinning API requests to an earlier release, you might get a warning as soon as a new major release is available. API 4.0 is already in the works.
Changelog
v3 | v2 | v1 | Date | Type | Changes |
---|---|---|---|---|---|
3.23 | - | - | 12/08/2020 | Feature | Added request type cursorinit to determine ideal initial cursor position for ongoing vulnerability stream (e.g. Splunk). |
3.22 | 2.19 | - | 12/04/2020 | Feature | Added field source_cve_cna which contains a string of the CVE Numbering Authority that assigned the CVE. |
3.21 | - | - | 04/17/2020 | Bugfix | The field entry_timestamp_change is now always present even if the entry was just created and never updated yet. In this case it will contain the same value like entry_timestamp_create . User of the official VulDB Splunk App are advised to update to the latest release. |
3.20 | - | - | 10/31/2019 | Feature | Added field family vulnerability_name which contains a string or array a popular names of the vulnerability (e.g. Shellshock, Poodle) |
3.19 | - | - | 09/13/2019 | Feature | Added field family entry_details_* which contain entry_details_affected , entry_details_vulnerability , entry_details_impact , entry_details_exploit , entry_details_countermeasures , and entry_details_sources |
3.18 | - | - | 08/31/2019 | Feature | Added field entry_replaces to display duplicates which have been replaced by this entry |
3.17 | - | - | 08/26/2019 | Feature | Added fields vulnerability_cvss3_basevector_vuldb and vulnerability_cvss3_tempvector_vuldb to display full VulDB CVSSv3 vectors easily |
3.16 | - | - | 06/04/2019 | Bugfix | Fixed value of field advisory_identifier , disabled safeguard mechanism to prevent inconsistency in result count |
3.15 | - | - | 05/17/2019 | Feature | Added fields software_website_vendor and software_website_product to the output |
3.14 | - | - | 05/08/2019 | Feature | Requesting dedicated CVSS fields supports the official response format (e.g. vulnerability_cvss3_vuldb_basescore ) and the legacy format (e.g. vulnerability_cvss3_basescore_vuldb ). The legacy format will be dropped in a future major release of the API. |
3.13 | 2.18 | 1.8 | 04/17/2019 | Feature | Added field software_cpe23 which introduces full CPE 2.3 support whereas software_cpe is still providing CPE 2.2 data |
3.12 | 2.17 | 1.7 | 03/04/2019 | Feature | Added fields entry_locked_status and entry_locked_reason to inform about entries undergoing update and review processes (they might change soon) |
3.11 | 2.16 | 1.6 | 02/20/2019 | Feature | Improved speed, reliability and accuracy of updates queries |
3.10 | - | - | 02/06/2019 | Feature | Added request parameter offset to set a starting point for results (pagination) |
3.9 | - | - | 01/18/2019 | Feature | Added field software_type |
3.8 | - | - | 01/11/2019 | Feature | VulDB CVSSv3 scores use AI-driven autocomplete based on historical data and additional sources. The field vulnerability_cvss3_vuldb_confidence indicates the confidence of the vectors |
3.7 | 2.15 | 1.5 | 01/08/2019 | Bugfix | Field software_component is not returning multiple fields anymore to prevent parsing errors |
3.6 | 2.14 | 1.4 | 12/13/2018 | Feature | Requesting details without unlocked archive access will warn in field entry_warning about limitation |
3.5 | - | - | 08/06/2018 | Feature | Support for the queries advisory_date_start , entry_timestamp_create_start , entry_timestamp_change_start |
3.4 | 2.13 | - | 06/12/2018 | Bugfix | Fixed enforcement of querylimit for details=0 queries (thanks to user "portal" for the report) |
3.3 | - | - | 06/11/2018 | Feature | Added CVSS meta score support with vulnerability_cvss3_meta |
3.2 | 2.12 | 1.3 | 06/06/2018 | Bugfix | Fixed wrong values in response_remaining (calculation was correct, value shown was wrong; thanks to user "portal" for the report) |
3.1 | 2.11 | 1.2 | 06/04/2018 | Bugfix | Fixed default sort order of recent and updates requests |
3.0 | - | - | 05/18/2018 | Change | Moved vulnerability_cpe to software_cpe |
- | 2.10 | - | 05/15/2018 | Feature | Added software_affectedlist and software_notaffectedlist , added vulnerability_risk (also shown in non-detail responses) |
- | 2.9 | - | 05/14/2018 | Feature | Detailed error messages regarding API key problems (missing , wrong , unknown , valid ), enterprise customers have performance priority over free users |
- | 2.8 | - | 05/08/2018 | Feature | entry_title does not show CVE anymore, added vulnerability_timeline , countermeasure_reactiondays , countermeasure_0daydays , countermeasure_exposuredays , and countermeasure_exploitdelaydays |
- | 2.7 | - | 05/07/2018 | Feature | Added support for request type topsoftware |
... | |||||
- | 2.0 | - | 01/22/2018 | Change | Response contains three elements (request , response , result ) instead just the results |
... | |||||
- | - | 1.0 | 12/01/2016 | Release | Initial release of Public API |
Authentication
To use the API, you have to own your individual API key. This key is generated as soon as you verify your new user account. Your API key can be found in your profile view
Accessing the API does not require a cookie-based session on the web site itself. The authentication data is sent as HTTP POST parameter or HTTP header.
If your personal API key got stolen and abused, please contact our support team immediately to invalidate and regenerate your API key for free.
Access Request Limit
The API access is limited by the number of requests and/or responses. It depends on your user rank and/or purchased API key license. The available API credits are shown in your user profile and included in the response section of an API reply. You are able to purchase API credits online.
Every request requires at least 1 credit, no matter if the response generated an error or returned valid results. It is possible to increase the detail level of results and to send complex queries. These might consume more credits as it is explained in the API documentation.
The moment you have reached the credit limit for your API access, further access is denied until your counter is reset. The amount of API credits is limited per 24 hours and is a moving window. You will regain your exhausted API credits the moment the request is older than 24 hours. If you need more API credits, please consider an upgrade of your account.
VulDB is also enforcing an anti-DDoS-protection. Please limit the number of requests you are executing per minute. It is suggested to state a maximum of 10 requests per minute. If you violate this paradigm, your account might be blocked for a few minutes and unblocked automatically. See the fields notification
and warning
in the response for more details about the current state of your API exchange.
Request Basics
To start an API query you have to do an HTTP POST request to the following resource:
https://vuldb.com/?api
Other languages are accessible by their respective URLs (e.g. https://vuldb.com/de/?api
for German). In this case all result field contents will be translated. The field names are always in English.
Every request must include your personal API key. You may propose it as part of the POST data with the field apikey
(you must enter the key without the brackets):
apikey=[your_personal_api_key]
As an alternative it is possible to use it as a custom HTTP request header named X-VulDB-ApiKey
:
X-VulDB-ApiKey: [your_personal_api_key]
Response Structure
The response will provide the results as JSON or XML structure. If within the request the field format
is left empty or defined as json
, the response will be JSON. If format
is set to xml
the response will be XML. The format of the response is shown within the response field format
.
A response contains three sections:
- response
- request
- result
Section response
The section response contains all header data of the returned response, like the header of an HTTP response.
Version
It will always contain the field version
which declares the version of the currently used API. Changes to the API will result in a new API version.
Minor releases are backward-compatible within the same major release. Major release changes require updates in parsing. In this case the field warning
is added and update suggested.
You can to pinpoint to a specific API major release by using the field version
in a request. Use this to guarantee stability and reliability for your automated processing.
Status
Every response also contains the field status
which shows the status code of the processed request. The status codes consist of a 3-digit number, similar to the ones used by HTTP. By nature, they might differ from the HTTP response code the web server returns for an API request. The most common API status codes are:
Status | Definition |
---|---|
200 | Request correct, allowed, processed and results returned |
204 | Request correct, allowed, processed but no results returned because they are empty |
401 | Authentication required, API key missing or unrecognized |
403 | API rate exceeded, no further requests allowed until counter reset |
405 | Unknown request type |
409 | API abuse suspected, no further requests possible until counter reset |
If the request or further processing was invalid, the response will contain the field error
which contains a human-readable description of the problem.
Type
If the request type is known and processed, the response section will contain the field type
which mirrors the request type. It will hold values like id
, recent
and search
for example. The field value
will contain the content that got requested. For example, the type
is set to id
and the value is set to 23
.
Count
If the response contains results, there will be the field items
(since APIv2) or count
(APIv1 only) which will hold the number of the returned results. This helps iterating through the result array. The maximum number of results is defined by query type and user account level. It is shown within the field querylimit
. This is used to prevent API credit and server resource exhaustion.
The fields consumption
and remaining
inform about the API credits used for the exchange and how many API credits are remaining.
Other Fields
There are other information like a timestamp of the request (timestamp), time of execution (rtt), limit of results for the query (querylimit), an unique ID for the data exchange (etag), and the language of the returned content (lang).
Section request
The section request contains the processed header data submitted with the prior request.
API-Key
The field apikey
indicates whether an API key was defined within the request. This field can hold the values missing
, wrong
, unknown
, and valid
. A successful request demands a valid
key.
Detail Level
By default, all queries just show only the basic information for an entry. By setting the field detail
to 1
in a request it is possible to show all details.
The field details
is 0
or 1
and declares if the results are basic or detailed. This difference influences the API credit consumption.
Sorting
There is the field sort
which indicates the database field which is used to sort the results. You may influence the sort order by proposing a sort
value yourself. The default sort order is set to entry_timestamp_create
(timestamp of the creation of a VulDB entry).
Offset / Pagination
Under certain circumstances a response might contain more results than displayed. To access results outside the default range 1-x
it is possible to use the request parameter offset
which expects an integer value.
If the default query would return the items 1-5
and you would propose offset=2
the response would contain the items 2-5
or 2-x
(if there are more than 5 items matching).
The field response_items
contains the number of items returned which is the current page size. This can be limited by the limit
parameter in the request.
The default and maximum page size vary regarding account type and request type. The maximum page size for your account/request is declared in response_querylimitmax
. The next page would be starting at the upper limit of your current page size. Commercial and enterprise users should have a maximum page size of 500
for most request types.
Section result
The section result contains the entries that match the request.
Result Count
Every entry is added as an array item and may be accessed within an iteration. The field items
(since APIv2) or count
(APIv1 only) in the section response declares how many items this array may hold.
Detail Fields
An entry contains all the requested fields. If details
is set to 1
, this might be many additional fields. Additional fields within a base query with details=0
can be displayed by using the parameter fields
in the request. Otherwise just the basic information is shown.
Requesting Vulnerability Entries
It is remarkably simple to request the details for a vulnerability entry. It is possible to show ID 67685 with the following POST request:
apikey=[your_personal_api_key]&id=67685
A request with curl looks like this (see the batch file example scripts in our GitHub repository):
curl -k --data "apikey=[your_personal_api_key]&id=67685" https://vuldb.com/?api
Example request with PHP (without curl extension, see the php example scripts in our GitHub repository):
$postdata = http_build_query( array( 'apikey' => '[your_personal_api_key]', 'id' => '67685' ) ); $opts = array('http' => array( 'method' => 'POST', 'content' => $postdata ) ); $context = stream_context_create($opts); $result = file_get_contents('https://vuldb.com/?api', false, $context);
The response might look like this:
{ "response": { "version": "3.19", "format": "json", "status": "200", "lang": "en", "items": 1, "consumption": 1, "remaining": 1999, "querylimit": 100, "querylimitmax": 500, "timestamp": "1569396339", "rtt": 0, "etag": "c7f8c6da025c3c8d-49e3ef31738dc04d-dcca48101505dd86" }, "request": { "timestamp": "1569396339", "apikey": "valid", "userid": "1", "details": 0, "sort": "entry_timestamp_create", "type": "id", "value": "67685" }, "result": [ { "entry": { "id": "67685", "title": "GNU Bash up to 3.2.48 Environment Variable variables.c privilege escalation", "timestamp": { "create": "1411593255", "change": "1539168525" } }, "vulnerability": { "risk": { "value": "3", "name": "high" } }, "advisory": { "date": "1411516800" }, "source": { "cve": { "id": "CVE-2014-6271" } } } ] }
By default replies just contain basic data points as shown:
entry_id
entry_title
entry_timestamp_create
entry_timestamp_change
vulnerability_risk_value
vulnerability_risk_name
advisory_date
source_cve_id
details
parameter to 1
.
Requesting Full Details
All request types deliver simply basic information about entries by default which will consume 1 API credit per request. It is possible to enable full details within results by setting details
to 1
which will cause that every vulnerability counts as a single point. This requires full access to the according entry (e.g. archive access unlocked for older entries). Example:
apikey=[your_personal_api_key]&id=67685&details=1
The results will contain additional fields:
{ "response": { "version": "3.19", "format": "json", "status": "200", "lang": "en", "items": 1, "consumption": 1, "remaining": 1998, "querylimit": 100, "querylimitmax": 500, "timestamp": "1569396209", "rtt": 0, "etag": "f81065ec5d5f6a50-dd867482c2cd761a-dcca48101505dd86" }, "request": { "timestamp": "1569396209", "apikey": "valid", "userid": "1", "details": 1, "sort": "entry_timestamp_create", "type": "id", "value": "67685" }, "result": [ { "entry": { "id": "67685", "title": "GNU Bash up to 3.2.48 Environment Variable variables.c privilege escalation", "summary": "A vulnerability was found in GNU Bash and classified as very critical. This issue affects some unknown functionality of the file variables.c of the component Environment Variable Handler. Applying a patch is able to eliminate this problem. The bugfix is ready for download at bugzilla.novell.com. The problem might be mitigated by replacing the product with Shell as an alternative. The best possible mitigation is suggested to be patching the affected component. A possible mitigation has been published even before and not after the disclosure of the vulnerability. Red Hat posted several mod_security rules which help to prevent exploitation of this vulnerability. It is also possible to enforce such a limitation with an IPTables rule: \"iptables using -m string --hex-string '|28 29 20 7B|'\" Attack attempts may be identified with Snort ID 31975. In this case the pattern () { is used for detection. Furthermore it is possible to detect and prevent this kind of attack with TippingPoint and the filter 16800. ", "details": { "affected": "A vulnerability was found in GNU Bash and classified as very critical.", "vulnerability": "The manipulation of the argument Environment with an unknown input leads to a privilege escalation vulnerability (Shellshock). Using CWE to declare the problem leads to CWE-78.", "impact": "Impacted is confidentiality, integrity, and availability.", "exploit": "A public exploit has been developed by Huzaifa Sidhpurwala in Bash and been published immediately after the advisory. It is declared as highly functional. The exploit is available at securityblog.redhat.com. We expect the 0-day to have been worth approximately $100k and more. The vulnerability scanner Nessus provides a plugin with the ID 77970 (Qmail Remote Command Execution via Shellshock), which helps to determine the existence of the flaw in a target environment. It is assigned to the family SMTP problems. The analysis with Nessus happens with this NASL code:if (rpm_check(release:"ALA", reference:"bash-4.1.2-15.19.amzn1")) flag++;\nif (rpm_check(release:"ALA", reference:"bash-debuginfo-4.1.2-15.19.amzn1")) flag++;\nif (rpm_check(release:"ALA", reference:"bash-doc-4.1.2-15.19.amzn1")) flag++;\n\nif (flag)\n{\n if (report_verbosity > 0) security_hole(port:0, extra:rpm_report_get());\n else security_hole(0);\n exit(0);\n}The commercial vulnerability scanner Qualys is able to test this issue with plugin 370037 (Citrix XenServer Security Update (CTX200223)). The code used by the exploit is:env x='() { :;}; echo vulnerable' bash -c "echo this is a test"", "countermeasure": "Applying a patch is able to eliminate this problem. The bugfix is ready for download at bugzilla.novell.com. The problem might be mitigated by replacing the product with Shell as an alternative. The best possible mitigation is suggested to be patching the affected component. A possible mitigation has been published even before and not after the disclosure of the vulnerability. Red Hat posted several mod_security rules which help to prevent exploitation of this vulnerability. It is also possible to enforce such a limitation with an IPTables rule: \"iptables using -m string --hex-string '|28 29 20 7B|'\" Attack attempts may be identified with Snort ID 31975. In this case the pattern () { is used for detection. Furthermore it is possible to detect and prevent this kind of attack with TippingPoint and the filter 16800.", "sources": "The vulnerability is also documented in the databases at SecurityFocus (BID 70137), X-Force (96209), Secunia (SA61541), SecurityTracker (ID 1030890) and Vulnerability Center (SBV-57351). access.redhat.com is providing further details. Similar entries are available at 67711 and 71528." }, "timestamp": { "create": "1411593255", "change": "1539168525" } }, "software": { "vendor": "GNU", "name": "Bash", "version": [ "1.14.0", "1.14.1", "1.14.2", "1.14.3", "1.14.4", "1.14.5", "1.14.6", "1.14.7", "2.0", "2.01", "2.01.1", "2.02", "2.02.1", "2.03", "2.04", "2.05", "3.0", "3.0.16", "3.1", "3.2", "3.2.48" ], "component": "Environment Variable Handler", "file": "variables.c", "argument": "Environment", "website": { "vendor": "https:\/\/www.gnu.org\/" }, "cpe": [ "cpe:\/a:gnu:bash:1.14.0", "cpe:\/a:gnu:bash:1.14.1", "cpe:\/a:gnu:bash:1.14.2", "cpe:\/a:gnu:bash:1.14.3", "cpe:\/a:gnu:bash:1.14.4", "cpe:\/a:gnu:bash:1.14.5", "cpe:\/a:gnu:bash:1.14.6", "cpe:\/a:gnu:bash:1.14.7", "cpe:\/a:gnu:bash:2.0", "cpe:\/a:gnu:bash:2.01", "cpe:\/a:gnu:bash:2.01.1", "cpe:\/a:gnu:bash:2.02", "cpe:\/a:gnu:bash:2.02.1", "cpe:\/a:gnu:bash:2.03", "cpe:\/a:gnu:bash:2.04", "cpe:\/a:gnu:bash:2.05", "cpe:\/a:gnu:bash:3.0", "cpe:\/a:gnu:bash:3.0.16", "cpe:\/a:gnu:bash:3.1", "cpe:\/a:gnu:bash:3.2", "cpe:\/a:gnu:bash:3.2.48" ], "cpe23": [ "cpe:2.3:a:gnu:bash:1.14.0:::::::*", "cpe:2.3:a:gnu:bash:1.14.1:::::::*", "cpe:2.3:a:gnu:bash:1.14.2:::::::*", "cpe:2.3:a:gnu:bash:1.14.3:::::::*", "cpe:2.3:a:gnu:bash:1.14.4:::::::*", "cpe:2.3:a:gnu:bash:1.14.5:::::::*", "cpe:2.3:a:gnu:bash:1.14.6:::::::*", "cpe:2.3:a:gnu:bash:1.14.7:::::::*", "cpe:2.3:a:gnu:bash:2.0:::::::*", "cpe:2.3:a:gnu:bash:2.01:::::::*", "cpe:2.3:a:gnu:bash:2.01.1:::::::*", "cpe:2.3:a:gnu:bash:2.02:::::::*", "cpe:2.3:a:gnu:bash:2.02.1:::::::*", "cpe:2.3:a:gnu:bash:2.03:::::::*", "cpe:2.3:a:gnu:bash:2.04:::::::*", "cpe:2.3:a:gnu:bash:2.05:::::::*", "cpe:2.3:a:gnu:bash:3.0:::::::*", "cpe:2.3:a:gnu:bash:3.0.16:::::::*", "cpe:2.3:a:gnu:bash:3.1:::::::*", "cpe:2.3:a:gnu:bash:3.2:::::::*", "cpe:2.3:a:gnu:bash:3.2.48:::::::*" ], "affectedlist": [ "Apple iPhone (Jailbreak only)", "Apple Mac OS X up to 10.9.4", "Debian GNU\/Linux up to 4.1-3\/4.2", "F5 BIG-IP up to 11.6.0", "Madravia Linux 1.0", "Palo Alto PAN-OS up to 6.0", "Red Hat Linux 4\/5\/6\/7", "Slackware Linux up to 14.1", "SuSE openSUSE 11.0", "Ubuntu Linux up to 14.04 LTS", "VMware Fusion" ], "notaffectedlist": [ "Android Default Installation\r", "FreeBSD Default Installation\r", "NetBSD Default Installation\r", "OpenBSD Default Installation" ] }, "vulnerability": { "risk": { "value": "3", "name": "high" }, "class": "privilege escalation", "cwe": "CWE-78", "cvss2": { "vuldb": { "basescore": "9.3", "tempscore": "7.3", "av": "N", "ac": "M", "au": "N", "ci": "C", "ii": "C", "ai": "C", "e": "POC", "rl": "OF", "rc": "C" } }, "cvss3": { "meta": { "basescore": "9.8", "tempscore": "8.8" }, "vuldb": { "confidence": "High", "basescore": "9.8", "tempscore": "8.8", "basevector": "AV:N\/AC:L\/PR:N\/UI:N\/S:U\/C:H\/I:H\/A:H", "tempvector": "E:P\/RL:O\/RC:C", "av": "N", "ac": "L", "pr": "N", "ui": "N", "s": "U", "c": "H", "i": "H", "a": "H", "e": "P", "rl": "O", "rc": "C" } }, "titleword": "Shellshock", "advisoryquote": "(...) a vulnerability in bash, related to how environment variables are processed: trailing code in function definitions was executed, independent of the variable name.", "timeline": [ { "date": "1410220800", "event": "CVE assigned", "color": "blue" }, { "date": "1410912000", "event": "Countermeasure disclosed", "diff": "+8 days", "color": "blue" }, { "date": "1411516800", "event": "Advisory disclosed", "diff": "+7 days", "color": "blue" }, { "date": "1411516800", "event": "Exploit disclosed", "diff": "+0 days", "color": "red" }, { "date": "1411516800", "event": "EDB entry disclosed", "diff": "+0 days", "color": "red" }, { "date": "1411516800", "event": "VulDB entry created", "diff": "+0 days", "link": "https:\/\/vuldb.com\/?recent.20140924", "color": "blue" }, { "date": "1411516800", "event": "NVD disclosed", "diff": "+0 days", "color": "blue" }, { "date": "1411516800", "event": "SecurityTracker entry created", "diff": "+0 days", "color": "blue" }, { "date": "1411516800", "event": "VulnerabilityCenter entry assigned", "diff": "+0 days", "color": "blue" }, { "date": "1411603200", "event": "SecurityFocus entry assigned", "diff": "+1 days", "color": "blue" }, { "date": "1411603200", "event": "Secunia entry created", "diff": "+0 days", "color": "blue" }, { "date": "1411948800", "event": "Nessus plugin released", "diff": "+4 days", "color": "blue" }, { "date": "1458086400", "event": "VulnerabilityCenter entry created", "diff": "+534 days", "color": "blue" }, { "date": "1466380800", "event": "VulnerabilityCenter entry updated", "diff": "+96 days", "color": "blue" }, { "date": "1539168525", "event": "VulDB last update", "diff": "+842 days", "link": "https:\/\/vuldb.com\/?id.67685", "color": "blue" } ] }, "advisory": { "date": "1411516800", "url": "http:\/\/seclists.org\/oss-sec\/2014\/q3\/649", "identifier": "remote code execution through bash", "reportconfidence": "confirmed", "person": { "name": "Stephane Chazelas" }, "advisoryquote": "Chet Ramey, the GNU bash upstream maintainer, will soon release official upstream patches." }, "exploit": { "availability": "1", "date": "1411516800", "publicity": "public", "url": "https:\/\/securityblog.redhat.com\/2014\/09\/24\/bash-specially-crafted-environment-variables-code-injection-attack\/", "developer": { "name": "Huzaifa Sidhpurwala" }, "language": "Bash", "exploitability": "highly functional", "price": { "0day": "$100k and more", "today": "$0-$1k" } }, "countermeasure": { "remediationlevel": "official fix", "name": "Patch", "date": "1410912000", "patch": { "url": "https:\/\/bugzilla.novell.com\/attachment.cgi?id=606672&action=edit" }, "alternative": { "name": "Shell" } }, "source": { "cve": { "id": "CVE-2014-6271", "assigned": "1410220800", "published": "1411516800", "summary": "GNU Bash through 4.3 processes trailing strings after function definitions in the values of environment variables, which allows remote attackers to execute arbitrary code via a crafted environment, as demonstrated by vectors involving the ForceCommand feature in OpenSSH sshd, the mod_cgi and mod_cgid modules in the Apache HTTP Server, scripts executed by unspecified DHCP clients, and other situations in which setting the environment occurs across a privilege boundary from Bash execution, aka \"ShellShock.\" NOTE: the original fix for this issue was incorrect; CVE-2014-7169 has been assigned to cover the vulnerability that is still present after the incorrect fix." }, "oval": { "id": "oval:org.mitre.oval:def:28331" }, "iavm": { "id": "2014-A-0142", "vmskey": "V0054753", "title": "GNU Bash Shell Code Execution Vulnerability" }, "osvdb": { "id": "112004", "title": "GNU bash Environment Variable Handling Shell Command Injection" }, "secunia": { "id": "61541", "date": "1411603200", "title": "GNU Bash Shell Function Definitions OS Commands Injection Vulnerability" }, "securityfocus": { "id": "70137", "date": "1411603200", "title": "GNU Bash CVE-2014-7169 Incomplete Fix Remote Code Execution Vulnerability", "class": "Design Error" }, "sectracker": { "id": "1030890", "title": "GNU bash Environment Variable Processing Flaw Lets Users Execute Arbitrary Code" }, "vulnerabilitycenter": { "id": "57351", "creationdate": "1458086400", "lastupdate": "1466380800", "reportingdate": "1411516800", "title": "GNU Bash through 4.3 Remote Code Execution via a Crafted Environment - CVE-2014-6271" }, "xforce": { "id": "96209", "identifier": "bash-cve20147169-command-exec", "title": "GNU Bash variables command execution", "risk": "High Risk" }, "exploitdb": { "id": "34765", "date": "1411516800" }, "heise": { "id": "2403305" }, "nessus": { "id": "77970", "date": "1411948800", "name": "Qmail Remote Command Execution via Shellshock", "filename": "ala_ALAS-2014-418.nasl", "family": "SMTP problems" }, "openvas": { "id": "871250", "title": "RedHat Update for bash RHSA-2014:1306-01", "filename": "gb_RHSA-2014_1306-01_bash.nasl", "family": "Red Hat Local Security Checks" }, "qualys": { "id": "370037", "title": "Citrix XenServer Security Update (CTX200223)" }, "saint": { "id": "exploit_info\/bash_shellshock_cups", "title": "Bash Environment Variable Handling Shell Command Injection Via CUPS", "link": "http:\/\/www.saintcorporation.com\/cgi-bin\/exploit_info\/bash_shellshock_cups" }, "metasploit": { "id": "apache_mod_cgi_bash_env.rb", "title": "Apache ActiveMQ Directory Traversal", "filename": "apache_mod_cgi_bash_env.rb" }, "snort": { "id": "31975", "class": "attempted-admin", "message": "Volex \u2013 Possible CVE-2014-6271 bash Vulnerability Requested (header)", "pattern": "() {" }, "suricata": { "id": "2014092401", "sig": "() {", "class": "attempted-admin" }, "issproventia": { "id": "2132121" }, "tippingpoint": { "id": "16800" }, "mcafeeips": { "id": "SMTP: EXPN Command Used", "version": "8.1.45.5" }, "fortigateips": { "id": "39294" }, "videolink": { "url": "https:\/\/youtu.be\/aa-O5EyCcKc" }, "misc": { "url": "https:\/\/access.redhat.com\/articles\/1200223" }, "seealso": [ "67711", "71528" ] } } ] }
A list of all available data points is available in the documentation
⚠️ Warning: By default enterprise customers are allowed to access the current year and the last two years. Access to earlier years requires an archive unlock per year. You are still possible to access archive entries without details. But if the unlock is not available, a warning is shown and details for the affected entry disabled.
⚠️ Warning: Be careful with detail queries like these because they might consume your API credits quite quickly. Especially if a query type is used to display multiple results (e.g. id list, search, date view). You may use the field limit
to limit the amount of maximum results.
Requesting Partial Details
Requesting data without details requires 1 API credit per request. And with details every result entry will demand 1 API credit. There might be situations where just a few more details are needed and therefore a full API request overblown.
In this case it is possible to use the optional parameter fields
to declare up to 3 additional fields within a simple request without full details. All fields found within a detail request can be defined here. An overview of all available data points is available in the documentation. For example:
vulnerability_cwe
vulnerability_cvss2_vuldb_basescore
vulnerability_cvss2_nvd_basescore
apikey=[your_personal_api_key]&id=67685&fields=vulnerability_cwe,vulnerability_cvss2_vuldb_basescore,vulnerability_cvss2_nvd_basescore
The result is enriched with the requested fields:
{ "response": { "version": "3.19", "format": "json", "status": "200", "lang": "en", "items": 3, "consumption": 1, "remaining": 1997, "querylimit": 100, "querylimitmax": 500, "timestamp": "1569396519", "rtt": 0, "etag": "285302e7a19f108f-339212fb83e8faa8-dcca48101505dd86" }, "request": { "timestamp": "1569396519", "apikey": "valid", "userid": "1", "details": 0, "sort": "entry_timestamp_create", "fields": "vulnerability_cwe,vulnerability_cvss2_vuldb_basescore,vulnerability_cvss2_nvd_basescore", "type": "id", "value": "5,23,42" }, "result": [ { "entry": { "id": "42", "title": "Cisco Secure ACS up to 3.1.1 on Windows Admin memory corruption", "timestamp": { "create": "1051056000", "change": "1528838409" } }, "vulnerability": { "risk": { "value": "2", "name": "medium" }, "cwe": "CWE-119", "cvss2": { "vuldb": { "basescore": "6.8" }, "nvd": { "basescore": "7.5" } } }, "advisory": { "date": "1051056000" }, "source": { "cve": { "id": "CVE-2003-0210" } } }, { "entry": { "id": "23", "title": "Linux Kernel up to 2.2.23 proc\/pid\/mem mmap PROT_READ denial of service", "timestamp": { "create": "1048809600", "change": "1516378012" } }, "vulnerability": { "risk": { "value": "1", "name": "low" }, "cwe": "CWE-404", "cvss2": { "vuldb": { "basescore": "1.9" }, "nvd": { "basescore": "2.1" } } }, "advisory": { "date": "1048809600" }, "source": { "cve": { "id": "CVE-2002-1380" } } }, { "entry": { "id": "5", "title": "Linux Kernel up to 2.4.19 privilege escalation", "timestamp": { "create": "1044316800", "change": "1496840061" } }, "vulnerability": { "risk": { "value": "1", "name": "low" }, "cwe": "CWE-269", "cvss2": { "vuldb": { "basescore": "4.1" }, "nvd": { "basescore": "3.6" } } }, "advisory": { "date": "1044316800" }, "source": { "cve": { "id": "CVE-2003-0018" } } } ] }
Simple requests with additional fields defined are handled like simple requests. No additional API credits are used. The applied fields are echoed within the field fields
as part of the request section in the response.
Requesting Multiple IDs
It is also possible to request multiple entries with a single request. Just delimit the IDs for the parameter id
with a comma.
apikey=[your_personal_api_key]&id=5,23,42
The response will contain all entries within the JSON array:
{ "response": { "version": "3.19", "format": "json", "status": "200", "lang": "en", "items": 3, "consumption": 1, "remaining": 1996, "querylimit": 100, "querylimitmax": 500, "timestamp": "1569396369", "rtt": 0, "etag": "d012a849effe05e7-4b18285a2d4d70a9-dcca48101505dd86" }, "request": { "timestamp": "1569396369", "apikey": "valid", "userid": "1", "details": 0, "sort": "entry_timestamp_create", "type": "id", "value": "5,23,42" }, "result": [ { "entry": { "id": "42", "title": "Cisco Secure ACS up to 3.1.1 on Windows Admin memory corruption", "timestamp": { "create": "1051056000", "change": "1528838409" } }, "vulnerability": { "risk": { "value": "2", "name": "medium" } }, "advisory": { "date": "1051056000" }, "source": { "cve": { "id": "CVE-2003-0210" } } }, { "entry": { "id": "23", "title": "Linux Kernel up to 2.2.23 proc\/pid\/mem mmap PROT_READ denial of service", "timestamp": { "create": "1048809600", "change": "1516378012" } }, "vulnerability": { "risk": { "value": "1", "name": "low" } }, "advisory": { "date": "1048809600" }, "source": { "cve": { "id": "CVE-2002-1380" } } }, { "entry": { "id": "5", "title": "Linux Kernel up to 2.4.19 privilege escalation", "timestamp": { "create": "1044316800", "change": "1496840061" } }, "vulnerability": { "risk": { "value": "1", "name": "low" } }, "advisory": { "date": "1044316800" }, "source": { "cve": { "id": "CVE-2003-0018" } } } ] }
⚠️ Warning: Keep in mind that full detail queries demand one credit per entry which will count towards the access limit. To limit exhaustion the number of requested IDs and the number of results is limited.
Recent and Updates Queries
It is possible to show the most recent entries with the request method recent
. The method itself demands a number of entries which shall be shown (similar to the limit
parameter in other query types):
apikey=[your_personal_api_key]&recent=10
apikey=[your_personal_api_key]&updates=10
The API credit demand is identical for both queries. As usual if the response contains full vulnerability information every entry returned will consume 1 API credit.
Requesting Timeframes
Sometimes a request for recent entries is not suitable. In this case it is possible to apply timeframes. There are two different approaches to do so.
List a specific Day
For example, if all entries created yesterday or a year ago should be listed. In this case a request with the following structure is possible to get all entries for a specific day:
apikey=[your_personal_api_key]&advisory_date=20180211
apikey=[your_personal_api_key]&entry_timestamp_create=20180211
apikey=[your_personal_api_key]&entry_timestamp_change=20180211
The request parameters advisory_date
(date of vulnerability disclosure), entry_timestamp_create
(VulDB entry added to the database) and entry_timestamp_change
(VulDB entry changed for the last time) can be used to get entries of a specific day. The date format uses YYYYMMDD
as structure.
Hint: If you want to establish an ongoing vulnerability management, you should prefer entry_timestamp_create
for prior dates or the current date. If you do so for the current day, keep in mind that the VulDB Mod Team is adding new entries 24 hours are day. Therefore, a single request will not suffice to keep the tracking complete.
List since a Specific Time
If all entries since a specific date should be listed, like 1518392525
in this example, the following queries are possible:
apikey=[your_personal_api_key]&advisory_date_start=1518392525
apikey=[your_personal_api_key]&entry_timestamp_create_start=1518392525
apikey=[your_personal_api_key]&entry_timestamp_change_start=1518392525
These queries expect an Unix timestamp as value. They are very useful as cursors in Splunk apps and alike. Take a look at the official Splunk app.
Keep in mind that the number of results is limited, and large requests should be split into smaller date chunks.
Establish a Steady Vulnerability Stream
If you want to establish a steady vulnerability stream there are different ways to do so. We may suggest the following timestamp pointer approach (as used by our official Splunk plugin):
1. Fetch with your initial request:
apikey=[your_personal_api_key]&entry_timestamp_create_start=[your_start_timestamp]
2. Determine the latest timestamp in entry_timestamp_create
of all returned entries, add 1 to it and use this as new starting point for your next request:
apikey=[your_personal_api_key]&entry_timestamp_create_start=[last_entry_timestamp_create_start+1]
This way you would not have to deal with pagination. You are able to reduce the amount of queries required by adding a high limit
value. Check the response header to see the maximum amount of items available within your license.
Search Queries
Furthermore it is possible to state search queries like they would be used in a search on the web site. The search
parameter needs to be URL encoded. For example PHP provides the function urlencode() to do so. The API request for Microsoft Windows looks like this:
apikey=[your_personal_api_key]&search=Microsoft%20Windows
It is also possible to search all other fields like CVE:
apikey=[your_personal_api_key]&search=CVE-2014-6271
Or you may use a CPE string to search for a specific product (this is an experimental feature at the moment):
apikey=[your_personal_api_key]&search=cpe:2.3:o:microsoft:windows_server_2019:::::::*
Such searches will display all matching vulnerabilities up to a certain amount of entries (depending on the license assigned to the account). As usual a simple query will cost 1 API credit no matter how many entries are included in the result.
Setting details
to 1
will deliver additional details about the vulnerabilities but every single result item will count towards the API request limit. So be careful while using this feature.
Advanced Search Queries
The common search queries use a string-based search to determine entries which are interesting. This might cause a large amount of results which may include entries not of real interest. In this case it might be useful to use an Advanced Search Query instead to narrow searches. The field can hold multiple search keys. The search keys are delimited by commas. And the field/search pair is delimited by colons. This example uses 3 search keys to look for Microsoft
(vendor), Windows
(product) and 10
(version):
apikey=[your_personal_api_key]&advancedsearch=vendor:Microsoft,product:Windows,version:10
The result will hold all entries containing these search keys in their according fields. The response structure is like the one of common Search Queries.
Supported are the following search keys:
Search Type | Keys |
---|---|
Fuzzy | vendor, product, version, component, function, argument, advisory (identifier), researcher, researcher_company, exploit_developer, exploit_language |
Exact | cve, bugtraq, osvdb, xforce, secunia, exploitdb, nessus |
Hint: It is nearly impossible to maintain accurate version listings in VulDB because most advisories lack accurate and complete version information. Therefore, it is suggested to only use version fields for well-known products - Try to use a conservative version definition (e.g. major version only) or use searches without versions at all and filter them afterwards.
Searching for CVE can be done very quick:
apikey=[your_personal_api_key]&advancedsearch=cve:CVE-2014-6271
The credit consumption of advanced search queries is the same as with simple search queries.
Individual Collection Queries
Enterprise customers have the capability to use Individual Collection Queries to get access to a pre-defined set of entries. This is often used as vendor or product-based collections within streamlined vulnerability management handling. Some example of common collections:
- All Microsoft products (except Windows Vista)
- All Oracle Java versions since 09/01/2018
- All products providing SSL capabilities
- All IoT devices with CVSSv3 base score above 6.9
collection
is used to request them. For example:
apikey=[your_personal_api_key]&collection=customer23_microsoft_without_vista
apikey=[your_personal_api_key]&collection=oracle_java_since_01042018
apikey=[your_personal_api_key]&collection=ssl_products
apikey=[your_personal_api_key]&collection=iot_cvss3_base_above_6.9
The name of the collection and the content can be defined by the customer. This makes it possible to provide a high level of anonymity. The multi-user capability of VulDB prevents other users from using, accessing or enumerating collections of other users. Please contact our support team to set-up your desired collections.
Sorting Results
Every successful response contains the field sort
in the request
section which indicates the field name which was used to sort the results. The default is the field entry_timestamp_create
which indicates the timestamp when the entry was created within the VulDB database.
You may be able to change the sort behavior with the request parameter sort
:
apikey=[your_personal_api_key]&search=Microsoft%20Windows&sort=source_cve
The following fields are supported for sorting:
id
entry_timestamp_create
entry_timestamp_change
advisory_date
source_cve
source_securityfocus
source_secunia
source_osvdb
Limiting Results
Some queries like search
might demand a lot of API credits (1 credit for every result within a full request) and generate a lot of data. To limit the API credit usage, the data output and to improve performance, you might use the limit
parameter to reduce the number of results included in the response:
apikey=[your_personal_api_key]&search=Microsoft%20Windows&sort=source_cve&limit=5
Queries which define a number of response items for themselves do not support the limit
parameter. These are typically recent
and updates
which will ignore limit
all the way.
Every request type has an internally hardcoded limit of results which is shown with the field querylimit
. The definition of limit
cannot exceed querylimit
or your remaining API credits. If a query has contradicting values, the smaller one will be used to prevent violation of policy.
Debugging
It is possible to see your recent API requests online in your user profile. This makes it possible to understand and debug API transactions. The debug log contains the full request and response headers. It does also list the items that were matching in this request.
An API request is logged if all of the following aspects are true:
Requirement | Prerequisite | Limit Log | No Log |
---|---|---|---|
personal API key valid | signup, account validated | - | 401 |
account allowed to use API | no lockout, no API limitations | - | 401 |
request type valid | correct API request | 403 | 405 |
Be aware that repeating error messages are only logged once per 10 minutes. If the error message of the same type is provoked again - for example 403 API rate exceeded
- the duplicate log entry will be ignored.
DDoS Protection
The services of VulDB are very well requested by people and customers all around the world. To prevent excessive fetching and destructive DDoS attacks (Distributed Denial of Service), the services have a DDoS Protection enabled. This protection tries to identify misbehavior and prevent attackers from influencing the experience of other users.
For example, a large amount of requests might cause an 429 Too Many Requests
HTTP error message. This message informs the requester how long the access got suspended. After this lockout further processing of requests is possible anymore.
In the first phase the lockout and unlocking happens automatically. In such cases we suggest that you increase the delay between your requests to prevent this effect. Usually a delay of 2-5 seconds should be enough to stay below the threshold.
If the problem persists, a permanent lockout might be enforced. In this case please contact the support team to discuss the possibilities.
License
Data requested via API underly the same license and terms like the rest of the web site.
You are able to purchase additional API credits online. If you are an enterprise customer with individual needs please contact us. We have different pricing models to match the individual needs of our customers.
Abuse of the API (e.g. flooding, key sharing, license violation) and misuse of the extracted data will be prosecuted technically and legally. See the Data Privacy Notice how data is processed on the web site. This is also applicable for the API interface.
Are you interested in using VulDB?
Download the whitepaper to learn more about our service!