Portal API Reference

The Patchman Portal API allows you to modify and update resources that you would otherwise have managed through the web interface.

The Portal API is organized around REST and designed to have predictable, resource-oriented URLs. We use built-in HTTP features, such as HTTP authentication, methods and response codes, that are understood by many HTTP clients. JSON is returned whenever possible, including in all errors.

Additionally, we have created a online web interface that allows you to explore the API with point-and-click. This interface is available from /api/v1/. The API is only available for plans featuring API access.

Unless specified otherwise in this documentation, you can simply use the operations listed to the right to access and modify objects. Not all operations are available on all resources, especially regarding which fields can be modified and which objects can be deleted. Searching is available in on a subset of fields (specified per resource) and only supports exact matches. Filters can be combined conjunctively.

In the case your client does not support e.g. PATCH or DELETE, you can:

• Add the _method field to your POST request.
• Add the X-HTTP-Method-Override header to your POST request.

All code examples below assume you are requesting JSON data (which is at this time the only accepted format).

HTTP methods

In a RESTful API, specific HTTP methods are used for specific actions.

Using PATCH versus PUT

When using PUT, you must specify a full resource representation as the request entity. Any properties that are omitted will be set to default values. Using PATCH will only update the resource with properties provided in the request entity.

Pagination

Pagination is off per default, but is encouraged to be used when requesting bigger datasets. Depending on the size of your server and user base, some API calls can return thousands of results. To enable pagination, provide a page_size GET parameter. The maximum number of results per page is 100.

As pagination provides extra values in the result to help you find the next and previous page, the actual result is stored in the result value. The meta parameters are:

Ordering

Certain API end-points allow you to order their results by providing ordering GET parameter. The value should be a comma separated list of fields by which detections will be ordered. By default, the order is ascending, if descending order is desired, the field must be prefix by a "-" sign.

As of now, only detections allow sorting, every type of detections below describes the possible fields for ordering.

Suborganization filtering

The API's scope is by default limited to objects that fall directly under your organization's control. In contrast, the Portal webinterface does provide access to objects owned by suborganizations by default, so this may cause apparent differences between results shown in the webinterface and through the API. However, there's a filter option available for all objects that allows you to show results that fall under a particular suborganization. The filter field is suborganization and it accepts the ID of the suborganization.

Note that this filter is not available for the license key endpoint and suborganization endpoint, since those endpoints show suborganization results by default.

Suspended account

In case your account is suspended, any request will give a HTTP 403 response and JSON from the example.

Authentication

The API is primarily accessible using OAuth2 Authorization Code and Client Credentials grants. Both flows require you to create an application in the 'Apps' section of your account in the Portal web interface.

The Authorization Code grant type is the one you should pick when you want others to authenticate through your app. This is a flow you may already know from other websites: the client logs in using his own credentials at the Portal web interface and accepts the application access.

The Client Credentials grant type is suited for situations where you are the only user of your application and you want to access your account details using an API.

If your application is not suited for use of any of these grant types, Implicit and Resource Owner Password Credentials (legacy) grants are also available. Please contact support detailing why you need these types if this is applicable to your situation.

Independent of the OAuth grant type, you will receive an access token that can be used to authorize your requests in the HTTP header. The token type will (almost) always be 'Bearer', which can be used to set the HTTP Authorization request header.

The latter of this section will describe how you can obtain such a token for the two supported grant types. The implementation of the Portal matches most common OAuth2 implementations and conforms to RFC 6749. You should be able to use most OAuth2 libraries to authenticate with the Portal. The documentation that follows is intended for those not comfortable using a dedicated OAuth2 library.

Authorization Code Grant Type

Authentication using authorization codes consists of the following steps:

1. The flow is initiated by pointing the user's user agent (e.g. browser) to the authorization endpoint. This request includes the client identifier, requested scope, local state and a redirection URL.
   The user authenticates with the Portal and requests the user to accept or deny the requested access. Assuming the user has granted access, the Portal will redirect the user back to the redirection URL. This includes an authorization code and any local state provided by the client.
2. The client requests an access token from the Portal's token endpoint, including the authorization code, client identifier, client secret and includes the redirection URL for verification.
   Finally, the Portal will verify the provided data and, assuming everything is correct, will issue an access token and optionally a refresh token.

Requesting Authorization

The first step in the authorization process is authentication of the user to the Portal and the authorization of the user for your application. This process starts by you, as client, redirecting the user to the authorization endpoint url, allowing you to provide the query parameters as specified below.

After authentication succeeds, the user is redirected to the redirect URI you specified before, with the code and state query parameters added to the URI. The provided authorization code is only valid for 60 seconds, requiring you to exchange the code for an access token.

Exchange for an Access Token

To exchange the authorization code received in the previous step for a more permanent access token, a POST request to the token endpoint should be made. This request is authorized using HTTP Basic authentication, using your client_id and client_secret as username and password (separated by a colon). Use the following POST parameters:

The response (in JSON) includes the expiration time of the token, the granted scopes, and an access token and refresh token.

Refresh a Token

As we have seen before, an access token can expire. You also receive a refresh token that can be used to obtain a new access token. After executing this action, the original access and refresh token can not be used to obtain access to the account anymore.

Client Credentials Grant Type

Authentication using client credentials is significantly easier to implement, as it only involves the client authenticating with the Portal and receiving an access token. You can directly exchange your client id and client secret for an access token for your own account:

The response (in JSON) includes the expiration time of the token, the granted scopes, and an access token and refresh token. The refresh token can be used in the same manner as with the authorization code grant type, although you could also simply reauthorize using the same method as described above.

License keys

License keys are used for registering new servers to your Portal account. They are used by the installation script, or used manually to enter in the /etc/patchman/license/key file prior to the agent's first start.

Note that after using the license key you will still need to approve the new server to your Portal account before it starts functioning completely. See server approval for more information.

License key revocation

If you think a license key may have been compromised, you can revoke it by performing a DELETE request to the license key object. A new license key will automatically be generated in its place, which you can request after the conclusion of the request. Since internally only the key property changes and the wrapping object isn't deleted in full, you will be able to request the new key using the same URL as the old one (the object isn't removed and the ID doesn't change).

Servers

Servers are objects representing your own hosting servers. They are part of a server group, which governs which default policies apply to the end-users of the server.

Server license cancellation

To request the cancellation for a server, you can use the cancel action using a POST request. No content is required in the POST body. If the server can be removed immediately, this call will cancel the license and remove the server from your account. If the server can not be removed immediately, the license will be canceled and removed on the first allowed removal date. The removal date is determined by your plan's license period, and can be seen as the property removable_per on the server object.

You can only cancel a server that has been approved (i.e. is active) and has not yet been cancelled. For removing an unapproved server, please refer to this section.

Server approval

When a newly installed server contacts the Portal, it has to be approved before it will be fully activated and allowed to start scanning. You can approve a server using a POST request to the approve action on a Server object. During approval, you may change the hostname and server group of a server as well. Note that an unapproved server will always be created as a member of the default server group if you don't change this property before or during approval.

The action will not have any effect on an already approved server, even if you specify changes on the hostname and/or server group fields. Please use the regular server update method if you wish to change those properties after approval.

Removing unapproved servers

If a server creation request has been submitted for your account but you don't want to approve the server, you can delete it using the DELETE method on the server object in question (not the approve action).

Please note that deleting an unapproved server is not the same as cancelling the license for an approved and active server. That action is documented here. Performing this action on any server that has already been approved will be rejected.

Server Groups

A server group contains common settings for all servers that are part of the server group.

Policies

Policies are sets of rules that apply to end-users. Any end-user has only one applicable policy at a given time, and may be set explicitly on the end-user object, but also on one of its parent end-users or at the server level.

The availability of adding and changing policies depends on the plan of the organization.

Policies Base Email Template

The policy base email templates are used as a base for formatting email messages sent to end-users.

End-users

End-users are accounts on your server.

End-user Metrics

Obtains the number of resolved and unresolved detections for each of the three types: malware, vulnerabilities and outdated applications.

These counts reflect the number of results if you were to call Detections with an end-user filter.

Detections

Patchman reports various kinds of detections. Each kind of detection has different parameters and supports different actions. Take care that you implement usage of these API resources separately.

All fields on detections and their associated actions are read-only. The only allowed modification is the creation of new actions for detections. Which actions are allowed depends on the type of detection, the current state of the detection, your policy settings and your plan.

Detections can be sorted by providing ordering GET parameter to the request. The value should be a comma separated list of fields by which detections will be ordered. By default the order is ascending, if descending order is desired, the field must be prefix by a "-" sign. Every detection end-point below gives a list of fields by which it can be ordered.

Applications

Application detections report the detected installations of web software packages. Only current detections are listed. Note that no actions are available for application detections.

Malware

Malware detections list script files with malicious purposes. These malware detections are based on hash matching. No dynamic malware will be returned using this API endpoint.

Malware actions

Each malware detection has actions associated with it to denote the various changes that can be made to a file that was detected as malware. You cannot modify existing actions, but you are allowed to create new actions. These actions are for hash based detections. Actions submitted for dynamic malware to this endpoint will result in detection not found.

Dynamic malware

Dynamic malware detections list script files with malicious purposes. These malware detections are based on rules that match partial files. No hash based malware detections will be returned using this API endpoint.

Dynamic malware actions

Each dynamic malware detection has actions associated with it to denote the various changes that can be made to a file that was detected as malware. You cannot modify existing actions, but you are allowed to create new actions. These malware detections are based on rules that match partial files. Actions submitted for hash based malware to this endpoint will result in detection not found.

Vulnerabilities

Vulnerability detections list files of installed web application software containing exploitable security vulnerabilities.

Vulnerability actions

Each vulnerability detection has actions associated with it to denote the various changes that can be made to a file that was detected as vulnerable. You cannot modify existing actions, but you are allowed to create new actions.

File Cleans

If your plan allows it, malware rule detection files will be automatically cleaned by Patchman. Consecutive cleans within the grace period (of the last clean) are grouped together, unless the time between the first and a new clean is more than the grace period limit, which is a setting on your plan.

All fields on file cleans are read-only.

End-user Token Retrieval

Part of this API, but not publicly exposed (as this uses a different authentication scheme) is retrieving a token for end-user authentication. This token is used by the end-users of a server to access the Patchman Portal interface detailing their specific user. This API is intended for use by control panel plugins and only available if the plan of the organization enables end-user logins. Additionally, this API will return HTTP 403 errors if the end-user has no policy that allows end-user logins.

This API is only available using the license certificate and key issued to server and only from the same IP that has been registered with Patchman. Authentication occurs through HTTPS client certificates. For OAuth2 authentication see token_url on End-users.

After issuing a successful request, the API returns a URL you should redirect your user to. This URL will take care of placing an authentication cookie on the end-user's computer. Following this, the user will be redirected to the page provided in the next argument, or (if this is not provided) to the default user view. Note that the redirect URL is only valid for one minute.

File Reporting

Patchman has many definition signatures to detect malware scripts, but it is inevitable that some malware may slip through. When you encounter such scripts, we would like to add it to our repository. This public API method allows you to submit malware samples to our reviewers, which may then result in adding it to our database.

Please try to be as descriptive as possible when submitting a file. Use the type field to describe in one or two words what you think the script is (e.g. phishing, spam, shell, etc) and the optional description field to add more context (e.g. observed behaviour, how you encountered it, etc).

Users

You can manage user accounts for the Portal through the API, for example if you wish to integrate this with the central staff user account management of your organization.

Note: upon creation of a user account through the API, a confirmation e-mail with the user's randomly generated password will be sent to the e-mail address you provide. There is no way to specify the password yourself.

Suborganizations

If your plan allows it, you can resell Patchman to your larger customers. Within Patchman, these are known as suborganizations. You can determine exactly which functionality of the product you want them to be able to tune themselves, while also keeping control through your own account. All billing will still pass through your own account.

Suborganization users

Like your own organization, suborganizations require one or more user accounts that can access the Portal, manage settings and view detections. The management of suborganization users is exactly the same as user management for your own organization.

Note: upon creation of a user account through the API, a confirmation e-mail with the user's randomly generated password will be sent to the e-mail address you provide. There is no way to specify the password yourself.