prelude-sdk-beta 1406__py3-none-any.whl

prelude_sdk_beta/controllers/build_controller.py

@@ -0,0 +1,309 @@
+import urllib
+
+from prelude_sdk_beta.controllers.http_controller import HttpController
+from prelude_sdk_beta.models.account import verify_credentials
+from prelude_sdk_beta.models.codes import Control, EDRResponse
+
+
+class BuildController(HttpController):
+
+    def __init__(self, account):
+        super().__init__(account)
+
+    @verify_credentials
+    def clone_test(self, source_test_id):
+        """Clone a test"""
+        res = self.post(
+            f"{self.account.hq}/build/tests",
+            json=dict(source_test_id=source_test_id),
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def create_test(self, name, unit, technique=None, test_id=None):
+        """Create or update a test"""
+        body = dict(name=name, unit=unit)
+        if technique:
+            body["technique"] = technique
+        if test_id:
+            body["id"] = test_id
+
+        res = self.post(
+            f"{self.account.hq}/build/tests",
+            json=body,
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def update_test(
+        self,
+        test_id,
+        name=None,
+        unit=None,
+        technique=None,
+        crowdstrike_expected_outcome: EDRResponse = None,
+    ):
+        """Update a test"""
+        body = dict()
+        if crowdstrike_expected_outcome:
+            body["expected"] = dict(crowdstrike=crowdstrike_expected_outcome.value)
+        if name:
+            body["name"] = name
+        if unit:
+            body["unit"] = unit
+        if technique is not None:
+            body["technique"] = technique
+
+        res = self.post(
+            f"{self.account.hq}/build/tests/{test_id}",
+            json=body,
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def delete_test(self, test_id, purge):
+        """Delete an existing test"""
+        res = self.delete(
+            f"{self.account.hq}/build/tests/{test_id}",
+            json=dict(purge=purge),
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def undelete_test(self, test_id):
+        """Undelete a tombstoned test"""
+        res = self.post(
+            f"{self.account.hq}/build/tests/{test_id}/undelete",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def upload(self, test_id, filename, data, skip_compile=False):
+        """Upload a test or attachment"""
+        if len(data) > 1000000:
+            raise ValueError(f"File size must be under 1MB ({filename})")
+
+        h = self.account.headers | {"Content-Type": "application/octet-stream"}
+        query_params = ""
+        if skip_compile:
+            query_params = "?" + urllib.parse.urlencode(dict(skip_compile=True))
+        res = self.post(
+            f"{self.account.hq}/build/tests/{test_id}/{filename}{query_params}",
+            data=data,
+            headers=h,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def compile_code_string(self, code: str, source_test_id: str = None):
+        """Compile a code string"""
+        res = self.post(
+            f"{self.account.hq}/build/compile",
+            json=dict(code=code, source_test_id=source_test_id),
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def get_compile_status(self, job_id):
+        res = self.get(
+            f"{self.account.hq}/build/compile/{job_id}",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def create_threat(
+        self, name, published, threat_id=None, source_id=None, source=None, tests=None
+    ):
+        """Create a threat"""
+        body = dict(name=name, published=published)
+        if threat_id:
+            body["id"] = threat_id
+        if source_id:
+            body["source_id"] = source_id
+        if source:
+            body["source"] = source
+        if tests:
+            body["tests"] = tests
+
+        res = self.post(
+            f"{self.account.hq}/build/threats",
+            json=body,
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def update_threat(
+        self,
+        threat_id,
+        name=None,
+        source_id=None,
+        source=None,
+        published=None,
+        tests=None,
+    ):
+        """Update a threat"""
+        body = dict()
+        if name:
+            body["name"] = name
+        if source_id is not None:
+            body["source_id"] = source_id
+        if source is not None:
+            body["source"] = source
+        if published is not None:
+            body["published"] = published
+        if tests is not None:
+            body["tests"] = tests
+
+        res = self.post(
+            f"{self.account.hq}/build/threats/{threat_id}",
+            json=body,
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def delete_threat(self, threat_id, purge):
+        """Delete an existing threat"""
+        res = self.delete(
+            f"{self.account.hq}/build/threats/{threat_id}",
+            json=dict(purge=purge),
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def undelete_threat(self, threat_id):
+        """Undelete a tombstoned threat"""
+        res = self.post(
+            f"{self.account.hq}/build/threats/{threat_id}/undelete",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def create_detection(
+        self, rule: str, test_id: str, detection_id=None, rule_id=None
+    ):
+        """Create a detection"""
+        body = dict(rule=rule, test_id=test_id)
+        if detection_id:
+            body["detection_id"] = detection_id
+        if rule_id:
+            body["rule_id"] = rule_id
+
+        res = self.post(
+            f"{self.account.hq}/build/detections",
+            json=body,
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def update_detection(self, detection_id: str, rule=None, test_id=None):
+        """Update a detection"""
+        body = dict()
+        if rule:
+            body["rule"] = rule
+        if test_id:
+            body["test_id"] = test_id
+
+        res = self.post(
+            f"{self.account.hq}/build/detections/{detection_id}",
+            json=body,
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def delete_detection(self, detection_id: str):
+        """Delete an existing detection"""
+        res = self.delete(
+            f"{self.account.hq}/build/detections/{detection_id}",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def create_threat_hunt(
+        self,
+        control: Control,
+        test_id: str,
+        name: str,
+        query: str,
+        threat_hunt_id: str = None,
+    ):
+        """Create a threat hunt"""
+        body = dict(
+            control=control.name,
+            name=name,
+            query=query,
+            test_id=test_id,
+        )
+        if threat_hunt_id:
+            body["id"] = threat_hunt_id
+
+        res = self.post(
+            f"{self.account.hq}/build/threat_hunts",
+            json=body,
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def update_threat_hunt(
+        self,
+        threat_hunt_id: str,
+        name: str = None,
+        query: str = None,
+        test_id: str = None,
+    ):
+        """Update a threat hunt"""
+        body = dict()
+        if name:
+            body["name"] = name
+        if query:
+            body["query"] = query
+        if test_id:
+            body["test_id"] = test_id
+
+        res = self.post(
+            f"{self.account.hq}/build/threat_hunts/{threat_hunt_id}",
+            json=body,
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def delete_threat_hunt(self, threat_hunt_id: str):
+        """Delete an existing threat hunt"""
+        res = self.delete(
+            f"{self.account.hq}/build/threat_hunts/{threat_hunt_id}",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()

prelude_sdk_beta/controllers/detect_controller.py

@@ -0,0 +1,243 @@
+from prelude_sdk_beta.controllers.http_controller import HttpController
+from prelude_sdk_beta.models.account import verify_credentials
+
+
+class DetectController(HttpController):
+
+    def __init__(self, account):
+        super().__init__(account)
+
+    def register_endpoint(self, host, serial_num, reg_string, tags=None):
+        """Register (or re-register) an endpoint to your account"""
+        body = dict(id=f"{host}:{serial_num}")
+        if tags:
+            body["tags"] = tags
+        account, token = reg_string.split("/")
+
+        res = self._session.post(
+            f"{self.account.hq}/detect/endpoint",
+            headers=dict(account=account, token=token, _product="py-sdk"),
+            json=body,
+            timeout=10,
+        )
+        return res.text
+
+    @verify_credentials
+    def update_endpoint(self, endpoint_id, tags=None):
+        """Update an endpoint in your account"""
+        body = dict()
+        if tags is not None:
+            body["tags"] = tags
+
+        res = self.post(
+            f"{self.account.hq}/detect/endpoint/{endpoint_id}",
+            headers=self.account.headers,
+            json=body,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def delete_endpoint(self, ident: str):
+        """Delete an endpoint from your account"""
+        params = dict(id=ident)
+        res = self.delete(
+            f"{self.account.hq}/detect/endpoint",
+            headers=self.account.headers,
+            json=params,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def list_endpoints(self, days: int = 90):
+        """List all endpoints on your account"""
+        params = dict(days=days)
+        res = self.get(
+            f"{self.account.hq}/detect/endpoint",
+            headers=self.account.headers,
+            params=params,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def describe_activity(self, filters: dict, view: str = "protected"):
+        """Get report for an Account"""
+        params = dict(view=view, **filters)
+        res = self.get(
+            f"{self.account.hq}/detect/activity",
+            headers=self.account.headers,
+            params=params,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def threat_hunt_activity(self, threat_hunt_id=None, test_id=None, threat_id=None):
+        """Get threat hunt activity"""
+        filters = dict(
+            threat_hunt_id=threat_hunt_id, test_id=test_id, threat_id=threat_id
+        )
+        res = self.get(
+            f"{self.account.hq}/detect/threat_hunt_activity",
+            headers=self.account.headers,
+            params=filters,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def list_tests(self, filters: dict = None):
+        """List all tests available to an account"""
+        res = self.get(
+            f"{self.account.hq}/detect/tests",
+            headers=self.account.headers,
+            params=filters if filters else {},
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def get_test(self, test_id):
+        """Get properties of an existing test"""
+        res = self.get(
+            f"{self.account.hq}/detect/tests/{test_id}",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def list_techniques(self):
+        """List techniques"""
+        res = self.get(
+            f"{self.account.hq}/detect/techniques",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def list_threats(self):
+        """List threats"""
+        res = self.get(
+            f"{self.account.hq}/detect/threats",
+            headers=self.account.headers,
+            params={},
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def get_threat(self, threat_id):
+        """Get properties of an existing threat"""
+        res = self.get(
+            f"{self.account.hq}/detect/threats/{threat_id}",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def list_detections(self):
+        """List detections"""
+        res = self.get(
+            f"{self.account.hq}/detect/detections",
+            headers=self.account.headers,
+            params={},
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def get_detection(self, detection_id):
+        """Get properties of an existing detection"""
+        res = self.get(
+            f"{self.account.hq}/detect/detections/{detection_id}",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def list_threat_hunts(self, filters: dict = None):
+        """List threat hunts"""
+        res = self.get(
+            f"{self.account.hq}/detect/threat_hunts",
+            headers=self.account.headers,
+            params=filters if filters else {},
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def get_threat_hunt(self, threat_hunt_id):
+        """Get properties of an existing threat hunt"""
+        res = self.get(
+            f"{self.account.hq}/detect/threat_hunts/{threat_hunt_id}",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def do_threat_hunt(self, threat_hunt_id):
+        """Run a threat hunt"""
+        res = self.post(
+            f"{self.account.hq}/detect/threat_hunts/{threat_hunt_id}",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def download(self, test_id, filename):
+        """Clone a test file or attachment"""
+        res = self.get(
+            f"{self.account.hq}/detect/tests/{test_id}/{filename}",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.content
+
+    @verify_credentials
+    def schedule(self, items: list):
+        """Schedule tests and threats so endpoints will start running them
+
+        Example: items=[dict(run_code='DAILY', tags='grp-1,grp2', test_id='123-123-123'),
+                        dict(run_code='DAILY', tags='grp-1', threat_id='abc-def-ghi')]
+        """
+        res = self.post(
+            url=f"{self.account.hq}/detect/queue",
+            headers=self.account.headers,
+            json=dict(items=items),
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def unschedule(self, items: list):
+        """Unschedule tests and threats so endpoints will stop running them
+
+        Example: items=[dict(tags='grp-1,grp2', test_id='123-123-123'),
+                        dict(tags='grp-1', threat_id='abc-def-ghi')]
+        """
+        res = self.delete(
+            f"{self.account.hq}/detect/queue",
+            headers=self.account.headers,
+            json=dict(items=items),
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def accept_terms(self, name, version):
+        """Accept terms and conditions"""
+        res = self.post(
+            f"{self.account.hq}/iam/terms",
+            headers=self.account.headers,
+            json=dict(name=name, version=version),
+            timeout=10,
+        )
+        return res.json()

prelude_sdk_beta/controllers/export_controller.py

@@ -0,0 +1,31 @@
+from prelude_sdk_beta.controllers.http_controller import HttpController
+from prelude_sdk_beta.models.account import verify_credentials
+from prelude_sdk_beta.models.codes import SCMCategory
+
+
+class ExportController(HttpController):
+
+    def __init__(self, account):
+        super().__init__(account)
+
+    @verify_credentials
+    def export_scm(
+        self,
+        export_type: SCMCategory,
+        filter: str = None,
+        orderby: str = None,
+        top: int = None,
+    ):
+        """Download partner data as a CSV"""
+        params = {
+            "$filter": filter,
+            "$orderby": orderby,
+            "$top": top,
+        }
+        res = self.post(
+            f"{self.account.hq}/export/scm/{export_type.name}",
+            params=params,
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()

prelude_sdk_beta/controllers/generate_controller.py

@@ -0,0 +1,40 @@
+from prelude_sdk_beta.controllers.http_controller import HttpController
+from prelude_sdk_beta.models.account import verify_credentials
+from prelude_sdk_beta.models.codes import Control
+
+
+class GenerateController(HttpController):
+    def __init__(self, account):
+        super().__init__(account)
+
+    @verify_credentials
+    def upload_threat_intel(self, file: str):
+        with open(file, "rb") as f:
+            body = f.read()
+        res = self.post(
+            f"{self.account.hq}/generate/threat-intel",
+            data=body,
+            headers=self.account.headers | {"Content-Type": "application/pdf"},
+            timeout=30,
+        )
+        return res.json()
+
+    @verify_credentials
+    def get_threat_intel(self, job_id: str):
+        res = self.get(
+            f"{self.account.hq}/generate/threat-intel/{job_id}",
+            headers=self.account.headers,
+            timeout=10,
+        )
+        return res.json()
+
+    @verify_credentials
+    def generate_from_partner_advisory(self, partner: Control, advisory_id: str):
+        params = dict(advisory_id=advisory_id)
+        res = self.post(
+            f"{self.account.hq}/generate/partner-advisories/{partner.name}",
+            headers=self.account.headers,
+            json=params,
+            timeout=30,
+        )
+        return res.json()

prelude_sdk_beta/controllers/http_controller.py

@@ -0,0 +1,63 @@
+import os
+import requests
+
+from requests.adapters import HTTPAdapter, Retry
+
+
+PRELUDE_BACKOFF_FACTOR = int(os.getenv("PRELUDE_BACKOFF_FACTOR", 30))
+PRELUDE_BACKOFF_TOTAL = int(os.getenv("PRELUDE_BACKOFF_TOTAL", 0))
+
+
+class HttpController(object):
+    def __init__(self, account):
+        self._session = requests.Session()
+        self.account = account
+
+        retry = Retry(
+            total=PRELUDE_BACKOFF_TOTAL,
+            backoff_factor=PRELUDE_BACKOFF_FACTOR,
+            status_forcelist=[429],
+        )
+
+        self._session.mount("http://", HTTPAdapter(max_retries=retry))
+        self._session.mount("https://", HTTPAdapter(max_retries=retry))
+
+    def get(self, url, retry=True, **kwargs):
+        res = self._session.get(url, **kwargs)
+        if res.status_code == 200:
+            return res
+        if res.status_code == 401 and retry and self.account.token_location:
+            self.account.refresh_tokens()
+            self.account.update_auth_header()
+            return self.get(url, retry=False, **kwargs)
+        raise Exception(res.text)
+
+    def post(self, url, retry=True, **kwargs):
+        res = self._session.post(url, **kwargs)
+        if res.status_code == 200:
+            return res
+        if res.status_code == 401 and retry and self.account.token_location:
+            self.account.refresh_tokens()
+            self.account.update_auth_header()
+            return self.post(url, retry=False, **kwargs)
+        raise Exception(res.text)
+
+    def delete(self, url, retry=True, **kwargs):
+        res = self._session.delete(url, **kwargs)
+        if res.status_code == 200:
+            return res
+        if res.status_code == 401 and retry and self.account.token_location:
+            self.account.refresh_tokens()
+            self.account.update_auth_header()
+            return self.delete(url, retry=False, **kwargs)
+        raise Exception(res.text)
+
+    def put(self, url, retry=True, **kwargs):
+        res = self._session.put(url, **kwargs)
+        if res.status_code == 200:
+            return res
+        if res.status_code == 401 and retry and self.account.token_location:
+            self.account.refresh_tokens()
+            self.account.update_auth_header()
+            return self.put(url, retry=False, **kwargs)
+        raise Exception(res.text)