| Name | scythe-ttp JSON |
| Version |
0.16.0
JSON |
| download |
| home_page | None |
| Summary | An extensible framework for emulating attacker TTPs with Selenium. |
| upload_time | 2025-09-17 18:32:54 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <=3.13,>=3.8 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h1 align="center">Scythe</h1>
<h2 align="center">
<img src="./assets/scythe.png" alt="scythe" width="200px">
<br>
</h2>
<h4 align="center">A comprehensive framework for adverse conditions testing</h4>
## Overview
Scythe is a powerful Python-based framework designed for testing applications under adverse conditions. Whether you're conducting security assessments, load testing, functional validation, or simulating real-world stress scenarios, Scythe provides the tools to comprehensively evaluate how your systems perform when faced with challenging conditions.
While security testing through Tactics, Techniques, and Procedures (TTPs) is a core capability, Scythe's scope extends far beyond traditional security assessments. It's built to handle any scenario where you need to test system resilience, validate expected behaviors under stress, or simulate complex user interactions at scale.
## Core Philosophy
Scythe operates on the principle that robust systems must be tested under adverse conditions to ensure they perform reliably in production. These conditions can include:
- **Security-focused adversarial testing**: Simulating attack patterns and malicious behavior
- **High-demand load testing**: Overwhelming systems with legitimate but intensive usage
- **Complex user workflow validation**: Multi-step processes under various conditions
- **Distributed testing scenarios**: Simulating global user bases and network conditions
- **Edge case exploration**: Testing boundary conditions and unusual usage patterns
- **Failure scenario simulation**: Understanding system behavior when components fail
## Key Capabilities
### π― **Comprehensive Testing Framework**
* **TTPs (Tactics, Techniques, Procedures)**: Security-focused testing with adversarial patterns
* **Journeys**: Multi-step workflow testing for complex user scenarios
* **Expected Results System**: Unit-testing-style validation with clear pass/fail criteria
* **Behavior Patterns**: Human, machine, and stealth execution patterns
* **Extensible Architecture**: Easy to add custom testing scenarios
### π **Authentication & Session Management**
* **Multiple Authentication Methods**: Basic auth, bearer tokens, custom mechanisms
* **Pre-execution Authentication**: Automatic login before test execution
* **Session State Management**: Maintain authentication across complex workflows
* **Multi-user Simulation**: Different credentials for distributed testing
### π **Scale & Distribution**
* **Concurrent Execution**: Run thousands of tests simultaneously
* **Geographic Distribution**: Execute tests from multiple network locations
* **Batch Processing**: Divide large test runs with intelligent retry logic
* **Resource Management**: Efficient distribution of credentials and network resources
* **Multiple Execution Strategies**: Sequential, parallel, and distributed patterns
### π **Professional Reporting**
* **Clear Result Indicators**: β Expected outcomes, β Unexpected results
* **Comprehensive Logging**: Detailed execution tracking and analysis
* **Version Detection**: Automatic extraction of X-SCYTHE-TARGET-VERSION headers
* **Performance Metrics**: Timing, success rates, and resource utilization
* **Execution Statistics**: Detailed reporting across all test types
## Use Cases
### Security Testing
Validate security controls and detection capabilities:
```python
# Test that brute force protection works
login_protection_test = LoginBruteforceTTP(
passwords=["password", "123456", "admin"],
expected_result=False, # Security should prevent this
authentication=admin_auth
)
```
### Load Testing
Assess system performance under high demand:
```python
# Simulate 1000 concurrent user registrations
registration_load_test = ScaleOrchestrator(
name="User Registration Load Test",
max_workers=50
)
result = registration_load_test.orchestrate_journey(
journey=user_registration_journey,
replications=1000
)
```
### Functional Validation
Test complex multi-step workflows:
```python
# Complete e-commerce purchase workflow
purchase_journey = Journey("E-commerce Purchase Flow")
purchase_journey.add_step(user_login_step)
purchase_journey.add_step(product_selection_step)
purchase_journey.add_step(checkout_process_step)
purchase_journey.add_step(payment_validation_step)
```
### Distributed Testing
Simulate global user base scenarios:
```python
# Test from multiple geographic locations
global_test = DistributedOrchestrator(
name="Global User Simulation",
proxies=worldwide_proxy_list,
credentials=regional_user_accounts
)
```
### Edge Case Testing
Explore boundary conditions and unusual scenarios:
```python
# Test file upload limits and edge cases
file_upload_ttp = FileUploadTTP(
files=["large_file.zip", "empty.txt", "special_chars_εε.pdf"],
expected_result=True, # Should handle various file types
size_limits_test=True
)
```
## Getting Started
### Prerequisites
- Python 3.8+
- Google Chrome browser
- Network access for target testing
### Installation
#### If you would like to use as a library:
setup the virtual environment
```bash
python3 -m venv venv
# source the venv
# bash,zsh: source venv/bin/activate
# fish: source venv/bin/activate.fish
```
install the package
```bash
# in an activated venv
pip3 install scythe-ttp
```
#### If you would like like to contribute:
1. Clone the repository:
```bash
git clone https://github.com/EpykLab/scythe.git
cd scythe
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Verify installation:
```bash
python -c "from scythe.core.ttp import TTP; print('β
Scythe installed successfully')"
```
## Quick Start Examples
### 1. Basic Security Testing
Test authentication controls with expected failure:
```python
from scythe.core.executor import TTPExecutor
from scythe.ttps.web.login_bruteforce import LoginBruteforceTTP
# Create a security test expecting controls to work
security_test = LoginBruteforceTTP(
username="admin",
passwords=["password", "123456", "admin"],
username_selector="#username",
password_selector="#password",
submit_selector="#submit",
expected_result=False # We EXPECT security to prevent this
)
executor = TTPExecutor(ttp=security_test, target_url="http://app.com/login")
executor.run()
```
### 2. Multi-Step Workflow Testing
Test complex user journeys:
```python
from scythe.journeys.base import Journey, Step
from scythe.journeys.actions import NavigateAction, FillFormAction, ClickAction, AssertAction
from scythe.journeys.executor import JourneyExecutor
# Create comprehensive workflow test
workflow_test = Journey(
name="User Onboarding Flow",
description="Complete new user registration and setup process"
)
# Step 1: Registration
registration_step = Step("User Registration", "Create new account")
registration_step.add_action(NavigateAction(url="http://app.com/register"))
registration_step.add_action(FillFormAction(field_data={
"#email": "test.user@example.com",
"#password": "SecurePassword123!",
"#confirm_password": "SecurePassword123!"
}))
registration_step.add_action(ClickAction(selector="#register-button"))
registration_step.add_action(AssertAction(
assertion_type="url_contains",
expected_value="verification"
))
# Step 2: Email Verification (simulated)
verification_step = Step("Email Verification", "Verify email address")
verification_step.add_action(NavigateAction(url="http://app.com/verify?token=test_token"))
verification_step.add_action(AssertAction(
assertion_type="page_contains",
expected_value="Email verified successfully"
))
# Step 3: Profile Setup
profile_step = Step("Profile Setup", "Complete user profile")
profile_step.add_action(NavigateAction(url="http://app.com/profile/setup"))
profile_step.add_action(FillFormAction(field_data={
"#first_name": "Test",
"#last_name": "User",
"#company": "Example Corp"
}))
profile_step.add_action(ClickAction(selector="#save-profile"))
workflow_test.add_step(registration_step)
workflow_test.add_step(verification_step)
workflow_test.add_step(profile_step)
# Execute the workflow
executor = JourneyExecutor(journey=workflow_test, target_url="http://app.com")
result = executor.run()
```
### 3. Load Testing at Scale
Stress test with concurrent users:
```python
from scythe.orchestrators.scale import ScaleOrchestrator
from scythe.orchestrators.base import OrchestrationStrategy
# Create high-concurrency load test
load_test = ScaleOrchestrator(
name="Application Load Test",
strategy=OrchestrationStrategy.PARALLEL,
max_workers=20,
ramp_up_delay=0.1 # Gradual ramp-up
)
# Simulate 500 concurrent users going through checkout process
result = load_test.orchestrate_journey(
journey=checkout_workflow,
target_url="http://app.com",
replications=500
)
print(f"Load Test Results:")
print(f" Total Users Simulated: {result.total_executions}")
print(f" Successful Completions: {result.successful_executions}")
print(f" Success Rate: {result.success_rate:.1f}%")
print(f" Average Response Time: {result.average_execution_time:.2f}s")
```
### 4. Global Distributed Testing
Test from multiple geographic locations:
```python
from scythe.orchestrators.distributed import DistributedOrchestrator, NetworkProxy, CredentialSet
# Define global testing infrastructure
global_proxies = [
NetworkProxy("US-West", proxy_url="proxy-us-west.example.com:8080", location="US-West"),
NetworkProxy("US-East", proxy_url="proxy-us-east.example.com:8080", location="US-East"),
NetworkProxy("EU-West", proxy_url="proxy-eu-west.example.com:8080", location="EU-West"),
NetworkProxy("Asia-Pacific", proxy_url="proxy-ap.example.com:8080", location="Asia-Pacific"),
NetworkProxy("South-America", proxy_url="proxy-sa.example.com:8080", location="South-America")
]
# Different user profiles for realistic testing
user_profiles = [
CredentialSet("premium_user", "premium@example.com", "PremiumPass123"),
CredentialSet("basic_user", "basic@example.com", "BasicPass123"),
CredentialSet("enterprise_user", "enterprise@example.com", "EnterprisePass123"),
CredentialSet("trial_user", "trial@example.com", "TrialPass123")
]
# Create distributed test orchestrator
global_test = DistributedOrchestrator(
name="Global Performance Assessment",
proxies=global_proxies,
credentials=user_profiles,
proxy_rotation_strategy="round_robin",
credential_rotation_strategy="random"
)
# Execute globally distributed test
result = global_test.orchestrate_journey(
journey=core_application_journey,
target_url="http://app.com",
replications=100 # Will be distributed across all locations and user types
)
print(f"Global Test Results:")
print(f" Locations Tested: {len(global_proxies)}")
print(f" User Profiles: {len(user_profiles)}")
print(f" Total Executions: {result.total_executions}")
print(f" Geographic Distribution: {result.metadata.get('distribution_stats', {})}")
```
### 5. Authenticated Complex Testing
Test workflows requiring authentication:
```python
from scythe.auth.basic import BasicAuth
from scythe.auth.bearer import BearerTokenAuth
# Basic web application authentication
web_auth = BasicAuth(
username="test_admin",
password="admin_password",
login_url="http://app.com/admin/login"
)
# API authentication for backend testing
api_auth = BearerTokenAuth(
token_url="http://api.app.com/auth/token",
username="api_user",
password="api_secret"
)
# Create authenticated security test
admin_security_test = PrivilegeEscalationTTP(
target_paths=["/admin/users", "/admin/settings", "/admin/logs"],
expected_result=False, # Should be prevented by access controls
authentication=web_auth
)
# Create authenticated API stress test
api_stress_test = APIEndpointTTP(
endpoints=["/api/users", "/api/reports", "/api/analytics"],
request_rate=100, # 100 requests per second
expected_result=True, # Should handle the load
authentication=api_auth
)
```
## Advanced Features
### Expected Results System
Scythe uses a unit-testing-style approach to define expected outcomes:
```python
# Security test - expecting controls to work (test should "fail")
security_ttp = SecurityTestTTP(
attack_vectors=["xss", "sqli", "csrf"],
expected_result=False # We EXPECT security to prevent these
)
# Performance test - expecting system to handle load (test should "pass")
performance_ttp = LoadTestTTP(
concurrent_users=1000,
expected_result=True # We EXPECT the system to handle this load
)
```
**Output Examples:**
- β **Expected Success**: System handled load as expected
- β **Unexpected Success**: Security vulnerability found (should have been blocked)
- β **Expected Failure**: Security controls working properly
- β **Unexpected Failure**: System failed under expected normal load
### Behavior Patterns
Control how tests execute with realistic behavior patterns:
```python
from scythe.behaviors import HumanBehavior, MachineBehavior, StealthBehavior
# Human-like testing (realistic user simulation)
human_behavior = HumanBehavior(
base_delay=2.0, # Natural pause between actions
delay_variance=1.0, # Variation in timing
typing_delay=0.1, # Realistic typing speed
error_probability=0.02 # Occasional user mistakes
)
# Machine testing (consistent, fast execution)
machine_behavior = MachineBehavior(
delay=0.3, # Fast, consistent timing
max_retries=5, # Systematic retry logic
fail_fast=True # Stop on critical errors
)
# Stealth testing (avoid detection/rate limiting)
stealth_behavior = StealthBehavior(
min_delay=5.0, # Longer delays
max_delay=15.0, # High variance
session_cooldown=60.0, # Breaks between sessions
max_requests_per_session=20 # Limit requests per session
)
# Apply behavior to any test
executor = TTPExecutor(
ttp=my_test,
target_url="http://app.com",
behavior=human_behavior # Use human-like timing
)
```
### Version Detection
Scythe automatically captures the `X-SCYTHE-TARGET-VERSION` header from HTTP responses to track which version of your web application is being tested:
```python
from scythe.core.ttp import TTP
from scythe.core.executor import TTPExecutor
# Your web application should set this header:
# X-SCYTHE-TARGET-VERSION: 1.3.2
class MyTTP(TTP):
def get_payloads(self):
yield "test_payload"
def execute_step(self, driver, payload):
driver.get("http://your-app.com/login")
# ... test logic ...
def verify_result(self, driver):
return "welcome" in driver.page_source
# Run the test
ttp = MyTTP("Version Test", "Test with version detection")
executor = TTPExecutor(ttp=ttp, target_url="http://your-app.com")
executor.run()
```
**Output includes version information:**
```
β EXPECTED SUCCESS: 'test_payload' | Version: 1.3.2
Target Version Summary:
Results with version info: 1/1
Version 1.3.2: 1 result(s)
```
**Server-side implementation examples:**
```python
# Python/Flask
@app.after_request
def add_version_header(response):
response.headers['X-SCYTHE-TARGET-VERSION'] = '1.3.2'
return response
# Node.js/Express
app.use((req, res, next) => {
res.set('X-SCYTHE-TARGET-VERSION', '1.3.2');
next();
});
# Java/Spring Boot
@Component
public class VersionHeaderFilter implements Filter {
@Override
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
HttpServletResponse httpResponse = (HttpServletResponse) response;
httpResponse.setHeader("X-SCYTHE-TARGET-VERSION", "1.3.2");
chain.doFilter(request, response);
}
}
```
This feature helps you:
- **Track test results** by application version
- **Verify deployment status** during testing
- **Correlate issues** with specific software versions
- **Ensure consistency** across test environments
### Custom Test Creation
Extend Scythe for specific testing needs:
```python
from scythe.core.ttp import TTP
from scythe.journeys.base import Action
from typing import Generator, Any
class CustomBusinessLogicTTP(TTP):
"""Test specific business logic under adverse conditions."""
def __init__(self, business_scenarios: list, expected_result: bool = True):
super().__init__(
name="Business Logic Test",
description="Test business logic edge cases",
expected_result=expected_result
)
self.scenarios = business_scenarios
def get_payloads(self) -> Generator[Any, None, None]:
for scenario in self.scenarios:
yield scenario
def execute_step(self, driver, payload):
# Implement your specific business logic testing
# This could involve API calls, database interactions, etc.
pass
def verify_result(self, driver) -> bool:
# Verify the business logic behaved correctly
return self.check_business_rules(driver)
class CustomWorkflowAction(Action):
"""Custom action for specific workflow steps."""
def __init__(self, workflow_step: str, parameters: dict):
super().__init__(f"Custom {workflow_step}", f"Execute {workflow_step}")
self.workflow_step = workflow_step
self.parameters = parameters
def execute(self, driver, context):
# Implement custom workflow logic
return self.perform_workflow_step(driver, context)
```
## Testing Scenarios
### E-commerce Platform Testing
```python
# Complete e-commerce stress test
ecommerce_suite = [
# Security testing
payment_security_test, # Test payment form security
user_data_protection_test, # Test PII protection
session_management_test, # Test session security
# Load testing
product_catalog_load_test, # High-traffic product browsing
checkout_process_load_test, # Concurrent checkout processes
search_functionality_test, # Search under load
# Workflow testing
complete_purchase_journey, # End-to-end purchase flow
return_process_journey, # Product return workflow
account_management_journey # User account operations
]
# Execute comprehensive test suite
orchestrator = ScaleOrchestrator(name="E-commerce Comprehensive Test")
for test in ecommerce_suite:
result = orchestrator.orchestrate_journey(test, target_url="http://shop.com")
print(f"{test.name}: {result.success_rate:.1f}% success rate")
```
### Financial Application Testing
```python
# High-security financial application testing
financial_test_suite = Journey("Financial Application Security Assessment")
# Multi-factor authentication testing
mfa_step = Step("MFA Security Test")
mfa_step.add_action(TTPAction(ttp=MFABypassTTP(expected_result=False)))
# Transaction integrity testing
transaction_step = Step("Transaction Integrity Test")
transaction_step.add_action(TTPAction(ttp=TransactionTamperingTTP(expected_result=False)))
# High-volume transaction testing
volume_step = Step("Transaction Volume Test")
volume_step.add_action(TTPAction(ttp=HighVolumeTransactionTTP(
transactions_per_second=1000,
expected_result=True # Should handle high volume
)))
financial_test_suite.add_step(mfa_step)
financial_test_suite.add_step(transaction_step)
financial_test_suite.add_step(volume_step)
```
### Healthcare System Testing
```python
# HIPAA-compliant healthcare system testing
healthcare_journey = Journey("Healthcare System Compliance Test")
# Patient data protection
data_protection_step = Step("Patient Data Protection")
data_protection_step.add_action(TTPAction(ttp=PatientDataAccessTTP(
expected_result=False # Unauthorized access should be blocked
)))
# System availability under load
availability_step = Step("System Availability Test")
availability_step.add_action(TTPAction(ttp=EmergencyLoadTTP(
concurrent_emergency_cases=500,
expected_result=True # System must remain available
)))
healthcare_journey.add_step(data_protection_step)
healthcare_journey.add_step(availability_step)
```
## Reporting and Analysis
### Comprehensive Result Analysis
```python
# Analyze test results
def analyze_test_results(orchestration_result):
print("="*60)
print("COMPREHENSIVE TEST ANALYSIS")
print("="*60)
print(f"Total Executions: {orchestration_result.total_executions}")
print(f"Success Rate: {orchestration_result.success_rate:.1f}%")
print(f"Average Execution Time: {orchestration_result.average_execution_time:.2f}s")
# Performance metrics
if orchestration_result.metadata.get('performance_stats'):
stats = orchestration_result.metadata['performance_stats']
print(f"Peak Response Time: {stats.get('peak_response_time', 'N/A')}")
print(f"95th Percentile: {stats.get('p95_response_time', 'N/A')}")
# Geographic distribution (if applicable)
if orchestration_result.metadata.get('distribution_stats'):
dist = orchestration_result.metadata['distribution_stats']
print("Geographic Distribution:")
for location, count in dist.get('location_usage', {}).items():
print(f" {location}: {count} executions")
# Error analysis
if orchestration_result.errors:
print(f"\nErrors Encountered: {len(orchestration_result.errors)}")
for i, error in enumerate(orchestration_result.errors[:5], 1):
print(f" {i}. {error}")
print("="*60)
# Use with any orchestration result
result = orchestrator.orchestrate_journey(test_journey, "http://app.com", replications=100)
analyze_test_results(result)
```
## Best Practices
### 1. Test Design Principles
- **Start with expected outcomes**: Define what success and failure look like
- **Use realistic data**: Test with data that represents real usage patterns
- **Consider edge cases**: Test boundary conditions and unusual scenarios
- **Plan for scale**: Design tests that can scale from single instances to thousands
### 2. Security Testing Guidelines
- **Test security controls**: Verify that protection mechanisms work as expected
- **Use safe environments**: Never test against production without explicit authorization
- **Document findings**: Clearly report both expected and unexpected results
- **Follow responsible disclosure**: Report vulnerabilities through proper channels
### 3. Load Testing Best Practices
- **Gradual ramp-up**: Increase load gradually to identify breaking points
- **Monitor resources**: Track CPU, memory, and network usage during tests
- **Test realistic scenarios**: Use actual user workflows, not just simple requests
- **Plan for cleanup**: Ensure test data doesn't impact production systems
### 4. Distributed Testing Considerations
- **Network latency**: Account for geographic differences in network performance
- **Time zones**: Consider when testing across global user bases
- **Legal compliance**: Ensure testing complies with local laws and regulations
- **Resource limits**: Respect proxy and network provider usage limits
## Contributing
We welcome contributions to Scythe! Whether you're adding new test types, improving orchestration capabilities, or enhancing documentation, your contributions help make Scythe better for everyone.
### How to Contribute
1. **Fork the repository** and create a feature branch
2. **Write tests** for new functionality
3. **Follow coding standards** and include documentation
4. **Submit a pull request** with a clear description of changes
### Areas for Contribution
- **New TTP implementations** for specific security tests
- **Additional Journey actions** for workflow testing
- **Custom orchestration strategies** for specialized scenarios
- **Enhanced reporting** and analysis capabilities
- **Integration adapters** for popular testing tools
- **Documentation improvements** and examples
## License
This project is licensed under the MIT License. See the `LICENSE` file for details.
## Architecture
Scythe's modular architecture enables flexible testing scenarios:
```
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β TTPs β β Journeys β β Orchestrators β
β β β β β β
β β’ Security Testsβ β β’ Multi-step β β β’ Scale Testing β
β β’ Logic Tests β β β’ Workflows β β β’ Distribution β
β β’ Edge Cases β β β’ User Stories β β β’ Batch Runs β
βββββββββββββββββββ βββββββββββββββββββ βββββββββββββββββββ
β β β
βββββββββββββββββββββββββΌββββββββββββββββββββββββ
β
βββββββββββββββββββ
β Core Engine β
β β
β β’ Execution β
β β’ Authenticationβ
β β’ Behaviors β
β β’ Reporting β
βββββββββββββββββββ
```
### Core Components
- **Core Engine**: Execution framework, authentication, and behavior management
- **TTPs**: Individual test procedures for specific scenarios
- **Journeys**: Multi-step workflows combining multiple actions
- **Orchestrators**: Scale and distribution management for large test runs
- **Behaviors**: Execution timing and pattern control
- **Authentication**: Session management and user simulation
- **Reporting**: Comprehensive result analysis and metrics
This architecture supports testing scenarios from simple security checks to complex, distributed, multi-user workflow validation at massive scale.
---
**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.
Raw data
{
"_id": null,
"home_page": null,
"name": "scythe-ttp",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.13,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "EpykLab <cyber@epyklab.com>",
"download_url": "https://files.pythonhosted.org/packages/cc/ad/bdaaa2d8fed44df1118daa71383c398a529318335383210999b654c791ff/scythe_ttp-0.16.0.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">Scythe</h1>\n\n<h2 align=\"center\">\n <img src=\"./assets/scythe.png\" alt=\"scythe\" width=\"200px\">\n <br>\n</h2>\n\n<h4 align=\"center\">A comprehensive framework for adverse conditions testing</h4>\n\n## Overview\n\nScythe is a powerful Python-based framework designed for testing applications under adverse conditions. Whether you're conducting security assessments, load testing, functional validation, or simulating real-world stress scenarios, Scythe provides the tools to comprehensively evaluate how your systems perform when faced with challenging conditions.\n\nWhile security testing through Tactics, Techniques, and Procedures (TTPs) is a core capability, Scythe's scope extends far beyond traditional security assessments. It's built to handle any scenario where you need to test system resilience, validate expected behaviors under stress, or simulate complex user interactions at scale.\n\n## Core Philosophy\n\nScythe operates on the principle that robust systems must be tested under adverse conditions to ensure they perform reliably in production. These conditions can include:\n\n- **Security-focused adversarial testing**: Simulating attack patterns and malicious behavior\n- **High-demand load testing**: Overwhelming systems with legitimate but intensive usage\n- **Complex user workflow validation**: Multi-step processes under various conditions\n- **Distributed testing scenarios**: Simulating global user bases and network conditions\n- **Edge case exploration**: Testing boundary conditions and unusual usage patterns\n- **Failure scenario simulation**: Understanding system behavior when components fail\n\n## Key Capabilities\n\n### \ud83c\udfaf **Comprehensive Testing Framework**\n* **TTPs (Tactics, Techniques, Procedures)**: Security-focused testing with adversarial patterns\n* **Journeys**: Multi-step workflow testing for complex user scenarios\n* **Expected Results System**: Unit-testing-style validation with clear pass/fail criteria\n* **Behavior Patterns**: Human, machine, and stealth execution patterns\n* **Extensible Architecture**: Easy to add custom testing scenarios\n\n### \ud83d\udd10 **Authentication & Session Management**\n* **Multiple Authentication Methods**: Basic auth, bearer tokens, custom mechanisms\n* **Pre-execution Authentication**: Automatic login before test execution\n* **Session State Management**: Maintain authentication across complex workflows\n* **Multi-user Simulation**: Different credentials for distributed testing\n\n### \ud83d\ude80 **Scale & Distribution**\n* **Concurrent Execution**: Run thousands of tests simultaneously\n* **Geographic Distribution**: Execute tests from multiple network locations\n* **Batch Processing**: Divide large test runs with intelligent retry logic\n* **Resource Management**: Efficient distribution of credentials and network resources\n* **Multiple Execution Strategies**: Sequential, parallel, and distributed patterns\n\n### \ud83d\udcca **Professional Reporting**\n* **Clear Result Indicators**: \u2713 Expected outcomes, \u2717 Unexpected results\n* **Comprehensive Logging**: Detailed execution tracking and analysis\n* **Version Detection**: Automatic extraction of X-SCYTHE-TARGET-VERSION headers\n* **Performance Metrics**: Timing, success rates, and resource utilization\n* **Execution Statistics**: Detailed reporting across all test types\n\n## Use Cases\n\n### Security Testing\nValidate security controls and detection capabilities:\n```python\n# Test that brute force protection works\nlogin_protection_test = LoginBruteforceTTP(\n passwords=[\"password\", \"123456\", \"admin\"],\n expected_result=False, # Security should prevent this\n authentication=admin_auth\n)\n```\n\n### Load Testing\nAssess system performance under high demand:\n```python\n# Simulate 1000 concurrent user registrations\nregistration_load_test = ScaleOrchestrator(\n name=\"User Registration Load Test\",\n max_workers=50\n)\nresult = registration_load_test.orchestrate_journey(\n journey=user_registration_journey,\n replications=1000\n)\n```\n\n### Functional Validation\nTest complex multi-step workflows:\n```python\n# Complete e-commerce purchase workflow\npurchase_journey = Journey(\"E-commerce Purchase Flow\")\npurchase_journey.add_step(user_login_step)\npurchase_journey.add_step(product_selection_step)\npurchase_journey.add_step(checkout_process_step)\npurchase_journey.add_step(payment_validation_step)\n```\n\n### Distributed Testing\nSimulate global user base scenarios:\n```python\n# Test from multiple geographic locations\nglobal_test = DistributedOrchestrator(\n name=\"Global User Simulation\",\n proxies=worldwide_proxy_list,\n credentials=regional_user_accounts\n)\n```\n\n### Edge Case Testing\nExplore boundary conditions and unusual scenarios:\n```python\n# Test file upload limits and edge cases\nfile_upload_ttp = FileUploadTTP(\n files=[\"large_file.zip\", \"empty.txt\", \"special_chars_\u540d\u524d.pdf\"],\n expected_result=True, # Should handle various file types\n size_limits_test=True\n)\n```\n\n## Getting Started\n\n### Prerequisites\n- Python 3.8+\n- Google Chrome browser\n- Network access for target testing\n\n### Installation\n\n#### If you would like to use as a library:\n\nsetup the virtual environment\n```bash\npython3 -m venv venv\n\n# source the venv\n# bash,zsh: source venv/bin/activate\n# fish: source venv/bin/activate.fish\n```\n\ninstall the package\n```bash\n# in an activated venv\n\npip3 install scythe-ttp\n```\n\n#### If you would like like to contribute:\n\n1. Clone the repository:\n ```bash\n git clone https://github.com/EpykLab/scythe.git\n cd scythe\n ```\n\n2. Install dependencies:\n ```bash\n pip install -r requirements.txt\n ```\n\n3. Verify installation:\n ```bash\n python -c \"from scythe.core.ttp import TTP; print('\u2705 Scythe installed successfully')\"\n ```\n\n## Quick Start Examples\n\n### 1. Basic Security Testing\n\nTest authentication controls with expected failure:\n\n```python\nfrom scythe.core.executor import TTPExecutor\nfrom scythe.ttps.web.login_bruteforce import LoginBruteforceTTP\n\n# Create a security test expecting controls to work\nsecurity_test = LoginBruteforceTTP(\n username=\"admin\",\n passwords=[\"password\", \"123456\", \"admin\"],\n username_selector=\"#username\",\n password_selector=\"#password\",\n submit_selector=\"#submit\",\n expected_result=False # We EXPECT security to prevent this\n)\n\nexecutor = TTPExecutor(ttp=security_test, target_url=\"http://app.com/login\")\nexecutor.run()\n```\n\n### 2. Multi-Step Workflow Testing\n\nTest complex user journeys:\n\n```python\nfrom scythe.journeys.base import Journey, Step\nfrom scythe.journeys.actions import NavigateAction, FillFormAction, ClickAction, AssertAction\nfrom scythe.journeys.executor import JourneyExecutor\n\n# Create comprehensive workflow test\nworkflow_test = Journey(\n name=\"User Onboarding Flow\",\n description=\"Complete new user registration and setup process\"\n)\n\n# Step 1: Registration\nregistration_step = Step(\"User Registration\", \"Create new account\")\nregistration_step.add_action(NavigateAction(url=\"http://app.com/register\"))\nregistration_step.add_action(FillFormAction(field_data={\n \"#email\": \"test.user@example.com\",\n \"#password\": \"SecurePassword123!\",\n \"#confirm_password\": \"SecurePassword123!\"\n}))\nregistration_step.add_action(ClickAction(selector=\"#register-button\"))\nregistration_step.add_action(AssertAction(\n assertion_type=\"url_contains\",\n expected_value=\"verification\"\n))\n\n# Step 2: Email Verification (simulated)\nverification_step = Step(\"Email Verification\", \"Verify email address\")\nverification_step.add_action(NavigateAction(url=\"http://app.com/verify?token=test_token\"))\nverification_step.add_action(AssertAction(\n assertion_type=\"page_contains\",\n expected_value=\"Email verified successfully\"\n))\n\n# Step 3: Profile Setup\nprofile_step = Step(\"Profile Setup\", \"Complete user profile\")\nprofile_step.add_action(NavigateAction(url=\"http://app.com/profile/setup\"))\nprofile_step.add_action(FillFormAction(field_data={\n \"#first_name\": \"Test\",\n \"#last_name\": \"User\",\n \"#company\": \"Example Corp\"\n}))\nprofile_step.add_action(ClickAction(selector=\"#save-profile\"))\n\nworkflow_test.add_step(registration_step)\nworkflow_test.add_step(verification_step)\nworkflow_test.add_step(profile_step)\n\n# Execute the workflow\nexecutor = JourneyExecutor(journey=workflow_test, target_url=\"http://app.com\")\nresult = executor.run()\n```\n\n### 3. Load Testing at Scale\n\nStress test with concurrent users:\n\n```python\nfrom scythe.orchestrators.scale import ScaleOrchestrator\nfrom scythe.orchestrators.base import OrchestrationStrategy\n\n# Create high-concurrency load test\nload_test = ScaleOrchestrator(\n name=\"Application Load Test\",\n strategy=OrchestrationStrategy.PARALLEL,\n max_workers=20,\n ramp_up_delay=0.1 # Gradual ramp-up\n)\n\n# Simulate 500 concurrent users going through checkout process\nresult = load_test.orchestrate_journey(\n journey=checkout_workflow,\n target_url=\"http://app.com\",\n replications=500\n)\n\nprint(f\"Load Test Results:\")\nprint(f\" Total Users Simulated: {result.total_executions}\")\nprint(f\" Successful Completions: {result.successful_executions}\")\nprint(f\" Success Rate: {result.success_rate:.1f}%\")\nprint(f\" Average Response Time: {result.average_execution_time:.2f}s\")\n```\n\n### 4. Global Distributed Testing\n\nTest from multiple geographic locations:\n\n```python\nfrom scythe.orchestrators.distributed import DistributedOrchestrator, NetworkProxy, CredentialSet\n\n# Define global testing infrastructure\nglobal_proxies = [\n NetworkProxy(\"US-West\", proxy_url=\"proxy-us-west.example.com:8080\", location=\"US-West\"),\n NetworkProxy(\"US-East\", proxy_url=\"proxy-us-east.example.com:8080\", location=\"US-East\"),\n NetworkProxy(\"EU-West\", proxy_url=\"proxy-eu-west.example.com:8080\", location=\"EU-West\"),\n NetworkProxy(\"Asia-Pacific\", proxy_url=\"proxy-ap.example.com:8080\", location=\"Asia-Pacific\"),\n NetworkProxy(\"South-America\", proxy_url=\"proxy-sa.example.com:8080\", location=\"South-America\")\n]\n\n# Different user profiles for realistic testing\nuser_profiles = [\n CredentialSet(\"premium_user\", \"premium@example.com\", \"PremiumPass123\"),\n CredentialSet(\"basic_user\", \"basic@example.com\", \"BasicPass123\"),\n CredentialSet(\"enterprise_user\", \"enterprise@example.com\", \"EnterprisePass123\"),\n CredentialSet(\"trial_user\", \"trial@example.com\", \"TrialPass123\")\n]\n\n# Create distributed test orchestrator\nglobal_test = DistributedOrchestrator(\n name=\"Global Performance Assessment\",\n proxies=global_proxies,\n credentials=user_profiles,\n proxy_rotation_strategy=\"round_robin\",\n credential_rotation_strategy=\"random\"\n)\n\n# Execute globally distributed test\nresult = global_test.orchestrate_journey(\n journey=core_application_journey,\n target_url=\"http://app.com\",\n replications=100 # Will be distributed across all locations and user types\n)\n\nprint(f\"Global Test Results:\")\nprint(f\" Locations Tested: {len(global_proxies)}\")\nprint(f\" User Profiles: {len(user_profiles)}\")\nprint(f\" Total Executions: {result.total_executions}\")\nprint(f\" Geographic Distribution: {result.metadata.get('distribution_stats', {})}\")\n```\n\n### 5. Authenticated Complex Testing\n\nTest workflows requiring authentication:\n\n```python\nfrom scythe.auth.basic import BasicAuth\nfrom scythe.auth.bearer import BearerTokenAuth\n\n# Basic web application authentication\nweb_auth = BasicAuth(\n username=\"test_admin\",\n password=\"admin_password\",\n login_url=\"http://app.com/admin/login\"\n)\n\n# API authentication for backend testing\napi_auth = BearerTokenAuth(\n token_url=\"http://api.app.com/auth/token\",\n username=\"api_user\",\n password=\"api_secret\"\n)\n\n# Create authenticated security test\nadmin_security_test = PrivilegeEscalationTTP(\n target_paths=[\"/admin/users\", \"/admin/settings\", \"/admin/logs\"],\n expected_result=False, # Should be prevented by access controls\n authentication=web_auth\n)\n\n# Create authenticated API stress test\napi_stress_test = APIEndpointTTP(\n endpoints=[\"/api/users\", \"/api/reports\", \"/api/analytics\"],\n request_rate=100, # 100 requests per second\n expected_result=True, # Should handle the load\n authentication=api_auth\n)\n```\n\n## Advanced Features\n\n### Expected Results System\n\nScythe uses a unit-testing-style approach to define expected outcomes:\n\n```python\n# Security test - expecting controls to work (test should \"fail\")\nsecurity_ttp = SecurityTestTTP(\n attack_vectors=[\"xss\", \"sqli\", \"csrf\"],\n expected_result=False # We EXPECT security to prevent these\n)\n\n# Performance test - expecting system to handle load (test should \"pass\")\nperformance_ttp = LoadTestTTP(\n concurrent_users=1000,\n expected_result=True # We EXPECT the system to handle this load\n)\n```\n\n**Output Examples:**\n- \u2713 **Expected Success**: System handled load as expected\n- \u2717 **Unexpected Success**: Security vulnerability found (should have been blocked)\n- \u2713 **Expected Failure**: Security controls working properly\n- \u2717 **Unexpected Failure**: System failed under expected normal load\n\n### Behavior Patterns\n\nControl how tests execute with realistic behavior patterns:\n\n```python\nfrom scythe.behaviors import HumanBehavior, MachineBehavior, StealthBehavior\n\n# Human-like testing (realistic user simulation)\nhuman_behavior = HumanBehavior(\n base_delay=2.0, # Natural pause between actions\n delay_variance=1.0, # Variation in timing\n typing_delay=0.1, # Realistic typing speed\n error_probability=0.02 # Occasional user mistakes\n)\n\n# Machine testing (consistent, fast execution)\nmachine_behavior = MachineBehavior(\n delay=0.3, # Fast, consistent timing\n max_retries=5, # Systematic retry logic\n fail_fast=True # Stop on critical errors\n)\n\n# Stealth testing (avoid detection/rate limiting)\nstealth_behavior = StealthBehavior(\n min_delay=5.0, # Longer delays\n max_delay=15.0, # High variance\n session_cooldown=60.0, # Breaks between sessions\n max_requests_per_session=20 # Limit requests per session\n)\n\n# Apply behavior to any test\nexecutor = TTPExecutor(\n ttp=my_test,\n target_url=\"http://app.com\",\n behavior=human_behavior # Use human-like timing\n)\n```\n\n### Version Detection\n\nScythe automatically captures the `X-SCYTHE-TARGET-VERSION` header from HTTP responses to track which version of your web application is being tested:\n\n```python\nfrom scythe.core.ttp import TTP\nfrom scythe.core.executor import TTPExecutor\n\n# Your web application should set this header:\n# X-SCYTHE-TARGET-VERSION: 1.3.2\n\nclass MyTTP(TTP):\n def get_payloads(self):\n yield \"test_payload\"\n\n def execute_step(self, driver, payload):\n driver.get(\"http://your-app.com/login\")\n # ... test logic ...\n\n def verify_result(self, driver):\n return \"welcome\" in driver.page_source\n\n# Run the test\nttp = MyTTP(\"Version Test\", \"Test with version detection\")\nexecutor = TTPExecutor(ttp=ttp, target_url=\"http://your-app.com\")\nexecutor.run()\n```\n\n**Output includes version information:**\n```\n\u2713 EXPECTED SUCCESS: 'test_payload' | Version: 1.3.2\nTarget Version Summary:\n Results with version info: 1/1\n Version 1.3.2: 1 result(s)\n```\n\n**Server-side implementation examples:**\n```python\n# Python/Flask\n@app.after_request\ndef add_version_header(response):\n response.headers['X-SCYTHE-TARGET-VERSION'] = '1.3.2'\n return response\n\n# Node.js/Express\napp.use((req, res, next) => {\n res.set('X-SCYTHE-TARGET-VERSION', '1.3.2');\n next();\n});\n\n# Java/Spring Boot\n@Component\npublic class VersionHeaderFilter implements Filter {\n @Override\n public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {\n HttpServletResponse httpResponse = (HttpServletResponse) response;\n httpResponse.setHeader(\"X-SCYTHE-TARGET-VERSION\", \"1.3.2\");\n chain.doFilter(request, response);\n }\n}\n```\n\nThis feature helps you:\n- **Track test results** by application version\n- **Verify deployment status** during testing\n- **Correlate issues** with specific software versions\n- **Ensure consistency** across test environments\n\n### Custom Test Creation\n\nExtend Scythe for specific testing needs:\n\n```python\nfrom scythe.core.ttp import TTP\nfrom scythe.journeys.base import Action\nfrom typing import Generator, Any\n\nclass CustomBusinessLogicTTP(TTP):\n \"\"\"Test specific business logic under adverse conditions.\"\"\"\n\n def __init__(self, business_scenarios: list, expected_result: bool = True):\n super().__init__(\n name=\"Business Logic Test\",\n description=\"Test business logic edge cases\",\n expected_result=expected_result\n )\n self.scenarios = business_scenarios\n\n def get_payloads(self) -> Generator[Any, None, None]:\n for scenario in self.scenarios:\n yield scenario\n\n def execute_step(self, driver, payload):\n # Implement your specific business logic testing\n # This could involve API calls, database interactions, etc.\n pass\n\n def verify_result(self, driver) -> bool:\n # Verify the business logic behaved correctly\n return self.check_business_rules(driver)\n\nclass CustomWorkflowAction(Action):\n \"\"\"Custom action for specific workflow steps.\"\"\"\n\n def __init__(self, workflow_step: str, parameters: dict):\n super().__init__(f\"Custom {workflow_step}\", f\"Execute {workflow_step}\")\n self.workflow_step = workflow_step\n self.parameters = parameters\n\n def execute(self, driver, context):\n # Implement custom workflow logic\n return self.perform_workflow_step(driver, context)\n```\n\n## Testing Scenarios\n\n### E-commerce Platform Testing\n\n```python\n# Complete e-commerce stress test\necommerce_suite = [\n # Security testing\n payment_security_test, # Test payment form security\n user_data_protection_test, # Test PII protection\n session_management_test, # Test session security\n\n # Load testing\n product_catalog_load_test, # High-traffic product browsing\n checkout_process_load_test, # Concurrent checkout processes\n search_functionality_test, # Search under load\n\n # Workflow testing\n complete_purchase_journey, # End-to-end purchase flow\n return_process_journey, # Product return workflow\n account_management_journey # User account operations\n]\n\n# Execute comprehensive test suite\norchestrator = ScaleOrchestrator(name=\"E-commerce Comprehensive Test\")\nfor test in ecommerce_suite:\n result = orchestrator.orchestrate_journey(test, target_url=\"http://shop.com\")\n print(f\"{test.name}: {result.success_rate:.1f}% success rate\")\n```\n\n### Financial Application Testing\n\n```python\n# High-security financial application testing\nfinancial_test_suite = Journey(\"Financial Application Security Assessment\")\n\n# Multi-factor authentication testing\nmfa_step = Step(\"MFA Security Test\")\nmfa_step.add_action(TTPAction(ttp=MFABypassTTP(expected_result=False)))\n\n# Transaction integrity testing\ntransaction_step = Step(\"Transaction Integrity Test\")\ntransaction_step.add_action(TTPAction(ttp=TransactionTamperingTTP(expected_result=False)))\n\n# High-volume transaction testing\nvolume_step = Step(\"Transaction Volume Test\")\nvolume_step.add_action(TTPAction(ttp=HighVolumeTransactionTTP(\n transactions_per_second=1000,\n expected_result=True # Should handle high volume\n)))\n\nfinancial_test_suite.add_step(mfa_step)\nfinancial_test_suite.add_step(transaction_step)\nfinancial_test_suite.add_step(volume_step)\n```\n\n### Healthcare System Testing\n\n```python\n# HIPAA-compliant healthcare system testing\nhealthcare_journey = Journey(\"Healthcare System Compliance Test\")\n\n# Patient data protection\ndata_protection_step = Step(\"Patient Data Protection\")\ndata_protection_step.add_action(TTPAction(ttp=PatientDataAccessTTP(\n expected_result=False # Unauthorized access should be blocked\n)))\n\n# System availability under load\navailability_step = Step(\"System Availability Test\")\navailability_step.add_action(TTPAction(ttp=EmergencyLoadTTP(\n concurrent_emergency_cases=500,\n expected_result=True # System must remain available\n)))\n\nhealthcare_journey.add_step(data_protection_step)\nhealthcare_journey.add_step(availability_step)\n```\n\n## Reporting and Analysis\n\n### Comprehensive Result Analysis\n\n```python\n# Analyze test results\ndef analyze_test_results(orchestration_result):\n print(\"=\"*60)\n print(\"COMPREHENSIVE TEST ANALYSIS\")\n print(\"=\"*60)\n\n print(f\"Total Executions: {orchestration_result.total_executions}\")\n print(f\"Success Rate: {orchestration_result.success_rate:.1f}%\")\n print(f\"Average Execution Time: {orchestration_result.average_execution_time:.2f}s\")\n\n # Performance metrics\n if orchestration_result.metadata.get('performance_stats'):\n stats = orchestration_result.metadata['performance_stats']\n print(f\"Peak Response Time: {stats.get('peak_response_time', 'N/A')}\")\n print(f\"95th Percentile: {stats.get('p95_response_time', 'N/A')}\")\n\n # Geographic distribution (if applicable)\n if orchestration_result.metadata.get('distribution_stats'):\n dist = orchestration_result.metadata['distribution_stats']\n print(\"Geographic Distribution:\")\n for location, count in dist.get('location_usage', {}).items():\n print(f\" {location}: {count} executions\")\n\n # Error analysis\n if orchestration_result.errors:\n print(f\"\\nErrors Encountered: {len(orchestration_result.errors)}\")\n for i, error in enumerate(orchestration_result.errors[:5], 1):\n print(f\" {i}. {error}\")\n\n print(\"=\"*60)\n\n# Use with any orchestration result\nresult = orchestrator.orchestrate_journey(test_journey, \"http://app.com\", replications=100)\nanalyze_test_results(result)\n```\n\n## Best Practices\n\n### 1. Test Design Principles\n\n- **Start with expected outcomes**: Define what success and failure look like\n- **Use realistic data**: Test with data that represents real usage patterns\n- **Consider edge cases**: Test boundary conditions and unusual scenarios\n- **Plan for scale**: Design tests that can scale from single instances to thousands\n\n### 2. Security Testing Guidelines\n\n- **Test security controls**: Verify that protection mechanisms work as expected\n- **Use safe environments**: Never test against production without explicit authorization\n- **Document findings**: Clearly report both expected and unexpected results\n- **Follow responsible disclosure**: Report vulnerabilities through proper channels\n\n### 3. Load Testing Best Practices\n\n- **Gradual ramp-up**: Increase load gradually to identify breaking points\n- **Monitor resources**: Track CPU, memory, and network usage during tests\n- **Test realistic scenarios**: Use actual user workflows, not just simple requests\n- **Plan for cleanup**: Ensure test data doesn't impact production systems\n\n### 4. Distributed Testing Considerations\n\n- **Network latency**: Account for geographic differences in network performance\n- **Time zones**: Consider when testing across global user bases\n- **Legal compliance**: Ensure testing complies with local laws and regulations\n- **Resource limits**: Respect proxy and network provider usage limits\n\n## Contributing\n\nWe welcome contributions to Scythe! Whether you're adding new test types, improving orchestration capabilities, or enhancing documentation, your contributions help make Scythe better for everyone.\n\n### How to Contribute\n\n1. **Fork the repository** and create a feature branch\n2. **Write tests** for new functionality\n3. **Follow coding standards** and include documentation\n4. **Submit a pull request** with a clear description of changes\n\n### Areas for Contribution\n\n- **New TTP implementations** for specific security tests\n- **Additional Journey actions** for workflow testing\n- **Custom orchestration strategies** for specialized scenarios\n- **Enhanced reporting** and analysis capabilities\n- **Integration adapters** for popular testing tools\n- **Documentation improvements** and examples\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n\n## Architecture\n\nScythe's modular architecture enables flexible testing scenarios:\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 TTPs \u2502 \u2502 Journeys \u2502 \u2502 Orchestrators \u2502\n\u2502 \u2502 \u2502 \u2502 \u2502 \u2502\n\u2502 \u2022 Security Tests\u2502 \u2502 \u2022 Multi-step \u2502 \u2502 \u2022 Scale Testing \u2502\n\u2502 \u2022 Logic Tests \u2502 \u2502 \u2022 Workflows \u2502 \u2502 \u2022 Distribution \u2502\n\u2502 \u2022 Edge Cases \u2502 \u2502 \u2022 User Stories \u2502 \u2502 \u2022 Batch Runs \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502 \u2502 \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502\n \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n \u2502 Core Engine \u2502\n \u2502 \u2502\n \u2502 \u2022 Execution \u2502\n \u2502 \u2022 Authentication\u2502\n \u2502 \u2022 Behaviors \u2502\n \u2502 \u2022 Reporting \u2502\n \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n```\n\n### Core Components\n\n- **Core Engine**: Execution framework, authentication, and behavior management\n- **TTPs**: Individual test procedures for specific scenarios\n- **Journeys**: Multi-step workflows combining multiple actions\n- **Orchestrators**: Scale and distribution management for large test runs\n- **Behaviors**: Execution timing and pattern control\n- **Authentication**: Session management and user simulation\n- **Reporting**: Comprehensive result analysis and metrics\n\nThis architecture supports testing scenarios from simple security checks to complex, distributed, multi-user workflow validation at massive scale.\n\n---\n\n**Scythe**: Comprehensive adverse conditions testing for robust, reliable systems.\n\n\n\n## Scythe CLI (embedded)\n\nScythe 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.\n\nNote: 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.\n\n- Install with pipx:\n - pipx install scythe-ttp\n- Or install locally in editable mode for development:\n - pip install -e .\n\n### Commands\n\n- scythe init [--path PATH]\n - Initializes a Scythe project at PATH (default: current directory).\n - Creates:\n - ./.scythe/scythe.db (SQLite DB with tests and runs tables)\n - ./.scythe/scythe_tests/ (where your test scripts live)\n\n- scythe new <name>\n - Creates a new test template at ./.scythe/scythe_tests/<name>.py and registers it in the DB (tests table).\n\n- scythe run <name or name.py>\n - 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).\n\n- scythe db dump\n - Prints a JSON dump of the tests and runs tables from ./.scythe/scythe.db.\n\n- scythe db sync-compat <name>\n - 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.\n\n### Test template\n\nCreated tests use a minimal template so you can start quickly:\n\n```python\n#!/usr/bin/env python3\n\n# scythe test initial template\n\nimport argparse\nimport os\nimport sys\nimport time\nfrom typing import List, Tuple\n\n# Scythe framework imports\nfrom scythe.core.executor import TTPExecutor\nfrom scythe.behaviors import HumanBehavior\n\n\ndef scythe_test_definition(args):\n # TODO: implement your test using Scythe primitives.\n return True\n\n\ndef main():\n parser = argparse.ArgumentParser(description=\"Scythe test script\")\n parser.add_argument('--url', help='Target URL (overridden by localhost unless FORCE_USE_CLI_URL=1)')\n args = parser.parse_args()\n\n ok = scythe_test_definition(args)\n sys.exit(0 if ok else 1)\n\n\nif __name__ == \"__main__\":\n main()\n```\n\nNotes:\n- The CLI looks for tests in ./.scythe/scythe_tests.\n- 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.\n- Each `new` creates a record in the `tests` table with name, path, created_date, compatible_versions.\n",
"bugtrack_url": null,
"license": null,
"summary": "An extensible framework for emulating attacker TTPs with Selenium.",
"version": "0.16.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5ab8b5b8319d13a52db1351d9bab202f5385ad6bcf1c979441ed8151ace5e169",
"md5": "017ac9d9693a6a52e37b4809d9824216",
"sha256": "ce38fa6fac149ebc66b1d58eff17b2af04f4662b8f6f017c5bf641e41fa3f326"
},
"downloads": -1,
"filename": "scythe_ttp-0.16.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "017ac9d9693a6a52e37b4809d9824216",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<=3.13,>=3.8",
"size": 84700,
"upload_time": "2025-09-17T18:32:52",
"upload_time_iso_8601": "2025-09-17T18:32:52.532558Z",
"url": "https://files.pythonhosted.org/packages/5a/b8/b5b8319d13a52db1351d9bab202f5385ad6bcf1c979441ed8151ace5e169/scythe_ttp-0.16.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ccadbdaaa2d8fed44df1118daa71383c398a529318335383210999b654c791ff",
"md5": "f4d0de5fb931ec6d6cc73abf00b770fa",
"sha256": "081cbebfa1a98c3b01f87a0206c3bd075fe9b097c9c9367657df4eb6610b8ea3"
},
"downloads": -1,
"filename": "scythe_ttp-0.16.0.tar.gz",
"has_sig": false,
"md5_digest": "f4d0de5fb931ec6d6cc73abf00b770fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.13,>=3.8",
"size": 98334,
"upload_time": "2025-09-17T18:32:54",
"upload_time_iso_8601": "2025-09-17T18:32:54.267394Z",
"url": "https://files.pythonhosted.org/packages/cc/ad/bdaaa2d8fed44df1118daa71383c398a529318335383210999b654c791ff/scythe_ttp-0.16.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-17 18:32:54",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "scythe-ttp"
}
