scythe-ttp 0.12.4__tar.gz → 0.14.0__tar.gz

{scythe_ttp-0.12.4 → scythe_ttp-0.14.0}/PKG-INFO

@@ -1,10 +1,8 @@
 Metadata-Version: 2.4
 Name: scythe-ttp
-Version: 0.12.4
+Version: 0.14.0
 Summary: An extensible framework for emulating attacker TTPs with Selenium.
-Home-page: https://github.com/EpykLab/scythe
-Author: EpykLab
-Author-email: cyber@epyklab.com
+Author-email: EpykLab <cyber@epyklab.com>
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -13,37 +11,31 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Information Technology
 Classifier: Topic :: Security
 Classifier: Framework :: Pytest
-Requires-Python: >=3.8
+Requires-Python: <=3.13,>=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: PySocks==1.7.1
 Requires-Dist: attrs==25.3.0
 Requires-Dist: certifi==2025.6.15
 Requires-Dist: charset-normalizer==3.4.2
 Requires-Dist: h11==0.16.0
 Requires-Dist: idna==3.10
 Requires-Dist: outcome==1.3.0.post0
-Requires-Dist: PySocks==1.7.1
+Requires-Dist: pydantic-core==2.18.2
+Requires-Dist: pydantic==2.7.1
 Requires-Dist: requests==2.32.4
 Requires-Dist: selenium==4.34.0
 Requires-Dist: setuptools==80.9.0
 Requires-Dist: sniffio==1.3.1
 Requires-Dist: sortedcontainers==2.4.0
-Requires-Dist: trio==0.30.0
 Requires-Dist: trio-websocket==0.12.2
+Requires-Dist: trio==0.30.0
 Requires-Dist: typing_extensions==4.14.0
 Requires-Dist: urllib3==2.4.0
 Requires-Dist: websocket-client==1.8.0
 Requires-Dist: wsproto==1.2.0
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
+Requires-Dist: typer
 Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 <h1 align="center">Scythe</h1>
 
@@ -792,3 +784,79 @@ This architecture supports testing scenarios from simple security checks to comp
 ---
 
 **Scythe**: Comprehensive adverse conditions testing for robust, reliable systems.
+
+
+
+## Scythe CLI (embedded)
+
+Scythe now ships with a lightweight CLI that helps you bootstrap and manage your local Scythe testing workspace. After installing the package (pipx recommended), a `scythe` command is available.
+
+Note: The CLI is implemented with Typer, so `scythe --help` and per-command help (e.g., `scythe run --help`) are available. Command names and options remain the same as before.
+
+- Install with pipx:
+  - pipx install scythe-ttp
+- Or install locally in editable mode for development:
+  - pip install -e .
+
+### Commands
+
+- scythe init [--path PATH]
+  - Initializes a Scythe project at PATH (default: current directory).
+  - Creates:
+    - ./.scythe/scythe.db (SQLite DB with tests and runs tables)
+    - ./.scythe/scythe_tests/ (where your test scripts live)
+
+- scythe new <name>
+  - Creates a new test template at ./.scythe/scythe_tests/<name>.py and registers it in the DB (tests table).
+
+- scythe run <name or name.py>
+  - Runs the specified test from ./.scythe/scythe_tests and records the run into the DB (runs table). Exit code reflects success (0) or failure (non-zero).
+
+- scythe db dump
+  - Prints a JSON dump of the tests and runs tables from ./.scythe/scythe.db.
+
+- scythe db sync-compat <name>
+  - Reads COMPATIBLE_VERSIONS from ./.scythe/scythe_tests/<name>.py (if present) and updates the `tests.compatible_versions` field in the DB. If the variable is missing, the DB entry is set to empty and the command exits successfully.
+
+### Test template
+
+Created tests use a minimal template so you can start quickly:
+
+```python
+#!/usr/bin/env python3
+
+# scythe test initial template
+
+import argparse
+import os
+import sys
+import time
+from typing import List, Tuple
+
+# Scythe framework imports
+from scythe.core.executor import TTPExecutor
+from scythe.behaviors import HumanBehavior
+
+
+def scythe_test_definition(args):
+    # TODO: implement your test using Scythe primitives.
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Scythe test script")
+    parser.add_argument('--url', help='Target URL (overridden by localhost unless FORCE_USE_CLI_URL=1)')
+    args = parser.parse_args()
+
+    ok = scythe_test_definition(args)
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+Notes:
+- The CLI looks for tests in ./.scythe/scythe_tests.
+- Each `run` creates a record in the `runs` table with datetime, name_of_test, x_scythe_target_version (best-effort parsed from output), result, raw_output.
+- Each `new` creates a record in the `tests` table with name, path, created_date, compatible_versions.

scythe_ttp-0.12.4/scythe_ttp.egg-info/PKG-INFO → scythe_ttp-0.14.0/README.md

@@ -1,50 +1,3 @@
-Metadata-Version: 2.4
-Name: scythe-ttp
-Version: 0.12.4
-Summary: An extensible framework for emulating attacker TTPs with Selenium.
-Home-page: https://github.com/EpykLab/scythe
-Author: EpykLab
-Author-email: cyber@epyklab.com
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Information Technology
-Classifier: Topic :: Security
-Classifier: Framework :: Pytest
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: attrs==25.3.0
-Requires-Dist: certifi==2025.6.15
-Requires-Dist: charset-normalizer==3.4.2
-Requires-Dist: h11==0.16.0
-Requires-Dist: idna==3.10
-Requires-Dist: outcome==1.3.0.post0
-Requires-Dist: PySocks==1.7.1
-Requires-Dist: requests==2.32.4
-Requires-Dist: selenium==4.34.0
-Requires-Dist: setuptools==80.9.0
-Requires-Dist: sniffio==1.3.1
-Requires-Dist: sortedcontainers==2.4.0
-Requires-Dist: trio==0.30.0
-Requires-Dist: trio-websocket==0.12.2
-Requires-Dist: typing_extensions==4.14.0
-Requires-Dist: urllib3==2.4.0
-Requires-Dist: websocket-client==1.8.0
-Requires-Dist: wsproto==1.2.0
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
 <h1 align="center">Scythe</h1>
 
 <h2 align="center">
@@ -792,3 +745,79 @@ This architecture supports testing scenarios from simple security checks to comp
 ---
 
 **Scythe**: Comprehensive adverse conditions testing for robust, reliable systems.
+
+
+
+## Scythe CLI (embedded)
+
+Scythe now ships with a lightweight CLI that helps you bootstrap and manage your local Scythe testing workspace. After installing the package (pipx recommended), a `scythe` command is available.
+
+Note: The CLI is implemented with Typer, so `scythe --help` and per-command help (e.g., `scythe run --help`) are available. Command names and options remain the same as before.
+
+- Install with pipx:
+  - pipx install scythe-ttp
+- Or install locally in editable mode for development:
+  - pip install -e .
+
+### Commands
+
+- scythe init [--path PATH]
+  - Initializes a Scythe project at PATH (default: current directory).
+  - Creates:
+    - ./.scythe/scythe.db (SQLite DB with tests and runs tables)
+    - ./.scythe/scythe_tests/ (where your test scripts live)
+
+- scythe new <name>
+  - Creates a new test template at ./.scythe/scythe_tests/<name>.py and registers it in the DB (tests table).
+
+- scythe run <name or name.py>
+  - Runs the specified test from ./.scythe/scythe_tests and records the run into the DB (runs table). Exit code reflects success (0) or failure (non-zero).
+
+- scythe db dump
+  - Prints a JSON dump of the tests and runs tables from ./.scythe/scythe.db.
+
+- scythe db sync-compat <name>
+  - Reads COMPATIBLE_VERSIONS from ./.scythe/scythe_tests/<name>.py (if present) and updates the `tests.compatible_versions` field in the DB. If the variable is missing, the DB entry is set to empty and the command exits successfully.
+
+### Test template
+
+Created tests use a minimal template so you can start quickly:
+
+```python
+#!/usr/bin/env python3
+
+# scythe test initial template
+
+import argparse
+import os
+import sys
+import time
+from typing import List, Tuple
+
+# Scythe framework imports
+from scythe.core.executor import TTPExecutor
+from scythe.behaviors import HumanBehavior
+
+
+def scythe_test_definition(args):
+    # TODO: implement your test using Scythe primitives.
+    return True
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Scythe test script")
+    parser.add_argument('--url', help='Target URL (overridden by localhost unless FORCE_USE_CLI_URL=1)')
+    args = parser.parse_args()
+
+    ok = scythe_test_definition(args)
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()
+```
+
+Notes:
+- The CLI looks for tests in ./.scythe/scythe_tests.
+- Each `run` creates a record in the `runs` table with datetime, name_of_test, x_scythe_target_version (best-effort parsed from output), result, raw_output.
+- Each `new` creates a record in the `tests` table with name, path, created_date, compatible_versions.

scythe_ttp-0.14.0/VERSION

@@ -0,0 +1 @@
+0.15.0

scythe_ttp-0.14.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scythe-ttp"
+description = "An extensible framework for emulating attacker TTPs with Selenium."
+readme = {file = "README.md", content-type = "text/markdown"}
+authors = [{name = "EpykLab", email = "cyber@epyklab.com"}]
+requires-python = ">=3.8,<=3.13"
+version = "0.14.0"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Information Technology",
+  "Topic :: Security",
+  "Framework :: Pytest",
+]
+
+dependencies = [
+    "PySocks==1.7.1",
+    "attrs==25.3.0",
+    "certifi==2025.6.15",
+    "charset-normalizer==3.4.2",
+    "h11==0.16.0",
+    "idna==3.10",
+    "outcome==1.3.0.post0",
+    "pydantic-core==2.18.2",
+    "pydantic==2.7.1",
+    "requests==2.32.4",
+    "selenium==4.34.0",
+    "setuptools==80.9.0",
+    "sniffio==1.3.1",
+    "sortedcontainers==2.4.0",
+    "trio-websocket==0.12.2",
+    "trio==0.30.0",
+    "typing_extensions==4.14.0",
+    "urllib3==2.4.0",
+    "websocket-client==1.8.0",
+    "wsproto==1.2.0",
+    "typer"
+]
+
+[project.scripts]
+scythe = "scythe.cli.main:main"
+
+[tool.setuptools]
+# Use find_packages and exclude tests/examples from the distribution
+packages = {find = {exclude = ["tests*", "examples*"]}}
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+dependencies = {file = "requirements.txt"}

{scythe_ttp-0.12.4 → scythe_ttp-0.14.0}/requirements.txt

@@ -1,18 +1,22 @@
+PySocks==1.7.1
 attrs==25.3.0
 certifi==2025.6.15
 charset-normalizer==3.4.2
 h11==0.16.0
 idna==3.10
 outcome==1.3.0.post0
-PySocks==1.7.1
+pydantic-core==2.18.2
+pydantic==2.7.1
 requests==2.32.4
 selenium==4.34.0
 setuptools==80.9.0
 sniffio==1.3.1
 sortedcontainers==2.4.0
-trio==0.30.0
 trio-websocket==0.12.2
+trio==0.30.0
 typing_extensions==4.14.0
 urllib3==2.4.0
 websocket-client==1.8.0
 wsproto==1.2.0
+# CLI framework
+typer==0.12.5

{scythe_ttp-0.12.4 → scythe_ttp-0.14.0}/scythe/auth/__init__.py

@@ -8,9 +8,11 @@ authenticate before executing their main functionality.
 from .base import Authentication
 from .bearer import BearerTokenAuth
 from .basic import BasicAuth
+from .cookie_jwt import CookieJWTAuth
 
 __all__ = [
     'Authentication',
     'BearerTokenAuth', 
-    'BasicAuth'
+    'BasicAuth',
+    'CookieJWTAuth',
 ]

{scythe_ttp-0.12.4 → scythe_ttp-0.14.0}/scythe/auth/base.py

@@ -80,6 +80,15 @@ class Authentication(ABC):
         """
         return {}
     
+    def get_auth_cookies(self) -> Dict[str, str]:
+        """
+        Get authentication cookies that should be set for API requests.
+        
+        Returns:
+            Dictionary mapping cookie name to cookie value.
+        """
+        return {}
+    
     def store_auth_data(self, key: str, value: Any) -> None:
         """
         Store authentication-related data.

scythe_ttp-0.14.0/scythe/auth/cookie_jwt.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import time
+from typing import Dict, Optional, Any
+from urllib.parse import urlparse
+
+try:
+    import requests  # type: ignore
+except Exception:  # pragma: no cover - tests may run without requests installed
+    requests = None  # type: ignore
+from selenium.webdriver.remote.webdriver import WebDriver
+
+from .base import Authentication, AuthenticationError
+
+
+def _extract_by_dot_path(data: Any, path: str) -> Optional[Any]:
+    """
+    Extract a value from a nested dict/list structure using a simple dot path.
+    Supports numeric indices for lists, e.g., "data.items.0.token".
+    """
+    if not path:
+        return None
+    parts = path.split(".")
+    current: Any = data
+    for part in parts:
+        if isinstance(current, dict):
+            if part in current:
+                current = current[part]
+            else:
+                return None
+        elif isinstance(current, list):
+            try:
+                idx = int(part)
+            except ValueError:
+                return None
+            if idx < 0 or idx >= len(current):
+                return None
+            current = current[idx]
+        else:
+            return None
+    return current
+
+
+class CookieJWTAuth(Authentication):
+    """
+    Hybrid authentication where a JWT is acquired from an API login response and
+    then used as a cookie for subsequent requests. Useful when the target server
+    expects a cookie (e.g., "stellarbridge") instead of Authorization headers.
+    
+    Behavior:
+    - In API mode: JourneyExecutor will call get_auth_cookies(); this class will
+      perform a POST to login_url (if token not cached), parse JSON, extract the
+      token via jwt_json_path, and return {cookie_name: token}.
+    - In UI mode: authenticate() will ensure the browser has the cookie set for
+      the target domain.
+    """
+
+    def __init__(self,
+                 login_url: str,
+                 username: Optional[str] = None,
+                 password: Optional[str] = None,
+                 username_field: str = "email",
+                 password_field: str = "password",
+                 extra_fields: Optional[Dict[str, Any]] = None,
+                 jwt_json_path: str = "token",
+                 cookie_name: str = "stellarbridge",
+                 session: Optional[requests.Session] = None,
+                 description: str = "Authenticate via API and set JWT cookie"):
+        super().__init__(
+            name="Cookie JWT Authentication",
+            description=description
+        )
+        self.login_url = login_url
+        self.username = username
+        self.password = password
+        self.username_field = username_field
+        self.password_field = password_field
+        self.extra_fields = extra_fields or {}
+        self.jwt_json_path = jwt_json_path
+        self.cookie_name = cookie_name
+        # Avoid importing requests in test environments; allow injected session
+        self._session = session or (requests.Session() if requests is not None else None)
+        self.token: Optional[str] = None
+
+    def _login_and_get_token(self) -> str:
+        payload: Dict[str, Any] = dict(self.extra_fields)
+        if self.username is not None:
+            payload[self.username_field] = self.username
+        if self.password is not None:
+            payload[self.password_field] = self.password
+        try:
+            resp = self._session.post(self.login_url, json=payload, timeout=15)
+            # try json; raise on non-2xx to surface errors
+            resp.raise_for_status()
+            data = resp.json()
+        except Exception as e:
+            raise AuthenticationError(f"Login request failed: {e}", self.name)
+        token = _extract_by_dot_path(data, self.jwt_json_path)
+        if not token or not isinstance(token, str):
+            raise AuthenticationError(
+                f"JWT not found at path '{self.jwt_json_path}' in login response",
+                self.name,
+            )
+        self.token = token
+        self.store_auth_data('jwt', token)
+        self.store_auth_data('login_time', time.time())
+        return token
+
+    def get_auth_cookies(self) -> Dict[str, str]:
+        """
+        Return cookie mapping for API mode. Will perform login if token absent.
+        """
+        if not self.token:
+            self._login_and_get_token()
+        if not self.token:
+            return {}
+        return {self.cookie_name: self.token}
+
+    def get_auth_headers(self) -> Dict[str, str]:
+        """
+        For this hybrid approach, we typically do not use auth headers.
+        """
+        return {}
+
+    def authenticate(self, driver: WebDriver, target_url: str) -> bool:
+        """
+        UI path: ensure the cookie exists on the browser for the target domain.
+        Will perform the API login if token not yet acquired.
+        """
+        try:
+            if not self.token:
+                self._login_and_get_token()
+            if not self.token:
+                return False
+            # Navigate to the target domain base so cookie domain matches
+            parsed = urlparse(target_url)
+            base = f"{parsed.scheme}://{parsed.netloc}"
+            try:
+                driver.get(base)
+            except Exception:
+                pass
+            cookie_dict = {
+                'name': self.cookie_name,
+                'value': self.token,
+                'path': '/',
+            }
+            # If domain available, set explicitly to be safe
+            if parsed.netloc:
+                cookie_dict['domain'] = parsed.hostname or parsed.netloc
+            driver.add_cookie(cookie_dict)
+            self.authenticated = True
+            return True
+        except Exception as e:
+            raise AuthenticationError(f"Cookie auth failed: {e}", self.name)
+
+    def is_authenticated(self, driver: WebDriver) -> bool:
+        return self.authenticated and self.token is not None
+
+    def logout(self, driver: WebDriver) -> bool:
+        try:
+            self.token = None
+            self.authenticated = False
+            self.clear_auth_data()
+            # Best-effort cookie removal
+            try:
+                driver.delete_cookie(self.cookie_name)
+            except Exception:
+                pass
+            super().logout(driver)
+            return True
+        except Exception:
+            return False

scythe_ttp-0.14.0/scythe/cli/__init__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+__all__ = ["main"]