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