Add subdomains (#11)

* Remove unused import

* Add subdomain endpoint

* Improve README

Author: dannywillems

README.md

@@ -19,6 +19,11 @@ Docstrings are used to document the library.
 Types are also used to inform the user on what type of objects the functions are
 expecting.
 
+Each API response is encoded in either a `SuccessResponse` object or a
+`ErrorResponse`.
+The methods `is_success()` or `is_error()` exist on each API response.
+You can get the actual response by using the method `json()` on the response object.
+
 The output are events described in
 [l9format](https://github.com/LeakIX/l9format-python).
 When you have an object of type `l9Event` (or the longer
@@ -29,6 +34,16 @@ model class for the available fields.
 For instance, to access the IP of an object `event` of type `L9Event`, you can
 use `event.ip`.
 
+Each object can be transformed back into a Python dictionary/JSON using the method `to_dict()`.
+For instance, for the response of the subdomains endpoint, you can get back individual JSON by using:
+
+```python
+def example_get_subdomains():
+    response = CLIENT.get_subdomains("leakix.net")
+    for subdomain in response.json():
+        print(subdomain.to_dict())
+```
+
 ## Support
 
 Feel free to open an issue if you have any question.

example/example_client.py

@@ -120,6 +120,12 @@ def example_bulk_service():
     print(response.json())
 
 
+def example_get_subdomains():
+    domain = "leakix.net"
+    response = CLIENT.get_subdomains(domain)
+    print(response.json())
+
+
 if __name__ == "__main__":
     example_get_host_filter_plugin()
     example_get_service_filter_plugin()
@@ -132,3 +138,4 @@ def example_bulk_service():
     example_bulk_export()
     example_bulk_service()
     example_bulk_export_last_event()
+    example_get_subdomain()

leakix/client.py

@@ -9,6 +9,7 @@
 from leakix.plugin import *
 from leakix.plugin import APIResult
 from leakix.field import *
+from leakix.domain import L9Subdomain
 
 
 __VERSION__ = "0.1.9"
@@ -153,6 +154,18 @@ def get_plugins(self):
             r.response_json = [APIResult.from_dict(d) for d in r.json()]
         return r
 
+    def get_subdomains(self, domain: str):
+        """
+        Returns the list of subdomains for a given domain.
+        The output is a list of `L9Subdomain` objects. The fields are `subdomain`, `distinct_ips` and `last_seen`.
+        To get back a JSON/Python dictionary, use the method `to_dict` on the individual element of the response object.
+        """
+        url = "%s/api/subdomains/%s" % (self.base_url, domain)
+        r = self.__get(url, params=None)
+        if r.is_success():
+            r.response_json = [L9Subdomain.from_dict(d) for d in r.json()]
+        return r
+
     def bulk_export(self, queries: Optional[List[Query]] = None):
         url = "%s/bulk/search" % (self.base_url)
         if queries is None or len(queries) == 0:

leakix/domain.py

@@ -0,0 +1,7 @@
+from serde import Model, fields
+
+
+class L9Subdomain(Model):
+    subdomain: fields.Str()
+    distinct_ips: fields.Int()
+    last_seen: fields.DateTime()

leakix/field.py

@@ -1,5 +1,4 @@
 from leakix.plugin import Plugin
-from abc import ABCMeta, abstractmethod
 from datetime import datetime
 from typing import Optional
 from enum import Enum