Initial Commit

Author: justhyped

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hyper Solutions
+
+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.

README.md

@@ -0,0 +1,175 @@
+# Hyper Solutions SDK for Python
+
+## Installation
+
+To use the Hyper Solutions SDK in your Python project, you need to install it using the following command:
+
+```
+pip install hyper-sdk
+```
+
+## Usage
+
+### Creating a Session
+
+To start using the SDK, you need to create a new `Session` instance by providing your API key:
+
+```python
+from hyper_sdk import Session
+
+session = Session(api_key="your-api-key")
+```
+
+You can also optionally set a JWT key and a custom HTTP client:
+
+```python
+from hyper_sdk import Session
+
+session = Session(api_key="your-api-key", jwt_key="your-jwt-key", client=custom_http_client)
+```
+
+## Akamai
+
+The Akamai package provides functions for interacting with Akamai Bot Manager, including generating sensor data, parsing script path, parsing pixel challenges, and handling sec-cpt challenges.
+
+### Generating Sensor Data
+
+To generate sensor data required for generating valid Akamai cookies, use the `generate_sensor_data` method:
+
+```python
+from hyper_sdk import SensorInput
+
+sensor_input = SensorInput(
+    page_url="https://example.com/",
+    user_agent="your-user-agent",
+    abck="your-abck-cookie",
+    bmsz="your-bmsz-cookie",
+    version="2.0"
+)
+sensor_data = session.generate_sensor_data(sensor_input)
+```
+
+### Parsing Script Path
+
+To parse the Akamai Bot Manager script path from the given HTML code, use the `parse_script_path` function from the `script_path` module:
+
+```python
+from hyper_sdk.akamai.script_path import parse_script_path
+
+script_path = parse_script_path(html_source)
+```
+
+### Handling Sec-Cpt Challenges
+
+The Akamai package provides functions for handling sec-cpt challenges:
+
+- `SecCptChallenge.parse`: Parses a sec-cpt challenge from an HTML source.
+- `generate_sec_cpt_payload`: Generates a sec-cpt payload using the provided sec-cpt cookie.
+- `sleep`: Sleeps for the duration specified in the sec-cpt challenge.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.sec_cpt import SecCptChallenge
+
+challenge = SecCptChallenge.parse(html_source)
+payload = challenge.generate_sec_cpt_payload(sec_cpt_cookie)
+challenge.sleep()
+```
+
+### Validating Cookies
+
+The Akamai package provides functions for validating cookies:
+
+- `is_cookie_valid`: Determines if the provided `_abck` cookie value is valid based on the given request count.
+- `is_cookie_invalidated`: Determines if the current session requires more sensors to be sent.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.stop_signal import is_cookie_valid, is_cookie_invalidated
+
+is_valid = is_cookie_valid(abck_cookie, request_count)
+is_invalidated = is_cookie_invalidated(abck_cookie)
+```
+
+### Generating Pixel Data
+
+To generate pixel data, use the `generate_pixel_data` method:
+
+```python
+from hyper_sdk import PixelInput
+
+pixel_input = PixelInput(
+    user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.82 Safari/537.36",
+    html_var="your-html-var",
+    script_var="your-script-var"
+)
+pixel_data = session.generate_pixel_data(pixel_input)
+```
+
+### Parsing Pixel Challenges
+
+The Akamai package provides functions for parsing pixel challenges:
+
+- `parse_pixel_html_var`: Parses the required pixel challenge variable from the given HTML code.
+- `parse_pixel_script_url`: Parses the script URL of the pixel challenge script and the URL to post a generated payload to from the given HTML code.
+- `parse_pixel_script_var`: Parses the dynamic value from the pixel script.
+
+Example usage:
+
+```python
+from hyper_sdk.akamai.pixel import parse_pixel_html_var, parse_pixel_script_url, parse_pixel_script_var
+
+html_var = parse_pixel_html_var(html_source)
+script_url, post_url = parse_pixel_script_url(html_source)
+script_var = parse_pixel_script_var(script_source)
+```
+
+
+## Incapsula
+
+The Incapsula package provides functions for interacting with Imperva Incapsula, including generating Reese84 sensor data, UTMVC cookies, and parsing UTMVC script paths.
+
+### Generating Reese84 Sensor
+
+To generate sensor data required for generating valid Reese84 cookies, use the `generate_reese84_sensor` method:
+
+```python
+sensor_data = session.generate_reese84_sensor(site="example.com", user_agent="your-user-agent")
+```
+
+### Generating UTMVC Cookie
+
+To generate the UTMVC cookie using the Hyper Solutions API, use the `generate_utmvc_cookie` method:
+
+```python
+from hyper_sdk import UtmvcInput
+
+utmvc_input = UtmvcInput(
+    user_agent="your-user-agent",
+    session_ids=["session-id-1", "session-id-2"],
+    script="your-script"
+)
+utmvc_cookie = session.generate_utmvc_cookie(utmvc_input)
+```
+
+### Parsing UTMVC Script Path
+
+To parse the UTMVC script path from a given script content, use the `parse_utmvc_script_path` function from the `utmvc` module:
+
+```python
+from hyper_sdk.incapsula.utmvc import parse_utmvc_script_path
+
+script_path = parse_utmvc_script_path(script_content)
+```
+
+### Generating UTMVC Submit Path
+
+To generate a unique UTMVC submit path with a random query parameter, use the `get_utmvc_submit_path` function from the `utmvc` module:
+
+```python
+from hyper_sdk.incapsula.utmvc import get_utmvc_submit_path
+
+submit_path = get_utmvc_submit_path()
+```

hyper_sdk/__init__.py

@@ -0,0 +1,6 @@
+from .akamai.pixel import *
+from .akamai.script_path import *
+from .akamai.sec_cpt import *
+from .akamai.stop_signal import *
+from .incapsula.utmvc import *
+from .session import *

hyper_sdk/akamai/__init__.py

@@ -0,0 +1,4 @@
+from .pixel import *
+from .script_path import *
+from .sec_cpt import *
+from .stop_signal import *

hyper_sdk/akamai/pixel.py

@@ -0,0 +1,83 @@
+import re
+
+pixel_html_expr = re.compile(r'bazadebezolkohpepadr="(\d+)"')
+pixel_script_url_expr = re.compile(r'src="(https?://.+/akam/\d+/\w+)"')
+pixel_script_var_expr = re.compile(r'g=_\[(\d+)]')
+pixel_script_string_array_expr = re.compile(r'var _=\[(.+?)];')
+pixel_script_strings_expr = re.compile(r'("[^",]*")')
+
+
+def parse_pixel_html_var(src: str) -> int:
+    """
+        ParsePixelHtmlVar gets the required pixel challenge variable from the given HTML code src.
+
+        Args:
+            src (str): HTML source code as a string.
+
+        Returns:
+            int: The parsed pixel HTML variable.
+
+        Raises:
+            Exception: If the pixel HTML var is not found in the source.
+    """
+    match = pixel_html_expr.search(src)
+    if match:
+        return int(match.group(1))
+    else:
+        raise Exception("hyper-sdk: pixel HTML var not found")
+
+
+def parse_pixel_script_url(src: str) -> tuple[str, str]:
+    """
+        ParsePixelScriptURL gets the script URL of the pixel challenge script and the URL
+        to post a generated payload to from the given HTML code src.
+
+        Args:
+            src (str): HTML source code as a string.
+
+        Returns:
+            tuple[str, str]: A tuple containing the script URL and the post URL.
+
+        Raises:
+            Exception: If the script URL is not found in the source.
+    """
+    match = pixel_script_url_expr.search(src)
+    if match:
+        script_url = match.group(1)
+        # Create post_url
+        parts = script_url.split("/")
+        parts[-1] = "pixel_" + parts[-1]
+        post_url = "/".join(parts)
+        return script_url, post_url
+    else:
+        raise Exception("hyper-sdk: script URL not found")
+
+
+def parse_pixel_script_var(src: str) -> str:
+    """
+        Gets the dynamic value from the pixel script.
+
+        Args:
+            src (str): HTML source code as a string.
+
+        Returns:
+            str: The dynamic value extracted from the pixel script.
+
+        Raises:
+            Exception: If the script variable is not found or if there are issues extracting it.
+    """
+    index_match = pixel_script_var_expr.search(src)
+    if not index_match:
+        raise Exception("hyper-sdk: script var not found")
+    string_index = int(index_match.group(1))
+
+    array_declaration_match = pixel_script_string_array_expr.search(src)
+    if not array_declaration_match:
+        raise Exception("hyper-sdk: script var not found")
+
+    raw_strings = pixel_script_strings_expr.findall(array_declaration_match.group(1))
+    if string_index >= len(raw_strings):
+        raise Exception("hyper-sdk: script var not found")
+
+    string_value = raw_strings[string_index].strip('"')
+    return string_value

hyper_sdk/akamai/script_path.py

@@ -0,0 +1,28 @@
+import re
+
+# Precompiled regular expressions
+script_path_expr = re.compile(r'<script type="text/javascript"\s+(?:nonce=".*?")?\s+src="([a-z\d/\-_]+)"></script>',
+                              re.IGNORECASE)
+
+
+def parse_script_path(src: str) -> str:
+    """
+        Gets the Akamai Bot Manager web SDK path from the given HTML code src.
+
+        This function searches the provided HTML source code for the path of a JavaScript script tag that matches the
+        specified regular expression pattern.
+
+        Args:
+            src (str): The HTML source code as a string.
+
+        Returns:
+            str: The path of the script extracted from the script tag.
+
+        Raises:
+            Exception: If the script path is not found in the source.
+    """
+    match = script_path_expr.search(src)
+    if match:
+        return match.group(1)
+    else:
+        raise "hyper-sdk: script path not found"