Vulnerability Scanner
Initializing a Scan
The Scan Request endpoint is the method responsible for initializing the scan of a target. Upon request, it returns a unique analysis identifier that should be used later to verify the progress of the process, as well as information about the target host and the vulnerabilities found.
Scan jobs can be configured by passing an optional "preferences" object. To view the full list of options please visit:
Request
To request the endpoint, you must enter the required credentials, as shown in the following example:
Example cURL request - Initiating a scan with XSS and SQL tasks enabled
Example cURL request - Initiating a scan with all crawler options enabled, SQL and XSS
Example Python request - starting a Full scan
*Filling in the API_KEY value is mandatory.
Return
The request response, in JSON format, contains the identification of the analysis for monitoring and obtaining the result.
Successful response
Getting Results for a Scan
The Fetch Scan by ID endpoint is the method responsible for returning the status, found vulnerabilities, and the percentage of completion of a certain scan. If the scan is in progress, you can still check the partial results.
You can also pass an optional language query parameter to determine the language of the returned response. Note: only vulnerability descriptions and remediations are translated. Currently VScanner supports the following languages:
Language query parameter | Language |
---|---|
en | English |
pt | Brazilian Portuguese |
Scans not initiated
Scans might take some time to get picked up by our workers. On cases where a scan was received and is in the queue to be processed fetching the scan will return the following JSON:
Receiving this message does not indicate an error and the scan will be executed.
Request
To request the endpoint, you must enter the required credentials, as shown in the following example:
API Key Fetch Scan
GET
https://api.vscanner.ai/v1/api/scan/<ENQUEUED_SCAN_ID>?language=en
Fetches the result of a given scan id.
Query Parameters
Name | Type | Description |
---|---|---|
language | String | Language of the returned vulnerability descriptions. 'pt' for Brazilian Portuguese and 'en' for English. Default: 'en' |
issue_types | Boolean | Returns issues grouped by types. Default: false |
Example cURL request
Example Python request
*Filling in the API_KEY value is mandatory.
Return
The request response, in JSON format, contains the results and the status of the scan.
Successful response
For this example response, the URL: https://example.com was used.
List scans
Lists all scans for a given user. Scans initiated through the dashboard will also appear here.
Request
Example cURL request
Example Python request
*Filling in the API_KEY value is mandatory.
Return
The request response, in JSON format, contains a list of objects with identifier and the date when the scan started.
Successful response
Issue Groups
Each vulnerability found by VScanner is referred to as an 'issue'. Every issue discovered belongs to a specific category, identified by its group ID.
Below is a table that lists all possible group IDs that VScanner can return, along with their respective descriptions.
Group ID | Issue Group Description |
---|---|
Improper Access Control | The product does not restrict or incorrectly restricts access to a resource from an unauthorized actor. |
Improper Interaction Between Multiple Correctly-Behaving Entities | An interaction error occurs when two entities have correct behavior when running independently of each other, but when they are integrated as components in a larger system or process, they introduce incorrect behaviors that may cause resultant weaknesses. |
Improper Control of a Resource Through its Lifetime | The product does not maintain or incorrectly maintains control over a resource throughout its lifetime of creation, use, and release. |
Incorrect Calculation | The product performs a calculation that generates incorrect or unintended results that are later used in security-critical decisions or resource management. |
Insufficient Control Flow Management | The code does not sufficiently manage its control flow during execution, creating conditions in which the control flow can be modified in unexpected ways. |
Protection Mechanism Failure | The product does not use or incorrectly uses a protection mechanism that provides sufficient defense against directed attacks against the product. |
Incorrect Comparison | The product compares two entities in a security-relevant context, but the comparison is incorrect, which may lead to resultant weaknesses. |
Improper Check or Handling of Exceptional Conditions | The product does not properly anticipate or handle exceptional conditions that rarely occur during normal operation of the product. |
Improper Neutralization | The product does not ensure or incorrectly ensures that structured messages or data are well-formed and that certain security properties are met before being read from an upstream component or sent to a downstream component. |
Improper Adherence to Coding Standards | The product does not follow certain coding rules for development, which can lead to resultant weaknesses or increase the severity of the associated vulnerabilities. |
Unspecified Threat | Vulnerabilities that have not been classified, or do not have CWE assigned by NIST. |
Scan Controls
Pause, resume or stop a running scan.
The following are the available controls currently allowed by VScanner.
Control Parameter | Description |
---|---|
pause | Pauses a running scan |
resume | Resumes a paused scan |
stop | Stops a running scan |
Controls a running scan
POST
https://api.vscanner.ai/v1/api/scan_control
Request Body
Name | Type | Description |
---|---|---|
scan_id* | String | Scan ID of a running scan |
control* | String | Which control to send to scanner. Refer to the table above for allowed parameters |
Get current scan control state
Use this endpoint if you need to check if a scan is running, paused or stopped.
Get scan control
GET
https://api.vscanner.ai/v1/api/scan_control/{scan_id}
Query Parameters
Name | Type | Description |
---|---|---|
scan_id* | String | Scan ID |
Last updated