Skip to content

Using custom fields from the API

Custom Fields allows you to extend the vulnerability's model by adding more fields. Custom Fields type can be int, str or list. You can learn more about Custom Fields creation on this Article.

In this small tutorial, we are going to use Python's library Requests and Faraday's API to authenticate, create a vulnerability and modify its Custom Fields.

Step 1: Authentication

To authenticate in Faraday, we are going to use a function called faraday_authentication(). This function will return an authenticated request session.

    def faraday_authentication(host, username, password):
           @host: Faraday server host, e.g:
           @username: Faraday username
           @password: username's password

           Return requests session object
        session = requests.Session()
        headers = {
            'Content-Type': 'application/json', # Very important! send this content-type header!!
        data = '{"email":username,"password": password}'
        response ='{0}/_api/login'.format(host), headers=headers, data=data)
        assert response.status_code == 200
        return session

Step 2: Create Custom Fields

In order to create a new Custom Field, follow the steps specified in this Article

Step 3: Create a vulnerability from the API

Before using the API, you need to understand how to send the data to the server. Faraday Server accepts JSON. Assuming that you created a custom field with the following data: * Field name: cvss, * Display name: CVSS And assuming that this vulnerability has as CVSS score "4", the JSON format for creating this vulnerability will be the following:

      "metadata": {
        "update_time": 1549569790.632,
        "update_user": "",
        "update_action": 0,
        "creator": "UI Web",
        "create_time": 1549569790.632,
        "update_controller_action": "UI Web New",
        "owner": "faraday"
      "obj_id": "",
      "owner": "faraday",
      "parent": 24,
      "parent_type": "Host",
      "type": "Vulnerability",
      "ws": "demo_workspace",
      "confirmed": true,
      "data": "",
      "desc": "Test",
      "easeofresolution": null,
      "impact": {
        "accountability": false,
        "availability": false,
        "confidentiality": false,
        "integrity": false
      "name": "dsadsadsa",
      "owned": false,
      "policyviolations": [],
      "refs": [],
      "resolution": "",
      "severity": "unclassified",
      "issuetracker": "",
      "status": "opened",
      "custom_fields": {
        "CVSS" : "4"
      "_attachments": {},
      "description": "",
      "protocol": "",
      "version": ""

Important Note that we have a key called "custom_fields" with its display name and its value:

    "custom_fields": {
      "CVSS" : "4"

Two important fields that we need to understand are parent_id and parent_type. In the JSON above, we specified them as follow:

     "parent_type" : "Host"
     "parent_id" : "24" 
This mean that in our database we have a Host with id 24. If you don't specify this two fields, you will get an invalid response.

You can learn more about the API Server by following this link.

Code sample for creating a vulnerability

Now, let's see a code sample that will create a new vulnerability called Test inside a workspace named demo_workspace. As vuln_payload we will use the JSON that we specified above:

faraday_host = ''
session = faraday_authentication(faraday_host, 'faraday', 'secret')
vulnerability_url = '{0}//_api/v3/ws/demo_workspace/vulns/386/'.format(faraday_host)
vuln_payload = '{"metadata":{"update_time":1549569790.632,"update_user":"","update_action":0,"creator":"UI Web","create_time":1549569790.632,"update_controller_action":"UI Web New","owner":"faraday"},"obj_id":"","owner":"faraday","parent":24,"parent_type":"Host","type":"Vulnerability","ws":"demo_workspace","confirmed":true,"data":"","desc":"dsadsadsa","easeofresolution":null,"impact":{"accountability":false,"availability":false,"confidentiality":false,"integrity":false},"name":"Test","owned":false,"policyviolations":[],"refs":[],"resolution":"","severity":"unclassified","issuetracker":"","status":"opened","custom_fields":{"CVSS" : "4"},"_attachments":{},"description":"","protocol":"","version":""}'
response =, json=vuln_payload)
The server is going to answer with the created vulnerability and it will return status code "201" (if the creation was successfull) or "409" (if there was any conflict). In our case it returned the status code "201" and a JSON with the response.

We can get the vulnerability id by getting the key "_id" from the JSON response. In this case, the vulnerability id is 386.

Important: If you didn't create the Custom Field (see step 2), it will not be seen in the vulnerability. Remember to create the custom field first.

Getting the vulnerability by its ID using the API Now you can do a GET request on the following url to see the vulnerability in JSON format. Note that we are using the same id as the one we get above (386):