Nessus API for hosts scanning

When I was writing earlier about Nessus API (“Retrieving scan results through Nessus API“) I have not mentioned how to create a new vulnerability scan task and launch it fully automatically. I assumed that all vulnerability scan entities was already created and scheduled in GUI, how it is often happens in a real life. However, managing the scans via Nessus API (run, pause, resume, stop) may be also useful, for example, when we need to automatically update vulnerability status of some host. Creating scan policy with API will be still out of scope of this post. We assume, that scan policy already exists.

Nessus API for scan management

API Description is still at https://192.168.56.101:8834/api# (where 192.168.56.101 is the IP address of your Nessus host). How to install Nessus read in “Tenable Nessus: registration, installation, scanning and reporting“.

Authentication

We need to get a token for authentication:

curl -s -k -X POST -H 'Content-Type: application/json' -d "{\"username\":\"admin\",\"password\":\"password\"}" https://192.168.56.101:8834/session

{"token":"0fadbb405516ff8b903450276d08ff603f2929cecbad99a2"}

Creating New Folder

Let’s create a new folder for our further new scan. To see what folders in Nessus we have run:

curl -s -k -X GET -H "X-Cookie: token=0fadbb405516ff8b903450276d08ff603f2929cecbad99a2" https://192.168.56.101:8834/folders | python -m json.tool

{
    "folders": [
        {
            "custom": 0,
            "default_tag": 1,
            "id": 313,
            "name": "My Scans",
            "type": "main",
            "unread_count": 1
        },
        {
            "custom": 0,
            "default_tag": 0,
            "id": 314,
            "name": "Trash",
            "type": "trash",
            "unread_count": null
        }
    ]
}

To create a new folder we need to send a POST request to https://192.168.56.101:8834/folders with parameter “name”.

curl -s -k -X POST -H "X-Cookie: token=0fadbb405516ff8b903450276d08ff603f2929cecbad99a2" -H 'Content-Type: application/json' -d '{"name": "new_folder"}' https://192.168.56.101:8834/folders

{"id":2538}

Hear it is a “new_folder”:

curl -s -k -X GET -H "X-Cookie: token=0fadbb405516ff8b903450276d08ff603f2929cecbad99a2" https://192.168.56.101:8834/folders | python -m json.tool

{
    "folders": [
        {
            "custom": 0,
            "default_tag": 1,
            "id": 313,
            "name": "My Scans",
            "type": "main",
            "unread_count": 1
        },
        {
            "custom": 0,
            "default_tag": 0,
            "id": 314,
            "name": "Trash",
            "type": "trash",
            "unread_count": null
        },
        {
            "custom": 1,
            "default_tag": 0,
            "id": 2538,
            "name": "new_folder",
            "type": "custom",
            "unread_count": null
        }
    ]
}

Creating New Scan

Ok, now we have to specify a scan policy for our new scan:

curl -s -k -X GET -H "X-Cookie: token=0fadbb405516ff8b903450276d08ff603f2929cecbad99a2" https://192.168.56.101:8834/policies | python -m json.tool

{
    "policies": [
        {
            "creation_date": 1432550082,
            "description": "",
            "id": 21,
            "last_modification_date": 1439817361,
            "name": "My_scan_policy",
            "no_target": "false",
            "owner": "admin",
            "owner_id": 2,
            "shared": 1,
            "template_uuid": "ad629e16-03b6-8c1d-cef6-ef8c9dd3c658d24bd260ef5f9e66",
            "user_permissions": 32,
            "visibility": "shared"
        }
    ]
}

As you can see, this is some scan policy I made earlier in GUI. Of course, you can do it also with API, but I think it would be more logical to keep this for another post.

Now let’s create a new scan task using My_scan_policy we need scan_id and template_uuid. We also need to specify ip addresses which we want to scan: one or several separated with “,”. In this example we specify folder_id, but it’s optional, if you don’t set this parameter scan will be created in the default “My Scans” folder.

curl -s -k -X POST -H "X-Cookie: token=0fadbb405516ff8b903450276d08ff603f2929cecbad99a2" -H 'Content-Type: application/json' -d '{"uuid": "ad629e16-03b6-8c1d-cef6-ef8c9dd3c658d24bd260ef5f9e66", "settings": { "name": "new_scan", "text_targets": "scantarget.corporation.com", "policy_id": "21", "folder_id":"2538" } }' https://192.168.56.101:8834/scans | python -m json.tool

{
    "scan": {
        "container_id": 0,
        "creation_date": 1475589009,
        "custom_targets": "scantarget.corporation.com",
        "dashboard_file": null,
        "default_permisssions": 0,
        "description": null,
        "emails": null,
        "enabled": true,
        "id": 2569,
        "last_modification_date": 1475589010,
        "name": "new_scan",
        "notification_filters": null,
        "owner": "admin",
        "owner_id": 4,
        "policy_id": 21,
        "rrules": null,
        "scan_time_window": null,
        "scanner_id": 1,
        "shared": 0,
        "sms": null,
        "starttime": null,
        "tag_id": 2538,
        "timezone": null,
        "type": "public",
        "use_dashboard": false,
        "user_permissions": 128,
        "uuid": "template-1ce406ae-4216-3956-c0d0-8c54b858ecafc4d8dca3232c26e3"
    }
}

Nessus New Scan created with API

Start Scanning

Ok, we have the scan entity. Let’s run it:

curl -s -k -X POST -H "X-Cookie: token=0fadbb405516ff8b903450276d08ff603f2929cecbad99a2" -d '' https://192.168.56.101:8834/scans/2569/launch

{"scan_uuid":"05223571-aeb5-6dca-f2e6-cf54f69028c66f031fa5087646d4"}

Checking status using GET request to https://192.168.56.101:8834/scans/2569 :

{
...
    "info": {
        "acls": [
            {
                "display_name": null,
                "id": null,
                "name": null,
                "owner": null,
                "permissions": 0,
                "type": "default"
            },
            {
                "display_name": "admin",
                "id": 4,
                "name": "admin",
                "owner": 1,
                "permissions": 128,
                "type": "user"
            }
        ],
        "alt_targets_used": null,
        "control": true,
        "edit_allowed": true,
        "folder_id": 2538,
        "hasaudittrail": true,
        "haskb": false,
        "hostcount": 1,
        "name": "new_scan",
        "no_target": null,
        "object_id": 2569,
        "pci-can-upload": false,
        "policy": "My_scan_policy",
        "scan_start": 1475589234,
        "scan_type": "local",
        "scanner_name": "Local Scanner",
        "scanner_start": 1475589234,
        "status": "running",
        "targets": "scantarget.corporation.com",
        "timestamp": 1475589234,
        "user_permissions": 128,
        "uuid": "05223571-aeb5-6dca-f2e6-cf54f69028c66f031fa5087646d4"
    },
...
}

Some minutes later the status will be changed. Run the same command:

{
    "info": {
        "acls": [
            {
                "display_name": null,
                "id": null,
                "name": null,
                "owner": null,
                "permissions": 0,
                "type": "default"
            },
            {
                "display_name": "admin",
                "id": 4,
                "name": "admin",
                "owner": 1,
                "permissions": 128,
                "type": "user"
            }
        ],
        "alt_targets_used": null,
        "control": true,
        "edit_allowed": true,
        "folder_id": 2538,
        "hasaudittrail": true,
        "haskb": true,
        "hostcount": 1,
        "name": "new_scan",
        "no_target": null,
        "object_id": 2569,
        "pci-can-upload": false,
        "policy": "My_scan_policy",
        "scan_end": 1475593001,
        "scan_start": 1475589234,
        "scan_type": "local",
        "scanner_end": 1475592997,
        "scanner_name": "Local Scanner",
        "scanner_start": 1475589234,
        "status": "completed",
        "targets": "scantarget.corporation.com",
        "timestamp": 1475593001,
        "user_permissions": 128,
        "uuid": "05223571-aeb5-6dca-f2e6-cf54f69028c66f031fa5087646d4"
    },
...
}

You can export scan results with Nessus API using the recommendations from my post “Retrieving scan results through Nessus API

Cleaning

To delete the scan make a request:

curl -s -k -X DELETE -H "X-Cookie: token=0fadbb405516ff8b903450276d08ff603f2929cecbad99a2" https://192.168.56.101:8834/scans/2569

If the output is empty, you have done it right. If id is not exist, you will get an error:

{"error":"The requested file was not found"}

To delete a folder run similar command:

curl -s -k -X DELETE -H "X-Cookie: token=0fadbb405516ff8b903450276d08ff603f2929cecbad99a2" https://192.168.56.101:8834/folders/2538

7 thoughts on “Nessus API for hosts scanning

  1. Pingback: Tenable Nessus: registration, installation, scanning and reporting | Alexander V. Leonov

  2. Pingback: Nessus Manager and Agents | Alexander V. Leonov

  3. Pingback: Automated task processing with JIRA API | Alexander V. Leonov

  4. Pingback: Retrieving scan results through Nessus API | Alexander V. Leonov

  5. Viacheslav

    Hi Alexandr,
    After launching the scan you are checking the scan status. What command do you use to retrieve the status?
    Mostly am interested in this part: “acls”: [
    {
    “display_name”: null,
    “id”: null,
    “name”: null,
    “owner”: null,
    “permissions”: 0,
    “type”: “default”
    },
    {
    “display_name”: “admin”,
    “id”: 4,
    “name”: “admin”,
    “owner”: 1,
    “permissions”: 128,
    “type”: “user”
    }
    ],

    Reply
  6. CZA

    I tried what you described but always end up with an:
    {“error”:”API is not available”}

    error, when I want to start a scan using a small bash script. The rest to prepare this (getting token, creating folder, getting policy ids) works like a charm.

    Im not sure but it looks like Tennable disabled the usage for the Nessus Professional API to push their tenable.io plattfom. But im not sure entirely if Im correct with this. I Just want to start a nessus scan via a small bash script instead setting up the scan manually.

    Thanks for the help!
    Best regards,
    Constantin

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.