Missions¶
A mission is one scoped assessment. In the API, missions live under /scans.
Create a mission¶
POST /v1/scans
Requires the write scope. Send an Idempotency-Key header, so that a retry can't start a second mission.
Request body¶
| Field | Type | Description |
|---|---|---|
name |
string | Required. A name you'll recognise in the app. |
target |
object | Required. What to test: {"type": "url", "url": "…"} for a web application, or {"type": "ip", "ip": "…"} for a host. |
authorization_confirmed |
boolean | Must be true for the mission to start. See Authorisation. |
scan_mode |
string | quick, normal or deep. Defaults to normal. Whether deep is available depends on your plan. |
scan_type |
string | web or network. Defaults to web. |
Other optional fields are described in the full reference.
{
"name": "Staging web app",
"target": {"type": "url", "url": "https://app.example.invalid"},
"scan_mode": "normal",
"scan_type": "web",
"authorization_confirmed": true
}
Authorisation¶
authorization_confirmed is your organisation's confirmation that it's authorised to test every target in the request. Set it to true only when that's so. Revelion records the confirmation with the mission.
The field is optional in the request schema and defaults to false, so a request can be well formed and still be refused. Without the confirmation, the API responds:
{
"error": {
"type": "forbidden",
"code": 403,
"message": "You must confirm you are authorized to perform security testing on this target before a mission can start. Send authorization_confirmed=true with this request. If you are using the dashboard, reload the page and tick the authorization box in the mission wizard."
}
}
Response¶
202 Accepted, with the new mission.
Requests can also be refused for reasons the schema can't show: not enough credits (402), an option your plan doesn't include (403), or a target value that isn't acceptable (400). The error reference lists every status.
Get a mission¶
GET /v1/scans/{id}
Requires the read scope. Returns the mission, or 404 if there's no mission with that ID in your organisation.
List missions¶
GET /v1/scans?limit=20&offset=0&status=running
Requires the read scope. Returns missions newest first, as a paginated list.
| Parameter | Description |
|---|---|
limit |
How many to return, up to 100. Defaults to 20. |
offset |
How many to skip. Defaults to 0. |
status |
Optional. Return only missions with this status. |
The mission object¶
| Field | Description |
|---|---|
id |
The mission's ID |
name |
The name you gave it |
status |
Where it is in its lifecycle |
target |
What it's testing |
scan_mode |
quick, normal or deep |
scan_type |
web or network |
error_message |
Why the mission ended in error, when it did |
created_at, started_at, completed_at, updated_at |
Timestamps |
The full reference lists every field.
Statuses¶
| Status | Meaning | Final? |
|---|---|---|
pending |
Accepted and waiting to run | No |
running |
In progress | No |
paused |
Paused; it can be resumed | No |
completed |
Finished | Yes |
error |
Ended with an error; see error_message |
Yes |
cancelled |
Cancelled before it finished | Yes |
More mission endpoints¶
The full reference also covers cancelling, pausing and resuming missions, listing a mission's agents and events, and reading its findings and reports.