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

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:

1. response
2. request
3. 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:

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

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:

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

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:

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.