Usage¶
On-demand scans are performed by invoking a handful of REST APIs. At this time, the request and response formats for most of the APIs are very simple - they expect a host as input, and return a UUID for the scan (if the host is valid). Valid host types are: FQDN, IPv4.
The REST API supports JSON.
The recommended method to use vautomator-serverless APIs in a vulnerability assessment is to use the vautomator-client.
You could use another tool such as curl
to invoke them (see the REST API section below).
Note
At this time, all REST API endpoints are protected with an API key, which
must be specified in an X-Api-Key HTTP
header. If using the vautomator-client
, this key will be retrieved by the client, provided that you are using the same AWS profile/role used to deploy vautomator-serverless
. If not, the client will prompt you to enter an API key.
For a detailed usage of vautomator-client
, refer to: https://github.com/mozilla/vautomator-client/blob/master/README.md
REST API¶
POST /scan¶
Perform all supported scans on a given host.
Parameters¶
target
is the host (FQDN or IPv4 address)
Output¶
- A
json
document containing step function execution name.
Example¶
curl -X POST 'https://vautomator.security.allizom.org/scan' -d '{"target": "www.mozilla.org"}' -H 'X-Api-Key: abcdefgh12345678' {"executionArn":"<executionARN>:ScanAll:e9648493-9c01-11e9-85f4-874b479eba5f","startDate":1.561986763711E9}
Note
This is an asynchronous endpoint. Behind the scenes, the host is processed by a state machine, which invokes a number of Lambda functions to perform all scans on the host, and an email is sent to desired parties when all scans are completed and results are available.
POST /ondemand/portscan¶
Add a target to the scan queue for port scan.
Parameters¶
target
is the host (FQDN or IPv4 address)
Output¶
- A
json
document containing a UUID associated with the scan.
Example¶
curl -X POST 'https://vautomator.security.allizom.org/ondemand/portscan' -d '{"target": "www.mozilla.org"}' -H 'X-Api-Key: abcdefgh12345678' {"uuid": "ac90f64c-3516-4449-bf4e-040d2f18fdc9"}
POST /ondemand/httpobservatory¶
Add a target to the scan queue for HTTP Observatory scan.
Parameters¶
target
is the host (FQDN or IPv4 address)
Note
While this endpoint will accept an IPv4 address, HTTP Observatory will not run a scan for an IP address only. vautomator will not complain, rather the HTTP Observatory scan results for the target will be empty.
Output¶
- A
json
document containing a UUID associated with the scan.
Example¶
curl -X POST 'https://vautomator.security.allizom.org/ondemand/httpobservatory' -d '{"target": "www.mozilla.org"}' -H 'X-Api-Key: abcdefgh12345678' {"uuid": "6dd38a01-4d2d-4781-8db1-3ab65b63e1fb"}
POST /ondemand/tlsobservatory¶
Add a target to the scan queue for TLS Observatory scan.
Parameters¶
target
is the host (FQDN or IPv4 address)
Output¶
- A
json
document containing a UUID associated with the scan.
Example¶
curl -X POST 'https://vautomator.security.allizom.org/ondemand/tlsobservatory' -d '{"target": "www.mozilla.org"}' -H 'X-Api-Key: abcdefgh12345678' {"uuid": "31c1f82e-83e2-4ccf-b245-8907d0a9eee8"}
POST /ondemand/sshobservatory¶
Add a target to the scan queue for SSH Observatory scan.
Parameters¶
target
is the host (FQDN or IPv4 address)
Output¶
- A
json
document containing a UUID associated with the scan.
Example¶
curl -X POST 'https://vautomator.security.allizom.org/ondemand/sshobservatory' -d '{"target": "www.mozilla.org"}' -H 'X-Api-Key: abcdefgh12345678' {"uuid": "be32e717-c72e-41d9-806f-fd4de805aae4"}
POST /ondemand/websearch¶
Add a target to the scan queue for a Google web search of a target with a keyword security
.
Parameters¶
target
is the host (FQDN or IPv4 address)
Output¶
- A
json
document containing a UUID associated with the scan.
Example¶
curl -X POST 'https://vautomator.security.allizom.org/ondemand/websearch' -d '{"target": "www.mozilla.org"}' -H 'X-Api-Key: abcdefgh12345678' {"uuid": "0b9e2375-1e8a-4921-8bb4-1e82f695d1dc"}
POST /ondemand/direnum¶
Add a target to the scan queue for a directory enumeration scan.
Parameters¶
target
is the host (FQDN or IPv4 address)
Output¶
- A
json
document containing a UUID associated with the scan.
Example¶
curl -X POST 'https://vautomator.security.allizom.org/ondemand/direnum' -d '{"target": "www.mozilla.org"}' -H 'X-Api-Key: abcdefgh12345678' {"uuid": "1c124924-2938-423b-a42a-489e2dc8ac64"}
POST /ondemand/tenablescan¶
Add a target to the scan queue for a Tenable.io scan.
Note
This endpoint will accept submissions, however a Tenable scan will not run unless vautomator was deployed with Tenable.io support during setup (see step 7).
Parameters¶
target
is the host (FQDN or IPv4 address)
Output¶
- A
json
document containing a UUID associated with the scan.
Example¶
curl -X POST 'https://vautomator.security.allizom.org/ondemand/tenablescan' -d '{"target": "www.mozilla.org"}' -H 'X-Api-Key: abcdefgh12345678' {"uuid": "a778ada0-051f-464f-bf18-599d051f0fac"}
POST /results¶
Downloads the scan results available for the requested host.
Parameters¶
target
is the host (FQDN or IPv4 address)
Note
In order for this endpoint to work properly, the request made must contain a
'Accept: application/gzip'
header (This is an AWS API gateway caveat).
Output¶
- A binary blob (
application/gzip
) containing compressed scan results for the host.
Example¶
curl -X POST 'https://vautomator.security.allizom.org/results' -d '{"target": "www.mozilla.org"}' -H 'X-Api-Key: abcdefgh12345678' -H 'Accept: application/gzip' > www.mozilla.org__results.tgz