scanapi is a small REST API that exposes functionality of a Nessus server to users or applications. This interface can be used to primarily execute scans using the Nessus server, and fetch results. The primary intent is to provide a more limited / restricted interface than is possible communicating directly with the Nessus API, and simplify creating scans and fetching results.
< users > --------> < scanapi > --------> < nessus >
The repo contains two primary components.
This is the API itself which will interact with Nessus on your behalf. You can install or run this if you want to run your own API instance.
This is a command line tool that can be used to interact with an existing scanapi instance, to create scans or fetch results from the instance. Using runscan is not required if you want to interact with scanapi yourself by making your own requests.
$ git clone https://github.com/mozilla/scanapi.git
$ cd scanapi
$ virtualenv myenv
$ source myenv/bin/activate
$ pip install -r requirements.txt
If you want to run your own scanapi API instance, it needs to be configured to interact with the Nessus server. If you just want runscan, skip to the later documentation section.
Copy scanapi.yml.example and edit it as required.
$ cd scanapi
$ cp scanapi.yml.example scanapi.yml
You will need to create a user in your Nessus server that scanapi will authenticate to Nessus as, and you need to create Nessus API keys for that user (generally done in the Nessus console). These keys should be added to the scanapi configuration file.
The zone
value can be set to a name that will be included in the result set, to
differentiate the results from other instances of scanapi that may be running.
The appkeys
section can be used to specify application keys, one of which
must be sent in the SCANAPIKEY header to authenticate when making requests to the
API. If no appkeys
section is present, no authentication against scanapi will
occur.
The enrichment
section can be used to specify external data sources used to
supplement returned results. The rpm2cve
option if specified, will read
rpm-to-cve.xml
(available from RedHat) from the file system and add vulnerable
package details to result entries specifically for RHSAs. The exemptplugins
option if specified indicates a file containing plugins IDs that will be excluded
from the vulnerabilities section of a result set. Results for matching plugins will
instead be included in the exempt_vulnerabilities section of the result.
Policies available to the user scanapi uses to talk to Nessus will be available to use for scans using scanapi.
Note that when creating a policy, ensure the Nessus policy option that removes plugin results for plugins called as a dependency is disabled. We want to make sure the results of these plugins are included in the result set, as they are used to piece together various information about the asset by scanapi.
scanapi can be run directly for testing.
$ ./scanapi.py
For actual use, you would generally configure it with nginx and uwsgi.
Supported API endpoints in scanapi, see scanapi or runscan code for details. All API responses are returned as JSON, with the exception of the raw CSV report request which is returned as text.
Parameters:
- None
Return status.
Purges any old scans created by scanapi from Nessus.
Parameters:
olderthan
: Integer, specifies minimum age in seconds of scans to be purged
Returns a status message.
Create a new scan in Nessus, against the indicated targets using the indicated policy.
Parameters:
targets
: Comma separated list of IP addresses or hostnames to scanpolicy
: A policy name, list of available policies can be queries via the policies endpoint
Returns a scan ID which can be used to fetch results.
Fetch the results of a scan, formatted into a JSON document.
Parameters:
scanid
: UUID, the scan ID to get results formincvss
: Float, instructs scanapi to only include vulnerabilities >= mincvssnooutput
: If set, plugin output will not be included in the results
Returns JSON formatted results.
Fetch the raw CSV results of a scan.
Parameters:
scanid
: UUID, the scan ID to get results for
Returns text content CSV report.
Get a list of policies that can be specified when running a scan.
Parameters:
- None
Returns list of available policies.
runscan is a command line tool that can be used to talk to scanapi. You need to set
a couple environment variables. You need to ensure the requirements listed in
requirements.txt
are installed, either globally or in a virtualenv to run
runscan.
- SCANAPIURL - Set to URL where scanapi is listening
- SCANAPIKEY - Set to an API key you configured in scanapi.yml if needed
$ ./runscan.py -h usage: runscan.py [-h] [--noverify] [--csv] [--filter-subnets subnetsfile] [--mozdef mozdefurl] [--mincvss cvss] [--nooutput] [--serviceapi sapiurl] [-s targets] [-p policy] [-D seconds] [-f] [-P] [-r scan id] optional arguments: -h, --help show this help message and exit --noverify skip verification of certificates --csv fetch raw results in csv format instead of modified json --filter-subnets subnetsfile filter any ip in target list that matches a subnet in subnetsfile --mozdef mozdefurl emit results as vulnerability events to mozdef, use 'stdout' as url to just print json to stdout --mincvss cvss filter vulnerabilities below specified cvss score --nooutput don't include plugin output in results --serviceapi sapiurl integrate with serviceapi for host ownership and indicators, used when fetching results -s targets run scan on comma separated targets, can also be filename with targets -p policy policy to use when running scan -D seconds purge scans older than argument, must be >= 300 -f follow scan until complete and get results -P list policies -r scan id fetch results The targets parameter can either contain a comma separated list of targets, or a path to a file containing a target list. If a file is used, it should contain one target per line.