Lastline Annotation API

The Lastline Annotation API is accessible at:

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

The Lastline Annotation API is a web-based API for commenting on events, incidents, analysis reports and other entities.

Annotation

Method Index

  • get_annotation():

    Retrieves annotations based on an entity type and an entity id.

  • list_annotations():

    Retrieves multiple annotations that are all within an entity type. The list is constrained by a start time and an end time, that is, all annotations, bound by the times and within a certain entity type, will be returned.

  • add_annotation():

    Adds an annotation of a entity type and id.

  • edit_annotation():

    Edits an annotation based on an annotation uuid.

  • delete_annotation():

    Deletes an annotation based on an annotation uuid.

Method Documentation

annotation.get_annotation(response_format)

Returns all annotations that are associated with an entity type.

URL

/papi/annotation/get[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • entity_type:

    The entity type is specific to the annotation. That is, each entity types have their own annotations, this parameter helps seperate annotations by the types. This parameter is a string, such as ‘malscape’. (required)

  • entity_id:

    The id of the entity type. Each entity type may contain multiple entities (which have their own id). (required)

  • timezone:

    The timezone in which to convert the annotation(s) that are returned. The annotation times are stored as UTC and converted to the specified timezone. If the timezone parameter is not provided, than the the stored (UTC) time will be displayed. (optional)

  • key

    access_key[:subkey] for which annotations need additional sensor information. It is required for events and incidents entity types, otherwise it is optional.

Contents of successful response

List of annotations of a specified entity_type and entity_id parameter. Each element in the list holds:

  • annotation_uuid:

    Identifier of the annotation. Can be used to edit or delete annotations, edit_annotation() and delete_annotation().

  • entity_type:

    The entity type is specific to the annotation.

  • entity_id:

    The id of the entity type. Each entity type may contain multiple entities (which have their own id).

  • entity_time:

    The time of the given entity. It is used to help speed up the search of some entities that may be partitioned by time.

  • author:

    The account name of the user who created the annotation.

  • create_time:

    The datetime in which the annotation was originally created.

  • last_modified:

    The datetime in which the annotation was modified most recently. Note: if the create_time and last_modified are the same, the annotation has not been modified.

  • title:

    The title of the annotation

  • body:

    The body of the annotation. This contains all of the text that describes the annotation.

  • tags:

    The tags that are associated with the annotation. These tags are a list of strings, where each element in the list contains the

  • tags:

    The tags that are associated with the annotation. These tags are a list of strings, where each element in the list contains a string that represents an individual tag, e.g: [“False Positive”, “Alert”]). An empty list represents no tags.

  • link:

    An http link that is associated with the annotation. An empty string represents no link.

annotation.list_annotations(response_format)

Returns all annotations that are associated with an entity type.

URL

/papi/annotation/list[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • entity_type:

    The entity type is specific to the annotation. That is, each entity types have their own annotations, this parameter helps seperate annotations by the types. This parameter is a string, such as ‘malscape’. (required)

  • start_time:

    Listing of annotations is restricted by time. This parameter indicates to look for all annotations from this time. (required)

  • end_time:

    In addition to a start time, the listing also is restricted by an end value for time. This specifies to look for all annotations with this time being the end limit. (required)

  • timezone:

    The timezone in which to convert the annotation(s) that are returned. The annotation times are stored as UTC and converted to the specified timezone. If the timezone parameter is not provided, than the the stored (UTC) time will be displayed. (optional)

  • key:

    access_key[:subkey] for which annotations need additional sensor information. If an access_key is specified, then all subkey ids, in which the user has “CAN_ACCESS_ALERTS” permissions, will be used. If no key is specified, then all subkey ids will be used (with the same permissions). (optional)

Contents of successful response

List of annotations of a specified entity_type parameter. Each element in the list holds:

  • annotation_uuid:

    Identifier of the annotation. Can be used to edit or delete annotations, edit_annotation() and delete_annotation().

  • entity_type:

    The entity type is specific to the annotation.

  • entity_id:

    The id of the entity type. Each entity type may contain multiple entities (which have their own id).

  • entity_time:

    The time of the given entity. It is used to help speed up the search of some entities that may be partitioned by time.

  • author:

    The account name of the user who created the annotation.

  • create_time:

    The datetime in which the annotation was originally created.

  • last_modified:

    The datetime in which the annotation was modified most recently. Note: if the create_time and last_modified are the same, the annotation has not been modified.

  • title:

    The title of the annotation

  • body:

    The body of the annotation. This contains all of the text that describes the annotation.

  • tags:

    The tags that are associated with the annotation. These tags are a list of strings, where each element in the list contains a string that represents an individual tag, e.g: [“False Positive”, “Alert”]. An empty list represents no tags.

  • link:

    An http link that is associated with the annotation. An empty string represents no link.

annotation.add_annotation(response_format)

Add a new annotation

URL

/papi/annotation/add[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • entity_type:

    The entity type is specific to the annotation. That is, each entity types have their own annotations, this parameter helps seperate annotations by the types. This parameter is a string, such as ‘malscape’. (required)

  • entity_id:

    The id of the entity type. Each entity type may contain multiple entities (which have their own id). (required)

  • entity_time:

    This parameter specifies the time of a given entity. It is used to help speed up the search of some entities. (required if event_type is ‘events’)

  • key:

    Some annotations are specific to sensors as well as entity types, such as events and incidents. When creating annotations that are involved with sensors, the key specifies the sensor. The key is a string of form key:subkey. (required if key_id and subkey_id are not passed)

  • key_id:

    The license identifier, can be provided in alternative to key. (required if key is not passed)

  • subkey_id:

    Sensor identifier, can be provided, together with key_id, in alternative to key. (required if key is not passed)

  • title:

    The title of the annotation being created. (required)

  • body:

    The body of the annotation. This contains all of the text that describes the annotation. (required)

  • tags:

    The tags that are associated with the annotation. These tags are a list of strings, where each element in the list contains a string that represents an individual tag, e.g: [“False Positive”, “Alert”]. (optional)

  • link:

    An http link that is associated with the annotation. (optional)

Contents of successful response
  • annotation_uuid:

    The uuid of the new annotation that was created.

annotation.edit_annotation(response_format)

Edit an existing annotation. The only fields that will be updated in an existing annotation are the fields that are passed along with an annotation_uuid parameter. A field that is not passed will NOT be modified.

URL

/papi/annotation/edit[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • annotation_uuid:

    Identifier of the annotation to edit, as returned by get_annotation() and list_annotations() (required)

  • title:

    The title of the annotation. (optional)

  • body:

    The body of the annotation. This contains all of the text that describes the annotation. (optional)

  • tags:

    The tags that are associated with the annotation. These tags are a list of strings, where each element in the list contains a string that represents an individual tag, e.g: [“False Positive”, “Alert”]) (optional)

  • link:

    An http link that is associated with the annotation. (optional)

Contents of successful response

“OK”
annotation.delete_annotation(response_format)

Deletes an existing annotation.

URL

/papi/annotation/delete[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

Contents of successful response

“OK”

Feedback

Method Index

Method Documentation

annotation.feedback.send(response_format)

Send some feedback

URL

/papi/feedback/send[. ‘response_format’]

‘response_format’ can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • url:

    The full url (including the parameters) to send feedback to Note that the url does not have any limitation on length, but might be truncated if it is too long (without raising an error)

  • category:

    The category of feedback; value can be any string and can be used to classify the feedback (e.g.: “bug”, “improvement”, “new feature”) (limited to 30 bytes)

  • feedback:

    The feedback itself (limited to 32768 bytes)

Contents of successful response
string “OK”