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.

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

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.

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.

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:

   "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:

"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:

{
  "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.

{ "hours": 768 }  

Error Responses

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

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:

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.

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.

GET https://defender.lumu.io/api/administration/labels?key={company-key}  

Example request:

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):

{
    "labels": [
        {
            "id": 1, 
            "name": "Sales", 
            "relevance": 3
        }, 
        {
            "id": 2, 
            "name": "Customers", 
            "relevance": 1
        }, 
    ],
   "paginationInfo": {
        "page": 2, 
        "items": 2, 
        "next": 3, 
        "prev": 1
    }
}  

Retrieve a specific label [Available for Insights]

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

GET https://defender.lumu.io/api/administration/labels/{label-id}?key={company-key}  

Example request:

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

Example response (200 - Success):

{
     "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.

GET https://defender.lumu.io/api/administration/users?key={company-key}  

Example request:

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):

{
    "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
    }
}  

Retrieve a specific user [Available for Insights]

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

GET https://defender.lumu.io/api/administration/users/{user-id}?key={company-key}  

Example request:

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

{
      "id": 2,
      "role": "admin", 
      "email": "sara@company.com", 
      "name": "Sara Green", 
      "time_zone": "Etc/UTC",
      "deactivated": false
}  

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.

POST https://defender.lumu.io/api/incidents/all?key={company-key}  

Body parameters

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):

{
    "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,
    } }  

Get details of a specific Incident.

GET https://defender.lumu.io/api/incidents/{incident-uuid}/details?key={company-key}  

Example request:

 --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):

{
    "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"
}  

Retrieve a specific Incident context

Get details of the context information from a specific Incident.

GET https://defender.lumu.io/api/incidents/{incident-uuid}/context?key={company-key}&hash={hash-type}  

Example request:

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):

{
    "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"
}  

Retrieve open incidents [Available for Insights]

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

POST https://defender.lumu.io/api/incidents/open?key={company-key}  

Body parameters

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):

{
    "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
    }
}  

POST https://defender.lumu.io/api/incidents/muted?key={company-key}   

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": [] }'   

{
    "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
    }
}   

POST https://defender.lumu.io/api/incidents/closed?key={company-key}     

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": [] }'    

{
    "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
    }
}   

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

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": [] }'     

{
    "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
    }
}     

GET https://defender.lumu.io/api/incidents/{incident-uuid}/mark-as-read?key={company-key}     

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 ''      

POST https://defender.lumu.io/api/incidents/{incident-uuid}/mute?key={company-key}   

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": "" }'   

POST https://defender.lumu.io/api/incidents/{incident-uuid}/unmute?key={company-key}    

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": "" }'    

POST https://defender.lumu.io/api/incidents/{incident-uuid}/close?key={company-key}    

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": "" }'    

Lumu provides a streaming endpoint to subscribe to real-time updates on activity notifications. 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:

{
    "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
        }
    }
}  

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

  {
    "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"
    }
}    

{
    "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"
    }
}      

{
    "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"
    }
}            

{
    "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
        }
    }
}     

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.

POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries?key={company-key}
   
GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries?key={company-key}  

Body parameters

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": [] }'  

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 ''  

{
    "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
    }
}  

POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last?key={company-key}
    
GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last?key={company-key}   

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": [] }'   

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 ''   

{
    "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.

POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last/list?key={company-key}
   
GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last/list?key={company-key}  

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": [] }'   

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 ''   

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.

POST https://defender.lumu.io/api/adversarial-activity/affected-endpoints?key={company-key}
    
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:

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:

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):

{
    "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.

POST https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last?key={company-key}
    
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:

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:

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):

{
    "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
    }
}   

POST https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last/list?key={company-key}
    
GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last/list?key={company-key}  

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": [] }'    

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 ''    

FW_SGM_DC_01 device95639625 Device64146868    

POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox?key={company-key}
    
GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox?key={company-key}   

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": [] }'    

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 ''    

{
    "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
    }
}    

POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last?key={company-key}
    
GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last?key={company-key}   

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": [] }'   

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 ''   

{
    "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
    }
}   

POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last/list?key={company-key}
    
GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last/list?key={company-key}   

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": [] }'    

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 ''    

fraud.ro phishing.com fake-site.com    

Retrieve Spambox adversaries

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

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": [] }'   

curl --location --request GET 'https://defender.lumu.io/api/spambox/adversaries?key=&page=1&items=50' \ --data-raw ''   

{ "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 } }   

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

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": [] }'    

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 ''    

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

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

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 }'    

curl --location --request GET 'https://defender.lumu.io/api/spambox/adversaries/last/list?key=&max-items=50&hours=1' \ --data-raw ''    

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