Lastline Knowledgebase API

The Lastline Knowledgebase API is accessible at:

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

Alerting

Alerting is a pro-active service provided by the LLKB knowledge base, allowing users to define rules matched at indexing time. Through this service, users can automatically be notified when new samples matching the desired rules are analyzed and indexed. Users can leverage this service to search for targeted attacks against their company, for example, when malware samples target their domain or executable client.

The Alerting service is accessible under the following locations:

https://user.lastline.com/papi/knowledgebase/alerting/

For rule management, methods are available at: https://user.lastline.com/papi/knowledgebase/alerting/matching_rule/<function>

To access rule matches, methods are available at: https://user.lastline.com/papi/knowledgebase/alerting/match/analysis_ioc/<function>

Matching rules

Matching rules are built on top of the LLKB knowledge base query language. Rules are similarly built on expressions, supporting the same set of operators and search keys.

The notable difference with the query language is the support of Regular Expression (RE) within values. Litteral values are still included within single quotes (‘). To integrate RE constructions to the searched value, the user simply has to include his value within slashes (/) as in the following example:

domain: /.*.mydomain.com/

Search Methods

Search Methods Index

The following methods are still available but scheduled for deprecation. For each of the method below, one of the methods above, or a combination of them, will provide an equivalent functionality. These legacy methods have different interfaces and require you to encode your queries using JSON. We recommend using the new methods above for their simplified interface, better performance and flexibility.

  • getlist():

    List available components to build queries to the LLKB knowledge base.

  • validateinput():

    Validate the format of queries to the LLKB knowledge base.

  • analyze():

    Query the LLKB knowledge base for analytical information around the queried artifacts (e.g. IOC, traffic destination).

  • search():

    Search the LLKB knowledge base for analysis reports matching the queried artifacts (e.g. IOC, traffic destination).

  • export_tasks_ips():

    Export blacklisted IPs belonging to analysis tasks that satisfy the given query string.

  • export_tasks_domains():

    Export blacklisted domains belonging to analysis tasks that satisfy the given query string.

Search Methods Documentation

knowledgebase.ping(response_format)

Ping this API.

Check if the module is properly installed and enabled.

URL

/papi/knowledgebase/ping[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

Contents of successful response

PONG
knowledgebase.parse_query(response_format)

Validate query string and rebuild list of terms included in the string.

URL

/papi/knowledgebase/parse_query[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • query_string:

    The query to validate as a string.

    See Search for the definition of our query language.

Error Codes

Contents of successful response

  • queried_terms:

    The queried terms contained in the query string as a list of dictionaries <term> for each term.

    Dictionary <term>:

    This dictionary contains the description of the atomic terms composing the query. It contains the following keys:

    • term: Type of term.
    • features: List of features composing the term.

    The length of the list depending on the arity of the term type.

To summarize:

{'queried_terms': [
    {'term': 'domain', 'features': ['www.google.com']},
    {'term': 'registry_keyvalue_written', 'features': ['HKLM\MYKEY', 'VALUE']}
]}
knowledgebase.query_examples(response_format)

Query for interesting query examples.

URL

/papi/knowledgebase/query_examples[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • limit:

    The maximum number of examples to return.

    Minimum value: 1, Maximum value: 10, Recommended value: 4

Error Codes

Contents of successful response

  • examples:

    The suggestions related to the terms from the query string as a list of dictionaries <example> for each result.

    Dictionary <example>:

    This dictionary contains the description of suggestions for the atomic terms composing the query. It contains the following keys:

    • title: Title describing the nature of the expected query results,
    • date: Date at which the example was written,
    • query: Query string to be submitted.

To summarize:

{'examples': [
    {"title": "'Blank Slate' Cerber Campaign",
     "date": "2017-03-31",
     "query": "domain: 'ibm-technoligi.top' or domain: 'polkiuj.top'"}
]}
knowledgebase.query_suggestions(response_format)

Query suggestions for the composing terms of a query string.

URL

/papi/knowledgebase/query_suggestions[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • query_string:

    The query to search as a string.

    See Search for the definition of our query language.

  • limit:

    The maximum number of suggestions to return per atomic term.

    Minimum value: 1, Maximum value: 10, Recommended value: 3

Error Codes

Contents of successful response

  • suggestions:

    The suggestions related to the terms from the query string as a list of dictionaries <suggestion> for each result.

    Dictionary <suggestion>:

    This dictionary contains the description of suggestions for the atomic terms composing the query. It contains the following keys:

    • term: Type of term,
    • original: List of features composing the original term,
    • suggested: List of suggested features in replacement.

    The length of the original and suggested lists depending on the arity of the term type.

To summarize:

{'suggestions': [
    {'term': 'domain',
     'original': ['www.google.com'],
     'suggested': ['www.gooogle.com'],
    {'term': 'registry_keyvalue',
     'original': ['HKLM\MYKEY', 'VALUE'],
     'suggested': ['HKLM\YOURKEY', 'VALUE']}
]}
knowledgebase.query_analytics(response_format)

Query analytic statistics aggregating the query results.

URL

/papi/knowledgebase/query_analytics[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • query_string:

    The query to search as a string.

    See Search for the definition of our query language.

  • limit:

    The maximum number of results to include in the analytics.

    Minimum value: 1, Maximum value: 10.000, Recommended value: 2.500 for faster results

  • clause_av_label:

    Filter results belonging to this AV label.

  • clause_file_type:

    Filter results belonging to this file type.

  • clause_market_vertical:

    Filter results belonging to this market vertical.

  • clause_severity:

    Filter results belonging to this severity.

Error Codes

Contents of successful response

  • analytics:

    The dictionary of analytical results indexed by the analysis axes:

    • overview:

      A list containing one entry ‘all’ pointing to a dictionary <entry_breakdown>.

    • severity:

      A list containing one entry per severity level, each entry represented as dictionary <analysis_breakdown>.

    • labels:

      A list containing one entry per threat label, each entry represented as dictionary <analysis_breakdown>.

    • types:

      A list containing one entry per file type, each entry represented as dictionary <analysis_breakdown>, enriched with a file_mime sub-key.

    • verticals:

      A list containing one key entry market vertical, each entry represented as dictionary <analysis_breakdown>.

    • clusters_codehashes:

      A list containing one entry per cluster label, each entry represented as dictionary <analysis_breakdown>.

    • clusters_dynamic:

      A list containing one entry per cluster label, each entry represented as dictionary <analysis_breakdown>.

    Dictionary <analysis_breakdown>:

    This dictionary contains the analysis breakdown for each entry. The structure always contains the following keys:

    • category: Category name.

    • total: Total number of analysis reports for that entry.

    • visibility: Breakdown of analysis reports per visibility scope:

      • public: publicly available,
      • user-only: disclosed to users that have submitted the analyzed artifact,
      • private: restricted access, only included in analytic aggregated results.
  • messages:

    A list of string information related to the query e.g. dropped terms, normalized terms, filtered terms

To summarize:

{'analytics': {
    'overview': [
        {'category': 'all',
         'total': n,
         'visibility': {'private': n, 'public': n}}
    ],
    'severity': [
        {'category': 'suspicious',
         'total': n,
         'visibility': {'private': n, 'public': n}}
    ],
    'labels': [
        {'category': 'Unclassified':
         'total': n,
         'visibility': {'private': n, 'public': n}},
        {'category': 'Undetected':
         'total': n,
         'visibility': {'private': n, 'public': n}},
        {'category': 'class.family':
         'total': n,
         'visibility': {'private': n, 'public': n}}}
    ],
    'types': [
        {'category': 'PeExeFile',
         'category_mime': 'application/x-dosexec',
         'total': n,
         'visibility': {'private': n, 'public': n}}
    ],
    'verticals': [
        {'category': 'Security Services & Products',
         'total': n,
         'visibility': {'private': n, 'public': n}}
    ],
    'clusters_codehashes': [
        {'category': c,
         'total': n,
         'visibility': {'private': n, 'public': n}}
    ],
    'clusters_dynamic': [
        {'category': c,
         'total': n,
         'visibility': {'private': n, 'public': n}}
    ],
 },
 'messages': [
     'Query terms have been normalized: C:\USERS\[USER]\APPDATA\TEST.EXE'
 ]}
knowledgebase.query_malscape_tasks(response_format)

Query examples of analysis tasks that satisfy the query.

URL

/papi/knowledgebase/query_malscape_tasks[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • query_string:

    The query to search as a string.

    See Search for the definition of our query language.

  • limit:

    The maximum number of malscape reports to include.

    Minimum value: 1, Maximum value: 100, Recommended value: 100

  • clause_av_label:

    Filter results belonging to this AV label.

  • clause_file_type:

    Filter results belonging to this file type.

  • clause_market_vertical:

    Filter results belonging to this market vertical.

  • clause_severity:

    Filter results belonging to this severity.

Error Codes

Contents of successful response

  • tasks:

    A list of dictionaries <analysis_report>.

    Dictionary <analysis_report>:

    This dictionary contains the analysis report metadata. The structure contains the following keys:

    • artifact: The artifact reference (SHA1 for file).

    • artifact_type: The type of artifact under analysis (file).

    • task_uuid: The analysis task UUID.

    • report_uuid: The specific report in the analysis task matching the query.

    • submission: The analysis task submission time.

    • analysis_env: The analysis report environment.

    • score: The analysis task score.

    • severity: The artifact severity (either malicious, suspicious, or benign).

    • visibility: The analyzed artifact visibility scope:

      • public: publicly available,
      • user-only: disclosed to users that have submitted the analyzed artifact,
      • private: restricted access, only included in analytic aggregated results.

    For the file artifacts, the following keys will be present:

    • subject_ids: The list of specific subjects in the report matching the query.

    • file_type: The analyzed file type.

    • file_mime: The analyzed file type as MIME type.

    • av_label: The analyzed artifact classification:

      • class.family - aggregated classification from AV companies results,
      • undetected - undetected by any AV companies,
      • unclassified - no AV information was available.

    • cluster_labels: The analyzed file clustering results with the following sub-keys:

      • code-hashes - static code clustering label,
      • dynamic - dynamic execution clustering label
  • messages:

    A list of string information related to the query e.g. dropped terms, normalized terms, filtered terms

To summarize:

{'tasks: [
    {'artifact': 'edbe17707d4da3f9210d97a06313ff6d2819d1e5',
     'artifact_type': 'file',
     'analysis_env': 'Microsoft Windows XP',
     'visibility': 'public',
     'task_uuid': 'c1a7ef8de5a7001006aa8f318baaa609',
     'report_uuid': '2fbffe68406f50553d8d5400f3e3ef9c:0b029314bd128c04l-zjt2zYJ_XNQt77ARpRSeD6OJ2YVyrvdK72REvmWdQ',
     'submission': '2016-10-13 14:54:42',
     'analysis_env': 'Microsoft Windows XP',
     'score': 100,
     'severity': 'malicious',
     'subject_ids': [44],
     'file_type': 'PeExeFile',
     'file_mime': 'application/x-dosexec',
     'av_label': 'virus.sality',
     'cluster_labels': {
         'code-hashes': u'c#_wxp_unknown_unknown_177612',
         'dynamic': u'dyn_wxp_unknown_unknown_264979'
     }
 ],
 'messages': [
     'Query terms have been normalized: C:\USERS\[USER]\APPDATA\TEST.EXE'
 ]}
knowledgebase.query_tasks_ips(response_format)

Query related IPs belonging to analysis tasks that satisfy the query.

URL

/papi/knowledgebase/query_tasks_ips[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • query_string:

    The query to search as a string.

    See Search for the definition of our query language.

  • limit:

    The maximum number of analysis tasks to include.

    Minimum value: 1, Maximum value: 100, Recommended value: 100

  • limit_list:

    If set, return the most frequent IPs up to the given limit. Otherwise, all IPs are returned.

  • serve_tags:

    If set to True, the list of IPs is enriched with information tags when available.

  • clause_av_label:

    Filter results belonging to this AV label.

  • clause_file_type:

    Filter results belonging to this file type.

  • clause_market_vertical:

    Filter results belonging to this market vertical.

  • clause_severity:

    Filter results belonging to this severity.

Error Codes

Contents of successful response

  • list_ips:

    A list of dictionaries <ip_entry>.

    Dictionary <ip_entry>:

    This dictionary contains the IP information. The structure contains the following keys:

    • ip: The IP address.
    • count: The number of ocurrences across reports.
    • total: The total number of reports inspected for IPs.

    The following field is only present when serve_tags is set to True.

    • tags: list of dictionaries with the following sub-keys:

      • type - type or source of the tag
      • fullname - textual description of the tag
      • severity - info, warning or alert

To summarize:

{'list_ips': [
    {'ip': '127.0.0.1', 'count': 5, 'total': 100},
    {'ip': '8.8.8.8', 'count': 4, 'total': 100,
     'tags': [
         {'type': 'blacklist', 'fullname': 'shared-hosting', 'severity': 'info'}
     ]}
]}
knowledgebase.query_tasks_domains(response_format)

Query related domains belonging to tasks that satisfy the query.

URL

/papi/knowledgebase/query_tasks_domains[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • query_string:

    The query to search as a string.

    See Search for the definition of our query language.

  • limit:

    The maximum number of analysis tasks to include.

    Minimum value: 1, Maximum value: 100, Recommended value: 100

  • limit_list:

    If set, return the most frequent domains up to the given limit. Otherwise, all domains are returned.

  • serve_tags:

    If set to True, the list of domains is enriched with information tags when available.

  • clause_av_label:

    Filter results belonging to this AV label.

  • clause_file_type:

    Filter results belonging to this file type.

  • clause_market_vertical:

    Filter results belonging to this market vertical.

  • clause_severity:

    Filter results belonging to this severity.

Error Codes

Contents of successful response

  • list_domains:

    A list of dictionaries <domain_entry>.

    Dictionary <domain_entry>:

    This dictionary contains the domain information. The structure contains the following keys:

    • domain: The domain name.
    • count: The number of ocurrences across reports.
    • total: The total number of reports inspected for domains.

    The following field is only present when serve_tags is set to True.

    • tags: list of dictionaries with the following sub-keys:

      • type - type or source of the tag
      • fullname - textual description of the tag
      • severity - info, warning or alert

To summarize:

{'list_domains': [
    {'domain': 'www.lastline.com', 'count': 5, 'total': 100},
    {'domain': 'www.google.com', 'count': 4, 'total': 100,
     'tags': [
         {'type': 'popularity', 'fullname': 'popularity:1', 'severity': 'info'}
     ]}
]}
knowledgebase.query_tasks_activities(response_format)

Query common behavioral activities belonging to tasks that satisfy the query.

URL

/papi/knowledgebase/query_tasks_activities[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • query_string:

    The query to search as a string.

    See Search for the definition of our query language.

  • limit:

    The maximum number of analysis tasks to include.

    Minimum value: 1, Maximum value: 100, Recommended value: 100

  • limit_list:

    If set, return the most frequent activities up to the given limit. Otherwise, all activities are returned.

  • clause_av_label:

    Filter results belonging to this AV label.

  • clause_file_type:

    Filter results belonging to this file type.

  • clause_market_vertical:

    Filter results belonging to this market vertical.

  • clause_severity:

    Filter results belonging to this severity.

Error Codes

Contents of successful response

  • list_activities:

    A list of dictionaries <activity_entry>.

    Dictionary <activity_entry>:

    This dictionary contains the activity information. The structure contains the following keys:

    • activity: The activity description.
    • count: The number of ocurrences across reports.
    • total: The total number of reports inspected for activities.
    • severity: The severity score associated to the activity.
    • analysis_env: List of environments in which the activity was observed.

To summarize:

{'list_activities': [
    {'activity': 'Evasion: Unmaps and overwrites base address',
     'count': 2,
     'total': 5,
     'severity': 25,
     'analysis_env': ['Microsoft Windows XP', 'Microsoft Windows 7']}
]}
knowledgebase.export_blacklist_ips()

Export blacklist built from provided IPs.

URL

/papi/knowledgebase/export_blacklist_ips

HTTP METHOD

GET, POST

GET Parameters

  • entries:

    List of comma separated IP entries.

  • title:

    The title of the blacklist (e.g. TTP).

  • export_format (optional):

    Export format. Accepted values are ‘stix’, ‘plaintext’; defaults to ‘plaintext’ if not specified.

  • annotate (optional, default True):

    If set to True, the blacklist is enriched with information concerning the entries reputation.

Error Codes

  • HTTP error code 422:

    returned when sending a request with an invalid parameter.

  • HTTP error code 429:

    returned when the user or license has momentarily exceeded the allowed number of accesses.

Contents of successful response

This function serves the blacklist content as a file attachment.
knowledgebase.export_blacklist_domains()

Export blacklist built from provided domains.

URL

/papi/knowledgebase/export_blacklist_domains

HTTP METHOD

GET, POST

GET Parameters

  • entries:

    List of comma separated domain entries.

  • title:

    The title of the blacklist (e.g. TTP).

  • export_format (optional):

    Export format. Accepted values are ‘stix’, ‘plaintext’; defaults to ‘plaintext’ if not specified.

  • annotate (optional, default True):

    If set to True, the blacklist is enriched with information concerning the entries reputation.

Error Codes

  • HTTP error code 422:

    returned when sending a request with an invalid parameter.

  • HTTP error code 429:

    returned when the user or license has momentarily exceeded the allowed number of accesses.

Contents of successful response

This function serves the blacklist content as a file attachment.
knowledgebase.intel_analysis_pdns(response_format)

Query pDNS information collected during analysis for the given entries.

URL

/papi/knowledgebase/intel_analysis_pdns[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • term:

    The type of entries to be queried. Supported terms are:

    -domain

    -ip

  • entries:

    List of comma separated entries.

  • limit_results:

    If set, return for each entry the most recently seen results up to the given limit. Otherwise, all results are returned for each entry.

Error Codes

Contents of successful response

  • pdns:

    A list of dictionaries <pdns_entry>.

    Dictionary <pdns_entry>:

    This dictionary contains the pDNS information for each association between an entry and a DNS result. The structure contains the following keys:

    • entry: The domain or IP.
    • association: The DNS result (IP, domain, or NX).
    • types: Types of DNS relation associating the two e.g. A, PTR.
    • first_seen: First time this association was observed.
    • last_seen: Last time this association was observed.

To summarize:

{'pdns': [
    {'entry': 'www.google.com,
     'association': '74.125.28.99',
     'types': set(['A', 'Reverse PTR']),
     'first_seen': '2014-12-13 00:52:33',
     'last_seen': '2016-11-21 16:43:45'}
]}
knowledgebase.intel_analysis_timeline(response_format)

Query timeline information collected during analysis for the given entries.

URL

/papi/knowledgebase/intel_analysis_timeline[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • term:

    The type of entries to be queried. Supported terms are:

    -domain

    -ip

    -file_md5

    -file_sha1

    -file_sha256

    -threat

  • entries:

    List of comma separated entries.

  • max_data_points:

    If set, timelines are resampled to enforce a maximum number of data points per timeline. Otherwise, timelines are returned with hourly granularity.

Error Codes

Contents of successful response

  • timelines:

    A list of dictionaries <timeline_entry>.

    Dictionary <timeline_entry>:

    This dictionary contains the timeline information for each entry. The structure contains the following keys:

    • entry: The domain, IP or hash.
    • timeline: List of couples (timestamp, count).

To summarize:

{'timelines': [
    {'entry': 'www.google.com,
     'timeline': [
        [1476230400, 2],
        [1476316800, 94],
       [1476403200, 56],
       [1476489600, 16]
     ]}
]}
knowledgebase.intel_network_reputation(response_format)

Query network reputation information for the given entries.

URL

/papi/knowledgebase/intel_network_reputation[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • term:

    The type of entries to be queried. Supported terms are:

    -domain

    -ip

  • entries:

    List of comma separated entries.

  • serve_tags:

    If set to True, the reputation information is enriched with information tags representing the information in a synthetic way.

Error Codes

Contents of successful response

  • reputations:

    A list of dictionaries <reputation_entry>.

    Dictionary <reputation_entry>:

    This dictionary contains the reputation information for each entry. The structure contains the following keys:

    • entry: The domain or IP.

    • blacklist: Blacklist information as a list of dictionaries.

      Each dictionary contains the following information:

      • threat: the threat name or clean.
      • compromised: if the threat denotes that the host is compromised.
      • first_seen: First time the threat association was observed or None.
      • last_seen: Last time the threat association was observed or None.
      • comment: an optional comment regarding this particular entry or None.
    • hosting (optional): Hosting description as a string.
      Examples:
      • ddns-hosting,
      • i2p-network,
      • tor-network,
      • localhost-tunnel
    • popularity (optional): Popularity information as a dictionary.

      The dictionary contains the following information:

      • current_rank: Current rank in top million domains, 1 being the most popular.
    • service (optional): Hosted service description as a string.
      Examples:

      -certificate-authority, -external-time -geolocate-ip -mail-host -network-traversal -public-ip -url-shortener

    The following field is only present when serve_tags is set to True.

    • tags: list of dictionaries with the following sub-keys:

      • type - type or source of the tag
      • fullname - textual description of the tag
      • severity - info, warning or alert

To summarize:

{'reputations': [
    {'entry': 'smtp.gmail.com',
     'alexa': {'average_rank_30_days': 106725, 'current_rank': 8439},
     'blacklist': [
         {'threat': 'Clean',
          'compromised': False,
          'first_seen': None,
          'last_seen': None,
          'comment': u'We have no evidence of malicious activity'}
     ],
     'service': u'mail-host'}
]}

Legacy Methods Documentation

knowledgebase.getlist(response_format)

List available components of the knowledgebase API.

URL

/papi/knowledgebase/getlist[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • listname:

    The accessed list of components:

    ‘complex_term_list’ - list of searchable keys.

Contents of successful response

  • elements:

    The retrieved list of components.

knowledgebase.validateinput(response_format)

Validate queries to the knowledgebase API.

URL

/papi/knowledgebase/validate[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • queryinput:

    The query to validate as a JSON string.

    See Search for the definition of our query language.

Error Codes

Contents of successful response

  • valid:

    True if the query is valid, otherwise an error is sent back.

knowledgebase.analyze(response_format)

Query the LLKB knowledge base for analytical information matching the query.

URL

/papi/knowledgebase/analyze[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • query:

    The query to match as a JSON string. The query must be encapsulated in a dictionary formatted as follows:

    {‘complex_query_string’: string <query>}

    string <query>

    See Search for the definition of our query language.

    To summarize:

    {'complex_query_string': "domain: 'test.com'"}
  • limit:

    The max number of results to include in the analysis.

    Maximum value: 10.000 - Recommended value: 2.500 for faster results.

Error Codes

Contents of successful response

  • analyses:

    The dictionary of analytical results indexed by the analysis axes:

    • overview:

      A dictionary containing one key ‘all’ pointing to a dictionary <analysis_breakdown>.

    • labels:

      A dictionary containing one key per threat label, each key pointing to a dictionary <analysis_breakdown>.

    • types:

      A dictionary containing one key per file type, each key pointing to a dictionary <analysis_breakdown> enriched with a file_mime sub-key.

    • verticals:

      A dictionary containing one key per market vertical, each key pointing to a dictionary <analysis_breakdown>.

    dictionary <analysis_breakdown>

    This dictionary contains the analysis breakdown for each entry. The structure always contains the following keys:

    • reports_total: Total number of analysis reports for that entry.

    • visibility: Breakdown of analysis reports per visibility scope:

      • public: publicly available,
      • user: disclosed to users that have submitted the analyzed artifact,
      • private: restricted access, only included in analytic aggregated results.

    To summarize:

    {'overview':
    {'all':
        {'reports_total': n,
        'visibility': {'private': n, 'public': n}}},
'labels':
    {'Unclassified':
        {'reports_total': n,
        'visibility': {'private': n, 'public': n}},
    'Undetected':
        {'reports_total': n,
        'visibility': {'private': n, 'public': n}},
    'class.family':
        {'reports_total': n,
        'visibility': {'private': n, 'public': n}}},
'types':
    {'PeExeFile':
        {'file_mime': u'application/x-dosexec',
        'reports_total': n,
        'visibility': {'private': n, 'public': n}}},
'verticals':
    {'Security Services & Products':
        {'reports_total': n,
        'visibility': {'private': n, 'public': n}}}}
  • messages:

    A list of string information related to the query.

  • opt_results:

    Dictionary of optional results indexed by result type. Optional results depend on the query searched keys.

    • pdns: (optional, reserved to ip and domain queries)

      Dictionary indexed by the searched values (IPs or domains). Each entry points to a second dictionary indexed by DNS result. Each result dictionary contains the following information:

      • types: Types of DNS relation associating the value with the result.
      • first_seen: First time the DNS association was observed in our analyses.
      • last_seen: Last time the DNS association was observed in our analyses.

      To summarize:

      {'pdns':
    {'eedroagranoarsa.biz':
        {'195.22.26.231':
            {'types': ['A'],
             'first_seen': '2015-06-25 20:56:37',
             'last_seen': '2015-09-25 22:07:57'},
        '195.22.26.252':
            {'types': ['A'],
             'first_seen': '2015-06-25 20:56:37',
             'last_seen': '2015-09-25 22:07:57'},
        'NX':
            {'types': ['A'],
             'first_seen': '2015-02-17 16:06:13',
             'last_seen': '2015-02-17 16:10:33'}}}}
knowledgebase.search(response_format)

Query the LLKB knowledge base for analysis reports matching the query.

URL

/papi/knowledgebase/search[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • query:

    The query to match as a JSON string. The query must be encapsulated in a dictionary formatted as follows:

    {‘complex_query_string’: string <query>}

    string <query>

    See Search for the definition of our query language.

    To summarize:

    {'complex_query_string': "domain: 'test.com'"}
  • limit:

    The max number of results to include in the analysis.

    Maximum value: 100.

  • clauses:

    Optional clauses to apply to the search. Clauses are built as a JSON dictionary where three different types of keys can be combined:

    • file_type: select results having the given file type.
    • av_label: select results having the given AV label.
    • market_vertical: select results observed in the given vertical.
    • severity: select results with the given severity (malicious, suspicious, or benign).

    The values for these keys can be taken from a previous call to analyze().

    To summarize:

    {'av_label': 'class.family', 'file_type': 'PeExeFile', 'severity': 'malicious'}

Error Codes

Contents of successful response

  • hits:

    A list of dictionaries <analysis_report>.

    dictionary <analysis_report>

    This dictionary contains the analysis report metadata. The structure contains the following keys:

    • file_sha1: The analyzed artifact SHA1 digest.

    • file_type: The analyzed artifact file type.

    • file_mime: The analyzed artifact file type as MIME type.

    • av_label: The analyzed artifact classification:

      • class.family - aggregated classification from AV companies results,
      • undetected - undetected by any AV companies,
      • unclassified - no AV information was available.

    • visibility: The analyzed artifact visibility scope:

      • public: publicly available,
      • user: disclosed to users that have submitted the analyzed artifact,
      • private: restricted access, only included in analytic aggregated results.

    • task_uuid: The analysis task UUID.

    • report_uuid: The specific report in the analysis task matching the query.

    • subject_ids: The specific subjects in the report matching the query.

    • submission: The analysis task submission time.

    • analysis_env: The analysis report environment.

    • score: The analysis task score.

    • severity: The artifact severity (either malicious, suspicious, or benign).

    To summarize:

    [{'file_sha1': 'b1183923b259f136b908420c0d206485db9c4e8d',
'file_type': 'PeExeFile',
'file_mime': 'application/x-dosexec',
'av_label': 'trojan.dyreza',
'visibility': 'public'
'task_uuid': 'ec51a9ddeea542ef8241553731e085f7',
'report_uuid': '...:...',
'subject_ids': [4, 5, 6, 7],
'submission': '2015-08-03 20:31:10',
'analysis_env': 'Microsoft Windows XP',
'score': 99,
'severity': 'malicious'},
{...}]
  • messages:

    A list of string information related to the query.

  • list_ips: (optional, only when data available)

    A list of IPs shared across returned reports, ordered by decreasing frequency.

  • list_domains: (optional, only when data available)

    A list of domains shared across returned reports, ordered by decreasing frequency.

  • suggestions: (optional, only when data available)

    A list of dictionaries <suggestion> for each atomic key:value pair of the complex query.

    dictionary <suggestion>

    This dictionary contains the suggestion to replace an atomic key:pair from the original query. The structure contains the following keys:

    • original: The original key value pair.
    • suggested: The suggested key:value pair.

    To summarize:

    [{'original': "domain: 'www.gogle.com'",
'suggested': "domain: 'tj.gogle.cn'"},
{'original': "domain: 'www.gogle.com'",
'suggested': "domain: 'u.gogle.cn'"},
{'original': "domain: 'www.gogle.com'",
'suggested': "domain: 'www.google.com'"}]}
knowledgebase.export_tasks_ips()

Export blacklisted IPs belonging to analysis tasks that satisfy the query.

URL

/papi/knowledgebase/export_tasks_ips

HTTP METHOD

GET

GET Parameters

  • query_string:

    The query to search as a string.

    See Search for the definition of our query language.

  • limit:

    The maximum number of analysis tasks to include.

    Minimum value: 1, Maximum value: 100, Recommended value: 100

  • limit_list:

    If set, return the most frequent activities up to the given limit. Otherwise, all activities are returned.

  • clause_av_label:

    Filter results belonging to this AV label.

  • clause_file_type:

    Filter results belonging to this file type.

  • clause_market_vertical:

    Filter results belonging to this market vertical.

  • clause_severity:

    Filter results belonging to this severity.

  • export_format (optional):

    Export format. Accepted values are ‘stix’, ‘plaintext’; defaults to ‘plaintext’ if not specified.

Error Codes

  • HTTP error code 204:

    returned when the export results are empty.

  • HTTP error code 422:

    returned when sending a request with an invalid parameter.

  • HTTP error code 429:

    returned when the user or license has momentarily exceeded the allowed number of accesses.

Contents of successful response

This function serves the blacklist content as a file attachment.
knowledgebase.export_tasks_domains()

Export blacklisted domains belonging to analysis tasks that satisfy the query.

URL

/papi/knowledgebase/export_tasks_domains

HTTP METHOD

GET

GET Parameters

  • query_string:

    The query to search as a string.

    See Search for the definition of our query language.

  • limit:

    The maximum number of analysis tasks to include.

    Minimum value: 1, Maximum value: 100, Recommended value: 100

  • limit_list:

    If set, return the most frequent activities up to the given limit. Otherwise, all activities are returned.

  • clause_av_label:

    Filter results belonging to this AV label.

  • clause_file_type:

    Filter results belonging to this file type.

  • clause_market_vertical:

    Filter results belonging to this market vertical.

  • clause_severity:

    Filter results belonging to this severity.

  • export_format (optional):

    Export format. Accepted values are ‘stix’, ‘plaintext’; defaults to ‘plaintext’ if not specified.

Error Codes

  • HTTP error code 204:

    returned when the export results are empty.

  • HTTP error code 422:

    returned when sending a request with an invalid parameter.

  • HTTP error code 429:

    returned when the user or license has momentarily exceeded the allowed number of accesses.

Contents of successful response

This function serves the blacklist content as a file attachment.

Alerting Methods

Alerting Methods Index

Alerting Methods Documentation

knowledgebase.alerting.ping(response_format)

Ping this API.

Check if the module is properly installed and enabled.

URL

/papi/knowledgebase/alerting/ping[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

Contents of successful response

PONG
knowledgebase.alerting.parse_rule(response_format)

Validate rule string and rebuild list of terms included in the string.

URL

/papi/knowledgebase/alerting/matching_rule/parse[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • rule:

    The rule to validate as a string

  • type:

    The type of the matching rule determining the rule format

    Supported types: analysis_ioc_match

Error Codes

Contents of successful response

  • rule_terms:

    The required terms contained in the rule as a list of dictionaries <term> for each term.

    Dictionary <term>:

    This dictionary contains the description of the atomic terms composing the rule.

    For analysis_ioc_match rules, this dictionary contains the following keys:

    • term: Type of term.
    • features: List of features (including regular expressions) composing the term.

    The length of the list depending on the arity of the term type.

To summarize type analysis_ioc_match:

{'queried_terms': [
    {'term': 'domain', 'features': ['www.google.*']},
    {'term': 'registry_keyvalue_written', 'features': ['HKLM\MYKEY', 'VALUE']}
]}
knowledgebase.alerting.list_matching_rules(response_format)

List all the matching rules of a given type.

URL

/papi/knowledgebase/alerting/matching_rule/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Filters:

  • type:

    The type of matching rules to return

    Supported types: analysis_ioc_match

  • enabled (optional):

    If set, filter by rule status. Otherwise, all rules are returned

  • installation_key (optional):

    If set to a special value “*”, return all rules If set to any other value, filter by the given installation_key If not set, return all hosted rules

Sorting and pagination:

  • orderby (optional):
    Sort results based on this parameter. Following values are allowed:

    last_modified [ASC|DESC] to sort by modification time

  • max_results (optional):

    Limit to this many results

  • offset_results (optional):

    Skip the first offset_results results

Error Codes

Contents of successful response

A dictionary containing the following field:

  • matching_rules:

    A list of mappings containing the following fields:

    • rule:

      The rule content

    • title:

      The title of the rule

    • type:

      The rule type

    • enabled:

      Whether the rule is enabled

    • uuid:

      The UUID identifying this rule

    • installation_key:

      The installation key of the rule if available, None otherwise

    • last_modified:

      Timestamp of last modification

For example:

{'matching_rules': [
    {'rule': 'domain: smtp.gmail.com',
     'title: 'This is a test rule',
     'type': 'analysis_ioc_match',
     'enabled': True,
     'uuid': 'deadbeeddeadbeefdeadbeefdeadbeef',
     'installation_key': None,
     'last_modified': '2016-01-01 14:12:03'},
    {'rule': 'domain: smtps.gmail.com',
     'title: 'This is a test rule',
     'type': 'analysis_ioc_match',
     'enabled': True,
     'uuid': 'deadbeeddeadbeefdeadbeefdeadbeee',
     'installation_key': None,
     'last_modified': '2016-01-01 14:12:03'}
]}
knowledgebase.alerting.get_matching_rule(response_format)

Get a matching rule definition and configuration.

URL

/papi/knowledgebase/alerting/matching_rule/get[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

  • uuid:

    The uuid of the rule to retrieve

Error Codes

Contents of successful response

A dictionary containing the following field:

  • matching_rule:

    A mapping with the following fields:

    • rule:

      The rule content

    • title:

      The title of the rule

    • type:

      The rule type

    • enabled:

      Whether the rule is enabled

    • uuid:

      The UUID identifying this rule

    • installation_key_id:

      The installation_key_id of the rule if available, None otherwise

    • last_modified:

      Timestamp of last modification

For example:

{'matching_rule': {
    'rule': 'domain: smtp.gmail.com',
    'title': 'This is a test rule',
    'type': 'kb_alerting_rule',
    'enabled': True,
    'uuid': 'deadbeeddeadbeefdeadbeefdeadbeef',
    'installation_key_id': None,
    'last_modified': '2016-01-01 14:12:03'}
}}
knowledgebase.alerting.add_matching_rule(response_format)

Add a matching rule.

URL

/papi/knowledgebase/alerting/matching_rule/add[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

POST Parameters

  • rule:

    The content of the rule

  • title:

    The title of the matching rule

  • type:

    The type of the matching rule

    Supported types: analysis_ioc_match

  • enabled (optional):

    Whether the rule should be enabled or not, defaults to True

  • installation_key (optional):

    The key of the installation referenced by this rule, defaults to None

Error Codes

Contents of successful response

A dictionary containing the following field:

  • uuid:

    The uuid of the rule once added to the storage

For example:

{'uuid': "deadbeefdeadbeefdeadbeefdeadbeef"}
knowledgebase.alerting.edit_matching_rule(response_format)

Edit a matching rule configuration.

The rule definition itself can not be updated using this method. Modifying the definition impacts historical matches leading to inconsistencies. If a rule is to be modified, we recommend disabling/deleting the existing rule and creating a new one that can be safely monitored.

URL

/papi/knowledgebase/alerting/matching_rule/edit[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

GET Parameters

  • uuid:

    The uuid of the rule to modify

  • title (optional):

    The title of the matching rule

  • enabled (optional):

    Whether the rule should be enabled or not

Error Codes

Contents of successful response

  • “ok”
knowledgebase.alerting.delete_matching_rule(response_format)

Delete a matching rule.

URL

/papi/knowledgebase/alerting/matching_rule/delete[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

POST

GET Parameters

  • uuid:

    The uuid of the rule to modify

Error Codes

Contents of successful response

  • “ok”
knowledgebase.alerting.list_analysis_ioc_matches(response_format)

List of analysis ioc matches of a given type.

URL

/papi/knowledgebase/alerting/match/analysis_ioc/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Selection:

  • start_time:

    Start of queried interval.

  • end_time:

    End of queried interval.

  • timezone (optional):

    Name of selected time zone. Defaults to ‘UTC’.

  • type:

    The type of match. Supported types: ‘FILE’.

Filters:

  • installation_key (optional):

    If set to a special value “*”, return all matches If set to any other value, filter by the given installation_key If not set, return all hosted matches

  • uuid (optional):

    If set, filter by match uuid. Otherwise, all matches are returned.

  • task_uuid (optional):

    If set, filter by analysis task uuid. Otherwise, all matches are returned.

  • rule_uuid (optional):

    If set, filter by matching rule uuid. Otherwise, all matches are returned.

  • min_score (optional):

    Set a minimum score for a match to be returned. Otherwise, all matches are returned.

  • max_score (optional):

    Set a maximum score for a match to be returned. Otherwise, all matches are returned.

Sorting and pagination:

  • orderby (optional):
    Sort results based on this parameter. Following values are allowed:

    insert_ts [ASC|DESC] to sort by insertion time

  • max_results (optional):

    Limit to this many results

  • offset_results (optional):

    Skip the first offset_results results

Error Codes

Contents of successful response

A dictionary containing the following field:

  • analysis_ioc_matches:

    A list of mappings containing the following fields:

    • uuid:

      The uuid of the match

    • rule_uuid:

      The uuid of the matching rule

    • rule_title:

      The title of the matching rule

    • task_uuid:

      The uuid of the task

    • score:

      The score

    • report_uuid:

      The uuid of this specific report

    • av_label:

      The AV label

    • submission_ts:

      The timestamp at which the task has been submitted

    • insert_ts:

      The timestamp at which the task has been matched

    • installation_key:

      The installation key of the match if available, None otherwise

    • match_type:
      The type of analysis_ioc_match. Possible values are:

      ‘FILE’ if the match is related to a file

    • instances:

      A list of dictionaries detailing the instances of the match if available, empty list otherwise. Each dictionary has the following keys:

      • expression_type: The type of expression of this match instance,

      • expression: The matching expression, i.e., the part of the matching rule

        responsible for the match, delimited by forward slashes ‘/’ if a regular expression or by single quotes “’” if an exact string,

      • instance: A single-quoted string representing what has been matched.

    • analysis_instance:

      The analysis instance to query to get information on the analysis task related to this rule match. Possible values are ‘analysis_hosted’ and ‘analysis_on_premise’

    If match_type is FILE:

    • md5:

      The MD5 hash of the matching file

    • sha1:

      The SHA1 hash of the matching file

    • file_category:

      High-level category of the matching file

    • file_type:

      Detailed description of the matching file

    • llfiletype:

      LLFile type of the matching file

    • file_size:

      The size of the matching file

For example:

{'analysis_ioc_matches': [
    {'uuid': '46356afe55fa3cea9cbe73ad442cad47',
     'rule_uuid': 'fa582c9e95da255e44f4c198d0daf3df',
     'rule_title' 'Test rule',
     'task_uuid': '12fe8f3f4abc5e0fffaf66f5064aee2d',
     'score': 90,
     'report_uuid': '558130e58532bf8bBT6CLDWLiaJrv_0ttIkeTmlBee9rWLMHrV82',
     'av_label': 'ransomware.locky',
     'submission_ts': '2016-01-01 14:12:03',
     'insert_ts': '2016-01-01 14:15:03',
     'installation_key': None,
     'match_type: 'FILE',
     'md5': '989b09ac0fb411e793ae92361f002671',
     'sha1': 'e716c96c7e86a3da7872be2835cf84173dc7c56b',
     'llfiletype': 'Pdf',
     'file_type': 'PDF document',
     'file_size': 14045,
     'instances': [
        {'expression_type': 'domain',
         'expression': "/www\.malicious.*/",
         'instance': "'www.malicious.com'"
        },
        {'expression_type': 'domain',
         'expression': "'www.malicious.com'",
         'instance': "'www.malicious.com'"
        }
     ]
   }
]}
knowledgebase.alerting.list_match_instances(response_format)

List match instances as evidences satisfying a single match.

URL

/papi/knowledgebase/alerting/match/instance/list[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET

GET Parameters

Selection:

  • start_time:

    Start of queried interval.

  • end_time:

    End of queried interval.

  • timezone (optional):

    Name of selected time zone. Defaults to ‘UTC’.

  • uuid:

    The uuid of the match.

Sorting and pagination:

  • max_results (optional):

    Limit to this many results

  • offset_results (optional):

    Skip the first offset_results results

Error Codes

Contents of successful response

A dictionary containing the following field:

  • match_instances:

    A list of mappings containing the following fields:

    • expression_type: The type of expression of this match instance,

    • expression: The matching expression, i.e., the part of the matching rule

      responsible for the match, delimited by forward slashes ‘/’ if a regular expression or by single quotes “’” if an exact string,

    • instance: A single-quoted string representing what has been matched.

For example:

{'match_instances': [
   {'expression_type': 'domain',
    'expression': "/www\.malicious.*/",
    'instance': "'www.malicious.com'"},
   {'expression_type': 'domain',
    'expression': "'www.malicious.com'",
    'instance': "'www.malicious.com'"}
]}