The Custom Collector API is a seamless way to integrate your network infrastructure with Lumu while layering Continuous Compromise Assessment. It allows sending network metadata captured from third-party platforms/services/appliances to Lumu, and it can also be used as an alternative for obtaining greater visibility in cases where the enterprise network restricts the use of Virtual Appliances.

If you are interested in getting started with Custom Collector API management in the Lumu Portal, consult our documentation.

Figure 1 - Custom Collector API general deployment architecture.

This article provides you with Custom Collector API endpoints specifications, requirements, sample JSON, and request parameters.

Access and Authentication

The authentication of the Lumu Customer Collector API is handled by a unique key referred to in this document as {lumu-client-key}. Each custom collector also has a unique ID that is referred to as {collector-id} to perform diagnostic/support tasks smoothly.

The Custom Collector API key (1) and collectors ID (2) are found in the Lumu Portal and are self-managed by company administrators.

Figure 2 - Custom Collector API management area - Lumu Portal.

General Syntax

The Lumu Custom Collectors is a REST API restricted to HTTPS and is available to make requests at: https://api.lumu.io

All requests to this endpoint must be sent with the Content-Type: application/json header.

All the post requests to Custom Collector API are identified as traffic of the company by the required query parameters {lumu_client_key} and {collector_id}, as in the following example:

 

  
https://api.lumu.io/collectors/64c1a892-9ea3-4c7b-b8af-e1f5b2ff6b0c/dns/packets?key=64c1a892-9ea3-4c7b-b8af-e1f5b2ff6b0c.

 

Send DNS Packets

This method post arrays of DNS packets captured using third-party solutions such as Logstash, Graylog, and other DNS packet capture tools.

 

  
POST /collectors/{collector-id}/dns/packets?key={lumu-client-key}

 

 

  
[ { "id": 69, "timestamp": "2021-01-05T14:37:02.228Z", "client_ip": "192.168.0.103", "client_name": "User9800", "op_code": "QUERY", "response_code": "NOERROR", "question": { "type": "A", "name": "www.example.com", "class": "IN" }, "flags": { "authoritative": false, "recursion_available": true, "truncated_response": false, "checking_disabled": false, "recursion_desired": true, "authentic_data": false }, "answers": [ { "name": "www.example.com", "type": "A", "class": "IN", "ttl": 2549, "data": "69.172.201.153" } ] } ]
 

Body parameters (details)

Send DNS Queries

Use this method to post simple DNS queries extracted from DNS servers’ logs. It is a simplified version of the DNS Packets method. While this form of posting DNS data is suitable for Lumu’s Illumination Process, it lacks information that could be useful for understanding more complex adversarial activity.

Note: Only operations of the QUERY type that belongs to the IN DNS Class should be posted through this service.

This method receives an array of DNS queries, which are identified as traffic of the company by the {lumu-client-key} in the Lumu Portal. The path parameter {collector-id} is a unique identifier for each collector to perform diagnostic/support tasks easily.

 

  
POST /collectors/{collector-id}/dns/queries?key={lumu-client-key}

 

 

  
[ { "timestamp": "2021-01-06T14:37:02.228Z", "name": "www.example.com", "client_ip": "192.168.0.103", "client_name": "MACHINE-0987", "type": "A" } ]

 

Body parameters (details)

Send Proxy Entries

Use this method to post proxy entries composed of information extracted from the client proxy log. This method receives an array of Proxy entries, which are identified as traffic of the company by the {lumu-client-key}.

 

  
POST /collectors/{collector-id}/proxy/entries?key={lumu-client-key}

 

 

  
[ { "timestamp": "2021-01-07T14:37:02.228Z", "client_ip": "192.168.0.103", "client_name": "optional DeviceName", "user_name": "optional UserName", "remote_ip": "201.98.87.1", "time_taken": 6532, "request": { "uri": { "host": "birazoku.com", "port": 443, "scheme": "https", "path": "/index.html", "query": "name=myname&wlkd=ksi" }, "method": "post", "length": 1034, "body_length": 887, "referrer": "referrer.com", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X1" }, "response": { "code": 200, "phrase": "Success", "length": 3049, "body_length": 2978 } } ]

 

Body parameters (details)

  

   
POST /collectors/{collector-id}/firewall/entries?key={lumu-client-key}
  

  

   
[ { "timestamp": "2021-01-06T14:37:02.228Z", "time_taken": 1630, "user_name": "optional UserName", "action": "accept", "protocol": "http", "additional": { "path": "/mhiQtgAAAAE", "query": "key=value&t=846" }, "source": { "ip": "10.0.0.46", "port": 54786, "name": "FW_SGM_DC_01" }, "destination": { "ip": "52.91.3.178", "port": 443, "name": "google.com" }, "sent": { "bytes": 53489, "packets": 183 }, "received": { "bytes": 67385, "packets": 163 } } ]