Skip to content

API reference

Python 3 library for the Vulners Perimeter Scanner. It provides basic project management and data retrieval API for the automation and integration purposes.

Requirements

  • Python: Library was tested on a python3.

  • API key: Please, sign up at Vulners. Go to the personal menu by clicking at your name at the right top corner. Follow API KEYS tab. Generate API key with scope "api" and use it with the library.

Disclaimer

In examples below localhost is used as IP address, but Perimeter Scanner works only with public hosts. Also uuides are shortened in examples, not in real data.

Getting started

All the callable methods are using Vulners REST API. Automate your audit routines with Vulners. To get started you need to know your license id and control api quota left:

import vulners

vulners_api = vulners.VulnersVscanner(api_key="YOUR_API_KEY_HERE")

license_id = vulners_api.license()
license_quota = vulners_api.quota(license_id[0])

{
    "licenseList": [
        {
            "id": "e0671ce0-..-bbb",
            "type": "free",
            "expiration": "2999-01-01T00:00:00"
        },
        {
            "id": "d4657eb6-..-9d7",
            "type": "vnmap-professional",
            "expiration": "2022-04-15T00:00:00"
        },
        {
            "id": "319b1ad1-..-45d",
            "type": "professional",
            "expiration": "2022-04-15T00:00:00"
        }
    ]
}
{
    "daily_quota": 102400, 
    "hourly_quota": 10240
}

Project management

To get started you should create new project. Project has three required parameters: name, notification and license id. Notification is an object, containing options such as period ("disabled", "asap", "hourly" or "daily") and method (via either or both email and slack). You can use method notification to create notification object, or method disabled_notification if you don't want to get notifications. So create new project with this code:

Create project

notification = vulners_api.notification("daily",
                                    ['email1@gmail.com'], 
                                    ["https://hooks.slack.com/services/..."])
# if no notifications needed
# notification = vulners_api.disabled_notification()

project = vulners_api.project(project_name="my project", 
                              license="0305fbd1-..-8a7", 
                              notification=notification)

{
    "_id": "4e0a9778-..-4d0",
    "name": "my project",
    "owner": "e5bc65b8-..-675",
    "license": {
        "id": "0305fbd1-..-8a7",
        "name": "vnmap-professional:7a11ad6558a7",
        "exp": 1649970000.0,
        "max_hosts": 256,
        "max_tasks": 5,
        "daily_quota": 102400,
        "hourly_quota": 10240,
        "timing": 3,
        "ports": "False"
    },
    "tasks_count": 0,
    "tasks": [],
    "admins": [],
    "viewers": [],
    "notification": {
        "period": "daily", 
        "email": ["email1@gmail.com"],  
        "slack": ["https://hooks.slack.com/services/..."]
    }
}

Edit project

With method project you can also edit existing project parameters. To set new values you should additionally specify project id. You should specify all parameters explicitly, otherwise it will be overwritten.

project = vulners_api.project(project_id=project['_id'],
                              project_name="new project name",
                              license=project['license']['id'],
                              notification = project['notification']
                              )

{
    "_id": "4e0a9778-..-4d0",
    "name": "new project name",
    "owner": "e5bc65b8-..-675",
    "license": {
        "id": "0305fbd1-..-8a7",
        "name": "vnmap-professional:7a11ad6558a7",
        "exp": 1649970000.0,
        "max_hosts": 256,
        "max_tasks": 5,
        "daily_quota": 102400,
        "hourly_quota": 10240,
        "timing": 3,
        "ports": "False"
    },
    "tasks_count": 0,
    "tasks": [],
    "admins": [],
    "viewers": [],
    "notification": {
        "period": "daily", 
        "email": ["email1@gmail.com"],  
        "slack": ["https://hooks.slack.com/services/..."]
    }
}

Get project data

Using this method, you can also get data about existing projects:

projects = vulners_api.projects()

[{
    "_id": "4e0a9778-..-4d0",
    "name": "new project name",
    "owner": "e5bc65b8-..-675",
    "license": {
        "id": "0305fbd1-..-8a7",
        "name": "vnmap-professional:7a11ad6558a7",
        "exp": 1649970000.0,
        "max_hosts": 256,
        "max_tasks": 5,
        "daily_quota": 102400,
        "hourly_quota": 10240,
        "timing": 3,
        "ports": "False"
    },
    "tasks_count": 0,
    "tasks": [],
    "admins": [],
    "viewers": [],
    "notification": {
        "period": "daily", 
        "email": ["email1@gmail.com"],  
        "slack": ["https://hooks.slack.com/services/..."]
    }
}]

Delete project

To delete project you can use this method:

result = vulners_api.delete_project(project['_id'])

None in case of success, or error message

Task Management

Second step is creating tasks. Task schedules network scan. To create task you should specify parent project id, task name, list of networks, enabled flag and schedule string.

Schedule string is a crontab string. It is a set of five fields which represent the time to execute the task. Crontab string contains following fields

minutes[0-59] hours[0-23] day_of_month[1-31] month[1-12] day_of_week[1-7]

Crontab string construction is quite complicated for our API refference, so you can use this manual and generator: crontab guru

Here are some examples

'*/10 * * * *' means "Task will start every 10th minute"
'0 10 * * *' means "Task will start at 10am every day"
'0 10 1 5 *' means "Task will start at 10am every first day of May"
'0 10 * * 1' means "Task will start at 10am every monday"

Create new task

To create new task use following method:

first_task = vulners_api.task(project_id=project['_id'],
                     name="first task",
                     networks=['example.com', '127.0.0.1'],
                     schedule='* 10 * * 1',
                     enabled=True
                     )

{
    "_id": "52d0f18b-..-b60",
    "name": "first task",
    "schedule": "* 10 * * 1",
    "networks": [
        "example.com",
        "127.0.0.1"
    ],
    "validated_networks": [
        "127.0.0.1/32",
        "127.0.0.1/32"
    ],
    "enabled": "False",
    "valid": "True",
    "total_hosts": 1,
    "project_id": "4e0a9778-..-4d0",
    "license": {
        "id": "0305fbd1-..-8a7",
        "name": "vnmap-professional:7a11ad6558a7",
        "exp": 1649970000.0,
        "max_hosts": 256,
        "max_tasks": 5,
        "daily_quota": 102400,
        "hourly_quota": 10240,
        "timing": 3,
        "ports": "False"
    },
    "next_run": 1621850400.0,
    "last_run": 0,
    "resolved": [
        "127.0.0.1",
        "example.com"
    ],
    "state": "disabled"
}

Edit task

To modify task parameters you should also specify existing task id. 

first_task = vulners_api.task(project_id=project['_id'],
                     name="first task",
                     networks=['example.com', '127.0.0.1'],
                     schedule='* 10 * * 2',
                     enabled=True,
                     task_id=first_task['_id']
                     )

{
    "_id": "52d0f18b-..-b60",
    "name": "first task",
    "schedule": "* 10 * * 2",
    "networks": [
        "example.com",
        "127.0.0.1"
    ],
    "validated_networks": [
        "127.0.0.1/32",
        "127.0.0.1/32"
    ],
    "enabled": "False",
    "valid": "True",
    "total_hosts": 1,
    "project_id": "4e0a9778-..-4d0",
    "license": {
        "id": "0305fbd1-..-8a7",
        "name": "vnmap-professional:7a11ad6558a7",
        "exp": 1649970000.0,
        "max_hosts": 256,
        "max_tasks": 5,
        "daily_quota": 102400,
        "hourly_quota": 10240,
        "timing": 3,
        "ports": "False"
    },
    "next_run": 1621850400.0,
    "last_run": 0,
    "resolved": [
        "127.0.0.1",
        "example.com"
    ],
    "state": "disabled"
}

Force task

When task is enabled, it will start according your schedule. If needed, task can be forced with method start_task like this

first_task = vulners_api.start_task(project_id=project['_id'],
                     task_id=first_task['_id']
                     )

{
    "_id": "52d0f18b-..-b60",
    "name": "first task",
    "schedule": "* 10 * * 2",
    "networks": [
        "example.com",
        "127.0.0.1"
    ],
    "validated_networks": [
        "127.0.0.1/32",
        "127.0.0.1/32"
    ],
    "enabled": "False",
    "valid": "True",
    "total_hosts": 1,
    "project_id": "4e0a9778-..-4d0",
    "license": {
        "id": "0305fbd1-..-8a7",
        "name": "vnmap-professional:7a11ad6558a7",
        "exp": 1649970000.0,
        "max_hosts": 256,
        "max_tasks": 5,
        "daily_quota": 102400,
        "hourly_quota": 10240,
        "timing": 3,
        "ports": "False"
    },
    "next_run": 1621850400.0,
    "last_run": 0,
    "resolved": [
        "127.0.0.1",
        "example.com"
    ],
    "state": "disabled"
}

Delete task

You can delete task with method delete_task.

result = vulners_api.delete_task(project_id=project['_id'],
                     task_id=first_task['_id'])

None in case of success, or error message

Reports

Get results

Final step is getting results. When task finishes, you can get scanning results. Just call method results with project id

result = vulners_api.result(project_id=projects[0]['project_id'])

{
    "_id": "62d6eab7-..-92b",
    "project_id": "4e0a9778-..-4d0",
    "ip": "127.0.0.1",
    "addr": 846214729,
    "name": "example.com",
    "resolved": "",
    "published": "2021-04-15T13:59:03Z",
    "scan_info": [
        {
            "port": "22",
            "protocol": "tcp",
            "service": "ssh",
            "product": "OpenSSH",
            "version": "8.2p1 Ubuntu 4ubuntu0.1",
            "ostype": "Linux",
            "extrainfo": "Ubuntu Linux; protocol 2.0",
            "cpe": "cpe:/a:openbsd:openssh:8.2p1",
            "vulnerabilities": [
                {
                    "id": "CVE-2020-12062",
                    "cvss": 5.0
                },
                {
                    "id": "CVE-2020-14145",
                    "cvss": 4.3
                },
                {
                    "id": "CVE-2020-15778",
                    "cvss": 6.8
                },
                {
                    "id": "CVE-2021-28041",
                    "cvss": 4.6
                },
                {
                    "id": "MSF:AUXILIARY/SCANNER/SSH/FORTINET_BACKDOOR/",
                    "cvss": 0.0
                }
            ]
        }
    ]
}

Clean up results

Sometimes it may be useful to cleanup your data. You can delete scan results with method delete_results.

result = vulners_api.delete_results(project_id=project['_id'])

None in case of success, or error message
Back to top