OpenText DAST REST API

This topic provides information about the OpenText DAST REST API.

What is the OpenText DAST REST API?

The OpenText DAST REST API provides a RESTful interface between your systems and OpenText DAST for remotely controlling the proxy and scanner. It runs as a lightweight Windows service (named WebInspect API) that is installed automatically when you install OpenText DAST. You configure, start, and stop the service using the Fortify Monitor tool. You can use the OpenText DAST REST API to add security audit capabilities to your existing automation scripts.

The OpenText DAST REST API is fully described and documented using the industry-standard Swagger RESTful API Documentation Specification version 2.0 (now known as OpenAPI Specification). The Swagger documentation provides detailed schema, parameter information, and sample code to simplify consumption of the REST API. It also provides functionality for testing the endpoints before using them in production.

Recommendation

OpenText recommends that you run only one scan at a time. When using SQL Express, in particular, depending on the size of the site, conducting concurrent (or parallel) scans might result in high usage of RAM, CPU, and disk resources on the OpenText DAST host.

Configuring the OpenText DAST REST API

Before you can use the OpenText DAST REST API, you must configure it.

1. From the Windows Start menu, click All Programs > OpenText > OpenText DAST Monitor.

   The OpenText DAST Monitor icon appears in the system tray.

2. Right-click the OpenText DAST Monitor icon, and select Configure DAST API.

   The Configure DAST API dialog box appears.

3. Configure the API Server settings as described in the following table.

   Setting	Value
   Host	Both OpenText DAST and the OpenText DAST REST API must reside on the same machine. The default setting, +, is a wild card that tells the OpenText DAST REST API to intercept all request on the port identified in the Port field. If you have another service running on the same port and want to define a specific hostname just for the API service, this value can be changed.
   Port	Use the provided value or change it using the up/down arrows to an available port number.
   Authentication	Choose None, Windows, Basic, or Client Certificate from the Authentication drop-down list. If you choose Basic for authentication, you must provide user name(s) and password(s). To do this: Click the Edit passwords button and select a text editor. The wircserver.keys file opens in the text editor. The file includes sample user name and password entries: username1:password1 username2:password2 Replace the samples with user credentials for access to your server. If additional credentials are needed, add a user name and password, separated by a colon, for each user to be authenticated. There should be only one user name and password per line. Save the file. If you choose Client Certificate for authentication, you must first generate a client certificate based on your root SSL certificate issued by a trusted certificate authority (CA), and then install it on the client machine. Tip: You can use a tool, such as the MakeCert utility in the Windows Software Development Kit (SDK), to create your client certificate.
   Use HTTPS	Select this check box to access the server over an HTTPS connection. To run the server over HTTPS, you must create a server certificate and bind it to the API service. To quickly create a self-signed certificate to test the API over HTTPS, run the following script in an Administrator PowerShell console: $rootcertID = (New-SelfSignedCertificate -DnsName "DO NOT TRUST - WIRC Test Root CA","localhost", "$($env:computername)" -CertStoreLocation "cert:\LocalMachine\My").Thumbprint $rootcert = (Get-Item -Path "cert:\LocalMachine\My\$($rootcertID)") $trustedRootStore = (Get-Item -Path "cert:\LocalMachine\Root") $trustedRootStore.open("ReadWrite") $trustedRootStore.add($rootcert) $trustedRootStore.close() netsh http add sslcert ipport=0.0.0.0:8443 certhash=$($rootcertID) appid="{160e1003-0b46-47c2-a2bc-01ea1e49b9dc}" The preceding script creates a certificate for the local host and the computer name, puts the certificate in the Personal Store and Trusted Root, and binds the certificate to port 8443. If you use a different port, specify the port you use in the script. Important! Use the self-signed certificate created by the preceding script for testing only. The certificate works only on your local machine and does not provide the security of a certificate from a certificate authority. For production, use a certificate that is generated by a certificate authority.
   Log Level	Choose the level of log information you want to collect. Tip: You can view the API log files using the Windows Event Viewer. The log files are located under Applications and Services Logs > WebInspect API.

4. Do one of the following:

   • To start the OpenText DAST REST API service and test the API configuration, click Test API.

     The service starts, and a browser opens and navigates to the OpenText DAST REST API Swagger UI page. For more information about this page, see Accessing the OpenText DAST API Swagger UI.

   • To start the OpenText DAST REST API service without testing the API configuration, click Start.

Accessing the OpenText DAST API Swagger UI

Complete documentation—including detailed schema, parameter information, sample code, and functionality for testing endpoints—is included in the OpenText DAST API Swagger UI.

To access this information:

1. After configuring and starting the OpenText DAST API service, open a browser.

2. Type http://<hostname>:<port>/webinspect/api in the address field and press Enter.

   Example: If you used the default settings when configuring the OpenText DAST REST API, you would type http://localhost:8083/webinspect/api.

   The OpenText DAST REST API Swagger UI page appears.

Switching between API versions

By default, the Swagger UI opens to version 1 (v1) of the OpenText DAST REST API. Version 2 (v2) of the API includes asynchronous versions of endpoints that take a long time to complete. Using these endpoints generates a job token that you can use with the v2 Job endpoints to get the status and results from the job.

To switch to OpenText DAST REST API v2:

• In the Swagger UI, change v1 at the end of the URL to v2.

  

To switch back to OpenText DAST REST API v1:

• In the Swagger UI, change v2 at the end of the URL to v1.

Using the Swagger UI

To use the Swagger UI:

1. In the Swagger UI, click an endpoint category.

2. Click the endpoint method to use.

   Detailed schema, parameter information, sample code, and functionality for testing the endpoint appear.

Getting field-level details

Some API endpoints have numerous fields that you can configure. These fields are documented in detail in the Swagger UI.

To view the field-level details:

• In the Parameters section of the endpoint, click Model under the Data Type heading.

  Additional details for all the endpoint fields appear.

Automating OpenText DAST

You can use the OpenText DAST API to add OpenText DAST to your existing automation scripts. As long as the user agent can access the Service Router, the scripts can exist in an entirely different environment from OpenText DAST.

OpenText DAST updates and the API

After updating OpenText DAST, you must open the OpenText DAST user interface and then open a scan so that any database schema changes can be applied to the scan database. Otherwise, you may not be able to run certain API commands without receiving an error.