User Guides
Using the Public API

Creating a scan using the API

10min

This feature is not available to all tiers, please contact us if you would like to discuss adding this feature to your Hexiosec ASM account.

The API endpoints required to create and start a scan are highlighted in the API documentation, but this page details those steps:

  1. Creating a scan
  2. Adding seeds to a scan
  3. Starting a scan
  4. Check a scan's state

In the following steps, an example scan ID, 00000001-0001-0001-0001-000000000001 and API token, XYZ have been used, and will need to be replaced with the valid values.

Create and start

1. Creating a scan

Information required*:

  • name: The name of the scan, as you would see in the app
  • scan_group_id: The ID of the group to add the scan to
  • type: The type of the scan to create, either:
    • adhoc: Ad Hoc scan
    • continuous_own: Own Asset Monitoring scan
    • continuous_vendor: Third Party Monitoring scan

*Other settings are available, see API documentation.

Example:

POST https://asm.hexiosec.com/api/v1/scans accept: application/json content-type: application/json x-hexiosec-api-key: XYZ { "name": "API Example Scan", "scan_group_id": "00000001-0001-0001-0001-000000000001", "type": "adhoc", "dns_namelist": true, "ignore_ip_nodes": false }

The response from this request will include the scan id value, to be used in step 2.

2. Adding seeds to a scan

When the scan has been created, you can add seeds. This endpoint will need to be called for each seed to be added.

Information required*:

  • id: The ID of the scan created, from step 1
  • In request body, for the seed:
    • name: The domain name, IP address or IP range
    • type: Either:
      • domain
      • ipv4
      • ipv6
      • iprange

*Other settings are available, see API documentation.

Example:

POST https://asm.hexiosec.com/api/v1/scans/00000001-0001-0001-0001-000000000001/seeds accept: application/json content-type: application/json x-hexiosec-api-key: XYZ { "name":"example.com", "type":"Domain" }

3. Starting a scan

Once the scan has been created and seeds added, you use the update endpoint to start the scan running.

Information required*:

  • id: The ID of the scan created, from step 1
  • In request body, set the state:
    • enabled: true

*Other settings are available, see API documentation.

Example:

PATCH https://asm.hexiosec.com/api/v1/scans/00000001-0001-0001-0001-000000000001 accept: application/json content-type: application/json x-hexiosec-api-key: XYZ { "enabled":true }

Check state

4. Check a scan's state

Once a scan has completed you will receive an email notification (if enabled).

You can also use the GET 'scans' endpoint to periodically query the state of the scan.

Information required*:

  • id: The ID of the scan created, from step 1
  • expand: iteration - To ensure you get the state

Example:

GET https://asm.hexiosec.com/api/v1/scans/00000001-0001-0001-0001-000000000001?expand=iteration acceptapplication/json x-hexiosec-api-key: XYZ

In the response, the iteration object contains the state of the latest iteration.

Example response when in progress:

"iteration": { "state": "in_progress" }

Example response when complete:

"iteration": { "state": "completed" }