API

Swagger Documentation

https://pentest.ws/docs/api/v1/

Please refer to the Swagger Documentation for a detailed listing of API end-points, example requests and testing platform.

The PenTest.WS API provides access to your Engagements, Hosts, Ports, Scratchpad, Note Pages, Credentials, Clients & Findings through a RESTful architecture, including GET, PUT, POST, & DELETE capabilities for each object. You can now build automation scripts and integrate external tools into your PenTest.WS environment.

API Authorization

All PenTest.WS API calls require authorization.

You can find your API-Key under Account Settings -> API-Key:

https://pentest.ws/settings/api-key

Security Info:

This API Key grants direct access to objects in your PenTest.WS account. This includes Engagements, Hosts, Ports, Notes, Findings and others.

Do not share your API key!

Curl Example

Get the API end-point /api/v1/e with the HTTP Header value X-API-KEY

curl -X GET "https://pentest.ws/api/v1/e" -H "X-API-KEY: {api-key}"

Nmap Scan Automation

Consider the following Nmap Scan Template:

nmap -sC -sV -oA tcp -vv %tip% && curl -X POST "https://pentest.ws/api/v1/e/%eid%/import/nmap" -H "X-API-KEY: %apikey%" -F "file=@tcp.xml"

The first half of this command runs a typical nmap scan on a target IP address, IP range or CIDR block, then outputs the results to a file called “tcp.xml”. The second half of this command uses curl to immediately post these results to your engagement in PenTest.WS.

Embedded in this command are several interesting variables:

%tip%	Target IP Address, Range or CIDR Block
%eid%	Current Engagement ID
%apikey%	Your API Key – when you click on a command with this variable, the application will prompt for your password before swapping the variable for your API Key. You can view your API key at https://pentest.ws/settings/api-key

The full list of template variables are available in the template screens:

Template Variables

Security Best Practices

• Do not embed API keys directly in code: API keys that are embedded in code can be accidentally exposed to the public, for example, if you forget to remove the keys from code that you share. Instead of embedding your API keys in your applications, store them in environment variables or in files outside of your application's source tree.

• Delete unneeded API keys: To minimize your exposure to attack, delete any API keys that you no longer need.

• Regenerate your API keys periodically: You can regenerate your PTWS API key by clicking the Generate New API Key button above. Then, update your applications to use the newly-generated key.

• Do not store API keys in files inside your application's source tree: If you store API keys in files, keep the files outside your application's source tree to help ensure your keys do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub.

Tier Availability

API is available on all tiers.