6 API reference

The api_sample.py demonstrates the ability to call a method or module, which will be querying the data from your own programs/scripts/products by importing the appropriate libraries.

Unified JSON response structure

The Python 3.x API returns data and error formatted using JSON with the respect, whenever it is possible, of the following structure:

Data response

    "source": [
      {
        "id": "identifier of the source",
        "parameters": {
          "class": "type or family of the identifier",
          "title": "title of the source,
          "file": "source file related to the identifier",
          "url": "link to source"
        }

Error response

{
  "object": "The impacted object",
  "status": "The whole captured error",
  "success": "status of the error such as false or true"
}

Here is a schema v1.2 to validate data structure.

Vulnerability information

Available methods

• get_info(): Retrieves basic vulnerability identifier and parameters (summary, published and modified dates)
• get_references(): Retrieves references (vendors and url)
• get_all(): Invokes both get_info() and get_references()

API snippet

from core.Information import Information

cve = "CVE-2017-5715"
info = Information(cve).get_info()
refs = Information(cve).get_references()
basic_data = Information(cve).get_all()

print(info)
print(refs)
print(basic_data)

Vulnerability classification

• get_targets(): Retrieves data related to the affected platforms and configurations (CPEs).
• get_packages(): Retrieves data related to the packages (vendor, product, affected version and the condition).
• get_weaknesses(): Returns information with all weaknesses and identifiers aligned with Mitre standards and other efforts (OWASP, WASC, etc ...)
• get_all(): Invokes both get_targets(), get_packages() and get_weaknesses()

API snippet

from core.Classification import Classification

cve = "CVE-2017-0199"
targets = Classification(cve).get_targets()
packages = Classification(cve).get_packages()
weaknesses = Classification(cve).get_weaknesses()
classification_data = Classification(cve).get_all()

print(targets)
print(packages)
print(weaknesses)
print(classification_data)

Vulnerability risk

Available methods

• get_cvss2(): Returns CVSS 2 vectors and scores
• get_cvss3(): Returns CVSS 3 vectors and scores
• get_cvss(): Invokes both get_cvss2() and get_cvss3()
• get_kev(): Returns KEV parameters
• get_epss(): Returns EPSS probability & percentile
• get_risk(): Returns all above (cvss, epss & kev)

API snippet

from core.Risk import Risk

cve = "CVE-2017-0199"
cvss2 = Risk(cve).get_cvss2()
cvss3 = Risk(cve).get_cvss3()
cvss = Classification(cve).get_cvss()

print(cvss2)
print(cvss3)
print(cvss)

API snippet

from core.Risk import Risk

cve = "CVE-2017-0199"
risk = Classification(cve).get_risk()

print(risk)

Vulnerability defense patches and rules

Available methods

• get_advisory(): Returns preventive data such fixes, bugs, bulletins & link to patches page.
• get_patches(): Returns list vulnerable packages, version fixed & non fixed and pactch status. As of today, this feature covers 4 vendors (Ubuntu, Debian, Redhat & Apache). It will be extended to Microsoft, IBM, Gentoo, Suse, Oracle & other vendors whenever the data is available.
• get_rules(): Retrieves detective data such IPS / IDS rules and more.
• get_all(): Invokes both get_advisory() and get_rules()

API snippet

# only preventive data
from core.Defense import Preventive

cve = "cve-2017-5638"
advisory = Preventive(cve).get_advisory()
print(advisory)

cve = "CVE-2011-3597"
patches = Preventive(cve).get_patches()
print(patches)

# only detective data 
from core.Defense import Detective

cve = "CVE-2017-5638"
rules = Detective(cve).get_rules()
print(rules)

# Now lets do all
from core.Defense import Defense

cve = "CVE-2017-5638"
defense_data = Defense(cve).get_all()
print(defense_data)

Vulnerability inspection signatures

Available methods

• get_remote(): Returns remote signatures of network/application scanners
• get_local(): Retrieves local signatures of host scanners
• get_all(): Invokes both get_remote() and get_local()

API snippet

# only preventive data
from core.Inspection import Inspection

cve = "CVE-2017-5715"
remote_sig = Inspection(cve).get_remote()
local_sig = Inspection(cve).get_local()
scanners = Inspection(cve).get_all()

print(remote_sig)
print(local_sig)
print(scanners)

Vulnerability exploitation PoCs

Available methods

• get_exploits(): Returns exploits and PoCs useful data from different sources

API snippet

from core.Exploitation import Exploitation

cve = "CVE-2017-5715"
exploits = Exploitation(cve). get_exploits()

print(exploits)

Vulnerability exporting

Available methods

• dump_json(): Exports vulnerability information and attributes into a JSON format. This module calls all available methods and stores the information into a JSON file. The file is moved to the export directory.
• dump_yaml(): Exports vulnerability information and attributes into a YAML format. This module calls all available methods and stores the information into a YAML file. The file is moved to the export directory.

API snippet

from core.Export import Export

cve = "CVE-2017-5715"
Export(cve).dump_json()
Export(cve). dump_yaml()

Updating the main vulnerability and threat database

Available methods

• update(): Updates automatically the vulnerability and threat database whenever the license keys are valid.

API snippet

from lib.Update import Update

Update().update()

Basic search module

Available methods

• search_cve(): Searches for CVE and returns basic information regarding the vulnerability.
• search_cwe(): Searches for CWE and returns all vulnerabilities that affect the CWE.
• search_cpe(): Searches for CPE (2.2 or 2.3 format) and returns all vulnerabilities that affect the target.

API snippet

from lib.Search import Search

cpe = "cpe:/a:apache:tomcat:7.0.5"
print(Search(cpe).search_cpe())

cpe = "cpe:2.3:a:adobe:flash_player:*:*:*:*:*:*:*:*"
print(Search(cpe).search_cpe())

cve = "cve-2017-3100"
print(Search(cve).search_cve())

cwe = "cwe-89"
print(Search(cve).search_cwe())