Defender API Specification

Defender API Specification

The Lumu Defender API is based on HTTP requests and JSON responses. This documentation provides you with the API endpoint requirements, sample JSON files, request parameters, and response messages.

The Lumu Defender API offers a framework to help you leverage the Lumu integration with various third-party solutions. To get started with the Lumu Defender API,  consult our documentation.

The Defender API is language agnostic and supports incoming and outgoing information. All API calls are encrypted using HTTPS (HTTP over SSL/TLS) and authenticated API key-based authentication.


Access and Authentication

The Defender API requires each client to use a unique and personal API key, referred to in our documentation as {company-key} . The company’s API key is found in the Defender menu of the Lumu Portal and is self-managed by company administrators.


The revocation process generates a new Defender API key. This action cannot be undone and will cause your existing API integrations to stop working. This option should be used in specific scenarios such as when your current key is compromised due to security policies, etc. To reactivate your integrations, update your configuration with the new key.

The ability to integrate Lumu with your security stack via Defender API is part of  Lumu Defender  . This tier allows the integration of Lumu’s real-time analysis into your security stack to mitigate and remediate compromise incidents quickly and precisely.

A limited version of Lumu Defender API may also be accessible by Lumu Insights customers for basic integrations. These resources are tagged as  [Available for Insights]  in this document.

You can access the API using various methods.
  1. Applications that allow you to make REST calls, like Insomnia and POSTMAN
  2. Any programming language or utility, like curl and python
  3. Any third-party application that you want to integrate with that supports REST methods, e.g. Fortinet, QRadar, Splunk, etc.

Postman Tutorial

Postman is a tool for exploring and testing APIs. Lumu provides a Postman collection, which is a group of API requests, contains a set of requests that provides you with Lumu Defender API endpoint requirements, request parameters, and response messages samples.

Resources overview

The following resources are accessible via the Lumu Defender API. These are core concepts of Lumu Portal that you should familiarize yourself with.

Resource
Description
administration
For retrieving users and labels’ data.
incidents
For subscribing, retrieving incident data, and managing their status.
adversarial-activity
For retrieving all adversarial activity found on your perimeters.
spambox
For retrieving the adversarial activity related to Lumu Email. This feature was formerly known as Spambox.

Syntax, pagination and date format

General Syntax

The public host of the Lumu API is: https://defender.lumu.io/

All API endpoints are relative to the base URL. For example, assuming the base URL of https://defender.lumu.io/api , the /spambox endpoint refers to https://defender.lumu.io/api/spambox

Pagination

You can determine the paging results via query string parameters. This feature is available to endpoints that return more results than can be returned in a single response.

Query Params
Data Type
Description
page
Integer (optional)
Page number of the result set (default: 1).
items
Integer (optional)
Limit the number of results per page (default: 50, max: 100)

Example of URI that includes paging parameters: https://defender.lumu.io/api/administration/labels?key={company-key}&items=20&page=3

Paginated queries deliver pagination info at the end of each query, for example:

  1.    "paginationInfo": {
        "total": 20, 
        "page": 2, 
        "items": 2, 
        "next": 3, 
        "prev": 1
    }

Note that "prev" or "next" may not be returned if there is no previous or next page; "total" may appear in some specific services, such as for the administration endpoint.

Date Format

The Defender API has adopted a date/time format to provide consistency and interoperability with third-party applications. Date and time information is always returned in Coordinated Universal Time (UTC). The date format follows standards published in RFC 3339 and ISO 8601: YYYY-MM-DDTHH:mm:ss:sssZ . For example, 2021-03-21T18:25:43.000Z , where the Z indicates that the time zone is UTC (GMT).

You can send queries to the Defender API using your time zone date and time. However, keep in mind that the Defender API will always convert the time zone in your query to UTC. The following are examples of formats currently accepted by the Defender API:

  1. "2021-02-23T10:15:30.00-05:00[Europe/Paris]"
"2021-02-23T16:15:30.234+01:00[America/Bogota]"
"2021-02-23T16:15:30.234+01:00"
"2021-12-23T16:15:30.235"
"2021-02-23T10:15:30"

All the dates and times provided in the examples below will be converted automatically by the Defender API to UTC format. Example: "2021-02-23T15:15:30.234Z"

Be aware that for any queries in which you include the parameters fromDate and ToDate , the dates accepted must have a maximum 31 calendar days interval between them and can not be older than 180 calendar days from the current date. In case you submit a query for a date range greater than 31 days or older than 180 days, you will receive a “ Bad Request - 400 ” error.

The following example will return error 400 as it includes a time range greater than a month:

  1. {
  "fromDate": "2021-02-09T15:15:30.228Z",
  "toDate": "2021-03-23T15:15:30.228Z"
}

Queries that include the parameter hours are limited to a maximum of 767 hours (30 days) before the current date/time. The following example represents a query that includes the parameter hours greater than the equivalent to one month, in this case, it will return a 400 error.

  1. { "hours": 768 }

Error Responses

Lumu API uses standard HTTP features and standard HTTP status codes to indicate errors.

HTTP Code
Description
200
OK  Everything worked as expected, and we provided the data.
400
Bad Request  Client-side error status. Verify malformed request syntax, invalid request message parameters, etc.
401
Unauthorized  The provided API key is not valid.
403
Forbidden  Your company does not have sufficient privileges to access the API resource.
500
Internal server error  Our application server encountered a problem, try again later and if the problem persist, please let us know.

Rate Limits

The default API call limit rates are 50 calls per minute and 10,000 calls per day.

For queries that provide listed results, you can determine the maximum number of items to be returned using the following query string parameter:

Query Params
Data Type
Description
max-items
Integer (optional)
The maximum number of items that will be returned (default: 10, max: 10240).

Example: https://defender.lumu.io/resources/administration/labels?key={company-key}&items=20&page=3&max-items=50

The examples of responses in this document are not comprehensive of all parameter configurations or operations. The examples of responses intend to show the basic information provided by the API call, the format, and how that information is structured and labeled. The actual response can include more parameters.

Working with Users and Labels

The /administration  endpoints contain information about labels and users of the company. Labels help identify and classify compromise distribution across your infrastructure.

Consult our documentation for getting started with Labels and Accounts.

Retrieve labels  [Available for Insights]

Get a paginated list of all the labels created for the company and its details such as id, name and business relevance. The items are sorted by the label id in ascending order.

  1. GET https://defender.lumu.io/api/administration/labels?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Example request:

  1. curl --location --request GET 'https://defender.lumu.io/api/administration/labels?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw ''

Example response (200 - Success):

  1. {
    "labels": [
        {
            "id": 1, 
            "name": "Sales", 
            "relevance": 3
        }, 
        {
            "id": 2, 
            "name": "Customers", 
            "relevance": 1
        }, 
    ],
   "paginationInfo": {
        "page": 2, 
        "items": 2, 
        "next": 3, 
        "prev": 1
    }
}
Additional response definitions
Parameter
Description
relevance
Business relevance. Companies define labels relevance according to their business reality for faster data-supported decisions. The possible values are 1 (low), 2 (medium) and 3 (high).

Retrieve a specific label  [Available for Insights]

Get details such as id, name and business relevance from a specific label.

  1. GET https://defender.lumu.io/api/administration/labels/{label-id}?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.

Example request:

  1. curl --location --request GET 'https://defender.lumu.io/api/administration/labels/1?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3' \ --data-raw ''

Example response (200 - Success):

  1. {
     "id": 1, 
     "name": "Sales", 
     "relevance": 3
}

Retrieve users  [Available for Insights]

Get a paginated list of all the users registered in the company and their details. The items are sorted by the user id in ascending order.

  1. GET https://defender.lumu.io/api/administration/users?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Example request:

  1. curl --location --request GET 'https://defender.lumu.io/api/administration/users?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items50' \ --data-raw ''

Example response (200 - Success):

  1. {
    "users": [
        {
            "id": 1, 
            "role": "admin", 
            "email": "john@company.com", 
            "name": "John Doe", 
            "time_zone": "Etc/UTC",
"deactivated": false
        }, 
        {
            "id": 2, 
            "role": "admin", 
            "email": "sara@company.com", 
            "name": "Sara Green", 
            "time_zone": "Etc/UTC",
"deactivated": true
        }
    ], 
    "paginationInfo": {
        "page": 2, 
        "items": 2, 
        "next": 3, 
        "prev": 1
    }
}
Additional response definitions
Parameter
Description
deactivated
User account status. The two possible values are false(user is active) and true(user is deactivated). A deactivated account  is unable to login into the Lumu Portal.

Retrieve a specific user  [Available for Insights]

Get specific user details such as id, name, and role.

  1. GET https://defender.lumu.io/api/administration/users/{user-id}?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.

Example request:

  1. curl --location --request GET 'https://defender.lumu.io/api/administration/users/2?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3' \ --data-raw '''
Example response (200 - Success):
  1. {
      "id": 2,
      "role": "admin", 
      "email": "sara@company.com", 
      "name": "Sara Green", 
      "time_zone": "Etc/UTC",
      "deactivated": false
}

Working with Incidents

The /incidents endpoints contain information about incidents of the company. Lumu groups all occurrences of contacts to malicious infrastructure by an adversary and presents them consolidated in the form of incidents.

For getting started with Incidents, consult our documentation.

General considerations

The set of incident status and incident types can vary, therefore, any implementation using endpoints that receive those as query data should consider variations. These are the current values for these parameters:

  • status:  "open", "muted", "closed" .
  • incident-types:  "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"

User identification considerations

To associate a specific user to POST API transactions (mark as read, mute, unmute and close), you should include the header  Lumu-User-Id  with the user id as a value.
Example:  Lumu-User-Id:2 . This parameter is optional and when not included, the action taken will not be associated to any user. For example, if we set in the query header the id 2, that corresponds to the user “Integration user”, the incident log will look like the following image.


Retrieve Incidents

Get a paginated list of incidents for the company. The items are listed by the most recent .

  1. POST https://defender.lumu.io/api/incidents/all?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
fromDate
date-time (optional)
Search start date. The default value is 7 days before the current date. Example: "2021-04-01T14:40:14.939Z"
toDate
date-time (optional)
Search end date. The default value is the current date. Example: "2021-04-07T14:40:14.939Z"
status
array (optional)
Incident status. If not specified, all objects are returned. Example: "open", "muted", "closed"
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 5

Example request:
  1. curl --location --request POST 'https://defender.lumu.io/api/incidents/all?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw '{ "fromDate": "2021-03-23T16:15:30.00-05:00[Europe/Paris]", "toDate": "2021-04-15T16:15:30.234+01:00[Europe/Paris]", "status": ["open"], "adversary-types": ["C2C"], "labels": [0, 815] }'

Example response (200 - Success):

  1. {
    "items": [
        {
            "id": "2a4862b0-97af-11eb-aa46-b5c18d44caca", 
            "timestamp": "2021-04-07T14:40:14.939Z", 
            "statusTimestamp": "2021-04-07T14:40:14.939Z", 
            "status": "open", 
            "contacts": 1, 
            "adversaries": [
                "example1.com"
            ], 
            "adversaryTypes": [
                "C2C"
            ], 
            "labelDistribution": {
                "17": 1
            }, 
            "totalEndpoints": 1, 
            "lastContact": "2021-04-04T14:37:02.228Z", 
            "unread": true
        }
    ],
    "paginationInfo": {
        "page": 1, 
        "items": 50,
    } 
}

Retrieve a specific Incident details  [Available for Insights]

Get details of a specific Incident. The response for this operation may include extra data ( DNSPacketExtraInfo for example) in its parameters which may vary according to the data collection source.

  1. GET https://defender.lumu.io/api/incidents/{incident-uuid}/details?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.

Example request:

  1.  --location --request GET 'https://defender.lumu.io/api/incidents/4d90fc30-a6de-11eb-8239-a117f0a9f6f5/details?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3' \ --data-raw ''

Example response (200 - Success):

  1. {
    "id": "4d90fc30-a6de-11eb-8239-a117f0a9f6f5",
    "timestamp": "2021-04-26T22:25:27.923Z",
    "isUnread": false,
    "contacts": 114,
    "adversaryId": "Malware family qakbot",
    "adversaries": [
        "malicious.net",
        "suspicious.biz",
        "example.com"
    ],
    "adversaryTypes": [
        "DGA"
    ],
    "description": "Malware family qakbot",
    "labelDistribution": {
        "144": 114
    },
    "totalEndpoints": 1,
    "lastContact": "2021-04-26T22:39:16.131Z",
    "actions": [
        {
            "datetime": "2021-04-27T15:13:56.939Z",
            "userId": 0,
            "action": "close",
            "comment": "Incident close from external API"
        },
        {
            "datetime": "2021-04-26T22:42:32.532Z",
            "userId": 1,
            "action": "read",
            "comment": ""
        }
    ],
    "status": "closed",
    "statusTimestamp": "2021-04-27T15:13:56.939Z",
    "firstContactDetails": {
        "uuid": "09e02310-de1b-11ec-b481-eb776e1a9b92",
        "datetime": "2022-05-28T00:13:45.281Z",
        "host": "111example.com",
        "types": [
            "Phishing"
        ],
        "details": [
            "Malware family Pony"
        ],
        "endpointIp": "255.111.22.000",
        "endpointName": "USER.USER-PC",
        "label": 346,
        "sourceType": "virtual_appliance",
        "sourceId": "55719C03-b31t-4d5e-8e1e-9f2b7d651c45",
        "sourceData": {
            "DNSPacketExtraInfo": {
                "question": {
                    "type": "A",
                    "name": "111example.com",
                    "class": "IN"
                },
                "responseCode": "NOERROR",
                "flags": {
                    "authoritative": false,
                    "recursion_available": true,
                    "truncated_response": false,
                    "checking_disabled": false,
                    "recursion_desired": true,
                    "authentic_data": false
                },
                "answers": [
                    {
                        "name": "111example.com",
                        "type": "A",
                        "class": "IN",
                        "ttl": 2549,
                        "data": "51.225.156.155"
                    }
                ],
                "opCode": "QUERY"
            }
        },
        "isPlayback": false
    },
    "lastContactDetails": {
        "uuid": "a53c04a0-de1b-11ec-8d45-eb776e3f5271",
        "datetime": "2022-05-28T00:18:05.930Z",
        "host": "111example.com",
        "types": [
            "Phishing"
        ],
        "details": [
            "Malware family Pony"
        ],
        "endpointIp": "119.129.000.11",
        "endpointName": "USER.USER-PC",
        "label": 346,
        "sourceType": "virtual_appliance",
        "sourceId": "55719C03-b31t-4d5e-8e1e-9f2b7d651c45",
        "sourceData": {
            "DNSPacketExtraInfo": {
                "question": {
                    "type": "A",
                    "name": "111example.com",
                    "class": "IN"
                },
                "responseCode": "NOERROR",
                "flags": {
                    "authoritative": false,
                    "recursion_available": true,
                    "truncated_response": false,
                    "checking_disabled": false,
                    "recursion_desired": true,
                    "authentic_data": false
                },
                "answers": [
                    {
                        "name": "111example.com",
                        "type": "A",
                        "class": "IN",
                        "ttl": 2549,
                        "data": "250.4.148.28"
                    }
                ],
                "opCode": "QUERY"
            }
        },
        "isPlayback": false
    }

Retrieve a specific Incident context

Get details of the context information from a specific Incident.

  1. GET https://defender.lumu.io/api/incidents/{incident-uuid}/context?key={company-key}&hash={hash-type}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
hash-type
Message-digest algorithm (Cryptographic Hash Function) you are requesting, can correspond to SHA256, SHA1 or MD5. If a hash type isn't requested, this will return a SHA256 hash by default. This parameter isn't case sensitive.

Example request:

  1. curl --location --request GET 'https://defender.lumu.io/api/incidents/4d90fc30-a6de-11eb-8239-a117f0a9f6f5/context?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&hash=sha1'

Example response (200 - Success):

  1. {
    "adversary_id": "domain-example.net",
    "currently_active": false, 
    "deactivated_on": "2021-09-04T14:32:23.325Z",    
    "mitre": {
      "details": [
        {
            "tactic": "discovery",
            "techniques": ["T1083", "T1069.002", "T1082"]
        }, 
        {
            "tactic": "initial-access",
            "techniques": ["T1189", "T1566.001"]
        }
      ],
      "matrix": "enterprise",
      "version": "9.0"      
    }, 
    "related_files": [
        "c7267981748605fd27af739ef32d4688dc1dc160",
        "0668db6c06fe1bf8726487cd346f5dea7a20caf7",
        "4adb5eeb53dae0a580f4ec55a9add1a0696f4e93",
        "c38e3a08046938c0d9017c5d09e460b3d0046563",
        "8ae2e0bbb7174320379d720ca35421d3d96843ff",
        "c5515101ec506e963cc6fd4d2fc488300c4b4053",
        "79d78a1de39c09977d7d2b8bb09d78cfd7621804",
        "981ea159a18d468aded419ddace8403efa53e1a6",
        "c08b0daa01a2a3f5ce42d1f4838ca5ecd0e6b64c",
        "c7ea27eb33916cc63243354bd6bee988f2a16d09",
        "46b37255f22cb75c5031153d1639794c4ea53da4",
        "e89a0a90d44b186c129a9dfac85b2a6cb5686c94",
        "253738ee1fdff2131cc9917088d277dae983859a",
        "b61ac17c70aed3ad70d768d92dd39771e3eb9c59"
    ],
    "threat_details": [
        "Sodinokibi Ransomware related"
    ], 
    "threat_triggers": ["http://domain-example.net/"],
    "playbooks": ["https://docs.lumu.io/portal/en/kb/articles/malware-incident-response-playbook"],
    "external_resources": [
        "https://www.virustotal.com/gui/domain/domain-example.net/relations",
        "https://urlhaus.abuse.ch/host/domain-example.net/",
        "https://www.appgate.com/blog/electric-company-ransomware-attack-calls-for-14-million-in-ransom", 
        "https://blog.talosintelligence.com/2019/04/sodinokibi-ransomware-exploits-weblogic.html"
    ],
    "timestamp": "2021-11-03T18:30:01.782Z"
}

Comment a specific incident  [Available for Insights]

Add a comment to a specific incident. This operation does not return a response. 
  1. POST https://defender.lumu.io/api/incidents/{incident-uuid}/comment?key={company-key}
Query Params
Description
keyYour company's unique API key available at the Lumu Portal.

Body parameters:
Name
Data type
Description
comment
string
Comment to be added to the incident. 

Example request:
  1. curl --location --request POST 'https://defender.lumu.io/api/incidents/eec41860-e69f-11ec-b7a5-9ded001a2220/comment?key=MbEoJwFYiPmMUDi8k1CaIIo3EDeFwWox' \
--header 'Content-Type: application/json' \
--data-raw '{
    "comment": "comment"
}'

Retrieve open incidents  [Available for Insights]

Get a paginated list of open incidents for the company. The items are listed by the most recent.

  1. POST https://defender.lumu.io/api/incidents/open?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 

Example request:
  1. curl --location --request POST 'https://defender.lumu.io/api/incidents/open?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw '{ "adversary-types": [], "labels": [] }'

Example response (200 - Success):

  1. {
    "items": [
        {
            "id": "d53f69d0-9948-11eb-9b30-bd475fa20b50",
            "timestamp": "2021-04-09T15:32:45.933Z",
            "statusTimestamp": "2021-04-13T15:15:57.591Z",
            "status": "open",
            "contacts": 4,
            "adversaries": [
                "malicious.com",
                "suspicious.com"
            ],
            "adversaryId": "Malware family Banjori",
            "adversaryTypes": [
                "DGA"
            ],
            "description": "Malware family Banjori",
            "labelDistribution": {
                "37": 2,
                "39": 1,
                "179": 1
            },
            "totalEndpoints": 3,
            "lastContact": "2021-04-08T15:25:02.228Z",
            "unread": false
        }
    ],
    "paginationInfo": {
        "page": 1,
        "items": 50
    }
}

Retrieve muted incidents  [Available for Insights]

Get a paginated list of muted incidents for the company. The items are listed by the most recent.

  1. POST https://defender.lumu.io/api/incidents/muted?key={company-key}
Query Params
Description
key
Your company unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 

Example request:
  1. curl --location --request POST 'https://defender.lumu.io/api/incidents/muted?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw '{ "adversary-types": [], "labels": [] }'

Example response (200 - Success):

  1. {
    "items": [
        {
            "id": "d53f69d0-9948-11eb-9b30-bd475fa2caca",
            "timestamp": "2021-04-09T15:32:45.933Z",
            "statusTimestamp": "2021-04-20T17:55:15.730Z",
            "status": "muted",
            "contacts": 4,
            "adversaries": [
                "malicious.top",
            ],
            "adversaryId": "Malware family Banjori",
            "adversaryTypes": [
                "DGA"
            ],
            "description": "Malware family Banjori",
            "labelDistribution": {
                "179": 1,
                "39": 1
            },
            "totalEndpoints": 3,
            "lastContact": "2021-04-08T15:25:02.228Z",
            "unread": false
        }
    ],
    "paginationInfo": {
        "page": 1,
        "items": 50
    }
}

Retrieve closed incidents

Get a paginated list of closed incidents for the company. The items are listed by the most recent.

  1. POST https://defender.lumu.io/api/incidents/closed?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 

Example request:
  1. curl --location --request POST 'https://defender.lumu.io/api/incidents/closed?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw '{ "adversary-types": [], "labels": [] }'

Example response (200 - Success):

  1. {
    "items": [
        {
            "id": "af16bc80-9c7d-11eb-93a2-5b93f424cf4d",
            "timestamp": "2021-04-13T17:28:38.728Z",
            "statusTimestamp": "2021-04-15T14:56:27.067Z",
            "status": "closed",
            "contacts": 1,
            "adversaries": [
                "example.com"
            ],
            "adversaryId": "example.com",
            "adversaryTypes": [
                "Phishing"
            ],
            "description": "Phishing domain",
            "labelDistribution": {
                "37": 1
            },
            "totalEndpoints": 1,
            "lastContact": "2021-04-12T15:25:02.228Z",
            "unread": false
        }
    ],
    "paginationInfo": {
        "page": 1,
        "items": 1,
        "next": 2
    }
}

Retrieve endpoints by incident  [Available for Insights]

Get a paginated summary of the endpoints affected by a specified incident.

  1. POST https://defender.lumu.io/api/incidents/{incident-uuid}/endpoints-contacts?key={company-key}&page=1&items=50
Query Params

Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name

Data Type

Description
endpointsarray (optional)
List of ID of contacting endpoints. If not specified, all objects are returned. Example: "182.168.100.29", “DESK-9867”
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 

Example request:
  1. curl --location --request POST 'https://defender.lumu.io/api/incidents/56a0fc30-a6de-85eb-8249-a117f0a9f8g3/endpoints-contacts?key=Xt78fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50 --data-raw '{ "endpoints": [], "labels": [] }'

Example response (200 - Success):

  1. {
    "items": [
        {
            "label": 179,
            "endpoint": "banrepnt",
            "total": 1,
            "first": "2021-04-08T15:25:02.228Z",
            "last": "2021-04-08T15:25:02.228Z"
        },
        {
            "label": 37,
            "endpoint": "192.23.65.61",
            "total": 2,
            "first": "2021-04-08T15:25:02.228Z",
            "last": "2021-04-08T15:25:02.228Z"
        },
        {
            "label": 39,
            "endpoint": "jbrow",
            "total": 1,
            "first": "2021-04-08T15:25:02.228Z",
            "last": "2021-04-08T15:25:02.228Z"
        }
    ],
    "paginationInfo": {
        "page": 1,
        "items": 50
    }
}

Mark incident as read  [Available for Insights]

This transaction does not require any additional body parameters.

  1. GET https://defender.lumu.io/api/incidents/{incident-uuid}/mark-as-read?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.

Example request:

  1. curl --location --request POST 'https://defender.lumu.io/api/incidents/d3f41000-af3f-11eb-84b5-75a575634188/mark-as-read?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3' \ --data-raw ''

Mute incident  [Available for Insights]

  1. POST https://defender.lumu.io/api/incidents/{incident-uuid}/mute?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.

Body parameters

Na me
Data Type
Description
comment
string (optional)
Comment to be added in the Incident log. Example: "Internal penetration tests"

Example request:
  1. curl --location --request POST 'https://defender.lumu.io/api/incidents/d3f41000-af3f-11eb-84b5-75a575634188/mute?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3' \ --data-raw '{ "comment": "" }'

Unmute incident  [Available for Insights]

  1. POST https://defender.lumu.io/api/incidents/{incident-uuid}/unmute?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.

Body parameters

Name
Data Type
Description
comment
string (optional)
Comment to be added in the Incident log. Example: "Internal penetration tests"

Example request:
  1. curl --location --request POST 'https://defender.lumu.io/api/incidents/d3f41000-af3f-11eb-84b5-75a575634188/unmute?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3' \ --data-raw '{ "comment": "" }'

Close incident  [Available for Insights]

  1. POST https://defender.lumu.io/api/incidents/{incident-uuid}/close?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.

Body parameters

Name
Data Type
Description
comment
string (optional)
Comment to be added in the Incident log. Example: "Internal penetration tests"

Example request:
  1. curl --location --request POST 'https://defender.lumu.io/api/incidents/d3f41000-af3f-11eb-84b5-75a575634188/close?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3' \ --data-raw '{ "comment": "" }'

Subscribe to Incidents (Websocket)

Lumu provides a streaming endpoint to subscribe to real-time updates on incident operations. Establishing a connection to the streaming API means making a very long-lived HTTP request, and parsing the response incrementally.

The following endpoint can be used to stream notifications to any client that implements WebSockets. 

wss://defender.lumu.io/api/incidents/subscribe?key={company-key}
The date format in the notifications received by a WebSocket client from the Defender API is in the UTC time zone and follows standards published in RFC 3339 and ISO 8601.

See the following examples of notification logs received by a WebSocket client from the Defender API:

New Incident

The stream notification log for a new incident detection will be similar to the following:

  1. {
    "NewIncidentCreated": {
        "companyId": "89068290-4388-4b4d-b638-b5y83a730a51",
        "incident": {
            "id": "3ccf3e50-a771-61eb-95ec-ab811662da34",
            "timestamp": "2021-04-27T15:57:15.829Z",
            "statusTimestamp": "2021-04-27T15:57:15.829Z",
            "status": "open",
            "contacts": 1,
            "adversaries": ["example.com"],
            "adversaryId": "example.com",
            "adversaryTypes": ["Phishing"],
            "description": "Phishing domain",
            "labelDistribution": {
                "37": 1
            },
            "totalEndpoints": 1,
            "lastContact": "2021-04-12T15:25:02.228Z",
            "unread": true
        },
        "openIncidentsStats": {
            "openIncidents": 2,
            "totalContacts": 4,
            "typeDistribution": {
                "Phishing": 2
            },
            "labelDistribution": {
                "179": 1,
                "37": 2
            },
            "totalEndpoints": 2
        }
    }
}

Incident Read

In the following log, we have an example of an incident that was marked as read:

  1. {
   "IncidentMarkedAsRead": {
         "companyId": "c5437753-03e1-4792-aec6-b72604f87668", 
         "incidentId": "be2a5ea0-989c-11eb-8093-c5b4c3cefe69"
   }
}

Incident Closed

In the following log, we have an example of an incident that was marked as closed:

  1.   {
    "IncidentClosed": {
        "companyId": "c5437753-03e1-4792-aec6-b72604f87668", 
        "incident": {
            "id": "17615ed0-97c9-11eb-b4f0-e13747f3cc1f", 
            "timestamp": "2021-04-07T17:45:50.141Z", 
            "statusTimestamp": "2021-04-07T17:47:07.906Z", 
            "status": "closed", 
            "contacts": 1, 
            "adversaries": [
                "fraud.it"
            ], 
            "adversaryId": "fraud.it", 
            "adversaryTypes": [
                "Phishing"
            ], 
            "labelDistribution": {
                "25": 1
            }, 
            "totalEndpoints": 1, 
            "lastContact": "2021-04-07T10:37:02.228Z", 
            "unread": false
        }, 
        "comment": "This case is now solved"
    }
}

Incident Muted

In the following log, we have an example of an incident that was marked as muted:

  1. {
    "IncidentMuted": {
        "companyId": "c5437753-03e1-4792-aec6-b72604f87668", 
        "incident": {
            "id": "547773a0-97c8-11eb-b4f0-e13747f3cc1f", 
            "timestamp": "2021-04-07T17:40:23.130Z", 
            "statusTimestamp": "2021-04-07T17:42:23.100Z", 
            "status": "muted", 
            "contacts": 1, 
            "adversaries": [
                "phishing.ru"
            ], 
            "adversaryId": "phishing.ru", 
            "adversaryTypes": [
                "Mining"
            ], 
            "labelDistribution": {
                "25": 1
            }, 
            "totalEndpoints": 1, 
            "lastContact": "2021-04-07T10:37:02.228Z", 
            "unread": false
        }, 
        "comment": "This was an internal test"
        "reason": "irrelevant"
    }
}

Incident Unmuted

In the following log, we have an example of an incident that was marked as unmuted:

  1. {
    "IncidentUnmuted": {
        "companyId": "c5437753-03e1-4792-aec6-b72604f87668", 
        "incident": {
            "id": "547773a0-97c8-11eb-b4f0-e13747f3cc1f", 
            "timestamp": "2021-04-07T17:40:23.130Z", 
            "statusTimestamp": "2021-04-07T17:44:50.861Z", 
            "status": "open", 
            "contacts": 3, 
            "adversaries": [
                "examlple.ru"
            ], 
            "adversaryId": "example.ru", 
            "adversaryTypes": [
                "Mining"
            ], 
            "labelDistribution": {
                "25": 3
            }, 
            "totalEndpoints": 1, 
            "lastContact": "2021-04-07T10:37:02.228Z", 
            "unread": false
        }, 
        "comment": "The incident is now relevant"
    }
}

Incident Updated

An incident is updated every time a new contact is detected with the adversary. In the following log, we have an example of an incident that was updated:

  1. {
    "IncidentUpdated": {
        "companyId": "89068290-4388-4b4d-b638-b9b93a730a51",
        "incident": {
            "id": "3ccf3e50-a771-11eb-95ec-ab811662da34",
            "timestamp": "2021-04-27T15:57:15.829Z",
            "statusTimestamp": "2021-04-27T15:57:15.829Z",
            "status": "open",
            "contacts": 2,
            "adversaries": ["example.com"],
            "adversaryId": "example.com",
            "adversaryTypes": ["Phishing"],
            "description": "Phishing domain",
            "labelDistribution": {
                "37": 2
            },
            "totalEndpoints": 1,
            "lastContact": "2021-04-12T15:25:02.228Z",
            "unread": true
        },
        "openIncidentsStats": {
            "openIncidents": 2,
            "totalContacts": 5,
            "typeDistribution": {
                "Phishing": 2
            },
            "labelDistribution": {
                "179": 1,
                "37": 2
            },
            "totalEndpoints": 2
        
    }
}

Consult incidents updates through REST

Lumu provides an endpoint to consult real-time updates on incident operations through REST when Websocket is not available.

The following can be used to consult the latest updates or the updates after provided offset
  1. curl --location --request GET 'https://defender.lumu.io/api/incidents/open-incidents/updates?=offset=0&items=50&time=30&key={company-key}'
The date format in the updates received from the endpoint is in the UTC time zone and follows standards published in RFC 3339 and ISO 8601
The endpoint will deliver the updates in the format described above.

Sample response:
  1. {
"updates": [
     {
         "IncidentClosed": {
             "companyId": "10228d9c-ff18-4251-ac19-514185e00f17",
             "incident": {
                 "id": "47fa7230-225a-11ed-9be2-739ab0337004",
                 "timestamp": "2022-08-22T20:37:46.835Z",
                 "statusTimestamp": "2022-08-23T19:58:50.887Z",
                 "status": "closed",
                 "contacts": 1,
                 "adversaries": [
                     "chinagrouptraders.xyz"
                 ],
                 "adversaryId": "chinagrouptraders.xyz",
                 "adversaryTypes": [
                     "C2C",
                     "Malware"
                 ],
                 "description": "Malware family Keybase",
                 "labelDistribution": {
                     "0": 1
                 },
                 "totalEndpoints": 1,
                 "lastContact": "2022-08-22T20:32:02.228Z",
                 "unread": false,
                 "hasPlaybackContacts": false,
                 "firstContact": "2022-08-22T20:32:02.228Z"
             },
             "comment": "test"
         }
     },
     {
         "OpenIncidentsStatusUpdated": {
             "companyId": "10228d9c-ff18-4251-ac19-514185e00f17",
             "openIncidentsStatus": {
                 "openIncidents": 575,
                 "totalContacts": 12617,
                 "typeDistribution": {
                     "DGA": 11,
                     "C2C": 117,
                     "Network Scan": 10,
                     "Mining": 139,
                     "Phishing": 53,
                     "Spam": 81,
                     "Malware": 281
                 },
                 "labelDistribution": {
                 },
                 "totalEndpoints": 115
             }
         }
     },
     {
         "IncidentUnmuted": {
             "companyId": "10228d9c-ff18-4251-ac19-514185e00f17",
             "incident": {
                 "id": "43511460-1fa7-11ed-bd66-d162eff789a8",
                 "timestamp": "2022-08-19T10:11:16.774Z",
                 "statusTimestamp": "2022-08-23T19:59:08.775Z",
                 "status": "open",
                 "contacts": 1,
                 "adversaries": [
                     "ethereum-pocket.com"
                 ],
                 "adversaryId": "ethereum-pocket.com",
                 "adversaryTypes": [
                     "Mining"
                 ],
                 "description": "CryptoMining domain",
                 "labelDistribution": {
                     "2148": 1
                 },
                 "totalEndpoints": 1,
                 "lastContact": "2022-08-16T20:23:23Z",
                 "unread": false,
                 "hasPlaybackContacts": false,
                 "firstContact": "2022-08-16T20:23:23Z"
             },
             "comment": "relevant"
         }
     },
     {
         "OpenIncidentsStatusUpdated": {
             "companyId": "10228d9c-ff18-4251-ac19-514185e00f17",
             "openIncidentsStatus": {
                 "openIncidents": 576,
                 "totalContacts": 12618,
                 "typeDistribution": {
                     "DGA": 11,
                     "C2C": 117,
                     "Network Scan": 10,
                     "Mining": 140,
                     "Phishing": 53,
                     "Spam": 81,
                     "Malware": 281
                 },
                 "labelDistribution": {
                 },
                 "totalEndpoints": 115
             }
         }
     },
     {
         "NewIncidentCreated": {
             "companyId": "10228d9c-ff18-4251-ac19-514185e00f17",
             "incident": {
                 "id": "923bb150-231e-11ed-95fb-d3cd7c5e7afb",
                 "timestamp": "2022-08-23T20:02:52.773Z",
                 "statusTimestamp": "2022-08-23T20:02:52.773Z",
                 "status": "open",
                 "contacts": 1,
                 "adversaries": [
                     "chinagrouptraders.xyz"
                 ],
                 "adversaryId": "chinagrouptraders.xyz",
                 "adversaryTypes": [
                     "C2C",
                     "Malware"
                 ],
                 "description": "Malware family Keybase",
                 "labelDistribution": {
                     "218": 1
                 },
                 "totalEndpoints": 1,
                 "lastContact": "2022-08-20T20:37:02.228Z",
                 "unread": true,
                 "hasPlaybackContacts": false,
                 "firstContact": "2022-08-20T20:37:02.228Z"
             },
             "openIncidentsStats": {
                 "openIncidents": 577,
                 "totalContacts": 12619,
                 "typeDistribution": {
                     "DGA": 11,
                     "C2C": 118,
                     "Network Scan": 10,
                     "Mining": 140,
                     "Phishing": 53,
                     "Spam": 81,
                     "Malware": 282
                 },
                 "labelDistribution": {
                 },
                 "totalEndpoints": 116
             }
         }
     }
],
"offset": 724454
}
The response offset must be included in the following call to the service in order to guarantee the order of the updates.

Working with Adversarial Activity

The /adversarial-activity endpoints contain detailed compromise activity detected on your network, categorized according to threat type.

For the GET endpoint queries., the default values are used for all parameters.

Retrieve contacted adversaries

Get a paginated summary of the adversaries contacted by endpoints within a time-frame.

  1. POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries?key={company-key}
    2.                
  2. GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
fromDate
date-time (optional)
Search start date. The default value is 7 days before the current date. Example: "2021-04-01T14:40:14.939Z"
toDate
date-time (optional)
Search end date. The default value is the current date. Example: "2021-04-07T14:40:14.939Z"
endpoints
array (optional)
List of ID of contacting endpoints. If not specified, all objects are returned. Example: "182.168.100.29", “DESK-9867”
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 5

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --header 'Content-Type: application/json' \ --data-raw '{ "fromDate": "2021-02-23T16:15:30.00-05:00[Europe/Paris]", "toDate": "2021-03-15T16:15:30.234+01:00[Europe/Paris]", "adversary-types": [], "endpoints": [], "labels": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw ''
Example response (200 - Success):
  1. {
    "items": [
        {
            "host": "example.xyz",
            "adversary-types": [
                "Spam"
            ],
            "descriptions": [
                "Spam related"
            ],
            "contacts": 1,
            "last-contact": {
                "time": "2020-06-06T11:05:11.964Z",
                "endpoint": "Gateway company 1",
                "label": 37
            }
        }
    ],
    "timestamp": "2021-03-15T15:15:30.234Z",
    "pagination": {
        "page": 1,
        "items": 50
    }
}

Retrieve last contacted adversaries

Get a paginated list of details from adversarial hosts contacted within a number of past hours.

  1. POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last?key={company-key}
    2.                   
  2. GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
The maximum number of items that will be returned (default: 10, max: 10240)
hours
(only for GET) The number of past hours you want to narrow your results to  (default: 1)
max-items
(only for GET) Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
hours
integer (optional)
The number of past hours you want to narrow your results to. The default value 1.
endpoints
array (optional)
List of ID of contacting endpoints. If not specified, all objects are returned. Example: "182.168.100.29", “DESK-9867”
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 5

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --header 'Content-Type: application/json' \ --data-raw '{ "hours": 200, "adversary-types": [], "labels": [], "endpoints": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&max-items=1&hours=1' \ --data-raw ''

Example response (200 - Success):

  1. {
    "items": [
        {
            "host": "example.com",
            "adversary-types": [
                "Phishing"
            ],
            "descriptions": [
                "Phishing domain"
            ],
            "contacts": 15,
            "last-contact": {
                "time": "2021-04-12T15:25:02.228Z",
                "endpoint": "Gateway 1",
                "label": 37
            }
        }
    ],
    "timestamp": "2021-03-15T15:15:30.234Z",
    "pagination": {
        "page": 1,
        "items": 50
    }
}

Retrieve last contacted adversaries list

Get a list of adversarial hosts contacted within a number of past hours in plain text format.

  1. POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last/list?key={company-key}
    2.                
  2. GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last/list?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
hours
(only for GET) The number of past hours you want to narrow your results to  (default: 1)
max-items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
hours
integer (optional)
The number of past hours you want to narrow your results to. The default value 1.
endpoints
array (optional)
List of ID of contacting endpoints. If not specified, all objects are returned. Example: "182.168.100.29", “DESK-9867”
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 5

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last/list?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&max-items=10' \ --data-raw '{ "hours": 200, "adversary-types": [], "endpoints": [], "labels": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last/list?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&max-items=10&hours=1' \ --data-raw ''

Example response (200 - Success):

  1. 126.25.36.2 fraud.ro phishing.com fake-site.com 95.26.34.5

Retrieve affected endpoints

Get a paginated summary of the incidents across endpoints within a time-frame.

  1. POST https://defender.lumu.io/api/adversarial-activity/affected-endpoints?key={company-key} 
    2.                   
  2. GET https://defender.lumu.io/api/adversarial-activity/affected-endpoints?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
fromDate
date-time (optional)
Search start date. The default value is 7 days before the current date. Example: "2021-04-01T14:40:14.939Z"
toDate
date-time (optional)
Search end date. The default value is the current date. Example: "2021-04-07T14:40:14.939Z"
adversaries
array (optional)
List of ID of contacting endpoints. If not specified, all objects are returned. Example: "182.168.100.29", “DESK-9867”
adversary-types
array (optional)
List of adversarial hosts. If not specified, all objects are returned. Example: "phishing-site.domain".
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 5

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/adversarial-activity/affected-endpoints?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw '{ "fromDate": "2021-02-23T16:15:30.00-05:00[Europe/Paris]", "toDate": "2021-03-15T16:15:30.234+01:00[Europe/Paris]", "adversary-types": [], "adversaries": [], "labels": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/adversarial-activity/affected-endpoints?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw ''

Example response (200 - Success):

  1. {
    "items": [
        {
            "label": 38,
            "endpoint": "192.168.0.103",
            "last-ip": "192.168.0.103",
            "total-activity": 6,
            "adversarial-contacts": {
                "last-time": "2020-12-01T17:36:02.228Z",
                "last-host": "example.xyz",
                "count": 6, 
                "distribution": {
                    "C2C": 5,
                    "Mining": 1
                }
            }
        }
    ],
    "timestamp": "2021-03-15T15:15:30.234Z",
    "pagination": {
        "page": 1,
        "items": 50
    }
}
The total number of incidents ("count") does not necessarily have to match the sum of the incident types, as the same incident can be classified in different categories. In case an endpoint was contacted by more than two adversaries, only the most recent adversary will be retrieved.

Retrieve last affected endpoints

Get a paginated list of endpoints and adversarial contacts within a number of past hours.

  1. POST https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last?key={company-key}
    2.                   
  2. GET https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
The maximum number of items that will be returned (default: 10, max: 10240)
hours
(only for GET) The number of past hours you want to narrow your results to  (default: 1)

Body parameters

Name
Data Type
Description
hours
integer (optional)
The number of past hours you want to narrow your results to. The default value 1.
adversaries
array (optional)
List of adversarial hosts. If not specified, all objects are returned. Example: "phishing-site.domain".
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 5

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --header 'Content-Type: application/json' \ --data-raw '{ "hours": 700, "adversary-types": [], "adversaries": [], "labels": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50&hours=1' \ --data-raw ''

Example response (200 - Success):

  1. {
    "items": [
        {
            "label": 37,
            "endpoint": "Gateway 1",
            "last-ip": "192.168.3.11",
            "total-activity": 15,
            "adversarial-contacts": {
                "last-time": "2021-04-12T15:25:02.228Z",
                "last-host": "example.com",
                "count": 15,
                "distribution": {
                    "Phishing": 15
                }
            }
        }
    ],
    "timestamp": "2021-04-26T17:55:43.929612Z",
    "pagination": {
        "page": 1,
        "items": 50
    }
}

Retrieve last affected endpoints list

Get a list of endpoints with adversarial contacts within a number of hours in plain text format.

  1. POST https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last/list?key={company-key}
    2.                   
  2. GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last/list?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
hours
(only for GET) The number of past hours you want to narrow your results to  (default: 1)
max-items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
hours
integer (optional)
The number of past hours you want to narrow your results to. The default value 1.
adversaries
array (optional)
List of adversarial hosts. If not specified, all objects are returned. Example: "phishing-site.domain".
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
endpoint-identification-type
string (optional)
Type of endpoint identification. Possible values: "IP" (IP address), "ID" (case-sensitive endpoint ID) - The default value is "ID".
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 5

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last/list?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&max-items=10' \ --header 'Content-Type: application/json' \ --data-raw '{ "hours": 700, "adversary-types": [], "adversaries": [], "endpoint-identification-type": "", "labels": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last/list?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&max-items=50&hours=1' \ --data-raw ''

Example response (200 - Success):

  1. FW_SGM_DC_01 device95639625 Device64146868

Get a paginated summary of the adversaries related to Lumu Email that were contacted by endpoints.

  1. POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox?key={company-key}
    2.                   
  2. GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
fromDate
date-time (optional)
Search start date. The default value is 7 days before the current date. Example: "2021-04-01T14:40:14.939Z"
toDate
date-time (optional)
Search end date. The default value is the current date. Example: "2021-04-07T14:40:14.939Z"
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 5

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --header 'Content-Type: application/json' \ --data-raw '{ "fromDate": "2021-03-20T16:15:30.00-05:00[Europe/Paris]", "toDate": "2021-04-20T16:15:30.234+01:00[Europe/Paris]", "labels": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw ''

Example response (200 - Success):

  1. {
    "items": [
        {
            "host": "malicious.com",
            "adversary-types": [
                "Phishing"
            ],
            "descriptions": [
                "Phishing domain"
            ],
            "contacts": 1,
            "last-contact": {
                "time": "2021-03-23T15:37:02.228Z",
                "endpoint": "Seek & Destroy",
                "label": 55
            }
        }
    ],
    "timestamp": "2021-04-20T15:15:30.234Z",
    "pagination": {
        "page": 1,
        "items": 1,
        "next": 2
    }
}

Get a detailed list of adversarial hosts contacted, related to Spambox, within a number of past hours.

  1. POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last?key={company-key}
    2.                   
  2. GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
The maximum number of items that will be returned (default: 10, max: 10240)
hours
(only for GET) The number of past hours you want to narrow your results to  (default: 1)

Body parameters

Name
Data Type
Description
hours
integer (optional)
The number of past hours you want to narrow your results to. The default value 1.
labels
array (optional)
Label IDs. You may previously use the label API call to retrieve label IDs and names. If not specified, all objects are returned. Example: 2, 3, 5

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw '{ "hours": 200, "labels": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50&hours=1' \ --data-raw ''

Example response (200 - Success):

  1. {
    "items": [
        {
            "host": "suspicious.com",
            "adversary-types": [
                "C2C"
            ],
            "descriptions": [
                "Malware family ZeuS"
            ],
            "contacts": 3,
            "last-contact": {
                "time": "2021-04-26T22:37:59.148Z",
                "endpoint": "New GW",
                "label": 144
            }
        }
    ],
    "timestamp": "2021-04-28T18:05:06.517940Z",
    "pagination": {
        "page": 1,
        "items": 1,
        "next": 2
    }
}

Get a list of adversarial hosts contacted within a number of past hours in plain text format.

  1. POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last/list?key={company-key}
    2.                   
  2. GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last/list?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
hours
(only for GET) The number of past hours you want to narrow your results to  (default: 1)
max-items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
hours
integer (optional)
The number of past hours you want to narrow your results to. The default value 1.
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last/list?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&max-items=10' \ --data-raw '{ "hours": 200, "adversary-types": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last/list?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&max-items=10&hours=1' \ --data-raw ''

Example response (200 - Success):

  1. fraud.ro phishing.com fake-site.com

Working with Lumu Email

The  /spambox endpoints contain detailed compromise activity detected to adversaries found on your inbox, categorized according to threat type, regardless of being contacted or not. For the GET endpoint queries., the default values are used for all parameters. For getting started with Lumu Email, consult our documentation.

Retrieve Lumu Email adversaries

Get a paginated summary of the adversaries found on your inbox.

  1. POST https://defender.lumu.io/api/spambox/adversaries?key={company-key}

  2. GET https://defender.lumu.io/api/spambox/adversaries?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
fromDate
date-time (optional)
Search start date. The default value is 7 days before the current date. Example: "2021-04-01T14:40:14.939Z"
toDate
date-time (optional)
Search end date. The default value is the current date. Example: "2021-04-07T14:40:14.939Z"
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/spambox/adversaries?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw '{ "fromDate": "2021-04-01T00:00:00.00-05:00[America/Bogota]", "toDate": "2021-04-28T14:50:59.99-05:00[America/Bogota]", "adversary-types": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/spambox/adversaries?key=&page=1&items=50' \ --data-raw ''
Example response (200 - Success):
  1. { "adversaries": [ { "indicator": "http://mining.com" "info": [ { "type": "Mining", "description": "CryptoMining domain" } ] } ], "timestamp": "2021-04-29T15:29:48.177Z", "paginationInfo": { "page": 1, "items": 1, "next": 2 } }

Retrieve last Lumu Email adversaries

Get a detailed list of adversarial hosts found on your inbox, within a number of past hours.

  1. POST https://defender.lumu.io/api/spambox/adversaries/last?key={company-key}
    2.                      
  2. GET https://defender.lumu.io/api/spambox/adversaries/last?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
page
Page number of the result set (default: 1)
items
The maximum number of items that will be returned (default: 10, max: 10240)
hours
(only for GET) The number of past hours you want to narrow your results to  (default: 1)

Body parameters

Name
Data Type
Description
hours
integer (optional)
The number of past hours you want to narrow your results to. The default value 1.
adversary-types
array (optional)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/spambox/adversaries/last?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw '{ "hours": 200, "adversary-types": [] }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/spambox/adversaries/last?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50&hours=1' \ --data-raw ''

Example response (200 - Success):

  1. {
    "adversaries": [
        {
            "indicator": "http://mining.com",
            "info": [
                {
                    "type": "Mining",
                    "description": "CryptoMining domain"
                }
            ]
        }
    ],
    "paginationInfo": {
        "page": 1,
        "items": 1,
        "next": 2
    }
}

Retrieve last Lumu Email adversaries list

Get a list of adversarial hosts contacted within a number of past hours in plain text format.

  1. POST https://defender.lumu.io/api/spambox/adversaries/last/list?key={company-key}
    2.                   
  2. GET https://defender.lumu.io/api/spambox/adversaries/last/list?key={company-key}
Query Params
Description
key
Your company's unique API key available at the Lumu Portal.
hours
(only for GET) The number of past hours you want to narrow your results to  (default: 1)
max-items
Limit the number of results per page (default: 50, max: 100)

Body parameters

Name
Data Type
Description
hours
integer (optional)
The number of past hours you want to narrow your results to. The default value 1.

Example POST request:
  1. curl --location --request POST 'https://defender.lumu.io/api/spambox/adversaries/last/list?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&max-items=50' \ --data-raw '{ "hours": 200 }'
Example GET request:
  1. curl --location --request GET 'https://defender.lumu.io/api/spambox/adversaries/last/list?key=&max-items=50&hours=1' \ --data-raw ''

Example response (200 - Success):

  1. http://fraud.ro/ 
http://phishing.com/ 
http://fake-site.com/

    Still can’t find an answer?
    Send a message to our experts.
    Contact Us

        • Related Articles

        • Custom Integrations - Lumu Defender API

          For getting started with Lumu integrations with third-party solutions, consult our Integrations guide. The Lumu Defender API offers a framework to help you leverage the value of existing investments by integrating Lumu’s real-time information on ...

        • Symantec Endpoint Protection Custom Response Integration

          Before going through this article, check our Out-of-the-box App Integrations category. This is the recommended way to integrate the components of your cybersecurity stack with Lumu. If the product you are looking to integrate is there, it is advised ...

        • Microsoft Defender Out-of-the-Box Response Integration

          To learn more about Out-of-the-box Integrations and their benefits, please refer to this article. Microsoft Azure is now called Entra ID Requirements One of the following Microsoft plans: Microsoft 365 Business Premium Microsoft 365 E3/E5 Microsoft ...

        • Bitdefender Custom Response Integration

          Bitdefender Custom Response Integration This article shows how to leverage the Lumu Defender API and Bitdefender API to mitigate security risks. Requirements GravityZone Business Security Enterprise, cloud version, ...

        • GLPI Custom SecOps Integration

          This article shows how to leverage GLPI API and Lumu Defender API to enhance your SecOps capabilities, pushing Lumu incidents into a GLPI deployment as Service Tickets, and syncing both systems. Requirements A GLPI active server and Web access. An ...