Fortify WebInspect REST API

This topic provides information about the Fortify WebInspect REST API.

What is the Fortify WebInspect REST API?

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

The Fortify WebInspect 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

Fortify 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 Fortify WebInspect host.

Configuring the Fortify WebInspect REST API

Before you can use the Fortify WebInspect REST API, you must configure it.

1. From the Windows Start menu, click All Programs > Fortify > Fortify WebInspect > Micro Focus Fortify Monitor.

   The Micro Focus Fortify Monitor icon appears in the system tray.

2. Right-click the Micro Focus Fortify Monitor icon, and select Configure WebInspect API.

   The Configure WebInspect API dialog box appears.

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

   Setting	Value
   Host	Both Fortify WebInspect and the Fortify WebInspect REST API must reside on the same machine. The default setting, +, is a wild card that tells the Fortify WebInspect 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 Fortify WebInspect REST API service and test the API configuration, click Test API.

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

   • To start the Fortify WebInspect REST API service without testing the API configuration, click Start.

Accessing the Fortify WebInspect REST API Swagger UI

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

To access this information:

1. After configuring and starting the Fortify WebInspect REST 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 Fortify WebInspect REST API, you would type http://localhost:8083/webinspect/api.

   The WebInspect REST API Swagger UI page appears.

Using the Swagger UI

To use the Swagger UI:

1. On the Swagger UI page, 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 Fortify WebInspect

You can use the Fortify WebInspect API to add Fortify WebInspect 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 Fortify WebInspect.

Fortify WebInspect Updates and the API

After updating Fortify WebInspect, you must open the Fortify WebInspect 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.