Logo

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.

Login with your PatrolServer account to view your API credentials.

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();
© 2016 - PatrolServer

Response