Defender API: Features, Functionality, and Usage

Defender API: Features, Functionality, and Usage

The Lumu Defender API uses HTTP requests and returns JSON responses. This documentation outlines the required endpoints, request parameters, sample JSON payloads, and expected response messages.

Idea
The Defender API provides a framework for maximizing the value of your existing cybersecurity investments by integrating real-time data on confirmed compromise instances with your current security stack, enabling unified automation of mitigation and remediation efforts. To get started, refer to our comprehensive documentation

The Defender API is language-agnostic and supports both incoming and outgoing data. All API calls are secured with HTTPS (SSL/TLS) and authenticated using API keys.

Access and Authentication

The Defender API requires each client to use a unique API key, referred to in this documentation as {company-key}. This key is available in the Integrations section of the Lumu Portal and is managed directly by your organization's administrators.

Alert The revocation process generates a new Defender API key. This action cannot be undone and will cause your existing API integrations to stop working until you update your integrations with the new key. This option should be used only in specific scenarios, such as when the current API key is compromised or must be rotated due to security policies.

The ability to integrate Lumu with your security stack via the Defender API is included in the Lumu Defender subscription. This tier enables seamless integration of Lumu’s real-time analysis into your existing security tools, helping you mitigate and remediate compromise incidents quickly and accurately.

Info
Lumu Insights customers have access to the Defender API, though with certain limitations. In this document, resources available to Insights accounts are marked with the tag  [Available for Insights].
You can access the API using various methods, including:
  1. Applications that support REST calls, such as Postman or Insomnia
  2. Programming languages or command-line tools, like Python or curl
  3. Third-party platforms that support REST integration, such as Fortinet, QRadar, or Splunk

Choose the method that best fits your organization’s needs and environment.

Postman Tutorial

Lumu provides a Postman collection, which is a structured set of pre-configured HTTP requests grouped together to test and document an API. Collections can include variables, authentication details, test scripts, and environment settings to streamline development and collaboration. You can use this collection to test the Lumu Defender API.

Resources overview

The following resources are accessible via the Lumu Defender API. These are familiar terms that can be traced to their counterpart in the Lumu Portal.

Resource
Description
administration
Used to retrieve data on users and labels.
incidents
Used to subscribe to incident updates, retrieve incident data, and manage incident statuses.
adversarial-activity
Used to retrieve all adversarial activity detected across your network perimeter.
spambox
Used to retrieve adversarial activity associated with your organization’s email intelligence.

Syntax, pagination and date format

General Syntax

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

All API endpoints are relative to the base URL. For example, since the base URL is URL of https://defender.lumu.io/api , the /incidents endpoint would be https://defender.lumu.io/api/incidents

Pagination

Paging results can be controlled using query string parameters. This feature is available for endpoints that return more data than can fit 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:

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 uses a standardized date and time format to ensure consistency and interoperability with third-party applications. All date and time values are returned in Coordinated Universal Time (UTC) and follow the formats defined by RFC 3339 and ISO 8601 (YYYY-MM-DDTHH:mm:ss:sssZ). For example, 2021-03-21T18:25:43.000Z , where the trailing Z indicates that the time zone is UTC (GMT).

You can submit queries to the Defender API using date and time values in your local time zone. However, note that the API will automatically convert all time zone values to UTC.

The following are examples of date and time formats currently accepted by the Defender API:
Example
"2025-02-23T10:15:30.00-05:00[Europe/Paris]"
"2025-02-23T16:15:30.234+01:00[America/Bogota]"
"2025-02-23T16:15:30.234+01:00"
"2025-12-23T16:15:30.235"
"2025-02-23T10:15:30"
All the dates and times provided in the example above will be converted automatically by the Defender API to UTC format. Example: "2025-02-23T15:15:30.234Z"

When using the fromDate and ToDate parameters in your queries, ensure that the specified date range does not exceed 31 calendar days and is not older than 180 calendar days from the current date.

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

Example
{
  "fromDate": "2025-02-0923T15:15:30.234Z",
  "toDate": "2025-03-23T15:15:30.234Z"
}
Queries that include the hours parameter are limited to a maximum of 767 hours (approximately 30 days) prior to the current date and time. The following example shows a query where the  hours value exceeds this limit, which will result in a 400 Bad Request error.
Example
{
  "hours": 800,
}

Error Responses

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

HTTP Code
Description
200
OK Everything worked as expected. The expected data was returned.
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

Info
The default rate limits for API calls are 50 requests per minute and 10,000 requests per day.

For queries that return listed results, you can specify 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 to be returned (default: 10, max: 10240).

Example: https://defender.lumu.io/resources/administration/labels?key={company-key}&items=20&page=3&max-items=50
Notes The response examples in this document are not exhaustive and do not cover all possible parameter configurations or operations. They are intended to illustrate the basic structure, formatting, and labeling of the data returned by the API. Actual responses may include additional parameters depending on the context of the request.

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.

Info
Consult our documentation to get 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 Request
GET Request
GET https://defender.lumu.io/administration/labels?key={company-key}

Query Params
Description
key
Your company's unique API key, available in 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
curl --location --request GET 'https://defender.lumu.io/administration/labels?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items=50' \ --data-raw ''

Example Response
{
    "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 label 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.

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

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

Example Response
{
     "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 Request
GET Request
GET https://defender.lumu.io/administration/users?key={company-key}
Query Params
Description
key
Your company's unique API key, available in 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
curl --location --request GET 'https://defender.lumu.io/api/administration/users?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3&page=1&items50' \ --data-raw ''
Example Response
{
    "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  cannot login in to the Lumu Portal.

Retrieve a specific user  [Available for Insights]

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

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

Example Request
curl --location --request GET 'https://defender.lumu.io/api/administration/users/2?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3' \ --data-raw ''' 
Example Response
{
      "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.

Info
To get started with Incidents, consult our documentation.

General considerations

Incident statuses and types may vary over time. Therefore, any implementation using endpoints that accept these as query parameters should account for possible changes.

The following 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 with POST API actions (such as mark as read, mute, unmute, and close), include the  Lumu-User-Id header in the request, using the user's ID as its value.
Notes Example:  Lumu-User-Id:2. This parameter is optional. If it is not included, the action will not be associated with any specific user. For example, if the query header includes the ID 2, which corresponds to the user "Integration user", the incident log will appear as shown in the following image.

Retrieve Incidents

Retrieves a paginated list of incidents for the company, ordered by most recent first.

POST Request
POST Request
POST https://defender.lumu.io/api/incidents/all?key={company-key}
Query Params
Description
key
Your company's unique API key, available in 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 can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3, 5
Example Request
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
{
    "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's details  [Available for Insights]

Retrieves detailed information about a specific incident. The response may include additional parameters—such as DNSPacketExtraInfo—depending on the data collection source.

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

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",
    "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's context

Retrieves contextual information related to a specific incident.

GET Request
GET Request
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 in 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
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"
}

Comment a specific incident  [Available for Insights]

Add a comment to a specific incident. This operation does not return a response. 

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

Body parameters:
Name
Data Type
Description
comment
string
comment to be added to the incident
Example Request
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]

Retrieves a paginated list of open incidents for the company, ordered by most recent first.

POST Request
POST Request
POST https://defender.lumu.io/incidents/open?key={company-key}
Query Params
Description
key
 Your company's unique API key, available in 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 can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,
Example Request
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
    }
}

Retrieve muted incidents  [Available for Insights]

Retrieves a paginated list of muted incidents for the company, ordered by most recent first.

POST Request
POST Request
POST https://defender.lumu.io/incidents/muted?key={company-key}
Query Params
Description
key
Your company unique API key available at the Lumu Portal.
pages
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 can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,

Mute incident  [Available for Insights]

Silence notifications for a specific incident.
POST Request
POST Request
POST https://defender.lumu.io/api/incidents/{incident-uuid}/mute?key={company-key}
Query Params
Description
key
Your company's unique API key, available in 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
curl --location --request POST 'https://defender.lumu.io/incidents/d3f41000-af3f-11eb-84b5-75a575634188/mute?key=56a0fc30-a6de-85eb-8249-a117f0a9f8g3' \ --data-raw '{ "comment": "" }'

Unmute incident  [Available for Insights]

Enable notifications for a specific incident.

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

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

Close incident  [Available for Insights]

Close a specific incident.
POST Request
POST Request
POST https://defender.lumu.io/api/incidents/{incident-uuid}/close?key={company-key}
Query Params
Description
key
Your company's unique API key, available in 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
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 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}
Info
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:

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

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

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

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

Example
{
    "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 whenever new contact with an Indicator of Compromise (IoC) is detected. The following log shows an example of an updated incident:

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

Working with Adversarial Activity

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

Info
For GET endpoint queries, default values are applied to all parameters if none are specified.

Retrieve contacted adversaries

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

POST Request
GET Request
POST Request
POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries?key={company-key}
GET Request
GET https://defender.lumu.io/api/adversarial-activity/contacted-adversaries?key={company-key}
Query Params
Description
key
Your company's unique API key, available in 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 can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
POST Request Example
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": [] }'
GET Request Example
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)
{
    "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

Retrieves a paginated list of details about adversarial hosts contacted within the specified number of past hours.

POST Request
GET Request
POST Request
POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last?key={company-key}
GET Request
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 in the Lumu Portal
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)
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 can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
POST Request Example
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": [] }'
GET Request Example
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)
{ "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 Request
GET Request
POST Request
POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/last/list?key={company-key}
GET Request
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 in 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
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 can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
POST Request Example
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": [] }'
GET Request Example
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)
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 Request
GET Request
POST Request
POST https://defender.lumu.io/api/adversarial-activity/affected-endpoints?key={company-key}
GET Request
GET https://defender.lumu.io/api/adversarial-activity/affected-endpoints?key={company-key}
Query Params
Description
key
Your company's unique API key, available in 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)
Adversary types. If not specified, all objects are returned. Examples: "C2C", "Malware", "DGA", "Mining", "Spam", "Phishing"
labels
array (optional)
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
POST Request Example
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": [] }'
GET Reuqest Example
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
    }
}   
Info
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 Request
GET Request
POST Request
POST https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last?key={company-key}
GET Request
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 in 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.
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 can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
POST Request Example
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": [] }'
GET Request Example
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
    }
}  

Retrieve last affected endpoints list

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

POST Request
GET Request
POST Request
POST https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last/list?key={company-key}
GET Request
GET https://defender.lumu.io/api/adversarial-activity/affected-endpoints/last/list?key={company-key}
Query Params
Description
key
Your company's unique API key, available in 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 can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5

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

POST Request
GET Request
POST Request
POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox?key={company-key}
GET Request
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 in 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 can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5

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

POST Request
GET Request
POST Request
POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last?key={company-key}
GET Request
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 in the Lumu Portal
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)
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
date-time (optional)
The number of past hours you want to narrow your results to. The default value 1.
labels
array (optional)
Label IDs — You can use the Labels API call beforehand to retrieve available label IDs and their corresponding names. If not specified, all objects are returned. Example: 2, 3,5
POST Request Example
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": [] }'
GET Request Example
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)
{
    "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.

POST Request
GET request
POST Request
POST https://defender.lumu.io/api/adversarial-activity/contacted-adversaries/spambox/last/list?key={company-key}
GET request
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 in 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"

Working with Lumu Email Intelligence (Spambox Endpoint)

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

Get a paginated summary of the adversaries related to Lumu Email Intelligence.

POST Request
GET Request
POST Request
POST https://defender.lumu.io/api/spambox/adversaries?key={company-key}
GET Request
GET https://defender.lumu.io/api/spambox/adversaries?key={company-key}
Query Params
Description
key
Your company's unique API key, available in 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"
POST Request Example
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": [] }'
GET Request Example
curl --location --request GET 'https://defender.lumu.io/api/spambox/adversaries?key=&page=1&items=50' \ --data-raw ''
Example Response (200 - Success)
{ "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 } }

Get a detailed list of adversarial hosts related to Lumu Email Intelligence, within a number of past hours.

POST Request
GET Request
POST Request
POST https://defender.lumu.io/api/spambox/adversaries/last?key={company-key}
GET Request
GET https://defender.lumu.io/api/spambox/adversaries/last?key={company-key}
Query Params
Description
key
Your company's unique API key, available in the Lumu Portal
page
Page number of the result set (default: 1)
items
Limit the number of results per page (default: 50, max: 100)
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"
POST Request Example
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": [] }'
GET Request Example
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)
{
    "adversaries": [
        {
            "indicator": "http:<span>//</span>mining<span>.</span>com",
            "info": [
                {
                    "type": "Mining",
                    "description": "CryptoMining domain"
                }
            ]
        }
    ],
    "paginationInfo": {
        "page": 1,
        "items": 1,
        "next": 2
    }
}  

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

POST Request
GET Request
POST Request
POST https://defender.lumu.io/api/spambox/adversaries/last/list?key={company-key}
GET Request
GET https://defender.lumu.io/api/spambox/adversaries/last/list?key={company-key}
Query Params
Description
key
Your company's unique API key, available in 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.
POST Request Example
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 }'
GET Request Example
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)
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 ...

        • ESET PROTECT Cloud Custom Response Integration

          Learn how to use the Lumu Defender API and ESET PROTECT Cloud, together with the ESET Connect API, to effectively mitigate security risks. Response integration between ESET PROTECT Cloud and Lumu Requirements ESET PROTECT Cloud You need an ESET ...

        • 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, ...

        • 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 ...

        • Guardicore Custom Response Integration

          This article shows how to leverage the Lumu Defender API and Guardicore API to mitigate security risks. Response integration between Guardcore and Lumu Requirements An active Guardicore Centra subscription A Guardicore administrator user. Lumu ...