Lastline Accounting API

The Lastline Accounting API is accessible at:

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

Quick-Start

To test your Accounting API credentials, paste the following URL into a browser after replacing the credential parameters accordingly:

https://user.lastline.com/papi/accounting/account/get_account.xml?username=<username>&password=<password>

This will fetch information about the current user as shown below:

<result>
  <success>1</success>
  <data>
    <username>myaccount@company.com</username>
    <first_name>Test</first_name>
    <last_name>User</last_name>
    <customer>mycompany@company.com</customer>
  </data>
</result>

Permissions

The currently supported permissions are listed below.

All API methods in the permission view returning or requesting a permission will return or accept one of these types:

  • can_view_appliances: view information about appliances (i.e., view appliace overview, monitoring, configurations and notification configurations)
  • can_manage_appliances: perform actions to manage an appliance (i.e., request appliances to perform a configure or reboot action, configure notifications, manage appliance settings outside normal appliance config, e.g., active directory)
  • can_manage_users: administrator permission for a customer
  • can_access_alerts: access to alerts and statistics
  • can_access_pcaps: ability to access artifacts collected by sensors such as pcaps
  • can_manage_labels: ability to manage backend settings for sensors such as host labels, event annotations, incident workflow
  • can_access_analyzed_files: allows to download files of less sensitive types that were analyzed by Lastline. These are files such as executables and scripts that are less likely to include sensitive information.
  • can_access_sensitive_analyzed_files: allows to download files of more sensitive types that were analyzed by Lastline. These are files such as Office documents or PDFs, that are more likely to include sensitive information. This permission does not imply “can_access_analyzed_files”, so both permissions should be granted individually.

There are 3 different levels (i.e., context in which they make sense) for permissions: customer, license, subkey.

Permissions can be available at multiple levels The levels for the permissions above are:

  • can_view_appliances: customer
  • can_manage_appliances: customer
  • can_manage_users: customer (this is the administrator permission for the customer)
  • can_access_alerts: customer, license, subkey (i.e., access alerts that belong to a customer, a specific license, a specific sensor respectively)
  • can_access_pcaps: customer, license, subkey (i.e., access artifacts that belong to a customer, a specific license, a specific sensor respectively)
  • can_manage_labels: customer, license, subkey (i.e., manage labels that belong to a customer, a specific license, a specific sensor respectively)
  • can_access_analyzed_files: customer
  • can_access_sensitive_analyzed_files: customer

With this permission model it’s possible to give accounts access to specific resources only at the specified level.

Methods

Method Index

Methods for customers

Methods for accounts

Methods for licenses

Methods for appliances

Methods for permissions

Methods for roles

Methods for licensing bundles

Method Documentation

accounting.customer.get_customer(response_format)

Get customer details.

URL

/papi/accounting/customer/get_customer[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET/POST

GET/POST Parameters

  • customer:

    Customer primary contact (optional, default: current user).

Error Codes

Contents of successful response

  • customer:

    Customer primary contact (optional, default: currently authenticated customer).

  • username:

    Customer primary contact (deprecated)

  • first_name:

    Customer primary contact first name.

  • last_name:

    Customer primary contact last name.

  • phone:

    Customer phone.

  • affiliation:

    Customer affiliation.

  • address1:

    Customer address1.

  • address2:

    Customer address2.

  • city:

    Customer city.

  • state:

    Customer state.

  • zipcode:

    Customer zipcode.

  • country:

    Customer country.

accounting.customer.update_customer(response_format)

Update customer details.

URL

/papi/accounting/customer/update_customer[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • customer:

    Customer primary contact to be updated.

  • first_name:

    Customer primary contact first name to update to (optional).

  • last_name:

    Customer primary contact last name to update to (optional).

  • phone:

    Customer phone to set to (optional).

  • affiliation:

    Customer affiliation to update to (optional).

  • address1:

    Customer address1 to update to (optional).

  • address2:

    Customer address2 to update to (optional).

  • city:

    Customer city to update to (optional).

  • state:

    Customer state to update to (optional).

  • zipcode:

    Customer zipcode to update to (optional).

  • country:

    Customer country to update to (optional).

  • block_customer:

    Disable all licenses and accounts on this customer (requires additional permissions). Set to 1 to block, 0 to unblock, do not specify the parameter to keep it unchanged (optional).

Contents of successful response

  • “success”
accounting.customer.update_customer_info(response_format)

Update customer details.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.12 or above.

URL

/papi/accounting/customer/update_customer_info[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • first_name:

    Customer primary contact first name to update to (optional).

  • last_name:

    Customer primary contact last name to update to (optional).

  • phone:

    Customer phone to set to (optional).

  • affiliation:

    Customer affiliation to update to (optional).

  • address1:

    Customer address1 to update to (optional).

  • address2:

    Customer address2 to update to (optional).

  • city:

    Customer city to update to (optional).

  • state:

    Customer state to update to (optional).

  • zipcode:

    Customer zipcode to update to (optional).

  • country:

    Customer country to update to (optional).

Contents of successful response

  • “OK”
accounting.account.get_account(response_format)

Get account details.

URL

/papi/accounting/account/get_account[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET/POST

GET/POST Parameters

None.

Error Codes

None.

Contents of successful response

  • username:

    Account username.

  • email:

    Account email.

  • first_name:

    Account first name.

  • last_name:

    Account last name.

  • customer:

    Primary customer account this account is associated with.

  • **is_blocked*:

    Specifies if the account is blocked.

  • created_by:

    Account that created this account if available. ‘Lastline’ if the account was created by Lastline. ‘deleted account’ if the account was created by an account that has since

    been deleted.

    Available for Lastline Enterprise On-Premise versions >= 7.18

  • create_time:

    Time when this account was created if available. Available for Lastline Enterprise On-Premise versions >= 7.18

  • last_modified_by:

    Account that last modified this account if available. ‘Lastline’ if the account was last modified by Lastline. ‘deleted account’ if the account was last modified by an account

    that has since been deleted.

    Available for Lastline Enterprise On-Premise versions >= 7.18

  • last_modified_time:

    Time when this account was last modified if available. Available for Lastline Enterprise On-Premise versions >= 7.18

  • block_time:

    Time when this account was last blocked if available. Available for Lastline Enterprise On-Premise versions >= 7.18

  • default_locale:

    Default locale configured for this account.

  • default_timezone:

    Default timezone configured for this account.

accounting.account.get_accounts(response_format)

Get account(s) (and their details).

URL

/papi/accounting/account/get_accounts[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET/POST

GET/POST Parameters

  • customer:

    Filter accounts returned to this customer. Use ‘*’ to request all accounts (requires additional permissions). (optional, default: currently authenticated customer).

  • account_username:

    Filter accounts returned to this account key (optional).

  • username_substring:

    Filter accounts usign substring matching on their username (optional)

Error Codes

Contents of successful response

  • list of accounts:

    • username:

      Account username.

    • email:

      Account email.

    • first_name:

      Account first name.

    • last_name:

      Account last name.

    • customer:

      Primary customer account this account is associated with.

    • is_blocked:

      Specifies if the account is blocked.

    • created_by:

      Account that created this account if available. ‘Lastline’ if the account was created by Lastline. ‘deleted account’ if the account was created by an account that has since

      been deleted.

      Available for Lastline Enterprise On-Premise versions >= 7.18

    • create_time:

      Time when this account was created if available. Available for Lastline Enterprise On-Premise versions >= 7.18

    • last_modified_by:

      Account that last modified this account if available. ‘Lastline’ if the account was last modified by Lastline. ‘deleted account’ if the account was last modified by an account

      that has since been deleted.

      Available for Lastline Enterprise On-Premise versions >= 7.18

    • last_modified_time:

      Time when this account was last modified if available. Available for Lastline Enterprise On-Premise versions >= 7.18

    • block_time:

      Time when this account was last blocked if available. Available for Lastline Enterprise On-Premise versions >= 7.18

    • default_locale:

      Default locale configured for this account.

    • default_timezone:

      Default timezone configured for this account.

accounting.account.create_account(response_format)

Update account details.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.3 or above.

URL

/papi/accounting/account/create[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • account_username:

    Username of the account to create.

  • email:

    Email of the account to create.

  • first_name:

    First-name of the account to create (optional).

  • last_name:

    Last-name of the account to create (optional).

  • password:

    Password of the account to create. (optional).

  • customer:

    Primary customer account in which to create the account.

  • default_locale:

    Default locale to use for this account.

  • default_timezone:

    Default timezone to use for this account.

  • customer:

    Specify the customer in which to create the account (requires additional permissions). (optional, default: currently authenticated customer).

Error Codes

Contents of successful response

  • “success”
accounting.account.delete_account(response_format)

Delete an account.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.3 or above.

URL

/papi/accounting/account/delete[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • account_username:

    Username of the account to delete.

Error Codes

Contents of successful response

  • “success”
accounting.account.update_account(response_format)

Update account details.

URL

/papi/accounting/account/update[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • account_username:

    Account username to update (optional, default: authenticated user).

  • email:

    New value for the email (optional). If specified, the parameter password_verify must contain the password of the account used to authenticate.

  • first_name:

    New value for the first-name (optional).

  • last_name:

    New value for the last-name (optional).

  • default_locale:

    New value for the default locale.

  • default_timezone:

    New value for the default timezone.

  • new_password:

    New value for the password (optional). If specified, the parameter password_verify must contain the password of the account used to authenticate.

  • reset_password:

    If set to 1 and new_password not provided, randomly generate a new password (optional, default: 0). If specified, the parameter password_verify must contain the password of the account used to authenticate.

  • password_verify:

    Password of the authenticated account, for verification purposes. (optional, required if new_password or email is set). In the case of an on premise installation with a version prior to 7.3, this parameter is named “old_password”

  • password_expiration_timestamp:

    Set password expiration timestamp (optional).

  • customer:

    Specify the customer the account to update belong to (requires additional permissions). (optional, default: currently authenticated customer).

Error Codes

Contents of successful response

  • “success”
accounting.account.block_account(response_format)

Block an account.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.3 or above.

URL

/papi/accounting/account/block[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • account_username:

    Username of the account to block.

Error Codes

Contents of successful response

  • “success”
accounting.account.unblock_account(response_format)

Unblock an account.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.3 or above.

URL

/papi/accounting/account/unblock[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • account_username:

    Username of the account to unblock.

Error Codes

Contents of successful response

  • “success”
accounting.license.generate_license(response_format)

Generate a new hosted license.

NOTE: After generating a license, it can take up to 15 minutes for the new license to be propagated to all systems.

URL

/papi/accounting/license/generate_license[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • customer:

    Lastline customer (primary username) for which to generate the license (optional, default: current customer).

  • product:

    Lastline product for the license. This is the name of a product bundle as returned by /papi/accounting/product_bundle/list corresponding to hosted licenses, i.e., having installation_type ‘HOSTED’

  • license_type:

    The license’s type. Currently supported: commercial, non-commercial-institutional, non-commercial-personal, trial (optional, default: commercial).

  • start_date:

    The license’s start-date (optional, default=today).

  • end_date:

    The license’s end-date (optional, default=start_date+1 year).

  • num_licenses:

    The number of identical licenses to generate. If this value is higher than 1, products that require more than one license are not accepted (e.g., Lastline Enterprise On-Premise) (optional, default=1, minimum=1, maximum=1000).

Contents of successful response

  • customer:

    Customer to which the generated license was assigned.

  • licenses:

    Set of newly generated licenses.

    • access_key:

      License key of the generated license.

    • api_token:

      API secret token of the generated license.

    • product:

      Lastline product of the generated license.

    • type:

      Type of the generated license.

    • start_date:

      Start-date of the generated license.

    • end_date:

      End-date of the generated license.

accounting.license.get_licenses(response_format)

Get license(s) (and their details).

URL

/papi/accounting/license/get_licenses[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET/POST

GET/POST Parameters

  • customer:

    Filter licenses returned to this customer. Use ‘*’ to request all licenses (requires additional permissions). (optional, default: currently authenticated customer).

  • access_key:

    Filter licenses returned to this license key. If the value is of the form <key>:<sensor>, the filter will also apply to Sensor keys (optional).

  • on_premise_fqdn:

    Filter licenses returned to this on-premise FQDN. Conflicts with hosted (optional).

  • product:

    Filter licenses returned to this product (optional).

  • license_type:

    Filter licenses returned to this license-type (optional).

  • hosted_keys:

    (DEPRECATED, use hosted) If set to 1, filter licenses returned to only hosted licenses. Conflicts with on_premise_fqdn (optional).

  • hosted:

    If set to 1, filter licenses returned to only hosted licenses. If set to 0 filter only licenses regarding onpremises installation. Conflicts with on_premise_fqdn (optional).

  • invalid_keys:

    If set to 0, filter licenses returned to exclude invalid or expired keys (optional, default=1).

  • include_child_licenses:

    Whether child licenses should be included in the response (optional, defaults to False).

Error Codes

Contents of successful response

  • list of licenses:

    • customer:

      Customer primary contact that owns the license.

    • access_key:

      License key of the license.

    • parent_access_key:

      License key of the parent of this license. (Optional)

    • product:

      Lastline product for this license.

    • license_type:

      Type of the license.

    • start_date:

      Start-date of the license.

    • end_date:

      End-date of the license.

    • auto_extension:

      Indicates whether the license will extend itself automatically.

    • deployment:

      Deployment type of the license. One of hosted, on-premise, or on-premise (not initialized).

    • on_premise_fqdn (optional):

      FQDN of the on-premise installation (if deployment is on-premise).

    • limits (optional):

      List of license-specific limits on the license.

    • installation_key (optional):

      access_key of the main license of the on-premise installation the current license belongs to

    • license_group_uuid (optional):

      UUID of the license group this license is part of

    • key_valid:

      Boolean: is this license currently valid (not expired)?

accounting.license.get_keys(response_format)

Get keys (and their details).

These are both licenses (access keys) and sensor subkeys

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.1 or above.

URL

/papi/accounting/license/get_keys[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • customer:

    Filter keys returned to this customer. (optional, default: currently authenticated customer). Use “*” to disable filtering by customer.

  • key:

    Filter keys returned to this key. If the value is of the form <key>:<subkey>, the filter will also apply to Sensor subkeys (optional).

  • key_id:

    Filter keys returned by this license key identifier. Provide in alternative to key

  • subkey_id:

    Filter keys returned by this subkey identifier. Provide together with key_id in alternative to key.

  • license_type:

    Filter licenses returned to this license-type (optional).

  • invalid_keys:

    If set to 0, filter licenses returned to exclude invalid or expired keys (optional, default=0).

  • hosted:

    If set to 1, filter sensors returned to only hosted ones. If set to 0, filter sensors returned to only on-premise ones (optional, default return both hosted and on-premise) This filter is ignored when making requests to an On-Premise installation.

  • products:

    Comma-separated list of license products to filter by

  • required_permission:

    Only return keys on which caller has this permission. Can be one of “access_alerts”, “access_pcaps”, “manage_labels”, “manage_licenses”. (optional, default “access_alerts”)

  • include_child_licenses:

    Whether child licenses should be included in the response (optional, defaults to False).

Contents of successful response

  • list of sensors:

    • customer:

      Customer primary contact that owns the license.

    • key:

      Full license key. This is <ACCESS_KEY>:<SUBKEY>

    • access_key:

      License key

    • access_key_id:

      Access key/license idenfitier

    • license_type:

      Type of sensor licens

    • license_start_date:

      Start-date of the license.

    • license_end_date:

      End-date of the license.

    • hosted:

      Boolean: is this a hosted or on-premise sensor

    • key_valid:

      Boolean: is this sensor’s license currently valid (not expired)?

    • notes:

      Notes for license

    • location:

      location of license

    • is_installation_license:

      Boolean: Is this the main installation license of this on-premise installation? Will always be False when API request is to Lastline hosted backend.

    If license includes a subkey, additionally:

    • subkey:

      Sensor subkey

    • name:

      Name of sensor/subkey

    • subkey_id:

      Sensor subkey identifier

accounting.license.get_keys_legacy(response_format)

Get keys (and their details), or get sensor information (including checkin information)

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.1 or above.

DEPRECTATED

This method is provided to ease the transition between legacy ll_api method get_keys, and new methods in this module. It will eventually be removed.

Use get_keys for listing licenses (key+subkey), or get_sensors for listing sensors including checkin information such as when a sensor last reported in and from what IP address.

URL

/papi/accounting/license/get_keys_legacy[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • restrict_to_user_id:

    Boolean, if set only return keys for selected customer

  • restrict_to_access_key_id:

    Boolean, if set only return key under selected license

  • restrict_to_subkey_id:

    Boolean, if set only return selected sensor key

  • key:

    <key>[:<subkey>]: for selecting customer, key or subkey to filter on (depending on the values of the “restrict” options) (optional)

  • key_id:

    Identifier for selecting keys to filter on. Provide in alternative to key

  • subkey_id:

    Identifier for selecting sensor to filter on. Provide together with key_id in alternative to key.

  • include_invalid_keys:

    If set, also include invalid or expired keys (optional, default=0).

  • hosted:

    If set to 1, filter sensors returned to only hosted ones. If set to 0, filter sensors returned to only on-premise ones (optional, default return both hosted and on-premise) This filter is ignored when making requests to an On-Premise installation.

  • required_permission:

    Only return keys on which caller has this permission. Can be one of “access_alerts”, “access_pcaps”, “manage_labels”, “manage_licenses”. (optional, default “access_alerts”)

  • products:

    Comma-separated list of license products to filter by

  • include_heartbeat_data:

    Boolean. If this is set, this method behaves more like get_sensors than get_keys, and returns additional information about sensor checkins. Implies restrict_to_user_id. (optional, default False)

  • include_child_licenses:

    Whether child licenses should be included in the response (optional, defaults to False).

Contents of successful response

  • list of sensors:

    • license_user:

      Customer primary contact that owns the license.

    • key:

      Full license key. This is <ACCESS_KEY>:<SUBKEY>

    • access_key:

      License key

    • access_key_id:

      Access key/license idenfitier

    • license_type:

      Type of sensor licens

    • license_start_date:

      Start-date of the license.

    • license_end_date:

      End-date of the license.

    • hosted:

      Boolean: is this a hosted or on-premise sensor

    • key_valid:

      Boolean: is this sensor’s license currently valid (not expired)?

    • notes:

      Notes for license

    • license_location:

      location of license

    • is_master:

      Boolean: True if this is just access_key, False if it includes sensor subkey.

    • is_installation_license:

      Boolean: Is this the main installation license of this on-premise installation? Will always be False when API request is to Lastline hosted backend.

    If license includes a subkey, additionally:

    • subkey:

      Sensor subkey

    • name:

      Name of sensor/subkey

    • subkey_id:

      Sensor subkey identifier

    If include_heartbeat_data is set, also:

    • last_heartbeat:

      Timestamp of last checkin

    • public_ip:

      Public IP address of sensor appliance

    • internal_ip:

      Private IP address of sensor appliance

    • tool_version

      Software version of sensor appliance

accounting.license.get_license_stats(response_format)

Get statistics about a license.

URL

/papi/accounting/license/get_license_stats[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET/POST

GET/POST Parameters

  • access_key:

    License to query.

  • start_date:

    Query date-range start (optional, default: end_date-7 days).

  • end_date:

    Query date-range end (optional, default: yesterday).

  • by_mime_type:

    If set to 1, query (file) submissions by type (optional, default: 0).

  • total_submissions:

    If set to 1, query the number of total submissions including submissions returning cached analysis results (optional, default: 0).

Error Codes

Contents of successful response

  • analysis:

    Statistics about analysis submissions (number of submissions per day, optionally additionally by mime-type).

accounting.license.update_license(response_format)

Update license details.

URL

/papi/accounting/license/update_license[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • access_key:

    (One of) the license(s) to update.

  • start_date:

    Update a licenses’ start date (optional, requires special permissions).

  • end_date:

    Update a license’s end-date (optional, requires special permissions).

  • license_type:

    Update a license’s type - e.g., change from trial to commercial (optional, requires special permissions).

Contents of successful response

  • licenses:

    All license- and sensor-keys that have been updated. It is possible that a request updated multiple licenses (e.g., when an on-premise license is updated).

accounting.license.get_sensors(response_format)

Get sensors (and their details).

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.1 or above.

URL

/papi/accounting/license/get_sensors[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • customer:

    Filter sensors returned to this customer. (optional, default: currently authenticated customer).

  • key:

    Filter sensors returned to this license key. If the value is of the form <key>:<subkey>, the filter will also apply to Sensor subkeys (optional).

  • key_id:

    Filter sensors returned by this license key identifier. Provide in alternative to key

  • subkey_id:

    Filter sensors returned by this subkey identifier. Provide together with key_id in alternative to key.

  • license_type:

    Filter licenses returned to this license-type (optional).

  • invalid_keys:

    If set to 0, filter licenses returned to exclude invalid or expired keys (optional, default=0).

  • hosted:

    If set to 1, filter sensors returned to only hosted ones. If set to 0, filter sensors returned to only on-premise ones (optional, default return both hosted and on-premise) This filter is ignored when making requests to an On-Premise installation.

  • include_checkin_data:

    If set, include information on most recent appliance checkin (optional, default False)

Contents of successful response

  • list of sensors:

    • customer:

      Customer primary contact that owns the license.

    • key:

      Full license key. This is <ACCESS_KEY>:<SUBKEY>

    • access_key:

      License key

    • subkey:

      Sensor subkey

    • name:

      Name of sensor/subkey

    • access_key_id:

      Access key/license idenfitier

    • subkey_id:

      Sensor subkey identifier

    • license_type:

      Type of sensor licens

    • license_start_date:

      Start-date of the license.

    • license_end_date:

      End-date of the license.

    • hosted:

      Boolean: is this a hosted or on-premise sensor

    • key_valid:

      Boolean: is this sensor’s license currently valid (not expired)?

    If the include_checkin_data option is set, each sensor may include the following additional fields:

    • last_checkin:

      Timestamp of last checkin

    • public_ip:

      Public IP address of sensor appliance

    • internal_ip:

      Private IP address of sensor appliance

    • fqdn

      Fully qualified domain name of sensor appliance

    • appliance_version

      Software version of sensor appliance

    • appliance_uuid:

      UUID of sensor appliance

accounting.license.add_sensor(response_format)

Update sensor license information.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.12 or above.

URL

/papi/accounting/license/add_sensor[. response_format]

response_format can be XML or JSON (defaults to JSON)

HTTP METHOD

POST

POST Parameters

  • key:

    The license key string. The sensor will be added under this license.

  • key_id:

    The license key identifier. This is an alternative to the key parameter. The sensor will be added under this license.

  • new_subkey:

    String, set the new sensor subkey to this valaue.

  • name:

    String, if provided, sets the name of the sensor to this value.

  • active:

    Boolean, if provided enables/disables the sensor based on “True” or “False” values respectively. Defaults to “True”.

Contents of successful response

“OK”
accounting.license.update_sensor(response_format)

Update sensor license information.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.12 or above.

URL

/papi/accounting/license/update_sensor[. response_format]

response_format can be XML or JSON (defaults to JSON)

HTTP METHOD

POST

POST Parameters

  • key:

    The full license key <ACCESS_KEY>:<SUBKEY> used to identify a sensor. The sensor that matches this key will be updated.

  • key_id:

    The license key identifier. This is to be used in conjuction with the subkey_id as an alternative to a full key parameter. The sensor that matches the key_id + subkey_id will be updated.

  • subkey_id:

    The subkey identifier used in conjuction with the key_id as an alternative to a full key parameter. The sensor that matches the key_id + subkey_id will be updated.

  • name:

    String, if provided, update the name of the sensor to this value.

  • active:

    Boolean, if provided enables/disables the sensor based on “True” or “False” values respectively.

Contents of successful response

“OK”
accounting.license.update_sensor_legacy(response_format)

Update sensor license information or add a new sensor.

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.12 or above.

DEPRECATED

This method is provided to ease the transition between legacy ll_api update_sensor method and the new methods in this module. It will be eventually be removed.

Use add_sensor to create a new sensor key. Use update_sensor to update an existing sensor key.

URL

/papi/accounting/license/update_sensor_legacy[. response_format]

response_format can be XML or JSON (defaults to JSON)

HTTP METHOD

POST

POST Parameters

  • sensor_key:

    The sensor key string used to identify a sensor. If this sensor key exists, the method will update the specified sensor, otherwise it will create a new sensor with the given sensor_key.

  • new_subkey:

    The subkey string that will be used to identify the sensor.

  • sensor_name OR name:

    The name of the sensor.

  • license_end_date OR expiration_date:

    The date that specifies the expiration of the sensor. The parameter only has an affect at the moment of the call, that is, if the expiration date exceeds the current date, the sensor will be in an “active state”. On the other side, if the expiration is before the current date, the sensor will be in an “inactive state”.

Contents of successful response

“OK”
accounting.license.reset_api_token(response_format)

Reset the API token of a license.

On-premise customers need to perform this request on their appliance, not on the hosted backend, and can only reset the API token of secondary licenses (to reset the API token of the main license Lastline support must be contacted).

On Premise Availability

This method is available on Lastline Enterprise/Analyst On-Premise version 7.14 or above.

URL

/papi/accounting/license/reset_api_token[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • access_key:

    Key of the secondary license whose api token will be reset

Contents of successful response

Dictionary with the following fields:

  • api_token:

    Newly generated API token

accounting.appliance.deregister_appliance(response_format)

Deregister an appliance

URL

/papi/accounting/appliance/deregister[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • customer:

    Name of the customer whose appliance should be deregistered. If not provided, use the customer associated with the currently authenticated account.

  • appliance_uuid:

    UUID of the appliance to deregister.

Contents of successful response

“OK”
accounting.appliance.disable_appliance(response_format)

Disable an appliance

URL

/papi/accounting/appliance/disable[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • customer:

    Name of the customer whose appliance should be disabled. If not provided, use the customer associated with the currently authenticated account.

  • appliance_uuid:

    UUID of the appliance to disable.

Contents of successful response

“OK”
accounting.appliance.enable_appliance(response_format)

Enable an appliance.

URL

/papi/accounting/appliance/enable[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • customer:

    Name of the customer whose appliance should be enabled. If not provided, use the customer associated with the currently authenticated account.

  • appliance_uuid:

    UUID of the appliance to disable.

Contents of successful response

“OK”
accounting.appliance.get_registered_appliances(response_format)

Get the list of registered appliances.

URL

/papi/accounting/appliance/list_registered[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

Contents of successful response

A list of dictionaries, with the following keys

  • access_key:

    Access key used to register the appliance

  • subkey:

    Subkey used to register the appliance

  • appliance_uuid:

    The UUID of the registered appliance

  • registration_state:

    Current state of the appliance registration (either ‘REGISTERED’ or ‘DISABLED’)

  • registration_timestamp:

    Timestamp of the appliance registration

  • **registration_account:

    Account that performed the registration

  • appliance_type:

    Type of the appliance

accounting.permission.grant_permission(response_format)

Grant a single permission to an account

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/accounting/permission/grant[. response_format]

HTTP METHOD

POST

POST Parameters

  • account_username:

    Grant a permission to this account (Required)

  • permission:

    Name of the permission See list_permissions_information() for the list of available permissions

  • permission_context:

    Level of the permission to be granted (i.e., customer, license, subkey)

  • grant:

    Entity on which the permission will be granted. Depending on the permission_context it could be:

    • customer level:

      customer username

    • license level:

      access_key of the license

    • subkey level:

      full key (i.e., key:subkey) of the license

Error Codes

  • llapi.LLAPI_ERROR__PERMISSION_DENIED:

    When an account is not allowed to grant a permission

  • llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

    When, in case of license/subkey level permission, the access_key/subkey do not exist

Contents of successful response

  • “OK”
accounting.permission.revoke_permission(response_format)

Revoke an account’s permission

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/accounting/permission/revoke[. response_format]

HTTP METHOD

POST

POST Parameters

  • account_username:

    Revoke a permission from this account (Required)

  • permission:

    Name of the permission See list_permissions_information() for the list of available permissions

  • permission_context:

    Level of the permission to be revoked (i.e., customer, license, subkey)

  • revocation:

    Entity on which the permission will be revoked Depending on the permission_context it could be:

    • customer level:

      customer username

    • license level:

      access_key of the license

    • subkey level:

      full key (i.e., key:subkey) of the license

Error Codes - llapi.LLAPI_ERROR__PERMISSION_DENIED:

When an account is not allowed to revoke a permission
  • llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

    When the permission to be revoked does not exist

  • llapi.LLAPI_ERROR__INVALID_PARAMETER:

    When trying to revoke admin permission from a customer’s main account

Contents of successful response

  • “OK”
accounting.permission.list_permissions(response_format)

List all permissions of an account

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/accounting/permission/list[. response_format]

HTTP METHOD

GET

GET Parameters

  • account_username:

    List permissions for this account (optional, default: authenticated user)

  • consider_roles

    Whether to consider permissions indirectly granted by roles held by this account (optional, default: true)

Contents of successful response

Dictionary with the following fields:

  • customer_permissions:

    List of the customer permissions for this account, represented as dictionary with the following fields:

    • permission:

      Name of the permission

    • customer:

      Name of the customer this permission refers to

  • license_permissions:

    List of the license permissions for this account, represented as dictionary with the following fields:

    • permission:

      Name of the permission

    • access_key:

      License key this permission refers to

    • access_key_id:

      Identifier of the license key

  • subkey_permissions:

    List of the subkey permissions for this account, represented as dictionary with the following fields:

    • permission:

      Name of the permission

    • key:

      License key (access_key:subkey) this permission refers to

    • subkey_id:

      Identifier of the subkey

accounting.permission.list_permissions_information(response_format)

Display general information about all permission types

On-Premise availability

This API method is available for Lastline Enterprise On-Premise versions >= 7.5

URL

/papi/accounting/permission/info[. response_format]

HTTP METHOD

GET

Contents of successful response

A list of dictionaries with the following keys:

  • permission:

    Name of the permission type

  • display_name:

    User friendly name of a permission

  • description:

    Short description of the permission

  • contexts:

    The contexts in which this permission can be applied (i.e., customer, license or subkey.)

accounting.role.list_roles_information(response_format)

Display general information about a role or all available roles

On-Premises availability

This API method is available for Lastline On-Premises versions >= 8.4

URL

/papi/accounting/role/info[. response_format]

HTTP METHOD

GET

GET Parameters

  • role_name:

    Only return information about this role (optional)

  • builtin:

    Filter to roles that are (or are not) built-in (optional)

  • customer:

    List roles available to this customer (optional, default: authenticated customer)

Contents of successful response

A list of dictionaries with the following keys:

  • role_name:

    Name of the role

  • builtin:

    Whether this role is built-in

  • description:

    Short description of the role

  • contexts:

    The contexts in which this role can be applied (i.e., “customer”)

  • permissions:

    List of permissions granted by this role

accounting.role.grant_role(response_format)

Grant a role to an account

On-Premises availability

This API method is available for Lastline On-Premises versions >= 8.4

URL

/papi/accounting/role/grant[. response_format]

HTTP METHOD

POST

POST Parameters

  • account_username:

    Grant a role to this account (Required)

  • role:

    Name of the role to grant See :py:func:list_roles_information for the list of available roles

  • builtin:

    True if role_name refers to a built-in role, False if role_name refers to a custom role

  • role_context:

    Level of the role to be granted (must be “customer”)

  • grant:

    Entity on which the role will be granted. (optional) Depending on the role_context it could be:

    • customer level:

      customer username (must match custom role’s customer). If the grant parameter is not specified, this is the customer username of the account specified in the account_username parameter.

Error Codes

  • llapi.LLAPI_ERROR__PERMISSION_DENIED:

    When an account is not allowed to grant a role

  • llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

    When the specified account or role to be granted does not exist

Contents of successful response

  • “OK”
accounting.role.revoke_role(response_format)

Revoke an account’s role

On-Premises availability

This API method is available for Lastline On-Premises versions >= 8.4

URL

/papi/accounting/role/revoke[. response_format]

HTTP METHOD

POST

POST Parameters

  • account_username:

    Revoke a role from this account (Required)

  • role:

    Name of the role to revoke See :py:func:list_roles_information for the list of available roles

  • builtin:

    True if role_name refers to a built-in role, False if role_name refers to a custom role

  • role_context:

    Level of the role to be revoked (must be “customer”)

  • revocation:

    Entity on which the role will be revoked. (Optional) Depending on the role_context it could be:

    • customer level:

      customer username If the revocation parameter is not specified, this is the customer username of the account specified in the account_username parameter.

Error Codes - llapi.LLAPI_ERROR__PERMISSION_DENIED:

When an account is not allowed to revoke a role
  • llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

    When the role to be revoked does not exist

Contents of successful response

  • “OK”
accounting.role.list_roles(response_format)

List all roles held by an account

On-Premises availability

This API method is available for Lastline On-Premises versions >= 8.4

URL

/papi/accounting/role/list[. response_format]

HTTP METHOD

GET

GET Parameters

  • account_username:

    List roles for this account (optional, default: authenticated user)

Contents of successful response

Dictionary with the following fields:

  • customer_roles:

    List of the customer roles for this account, represented as a dictionary with the following fields:

    • role:

      Name of the role

    • builtin:

      Whether this role is built-in

    • customer:

      Name of the customer this role refers to

    • is_ephemeral:

      If the role was granted ephemerally

accounting.role.create_role(response_format)

Create a custom role.

On-Premises availability

This API method is available for Lastline On-Premises versions >= 8.4

URL

/papi/accounting/role/create[. response_format]

HTTP METHOD

POST

POST Parameters

  • name:

    Name of the role to create (up to 64 unicode characters).

  • description:

    A short description of the role (up to 128 unicode characters).

Error Codes

Contents of successful response

  • “success”
accounting.role.update_role(response_format)

Update a custom role’s details.

On-Premises availability

This API method is available for Lastline On-Premises versions >= 8.4

URL

/papi/accounting/role/update[. response_format]

HTTP METHOD

POST

POST Parameters

  • name:

    Name of the role to update.

  • new_name:

    New name for the role (optional; up to 64 unicode characters).

  • description:

    New description of the role (optional; up to 128 unicode characters).

  • context:

    Comma-separated list of contexts (i.e. “customer”) at which the role may be applied. (optional).

Error Codes

Contents of successful response

  • “success”
accounting.role.grant_role_permission(response_format)

Grant a permission to a custom role

On-Premises availability

This API method is available for Lastline On-Premises versions >= 8.4

URL

/papi/accounting/role/permission/grant[. response_format]

HTTP METHOD

POST

POST Parameters

  • role:

    Grant a permission to this role (required)

  • permission:

    Name of the permission to grant See list_permissions_information() for the list of available permissions

Error Codes

  • llapi.LLAPI_ERROR__PERMISSION_DENIED:

    When an account is not allowed to grant a permission

  • llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

    When the specified role does not exist

  • llapi.LLAPI_ERROR__INVALID_PARAMETER:

    When the specified permission to be granted does not exist

Contents of successful response

  • “OK”
accounting.role.revoke_role_permission(response_format)

Revoke a permission from a custom role

On-Premises availability

This API method is available for Lastline On-Premises versions >= 8.4

URL

/papi/accounting/role/permission/revoke[. response_format]

HTTP METHOD

POST

POST Parameters

  • role:

    Revoke a permission from this role (required)

  • permission:

    Name of the permission to revoke See list_permissions_information() for the list of available permissions

Error Codes

  • llapi.LLAPI_ERROR__PERMISSION_DENIED:

    When an account is not allowed to revoke a permission

  • llapi.LLAPI_ERROR__NO_SUCH_ENTITY:

    When the specified role does not exist

  • llapi.LLAPI_ERROR__INVALID_PARAMETER:

    When the specified permission to be revoked does not exist

Contents of successful response

  • “OK”
accounting.license_bundle.get_license_bundle(response_format)

Return a bundle containing licensing information of an onpremise installation.

This method can be used by customers with airgap deployment or manager appliances to sync license information.

URL

/papi/accounting/license_bundle/get

HTTP METHOD

GET

GET Parameters

  • access_key:

    Primary access key of the onpremise installation

  • bundle_format_version:

    Version of the bundle’s format to be returned (optional, defaults to 1). Different versions of the bundle will have differing content, at the moment:

    • version 1: no extra content
    • version 2: contains child licenses information

Contents of successful response

Compressed zip archive containing licensing information

HTTP Error codes

  • 403

    Returned when authentication was not successful

  • 422

    Returned when invalid or missing parameters are sent in the request

  • 501

    Returned when the requested operation is not supported

  • 503

    Returned when a temporary error in the signing of the bundle is encountered

accounting.license_bundle.get_airgap_installation_license_bundle(response_format)

Return a bundle containing licensing information of an onpremise installation for a new airgap installation.

This bundle is going to be used for a new airgap installation of an onpremise appliance and as a side-effect the license API-token is set to a new value, which is inserted in the bundle, and, in case of success, the onpremise installation is marked as installed. This method can only be invoked once per onpremise installation, to be able to re-use it for a new installation of the same appliance Lastline support must be contacted.

URL

/papi/accounting/license_bundle/airgap_installation

HTTP METHOD

POST

URL Parameters

  • access_key:

    Primary access key of the onpremise installation

  • bundle_format_version:

    Version of the bundle’s format to be returned (optional, defaults to 1). Different versions of the bundle will have differing content, at the moment:

    • version 1: no extra content
    • version 2: contains child licenses information

Contents of successful response

Compressed zip archive containing licensing information

HTTP Error codes

  • 403

    Returned when the right permissions are missing

  • 422

    Returned when invalid or missing parameters are sent in the request

  • 501

    Returned when the requested operation is not supported

  • 503

    Returned when a temporary error in the signing of the bundle is encountered

Error Codes

accounting.LLAPI_ACCOUNTING_ERROR__INVALID_CERTIFICATE_REQUEST

Error code 6001: Returned when requesting an certificate request is issued.

accounting.LLAPI_ACCOUNTING_ERROR__UNKNOWN_USER

Error code 6002: Returned when requesting data on an invalid customer.

accounting.LLAPI_ACCOUNTING_ERROR__UNKNOWN_ON_PREMISE

Error code 6003: Returned when requesting data on an invalid on-premise installation.

accounting.LLAPI_ACCOUNTING_ERROR__UNKNOWN_LICENSE_KEY

Error code 6004: Returned when requesting data on an invalid license.

accounting.LLAPI_ACCOUNTING_ERROR__UNKNOWN_ACCOUNT

Error code 6004: Returned when requesting data on an invalid account.

Notes on the appliance registration

An appliance can be in 3 different states:

  • registered: the appliance is associated with a license and operational
  • deregistered: the appliance is not associated with any license and not operational
  • disabled: the appliance is associated with a license but not operational

The following indicates how to switch an appliance between these various states:

  • To register an appliance, use the command line tool lastline_register

    The tool will ask you to select a license to associate with this appliance; once registered, the appliance will be operational

  • To put an appliance in the deregistered state, use the API “deregister_appliance”

    The license that was associated with the appliance will be considered as free and can be reused for another appliance

  • To put an appliance in the disable state, use the API “disable_appliance”

    The license is still associated with the appliance and then can not be reused, however, the appliance is not operational.

    To re-enable an appliance, use the API “enable_appliance”