In this quick example we will start a scan for a target from a list and get the final scan results.

To run the requests, replace <PROBELY_AUTH_TOKEN> with your authentication token.
Read more about how to obtain the authentication token in the Authentication section.

We will start with a request to get the list of targets of the account.

curl https://api.probely.com/targets/ -X GET -H "Content-Type: application/json" -H "Authorization: JWT <PROBELY_AUTH_TOKEN>"

The response returns a JSON with the list of targets in your account.

{
  "count": 32,
  "page_total": 4,
  "page": 1,
  "length": 10,
  "results": [ 
    {
      "id": "3jWDZrNpfhSK",
      "site": {
        "id": "44rhjEiKbqHP",
        "name": "My Website",
        "desc": "",
        "url": "https://www.example.com/",
        ...
      },
      ...
    },
    ...
  ]
}

With a list of targets, we will start a scan for the first target (with the identifier 3jWDZrNpfhSK).

curl https://api.probely.com/targets/3jWDZrNpfhSK/scan_now/ -X POST -H "Content-Type: application/json" -H "Authorization: JWT <PROBELY_AUTH_TOKEN>"

The response returns a JSON with information about the scan, such as the scan identifier, the scan status, and the creation date.

{
  "id": "37borpHTaGDe",
  "target": {
    "id": "3jWDZrNpfhSK",
    ...
  },
  "status": "queued",
  ...
  "created": "2023-11-15T15:14:20.650073Z",
  ...
}

Now, we will poll Probely with the following request to get the scan information and check whether the scan is complete.
We will use the scan identifier (37borpHTaGDe) and target identifier (3jWDZrNpfhSK) from the previous steps.

curl https://api.probely.com/targets/3jWDZrNpfhSK/scans/37borpHTaGDe/ -X GET -H "Content-Type: application/json" -H "Authorization: JWT <PROBELY_AUTH_TOKEN>"

When the scan is complete, the response returns a JSON with the scan status as completed, together with the date and time of completion and the final number of vulnerabilities found (low, medium, and high).

{
  "id": "37borpHTaGDe",
  "target": {
    "id": "3jWDZrNpfhSK",
    ...
  },
  "status": "completed",
  "started": "2023-11-15T15:14:22.971155Z",
  "completed": "2023-11-15T15:57:52.888459Z",
  "scan_profile": "api_normal",
  "lows": 1,
  "mediums": 2,
  "highs": 24,
  ...
}

In this last step, we polled Probely to get the scan information and check whether it was complete.
An alternative to this is to subscribe to Probely events and get notified about changes in your account.
Learn more about the available events and how to subscribe to them in Events.

A valid authentication token is required to make requests to the Probely API.

To obtain the authenticationtoken, generate an API Key in the Probely app and save it in a secure place.
Treat the authentication token as a password since it allows access to information in your account and possible manipulation (depending on the role associated with the API Key).

To pass the authentication token in requests, add it to the authorization header using the following format:

Authorization: JWT <PROBELY_AUTH_TOKEN>

TL;DR: you run scans on targets, and findings are created for any issue that is found. However, there are a few more concepts that must be explained in order to get a complete picture of how Probely works. We will spend the next few sections detailing the most important concepts.

A target defines the scope of a scan, what will and won't be included in the scan plan. This is done by filling a target's site and assets.

The entry point for the web application (and authentication) is setup in the target's site.

In modern web applications, you are probably loading resources from multiple domains. A single page app, for example, will usually load the page from one domain and make AJAX requests to another. This is what assets are for: they specify what domains our scanner should follow and create requests for.

A URL is probably not the only thing you will need to setup when scanning your application.
For example:

• Does the application have an authenticated area?
• Does it use basic auth?
• Does it expect a certain cookie or header?

These parameters are all configured in the target's site.

We need to ensure that only allowed web applications are scanned. Therefore, we must verify that you have control of any site you wish to include. This can be done by:

• Placing a file on a well-known location, on the site's server.
• Creating specific DNS records.
• Adding an HTML meta tag to the root of the site.

This is what you're here for. After configuring your target, you will want to run scans against it. You can either start a one off scan, or schedule one for later - recurring or not.

During the scan, we will crawl the site and run several modules to check for security issues, which we call findings. You can check the findings even before a scan ends. If everything goes well, the scan will complete and that is it.

With some findings, our automated processes may have difficulties determining if it is a false positive or a legitimate issue. In these instances, a scan will be marked as under review, and we will further analyze the finding before making a decision. We will only show findings that, for some degree of confidence, are true positives. A finding that we are not sure of will never be displayed.

As much as we try to prevent it, a scan (or a sub-module) can malfunction.
If this happens, a scan is marked as:

• "failed": the problem was irrecoverable.

During a scan, we try to determine what frameworks you are using and add this information to the site and asset objects discussed previously.

The last core concept is the finding, this is a security issue that we have found during our scans. If the same issue is found in a new scan it will not open a new finding but update the previous.

A finding will have a lot of information about the issue. Namely, where it was found, URL, insertion point (e.g. cookie), parameter, and method. Evidence we gathered, and the full request and response that we used. Sugestions of how to go about fixing it. A full description of the vulnerability is also present in the definition property. We also assign a severity and calculate the CVSS score for each.

Besides all this, there are also actions that you can perform on a finding. You can assign it to one user, leave comments for your team or add labels, and reduce or increase the severity.

If you don't plan on fixing the finding and accept the risk, or you think we reported a false positive, you can mark the finding to reflect that.

Scan profiles allow you perform different kinds of scans that differ in their duration, type and number of requests performed and vulnerabilities tested for:

There are several scan profiles:

Security Posture scans usually run in under a minute and check for SSL/TLS, HTTP headers, and cookies attribute-related vulnerabilities.

The safe profile tests for all the vulnerabilities we support, but with a limited set of payloads, to reduce the possible impact on the target application. The scanner will not make POST, PUT or DELETE requests, however, our crawler will still make requests with these methods if there are actions that trigger them.

The Normal profile tests for all the vulnerabilities we support, with a larger set of payloads than the one used in the safe profile, for some tests. It also has no restrictions about which methods it uses.

The Full profile includes all the tests from the normal profile, plus an even larger set of payloads.

Specifically for API targets, there are also the API Normal/API Full that correspond to profiles normal/full for web targets.

API users are a special kind of user in a Probely account. They represent applications interacting with Probely through the API in machine-to-machine scenarios, such as standalone applications integrating with Probely.

Depending on the roles assigned, API users can have access to different features of Probely to perform their tasks. Read more on How do Roles and Permissions Work

Functionality

The endpoints under API Users provide the following functionality:

• Create and manage API users.
• Create, manage, and assign API user roles to API users.

Important Notes

Some relevant information when using API Users:

• An API user has an access token that identifies it.
• Unlike users, access tokens for API users won't have an expiration date due to the nature of machine-to-machine interactions.

Related Tags

Further functionality related to API Users is provided in the following tags:

• User Management - Manage users in the account including API users.
• User - Manage specific API user settings, like passwords or notifications.