pylookyloo 1.24.0__py3-none-any.whl → 1.26.1__py3-none-any.whl

pylookyloo/api.py

@@ -2,12 +2,14 @@
 
 from __future__ import annotations
 
+import os
 import base64
 import warnings
 
+from datetime import datetime
 from importlib.metadata import version
 from io import BytesIO, StringIO
-from typing import Any, TypedDict, overload
+from typing import Any, TypedDict, overload, Literal
 from urllib.parse import urljoin, urlparse
 from pathlib import PurePosixPath, Path
 
@@ -40,6 +42,7 @@ class CaptureSettings(TypedDict, total=False):
     timezone_id: str | None
     locale: str | None
     color_scheme: str | None
+    java_script_enabled: bool
     viewport: dict[str, int] | None
     referer: str | None
 
@@ -145,6 +148,7 @@ class Lookyloo():
                timezone_id: str | None=None,
                locale: str | None=None,
                color_scheme: str | None=None,
+               java_script_enabled: bool=True,
                viewport: dict[str, int] | None=None,
                referer: str | None=None,
                listing: bool | None=None,
@@ -167,6 +171,7 @@ class Lookyloo():
                timezone_id: str | None=None,
                locale: str | None=None,
                color_scheme: str | None=None,
+               java_script_enabled: bool | None=None,
                viewport: dict[str, int] | None=None,
                referer: str | None=None,
                listing: bool | None=None,
@@ -193,6 +198,7 @@ class Lookyloo():
         :param timezone_id: The timezone, warning, it m ust be a valid timezone (continent/city)
         :param locale: The locale of the browser
         :param color_scheme: The prefered color scheme of the browser (light or dark)
+        :param java_script_enabled: If False, no JS will run during the capture.
         :param viewport: The viewport of the browser used for capturing
         :param referer: The referer URL for the capture
         :param listing: If False, the capture will be not be on the publicly accessible index page of lookyloo
@@ -244,6 +250,8 @@ class Lookyloo():
                 to_send['locale'] = locale
             if color_scheme:
                 to_send['color_scheme'] = color_scheme
+            if java_script_enabled is not None:
+                to_send['java_script_enabled'] = java_script_enabled
             if viewport:
                 to_send['viewport'] = viewport
             if referer:
@@ -283,6 +291,14 @@ class Lookyloo():
         else:
             raise AuthError('Unable to initialize API key')
 
+    def get_user_config(self) -> dict[str, Any] | None:
+        '''Get the configuration enforced by the server for the current user (requires an authenticated user, use init_apikey first)
+        '''
+        if not self.apikey:
+            raise AuthError('You need to initialize the apikey to use this method (see init_apikey)')
+        r = self.session.get(urljoin(self.root_url, str(PurePosixPath('json', 'get_user_config'))))
+        return r.json()
+
     def misp_export(self, tree_uuid: str) -> dict[str, Any]:
         '''Export the capture in MISP format'''
         r = self.session.get(urljoin(self.root_url, str(PurePosixPath('json', tree_uuid, 'misp_export'))))
@@ -320,6 +336,13 @@ class Lookyloo():
         r = self.session.post(urljoin(self.root_url, str(PurePosixPath('admin', tree_uuid, 'hide'))))
         return r.json()
 
+    def remove_capture(self, tree_uuid: str) -> dict[str, str]:
+        '''Remove a capture, it will be impossible to get it by UUID (requires an authenticated user, use init_apikey first)'''
+        if not self.apikey:
+            raise AuthError('You need to initialize the apikey to use this method (see init_apikey)')
+        r = self.session.post(urljoin(self.root_url, str(PurePosixPath('admin', tree_uuid, 'remove'))))
+        return r.json()
+
     def get_redirects(self, capture_uuid: str) -> dict[str, Any]:
         '''Returns the initial redirects.
 
@@ -433,13 +456,22 @@ class Lookyloo():
         r = self.session.get(urljoin(self.root_url, str(PurePosixPath('json', 'stats'))))
         return r.json()
 
-    def get_takedown_information(self, capture_uuid: str) -> dict[str, Any]:
+    @overload
+    def get_takedown_information(self, capture_uuid: str, filter_contacts: Literal[True]) -> list[str]:
+        ...
+
+    @overload
+    def get_takedown_information(self, capture_uuid: str, filter_contacts: Literal[False]=False) -> list[dict[str, Any]]:
+        ...
+
+    def get_takedown_information(self, capture_uuid: str, filter_contacts: bool=False) -> list[dict[str, Any]] | list[str]:
         '''Returns information required to request a takedown for a capture
 
         :param capture_uuid: UUID of the capture
+        :param filter_contacts: If True, will only return the contact emails and filter out the invalid ones.
         '''
         r = self.session.post(urljoin(self.root_url, str(PurePosixPath('json', 'takedown'))),
-                              json={'capture_uuid': capture_uuid})
+                              json={'capture_uuid': capture_uuid, 'filter': filter_contacts})
         return r.json()
 
     def compare_captures(self, capture_left: str, capture_right: str, /, *, compare_settings: CompareSettings | None=None) -> dict[str, Any]:
@@ -464,8 +496,121 @@ class Lookyloo():
         return r.json()
 
     def send_mail(self, tree_uuid: str, email: str = '', comment: str | None = None) -> bool | dict[str, Any]:
+        '''Reports a capture by sending an email to the investigation team
+
+        :param tree_uuid: UUID of the capture
+        :param email: Email of the reporter, used by the analyst to get in touch
+        :param comment: Description of the URL, will be given to the analyst
+        '''
         to_send = {'email': email}
         if comment:
             to_send['comment'] = comment
         r = self.session.post(urljoin(self.root_url, str(PurePosixPath('json', tree_uuid, 'report'))), json=to_send)
         return r.json()
+
+    def get_recent_captures(self, timestamp: str | datetime | float | None=None) -> list[str]:
+        '''Gets the uuids of the most recent captures
+
+        :param timestamp: Oldest timestamp to consider
+        '''
+        if timestamp:
+            if isinstance(timestamp, datetime):
+                timestamp = timestamp.timestamp()
+            url = urljoin(self.root_url, str(PurePosixPath('json', 'recent_captures', str(timestamp))))
+        else:
+            url = urljoin(self.root_url, str(PurePosixPath('json', 'recent_captures')))
+        r = self.session.get(url)
+        return r.json()
+
+    def get_categories_captures(self, category: str | None=None) -> list[str] | dict[str, list[str]] | None:
+        '''Get uuids for a specific category or all categorized uuids if category is None
+
+        :param category: The category according to which the uuids are to be returned
+        '''
+        if category:
+            url = urljoin(self.root_url, str(PurePosixPath('json', 'categories', category)))
+        else:
+            url = urljoin(self.root_url, str(PurePosixPath('json', 'categories')))
+        r = self.session.get(url)
+        return r.json()
+
+    @overload
+    def upload_capture(self, *, quiet: Literal[True],
+                       listing: bool = False,
+                       full_capture: Path | BytesIO | str | None = None,
+                       har: Path | BytesIO | str | None = None,
+                       html: Path | BytesIO | str | None = None,
+                       last_redirected_url: str | None = None,
+                       screenshot: Path | BytesIO | str | None = None) -> str:
+        ...
+
+    @overload
+    def upload_capture(self, *, quiet: Literal[False]=False,
+                       listing: bool = False,
+                       full_capture: Path | BytesIO | str | None = None,
+                       har: Path | BytesIO | str | None = None,
+                       html: Path | BytesIO | str | None = None,
+                       last_redirected_url: str | None = None,
+                       screenshot: Path | BytesIO | str | None = None) -> tuple[str, dict[str, str]]:
+        ...
+
+    def upload_capture(self, *, quiet: bool = False,
+                       listing: bool = False,
+                       full_capture: Path | BytesIO | str | None = None,
+                       har: Path | BytesIO | str | None = None,
+                       html: Path | BytesIO | str | None = None,
+                       last_redirected_url: str | None = None,
+                       screenshot: Path | BytesIO | str | None = None) -> str | tuple[str, dict[str, str]]:
+        '''Upload a capture via har-file and others
+
+        :param quiet: Returns the UUID only, instead of the the UUID and the potential error / warning messages
+        :param listing: if true the capture should be public, else private - overwritten if the full_capture is given and it contains no_index
+        :param full_capture: path to the capture made by another instance
+        :param har: Harfile of the capture
+        :param html: rendered HTML of the capture
+        :param last_redirected_url: The landing page of the capture
+        :param screenshot: Screenshot of the capture
+        '''
+        def encode_document(document: Path | BytesIO | str) -> str:
+            if isinstance(document, str):
+                if not os.path.exists(document):
+                    raise FileNotFoundError(f'{document} does not exist')
+                document = Path(document)
+            if isinstance(document, Path):
+                with document.open('rb') as f:
+                    document = BytesIO(f.read())
+            return base64.b64encode(document.getvalue()).decode()
+
+        to_send: dict[str, Any] = {'listing': listing}
+
+        if full_capture:
+            b64_full_capture = encode_document(full_capture)
+            to_send['full_capture'] = b64_full_capture
+        elif har:
+            b64_har = encode_document(har)
+            to_send['har_file'] = b64_har
+
+            if html:
+                b64_html = encode_document(html)
+                to_send['html_file'] = b64_html
+
+            if last_redirected_url:
+                to_send['landing_page'] = last_redirected_url
+
+            if screenshot:
+                b64_screenshot = encode_document(screenshot)
+                to_send['screenshot_file'] = b64_screenshot
+        else:
+            raise PyLookylooError("Full capture or at least har-file are required")
+
+        r = self.session.post(urljoin(self.root_url, str(PurePosixPath('json', 'upload'))), json=to_send)
+        r.raise_for_status()
+        json_response = r.json()
+        uuid = json_response['uuid']
+        messages = json_response['messages']
+
+        if not uuid:
+            raise PyLookylooError('Unable to get UUID from lookyloo instance.')
+        if quiet:
+            return uuid
+        return uuid, messages

{pylookyloo-1.24.0.dist-info → pylookyloo-1.26.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pylookyloo
-Version: 1.24.0
+Version: 1.26.1
 Summary: Python CLI and module for Lookyloo
 Home-page: https://github.com/lookyloo/PyLookyloo
 License: BSD-3-Clause
@@ -24,8 +24,9 @@ Classifier: Topic :: Internet
 Classifier: Topic :: Security
 Provides-Extra: docs
 Requires-Dist: Sphinx (<7.2) ; (python_version < "3.9") and (extra == "docs")
-Requires-Dist: Sphinx (>=7.2,<8.0) ; (python_version >= "3.9") and (extra == "docs")
-Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: Sphinx (>=7.2,<8.0) ; (python_version >= "3.9" and python_version < "3.10") and (extra == "docs")
+Requires-Dist: Sphinx (>=8,<9) ; (python_version >= "3.10") and (extra == "docs")
+Requires-Dist: requests (>=2.32.3,<3.0.0)
 Project-URL: Documentation, https://pylookyloo.readthedocs.io/en/latest/
 Project-URL: Repository, https://github.com/lookyloo/PyLookyloo
 Description-Content-Type: text/markdown

pylookyloo-1.26.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+pylookyloo/__init__.py,sha256=_JYXwXHL7ShZkeruvGd8qDTpxNRfuDjvV65SOMMU6yc,1922
+pylookyloo/api.py,sha256=2U7ExW9Cr7dJUOXXop_UIULR4Zru4SogC2Cu_wJ6OcM,28683
+pylookyloo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pylookyloo-1.26.1.dist-info/LICENSE,sha256=4C4hLYrIkUD96Ggk-y_Go1Qf7PBZrEm9PSeTGe2nd4s,1516
+pylookyloo-1.26.1.dist-info/METADATA,sha256=NwfOYpAMGHvhLk1kQzntIwKqR07HNrER1-0_SXzmGhY,2450
+pylookyloo-1.26.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+pylookyloo-1.26.1.dist-info/entry_points.txt,sha256=y2c0Ujg8co6Xyf7MoxStVU-fLQMZBSGAg-KFidmsha4,44
+pylookyloo-1.26.1.dist-info/RECORD,,

pylookyloo-1.24.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-pylookyloo/__init__.py,sha256=_JYXwXHL7ShZkeruvGd8qDTpxNRfuDjvV65SOMMU6yc,1922
-pylookyloo/api.py,sha256=nbuCJmeGy34ZCFH5kZeVwJlysgmn_h6ZiQrqYAmA5iM,21748
-pylookyloo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pylookyloo-1.24.0.dist-info/LICENSE,sha256=4C4hLYrIkUD96Ggk-y_Go1Qf7PBZrEm9PSeTGe2nd4s,1516
-pylookyloo-1.24.0.dist-info/METADATA,sha256=GV8FRY1VU92q8jN8-Ko5Tohul-Vf0J0a7AM_S0Vsrvw,2340
-pylookyloo-1.24.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-pylookyloo-1.24.0.dist-info/entry_points.txt,sha256=y2c0Ujg8co6Xyf7MoxStVU-fLQMZBSGAg-KFidmsha4,44
-pylookyloo-1.24.0.dist-info/RECORD,,