scythe-ttp 0.16.1__py3-none-any.whl → 0.18.1__py3-none-any.whl

scythe/auth/cookie_jwt.py

@@ -49,10 +49,17 @@ class CookieJWTAuth(Authentication):
     
     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}.
+      perform a POST to login_url (if token not cached), extract the token, and 
+      return {cookie_name: token}.
     - In UI mode: authenticate() will ensure the browser has the cookie set for
       the target domain.
+    
+    Parameters:
+    - content_type: Either "json" (default) to send payload as JSON, or "form" 
+      to send as application/x-www-form-urlencoded form data.
+    - jwt_source: Either "json" (default) to extract JWT from the JSON response body
+      using jwt_json_path, or "cookie" to extract it from the Set-Cookie response header
+      using cookie_name.
     """
 
     def __init__(self,
@@ -64,6 +71,8 @@ class CookieJWTAuth(Authentication):
                  extra_fields: Optional[Dict[str, Any]] = None,
                  jwt_json_path: str = "token",
                  cookie_name: str = "stellarbridge",
+                 content_type: str = "json",
+                 jwt_source: str = "json",
                  session: Optional[requests.Session] = None,
                  description: str = "Authenticate via API and set JWT cookie"):
         super().__init__(
@@ -78,29 +87,49 @@ class CookieJWTAuth(Authentication):
         self.extra_fields = extra_fields or {}
         self.jwt_json_path = jwt_json_path
         self.cookie_name = cookie_name
+        self.content_type = content_type
+        self.jwt_source = jwt_source
         # 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
+        payload[self.username_field] = self.username
+        payload[self.password_field] = self.password
         try:
-            resp = self._session.post(self.login_url, json=payload, timeout=15)
+            if self.content_type == "form":
+                resp = self._session.post(self.login_url, data=payload, timeout=15)
+            else:
+                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,
-            )
+        
+        # Extract token from either response cookies or JSON body
+        token = None
+        if self.jwt_source == "cookie":
+            # Extract from response cookies
+            token = resp.cookies.get(self.cookie_name)
+            if not token or not isinstance(token, str):
+                raise AuthenticationError(
+                    f"JWT cookie '{self.cookie_name}' not found in login response",
+                    self.name,
+                )
+        else:
+            # Extract from JSON response body
+            try:
+                data = resp.json()
+            except Exception as e:
+                raise AuthenticationError(f"Failed to parse JSON response: {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())

scythe/cli/main.py

@@ -65,10 +65,49 @@ def check_version_in_response_header(args) -> bool:
         return False
     return True
 
-def scythe_test_definition(args) -> bool:
+def scythe_test_definition(args) -> int:
     # TODO: implement your test using Scythe primitives.
     # Example placeholder that simply passes.
-    return True
+
+    # Example usage with TTPExecutor:
+    # from scythe.core.executor import TTPExecutor
+    # from scythe.ttps.web.login_bruteforce import LoginBruteforceTTP
+    #
+    # ttp = LoginBruteforceTTP(
+    #     payloads=['admin', 'root', 'test'],
+    #     expected_result=False  # Expect security controls to block attempts
+    # )
+    # executor = TTPExecutor(ttp=ttp, target_url=args.url)
+    # executor.run()
+    # return executor.was_successful()  # Returns True if all results matched expectations
+
+    # Example usage with JourneyExecutor:
+    # from scythe.journeys.executor import JourneyExecutor
+    # from scythe.journeys.base import Journey, Step
+    # from scythe.journeys.actions import NavigateAction, FillFormAction, ClickAction
+    #
+    # journey = Journey(
+    #     name="Login Journey",
+    #     description="Test user login flow",
+    #     expected_result=True  # Expect journey to succeed
+    # )
+    # journey.add_step(Step("Navigate").add_action(NavigateAction(url=args.url)))
+    # executor = JourneyExecutor(journey=journey, target_url=args.url)
+    # executor.run()
+    # return executor.was_successful()  # Returns True if journey succeeded as expected
+
+    # Example usage with Orchestrators:
+    # from scythe.orchestrators.scale import ScaleOrchestrator
+    # from scythe.orchestrators.base import OrchestrationStrategy
+    #
+    # orchestrator = ScaleOrchestrator(
+    #     strategy=OrchestrationStrategy.PARALLEL,
+    #     max_workers=10
+    # )
+    # result = orchestrator.orchestrate_ttp(ttp=my_ttp, target_url=args.url, replications=100)
+    # return orchestrator.exit_code(result) == 0  # Returns True if all executions succeeded
+
+    return executor.exit_code() # assumes executor var
 
 
 def main():
@@ -83,19 +122,151 @@ def main():
         dest='gate_versions',
         help='Gate versions to test against')
 
+    # Core Application Parameters
+    parser.add_argument(
+        '--protocol',
+        default='https',
+        choices=['http', 'https'],
+        help='Protocol to use (http/https, default: https)')
+    parser.add_argument(
+        '--port',
+        type=int,
+        help='Port number for the target application')
+
+    # Authentication Parameters
+    parser.add_argument(
+        '--username',
+        help='Username for authentication')
+    parser.add_argument(
+        '--password',
+        help='Password for authentication')
+    parser.add_argument(
+        '--token',
+        help='Bearer token or API key')
+    parser.add_argument(
+        '--auth-type',
+        choices=['basic', 'bearer', 'form'],
+        help='Authentication method (basic, bearer, form, etc.)')
+    parser.add_argument(
+        '--credentials-file',
+        help='Path to file containing multiple user credentials')
+
+    # Test Data Parameters
+    parser.add_argument(
+        '--users-file',
+        help='Path to CSV file containing user data')
+    parser.add_argument(
+        '--emails-file',
+        help='Path to text file containing email addresses')
+    parser.add_argument(
+        '--payload-file',
+        help='Path to file containing test payloads')
+    parser.add_argument(
+        '--data-file',
+        help='Generic path to test data file')
+
+    # Execution Control Parameters
+    parser.add_argument(
+        '--batch-size',
+        type=int,
+        default=10,
+        help='Number of operations per batch (default: 10)')
+    parser.add_argument(
+        '--max-batches',
+        type=int,
+        help='Maximum number of batches to run')
+    parser.add_argument(
+        '--workers',
+        type=int,
+        help='Number of concurrent workers/threads')
+    parser.add_argument(
+        '--replications',
+        type=int,
+        help='Number of test replications for load testing')
+    parser.add_argument(
+        '--timeout',
+        type=int,
+        help='Request timeout in seconds')
+    parser.add_argument(
+        '--delay',
+        type=float,
+        help='Delay between requests in seconds')
+
+    # Browser/Execution Parameters
+    parser.add_argument(
+        '--headless',
+        action='store_true',
+        help='Run browser in headless mode (flag)')
+    parser.add_argument(
+        '--browser',
+        choices=['chrome', 'firefox', 'safari', 'edge'],
+        help='Browser type (chrome, firefox, etc.)')
+    parser.add_argument(
+        '--user-agent',
+        help='Custom user agent string')
+    parser.add_argument(
+        '--proxy',
+        help='Proxy server URL')
+    parser.add_argument(
+        '--proxy-file',
+        help='Path to file containing proxy list')
+
+    # Output and Reporting Parameters
+    parser.add_argument(
+        '--output-dir',
+        help='Directory for output files')
+    parser.add_argument(
+        '--report-format',
+        choices=['json', 'csv', 'html'],
+        help='Report format (json, csv, html)')
+    parser.add_argument(
+        '--log-level',
+        choices=['debug', 'info', 'warning', 'error'],
+        help='Logging level (debug, info, warning, error)')
+    parser.add_argument(
+        '--verbose',
+        action='store_true',
+        help='Enable verbose output (flag)')
+    parser.add_argument(
+        '--silent',
+        action='store_true',
+        help='Suppress output except errors (flag)')
+
+    # Test Control Parameters
+    parser.add_argument(
+        '--fail-fast',
+        action='store_true',
+        help='Stop immediately on first failure (flag)')
+    parser.add_argument(
+        '--dry-run',
+        action='store_true',
+        help='Validate configuration without executing tests (flag)')
+    parser.add_argument(
+        '--test-type',
+        choices=['load', 'security', 'functional'],
+        help='Type of test to run (load, security, functional)')
+    parser.add_argument(
+        '--iterations',
+        type=int,
+        help='Number of test iterations')
+    parser.add_argument(
+        '--duration',
+        type=int,
+        help='Test duration in seconds')
+
     args = parser.parse_args()
 
     if check_url_available(args.url):
         if args.gate_versions:
             if check_version_in_response_header(args):
-                ok = scythe_test_definition(args)
-                sys.exit(0 if ok else 1)
+                exit_code = scythe_test_definition(args)
+                sys.exit(exit_code)
             else:
                 print("No compatible version found in response header.")
                 sys.exit(1)
         else:
-            ok = scythe_test_definition(args)
-            sys.exit(0 if ok else 1)
+            exit_code = scythe_test_definition(args)
+            sys.exit(exit_code)
     else:
         print("URL not available.")
         sys.exit(1)
@@ -109,6 +280,13 @@ class ScytheCLIError(Exception):
     pass
 
 
+class ExitWithCode(Exception):
+    """Exception to exit with a specific code from within Typer commands."""
+    def __init__(self, code: int):
+        self.code = code
+        super().__init__()
+
+
 def _find_project_root(start: Optional[str] = None) -> Optional[str]:
     """Walk upwards from start (or cwd) to find a directory containing .scythe."""
     cur = os.path.abspath(start or os.getcwd())
@@ -557,7 +735,10 @@ def main(argv: Optional[List[str]] = None) -> int:
         code, output, version = _run_test(project_root, name, extra)
         _record_run(project_root, name, code, output, version)
         print(output)
-        return code
+        # Raise exception to propagate exit code through Typer
+        if code != 0:
+            raise ExitWithCode(code)
+        return 0
 
     db_app = typer.Typer(
         no_args_is_help=True,
@@ -592,8 +773,10 @@ def main(argv: Optional[List[str]] = None) -> int:
     app.add_typer(db_app, name="db")
 
     try:
-        rv = app()
-        return int(rv) if isinstance(rv, int) else 0
+        app()
+        return 0
+    except ExitWithCode as e:
+        return e.code
     except ScytheCLIError as e:
         print(f"Error: {e}", file=sys.stderr)
         return 2

scythe/core/executor.py

@@ -3,9 +3,10 @@ import logging
 from selenium import webdriver
 from selenium.webdriver.chrome.options import Options
 from .ttp import TTP
-from typing import Optional
+from typing import Optional, Dict, Any
 from ..behaviors.base import Behavior
 from .headers import HeaderExtractor
+import requests
 
 # Configure logging
 logging.basicConfig(
@@ -40,6 +41,7 @@ class TTPExecutor:
         self.driver = None
         self.results = []
         self.header_extractor = HeaderExtractor()
+        self.has_test_failures = False  # Track if any test had unexpected results
 
     def _setup_driver(self):
         """Initializes the WebDriver."""
@@ -59,7 +61,18 @@ class TTPExecutor:
             self.logger.info(f"Using behavior: {self.behavior.name}")
             self.logger.info(f"Behavior description: {self.behavior.description}")
 
-        self._setup_driver()
+        # Check execution mode
+        if self.ttp.execution_mode == 'api':
+            self.logger.info("Execution mode: API")
+            self._run_api_mode()
+            return
+        else:
+            self.logger.info("Execution mode: UI")
+            self._setup_driver()
+            self._run_ui_mode()
+    
+    def _run_ui_mode(self):
+        """Execute TTP in UI mode using Selenium."""
 
         try:
             # Handle authentication if required
@@ -134,10 +147,12 @@ class TTPExecutor:
                         else:
                             version_info = f" | Version: {target_version}" if target_version else ""
                             self.logger.warning(f"UNEXPECTED SUCCESS: '{payload}' (expected to fail){version_info}")
+                            self.has_test_failures = True  # Mark as failure when result differs from expected
                     else:
                         consecutive_failures += 1
                         if self.ttp.expected_result:
                             self.logger.info(f"EXPECTED FAILURE: '{payload}' (security control working)")
+                            self.has_test_failures = True  # Mark as failure when result differs from expected
                         else:
                             self.logger.info(f"EXPECTED FAILURE: '{payload}'")
 
@@ -169,6 +184,108 @@ class TTPExecutor:
         finally:
             self._cleanup()
 
+    def _run_api_mode(self):
+        """Execute TTP in API mode using requests."""
+        session = requests.Session()
+        context: Dict[str, Any] = {
+            'target_url': self.target_url,
+            'auth_headers': {},
+            'rate_limit_resume_at': None
+        }
+        
+        try:
+            # Handle authentication if required (API mode)
+            if self.ttp.requires_authentication():
+                auth_name = self.ttp.authentication.name if self.ttp.authentication else "Unknown"
+                self.logger.info(f"Authentication required for TTP: {auth_name}")
+                
+                # Try to get auth headers directly
+                try:
+                    if hasattr(self.ttp.authentication, 'get_auth_headers'):
+                        auth_headers = self.ttp.authentication.get_auth_headers() or {}
+                        context['auth_headers'] = auth_headers
+                        session.headers.update(auth_headers)
+                        self.logger.info("Authentication headers applied")
+                except Exception as e:
+                    self.logger.warning(f"Failed to get auth headers: {e}")
+            
+            consecutive_failures = 0
+            
+            for i, payload in enumerate(self.ttp.get_payloads(), 1):
+                # Check if behavior wants to continue
+                if self.behavior and not self.behavior.should_continue(i, consecutive_failures):
+                    self.logger.info("Behavior requested to stop execution")
+                    break
+                
+                self.logger.info(f"Attempt {i}: Executing with payload -> '{payload}'")
+                
+                try:
+                    # Execute API request
+                    response = self.ttp.execute_step_api(session, payload, context)
+                    
+                    # Use behavior delay if available, otherwise use default
+                    if self.behavior:
+                        step_delay = self.behavior.get_step_delay(i)
+                    else:
+                        step_delay = self.delay
+                    
+                    time.sleep(step_delay)
+                    
+                    # Verify result
+                    success = self.ttp.verify_result_api(response, context)
+                    
+                    # Compare actual result with expected result
+                    if success:
+                        consecutive_failures = 0
+                        
+                        # Extract target version from response headers
+                        target_version = response.headers.get('X-SCYTHE-TARGET-VERSION') or response.headers.get('x-scythe-target-version')
+                        
+                        result_entry = {
+                            'payload': payload,
+                            'url': response.url if hasattr(response, 'url') else self.target_url,
+                            'expected': self.ttp.expected_result,
+                            'actual': True,
+                            'target_version': target_version
+                        }
+                        self.results.append(result_entry)
+                        
+                        if self.ttp.expected_result:
+                            version_info = f" | Version: {target_version}" if target_version else ""
+                            self.logger.info(f"EXPECTED SUCCESS: '{payload}'{version_info}")
+                        else:
+                            version_info = f" | Version: {target_version}" if target_version else ""
+                            self.logger.warning(f"UNEXPECTED SUCCESS: '{payload}' (expected to fail){version_info}")
+                            self.has_test_failures = True
+                    else:
+                        consecutive_failures += 1
+                        if self.ttp.expected_result:
+                            self.logger.info(f"EXPECTED FAILURE: '{payload}' (security control working)")
+                            self.has_test_failures = True
+                        else:
+                            self.logger.info(f"EXPECTED FAILURE: '{payload}'")
+                
+                except Exception as step_error:
+                    consecutive_failures += 1
+                    self.logger.error(f"Error during step {i}: {step_error}")
+                    
+                    # Let behavior handle the error
+                    if self.behavior:
+                        if not self.behavior.on_error(step_error, i):
+                            self.logger.info("Behavior requested to stop due to error")
+                            break
+                    else:
+                        # Default behavior: continue on most errors
+                        continue
+        
+        except KeyboardInterrupt:
+            self.logger.info("Test interrupted by user.")
+        except Exception as e:
+            self.logger.error(f"An unexpected error occurred: {e}", exc_info=True)
+        finally:
+            session.close()
+            self._cleanup()
+    
     def _cleanup(self):
         """Closes the WebDriver and prints a summary."""
         if self.driver:
@@ -212,3 +329,27 @@ class TTPExecutor:
                 self.logger.info("No successes detected (expected to find vulnerabilities).")
             else:
                 self.logger.info("No successes detected (security controls working as expected).")
+        
+        # Log overall test status
+        if self.has_test_failures:
+            self.logger.error("\n✗ TEST FAILED: One or more test results differed from expected")
+        else:
+            self.logger.info("\n✓ TEST PASSED: All test results matched expectations")
+    
+    def was_successful(self) -> bool:
+        """
+        Check if all test results matched expectations.
+        
+        Returns:
+            True if all test results matched expectations, False otherwise
+        """
+        return not self.has_test_failures
+    
+    def exit_code(self) -> int:
+        """
+        Get the exit code for this test execution.
+        
+        Returns:
+            0 if test was successful (results matched expectations), 1 otherwise
+        """
+        return 0 if self.was_successful() else 1

scythe/core/ttp.py

@@ -1,9 +1,10 @@
 from abc import ABC, abstractmethod
-from typing import Generator, Any, Optional, TYPE_CHECKING
+from typing import Generator, Any, Optional, TYPE_CHECKING, Dict
 from selenium.webdriver.remote.webdriver import WebDriver
 
 if TYPE_CHECKING:
     from ..auth.base import Authentication
+    import requests
 
 class TTP(ABC):
     """
@@ -11,9 +12,14 @@ class TTP(ABC):
 
     Each TTP implementation must define how to generate payloads, how to
     execute a test step with a given payload, and how to verify the outcome.
+    
+    TTPs can operate in two modes:
+    - 'ui': Uses Selenium WebDriver to interact with web UI (default)
+    - 'api': Uses requests library to interact directly with backend APIs
     """
 
-    def __init__(self, name: str, description: str, expected_result: bool = True, authentication: Optional['Authentication'] = None):
+    def __init__(self, name: str, description: str, expected_result: bool = True, 
+                 authentication: Optional['Authentication'] = None, execution_mode: str = 'ui'):
         """
         Initialize a TTP.
         
@@ -24,11 +30,13 @@ class TTP(ABC):
                            True means we expect to find vulnerabilities/success conditions.
                            False means we expect the security controls to prevent success.
             authentication: Optional authentication mechanism to use before executing TTP
+            execution_mode: Execution mode - 'ui' for Selenium-based UI testing or 'api' for direct API testing
         """
         self.name = name
         self.description = description
         self.expected_result = expected_result
         self.authentication = authentication
+        self.execution_mode = execution_mode.lower()
 
     @abstractmethod
     def get_payloads(self) -> Generator[Any, None, None]:
@@ -80,9 +88,59 @@ class TTP(ABC):
     @abstractmethod
     def verify_result(self, driver: WebDriver) -> bool:
         """
-        Verifies the outcome of the executed step.
+        Verifies the outcome of the executed step in UI mode.
 
         Returns:
             True if the test indicates a potential success/vulnerability, False otherwise.
         """
         pass
+    
+    def execute_step_api(self, session: 'requests.Session', payload: Any, context: Dict[str, Any]) -> 'requests.Response':
+        """
+        Executes a single test action using the provided payload via API request.
+        This method should be overridden by TTPs that support API mode.
+        
+        Args:
+            session: requests.Session instance for making HTTP requests
+            payload: The payload to use for this test iteration
+            context: Shared context dictionary for storing state and auth headers
+            
+        Returns:
+            requests.Response object from the API call
+            
+        Raises:
+            NotImplementedError: If the TTP does not support API mode
+        """
+        raise NotImplementedError(f"{self.name} does not support API execution mode")
+    
+    def verify_result_api(self, response: 'requests.Response', context: Dict[str, Any]) -> bool:
+        """
+        Verifies the outcome of the executed step in API mode.
+        This method should be overridden by TTPs that support API mode.
+        
+        Args:
+            response: The requests.Response object from execute_step_api
+            context: Shared context dictionary for accessing state
+            
+        Returns:
+            True if the test indicates a potential success/vulnerability, False otherwise
+            
+        Raises:
+            NotImplementedError: If the TTP does not support API mode
+        """
+        raise NotImplementedError(f"{self.name} does not support API result verification in API mode")
+    
+    def supports_api_mode(self) -> bool:
+        """
+        Check if this TTP implementation supports API execution mode.
+        
+        Returns:
+            True if API mode is supported, False otherwise
+        """
+        # Check if the TTP has overridden the API methods
+        try:
+            # Try to call the method on the class to see if it's been overridden
+            return (type(self).execute_step_api != TTP.execute_step_api or 
+                    type(self).verify_result_api != TTP.verify_result_api)
+        except Exception:
+            return False