Lastline Appliance Management API¶

The Lastline Appliance Management API is accessible at:

https://user.lastline.com/papi/appliance_mgmt/<function>

Appliance Types¶

The currently supported appliance types are listed below. All API methods returning or requesting an appliance type, will return or accept one or more of these types:

ANALYST

ENDPOINTMGR

ENGINE

MANAGER

PINBOX

SENSOR

Response Format¶

Each of the API functions supports XML and JSON as response format. To request a given format, .xml, respective, .json can be appended to the URL.

For example, the following URL will return the response XML formatted:

https://user.lastline.com/papi/appliance_mgmt/status.xml

If no response format is provided, JSON is used.

Methods¶

Method Index¶

overview():

Return overall status information for the appliances of the current user.
status():

Return detailed status information for a specific appliance.
configuration():

Return the current configuration for a specific appliance.
coordinates():

Set latitude and longitude information for a given appliance.
action_request():

Request that the appliance perform an action.
action_status():

Return the status of a requested action.
action_list():

Return the status of recent appliance actions.

Method Documentation¶

appliance_mgmt.overview(response_format)¶

Return overall status information for all appliances of the current user.

URL

/papi/appliance_mgmt/overview[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

appliance_type:

Comma separated list of appliance types. Optional, defaults to all.

filter_offline_duplicate:

Filter sensor, manager, analyst and pinbox appliances based on their licenses and online status. That is, do not return sensor appliances which are offline if there exists an online sensor appliance in the result with the same license. Optional, defaults to true.

filter_dangling:

Remove all offline appliances whose manager is not known or not returned because they have been filtered by filter_offline_duplicate. Optional, defaults to true.

timezone:

The timezone to convert timestamps to. Optional, defaults to UTC.

Contents of successful response

data
Contains a map of appliance UUIDs to a further map containing status information about each appliance:
"data": {
    "8b6b397048d8497caba6f9092973d68d": {<appliance_info>},
    "94f11a73df5247eaa7c25548799ebc63": {<appliance_info>},
}
Each appliance_info can contain the following fields.

General information

type:

One of the supported appliance types.

license:

The license information used by this appliances. For sensor appliance this contains the sensor licenses separated by a colon.

license_status:

The expiration status of the license used by this appliance, one of active, near-expiration, expired

license_expiration:

The expiration date of the license used by this appliance

license_product:

Lastline product for the license (Availabile from Lastline Enterprise or Analyst On-Premises version 7.15)

access_key_id:

Opaque numeric identifier for the license.

name:

Only available for sensor appliances. Represents the name associated with the sensor license. May be null or absent for other appliances.

fqdn:

The fully qualified domain name as reported by the appliance. Usually determined using socket.getfqdn().

registration_status:

Status of the appliance registration, one of REGISTERED, DISABLED, UNREGISTERED or DEREGISTERED

Connection related information

public_ip:

The IP of the appliance as determined by the receiver of a checkin. Can be 127.0.0.1 on self-managing appliances.

internal_ip:

The IP of the interface used for external connections.

connections_status:

Either online or offline as determined by the backend based on the time of the last checkin

last_checkin_ts:

The timestamp of the last checkin. This timestamp represents the time on the appliance. The format is YY-mm-dd HH:MM:ss.

last_backend_ts:

The timestamp when the checkin was received/processed by the backend. The format is YY-mm-dd HH:MM:ss.

manager_appliance_uuid:

The appliance UUID of the manager appliance. This field applies to sensor and engine appliances only. May be null or absent for other appliance types.

lat/lng:

Latitude and longitude as configured using coordinates() or determined using geoip. May be null.

Version related information

configured_software_version:

The configured version of this appliance.

reported_software_version:

The version as reported by the appliance.

latest_software_version:

The latest version available for this appliance. May be null if no information is available.

staged_release_version:

The latest staged release available for this appliance. May be null if no information is available.

update_status:

One of up-to-date, outdated or testing/pre-release or up-to-date (new version available) based on the values of reported_software_version, latest_software_version, and staged_release_version.

required_distribution:

In case the latest software version available for this appliance does not support its current distribution and the appliance is at the last version supporting its distribution, this will be set to the next distribution the appliance needs to be upgraded to. (available for Lastline Enterprise On-Premise versions >= 7.15)

User information

can_manage:

Can the currently authenticated user manage this appliance. That is, can the user see detailed logs of components and send configuration action requests.

Status information
action:
Points to a map containing information about the most recent executed action. The following fields are available in the map:

status:

One of pending, error, success.

action_type:

The type of the action.

action_uuid:

The action UUID identifying this action. Can be used with action_status() to get more information about the status of this action.

note:

Short human readable note about the action status.

Example:
"action": {
    "note": "Error applying configuration.",
    "status": "error",
    "action_type": "CONFIGURE",
    "action_uuid": "d76e5e072d0740da8bde4d6205414a3f"
}
components:
Points to a map holding the status of an appliance divided by top-level components. Top-level components are specific to the type and version of the appliance. Each key in the map represents the name of a component and points to another map containing the following two fields:

status:

One of OK, WARNING, ERROR or DISABLED. To get detailed information about the status of a component in case of WARNING or ERROR, the API method status() can be used.

message:

A short message describing the issue in case the status is ERROR or WARNING.

Following is an example of the components field.
"components": {
    "Management": {
        "status": "OK",
        "message": ""
    },
    "Analysis": {
        "status": "OK",
        "message": ""
    },
    "Integrations": {
        "status": "ERROR",
        "message": "Error in Logs"
    },
    ...
}

appliance_mgmt.status(response_format)¶

Return detailed status information of a single appliance.

URL

/papi/appliance_mgmt/status[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

appliance_uuid:

Unique identifier of an appliance (required)

timezone:

The timezone to convert timestamps to. Defaults to UTC.

Contents of successful response

data:

Contains the <appliance_info> map as described for the API method overview() for the requested appliance. The components field is replaced by a status field as described below, providing more detailed information about the status. A capabilities field is added as described below.

The following fields are added to the <appliance_info> map:

capabilities:

A list of capabilities provided by the requested appliance’s license and that license’s children.

status:

A hierarchical structure describing the components of the requested appliance. The structure and content is dependent on appliance type and configured version of the appliance. The first level contains fields pointing to maps as described below.

Each map of this structure has the following entries:

component_type:

One of GROUP or DETAIL.

position:

A numeric value the UI can use for ordering.

displayname:

A name that can be show in the UI.

If component_type is SUMMARY, all other fields point to further maps. These maps represent sub-components.

If a map has component_type set to DETAIL, additionally any of the following fields are available:

status:

One of OK, WARNING, ERROR or DISABLED.

value:

A value to display. Used for addresses, hostname.

note:

OK or DISABLED. Short human readable note about the component in case status is not OK or DISABLED.

log:

Detailed information about the component in case status is not OK or DISABLED.

In general, keys pointing to sub-components have no meaning associated with them. However, the current choice are readable shortenings of the displayname.

Error Codes

LLAPI_APPLIANCE_MGMT_ERROR__NO_SUCH_APPLIANCE

Example status Field

The following is an example of the status field containing three summary components displayed as Libraries, Integrations and System:

"status": {
    "libs": {
        "component_type": "GROUP",
        "displayname": "Libraries",
        "position": 60
        "libs.llfile": {
            "status": "OK",
            "position": 10,
            "displayname": "llfile",
            "component_type": "DETAIL"
        },
        "libs.lldoc": {
            "status": "OK",
            "position": 20,
            "displayname": "lldoc",
            "component_type": "DETAIL"
        },
        "libs.pfring": {
            "component_type": "DETAIL"
            "displayname": "PF_RING Support",
            "position": 40,
            "status": "DISABLED",
        }
    },
    "integrations": {
        "component_type": "GROUP"
        "displayname": "Integrations",
        "position": 30,
        "integration.session_tracker": {
            "component_type": "DETAIL"
            "displayname": "Session Tracker Service",
            "position": 20,
            "status": "OK",
        },
        "integrations.notification-proxy_status": {
            "component_type": "DETAIL",
            "displayname": "Notification Delivery Service",
            "log": "Error: SIEM Server Status: Could not resolve
                    SIEM server address",
            "note": "Error in Logs",
            "position": 10
            "status": "ERROR",
        },
    },
    "system": {
        "component_type": "GROUP"
        "displayname": "System",
        "position": 10,
        "system.ipv4_address": {
            "status": "OK",
            "position": 100,
            "displayname": "Internal IPv4 address",
            "value": "192.168.133.101",
            "component_type": "DETAIL"
        }
    }
}

appliance_mgmt.configuration(response_format)¶

Return the current configuration of an appliance.

The configuration can be changed with action_request() using the CONFIGURE action_type.

URL

/papi/appliance_mgmt/configuration[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

appliance_uuid:

Unique identifier of an appliance

include_unknown_settings:

If true, Include settings that are not used/known by the software version the appliance is configured to. Defaults to false.

Contents of successful response

data:

Describes the current configuration of an appliance and possible default settings. The following fields are currently returned:

software_version:

The currently configured software version.

auto_update:

If the appliance has auto-update enabled or disabled.

settings:

Generic settings map. Maps setting names to values. Both are treated as opaque string values. The maximum size of a single value is currently 16K.

default_settings:

Generic settings map containing the default values instead of the currently set ones.

An example response is as follows:
"data": {
    "software_version": "4.7-testing1",
    "auto_update": true,
    "settings": {
        "setting1": "value1",
        "setting2": "",
        ...
    },
    "default_settings": {
        "setting1": "",
        "setting2": "default",
        ...
    }
}

Error Codes

LLAPI_APPLIANCE_MGMT_ERROR__NO_SUCH_APPLIANCE

appliance_mgmt.coordinates(response_format)¶

Set latitude and longitude information for a given appliance.

URL

/papi/appliance_mgmt/coordinates[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

appliance_uuid:

Unique identifier of an appliance

lat

The latitude value

lng

The longitude value

appliance_mgmt.action_request(response_format)¶

Request an appliance to perform an action.

URL

/papi/appliance_mgmt/action/request[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

appliance_uuid:

Unique identifier of appliance (required)

action_type:

Type of the action to execute.

action_parameters:

Encoded JSON map with action specific parameters.

Supported action types

REBOOT

Takes no action_parameters.
CONFIGURE
Supported entries in action_parameters are software_version, auto_update, settings. None of these are required. If settings is provided, it is required to be a dictionary. That is, action_parameters should be set to the encoded version of the following python dictionary:
action_parameters = {
    "software_version": "4.7-testing10",
    "settings": {
        "llmail_user": "john_doe"
    }
}
The supported entries in the settings dictionary are appliance type and version specific. However, never should any nested settings be used. Further, “true” and “false” will be converted into True and False.

A CONFIGURE action will update the configuration of an appliance if any of supported action parameters is provided. If no parameters are provided, the current configuration will be re-applied on the appliance.

The current configuration can be requested using configuration().

Contents of successful response

action_uuid:

The uuid of the action which can be used to query the status of this action using action_status().

Error Codes

LLAPI_APPLIANCE_MGMT_ERROR__NO_SUCH_APPLIANCE

LLAPI_APPLIANCE_MGMT_ERROR__UNKNOWN_ACTION_TYPE

LLAPI_APPLIANCE_MGMT_ERROR__NO_SUCH_VERSION

appliance_mgmt.action_status(response_format)¶

Return the status of an action.

This requires the CAN_VIEW_APPLIANCES permission.

URL

/papi/appliance_mgmt/action/status[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

action_uuid:

Unique action identifier, as returned by action_request().

timezone:

The timezone to convert timestamps to. Defaults to UTC.

Contents of successful response

status:

One of pending, error, success.

note

Short human readable note about the action status.

log

The full log output, potentially partial.

start_time

When the action was started.

end_time

When the action was last updated.

Error Codes

LLAPI_APPLIANCE_MGMT_ERROR__NO_SUCH_ACTION

appliance_mgmt.action_list(response_format)¶

Return a list of actions for a given appliance.

URL

/papi/appliance_mgmt/action/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

appliance_uuid:

Unique identifier of appliance (required)

status:

Only return actions that are in the specified state. (optional) One of pending, success or error.

timezone:

The timezone to convert timestamps to. Defaults to UTC.

Contents of successful response

List of actions for a given appliance in the following format:

[
    {
        "action_uuid": ...,
        "action_type": ...,
        "note": ...,
        "status": ...,
        "start_time": ...,
        "end_time": ...,
        "has_log": true|false,
    },
]

Error Codes¶

appliance_mgmt.LLAPI_APPLIANCE_MGMT_ERROR__NO_SUCH_APPLIANCE¶: Error Code 9001: No appliance with the given appliance_uuid exists.

appliance_mgmt.LLAPI_APPLIANCE_MGMT_ERROR__NO_SUCH_VERSION¶: Error Code 9002: The specified software version for this appliance type is unknown.

appliance_mgmt.LLAPI_APPLIANCE_MGMT_ERROR__NO_SUCH_ACTION¶: Error Code 9003: No action with the given action_uuid could be found.

appliance_mgmt.LLAPI_APPLIANCE_MGMT_ERROR__UNKNOWN_ACTION_TYPE¶: Error Code 9004: The requested action_type is not supported.

appliance_mgmt.LLAPI_APPLIANCE_MGMT_ERROR__EXISTING_ACTION¶: Error Code 9005: The provided action_uuid has been used previously.

Lastline Appliance Management API¶

Appliance Types¶

Response Format¶

Methods¶

Method Index¶

Method Documentation¶

Error Codes¶

Table Of Contents

Previous topic

Next topic