Patronus API

The Patronus API Developer Hub

Welcome to the Patronus API developer hub. You'll find comprehensive guides and documentation to help you start working with our pentest module as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Getting Started

API-Key Generation

Note for Testing

Currently, our Patronus-API is only available to a selected group of developers. If you are interested in testing it, please first send an email to api@patronus.io with a short introduction of your profile/organization. Our onboarding team will get back to you within 24 hours.

To be able to use Patronus-API in your development workflow, we provide you with an API-Key that will start the test run of the pentest for each of your projects.

In order to generate an API Key, please follow the steps described below:

1. Receive Custom User Account

After you have been confirmed by our onboarding team for the test period, we will send you custom login credentials for our platform.

2. Log in to the Patronus API Dashboard

Sign in to your account with the provided credentials.
Login URL: api.patronus.io

2.1 Create an API-Key

Once you are logged in, press the "Create API-Key" button and create an API-Key for every URL that you want to test.

2.2 Configure the API-Key Settings

For each API-Key, you have a variety of customization options at your disposal, so that the pentest can accommodate your testing needs. Note: If you keep the fields blank, our test will proceed with the set default values for each parameter (see table below). Some fields like Start-URL are mandatory.

You can configure the following parameters:

Selecting the right Environment / URL to test

We recommend to run the pentest on some form of staging or testing environment, as the scan can have an impact on the performance of your live system (production environment).

Parameters
Description

API-Key Name

The name of the API-Key (can arbitrarily chosen)

Start-URL

The host or start-URL you want the crawler to start at.

This needs to be a full URL including the protocol.

Example: https://example.com/start/here

Whitelist

A list of whitelisted hosts, that the crawler is allowed to crawl, given that it finds a link targeting the host.

At least one entry is required. Usually this is the domain of your start-URL.

Example: example.com
Subdomains of whitelisted hosts are also automatically whitelisted.

Example: sub.example.com is whitelisted when example.com is whitelisted.

Requests per Minute

The number of requests per minute our services are allowed to send towards your hosts.

Default: 1000

Login

If you want to run tests behind a login-wall as well, you can provide the API with information about your login-forms.

Login Domain

The domain on which your login form is located at.

Example: example.com

Login Path

The path on the domain where you login form is located at.

Example: /login.php

Login HTML Form Action

If your login forms action-URL is not the same as the URL the form itself is on, please enable this and enter the path to the forms action URL.

Example: /login-perform.php

Login Data

This is the actual login data that will be sent via the login form. This needs to be a JSON-object with the keys being the form's field-names and their values being the actual value you would enter in the fields.

Example:

{
  "username": "example-user",
  "password-field": "secret-password",
  "additional-fields-name": "additional-fields-value"
}

Login Noncer

If your login form uses a CSRF-token (numeric or something similar) to protect your website you can pass the fields name here and not include it in the login-data-setting.

Before sending the login-data we will then open the site where the login-form is located at and extract the value that was provided in the field with the given name before submitting the login form.

Example: user_token

Login Check

The data provided in this field will be used to validate if the login was successful.

You can pass the following data:

HTTP-Request-Method:
Select the HTTP-Method that can be use to make a request to the given path.

Example: GET

Path:
The path that can be requested to check if the login was successful.

Example: /admin-dashboard.php

HTTP-Status-Code:
The expected status code when requesting this endpoint when the login is successful.

Example: 200

Regex (optional):
A regex run against the response of the request to check if the login was successful.

Example: logout

Login Fallback

This path will be used if the login-form does not redirect you to a site that is only visible to logged-in users.

Example: /admin-dashboard.php

Testing a Single-Page Application?

If you want to test a web application that is based on a javascript framework like REACT, please select the crawler type: Javascript (currently in BETA).

3 URL verfication

In order to validate that you are the authorized to scan the URL, you must upload a verification file as confirmation.

Validation Steps:

  • First, download the verification file from the menu.
  • Place the file in your root directory of your server.
  • Wait a few seconds for the system to validate the file.

4. Start the first Test

Once all the parameters were passed successfully, you can start the pentest for the validated URL with the generated API-Key.


What's Next

Start the authentication process and the pentest will be running in no time.

Authentication