PatrolServer API

Introduction

PatrolServer is a service for developers to keep track of outdated software on their servers. We run a daily scan on your servers, to make sure you run updated software. We would like to make it easy for you developers to integrate with our services and delivery across many platforms. Our powerful APIs are here to provide you a smooth integration with your own project.

Our developer tools allow you to access your own data within the PatrolServer architecture. Our ultimate goal is to cover most virtual facets of PatrolServer, for you to integrate whenever you want. The PHP SDK provides a stable interface to implement PatrolServer functionality in your own applications.

GETTING STARTED: You can download the SDK on GitHub.

Register an API key

In order to start to develop with us, it is mandatory to register your application and retrieve an API key and a secret. We'll guide you through this with the following steps:

1. Access the PatrolServer dashboard.
- In case you have no account, register your own account on PatrolServer.
- If you have an account, login to your PatrolServer dashboard.
2. Request an API key and secret in the API settings page.
3. You can now start developing your application!

Your API credentials

You are currently logged in as <% user.email %>, and you have a key and secret credential linked to your account.

Connect to the API

The PatrolServer API uses the REST format, and is built in a resource-oriented structure. The API fully supports cross-origin resource sharing, which enables you to interact with our API from any application.

The API responses are returned in a JSON format.

Endpoint

http://api.patrolserver.com

Errors

PatrolServer uses the standard HTTP response status codes in order to indicate whether a response contains the correct data or not. When your request is succesfully handled, it will be sent back to you with a code in the range of 2xx. In detail, this means the action requested by the client was received, understood, accepted and processed successfully. The 4xx class of status code is intended for cases in which the client seems to have erred. This means an error occured based on the request. Any code related to 5xx is an error on our end, but they are very rare.

Fields

code number

The PatrolServer error code

http_code number

The HTTP status code

message string

An understandable message which shows more information about this error

200 - OK	Standard response for successful HTTP requests.
400 - Bad Request	The server cannot process the request due to something that is perceived to be a client error, mostly due to a malformed request syntax.
405 - Not Found	The requested resource could not be found.
500 - Server Error	An unknown server error. These are rare, but we log them and fix them as soon as possible.

Error codes

When the PatrolServer API returns error messages, it does so in JSON format. The error format is described above, and contains a code field, which projects the current type of error. As a developer, you can use these codes to integrate certain behaviors in your application when an error occurs.

In addition to error text describing the error itself, each error message has a unique code bound to the action performed. While the text for error messages may change in the future, the codes will always stay the same.

The table next describes the current codes that may appear when working with the API.

3	Auth failed	Authentication failed.
4	No key/secret	A key and secret parameter is mandatory.
5	Insufficient rights	You do not have the rights to access this resource.
6	Locked	Your requests are currently locked for an unknown period of time.
13	User not found	The requested user profile can not be found.
21	Server not found	The requested server could not be found.
22	Server maximum exceeded	You're at the maximum capacity of servers on your account.
23	Server already verified	The server you're trying to verify is already verified.
24	Server not verified	In order to succesfully perform this task, the server needs to be verified.
25	No server verification token	Request a token for this server before proceeding.
26	Domain mismatch	The verification domains do not match.
31	Software not found	The requested software could not be found.
41	Bucket not found	The requested bucket could not be found.
42	Bucket not unique	The name of the bucket already exists.
51	Webhook not found	The requested webhook can not be found.
52	Event not found	The requested event can not be found.
101	Filter not found	The requested filter can not be found.
111	API credentials not found	The requested credentials can not be found.
81	Parse error	The input can not be parsed.
82	Input error	Wrong input in the request.
-1	Fatal error	Shouldn't happen at all.

Authentication

You can authenticate your account with the API by including a key and a secret parameter in the request. If you're logged in to your PatrolServer account, both your key and secret should be visible in the section above. It is advised to keep your API secret private, as it contains many privileges. Do not share your secret publicly and double check for any hard-coded credentials when pushing your code to services like GitHub, Bitbucket, ...

All the API requests must be made over HTTPS, only then we can provide you maximum security. API requests without authentication will fail.

Request

$ curl http://api.patrolserver.com/servers?key=KEY&secret=SECRET

When your credentials are valid, all examples will work and will contain your own key and secret variables. But please, do not store your secret in a client-side application as it will expose the value.

We'll initialize the library with our unique key and secret pair. When the SDK is not initialized with credentials, it will not function as expected.

Example code

// Use the Singleton or create a separate PatrolSdk\Patrol object
use PatrolSdk\Singleton as Patrol;

Patrol::setApiKey('<% user.key %>');
Patrol::setApiSecret('<% user.secret %>');

Scopes

Scopes are parameters you can use to get additional information. By default, we restrict the amount of information you can request through the API. However, you can force the API to send back more related data by specifying a scope variable.

Example: You can collect a list of all your servers by using the /servers API. Now, we'd like to get the vulnerability status with all those servers. Instead of calling a details API endpoint for each server, we apply the exploitable scope.

Request

$ curl http://api.patrolserver.com/servers?key=KEY&secret=SECRET&scope=status,exploitable

The call above will not only list your current servers, but will also contain a status and exploitable field for each server.

When SDK methods support scopes, an example will be given. Just scroll down and you'll see where you can enter scopes when fetching data from the API.

Versioning

Our API supports versioning so that app builders can roll out changes over a period of time. We introduce new changes but keep the old ones for atleast one version update. This gives developers the time to adapt to new changes. Minor changes to the API will always keep your API integration up and running, when major changes might need development work in order to migrate.

The API returns an apiVersion field that displays the current version.

Servers

Server objects are representations of a single server. They can be used to lookup your current server statuses and allow developers to interact with their servers. The API allows you to create, delete and retrieve your servers. Both individual and in a collection.

List all servers

Provides a list of your servers. They are returned sorted by creation date, with the oldest server listed first.

Fields

id number

name string

The name of the server

url string

The full url (with port)

verified boolean

Whether or not this server completed the verification process

exploitable boolean, null when never crawled

exploitable

Whether your server contains outdated software or not

status object

status

Contains the status of your current server

last_finished_crawl datetime

The last timestamp the server finished crawling

last_requested_crawl datetime

The last timestamp a crawl has been requested. If the requested time is after the finished crawling time, this indicates that the server is currently being scanned

created_at datetime

Creation timestamp

updated_at datetime

Last time the server contents have been updated

verification_methods object

verification_methods

Information about how to verify your server. Can happen by email, HTML file or by installing the Bash Scanner

by_email object

The allowed verification email addresses in the options property.

by_html_file object

Information and download URL of the verification HTML file.

Definition

GET http://api.patrolserver.com/servers

Request

$ curl http://api.patrolserver.com/servers?key=KEY&secret=SECRET

Response

{
    "apiVersion": "1.0",
    "data": [
        {
            "id": 123,
            "name": "example.com",
            "url": "http:\/\/example.com:80",
            "verified": true
        },
        {
            "id": 124,
            "name": "blog.server.com",
            "url": "http:\/\/blog.server.com:80",
            "verified": false
        }
    ]
}

Example code

// Get all the servers from the account linked to the key or secret above
$servers = Patrol::servers();

foreach ($servers as $server) {
    echo $server->url . "\n";
}

// Use scopes to fetch data
// As an optional parameter when fetching servers, you can provide scopes
$servers = Patrol::servers(['exploitable', 'status']);

foreach ($servers as $server) {
    echo $server->url . ": " . $server->exploitable . "\n";
}

Retrieve a server

Retrieves the details of an existing server. You supply the identifier of the particular server that you would need.

Fields

id number

name string

The name of the server

url string

The full url (with port)

verified boolean

Whether or not this server completed the verification process

exploitable boolean, null when never crawled

exploitable

Whether your server contains outdated software or not

status object

status

Contains the status of your current server

last_finished_crawl datetime

The last timestamp the server finished crawling

last_requested_crawl datetime

The last timestamp a crawl has been requested. If the requested time is after the finished crawling time, this indicates that the server is currently being scanned

created_at datetime

Creation timestamp

updated_at datetime

Last time the server contents have been updated

verification_methods object

verification_methods

Information about how to verify your server. Can happen by email, HTML file or by installing the Bash Scanner

by_email object

The allowed verification email addresses in the options property.

by_html_file object

Information and download URL of the verification HTML file.

Definition

GET http://api.patrolserver.com/servers/:id:

Request

$ curl http://api.patrolserver.com/servers/<% con.server_id %>?key=KEY&secret=SECRET&scope=exploitable,status

Response

{
    "apiVersion": "1.0",
    "data": {
        "id": 123,
        "name": "example.com",
        "url": "http:\/\/example.com:80",
        "verified": true,
        "status": {
            "last_finished_crawl": "2015-12-17 13:51:33",
            "last_requested_crawl": "2015-12-17 11:19:18",
            "created_at": "2015-12-17 11:19:17",
            "updated_at": "2015-12-17 13:51:35"
        },
        "exploitable": true
    }
}

Example code


// Specify the server id
$id = 1;

// Get a single server by id
$server = Patrol::server($id);
echo $server->url . "\n";

// Use scopes to fetch data
// As an optional parameter when fetching a single server, you can provide scopes
$server = Patrol::server($id, ['exploitable', 'status']);
echo $server->url . ": " . $server->exploitable . "\n";

Create a server

Creates a new server, which is a process split in 3 steps.

1. Creating your server by sending the domain through the API.
2. Requesting a verification token in order to verify your domain.
3. Verifying your server with the verification token.

1. Creating

Store your server by providing a domain name.

POST Fields

domain string

The domain name you want to add

A valid server object will be returned.

Once the server object is persisted, it will contain valid data upon success and $server->id will be accessible.

Definition

POST http://api.patrolserver.com/servers

Example

$ curl http://api.patrolserver.com/servers?key=KEY&secret=SECRET \
    -d domain=example.com \
    -X POST

Example code

// Create a server instance
$server = Patrol::server();

// Specify the domain
// $server->domain = "example.com";
// $server->domain = "http://example.com";
$server->domain = "example.com:80";

$server->save();

2. Requesting

Request a verification token for your particular domain.
Note: You must request the token on the server where "example.com" (in our example case) is located.

GET Fields

domain string

The domain name you want to add

When a valid token is generated, the following data will be available and is mandatory in order to verify your server.

Fields

token string

Unique token that you need to verify your server

is_new boolean

Indicates whether this token has been created before or is fresh.

Definition

GET http://api.patrolserver.com/request_verification_token?domain=example.com

Example

$ curl http://api.patrolserver.com/request_verification_token?key=KEY&secret=SECRET&domain=example.com

Succesful Response

{
    "apiVersion": "1.0",
    "data": {
        "token": "e344ee61f84941745c835bcd346c8a7ca40d3f761f960e6280aec7b3eec035ec6dbf4370cd6c758e3b79c5b1c7856d327b4f1aa7e63a8737f5b9e1dd6bd966de",
        "is_new": false
    }
}

Failed Response

{
    "apiVersion": "1.0",
    "error": {
        "message": "You must request a token on the server where your domain example.com is located. The requested machine should have the ip 93.184.216.34, but you request a token from the ip 216.58.209.238"
    }
}

Example code

// Request a verification token
$token = $server->requestVerificationToken();

3. Verifying

When your token matches the domain name, your server is verified and will provide scanning details.

POST Fields

token string

The token generated in the step above must be included

Definition

POST http://api.patrolserver.com/servers/:id:/verify

Example

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/verify?key=KEY&secret=SECRET \
    -d token=e344ee61f84941745c835bcd346c8a7c \
    -X POST

Example code

// Verify your server with the token
$response = $server->verify($token);

print_r($response);

Alternative: Verify by email

When you request your server, use the verification_methods scope to get alternative methods for verifying your server. One of the alternative methods is verification by email. The system provides you with certain email addresses that you can use in order to verify your server. Use this endpoint to send an email to one of the pre-defined email addresses.

POST Fields

email string

The verification email requested when fetching a single server.

Definition

POST http://api.patrolserver.com/servers/:id:/verifyByEmail

Example

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/verifyByEmail?key=KEY&secret=SECRET \
    -d email=info@example.com \
    -X POST

Alternative: Verify by HTML file

You can upload a HTML file on your server and use this endpoint to verify if the file is present. When the system detected your HTML file, it will automatically verify your server.

Note: You can know the download URL by requesting your server with the verification_methods scope.

Definition

POST http://api.patrolserver.com/servers/:id:/verifyByHtmlFile

Example

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/verifyByHtmlFile?key=KEY&secret=SECRET \
    -X POST

Delete a server

Delete a server by unique identifier. This action can not be undone. It also immediately deletes all related data from this particular server.

Definition

POST http://api.patrolserver.com/servers/:id:/delete

Example

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/delete?key=KEY&secret=SECRET \
    -X POST

Example code

// Specify the server id
$id = 1;

// Get a single server by id
$server = Patrol::server($id);

// Delete the server
$server->delete();

Scan a server

Trigger the command to scan your server.

Manually triggered scans will also invoke your webhooks. When scan is executed, a webhook.scan_started event will be sent to your webhook. You may then implement whatever you like.

Definition

POST http://api.patrolserver.com/servers/:id:/scan

Example

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/scan?key=KEY&secret=SECRET \
    -X POST

Example code

// Specify the server id
$id = 1;

// Get a single server by id
$server = Patrol::server($id);

// Trigger a scan
$server->scan();

Scanning status

The status of your server will either be that it is scanning or that your server is not being scanned at the moment.

Definition

GET http://api.patrolserver.com/servers/:id:/isScanning

Request

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/isScanning?key=KEY&secret=SECRET

Response

{
    "apiVersion": "1.0",
    "data": true
}

Example code

// Specify the server id
$id = 1;

// Get a single server by id
$server = Patrol::server($id);

// Check if this server is scanning
if (server->isScanning()) {
    // This server is currently being scanned
}

Software

Software objects are representations of installed software on your server. They can be used to lookup your currently installed software and exploits found on your server. The API allows you to retrieve the installed software of your servers. Both individual and in a collection.

List server software

Provides a list of all the software installed on a particular server you own.

Fields

id number

name string

The name of the software

canonical_name string

The canonical name of the software

supported string

Indicates if this installed software is still supported. Values can be "yes", "no" or "unknown"

version string, single or multiple

A single version is found

versions array, single or multiple

Multiple versions are found, or the version is guessed and we can be certain it is one of these

newest_bugfix_release string

Only available when we know a stable new version

parent string

When this software has a parent. Example: A Drupal module is found, and will have "drupal" as it's parent

location string

The location where the software is found

created_at datetime

The date when the software has been lastly detected

exploits array

exploits

A list of all exploits currently available in this particular software package, in the same format as the Exploit object

Definition

GET http://api.patrolserver.com/servers/:id:/software

Request

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/software?key=KEY&secret=SECRET

Response

{
    "apiVersion": "1.0",
    "data": [
        {
            "id": 180,
            "name": "PHP",
            "canonical_name": "php",
            "supported": "no",
            "location": "/var/web/software",
            "version": "5.5.24",
            "parent": null,
            "created_at": "2016-02-02 00:00:37"
        },
        {
            "id": 181,
            "name": "Drupal",
            "canonical_name": "drupal",
            "supported": "yes",
            "location": "/",
            "version": "7.2",
            "parent": null,
            "created_at": "2016-02-02 00:00:37"
        },
        {
            "id": 182,
            "name": "Drupal Router",
            "canonical_name": "drupal:router",
            "supported": "unknown",
            "location": "/",
            "parent": "drupal",
            "created_at": "2016-02-02 00:00:37"
        }
    ]
}

Example code

$id = 1;

$server = Patrol::server($id);

// Collect all the software found on this server
$software = $server->allSoftware();

foreach ($software as $singleSoftware) {
    echo $singleSoftware->name . "\n";
}

// Use the exploits scope to list the amount of exploits found in the software
// The allSoftware method accepts an array with scopes
$software = $server->allSoftware(['exploits']);

foreach ($software as $singleSoftware) {
    echo $singleSoftware->name . " has " . count($singleSoftware->exploits) . " exploits" . "\n";
}

Retrieve software

Retrieves the details of an existing installed software object. You supply the identifier of the particular installed software that you would need.

Fields

id number

name string

The name of the software

canonical_name string

The canonical name of the software

supported string

Indicates if this installed software is still supported. Values can be "yes", "no" or "unknown"

version string, single or multiple

A single version is found

versions array, single or multiple

Multiple versions are found, or the version is guessed and we can be certain it is one of these

newest_bugfix_release string

Only available when we know a stable new version

parent string

When this software has a parent. Example: A Drupal module is found, and will have "drupal" as it's parent

location string

The location where the software is found

created_at datetime

The date when the software has been lastly detected

exploits array

exploits

A list of all exploits currently available in this particular software package, in the same format as the Exploit object

Definition

GET http://api.patrolserver.com/servers/:id:/software/:software_id:/

Request

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/software/<% con.software_id %>?key=KEY&secret=SECRET&scope=exploits

Response

{
    "apiVersion": "1.0",
    "data": {
        "id": 232,
        "name": "OpenSSH",
        "canonical_name": "openssh",
        "supported": "no",
        "location": "/",
        "parent": null,
        "version": "5.3",
        "created_at": "2016-02-02 00:07:23",
        "exploits": [
            {
                "cve": "CVE-2010-4478",
                "risk": 7.5,
                "detected_at": "2016-02-02 00:07:23"
            },
            {
                "cve": "CVE-2010-4755",
                "risk": 4,
                "detected_at": "2016-02-02 00:07:23"
            }
        ]
    }
}

Example code

$server_id = 1;
$software_id = 2;

$server = Patrol::server($server_id);

// Without scopes
$software = $server->software($software_id);
print_r($software);

// With the exploits scope, returning a list of exploits
$software = $server->software($software_id, ['exploits']);
print_r($software);

Exploits

Exploit objects are representations of exploits found in your installed software. They can be used to lookup your currently vulnerable exploits from the software found on your server. They are only listed as a collection.

List software exploits

Provides a list of all the exploits present in the software found on your server.

Fields

cve string

A CVE is a list of information security vulnerabilities and exposures that aims to provide common names for publicly known problems

risk number

A risk factor based from 1 (minor) to 10 (major)

detected_at datetime

The moment this exploit has been detected on the server

Definition

GET http://api.patrolserver.com/servers/:id:/software/:software_id:/exploits

Request

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/software/<% con.software_id %>/exploits?key=KEY&secret=SECRET

Response

{
    "apiVersion": "1.0",
    "data": [
        {
            "cve": "CVE-2010-4478",
            "risk": 7.5,
            "detected_at": "2016-02-02 00:07:23"
        },
        {
            "cve": "CVE-2010-4755",
            "risk": 4,
            "detected_at": "2016-02-02 00:07:23"
        }
    ]
}

Example code

$server_id = 1;
$software_id = 2;

// Get server
$server = Patrol::server($server_id);

// Get a single software item from the server
$software = $server->software($software_id);

// Get all exploits in the single software item
$exploits = $software->exploits();

Webhooks

A webhook is a way for PatrolServer to provide other applications with real-time information. Our webhooks deliver data to other applications as it happens, meaning you get data immediately. When an event occurs, we create a new Event object. For example, your server has finished scanning, we create a webhook.scan_finished event which you can then retrieve by using the corresponding API endpoint.

Webhooks can be created and managed in the API settings page. Simply enter your server endpoint, and we will send a POST request to that URL with further information regarding the event.

Triggers

It is important to understand how our webhooks work in order to implement them correctly. We will simulate the webhook.test event, which is caused when testing the webhook for arrival in the API settings page.

1. The webhook.test event occurs. A new Event object is created and stored on our server.
2. A POST request is sent to the webhook URL from your API settings page, containing webhook_id and event_id.
3. Your code can access the Event object through the API with your key and secret.

Fields

webhook_patrolserver number, defaults 1

Verifier

identifier string

Name of the event

event_id string

The event identifier

webhook_id string

The webhook identifier

Received payload

{
    "webhook_patrolserver": 1,
    "identifier": "webhook.test",
    "event_id": 18,
    "webhook_id": 219
}

The data needed to fetch the event will be delivered in JSON format. We guarantee that events will be accessible for fetching for a maximum of 30 days.

Definition

GET http://api.patrolserver.com/webhooks/:webhook_id:/events/:event_id:

Request

$ curl http://api.patrolserver.com/webhooks/21/events/52?key=KEY&secret=SECRET

The following response is an example of the webhook.new_server_issues event, which gets triggered when your server becomes vulnerable or when new issues are found.

Response

{
    "server_id": 1,
    "new_issues": [
        {
            "title": "Upgrade your PHP to a supported version.",
            "description": "Your current PHP version (5.2.27) is no longer supported, it is advised to upgrade to a supported version.",
            "software": {
                "version": "5.2.17",
                "software": {
                    "name": "PHP",
                    "canonical_name": "php"
                }
            }
        }
    ]
}

We'll wrap this in an example, imagine you've hosted a PHP file on your website with the the following URL: http://example.com/webhook.php. This particular URL is added on your dashboard and we will send a webhook event whenever one occurs. The code below are the contents of the file.

// Use the Singleton or create a separate PatrolSdk\Patrol object
use PatrolSdk\Singleton as Patrol;

Patrol::setApiKey('<% user.key %>');
Patrol::setApiSecret('<% user.secret %>');

Patrol::webhook('webhook.scan_finished', function ($event) {
    // Get the Server object from the server_id
    $server = Patrol::server($event['server_id']);

    // Get the installed software
    $software = $server->allSoftware();

    // The variable $software contains all the software that we've found on your server
});

Patrol::webhook('webhook.new_server_issues', function ($event) {
    $server = Patrol::server($event['server_id']);
    $issues = $event['new_issues'];

    foreach ($issues as $issue) {
        $installed = $issue['software'];
        $software = $installed['software'];

        $version = "unknown";

        if (isset($installed['version']))
            $version = $installed['version'];
        if (isset($installed['versions']))
            $version = implode(', ',$installed['versions']);

        $str = $software['name'] . ' ' . $version . ' is no longer safe.';

        // $str is a textual representation of the software with current version no longer being safe.
    }
});

Event types

Fields

webhook.scan_started started

When we finished scanning your server, both manually or automatically, this webhook will inform your application.

webhook.scan_finished finished

When a scan is started, both manually or automatically, this webhook will inform your application.

webhook.new_server_issues new issues found

When new issues are found on your server. Let's say, your PHP software package suddenly becomes outdated, this webhook will inform your software about the fact that that particular server now runs an outdated PHP package.

Buckets

Storing data in buckets makes it possible to add your own software with versions to the PatrolServer architecture. Let's take BashScanner for example. It lists the software on your server and stores it in a bucket. PatrolServer then uses the data in the buckets in order to scan.

Fields in buckets are one character long.

Retrieve a bucket

Provides a bucket bound to a specific server. You can specify the key and the corresponding bucket will be returned, together with the software it contains.

POST Fields

id number

server_id number

key string

The name of the bucket.

software array

Collection of the software stored in the bucket.

n string

The name of the software package.

v string

The version of the software package.

l string

The location of the software package.

p string

The parent of the software package. Let's say we want to scan a Drupal package, then drupal will be set as parent.

expire number

The amount of seconds needed to expire this bucket. When a bucket is expired, it will no longer be used to scan the software.

created_at datetime

The date and time when the bucket is created.

updated_at datetime

The date and time when the bucket has lastly been updated.

Definition

GET http://api.patrolserver.com/servers/:id/buckets/:key:

Request

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/buckets/testBucket?key=KEY&secret=SECRET

Response

{
    "apiVersion": "1.0",
    "data": {
        "id": 3,
        "server_id": 9,
        "software": [
            {
                "n": "php",
                "v": "5.5.8",
                "l": "/"
            }
        ],
        "created_at": "2016-02-17 13:28:03",
        "updated_at": "2016-02-17 13:28:03",
        "key": "testBucket",
        "expire": null
    }
}

Example code

// Specify the server id and bucket key
$id = 1;
$bucket_key = 'testBucket';

// Get a single server by id and retrieve the bucket
$bucket = Patrol::server($id)->bucket($bucket_key);

print_r($bucket);

Create a bucket

This endpoint allows a user to add their own software in the form of a bucket to their servers.

In this example, we will add PHP 5.5.8 manually to the scanner and the data will be stored in a bucket with the key testBucket. Eventually, the data stored in the bucket will be used to perform a scan and if it is outdated, a card will be shown in the dashboard and exposed through the API/webhooks.

POST Fields

id number

server_id number

key string

The name of the bucket.

software array

Collection of the software stored in the bucket.

n string

The name of the software package.

v string

The version of the software package.

l string

The location of the software package.

p string

The parent of the software package. Let's say we want to scan a Drupal package, then drupal will be set as parent.

expire number

The amount of seconds needed to expire this bucket. When a bucket is expired, it will no longer be used to scan the software.

created_at datetime

The date and time when the bucket is created.

updated_at datetime

The date and time when the bucket has lastly been updated.

Definition

POST http://api.patrolserver.com/servers/:id:/buckets/:key:

Example

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/buckets/testBucket?key=KEY&secret=SECRET \
    -d software[0][n]=php \
    -d software[0][v]=5.5.8 \
    -d software[0][l]=/ \
    -d expire=604800 \
    -X POST

Example code

// Specify the server id and bucket key
$id = 1;
$bucket_key = 'testBucket';

// Get a single server by id and retrieve the bucket
$bucket = Patrol::server($id)->bucket($bucket_key);

// Store software in the bucket in the requested format
$bucket->software = [
    [
        "n" => "php",
        "v" => "5.5.8",
        "l" => "/",
        "p" => ""
    ]
];

// Set an expiration time
$bucket->expire = 60*60*24*7; // for 7 days, we'll use this data to scan your server

$bucket->save();

Update a bucket

Updating a bucket is entirely the same as creating a bucket. If the key already exists, the software data will be replaced with the new software data.

Note: it is important to update the expire field when updating a bucket.

Delete a bucket

Delete a bucket by its key. This action can not be undone. It also immediately deletes all related data from this particular bucket.

Definition

POST http://api.patrolserver.com/servers/:id:/delete

Example

$ curl http://api.patrolserver.com/servers/<% con.server_id %>/buckets/testBucket/delete?key=KEY&secret=SECRET \
    -X POST

Example code

// Specify the server id and bucket key
$id = 1;
$bucket_key = 'testBucket';

// Get a single server by id and retrieve the bucket
$bucket = Patrol::server($id)->bucket($bucket_key);

// Delete the bucket
$bucket->delete();

<% l.name %>

Request

Fetch API endpoint

Response