Legacy API and methods

As part of the evolution of the Lastline API, certain parts of the API become legacy and are slowly phased out of the API. To keep the user informed, this section provides a reference schedule of the methods to be deprecated, as well as references to the legacy API.

Lastline API methods deprecation

The Lastline API is constantly improved and enriched with new functionalities. The introduction of new API methods can render certain existing methods obsolete, as these new methods offer better functionalities, better performances, or more flexible work flows. Once replacing methods are provided by the Lastline API and the continuity of the functionality is guaranteed, API methods made obsolete are scheduled for deprecation.

API methods scheduled for deprecation will eventually be discontinued completely. This section documents the deprecation schedule for these API methods, as well as provide information on how customers can replace calls to these API methods with calls to new API methods offering equivalent or substituting functionalities. API methods or combination of methods providing equivalent functionalities will be provided for most methods to be deprecated before they are discontinued.

Deprecation schedule

The tables below show the schedule for the deprecation of methods per module.

Method:Name of the API method in the module that is being deprecated.
Deprecated:These are the version numbers starting from which use of this legacy method is deprecated. The three columns provide version numbers for different Lastline products. H.: Lastline Enterprise and Analyst Hosted, E.: Lastline Enterprise On-premise and A.: Lastline Analyst On-premise. A version number preceded by >= indicates that deprecation of this method may happen in this version or any later version.
Discontinued:These are the version numbers in which this deprecated method has been removed, and is no longer be available. After this time, requests for these methods may return an unsupported function error or return an HTTP 40x status code. The three columns provide version numbers for different Lastline products. H.: Lastline Enterprise and Analyst Hosted, E.: Lastline Enterprise On-premises and A.: Lastline Analyst On-premises. A version number preceded by >= indicates that removal of this method may happen in this version or any later version.
Replacement:This is the API method, or combination of methods, of the current Lastline API that can be used in order to achieve equivalent or substituting functionality.

Additional methods of the modules will be added to these tables as they are added to our deprecation schedule. Furthermore, we will update the table with more specific version numbers for deprecation or removal once they become known.

Deprecation Schedule: Knowledgebase API,

Method Deprecated Discontinued Replacement
knowledgebase.getlist() 2018.3 8.1 8.1 >=2018.5 >=8.2 >=8.2 N.A.
knowledgebase.validateinput() 2018.3 8.1 8.1 >=2018.5 >=8.2 >=8.2 knowledgebase.parse_query()
knowledgebase.analyze() 2018.3 8.1 8.1 >=2018.5 >=8.2 >=8.2 knowledgebase.query_analytics()
knowledgebase.search() 2018.3 8.1 8.1 >=2018.5 >=8.2 >=8.2 knowledgebase.query_malscape_tasks()
knowledgebase.export_tasks_ips() 2018.3 8.1 8.1 >=2018.5 >=8.2 >=8.2 [a] knowledgebase.query_tasks_ips() and knowledgebase.export_blacklist_ips()
knowledgebase.export_tasks_domains() 2018.3 8.1 8.1 >=2018.5 >=8.2 >=8.2 [a] knowledgebase.query_tasks_domains() and knowledgebase.export_blacklist_domains()
/papi/blacklist/export 2020.2 N/A N/A 2020.2 [b] N/A N/A [b] intel.blacklist.get_threat_intel_feed()
[a](1, 2) export_tasks_ips and export_tasks_domains are currently used for both fetching the IPs/domains common to the queried tasks and export them. It is replaced by a two-stage process: querying the IPs/domains first, and then exporting the selected IPs/domains into the desired format so that the user can proceed with some selection between the two stages.
[b](1, 2) get_threat_intel_feed is a fully re-implemented drop-in replacement for the deprecated export method, that resolves performance problems in that API. The new API is also served transparently also from the legacy URL /papi/blacklist/export. The only limitation to backwards-compatibility is that the new API only supports JSON format, and no longer supports XML format.

Legacy API

In addition to the Lastline API, Lastline supports a legacy API that can be reached at:

On-premise customers can access the legacy API on their Manager or Analyst at:

https://user.<MANAGER HOST NAME>/ll_api/ll_api

This legacy API was deprecated in its entirety with the following releases:

  • Lastline Enterprise and Analyst hosted 7.24
  • Lastline Enterprise On-Premises 7.15
  • Lastline Analyst On-Premises 7.15

Support for this legacy API will eventually be dropped completely. This section documents the deprecation schedule for this API, as well as provide information on how customers can replace calls to the legacy API with calls to the new API.

Backwards-compatibility

Backwards-compatible methods will be provided in the new API for most legacy API functions before the legacy methods are dropped.

There are however some exceptions to this backwards-compatibility:

  • HTTP method support: methods in the new API that read data accept only requests using the HTTP GET verb, while methods that modify data accept only requests using the HTTP POST verb. The legacy API had laxer handling of HTTP verbs, and allowed POST requests for some read-only methods.
  • Sorting by multiple criteria is not supported, so an ‘orderby’ parameter such as “field1, field2” will be rejected as invalid.
  • Missing or empty values: The new API’s handling of missing or empty values may not be identical to the legacy API’s. Empty string, null and missing values may be used interchangeably, so client code should be robust to these possibilities.
  • Timezone selection: when no time zone setting is explicitly selected for an API call, the new API will always use the UTC time zone. The legacy API on the other hand defaulted to an accounts’ configured default timezone, and kept state of the selected time zone across requests. To ensure consistent behavior across the transition from legacy to new API, explicitly provide a timezone parameter to all API calls.
  • Key selection: the legacy API kept state of the currently selected license key. Therefore, certain API calls that operate on a license could be called without explicitly specifying one, so long as a license had been selected with a previous API call. The new API does not support this behavior. To ensure consistent behavior across the transition from legacy to new API, explicitly provide a key or key_id parameter to all API calls that operate on a selected license or sensor.
  • Most API calls in the legacy API supported both authentication based on API key + API token, and authentication based on username and password. In the new API, most methods support only username + password authentication. To ensure a smooth transition between the legacy and new APIs, use user-based authentication for all calls to the legacy API where this is supported.

Individual methods that replace legacy API methods may also have some specific exceptions to backwards-compatibility. These additional exceptions will be noted in the individual methods’ documentation.

Deprecation schedule

The table below shows the schedule for the deprecation of methods of the legacy API.

Method:Name of method in the legacy API that is being deprecated. This is value of the func parameter of the request to /ll_api/ll_api.
Deprecated:These are the version numbers starting from which use of this legacy method is deprecated. The three columns provide version numbers for different Lastline products. H.: Lastline Enterprise and Analyst Hosted, E.: Lastline Enterprise On-premise and A.: Lastline Analyst On-premise. A version number preceded by >= indicates that deprecation of this method may happen in this version or any later version.
Discontinued:These are the version numbers in which this legacy method has been removed, and is no longer be available. After this time, requests for these methods may return an unsupported function error or return an HTTP 40x status code. The three columns provide version numbers for different Lastline products. H.: Lastline Enterprise and Analyst Hosted, E.: Lastline Enterprise On-premises and A.: Lastline Analyst On-premises. A version number preceded by >= indicates that removal of this method may happen in this version or any later version. When this column is empty, the function will be discontinued when the entire legacy API is discontinued.
Replacement:This is the API method of the current Lastline API that is backwards-compatible with the legacy method, and can be used as a drop-in replacement.

Additional methods of the legacy API will be added to this table as they are added to our deprecation schedule. Furthermore, we will update the table with more specific version numbers for deprecation or removal once they become known.

Method Deprecated Discontinued Replacement
query_file_downloads 6.6 6.3 N.A.     N.A. net.file_capture.get_downloads()
query_binaries 6.6 6.3 N.A.     N.A. net.file_capture.get_downloads()
binaries 6.6 6.3 N.A.     N.A. net.file_capture.get_downloads()
query_downloaded_files 6.6 6.3 N.A.     N.A. net.file_capture.get_unique_downloads()
query_download_stats 6.10 6.5 N.A.     N.A. net.file_capture.get_download_stats()
query_pcaps 6.7 6.4 N.A.     N.A. net.pcap.get_pcaps_info_legacy()
get_pcaps 6.7 6.4 N.A.     N.A. net.pcap.get_pcap()
query_network_status 6.6 6.3 N.A. 7.1 7.1 N.A. [1]
query_event_labels       7.9 7.5 N.A. [2] net.network_event.get_event_evidence() and net.network_event.get_event_attributes()
query_incident_labels       7.9 7.5 N.A. [2] net.incident.get_incident_evidence()
incident_label_description       7.9 7.5 N.A. [2] [3]
set_appliance_geoposition 6.6 6.3 6.2       appliance_mgmt.coordinates()
set_account_permission       7.11 7.6 7.6 [5] accounting.permission.grant_permission() and accounting.permission.revoke_permission()
query_account_permissions       7.11 7.6 7.6 [5] accounting.permission.list_permissions()
switch_to_key 6.6 6.3 N.A.     N.A. [6]
switch_to_timezone 6.6 6.3 N.A.     N.A. [7]
get_keys 7.1 7.1 7.1       accounting.license.get_keys_legacy()
query_mail_attachments 7.1 7.1 7.1     N.A. net.mail.get_mail_attachments()
query_attached_files 7.1 7.1 7.1     N.A. net.mail.get_unique_mail_attachments()
query_mail_attachment_stats 7.1 7.1 7.1     N.A. net.mail.get_mail_attachment_stats()
events 7.3 7.2 N.A.     N.A. net.network_event.get_events_legacy()
query_events 7.3 7.2 N.A.     N.A. net.network_event.get_events_legacy()
incidents 7.3 7.2 N.A.     N.A. net.incident.get_incidents_legacy()
query_incidents 7.3 7.2 N.A.     N.A. net.incident.get_incidents_legacy()
malware 7.3 7.2 N.A.     N.A. net.incident.get_malware()
query_malware 7.3 7.2 N.A.     N.A. net.incident.get_malware()
incident_sources 7.3 7.2 N.A.     N.A. net.incident.get_incident_sources_legacy()
query_incident_sources 7.3 7.2 N.A.     N.A. net.incident.get_incident_sources_legacy()
query_default_key 7.3 7.2 7.2 7.6 7.3 7.3 [8]
query_account_details 7.6 7.3 7.3 7.7 7.5 7.5 accounting.account.get_account()
query_accounts 7.6 7.3 7.3 7.7 7.5 7.5 accounting.account.get_accounts()
delete_account 7.6 7.3 7.3 7.7 7.5 7.5 accounting.account.delete_account()
update_account_details 7.6 7.3 7.3 7.7 7.5 7.5 [4] accounting.account.create_account() and accounting.account.update_account()
update_sensor_details 7.18 7.12 N.A.     N.A. accounting.license.update_sensor_legacy()
add_submission_to_history 7.7 7.5 7.5       analysis.add_submission_to_history_legacy()
list_threat_classes 7.16 7.10 N.A.     N.A. intel.intel_metadata.list_threat_classes()
list_threats 7.16 7.10 N.A.     N.A. intel.intel_metadata.list_threats()
query_entry_info 7.16 7.10 N.A.     N.A. intel.intel_metadata.get_entry_info()
update_license_details 7.18 7.12 7.12       accounting.customer.update_customer_info()
query_license_details 7.18 7.12 7.12       accounting.customer.get_customer()
query_stats_notifications 7.21 7.14 N.A.     N.A. report.report.get_report_configs()
add_stats_notification 7.21 7.14 N.A.     N.A. report.report.add_reporting_config()
update_stats_notification 7.21 7.14 N.A.     N.A. report.report.update_report_config()
delete_stats_notification 7.21 7.14 N.A.     N.A. report.report.delete_report()
add_host_label 7.24 7.15 N.A.     N.A. net.settings.host_label.add_host_label_legacy()
delete_host_label 7.24 7.15 N.A.     N.A. net.settings.host_label.delete_host_label()
query_host_labels 7.24 7.15 N.A.     N.A. net.settings.host_label.get_host_labels()
set_incident_read_status 7.24 7.15 N.A.     N.A. net.incident.set_incident_read_status()
set_incident_archived_status 7.24 7.15 N.A.     N.A. net.incident.set_incident_archived_status()
set_source_cleaned_status 7.24 7.15 N.A.     N.A. net.incident.set_source_cleaned_status()
set_source_threat_ignored_status 7.24 7.15 N.A.     N.A. net.incident.set_source_threat_ignored_status()
[1]query_network_status: there is no backwards-compatible replacement for this method. However, information about the network traffic monitored by a Lastline Sensor can be obtained from the monitoring.get_metric() method. Specifically, packets and bytes processed are provided by the counter.llsnifflogmon.traffic.packets.total and counter.llsnifflogmon.traffic.bytes.total metrics respectively.
[2](1, 2, 3) query_event_labels, query_incident_labels, incident_label_description: there is no backwards-compatible replacement for these methods. These methods will be replaced by similar methods for requesting evidence for a detection.
[3]incident_label_description: also applies to it’s synonym query_incident_label_description.
[4]update_account_details is currently used for both creating new accounts and updating existing ones. It will be replaced with 2 methods for performing these two separate tasks. Therefore, this replacements is not fully backwards-compatible.
[5](1, 2) set_account_permission, query_account_permissions: these methods will be replaced with new permissions methods that will allow us to offer more fine-grained control of permissions for accounts. The replacements are not backwards-compatible.
[6]switch_to_key: This method will be discontinued without a replacement. The new API does not keep state for the selected key, so such a method would be meaningless. To ensure consistent behavior across the transition from legacy to new API, explicitly provide a key or key_id parameter to all API calls that operate on a selected license or sensor.
[7]switch_to_timezone: This method will be discontinued without a replacement. The new API does not keep state for the selected timezone, so such a method would be meaningless. To ensure consistent behavior across the transition from legacy to new API, explicitly provide a timezone parameter to all API calls.
[8]query_default_key: This method will be discontinued without a replacement. The new API does not have a concept of default license. Clients can list available licenses with methods such as accounting.license.get_keys() and then select one of the returned keys as default.