prelude-sdk-beta 1441__tar.gz

prelude_sdk_beta-1441/LICENSE

@@ -0,0 +1,9 @@
+MIT LICENSE
+
+Copyright 2022, Prelude Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

prelude_sdk_beta-1441/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: prelude-sdk-beta
+Version: 1441
+Summary: For interacting with the Prelude API
+Home-page: https://github.com/preludeorg
+Author: Prelude Research
+Author-email: support@preludesecurity.com
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# Prelude SDK
+
+Interact with the Prelude Service API via Python. 
+
+> The prelude-cli utility wraps around this SDK to provide a rich command line experience.
+
+Install this package to write your own tooling that works with Build or Detect functionality.
+
+- IAM: manage your account
+- Build: write and maintain your collection of security tests
+- Detect: schedule security tests for your endpoints
+
+## Quick start
+
+```bash
+pip install prelude-sdk
+```
+
+## Documentation 
+
+TBD
+
+## Testing
+
+To test the Python SDK and Probes, run the following commands from the python/sdk/ directory:
+
+```bash
+pip install -r tests/requirements.txt
+pytest tests --api https://api.preludesecurity.com --email <EMAIL>
+```

prelude_sdk_beta-1441/README.md

@@ -0,0 +1,30 @@
+# Prelude SDK
+
+Interact with the Prelude Service API via Python. 
+
+> The prelude-cli utility wraps around this SDK to provide a rich command line experience.
+
+Install this package to write your own tooling that works with Build or Detect functionality.
+
+- IAM: manage your account
+- Build: write and maintain your collection of security tests
+- Detect: schedule security tests for your endpoints
+
+## Quick start
+
+```bash
+pip install prelude-sdk
+```
+
+## Documentation 
+
+TBD
+
+## Testing
+
+To test the Python SDK and Probes, run the following commands from the python/sdk/ directory:
+
+```bash
+pip install -r tests/requirements.txt
+pytest tests --api https://api.preludesecurity.com --email <EMAIL>
+```

prelude_sdk_beta-1441/prelude_sdk_beta/controllers/build_controller.py

@@ -0,0 +1,315 @@
+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,
+        )
+        threat_hunt = res.json()
+        if self.account.resolve_enums:
+            self.resolve_enums(threat_hunt, [(Control, "control")])
+        return threat_hunt
+
+    @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,
+        )
+        threat_hunt = res.json()
+        if self.account.resolve_enums:
+            self.resolve_enums(threat_hunt, [(Control, "control")])
+        return threat_hunt
+
+    @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-1441/prelude_sdk_beta/controllers/detect_controller.py

@@ -0,0 +1,256 @@
+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, RunCode
+
+
+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,
+        )
+        endpoints = res.json()
+        if self.account.resolve_enums:
+            self.resolve_enums(endpoints, [(Control, "control")])
+        return endpoints
+
+    @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,
+        )
+        threat_hunts = res.json()
+        if self.account.resolve_enums:
+            self.resolve_enums(threat_hunts, [(Control, "control")])
+        return threat_hunts
+
+    @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,
+        )
+        threat_hunt = res.json()
+        if self.account.resolve_enums:
+            self.resolve_enums(threat_hunt, [(Control, "control")])
+        return threat_hunt
+
+    @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,
+        )
+        schedule = res.json()
+        if self.account.resolve_enums:
+            self.resolve_enums(schedule, [(RunCode, "run_code")])
+        return schedule
+
+    @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-1441/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()