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.

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"
    }
}

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