Package connpy
Connpy (v6.5.0b1)
Connpy is a powerful Connection Manager and Network Automation Platform for Linux, Mac, and Docker. It provides a unified interface for SSH, SFTP, Mosh, Telnet, kubectl, Docker pods, and AWS SSM.
The v6 release introduces a comprehensive AI Copilot and AI Playbook Engine, transforming your terminal into an interactive network assistant that understands your device outputs, configures parameters safely, and runs simulations.
1. π€ AI System
1a. Terminal Copilot (Ctrl+Space)
Invoke the context-aware AI Copilot directly inside any active terminal session by pressing Ctrl + Space.
* Context Modes: Cycles through LINES (sends raw scroll buffer), SINGLE (captures exactly one command + output block), and RANGE (logical group of recent commands) using Ctrl+Up/Down.
* Slash Commands (/): Control the AI persona, safety settings, and mission mode:
* /mission [objective]: Start an autonomous multi-step investigation mission with human approval.
* /cancel: Abort active mission.
* /architect / /engineer: Swaps the agent between high-level strategist and technical executor.
* /trust / /untrust: Configures auto-run behavior for suggested non-destructive commands.
* /os [system]: Manually overrides target OS parsing rules (e.g. /os cisco_ios).
* /prompt [regex]: Overrides command prompt detection bounds.
* /clear: Clear context history.
1b. AI Chat (conn ai)
Start a standalone persistent session with the AI Copilot. Manage sessions using --list, --resume, --session <id> (to restore a specific history), --delete <id>, or send a quick single-shot question directly from the terminal prompt:
conn ai "how do i check bgp summary on cisco?"
1c. MCP Integration (Client & Server)
Connect to external data sources and tools dynamically, or expose connpy as a native MCP server for external agents (Claude Desktop, Cursor, IDEs):
# MCP Client: Manage connected MCP servers
conn ai --mcp # Interactive configuration wizard
conn ai --mcp list # List configured MCP servers
conn ai --mcp add <name> <url> [os] # Add a remote SSE MCP server
# MCP Server: Serve connpy inventory, diagnostic tools, and playbooks
conn ai --mcp serve # Standard I/O mode (default, for local clients)
conn ai --mcp serve --sse --port 8080 # Remote SSE mode
conn ai --mcp serve --trust # Enable inventory mutations (CRUD) & configuration commands
1d. Local Interactive Shell (conn shell)
Launch a local interactive shell with AI Copilot support enabled directly on your host machine:
conn shell # Start local shell (default: $SHELL or /bin/bash)
conn shell -c /bin/zsh # Override shell executable
conn shell --capture session.log # Log session output to file
- Nested Sessions & Passthrough: Supports running nested
conn/connpyconnections insideconn shell. Automatically detects foregroundconnprocesses and forwardsCtrl+Spacedown to the active device connection instead of triggering the local Copilot. - Shell Configuration: Configure default shell command, prompt regex, or OS type via
conn config:
conn config --shell-command /bin/zsh
conn config --shell-prompt "\$\s*$"
conn config --shell-os ubuntu
2. βοΈ Automation & Playbooks
2a. Quick Run (conn run)
Run commands in parallel directly on target nodes or folder structures:
conn run router1 "show interface"
2b. YAML Playbook Engine
Execute complex structured automation playbooks defined in YAML configuration files. Supports multi-task execution, variables (using global, per-node, or regex matching definitions), timeouts, and variable parallel execution bounds.
# example_playbook.yaml
- name: Verify Network Operations
hosts: "@office"
parallel: true
tasks:
- name: Get interface brief
run: "show ip interface brief"
- name: Check OSPF state
run: "show ip ospf neighbor"
test: "FULL"
Execute using the playbooks runner:
conn run example_playbook.yaml
2c. AI-Assisted Automation
Leverage AI to generate playbook templates (--generate-ai), simulate command changes before execution (--preflight-ai), or analyze consolidated execution logs post-run (--analyze). Use --test "expected text1" "expected text2" to specify assert-style output validations.
* To generate an empty template: conn run --generate
3. π Inventory Management
3a. Nodes
Manage connections using standard commands: add (conn --add node1), edit (conn --mod node1), delete (conn --del node1), show configuration (conn --show node1), or connect (conn node1).
3b. Profiles
Define credentials and templates globally and reference them inside node fields using the @profile_name placeholder. Manage profiles interactively or via commands:
conn profile -a profile_name
# Or equivalently:
conn -a profile profile_name
During the interactive conn --add prompt, you can input @profile_name in the username or password fields to reference it.
3c. Folders, Move, Copy, List
Organize nodes into logical folder hierarchies (@office, @datacenter@office). Move items (conn move [src] [dst]), copy (conn copy [src] [dst]), or list items with custom filters and formatting:
conn list nodes --filter ".*-prod" --format "{name} ({host}) runs {protocol}"
3d. Bulk, Export, Import
Bulk import connections from formatted text files (conn bulk -f nodes.txt), or export/import connection folders using YAML configurations (conn export @folder > backup.yaml / conn import backup.yaml).
3e. Tags System
Customize connection settings dynamically using tags. Configure per-node settings like custom OS types (os), prompt regex rules (prompt), and page length triggers (screen_length_command).
# Custom tags dictionary (YANG / VSR context)
tags: { "os": "cisco_ios", "prompt": ".*#", "screen_length_command": "terminal length 0" }
3f. Credential Fallback Chain, compose: & Auth Budgets
Configure automatic backup credentials (fallback) on nodes or @profile templates so both interactive (conn <node>) and unattended (conn run / MCP) sessions switch seamlessly when primary TACACS+/AAA authentication fails (opt-out via tags.allow_fallback: false).
* Fallback Formats: Accepts @profile, explicit JSON list/dict entries ([{"user": "backup", "password": "..."}]), or compose: expressions. Nodes referencing multiple profiles inherit fallback with priority from user/password @profile references.
* Password Composition (compose:): Concatenate secrets and literals explicitly using compose:@prof1+@prof2+"suffix" (use @@ to escape leading literal @).
* Anti-Lockout Guardrails (conn config): Enforce strict attempt bounds via --max-auth-prompts, --max-total-auth-attempts, --max-hop-host-attempts, --max-global-user-attempts, and --disable-fallback-on-insecure-hostkey.
4. π Protocols & Connection Features
4a. SSH / SFTP / Mosh / Telnet / kubectl / Docker / AWS SSM
Connect to various architectures using native protocols:
* SSH / Telnet: Standard CLI protocols.
* Mosh: Mobile Shell with roaming and local echo support.
* SFTP: Transfer files securely (conn --sftp node).
* Docker: Connect directly to local container names (host set to container name/ID).
* Kubernetes (kubectl): Connect to pods (namespace customizable via options).
* AWS SSM: Connect to EC2 instances using Instance IDs as hosts.
4b. Jumphosts
Support for single or chained intermediate gateway nodes (SSH, Mosh, SSM, kubectl, or docker jumphosts) to tunnel traffic safely into target environments.
4c. Debug Mode, Keepalive, Logging
Track connection steps (conn --debug node), set idle keepalive intervals (conn config --keepalive <seconds>), or define dynamic output log files using variables like ${unique}, ${host}, ${port}, ${user}, ${protocol}, or ${date 'format'}.
4d. Adaptive Multi-Hop Timeouts
Differentiate --connect-timeout and --auth-timeout stages (conn run / conn config), automatically computing topological per-hop latency budgets for chained SSM and Jumphost tunnels with bounded progress extensions on slow handshakes.
5. π₯οΈ Remote Capture (conn capture - Core Plugin)
Perform remote packet capture (tcpdump) on hosts over secure SSH or Mosh reverse tunnels and stream packets live into your local Wireshark GUI:
conn capture router1 eth0 -w -f "port 80"
- Requirements: Local installation of Wireshark or
tsharkis required for live piping (-w). - Advanced flags: Specify network namespaces (
--ns <name>), custom filters (-f <filter>), or configure the Wireshark local path (--set-wireshark-path).
6. π‘οΈ Context Filtering
Prevent accidental command execution in production by setting active regex contexts. This hides non-matching inventory items and restricts execution scope:
conn context production -a --regex ".*-prod"
conn context production --set
- Manage Contexts: List defined filters (
conn context --ls), show context details (conn context production -s), or delete contexts (conn context production -r).
7. π Plugin System
Extend connpy features and hook into core execution events (pre/post hooks) by writing Python scripts. Add, update, delete, or list plugins locally, or execute them on remote instances:
conn plugin --add my_plugin script.py
conn plugin --update my_plugin script.py
conn plugin --remote --sync
8. βοΈ gRPC Client-Server Architecture
8a. Server (start/stop/restart/debug)
Execute tasks on a centralized remote host. Start gRPC server (conn api -s 50051), stop (conn api -x), restart (conn api -r), or debug in the foreground (conn api -d).
8b. Client Config
Shift the local CLI to communicate with a remote server instance:
conn config --service-mode remote
conn config --remote localhost:50051
8c. User Management & API Tokens
Manage server-side user credentials and Personal Access Tokens (PAT) for automated setups:
conn user --add username
conn user --list
conn user --regen-password username
# Personal Access Tokens (PAT) for non-interactive API access
conn user --create-token "CI/CD Token" --expires-in 30
conn user --list-tokens
conn user --revoke-token <token_id>
Use --path to specify custom configuration folders in server Mode B. Pass API tokens via CONNPY_TOKEN environment variable.
8d. SSO / OIDC
Configure identity providers (e.g. Authelia, Keycloak) for SSO gRPC authentication using the interactive wizard:
conn sso --add provider_name
8e. Login / Logout
Authenticate client sessions (conn login [username]), check connection status (conn login --status), or close sessions (conn logout).
9. β‘ Installation & Configuration
9a. pip install
pip install connpy
9b. Shell Completion + FZF
Install autocompletions and fuzzy-search wrappers into your shell profile:
eval "$(conn config --completion bash)"
eval "$(conn config --fzf-wrapper bash)"
9c. conn config options
View configuration details (conn config) or customize variables like case sensitivity (--allow-uppercase), FZF list picker (--fzf true), configurations directory (--configfolder), or persistent AI API keys and models (--engineer-model).
9d. Theming
Customize CLI panel styles and colors by pointing to built-in presets or external YAML styles:
conn config --theme /path/to/theme.yaml
10. π Privacy, Security & Synchronization (conn sync)
Encrypts inventory and profiles locally via RSA/OAEP. Backup and sync configurations to Google Drive manually (conn sync --once, --list, --restore) or schedule auto-sync. Segregate restores (--nodes / --config) or sync remote nodes with --sync-remote.
11. π Python API
Embed connection and automation routines programmatically in Python:
import connpy
# 1. Direct single node interaction
router = connpy.node("router1", "1.1.1.1", user="admin")
router.run(["show ip int brief"])
print(router.output)
# 2. Parallel nodes execution with variables
config = connpy.configfile()
nodes_info = config.getitem("@office", ["router1", "router2"])
routers = connpy.nodes(nodes_info, config=config)
variables = {
"router1@office": {"id": "1"},
"__global__": {"mask": "255.255.255.0"}
}
routers.run(["interface lo{id}", "ip address 10.0.0.{id} {mask}"], variables)
# 3. AI Copilot prompts
myai = connpy.ai(connpy.configfile())
response = myai.ask("Show BGP status.")
print(response)
Supports additional programmatic features like node.test(), node.interact(), configfile.encrypt(), connapp embeds, and ClassHook / MethodHook plugin hooks.
12. π³ Docker Deployment
Run connpy containerized and silent:
docker compose run --rm connpy-app [command]
Add alias conn='docker compose run --rm connpy-app' for a transparent container experience.
13. π License
Sub-modules
connpy.aiconnpy.auth_utils-
Pure authentication, composition, masking, sanitization, and rate-limit helpers.
connpy.cliconnpy.grpc_layerconnpy.mcp_clientconnpy.mcp_serverconnpy.protoconnpy.servicesconnpy.tunnelsconnpy.utils
Classes
class Plugins-
Expand source code
class Plugins: def __init__(self): self.plugins = {} self.plugin_parsers = {} self.preloads = {} self.remote_plugins = {} self.preferences = {} def _load_preferences(self, config_dir): import json path = os.path.join(config_dir, "plugin_preferences.json") try: with open(path) as f: self.preferences = json.load(f) except (FileNotFoundError, json.JSONDecodeError): self.preferences = {} def _save_preferences(self, config_dir): import json path = os.path.join(config_dir, "plugin_preferences.json") try: with open(path, "w") as f: json.dump(self.preferences, f, indent=4) except OSError as e: printer.error(f"Failed to save plugin preferences: {e}") def verify_script(self, file_path): """ Verifies that a given Python script meets specific structural requirements. This function checks a Python script for compliance with predefined structural rules. It ensures that the script contains only allowed top-level elements (functions, classes, imports, pass statements, and a specific if __name__ block) and that it includes mandatory classes with specific attributes and methods. ### Arguments: - file_path (str): The file path of the Python script to be verified. ### Returns: - str: A message indicating the type of violation if the script doesn't meet the requirements, or False if all requirements are met. ### Verifications: - The presence of only allowed top-level elements. - The existence of two specific classes: 'Parser' and 'Entrypoint'. and/or specific class: Preload. - 'Parser' class must only have an '__init__' method and must assign 'self.parser'. - 'Entrypoint' class must have an '__init__' method accepting specific arguments. If any of these checks fail, the function returns an error message indicating the reason. If the script passes all checks, the function returns False, indicating successful verification. ### Exceptions: - SyntaxError: If the script contains a syntax error, it is caught and returned as a part of the error message. """ with open(file_path, 'r') as file: source_code = file.read() try: tree = ast.parse(source_code) except SyntaxError as e: return f"Syntax error in file: {e}" has_parser = False has_entrypoint = False has_preload = False for node in tree.body: # Allow only function definitions, class definitions, and pass statements at top-level if isinstance(node, ast.If): # Check for the 'if __name__ == "__main__":' block if not (isinstance(node.test, ast.Compare) and isinstance(node.test.left, ast.Name) and node.test.left.id == '__name__' and ((hasattr(ast, 'Str') and isinstance(node.test.comparators[0], getattr(ast, 'Str')) and node.test.comparators[0].s == '__main__') or (hasattr(ast, 'Constant') and isinstance(node.test.comparators[0], getattr(ast, 'Constant')) and node.test.comparators[0].value == '__main__'))): return "Only __name__ == __main__ If is allowed" elif not isinstance(node, (ast.FunctionDef, ast.ClassDef, ast.Import, ast.ImportFrom, ast.Pass)): return f"Plugin can only have pass, functions, classes and imports. {node} is not allowed" # Reject any other AST types if isinstance(node, ast.ClassDef): if node.name == 'Parser': has_parser = True # Ensure Parser class has only the __init__ method and assigns self.parser if not all(isinstance(method, ast.FunctionDef) and method.name == '__init__' for method in node.body): return "Parser class should only have __init__ method" # Check if 'self.parser' is assigned in __init__ method init_method = node.body[0] assigned_attrs = [target.attr for expr in init_method.body if isinstance(expr, ast.Assign) for target in expr.targets if isinstance(target, ast.Attribute) and isinstance(target.value, ast.Name) and target.value.id == 'self'] if 'parser' not in assigned_attrs: return "Parser class should set self.parser" elif node.name == 'Entrypoint': has_entrypoint = True init_method = next((item for item in node.body if isinstance(item, ast.FunctionDef) and item.name == '__init__'), None) if not init_method or len(init_method.args.args) != 4: # self, args, parser, conapp return "Entrypoint class should have method __init__ and accept only arguments: args, parser and connapp" # 'Entrypoint' __init__ does not have correct signature elif node.name == 'Preload': has_preload = True init_method = next((item for item in node.body if isinstance(item, ast.FunctionDef) and item.name == '__init__'), None) if not init_method or len(init_method.args.args) != 2: # self, connapp return "Preload class should have method __init__ and accept only argument: connapp" # 'Preload' __init__ does not have correct signature # Applying the combination logic based on class presence if has_parser and not has_entrypoint: return "Parser requires Entrypoint class to be present." elif has_entrypoint and not has_parser: return "Entrypoint requires Parser class to be present." if not (has_parser or has_entrypoint or has_preload): return "No valid class (Parser, Entrypoint, or Preload) found." return False # All requirements met, no error def _import_from_path(self, path): spec = importlib.util.spec_from_file_location("module.name", path) module = importlib.util.module_from_spec(spec) sys.modules["module.name"] = module spec.loader.exec_module(module) return module def _import_plugins_to_argparse(self, directory, subparsers, remote_enabled=False): if not os.path.exists(directory): return for filename in os.listdir(directory): commands = subparsers.choices.keys() if filename.endswith(".py"): root_filename = os.path.splitext(filename)[0] if root_filename in commands: continue # Check preferences: if remote is preferred AND remote is enabled, skip local loading if remote_enabled and self.preferences.get(root_filename) == "remote": continue # Construct the full path filepath = os.path.join(directory, filename) check_file = self.verify_script(filepath) if check_file: printer.error(f"Failed to load plugin: {filename}. Reason: {check_file}") continue else: self.plugins[root_filename] = self._import_from_path(filepath) if hasattr(self.plugins[root_filename], "Parser"): self.plugin_parsers[root_filename] = self.plugins[root_filename].Parser() plugin = self.plugin_parsers[root_filename] # Default to RichHelpFormatter if plugin doesn't set one try: from rich_argparse import RichHelpFormatter as _RHF fmt = plugin.parser.formatter_class if fmt is argparse.HelpFormatter or fmt is argparse.RawTextHelpFormatter or fmt is argparse.RawDescriptionHelpFormatter: fmt = _RHF except ImportError: fmt = plugin.parser.formatter_class subparsers.add_parser(root_filename, parents=[self.plugin_parsers[root_filename].parser], add_help=False, help=plugin.parser.description, usage=plugin.parser.usage, description=plugin.parser.description, epilog=plugin.parser.epilog, formatter_class=fmt) if hasattr(self.plugins[root_filename], "Preload"): self.preloads[root_filename] = self.plugins[root_filename] def _import_remote_plugins_to_argparse(self, plugin_stub, subparsers, cache_dir, force_sync=False): import hashlib os.makedirs(cache_dir, exist_ok=True) try: remote_plugins_info = plugin_stub.list_plugins() except Exception: return # Pruning: Remove local cached files that are no longer on the server for local_file in os.listdir(cache_dir): if local_file.endswith(".py"): name = local_file[:-3] if name not in remote_plugins_info: try: os.remove(os.path.join(cache_dir, local_file)) except Exception: pass for name, info in remote_plugins_info.items(): if not info.get("enabled", True): continue pref = self.preferences.get(name, "local") if pref != "remote" and name in self.plugins: continue if not force_sync and name in subparsers.choices: continue cache_path = os.path.join(cache_dir, f"{name}.py") # Hash comparison remote_hash = info.get("hash", "") local_hash = "" if os.path.exists(cache_path): try: with open(cache_path, "rb") as f: local_hash = hashlib.md5(f.read()).hexdigest() except Exception: pass # Update only if hash differs or force_sync is True if force_sync or remote_hash != local_hash or not os.path.exists(cache_path): try: source = plugin_stub.get_plugin_source(name) with open(cache_path, "w") as f: f.write(source) except Exception as e: printer.warning(f"Failed to sync remote plugin {name}: {e}") continue # Verify and load check_file = self.verify_script(cache_path) if check_file: printer.warning(f"Remote plugin {name} failed verification: {check_file}") continue module = self._import_from_path(cache_path) if hasattr(module, "Parser"): self.plugin_parsers[name] = module.Parser() self.remote_plugins[name] = True plugin = self.plugin_parsers[name] try: from rich_argparse import RichHelpFormatter as _RHF fmt = plugin.parser.formatter_class if fmt is argparse.HelpFormatter or fmt is argparse.RawTextHelpFormatter or fmt is argparse.RawDescriptionHelpFormatter: fmt = _RHF except ImportError: fmt = plugin.parser.formatter_class # If force_sync, we might be re-registering, but argparse subparsers.add_parser # might fail if it exists. We check if it's already there. if name not in subparsers.choices: subparsers.add_parser( name, parents=[plugin.parser], add_help=False, help=f"[remote] {plugin.parser.description}", usage=plugin.parser.usage, description=plugin.parser.description, epilog=plugin.parser.epilog, formatter_class=fmt )Methods
def verify_script(self, file_path)-
Expand source code
def verify_script(self, file_path): """ Verifies that a given Python script meets specific structural requirements. This function checks a Python script for compliance with predefined structural rules. It ensures that the script contains only allowed top-level elements (functions, classes, imports, pass statements, and a specific if __name__ block) and that it includes mandatory classes with specific attributes and methods. ### Arguments: - file_path (str): The file path of the Python script to be verified. ### Returns: - str: A message indicating the type of violation if the script doesn't meet the requirements, or False if all requirements are met. ### Verifications: - The presence of only allowed top-level elements. - The existence of two specific classes: 'Parser' and 'Entrypoint'. and/or specific class: Preload. - 'Parser' class must only have an '__init__' method and must assign 'self.parser'. - 'Entrypoint' class must have an '__init__' method accepting specific arguments. If any of these checks fail, the function returns an error message indicating the reason. If the script passes all checks, the function returns False, indicating successful verification. ### Exceptions: - SyntaxError: If the script contains a syntax error, it is caught and returned as a part of the error message. """ with open(file_path, 'r') as file: source_code = file.read() try: tree = ast.parse(source_code) except SyntaxError as e: return f"Syntax error in file: {e}" has_parser = False has_entrypoint = False has_preload = False for node in tree.body: # Allow only function definitions, class definitions, and pass statements at top-level if isinstance(node, ast.If): # Check for the 'if __name__ == "__main__":' block if not (isinstance(node.test, ast.Compare) and isinstance(node.test.left, ast.Name) and node.test.left.id == '__name__' and ((hasattr(ast, 'Str') and isinstance(node.test.comparators[0], getattr(ast, 'Str')) and node.test.comparators[0].s == '__main__') or (hasattr(ast, 'Constant') and isinstance(node.test.comparators[0], getattr(ast, 'Constant')) and node.test.comparators[0].value == '__main__'))): return "Only __name__ == __main__ If is allowed" elif not isinstance(node, (ast.FunctionDef, ast.ClassDef, ast.Import, ast.ImportFrom, ast.Pass)): return f"Plugin can only have pass, functions, classes and imports. {node} is not allowed" # Reject any other AST types if isinstance(node, ast.ClassDef): if node.name == 'Parser': has_parser = True # Ensure Parser class has only the __init__ method and assigns self.parser if not all(isinstance(method, ast.FunctionDef) and method.name == '__init__' for method in node.body): return "Parser class should only have __init__ method" # Check if 'self.parser' is assigned in __init__ method init_method = node.body[0] assigned_attrs = [target.attr for expr in init_method.body if isinstance(expr, ast.Assign) for target in expr.targets if isinstance(target, ast.Attribute) and isinstance(target.value, ast.Name) and target.value.id == 'self'] if 'parser' not in assigned_attrs: return "Parser class should set self.parser" elif node.name == 'Entrypoint': has_entrypoint = True init_method = next((item for item in node.body if isinstance(item, ast.FunctionDef) and item.name == '__init__'), None) if not init_method or len(init_method.args.args) != 4: # self, args, parser, conapp return "Entrypoint class should have method __init__ and accept only arguments: args, parser and connapp" # 'Entrypoint' __init__ does not have correct signature elif node.name == 'Preload': has_preload = True init_method = next((item for item in node.body if isinstance(item, ast.FunctionDef) and item.name == '__init__'), None) if not init_method or len(init_method.args.args) != 2: # self, connapp return "Preload class should have method __init__ and accept only argument: connapp" # 'Preload' __init__ does not have correct signature # Applying the combination logic based on class presence if has_parser and not has_entrypoint: return "Parser requires Entrypoint class to be present." elif has_entrypoint and not has_parser: return "Entrypoint requires Parser class to be present." if not (has_parser or has_entrypoint or has_preload): return "No valid class (Parser, Entrypoint, or Preload) found." return False # All requirements met, no errorVerifies that a given Python script meets specific structural requirements.
This function checks a Python script for compliance with predefined structural rules. It ensures that the script contains only allowed top-level elements (functions, classes, imports, pass statements, and a specific if name block) and that it includes mandatory classes with specific attributes and methods.
Arguments:
- file_path (str): The file path of the Python script to be verified.Returns:
- str: A message indicating the type of violation if the script doesn't meet the requirements, or False if all requirements are met.Verifications:
- The presence of only allowed top-level elements. - The existence of two specific classes: 'Parser' and 'Entrypoint'. and/or specific class: Preload. - 'Parser' class must only have an '__init__' method and must assign 'self.parser'. - 'Entrypoint' class must have an '__init__' method accepting specific arguments.If any of these checks fail, the function returns an error message indicating the reason. If the script passes all checks, the function returns False, indicating successful verification.
Exceptions:
- SyntaxError: If the script contains a syntax error, it is caught and returned as a part of the error message.
class configfile (conf=None, key=None, shared_config=None)-
Expand source code
@ClassHook class configfile: ''' This class generates a configfile object. Containts a dictionary storing, config, nodes and profiles, normaly used by connection manager. ### Attributes: - file (str): Path/file to config file. - key (str): Path/file to RSA key file. - config (dict): Dictionary containing information of connection manager configuration. - connections (dict): Dictionary containing all the nodes added to connection manager. - profiles (dict): Dictionary containing all the profiles added to connection manager. - privatekey (obj): Object containing the private key to encrypt passwords. - publickey (obj): Object containing the public key to decrypt passwords. ''' def __init__(self, conf = None, key = None, shared_config = None): self._mutation_lock = threading.RLock() self._cache_dirty = False self._enforce_context = True self._shared_config = shared_config ''' ### Optional Parameters: - conf (str): Path/file to config file. If left empty default path is ~/.config/conn/config.yaml - key (str): Path/file to RSA key file. If left empty default path is ~/.config/conn/.osk ''' home = os.path.expanduser("~") defaultdir = home + '/.config/conn' if conf is None: # Standard path: use ~/.config/conn and respect .folder redirection self.anchor_path = defaultdir self.defaultdir = defaultdir Path(defaultdir).mkdir(parents=True, exist_ok=True) pathfile = defaultdir + '/.folder' try: with open(pathfile, "r") as f: configdir = f.read().strip() except (FileNotFoundError, IOError): with open(pathfile, "w") as f: f.write(str(defaultdir)) configdir = defaultdir self.defaultdir = configdir self.file = configdir + '/config.yaml' self.key = key or (configdir + '/.osk') # Ensure redirected directories exist Path(configdir).mkdir(parents=True, exist_ok=True) Path(f"{configdir}/plugins").mkdir(parents=True, exist_ok=True) # Backwards compatibility: Migrate from JSON to YAML only for default path legacy_json = configdir + '/config.json' legacy_noext = configdir + '/config' legacy_file = None if os.path.exists(legacy_json): legacy_file = legacy_json elif os.path.exists(legacy_noext): legacy_file = legacy_noext if not os.path.exists(self.file) and legacy_file: try: with open(legacy_file, 'r') as f: old_data = json.load(f) if not self._validate_config(old_data): printer.warning(f"Legacy config {legacy_file} has invalid structure, skipping migration.") else: with open(self.file, 'w') as f: yaml.dump(old_data, f, Dumper=NoAliasDumper, default_flow_style=False, sort_keys=False) # Verify the written YAML can be read back correctly with open(self.file, 'r') as f: verify = yaml.safe_load(f) if not self._validate_config(verify): os.remove(self.file) printer.warning("YAML verification failed after migration, keeping legacy config.") else: # Note: cachefile is derived later, we use temp one for migration sync temp_cache = configdir + '/.config.cache.json' with open(temp_cache, 'w') as f: json.dump(old_data, f) shutil.move(legacy_file, legacy_file + ".backup") printer.success(f"Migrated legacy config ({len(old_data.get('connections',{}))} folders/nodes) into YAML and Cache successfully!") except Exception as e: # noqa: BLE001 if os.path.exists(self.file): with suppress(OSError): os.remove(self.file) printer.warning(f"Failed to migrate legacy config: {e}") else: # Custom path (common in tests): isolate everything to the conf parent directory self.file = os.path.abspath(conf) configdir = os.path.dirname(self.file) self.anchor_path = configdir self.defaultdir = configdir self.key = os.path.abspath(key) if key else (configdir + '/.osk') # Sidecar files always live next to the config file (or in the redirected configdir) self.cachefile = configdir + '/.config.cache.json' self.fzf_cachefile = configdir + '/.fzf_nodes_cache.txt' self.folders_cachefile = configdir + '/.folders_cache.txt' self.profiles_cachefile = configdir + '/.profiles_cache.txt' if os.path.exists(self.file): config = self._loadconfig(self.file) else: config = self._createconfig(self.file) self.config = config["config"] self.connections = config["connections"] self.profiles = config["profiles"] self._privatekey_obj = None self._publickey_obj = None if not os.path.exists(self.key): self._createkey(self.key) # Self-heal text caches if they are missing if not os.path.exists(self.fzf_cachefile) or not os.path.exists(self.folders_cachefile) or not os.path.exists(self.profiles_cachefile): self._generate_nodes_cache() @property def privatekey(self): if getattr(self, '_privatekey_obj', None) is None: from Crypto.PublicKey import RSA if not os.path.exists(self.key): self._createkey(self.key) with open(self.key) as f: self._privatekey_obj = RSA.import_key(f.read()) return self._privatekey_obj @privatekey.setter def privatekey(self, value): self._privatekey_obj = value @property def publickey(self): if getattr(self, '_publickey_obj', None) is None: self._publickey_obj = self.privatekey.publickey() return self._publickey_obj @publickey.setter def publickey(self, value): self._publickey_obj = value def get_effective_setting(self, key, default=None): """Get config setting with shared fallback for inheritable keys.""" val = self.config.get(key) if key == "ai": if val is not None: if self._shared_config: import copy # Deep merge: shared as base, user overrides base = copy.deepcopy(self._shared_config.config.get(key, {})) if isinstance(base, dict) and isinstance(val, dict): # Credential isolation: # If user defines engineer credentials, discard shared ones if "engineer_api_key" in val or "engineer_auth" in val: base.pop("engineer_api_key", None) base.pop("engineer_auth", None) # If user defines architect credentials, discard shared ones if "architect_api_key" in val or "architect_auth" in val: base.pop("architect_api_key", None) base.pop("architect_auth", None) # Recursive update for inner dictionaries (like mcp_servers or model details) def deep_merge(d1, d2): for k, v in d2.items(): if isinstance(v, dict) and k in d1 and isinstance(d1[k], dict): deep_merge(d1[k], v) else: d1[k] = copy.deepcopy(v) deep_merge(base, val) return base return val elif self._shared_config: return self._shared_config.config.get(key, default) return val if val is not None else default def _validate_config_entry_unlocked(self, entry): """Strictly validate tags, fallback, and password compose syntax on a node or profile entry.""" if not isinstance(entry, dict): return if "tags" in entry and entry["tags"] not in ("", None): validate_auth_budget_tags(entry["tags"]) if "fallback" in entry and entry["fallback"] not in (None, "", []): validate_fallback_entries(entry["fallback"]) pw = entry.get("password") if is_compose_expression(pw): validate_compose_syntax(pw) elif isinstance(pw, (list, tuple)): for item in pw: if is_compose_expression(item): validate_compose_syntax(item) def _walk_connections_validate_unlocked(self, container): """Recursively validate all connection dicts inside nested folders/subfolders.""" if not isinstance(container, dict): raise TypeError("Connections container must be a dict") for key, val in container.items(): if key == "type" or not isinstance(val, dict): continue entry_type = val.get("type") if entry_type in ("folder", "subfolder"): self._walk_connections_validate_unlocked(val) else: self._validate_config_entry_unlocked(val) def _validate_config_strict(self, data): """Strictly validate config structure, budgets, and fallback rules; raises on error.""" if not isinstance(data, dict): raise TypeError("Config root must be a dict") required = {"config", "connections", "profiles"} if not required.issubset(data.keys()): raise ValueError("Config missing required sections") if not isinstance(data["config"], dict): raise TypeError("'config' section must be a dict") if not isinstance(data["connections"], dict): raise TypeError("'connections' section must be a dict") if not isinstance(data["profiles"], dict): raise TypeError("'profiles' section must be a dict") validate_config_auth_settings(data["config"]) self._walk_connections_validate_unlocked(data["connections"]) for prof_val in data["profiles"].values(): if not isinstance(prof_val, dict): raise TypeError("Each profile entry must be a dict") self._validate_config_entry_unlocked(prof_val) def _validate_config(self, data): """Verify config data has the required structure.""" try: self._validate_config_strict(data) except (ValueError, TypeError, SanitizedAuthError): return False return True def _atomic_write_text_unlocked(self, target_path, writer): """Atomically write text file with symlink refusal, 0o600 mode, fsync, and os.replace.""" if os.path.islink(target_path): raise OSError(f"Refusing to write through symlink: {target_path}") target_dir = os.path.dirname(os.path.abspath(target_path)) or "." os.makedirs(target_dir, exist_ok=True) fd, tmp_path = tempfile.mkstemp( dir=target_dir, prefix=f".{os.path.basename(target_path)}.", suffix=".tmp", ) try: with os.fdopen(fd, "w", encoding="utf-8") as f: writer(f) f.flush() os.fsync(f.fileno()) os.chmod(tmp_path, 0o600) os.replace(tmp_path, target_path) except BaseException: with suppress(OSError): os.unlink(tmp_path) raise def _fsync_dir_nonfatal(self, file_path): target_dir = os.path.dirname(os.path.abspath(file_path)) or "." try: dir_fd = os.open(target_dir, os.O_RDONLY) except OSError: return try: os.fsync(dir_fd) except OSError: return finally: with suppress(OSError): os.close(dir_fd) def _loadconfig(self, conf): #Loads config file using dual cache cache_exists = os.path.exists(self.cachefile) yaml_time = os.path.getmtime(conf) if os.path.exists(conf) else 0 cache_time = os.path.getmtime(self.cachefile) if cache_exists else 0 if not cache_exists or yaml_time > cache_time: with open(conf, 'r') as f: data = yaml.safe_load(f) if not self._validate_config(data): # YAML is broken, try to recover from cache if cache_exists: printer.warning("Config file appears corrupt, recovering from cache...") with open(self.cachefile, 'r') as f: data = json.load(f) if self._validate_config(data): # Re-write the YAML from good cache with suppress(OSError): self._atomic_write_text_unlocked( conf, lambda fp: yaml.dump( data, fp, Dumper=NoAliasDumper, default_flow_style=False, sort_keys=False, ), ) return data # Both broken or no cache - create fresh printer.error("Config file is corrupt and no valid cache exists. Creating default config.") return self._createconfig(conf) with suppress(OSError, TypeError, ValueError): self._atomic_write_text_unlocked(self.cachefile, lambda fp: json.dump(data, fp)) return data else: with open(self.cachefile, 'r') as f: data = json.load(f) if not self._validate_config(data): # Cache broken, try yaml with open(conf, 'r') as f: data = yaml.safe_load(f) if self._validate_config(data): return data # Both broken printer.error("Both config and cache are corrupt. Creating default config.") return self._createconfig(conf) return data def _createconfig(self, conf): #Create config file (always writes defaults, safe for recovery) defaultconfig = {'config': {'case': False, 'idletime': 30, 'fzf': False}, 'connections': {}, 'profiles': { "default": { "host":"", "protocol":"ssh", "port":"", "user":"", "password":"", "options":"", "logs":"", "tags": "", "jumphost":"", "fallback": ""}}} self._atomic_write_text_unlocked( conf, lambda f: yaml.dump(defaultconfig, f, Dumper=NoAliasDumper, default_flow_style=False, sort_keys=False), ) with suppress(OSError, TypeError, ValueError): self._atomic_write_text_unlocked(self.cachefile, lambda f: json.dump(defaultconfig, f)) return defaultconfig def _saveconfig_unlocked(self, conf, *, _raise_on_error=False): # Save config file atomically inside _mutation_lock without invoking hooks or printer newconfig = { "config": self.config, "connections": self.connections, "profiles": self.profiles, } try: self._atomic_write_text_unlocked( conf, lambda f: yaml.dump( newconfig, f, Dumper=NoAliasDumper, default_flow_style=False, sort_keys=False, ), ) except (OSError, TypeError, yaml.YAMLError) as e: if _raise_on_error: raise return 1, f"Failed to save config: {e}" # YAML is safely committed on disk; fsync dir and sidecar caches are non-fatal self._fsync_dir_nonfatal(conf) try: self._atomic_write_text_unlocked(self.cachefile, lambda f: json.dump(newconfig, f)) self._cache_dirty = False if self._is_context_filtering_enabled_unlocked(): self._generate_nodes_cache_unlocked(_raise_on_error=True) except (OSError, TypeError, ValueError): self._cache_dirty = True return 0, None def _run_saveconfig_post_hooks(self, conf, result): """Run @MethodHook post-hooks registered for _saveconfig outside _mutation_lock.""" cls_desc = type(self).__dict__.get("_saveconfig") cls_post = list(cls_desc.post_hooks) if isinstance(cls_desc, MethodHook) else [] inst_post = ( self.__dict__.get("_method_post_hooks", {}).get("_saveconfig", []) if isinstance(self.__dict__.get("_method_post_hooks"), dict) else [] ) all_post = cls_post + [h for h in inst_post if h not in cls_post] for hook in all_post: try: result = hook(self, conf, result=result) except Exception as e: # noqa: BLE001 hook_name = getattr(hook, "__name__", str(hook)) printer.error(f"_saveconfig Post-hook {hook_name} raised an exception: {e}") return result @MethodHook def _saveconfig(self, conf): #Save config file atomically to prevent corruption with self._mutation_lock: rc, err_msg = self._saveconfig_unlocked(conf, _raise_on_error=False) if err_msg: printer.error(err_msg) return rc def transactional_update(self, mutator): """Run mutator atomically inside _mutation_lock with in-place RAM rollback on error.""" save_desc = type(self).__dict__.get("_saveconfig") mocked_save = "_saveconfig" in self.__dict__ or not isinstance(save_desc, MethodHook) with self._mutation_lock: snap_config = deepcopy(self.config) snap_connections = deepcopy(self.connections) snap_profiles = deepcopy(self.profiles) try: result = mutator(self) self._validate_config_strict( { "config": self.config, "connections": self.connections, "profiles": self.profiles, } ) if mocked_save: rc = self._saveconfig(self.file) if rc != 0: raise OSError("Failed to save config") else: self._saveconfig_unlocked(self.file, _raise_on_error=True) except BaseException: self.config.clear() self.config.update(snap_config) self.connections.clear() self.connections.update(snap_connections) self.profiles.clear() self.profiles.update(snap_profiles) raise if not mocked_save: self._run_saveconfig_post_hooks(self.file, 0) return result def refresh_cache(self): """Rebuild JSON and fzf sidecar caches atomically; returns True on success.""" with self._mutation_lock: snapshot = { "config": self.config, "connections": self.connections, "profiles": self.profiles, } try: self._atomic_write_text_unlocked(self.cachefile, lambda f: json.dump(snapshot, f)) self._generate_nodes_cache_unlocked(_raise_on_error=True) self._cache_dirty = False return True except (OSError, TypeError, ValueError): self._cache_dirty = True return False def _is_context_filtering_enabled_unlocked(self) -> bool: if not getattr(self, "_enforce_context", True): return False return not (len(sys.argv) > 1 and sys.argv[1] == "api") def _filter_by_active_context_unlocked(self, items: list[str]) -> tuple[list[str], bool]: if not self._is_context_filtering_enabled_unlocked() or is_default_all_context_cfg( self.config ): return (list(items), False) patterns, had_err = compile_active_context_patterns_with_status(self.config) return ([i for i in items if match_active_context_patterns(i, patterns)], had_err) def _generate_nodes_cache_unlocked(self, nodes=None, folders=None, profiles=None, *, _raise_on_error=False): try: raw_nodes = self._getallnodes_unlocked() if nodes is None else list(nodes) raw_folders = self._getallfolders_unlocked() if folders is None else list(folders) nodes, err_n = self._filter_by_active_context_unlocked(raw_nodes) folders, err_f = self._filter_by_active_context_unlocked(raw_folders) if profiles is None: profiles = list(self.profiles.keys()) self._atomic_write_text_unlocked(self.fzf_cachefile, lambda f: f.write("\n".join(nodes))) self._atomic_write_text_unlocked(self.folders_cachefile, lambda f: f.write("\n".join(folders))) self._atomic_write_text_unlocked(self.profiles_cachefile, lambda f: f.write("\n".join(profiles))) if err_n or err_f: self._cache_dirty = True except (OSError, TypeError, ValueError): if _raise_on_error: raise self._cache_dirty = True def _generate_nodes_cache(self, nodes=None, folders=None, profiles=None): with self._mutation_lock: self._generate_nodes_cache_unlocked( nodes=nodes, folders=folders, profiles=profiles, _raise_on_error=False, ) def _createkey(self, keyfile): #Create key file from Crypto.PublicKey import RSA key = RSA.generate(2048) with open(keyfile,'wb') as f: f.write(key.export_key('PEM')) f.close() os.chmod(keyfile, 0o600) return key def _explode_unique_unlocked(self, unique): #Divide unique name into folder, subfolder and id uniques = unique.split("@") if not unique.startswith("@"): result = {"id": uniques[0]} else: result = {} if len(uniques) == 2: result["folder"] = uniques[1] if result["folder"] == "": return False elif len(uniques) == 3: result["folder"] = uniques[2] result["subfolder"] = uniques[1] if result["folder"] == "" or result["subfolder"] == "": return False elif len(uniques) > 3: return False return result @MethodHook def _explode_unique(self, unique): return self._explode_unique_unlocked(unique) def _resolve_profile_attr_unlocked(self, prof_name, key, *, depth=0, visited=frozenset()): if prof_name in visited or depth >= 5: return None prof = self.profiles.get(prof_name) if not isinstance(prof, dict) or key not in prof: return None val = prof[key] if key == "password": if isinstance(val, str): if is_compose_expression(val): return val if val.startswith("@") and val[1:] in self.profiles: sub = self._resolve_profile_attr_unlocked( val[1:], key, depth=depth + 1, visited=visited | {prof_name}, ) return sub if sub is not None else val return val if isinstance(val, list): resolved_list = [] for item in val: if ( isinstance(item, str) and not is_compose_expression(item) and item.startswith("@") and item[1:] in self.profiles ): sub = self._resolve_profile_attr_unlocked( item[1:], "password", depth=depth + 1, visited=visited | {prof_name}, ) if isinstance(sub, list): resolved_list.extend(deepcopy(sub)) elif sub is not None: resolved_list.append(deepcopy(sub)) else: resolved_list.append(item) else: resolved_list.append(deepcopy(item)) return resolved_list return deepcopy(val) if isinstance(val, str) and val.startswith("@") and val[1:] in self.profiles: sub = self._resolve_profile_attr_unlocked( val[1:], key, depth=depth + 1, visited=visited | {prof_name}, ) return sub if sub is not None else "" return deepcopy(val) def _find_inherited_profile_fallback_unlocked(self, raw_user, raw_pw): """Inherit fallback from a primary @profile referenced by node user/password.""" candidates = [] for raw_val, field in ((raw_user, "user"), (raw_pw, "password")): if isinstance(raw_val, (list, tuple)): for item in raw_val: candidates.append((item, field)) else: candidates.append((raw_val, field)) for candidate_val, field in candidates: if ( isinstance(candidate_val, str) and not is_compose_expression(candidate_val) and candidate_val.startswith("@") and "+" not in candidate_val ): prof_name = candidate_val[1:] visited = set() while prof_name and prof_name not in visited and len(visited) < MAX_PROFILE_DEPTH: visited.add(prof_name) prof = self.profiles.get(prof_name) if not isinstance(prof, dict): break prof_fb = prof.get("fallback") if prof_fb in (None, "", []) and isinstance(prof.get("tags"), dict): prof_fb = prof["tags"].get("fallback") if prof_fb not in (None, "", []): return deepcopy(prof_fb) next_val = prof.get(field) if isinstance(next_val, (list, tuple)): next_ref = next( ( item for item in next_val if isinstance(item, str) and not is_compose_expression(item) and item.startswith("@") and "+" not in item ), None, ) prof_name = next_ref[1:] if next_ref else "" elif ( isinstance(next_val, str) and not is_compose_expression(next_val) and next_val.startswith("@") and "+" not in next_val ): prof_name = next_val[1:] else: break return None def _extract_node_fields_unlocked(self, node_dict): """Resolve @profile references on a copied node dict, keeping legacy core.node(**cfg) contract.""" raw_user = node_dict.get("user") raw_pw = node_dict.get("password") raw_fb = node_dict.pop("fallback", None) for key, value in list(node_dict.items()): if key == "password": if isinstance(value, str): if is_compose_expression(value): continue if value.startswith("@") and value[1:] in self.profiles: resolved = self._resolve_profile_attr_unlocked(value[1:], "password") node_dict["password"] = resolved if resolved is not None else "" elif isinstance(value, list): resolved_pw = [] for item in value: if ( isinstance(item, str) and not is_compose_expression(item) and item.startswith("@") and item[1:] in self.profiles ): sub = self._resolve_profile_attr_unlocked(item[1:], "password") if isinstance(sub, list): resolved_pw.extend(deepcopy(sub)) elif sub is not None: resolved_pw.append(deepcopy(sub)) else: resolved_pw.append("") else: resolved_pw.append(deepcopy(item)) node_dict["password"] = resolved_pw continue if isinstance(value, str) and value.startswith("@"): ref_name = value[1:] if ref_name in self.profiles: res = self._resolve_profile_attr_unlocked(ref_name, key) node_dict[key] = res if res is not None else "" else: node_dict[key] = "" elif value == "" and key == "protocol": default_proto = self.profiles.get("default", {}).get("protocol", "ssh") node_dict[key] = default_proto if default_proto else "ssh" tags_fb_present = ( isinstance(node_dict.get("tags"), dict) and node_dict["tags"].get("fallback") not in (None, "", []) ) if raw_fb in (None, "", []) and not tags_fb_present: raw_fb = self._find_inherited_profile_fallback_unlocked(raw_user, raw_pw) resolved_fb = [] if raw_fb not in (None, "", []): resolved_fb = resolve_fallback_entries(raw_fb, self.profiles) if resolved_fb: tags_val = node_dict.get("tags", "") if isinstance(tags_val, dict): tags_copy = deepcopy(tags_val) tags_copy["_fallback"] = resolved_fb node_dict["tags"] = tags_copy elif tags_val in ("", None): node_dict["tags"] = {"_fallback": resolved_fb} else: node_dict["tags"] = {"_raw": tags_val, "_fallback": resolved_fb} elif isinstance(node_dict.get("tags"), dict) and node_dict["tags"].get("fallback") not in (None, "", []): tags_copy = deepcopy(node_dict["tags"]) tags_copy["_fallback"] = resolve_fallback_entries(tags_copy["fallback"], self.profiles) node_dict["tags"] = tags_copy def getitem_unlocked(self, unique, keys=None, extract=False): uniques = self._explode_unique_unlocked(unique) if unique.startswith("@"): if uniques.keys() >= {"folder", "subfolder"}: folder = self.connections[uniques["folder"]][uniques["subfolder"]] else: folder = self.connections[uniques["folder"]] newfolder = deepcopy(folder) newfolder.pop("type") for node_name in list(folder.keys()): if node_name == "type": continue if "type" in newfolder[node_name]: if newfolder[node_name]["type"] == "subfolder": newfolder.pop(node_name) else: newfolder[node_name].pop("type") if keys is not None: newfolder = {k: newfolder[k] for k in keys} if extract: for node_keys in newfolder.values(): self._extract_node_fields_unlocked(node_keys) return {f"{k}{unique}": v for k, v in newfolder.items()} if uniques.keys() >= {"folder", "subfolder"}: node = self.connections[uniques["folder"]][uniques["subfolder"]][uniques["id"]] elif "folder" in uniques: node = self.connections[uniques["folder"]][uniques["id"]] else: node = self.connections[uniques["id"]] newnode = deepcopy(node) newnode.pop("type") if extract: self._extract_node_fields_unlocked(newnode) return newnode @MethodHook def getitem(self, unique, keys = None, extract = False): """Get a node or folder of nodes from configfile.""" with self._mutation_lock: return self.getitem_unlocked(unique, keys=keys, extract=extract) @MethodHook def getitems(self, uniques, extract = False): ''' Get a group of nodes from configfile which can be passed to node/nodes class ### Parameters: - uniques (str/list): String name that will match hostnames from the connection manager. It can be a list of strings. ### Optional Parameters: - extract (bool): If True, extract information from profiles. Default False. ### Returns: dict: Dictionary containing information of node or multiple dictionaries of multiple nodes. ''' if isinstance(uniques, str): uniques = [uniques] with self._mutation_lock: nodes = {} case_sensitive = self.config.get("case", False) for item in uniques: target = item if case_sensitive else item.lower() if target.startswith("@"): nodes.update(self.getitem_unlocked(target, extract=extract)) else: nodes[target] = self.getitem_unlocked(target, extract=extract) return nodes def _connections_add_unlocked( self, *, id, host, folder='', subfolder='', options='', logs='', password='', port='', protocol='', user='', tags='', jumphost='', fallback='', type="connection", ): entry = { "host": host, "options": options, "logs": logs, "password": password, "port": port, "protocol": protocol, "user": user, "tags": tags, "jumphost": jumphost, "fallback": fallback, "type": type, } if folder == '': self.connections[id] = entry elif subfolder == '': self.connections[folder][id] = entry else: self.connections[folder][subfolder][id] = entry @MethodHook def _connections_add(self,*, id, host, folder='', subfolder='', options='', logs='', password='', port='', protocol='', user='', tags='', jumphost='', fallback='', type = "connection" ): #Add connection from config with self._mutation_lock: self._connections_add_unlocked( id=id, host=host, folder=folder, subfolder=subfolder, options=options, logs=logs, password=password, port=port, protocol=protocol, user=user, tags=tags, jumphost=jumphost, fallback=fallback, type=type, ) def _connections_del_unlocked(self, *, id, folder='', subfolder=''): if folder == '': del self.connections[id] elif subfolder == '': del self.connections[folder][id] else: del self.connections[folder][subfolder][id] @MethodHook def _connections_del(self,*, id, folder='', subfolder=''): #Delete connection from config with self._mutation_lock: self._connections_del_unlocked(id=id, folder=folder, subfolder=subfolder) def _folder_add_unlocked(self, *, folder, subfolder=''): if subfolder == '': if folder not in self.connections: self.connections[folder] = {"type": "folder"} else: if subfolder not in self.connections[folder]: self.connections[folder][subfolder] = {"type": "subfolder"} @MethodHook def _folder_add(self,*, folder, subfolder = ''): #Add Folder from config with self._mutation_lock: self._folder_add_unlocked(folder=folder, subfolder=subfolder) def _folder_del_unlocked(self, *, folder, subfolder=''): if subfolder == '': del self.connections[folder] else: del self.connections[folder][subfolder] @MethodHook def _folder_del(self,*, folder, subfolder=''): #Delete folder from config with self._mutation_lock: self._folder_del_unlocked(folder=folder, subfolder=subfolder) def _profiles_add_unlocked(self, *, id, host='', options='', logs='', password='', port='', protocol='', user='', tags='', jumphost='', fallback=''): self.profiles[id] = { "host": host, "options": options, "logs": logs, "password": password, "port": port, "protocol": protocol, "user": user, "tags": tags, "jumphost": jumphost, "fallback": fallback, } @MethodHook def _profiles_add(self,*, id, host = '', options='', logs='', password='', port='', protocol='', user='', tags='', jumphost='', fallback=''): #Add profile from config with self._mutation_lock: self._profiles_add_unlocked( id=id, host=host, options=options, logs=logs, password=password, port=port, protocol=protocol, user=user, tags=tags, jumphost=jumphost, fallback=fallback, ) def _profiles_del_unlocked(self, *, id): del self.profiles[id] @MethodHook def _profiles_del(self,*, id ): #Delete profile from config with self._mutation_lock: self._profiles_del_unlocked(id=id) @staticmethod def _normalize_filter_arg(filter_arg): if not filter_arg: return [] if isinstance(filter_arg, str): return [filter_arg] if isinstance(filter_arg, list): return [item for item in filter_arg if isinstance(item, str)] return None def _getallnodes_unlocked(self, filter=None): nodes = [] layer1 = [k for k, v in self.connections.items() if isinstance(v, dict) and v.get("type") == "connection"] folders = [k for k, v in self.connections.items() if isinstance(v, dict) and v.get("type") == "folder"] nodes.extend(layer1) for f in folders: layer2 = [k + "@" + f for k, v in self.connections[f].items() if isinstance(v, dict) and v.get("type") == "connection"] nodes.extend(layer2) subfolders = [k for k, v in self.connections[f].items() if isinstance(v, dict) and v.get("type") == "subfolder"] for s in subfolders: layer3 = [k + "@" + s + "@" + f for k, v in self.connections[f][s].items() if isinstance(v, dict) and v.get("type") == "connection"] nodes.extend(layer3) if filter: flat_filter = self._normalize_filter_arg(filter) flags = re.IGNORECASE if not self.config.get("case", False) else 0 nodes = [item for item in nodes if any(re.search(pattern, item, flags) for pattern in flat_filter)] return nodes @MethodHook def _getallnodes(self, filter = None): #get all nodes on configfile if filter and self._normalize_filter_arg(filter) is None: printer.error("Filter must be a string or a list of strings") sys.exit(1) with self._mutation_lock: return self._getallnodes_unlocked(filter=filter) def _getallnodesfull_unlocked(self, filter=None, extract=True): nodes = {} layer1 = {k: deepcopy(v) for k, v in self.connections.items() if isinstance(v, dict) and v.get("type") == "connection"} folders = [k for k, v in self.connections.items() if isinstance(v, dict) and v.get("type") == "folder"] nodes.update(layer1) for f in folders: layer2 = {k + "@" + f: deepcopy(v) for k, v in self.connections[f].items() if isinstance(v, dict) and v.get("type") == "connection"} nodes.update(layer2) subfolders = [k for k, v in self.connections[f].items() if isinstance(v, dict) and v.get("type") == "subfolder"] for s in subfolders: layer3 = {k + "@" + s + "@" + f: deepcopy(v) for k, v in self.connections[f][s].items() if isinstance(v, dict) and v.get("type") == "connection"} nodes.update(layer3) if filter: flat_filter = self._normalize_filter_arg(filter) flat_filter = ["^(?!.*@).+$" if item == "@" else item for item in flat_filter] nodes = {k: v for k, v in nodes.items() if any(re.search(pattern, k) for pattern in flat_filter)} if extract: for node_dict in nodes.values(): self._extract_node_fields_unlocked(node_dict) return nodes @MethodHook def _getallnodesfull(self, filter = None, extract = True): #get all nodes on configfile with all their attributes. if filter and self._normalize_filter_arg(filter) is None: printer.error("Filter must be a string or a list of strings") sys.exit(1) with self._mutation_lock: return self._getallnodesfull_unlocked(filter=filter, extract=extract) def _getallfolders_unlocked(self): folders = ["@" + k for k, v in self.connections.items() if isinstance(v, dict) and v.get("type") == "folder"] subfolders = [] for f in folders: s = ["@" + k + f for k, v in self.connections[f[1:]].items() if isinstance(v, dict) and v.get("type") == "subfolder"] subfolders.extend(s) folders.extend(subfolders) return folders @MethodHook def _getallfolders(self): #get all folders on configfile with self._mutation_lock: return self._getallfolders_unlocked() def _profileused_unlocked(self, profile): target_profiles = {profile} changed = True while changed: changed = False for pname, pval in self.profiles.items(): if ( pname not in target_profiles and isinstance(pval, dict) and (extract_profile_refs_from_value(pval) & target_profiles) ): target_profiles.add(pname) changed = True nodes = [] layer1 = [ k for k, v in self.connections.items() if isinstance(v, dict) and v.get("type") == "connection" and bool(extract_profile_refs_from_value(v) & target_profiles) ] folders = [k for k, v in self.connections.items() if isinstance(v, dict) and v.get("type") == "folder"] nodes.extend(layer1) for f in folders: layer2 = [ k + "@" + f for k, v in self.connections[f].items() if isinstance(v, dict) and v.get("type") == "connection" and bool(extract_profile_refs_from_value(v) & target_profiles) ] nodes.extend(layer2) subfolders = [k for k, v in self.connections[f].items() if isinstance(v, dict) and v.get("type") == "subfolder"] for s in subfolders: layer3 = [ k + "@" + s + "@" + f for k, v in self.connections[f][s].items() if isinstance(v, dict) and v.get("type") == "connection" and bool(extract_profile_refs_from_value(v) & target_profiles) ] nodes.extend(layer3) return nodes @MethodHook def _profileused(self, profile): #Return all the nodes that uses this profile. with self._mutation_lock: return self._profileused_unlocked(profile) @MethodHook def encrypt(self, password, keyfile=None): ''' Encrypts password using RSA keyfile ### Parameters: - password (str): Plaintext password to encrypt. ### Optional Parameters: - keyfile (str): Path/file to keyfile. Default is config keyfile. ### Returns: str: Encrypted password. ''' if keyfile is None: keyfile = self.key with open(keyfile) as f: from Crypto.PublicKey import RSA from Crypto.Cipher import PKCS1_OAEP key = RSA.import_key(f.read()) f.close() publickey = key.publickey() encryptor = PKCS1_OAEP.new(publickey) password = encryptor.encrypt(password.encode("utf-8")) return str(password)This class generates a configfile object. Containts a dictionary storing, config, nodes and profiles, normaly used by connection manager.
Attributes:
- file (str): Path/file to config file. - key (str): Path/file to RSA key file. - config (dict): Dictionary containing information of connection manager configuration. - connections (dict): Dictionary containing all the nodes added to connection manager. - profiles (dict): Dictionary containing all the profiles added to connection manager. - privatekey (obj): Object containing the private key to encrypt passwords. - publickey (obj): Object containing the public key to decrypt passwords.Instance variables
prop privatekey-
Expand source code
@property def privatekey(self): if getattr(self, '_privatekey_obj', None) is None: from Crypto.PublicKey import RSA if not os.path.exists(self.key): self._createkey(self.key) with open(self.key) as f: self._privatekey_obj = RSA.import_key(f.read()) return self._privatekey_obj prop publickey-
Expand source code
@property def publickey(self): if getattr(self, '_publickey_obj', None) is None: self._publickey_obj = self.privatekey.publickey() return self._publickey_obj
Methods
def encrypt(self, password, keyfile=None)-
Expand source code
@MethodHook def encrypt(self, password, keyfile=None): ''' Encrypts password using RSA keyfile ### Parameters: - password (str): Plaintext password to encrypt. ### Optional Parameters: - keyfile (str): Path/file to keyfile. Default is config keyfile. ### Returns: str: Encrypted password. ''' if keyfile is None: keyfile = self.key with open(keyfile) as f: from Crypto.PublicKey import RSA from Crypto.Cipher import PKCS1_OAEP key = RSA.import_key(f.read()) f.close() publickey = key.publickey() encryptor = PKCS1_OAEP.new(publickey) password = encryptor.encrypt(password.encode("utf-8")) return str(password)Encrypts password using RSA keyfile
Parameters:
- password (str): Plaintext password to encrypt.Optional Parameters:
- keyfile (str): Path/file to keyfile. Default is config keyfile.Returns:
str: Encrypted password. def get_effective_setting(self, key, default=None)-
Expand source code
def get_effective_setting(self, key, default=None): """Get config setting with shared fallback for inheritable keys.""" val = self.config.get(key) if key == "ai": if val is not None: if self._shared_config: import copy # Deep merge: shared as base, user overrides base = copy.deepcopy(self._shared_config.config.get(key, {})) if isinstance(base, dict) and isinstance(val, dict): # Credential isolation: # If user defines engineer credentials, discard shared ones if "engineer_api_key" in val or "engineer_auth" in val: base.pop("engineer_api_key", None) base.pop("engineer_auth", None) # If user defines architect credentials, discard shared ones if "architect_api_key" in val or "architect_auth" in val: base.pop("architect_api_key", None) base.pop("architect_auth", None) # Recursive update for inner dictionaries (like mcp_servers or model details) def deep_merge(d1, d2): for k, v in d2.items(): if isinstance(v, dict) and k in d1 and isinstance(d1[k], dict): deep_merge(d1[k], v) else: d1[k] = copy.deepcopy(v) deep_merge(base, val) return base return val elif self._shared_config: return self._shared_config.config.get(key, default) return val if val is not None else defaultGet config setting with shared fallback for inheritable keys.
def getitem(self, unique, keys=None, extract=False)-
Expand source code
@MethodHook def getitem(self, unique, keys = None, extract = False): """Get a node or folder of nodes from configfile.""" with self._mutation_lock: return self.getitem_unlocked(unique, keys=keys, extract=extract)Get a node or folder of nodes from configfile.
def getitem_unlocked(self, unique, keys=None, extract=False)-
Expand source code
def getitem_unlocked(self, unique, keys=None, extract=False): uniques = self._explode_unique_unlocked(unique) if unique.startswith("@"): if uniques.keys() >= {"folder", "subfolder"}: folder = self.connections[uniques["folder"]][uniques["subfolder"]] else: folder = self.connections[uniques["folder"]] newfolder = deepcopy(folder) newfolder.pop("type") for node_name in list(folder.keys()): if node_name == "type": continue if "type" in newfolder[node_name]: if newfolder[node_name]["type"] == "subfolder": newfolder.pop(node_name) else: newfolder[node_name].pop("type") if keys is not None: newfolder = {k: newfolder[k] for k in keys} if extract: for node_keys in newfolder.values(): self._extract_node_fields_unlocked(node_keys) return {f"{k}{unique}": v for k, v in newfolder.items()} if uniques.keys() >= {"folder", "subfolder"}: node = self.connections[uniques["folder"]][uniques["subfolder"]][uniques["id"]] elif "folder" in uniques: node = self.connections[uniques["folder"]][uniques["id"]] else: node = self.connections[uniques["id"]] newnode = deepcopy(node) newnode.pop("type") if extract: self._extract_node_fields_unlocked(newnode) return newnode def getitems(self, uniques, extract=False)-
Expand source code
@MethodHook def getitems(self, uniques, extract = False): ''' Get a group of nodes from configfile which can be passed to node/nodes class ### Parameters: - uniques (str/list): String name that will match hostnames from the connection manager. It can be a list of strings. ### Optional Parameters: - extract (bool): If True, extract information from profiles. Default False. ### Returns: dict: Dictionary containing information of node or multiple dictionaries of multiple nodes. ''' if isinstance(uniques, str): uniques = [uniques] with self._mutation_lock: nodes = {} case_sensitive = self.config.get("case", False) for item in uniques: target = item if case_sensitive else item.lower() if target.startswith("@"): nodes.update(self.getitem_unlocked(target, extract=extract)) else: nodes[target] = self.getitem_unlocked(target, extract=extract) return nodesGet a group of nodes from configfile which can be passed to node/nodes class
Parameters:
- uniques (str/list): String name that will match hostnames from the connection manager. It can be a list of strings.Optional Parameters:
- extract (bool): If True, extract information from profiles. Default False.Returns:
dict: Dictionary containing information of node or multiple dictionaries of multiple nodes. def refresh_cache(self)-
Expand source code
def refresh_cache(self): """Rebuild JSON and fzf sidecar caches atomically; returns True on success.""" with self._mutation_lock: snapshot = { "config": self.config, "connections": self.connections, "profiles": self.profiles, } try: self._atomic_write_text_unlocked(self.cachefile, lambda f: json.dump(snapshot, f)) self._generate_nodes_cache_unlocked(_raise_on_error=True) self._cache_dirty = False return True except (OSError, TypeError, ValueError): self._cache_dirty = True return FalseRebuild JSON and fzf sidecar caches atomically; returns True on success.
def transactional_update(self, mutator)-
Expand source code
def transactional_update(self, mutator): """Run mutator atomically inside _mutation_lock with in-place RAM rollback on error.""" save_desc = type(self).__dict__.get("_saveconfig") mocked_save = "_saveconfig" in self.__dict__ or not isinstance(save_desc, MethodHook) with self._mutation_lock: snap_config = deepcopy(self.config) snap_connections = deepcopy(self.connections) snap_profiles = deepcopy(self.profiles) try: result = mutator(self) self._validate_config_strict( { "config": self.config, "connections": self.connections, "profiles": self.profiles, } ) if mocked_save: rc = self._saveconfig(self.file) if rc != 0: raise OSError("Failed to save config") else: self._saveconfig_unlocked(self.file, _raise_on_error=True) except BaseException: self.config.clear() self.config.update(snap_config) self.connections.clear() self.connections.update(snap_connections) self.profiles.clear() self.profiles.update(snap_profiles) raise if not mocked_save: self._run_saveconfig_post_hooks(self.file, 0) return resultRun mutator atomically inside _mutation_lock with in-place RAM rollback on error.
class node (unique,
host,
options='',
logs='',
password='',
port='',
protocol='',
user='',
config='',
tags='',
jumphost='',
allow_unsafe_options=None,
fallback=None,
disable_fallback_on_insecure_hostkey=None)-
Expand source code
@ClassHook class node: ''' This class generates a node object. Containts all the information and methods to connect and interact with a device using ssh or telnet. ### Attributes: - output (str): Output of the commands you ran with run or test method. - result(bool): True if expected value is found after running the commands using test method. - status (int): 0 if the method run or test run successfully. 1 if connection failed. 2 if expect timeouts without prompt or EOF. ''' def __init__( self, unique, host, options='', logs='', password='', port='', protocol='', user='', config='', tags='', jumphost='', allow_unsafe_options=None, fallback=None, disable_fallback_on_insecure_hostkey=None, ): ''' ### Parameters: - unique (str): Unique name to assign to the node. - host (str): IP address or hostname of the node. ### Optional Parameters: - options (str): Additional options to pass the ssh/telnet for connection. - logs (str): Path/file for storing the logs. You can use ${unique},${host}, ${port}, ${user}, ${protocol} as variables. - password (str): Encrypted or plaintext password. - port (str): Port to connect to node, default 22 for ssh and 23 for telnet. - protocol (str): Select ssh, mosh, telnet, kubectl, docker or ssm. Default is ssh. - user (str): Username to of the node. - config (obj): Pass the object created with class configfile with key for decryption and extra configuration if you are using connection manager. - tags (dict) : Tags useful for automation and personal porpuse like "os", "prompt" and "screenleght_command" - jumphost (str): Reference another node to be used as a jumphost - allow_unsafe_options (bool): Explicitly override safety restrictions. ''' self.config = config if config == '': self.idletime = 0 self.key = None else: self.idletime = config.config["idletime"] if (hasattr(config, "config") and isinstance(config.config, dict) and "idletime" in config.config) else 0 self.key = getattr(config, "key", None) if allow_unsafe_options is not None: self.allow_unsafe_options = bool(allow_unsafe_options) elif config != '' and config is not None and hasattr(config, "config") and isinstance(config.config, dict): self.allow_unsafe_options = bool(config.config.get("allow_unsafe_options", False)) else: self.allow_unsafe_options = False self.unique = unique profiles_map = getattr(config, "profiles", {}) if (config != '' and config is not None) else {} attr = {"host": host, "logs": logs, "options":options, "port": port, "protocol": protocol, "user": user, "tags": tags, "jumphost": jumphost} for key, attr_val in attr.items(): profile = re.search("^@(.*)", str(attr_val)) if profile and config != '': try: setattr(self, key, deepcopy(profiles_map[profile.group(1)][key])) except KeyError: setattr(self, key, "") elif attr_val == '' and key == "protocol": try: setattr(self, key, profiles_map["default"][key]) except (KeyError, AttributeError): setattr(self, key, "ssh") else: setattr(self, key, attr_val) self._orig_protocol = self.protocol if isinstance(password, list): self.password = [] for item in password: if ( isinstance(item, str) and not is_compose_expression(item) and item.startswith("@") and config != '' and item[1:] in profiles_map ): self.password.append(deepcopy(profiles_map[item[1:]].get("password", ""))) else: self.password.append(item) else: if ( isinstance(password, str) and not is_compose_expression(password) and password.startswith("@") and config != '' and password[1:] in profiles_map ): resolved_pw = profiles_map[password[1:]].get("password", "") self.password = deepcopy(resolved_pw) if isinstance(resolved_pw, list) else [resolved_pw] else: self.password = [password] target_passwords_snapshot = list(self.password) raw_fallback = fallback if raw_fallback in (None, "", []) and isinstance(self.tags, dict): if "_fallback" in self.tags: raw_fallback = self.tags.pop("_fallback", None) elif "fallback" in self.tags: raw_fallback = self.tags.get("fallback") if raw_fallback not in (None, "", []): resolved_fb_entries = resolve_fallback_entries(raw_fallback, profiles_map) else: resolved_fb_entries = [] candidates: list[AuthCandidate] = [] primary_specs = tuple( p for p in target_passwords_snapshot if isinstance(p, str) and p != "" ) if primary_specs: candidates.append( AuthCandidate( user=str(self.user or ""), password_spec=primary_specs if len(primary_specs) > 1 else primary_specs[0], is_fallback=False, label="primary", ) ) elif self.user: candidates.append( AuthCandidate( user=str(self.user or ""), password_spec="", is_fallback=False, label="primary", ) ) for fb_idx, entry in enumerate(resolved_fb_entries, start=1): fb_user = str(entry.get("user") or self.user or "") fb_pw = entry.get("password", "") if isinstance(fb_pw, list): pw_spec: str | tuple[str, ...] = tuple(str(x) for x in fb_pw if x != "") else: pw_spec = str(fb_pw or "") candidates.append( AuthCandidate( user=fb_user, password_spec=pw_spec, is_fallback=True, label=f"fallback#{fb_idx}", ) ) self._auth_candidates: tuple[AuthCandidate, ...] = tuple(candidates) if disable_fallback_on_insecure_hostkey is not None: self.disable_fallback_on_insecure_hostkey = bool(disable_fallback_on_insecure_hostkey) elif isinstance(self.tags, dict) and "disable_fallback_on_insecure_hostkey" in self.tags: self.disable_fallback_on_insecure_hostkey = bool( self.tags["disable_fallback_on_insecure_hostkey"] ) elif ( config != '' and config is not None and hasattr(config, "config") and isinstance(config.config, dict) ): self.disable_fallback_on_insecure_hostkey = bool( config.config.get("disable_fallback_on_insecure_hostkey", False) ) else: self.disable_fallback_on_insecure_hostkey = False self._jumphost_name = self.jumphost if (self.jumphost != "" and config != '') else "" self._hop_chain_meta = [] self._jumphost_hops: tuple[dict, ...] = () if self.jumphost != "" and config != '': chain_res = self._build_jumphost_chain(self.jumphost, config, include_meta=True) if len(chain_res) == 3: raw_cmd, jh_passwords, self._hop_chain_meta = chain_res else: raw_cmd, jh_passwords = chain_res self._hop_chain_meta = [] self._jumphost_hops = tuple(self._collect_jumphost_hops(self._jumphost_name, config)) if jh_passwords: self.password = jh_passwords + self.password if raw_cmd: escaped = raw_cmd.replace('\\', '\\\\').replace('"', '\\"') self.jumphost = f'-o ProxyCommand="{escaped}"' else: self.jumphost = "" self.last_fallback_used = False self.output = "" self.status = 1 self.result = {} self.cmd_byte_positions = [(0, None)] def _collect_jumphost_hops(self, jumphost_name, config, visited=None, depth=0): """Collect structured hop metadata in SSH ProxyCommand prompt order.""" if depth >= 5: return [] if visited is None: visited = [] if jumphost_name in visited: return [] visited = [*visited, jumphost_name] try: jh = config.getitem(jumphost_name) except Exception: # noqa: BLE001 return [] jh = self._resolve_jumphost_data(deepcopy(jh), config) hops = [] if jh.get("jumphost", "") != "": hops.extend( self._collect_jumphost_hops( jh["jumphost"], config, visited, depth + 1, ) ) jh_tags = jh.get("tags") resolved_fqdn = "" if isinstance(jh_tags, dict) and jh_tags.get("fqdn"): resolved_fqdn = str(jh_tags["fqdn"]) hops.append( { "name": jumphost_name, "host": str(jh.get("host", "") or ""), "port": str(jh.get("port", "") or ""), "protocol": str(jh.get("protocol", "ssh") or "ssh"), "user": str(jh.get("user", "") or ""), "options": str(jh.get("options", "") or ""), "tags": deepcopy(jh_tags) if isinstance(jh_tags, dict) else jh_tags, "resolved_fqdn": resolved_fqdn, "passwords": tuple(p for p in (jh.get("password") or []) if p != ""), } ) return hops @staticmethod def _resolve_jumphost_data(jh_dict, config): '''Resolve @profile references and normalize passwords in a jumphost dict.''' profiles_map = getattr(config, "profiles", {}) if config else {} for key, jh_val in list(jh_dict.items()): if key == "password": continue profile = re.search("^@(.*)", str(jh_val)) if profile: try: jh_dict[key] = deepcopy(profiles_map[profile.group(1)][key]) except KeyError: jh_dict[key] = "" elif jh_val == '' and key == "protocol": try: jh_dict[key] = profiles_map["default"][key] except KeyError: jh_dict[key] = "ssh" raw_pw = jh_dict.get("password", "") if isinstance(raw_pw, list): resolved = [] for p in raw_pw: if ( isinstance(p, str) and not is_compose_expression(p) and p.startswith("@") and p[1:] in profiles_map ): resolved.append(deepcopy(profiles_map[p[1:]].get("password", ""))) else: resolved.append(p) jh_dict["password"] = resolved else: if ( isinstance(raw_pw, str) and not is_compose_expression(raw_pw) and raw_pw.startswith("@") and raw_pw[1:] in profiles_map ): res = profiles_map[raw_pw[1:]].get("password", "") jh_dict["password"] = deepcopy(res) if isinstance(res, list) else [res] else: jh_dict["password"] = [raw_pw] return jh_dict def _is_unsafe_allowed(self) -> bool: if getattr(self, "allow_unsafe_options", False): return True if hasattr(self, "config") and self.config and hasattr(self.config, "config") and isinstance(self.config.config, dict): return bool(self.config.config.get("allow_unsafe_options", False)) return False def _validate_base_fields(self, check_port=True): """Sanitize host, user, and port against argument injection and shell metacharacters.""" host_s = str(self.host) if self.host is not None else "" if not host_s: raise ValueError("Host cannot be empty") if host_s.startswith("-"): raise ValueError(f"Host cannot start with '-': '{self.host}'") host_bare = ( host_s[1:-1] if (host_s.startswith("[") and host_s.endswith("]")) else host_s ) if not host_bare or host_bare.startswith("-"): raise ValueError(f"Invalid characters in host: '{self.host}'") if _LEGACY_SSH_UNSAFE_RE.search(host_bare): raise ValueError(f"Invalid characters in host: '{self.host}'") user_s = str(self.user) if self.user is not None else "" if user_s: if user_s.startswith("-"): raise ValueError(f"User cannot start with '-': '{self.user}'") if _LEGACY_SSH_UNSAFE_RE.search(user_s): raise ValueError(f"Invalid characters in user: '{self.user}'") if check_port and self.port != "" and self.port is not None: if isinstance(self.port, (bool, float)): raise ValueError(f"Invalid TCP SSH port '{self.port}'") port_s = str(self.port).strip() if port_s and ( not port_s.isascii() or not re.fullmatch(r"[0-9]+", port_s, re.ASCII) or not (1 <= int(port_s) <= 65535) ): raise ValueError(f"Invalid TCP SSH port '{self.port}'") def _validate_options_and_safety(self): """Validate options string for unbalanced quotes and dangerous control characters.""" if not self.options: return opts_str = str(self.options).strip() if not opts_str: return if not self._is_unsafe_allowed(): if any(c in opts_str for c in ("\n", "\r", "\x00")): raise ValueError("Options cannot contain newlines or null bytes") try: shlex.split(opts_str) except ValueError as e: raise ValueError(f"Invalid options: unbalanced quotes ({e})") from e def _validate_ssh_options(self): """Sanitize SSH options against local command execution directives.""" self._validate_options_and_safety() if not self.options: return opts_str = str(self.options).strip() if not opts_str: return if not self._is_unsafe_allowed(): dangerous_directives = ("ProxyCommand", "LocalCommand", "PermitLocalCommand", "KnownHostsCommand") pattern = r'(?:' + '|'.join(dangerous_directives) + r')' match = re.search(pattern, opts_str, re.IGNORECASE) if match: raise ValueError(f"Disallowed SSH directive in options: '{match.group(0)}'") @staticmethod def _validate_legacy_ssh_hop_fields(host, user, port): """Minimal injection guard for legacy SSH jumphost fields (preserves DOMAIN\\user, %scope, etc.).""" host_s = str(host) if host is not None else "" if host_s.startswith("-"): raise ValueError("Host cannot start with '-'") if not host_s or _LEGACY_SSH_UNSAFE_RE.search(host_s): raise ValueError(f"Invalid characters in host: '{host}'") host_bare = ( host_s[1:-1] if (host_s.startswith("[") and host_s.endswith("]")) else host_s ) if not host_bare or host_bare.startswith("-"): raise ValueError(f"Invalid characters in host: '{host}'") user_s = str(user) if user is not None else "" if user_s.startswith("-"): raise ValueError("User cannot start with '-'") if user_s and _LEGACY_SSH_UNSAFE_RE.search(user_s): raise ValueError(f"Invalid characters in user: '{user}'") port_out = "" if port != "" and port is not None: if isinstance(port, (bool, float)): raise ValueError(f"Invalid TCP SSH port '{port}'") port_s = str(port).strip() if port_s: if ( not port_s.isascii() or not re.fullmatch(r"[0-9]+", port_s, re.ASCII) or not (1 <= int(port_s) <= 65535) ): raise ValueError(f"Invalid TCP SSH port '{port}'") port_out = port_s return host_bare, port_out @staticmethod def _validate_mosh_ssh_fields( host, user, port, tags, *, strip_non_tunnel_flags=False, allow_reverse_tunnel_port=None, ): """Validate host, user, TCP SSH port, and mosh_ssh_options for Mosh SSH backend. Accepts IPv4, hostnames, and bare or bracketed IPv6 literals (including IPv4-mapped IPv6 like ::ffff:1.2.3.4, without scope-id '%'). Returns: tuple[str, str, str]: (host_bare_str, validated_port_str, validated_ssh_opts_str) """ host_s = str(host) if host is not None else "" if host_s.startswith("-"): raise ValueError("Host cannot start with '-'") if not host_s: raise ValueError(f"Invalid characters in host: '{host}'") if (host_s.startswith("[") and host_s.endswith("]")) or ":" in host_s: inner = host_s[1:-1] if (host_s.startswith("[") and host_s.endswith("]")) else host_s if "%" in inner or not re.fullmatch(r"[0-9A-Fa-f:.]+", inner, re.ASCII): raise ValueError(f"Invalid characters in host: '{host}'") try: ipaddress.IPv6Address(inner) except ValueError as exc: raise ValueError(f"Invalid characters in host: '{host}'") from exc host_bare = inner else: if not re.fullmatch(r"[A-Za-z0-9._-]+", host_s, re.ASCII): raise ValueError(f"Invalid characters in host: '{host}'") host_bare = host_s user_s = str(user) if user is not None else "" if user_s.startswith("-"): raise ValueError("User cannot start with '-'") if user_s and not re.fullmatch( r"[A-Za-z0-9._-]+(?:@[A-Za-z0-9._-]+)?", user_s, re.ASCII ): raise ValueError(f"Invalid characters in user: '{user}'") port_out = "" if port != "" and port is not None: if isinstance(port, (bool, float)): raise ValueError(f"Invalid TCP SSH port '{port}'") port_s = str(port).strip() if port_s: if ( not port_s.isascii() or not re.fullmatch(r"[0-9]+", port_s, re.ASCII) or not (1 <= int(port_s) <= 65535) ): raise ValueError(f"Invalid TCP SSH port '{port}'") port_out = port_s allowed_r_port = None if allow_reverse_tunnel_port is not None: r_port_s = str(allow_reverse_tunnel_port).strip() if ( isinstance(allow_reverse_tunnel_port, (bool, float)) or not r_port_s.isascii() or not re.fullmatch(r"[0-9]+", r_port_s, re.ASCII) or not (1 <= int(r_port_s) <= 65535) ): raise ValueError( f"Invalid allow_reverse_tunnel_port '{allow_reverse_tunnel_port}'" ) allowed_r_port = r_port_s opts_out = "" raw_opts = tags.get("mosh_ssh_options", "") if isinstance(tags, dict) else "" if raw_opts: ssh_opts = str(raw_opts).strip() if "\x00" in ssh_opts or "\n" in ssh_opts or "\r" in ssh_opts: raise ValueError("Disallowed control characters in mosh_ssh_options") if ssh_opts: try: tokens = shlex.split(ssh_opts) except ValueError as exc: raise ValueError( "Invalid mosh_ssh_options: unbalanced quotes" ) from exc r_count = 0 exit_fwd_count = 0 out_tokens = [] idx = 0 # Normative branch evaluation order: # 1. NOARG -> 2. ARG separate -> 3. ARG attached -> 4. -R -> 5. -o/-oXXX -> 6. other while idx < len(tokens): tok = tokens[idx] if tok in _ALLOWED_SSH_NOARG_FLAGS: if not (strip_non_tunnel_flags and tok in _NON_TUNNEL_SSH_FLAGS): out_tokens.append(tok) idx += 1 elif tok in _ALLOWED_SSH_ARG_FLAGS: if idx + 1 >= len(tokens) or not tokens[idx + 1].strip(): raise ValueError( f"Missing argument for ssh option '{tok}' in mosh_ssh_options" ) arg_val = tokens[idx + 1] val_re = _SAFE_SSH_PATH_RE if tok == "-i" else _SAFE_SSH_O_VALUE_RE if arg_val.startswith("-") or not val_re.fullmatch(arg_val): raise ValueError( f"Invalid argument for ssh option '{tok}' in mosh_ssh_options" ) out_tokens.extend([tok, arg_val]) idx += 2 elif tok[:2] in _ALLOWED_SSH_ARG_FLAGS and len(tok) > 2: flag_prefix = tok[:2] arg_val = tok[2:] val_re = _SAFE_SSH_PATH_RE if flag_prefix == "-i" else _SAFE_SSH_O_VALUE_RE if ( not arg_val.strip() or arg_val.startswith("-") or not val_re.fullmatch(arg_val) ): raise ValueError( f"Invalid argument for ssh option '{flag_prefix}' in mosh_ssh_options" ) out_tokens.append(tok) idx += 1 elif tok == "-R": if ( allowed_r_port is None or r_count >= 1 or idx + 1 >= len(tokens) or tokens[idx + 1] != f"{allowed_r_port}:localhost:{allowed_r_port}" ): raise ValueError( f"Disallowed ssh option in mosh_ssh_options: '{tok}'" ) r_count += 1 out_tokens.extend([tok, tokens[idx + 1]]) idx += 2 elif tok == "-o" or tok.startswith("-o"): if tok == "-o": if idx + 1 >= len(tokens) or not tokens[idx + 1].strip(): raise ValueError( "Missing argument for ssh option '-o' in mosh_ssh_options" ) opt_spec = tokens[idx + 1] step = 2 else: opt_spec = tok[2:] step = 1 if re.search(r"(?:localcommand|proxycommand)", opt_spec, re.IGNORECASE): raise ValueError( "mosh_ssh_options cannot contain LocalCommand or ProxyCommand" ) m = re.fullmatch(r"([A-Za-z0-9]+)=(.+)", opt_spec, re.ASCII) if ( not m or not m.group(2).strip() or not _SAFE_SSH_O_VALUE_RE.fullmatch(m.group(2).strip()) ): raise ValueError( f"Disallowed -o directive in mosh_ssh_options: '{opt_spec}'" ) key_raw = m.group(1) key_lower = key_raw.lower() val_str = m.group(2).strip() if key_lower == "exitonforwardfailure": if ( allowed_r_port is None or exit_fwd_count >= 1 or val_str.lower() != "yes" ): raise ValueError( f"Disallowed -o directive in mosh_ssh_options: '{opt_spec}'" ) exit_fwd_count += 1 elif key_lower not in _ALLOWED_SSH_O_KEYS: raise ValueError( f"Disallowed -o directive in mosh_ssh_options: '{opt_spec}'" ) if not (strip_non_tunnel_flags and key_lower == "forwardagent"): if tok == "-o": out_tokens.extend(["-o", f"{key_raw}={val_str}"]) else: out_tokens.append(f"-o{key_raw}={val_str}") idx += step else: if re.search(r"(?:localcommand|proxycommand)", tok, re.IGNORECASE): raise ValueError( "mosh_ssh_options cannot contain LocalCommand or ProxyCommand" ) raise ValueError( f"Disallowed ssh option in mosh_ssh_options: '{tok}'" ) opts_out = shlex.join(out_tokens) return host_bare, port_out, opts_out @staticmethod def _validate_and_prepare_ssh_options( raw_opts, *, field_name: str = "options", strip_non_tunnel_flags: bool = False, allow_unsafe: bool = False, connect_timeout: int | None = None, ) -> str: """Validate SSH options against _ALLOWED_SSH_O_KEYS and optionally inject ConnectTimeout/ServerAliveInterval.""" out_tokens: list[str] = [] if raw_opts: ssh_opts = str(raw_opts).strip() if _CONTROL_CHAR_RE.search(ssh_opts): raise ValueError(f"Disallowed control characters in {field_name}") if ssh_opts: try: tokens = shlex.split(ssh_opts) except ValueError as exc: raise ValueError(f"Invalid {field_name}: unbalanced quotes") from exc if allow_unsafe: out_tokens = list(tokens) else: idx = 0 while idx < len(tokens): tok = tokens[idx] if tok in _ALLOWED_SSH_NOARG_FLAGS: if not (strip_non_tunnel_flags and tok in _NON_TUNNEL_SSH_FLAGS): out_tokens.append(tok) idx += 1 elif tok in _ALLOWED_SSH_ARG_FLAGS: if idx + 1 >= len(tokens) or not tokens[idx + 1].strip(): raise ValueError( f"Missing argument for ssh option '{tok}' in {field_name}" ) arg_val = tokens[idx + 1] val_re = _SAFE_SSH_PATH_RE if tok == "-i" else _SAFE_SSH_O_VALUE_RE if arg_val.startswith("-") or not val_re.fullmatch(arg_val): raise ValueError( f"Invalid argument for ssh option '{tok}' in {field_name}" ) out_tokens.extend([tok, arg_val]) idx += 2 elif tok[:2] in _ALLOWED_SSH_ARG_FLAGS and len(tok) > 2: flag_prefix = tok[:2] arg_val = tok[2:] val_re = _SAFE_SSH_PATH_RE if flag_prefix == "-i" else _SAFE_SSH_O_VALUE_RE if ( not arg_val.strip() or arg_val.startswith("-") or not val_re.fullmatch(arg_val) ): raise ValueError( f"Invalid argument for ssh option '{flag_prefix}' in {field_name}" ) out_tokens.append(tok) idx += 1 elif tok == "-o" or tok.startswith("-o"): if tok == "-o": if idx + 1 >= len(tokens) or not tokens[idx + 1].strip(): raise ValueError( f"Missing argument for ssh option '-o' in {field_name}" ) opt_spec = tokens[idx + 1] step = 2 else: opt_spec = tok[2:] step = 1 if re.search( r"(?:localcommand|proxycommand|permitlocalcommand|knownhostscommand)", opt_spec, re.IGNORECASE, ): raise ValueError( f"{field_name} cannot contain LocalCommand or ProxyCommand" ) m = re.fullmatch(r"([A-Za-z0-9]+)=(.+)", opt_spec, re.ASCII) if ( not m or not m.group(2).strip() or not _SAFE_SSH_O_VALUE_RE.fullmatch(m.group(2).strip()) ): raise ValueError( f"Disallowed -o directive in {field_name}: '{opt_spec}'" ) key_raw = m.group(1) key_lower = key_raw.lower() val_str = m.group(2).strip() if key_lower not in _ALLOWED_SSH_O_KEYS: raise ValueError( f"Disallowed -o directive in {field_name}: '{opt_spec}'" ) if not (strip_non_tunnel_flags and key_lower == "forwardagent"): if tok == "-o": out_tokens.extend(["-o", f"{key_raw}={val_str}"]) else: out_tokens.append(f"-o{key_raw}={val_str}") idx += step else: if re.search( r"(?:localcommand|proxycommand|permitlocalcommand|knownhostscommand)", tok, re.IGNORECASE, ): raise ValueError( f"{field_name} cannot contain LocalCommand or ProxyCommand" ) raise ValueError( f"Disallowed ssh option in {field_name}: '{tok}'" ) if connect_timeout is not None: ct_val = validate_strict_timeout_int(connect_timeout, "connect_timeout") existing_keys = _extract_ssh_o_keys(out_tokens) if "connecttimeout" not in existing_keys and "connecttimeout" in _ALLOWED_SSH_O_KEYS: out_tokens.extend(["-o", f"ConnectTimeout={ct_val}"]) if ( "serveraliveinterval" not in existing_keys and "serveraliveinterval" in _ALLOWED_SSH_O_KEYS ): out_tokens.extend(["-o", "ServerAliveInterval=15"]) return shlex.join(out_tokens) if out_tokens else "" def _build_jumphost_chain( self, jumphost_name, config, visited=None, depth=0, target_host="%h", target_port="%p", *, include_meta=False, connect_timeout=None, ): """Recursively build ProxyCommand for chained jumphosts. Returns: tuple: (raw_proxy_command, passwords_list) when include_meta=False, or (raw_proxy_command, passwords_list, hop_meta) when include_meta=True. Raises: ValueError: On circular references, invalid hop fields, or exceeding max depth (5). """ if depth >= 5: raise ValueError("Jumphost chain exceeds maximum depth of 5 hops") if visited is None: visited = [] if jumphost_name in visited: cycle = " -> ".join(visited + [jumphost_name]) raise ValueError(f"Circular jumphost reference detected: {cycle}") visited = visited + [jumphost_name] jh = config.getitem(jumphost_name) jh = self._resolve_jumphost_data(jh, config) # Unconditional control-character guard on all hop metadata fields for fld_name in ("host", "user", "port"): fld_val = jh.get(fld_name) if fld_val not in (None, "") and _CONTROL_CHAR_RE.search(str(fld_val)): raise ValueError(f"Control characters disallowed in jumphost {fld_name}") jh_tags = jh.get("tags") if isinstance(jh_tags, dict): for tag_fld in ("profile", "region"): tag_val = jh_tags.get(tag_fld) if tag_val not in (None, "") and _CONTROL_CHAR_RE.search(str(tag_val)): raise ValueError(f"Control characters disallowed in jumphost {tag_fld}") if connect_timeout is not None: connect_timeout = validate_strict_timeout_int(connect_timeout, "connect_timeout") jh_proto = jh.get("protocol", "ssh") if jh_proto == "mosh": jh_host, jh_port, jh_opts = self._validate_mosh_ssh_fields( jh.get("host", ""), jh.get("user", ""), jh.get("port", ""), jh.get("tags", ""), strip_non_tunnel_flags=True, ) if connect_timeout is not None: jh_opts = self._validate_and_prepare_ssh_options( jh_opts, field_name="mosh_ssh_options", strip_non_tunnel_flags=True, connect_timeout=connect_timeout, ) elif jh_proto == "ssh": jh_host, jh_port = self._validate_legacy_ssh_hop_fields( jh.get("host", ""), jh.get("user", ""), jh.get("port", ""), ) jh_opts = self._validate_and_prepare_ssh_options( jh.get("options", ""), field_name="jumphost options", allow_unsafe=self._is_unsafe_allowed(), connect_timeout=connect_timeout, ) else: jh_host = str(jh.get("host", "") or "") jh_port = str(jh["port"]).strip() if jh.get("port") not in ("", None) else "" jh_opts = jh.get("options", "") passwords = [] inner_proxy_opt = "" inner_meta: list[dict[str, str]] = [] # Recursively resolve inner jumphost if jh.get("jumphost", "") != "": if jh_proto not in ["ssh", "mosh"]: raise ValueError( f"Jumphost '{jumphost_name}' uses protocol '{jh_proto}' " "which does not support chained jumphosts. " "Only SSH or Mosh jumphosts can have their own jumphosts." ) parent_port = jh_port if jh_port != "" else "22" inner_res = self._build_jumphost_chain( jh["jumphost"], config, visited, depth + 1, target_host=jh_host, target_port=parent_port, include_meta=True, connect_timeout=connect_timeout, ) if len(inner_res) == 3: inner_raw_cmd, inner_passwords, inner_meta = inner_res else: inner_raw_cmd, inner_passwords = inner_res inner_meta = [] passwords = inner_passwords escaped = inner_raw_cmd.replace("\\", "\\\\").replace('"', '\\"') inner_proxy_opt = f'-o ProxyCommand="{escaped}"' # Collect this hop's passwords if jh["password"] != [""]: passwords = passwords + jh["password"] hop_meta = [*inner_meta, {"name": jumphost_name, "protocol": jh_proto}] t_port = target_port if target_port != "" else "22" if jh_proto in ["ssh", "mosh", "ssm"]: if target_host == "%h" and t_port == "%p": w_target = "%h" w_port = "%p" else: t_host_bare, t_port_norm = self._validate_legacy_ssh_hop_fields( target_host, "", t_port ) w_target = f"[{t_host_bare}]" if ":" in t_host_bare else t_host_bare w_port = t_port_norm if t_port_norm != "" else "22" else: w_target = target_host w_port = t_port # Build raw command based on protocol if jh_proto in ["ssh", "mosh"]: cmd = f"ssh -W {w_target}:{w_port}" if inner_proxy_opt: cmd += f" {inner_proxy_opt}" if jh_port != "": cmd += f" -p {jh_port}" if jh_opts != "": cmd += f" {jh_opts}" jh_user = str(jh.get("user", "") or "") user_host = f"{jh_user}@{jh_host}" if jh_user else jh_host cmd += f" {user_host}" elif jh_proto == "ssm": ssm_target = str(jh.get("host", "") or "") if ( ".." in ssm_target or ssm_target.startswith("-") or not _SSM_TARGET_RE.fullmatch(ssm_target) ): raise ValueError(f"Invalid SSM jumphost target: '{ssm_target}'") ssm_user = str(jh.get("user", "") or "") if ssm_user and (ssm_user.startswith("-") or _LEGACY_SSH_UNSAFE_RE.search(ssm_user)): raise ValueError(f"Invalid characters in SSM jumphost user: '{ssm_user}'") ssm_parts = [ "aws", "ssm", "start-session", "--target", ssm_target, "--document-name", "AWS-StartSSHSession", "--parameters", "portNumber=22", ] if isinstance(jh_tags, dict): for tag_key in ("profile", "region"): raw_val = jh_tags.get(tag_key) if raw_val not in (None, ""): tag_str = str(raw_val) if ( ".." in tag_str or tag_str.startswith("-") or not _SSM_TAG_RE.fullmatch(tag_str) ): raise ValueError(f"Invalid SSM jumphost {tag_key}: '{tag_str}'") ssm_parts.extend([f"--{tag_key}", tag_str]) ssm_opts_raw = str(jh.get("options", "") or "").strip() if ssm_opts_raw: if _CONTROL_CHAR_RE.search(ssm_opts_raw) or ( not self._is_unsafe_allowed() and _SSM_UNSAFE_OPTIONS_RE.search(ssm_opts_raw) ): raise ValueError("Invalid characters in SSM jumphost options") try: ssm_opt_tokens = shlex.split(ssm_opts_raw) except ValueError as exc: raise ValueError("Invalid SSM jumphost options: unbalanced quotes") from exc ssm_parts.extend(ssm_opt_tokens) ssm_cmd = shlex.join(ssm_parts) raw_ssh_opts = jh_tags.get("ssh_options", "") if isinstance(jh_tags, dict) else "" ssh_opts = self._validate_and_prepare_ssh_options( raw_ssh_opts, field_name="ssm ssh_options", strip_non_tunnel_flags=True, allow_unsafe=self._is_unsafe_allowed(), connect_timeout=connect_timeout, ) bastion_user_part = f"{ssm_user}@{ssm_target}" if ssm_user else ssm_target outer_parts = ["ssh"] if ssh_opts: outer_parts.extend(shlex.split(ssh_opts)) outer_parts.extend( ["-o", f"ProxyCommand={ssm_cmd}", "-W", f"{w_target}:{w_port}", bastion_user_part] ) cmd = shlex.join(outer_parts) elif jh_proto in ["kubectl", "docker"]: if not jh_host or jh_host.startswith("-") or _LEGACY_SSH_UNSAFE_RE.search(jh_host): raise ValueError(f"Invalid characters in {jh_proto} jumphost host: '{jh_host}'") nc_cmd = "nc" if isinstance(jh_tags, dict) and "nc_command" in jh_tags: nc_cmd = str(jh_tags["nc_command"]) if _CONTROL_CHAR_RE.search(nc_cmd) or ( not self._is_unsafe_allowed() and _SSM_UNSAFE_OPTIONS_RE.search(nc_cmd) ): raise ValueError(f"Invalid nc_command in {jh_proto} jumphost") jh_opt_joined = "" jh_opt_str = str(jh.get("options", "") or "").strip() if jh_opt_str: if _CONTROL_CHAR_RE.search(jh_opt_str): raise ValueError(f"Control characters disallowed in {jh_proto} options") if not self._is_unsafe_allowed() and _SSM_UNSAFE_OPTIONS_RE.search(jh_opt_str): raise ValueError(f"Invalid characters in {jh_proto} options") try: jh_opt_tokens = shlex.split(jh_opt_str) except ValueError as exc: raise ValueError(f"Invalid {jh_proto} options: unbalanced quotes") from exc jh_opt_joined = shlex.join(jh_opt_tokens) if jh_proto == "kubectl": cmd = "kubectl exec " if jh_opt_joined: cmd += f"{jh_opt_joined} " cmd += f"{jh_host} -i -- {nc_cmd} {w_target} {w_port}" else: cmd = "docker " if jh_opt_joined: cmd += f"{jh_opt_joined} " cmd += f"exec -i {jh_host} {nc_cmd} {w_target} {w_port}" else: if include_meta: return "", passwords, inner_meta return "", passwords if include_meta: return cmd, passwords, hop_meta return cmd, passwords @MethodHook def _passtx(self, passwords, *, keyfile=None): # decrypts passwords, used by other methdos. dpass = [] if keyfile is None: keyfile = self.key if keyfile is not None: from Crypto.Cipher import PKCS1_OAEP from Crypto.PublicKey import RSA with open(keyfile) as f: key = RSA.import_key(f.read()) decryptor = PKCS1_OAEP.new(key) for passwd in passwords: if not re.match('^b[\"\'].+[\"\']$', passwd): dpass.append(passwd) else: try: decrypted = decryptor.decrypt(ast.literal_eval(passwd)).decode("utf-8") dpass.append(decrypted) except Exception: # noqa: BLE001 printer.error("Decryption failed: Missing or corrupted key.") printer.info("Verify your RSA key and configuration settings.") sys.exit(1) return dpass @MethodHook def _logfile(self, logfile = None): # translate logs variables and generate logs path. if logfile is None: logfile = self.logs logfile = logfile.replace("${unique}", self.unique) logfile = logfile.replace("${host}", self.host) logfile = logfile.replace("${port}", self.port) logfile = logfile.replace("${user}", self.user) logfile = logfile.replace("${protocol}", self.protocol) now = datetime.datetime.now() dateconf = re.search(r'\$\{date \'(.*)\'}', logfile) if dateconf: logfile = re.sub(r'\$\{date (.*)}',now.strftime(dateconf.group(1)), logfile) return logfile @MethodHook def _logclean(self, logfile, var = False): """Remove special ascii characters and process terminal cursor movements to clean logs.""" from .utils import log_cleaner if not var: try: with open(logfile) as f: t = f.read() except Exception: # noqa: BLE001 return else: t = logfile result = log_cleaner(t) if not var: try: with open(logfile, "w") as f: f.write(result) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Failed writing cleaned log %s: %s", logfile, exc) return else: return result @MethodHook def _savelog(self): '''Save the log buffer to the file at regular intervals if there are changes.''' t = threading.current_thread() prev_size = 0 # Store the previous size of the buffer while getattr(t, "do_run", True): # Check if thread is signaled to stop current_size = self.mylog.tell() # Current size of the buffer # Only save if the buffer size has changed if current_size != prev_size: with open(self.logfile, "w") as f: # Use "w" to overwrite the file f.write(self._logclean(self.mylog.getvalue().decode(), True)) prev_size = current_size # Update the previous size sleep(5) @MethodHook def _filter(self, a): #Set time for last input when using interact self.lastinput = time() return a @MethodHook def _keepalive(self): #Send keepalive ctrl+e when idletime passed without new inputs on interact self.lastinput = time() while True: if time() - self.lastinput >= self.idletime: self.child.sendcontrol("e") self.lastinput = time() sleep(1) def _setup_interact_environment(self, debug=False, logger=None, async_mode=False): try: size = re.search('columns=([0-9]+).*lines=([0-9]+)',str(os.get_terminal_size())) self.child.setwinsize(int(size.group(2)),int(size.group(1))) except OSError: pass if logger and self.protocol != "local": port_str = f":{self.port}" if self.port and self.protocol not in ["ssm", "kubectl", "docker"] else "" logger("success", f"Connected to {self.unique} at {self.host}{port_str} via: {self.protocol}") # Always initialize self.mylog to capture terminal context for the AI Copilot if not hasattr(self, 'mylog'): self.mylog = io.BytesIO() if not async_mode: self.child.logfile_read = self.mylog # Only start disk-logging tasks if logfile is configured if hasattr(self, "logfile") and not async_mode: # Start the _savelog thread (sync mode) log_thread = threading.Thread(target=self._savelog) log_thread.daemon = True log_thread.start() if getattr(self, "missingtext", False) and not async_mode: print(self.child.after.decode(), end="") if self.idletime > 0 and not async_mode: x = threading.Thread(target=self._keepalive) x.daemon = True x.start() if debug and hasattr(self, "mylog") and not async_mode: print(self.mylog.getvalue().decode()) def _teardown_interact_environment(self): if 'logfile' in dir(self) and hasattr(self, 'mylog'): with open(self.logfile, "w") as f: f.write(self._logclean(self.mylog.getvalue().decode(), True)) def _write_clean_logfile(self, raw_log: str) -> None: """Clean and synchronously write raw log output to self.logfile.""" cleaned_log = self._logclean(raw_log, True) with open(self.logfile, "w") as f: f.write(cleaned_log) def _is_child_connpy_active(self, child_fd: int) -> bool: if self.protocol != "local": return False try: fg_pgid = os.tcgetpgrp(child_fd) if fg_pgid <= 0: return False cmdline_path = f"/proc/{fg_pgid}/cmdline" if os.path.exists(cmdline_path): with open(cmdline_path, "rb") as f: raw_args = f.read().split(b"\x00") is_active = False for raw_arg in raw_args: arg_str = raw_arg.decode(errors="ignore") if not arg_str: continue base_name = os.path.basename(arg_str) if base_name in ["conn", "connpy", "connapp"] or "connpy" in arg_str or "connapp" in arg_str: is_active = True break return is_active except Exception as exc: # noqa: BLE001 _LOGGER.debug("Failed checking active connpy process: %s", exc) return False async def _async_interact_loop(self, local_stream, resize_callback, copilot_handler=None): local_stream.setup(resize_callback=resize_callback) self.current_local_stream = local_stream try: child_fd = self.child.child_fd # 1. Flush ghost buffer (Clean UX) ghost_buffer = b'' if getattr(self, 'missingtext', False): # If we are missing the password, we MUST show the password prompt ghost_buffer = (self.child.after or b'') + (self.child.buffer or b'') else: # We auto-logged in. Hide the messy password negotiation and just keep any pending live stream. ghost_buffer = self.child.buffer or b'' # Fix user's pet peeve: Strip leading newlines to avoid the empty lines # the router echoes after receiving the password or blank line. if not getattr(self, 'missingtext', False): ghost_buffer = ghost_buffer.lstrip(b'\r\n ') if ghost_buffer: # Add a single clean newline so it doesn't merge with the Connected message await local_stream.write(b'\r\n' + ghost_buffer) if hasattr(self, 'mylog'): self.mylog.write(b'\n' + ghost_buffer) self.child.buffer = b'' self.child.before = b'' # 2. Set child fd non-blocking flags = fcntl.fcntl(child_fd, fcntl.F_GETFL) fcntl.fcntl(child_fd, fcntl.F_SETFL, flags | os.O_NONBLOCK) loop = asyncio.get_running_loop() child_reader_queue = asyncio.Queue() # Reset and track command byte positions for copilot context navigation # Each entry is (byte_position, command_text_or_None) self.cmd_byte_positions = [(self.mylog.tell() if hasattr(self, 'mylog') else 0, None)] def _child_read_ready(): try: # Increase buffer to 64KB for better high-speed handling data = os.read(child_fd, 65536) if data: child_reader_queue.put_nowait(data) else: child_reader_queue.put_nowait(b'') except BlockingIOError: pass except OSError: child_reader_queue.put_nowait(b'') loop.add_reader(child_fd, _child_read_ready) self.lastinput = time() async def ingress_task(): while True: data = await local_stream.read() if not data: break # Copilot interception if copilot_handler and b'\x00' in data: if self._is_child_connpy_active(child_fd): try: os.write(child_fd, data) except OSError: break self.lastinput = time() continue # Build node info from available metadata and ensure values are strings (not bytes) def to_str(val): if isinstance(val, bytes): return val.decode(errors='replace') return str(val) if val is not None else "unknown" node_info = { "name": to_str(getattr(self, 'unique', 'unknown')), "host": to_str(getattr(self, 'host', 'unknown')) } if isinstance(getattr(self, 'tags', None), dict): node_info["os"] = to_str(self.tags.get("os", "unknown")) node_info["prompt"] = to_str(self.tags.get("prompt", r'>$|#$|\$$|>.$|#.$|\$.$')) # Invoke copilot (async callback handles UI) await copilot_handler(self.mylog.getvalue(), node_info, local_stream, child_fd, self.cmd_byte_positions) continue # Remove any stray \x00 bytes and forward normally clean_data = data.replace(b'\x00', b'') if clean_data: # Track command boundaries when user hits Enter or presses Ctrl+C if hasattr(self, 'mylog') and (b'\r' in clean_data or b'\n' in clean_data or b'\x03' in clean_data): pos = self.mylog.tell() marker_cmd = "CANCELLED" if b'\x03' in clean_data else None self.cmd_byte_positions.append((pos, marker_cmd)) if hasattr(self, 'current_local_stream') and self.current_local_stream is not None: try: await self.current_local_stream.write(f'\x1b]133;B;{pos}\x07'.encode()) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Failed writing OSC 133 marker: %s", exc) try: os.write(child_fd, clean_data) except OSError: break self.lastinput = time() async def egress_task(): # Continue stripping newlines from the live stream until we hit real text skip_newlines = not getattr(self, 'missingtext', False) and not ghost_buffer while True: data = await child_reader_queue.get() if not data: break # Batching Optimization: Drain the queue to batch writes during high-volume bursts # Helps the terminal parse ANSI faster and reduces syscalls. chunks = [data] while not child_reader_queue.empty(): try: extra = child_reader_queue.get_nowait() if not extra: chunks.append(b'') # Re-put EOF later or handle it break chunks.append(extra) except asyncio.QueueEmpty: break has_eof = chunks[-1] == b'' if has_eof: chunks.pop() if chunks: combined_data = b''.join(chunks) if skip_newlines: stripped = combined_data.lstrip(b'\r\n') if stripped: skip_newlines = False combined_data = stripped else: if has_eof: break continue await local_stream.write(combined_data) if hasattr(self, 'mylog'): self.mylog.write(combined_data) if has_eof: break async def keepalive_task(): while True: await asyncio.sleep(1) if time() - self.lastinput >= self.idletime: try: self.child.sendcontrol("e") self.lastinput = time() except Exception as exc: # noqa: BLE001 _LOGGER.debug("Keepalive sendcontrol failed: %s", exc) async def savelog_task(): prev_size = 0 while True: await asyncio.sleep(5) current_size = self.mylog.tell() if current_size != prev_size: try: # Move heavy log cleaning & file I/O to a thread to avoid freezing the interaction loop raw_log = self.mylog.getvalue().decode(errors='replace') await asyncio.to_thread(self._write_clean_logfile, raw_log) prev_size = current_size except Exception as exc: # noqa: BLE001 _LOGGER.debug("Periodic savelog sync failed: %s", exc) async def pwd_tracker_task(): import socket hostname = socket.gethostname() last_cwd = None while True: await asyncio.sleep(0.3) try: child_pid = getattr(self.child, 'pid', None) if child_pid: new_cwd = os.readlink(f"/proc/{child_pid}/cwd") if new_cwd != last_cwd: last_cwd = new_cwd try: os.chdir(new_cwd) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Failed syncing cwd: %s", exc) try: await local_stream.write(f"\033]7;file://{hostname}{new_cwd}\007".encode()) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Failed writing OSC 7 update: %s", exc) if isinstance(self.tags, dict): self.tags["cwd"] = new_cwd except Exception as exc: # noqa: BLE001 _LOGGER.debug("pwd_tracker_task iteration failed: %s", exc) try: # We wait for either the user (ingress) or the child (egress) to finish tasks = [ asyncio.create_task(ingress_task()), asyncio.create_task(egress_task()) ] if self.protocol == "local": tasks.append(asyncio.create_task(pwd_tracker_task())) if self.idletime > 0: tasks.append(asyncio.create_task(keepalive_task())) if hasattr(self, 'logfile') and hasattr(self, 'mylog'): tasks.append(asyncio.create_task(savelog_task())) done, _pending = await asyncio.wait( [tasks[0], tasks[1]], return_when=asyncio.FIRST_COMPLETED ) # If ingress finished first (user quit), give egress a small window to catch up # on the remaining output in the queue. if tasks[0] in done and tasks[1] not in done: try: await asyncio.wait_for(tasks[1], timeout=0.2) except (asyncio.TimeoutError, TimeoutError, asyncio.CancelledError): # noqa: UP041 pass for t in tasks: if t not in done: t.cancel() # Final log sync on thread to avoid losing last lines if hasattr(self, 'logfile') and hasattr(self, 'mylog'): try: raw_log = self.mylog.getvalue().decode(errors='replace') await asyncio.to_thread(self._write_clean_logfile, raw_log) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Final savelog sync failed: %s", exc) finally: loop.remove_reader(child_fd) try: flags = fcntl.fcntl(child_fd, fcntl.F_GETFL) fcntl.fcntl(child_fd, fcntl.F_SETFL, flags & ~os.O_NONBLOCK) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Failed restoring blocking mode on child_fd: %s", exc) finally: self.current_local_stream = None local_stream.teardown() @MethodHook async def inject_commands(self, commands, child_fd, on_inject=None): """ Inject a list of commands into the node's PTY. Handles screen_length_command, history tracking and delays. """ if not commands: return # 0. Clear line os.write(child_fd, b'\x15') await asyncio.sleep(0.1) # 1. Prepare list (prepend screen_length if exists) slc = self.tags.get("screen_length_command") if hasattr(self, 'tags') and isinstance(self.tags, dict) else None to_send = list(commands) if slc and slc not in to_send: # avoid duplicates if already there to_send.insert(0, slc) # 2. Inject one by one for cmd in to_send: # Register in node's official history (SKIP if it's the administrative screen length command) if cmd != slc and hasattr(self, 'cmd_byte_positions') and self.cmd_byte_positions is not None: log_pos = self.mylog.tell() if hasattr(self, 'mylog') else 0 self.cmd_byte_positions.append((log_pos, cmd)) if hasattr(self, 'current_local_stream') and self.current_local_stream is not None: try: await self.current_local_stream.write(f'\x1b]133;B;{log_pos}\x07'.encode()) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Failed writing command boundary marker: %s", exc) # Write physically to PTY os.write(child_fd, (cmd + "\n").encode()) # Notify (e.g., for gRPC or logs) - SKIP for administrative SLC if on_inject and cmd != slc: if asyncio.iscoroutinefunction(on_inject): await on_inject(cmd) else: on_inject(cmd) # Delay to avoid overwhelming the router await asyncio.sleep(0.8) @MethodHook def interact(self, debug=False, logger=None): ''' Asynchronous interactive session using Smart Tunnel architecture. Allows multiplexing I/O and handling SIGWINCH events locally without blocking. ''' connect = self._connect(debug=debug, logger=logger) if connect is True: try: self._setup_interact_environment(debug=debug, logger=logger, async_mode=True) local_stream = LocalStream() def resize_callback(rows, cols): try: self.child.setwinsize(rows, cols) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Failed resizing child window: %s", exc) # Build local copilot handler copilot_handler = self._build_local_copilot_handler() asyncio.run(self._async_interact_loop(local_stream, resize_callback, copilot_handler=copilot_handler)) finally: self._teardown_interact_environment() else: if logger: logger("error", str(connect)) else: printer.error(f"Connection failed: {connect!s}") sys.exit(1) def _build_local_copilot_handler(self): """Build copilot handler for local CLI sessions using rich for rendering.""" config = getattr(self, 'config', None) if hasattr(self, 'config') else None return self._copilot_handler(config) def _copilot_handler(self, config): """Unified copilot handler for local session.""" async def handler(buffer, node_info, stream, child_fd, cmd_byte_positions=None): try: from .cli.terminal_ui import CopilotInterface from .services.ai_service import AIService interface = CopilotInterface( config, history=getattr(stream, 'copilot_history', None), session_state=getattr(stream, 'copilot_state', None) ) # Save history back to stream for persistence in current session stream.copilot_history = interface.history stream.copilot_state = interface.session_state interface.session_state['banner_shown'] = False ai_service = AIService(config) async def on_ai_call(active_buffer, question, chunk_callback, merged_node_info): return await ai_service.aask_copilot( active_buffer, question, node_info=merged_node_info, chunk_callback=chunk_callback ) # Get raw bytes from BytesIO raw_bytes = self.mylog.getvalue() # Stop terminal reading so prompt_toolkit (in run_session) # has exclusive control of stdin without LocalStream interference. if hasattr(stream, 'stop_reading'): stream.stop_reading() elif hasattr(stream, '_loop') and hasattr(stream, 'stdin_fd'): # Fallback if the method is missing (in LocalStream) stream._loop.remove_reader(stream.stdin_fd) try: with copilot_terminal_mode(): while True: action, commands, custom_cmd = await interface.run_session( raw_bytes=raw_bytes, cmd_byte_positions=self.cmd_byte_positions, node_info=node_info, on_ai_call=on_ai_call ) if action in ("send_all", "custom"): cmds_to_send = commands if action == "send_all" else custom_cmd await self.inject_commands(cmds_to_send, child_fd) # Dynamic Wait for Device Prompt Settle prompt_pattern = node_info.get("prompt", r'>$|#$|\$$|>.$|#.$|\$.$') start_t = time() last_len = 0 quiet_count = 0 while time() - start_t < 60: await asyncio.sleep(0.15) cur_bytes = self.mylog.getvalue() if len(cur_bytes) == last_len: quiet_count += 1 else: quiet_count = 0 last_len = len(cur_bytes) clean_txt = self._logclean(cur_bytes.decode(errors='replace'), True).strip() lines = [line.strip() for line in clean_txt.split('\n') if line.strip()] last_line = lines[-1] if lines else "" if quiet_count >= 2 and re.search(prompt_pattern, last_line): break raw_bytes = self.mylog.getvalue() continue if action == "continue": continue break finally: print("\033[2m Returning to session...\033[0m", flush=True) # Restart terminal reading to return to interactive SSH/Telnet mode if hasattr(stream, 'start_reading'): stream.start_reading() elif hasattr(stream, '_loop') and hasattr(stream, 'stdin_fd'): stream._loop.add_reader(stream.stdin_fd, stream._read_ready) os.write(child_fd, b'\x15\r') except Exception as e: # noqa: BLE001 import traceback print(f"\n[ERROR in Copilot Handler] {e}", flush=True) traceback.print_exc() os.write(child_fd, b'\x15\r') return handler @MethodHook def run( self, commands, vars=None, *, folder='', prompt=r'>$|#$|\$$|>.$|#.$|\$.$', stdout=False, timeout=None, logger=None, connect_timeout=None, auth_timeout=None, _default_cmd_timeout=10, unattended=True, attempt_tracker=None, ): ''' Run a command or list of commands on the node and return the output. ### Parameters: - commands (str/list): Commands to run on the node. Should be str or a list of str. You can use variables as {varname} and defining them in optional parameter vars. ### Optional Parameters: - vars (dict): Dictionary containing the definition of variables used in commands parameter. Keys: Variable names. Values: strings. ### Optional Named Parameters: - folder (str): Path where output log should be stored, leave empty to disable logging. - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - stdout (bool):Set True to send the command output to stdout. default False. - timeout (int):Time in seconds for expect to wait for prompt/EOF. default 10. ### Returns: str: Output of the commands you ran on the node. ''' force_ssh = self.protocol == "mosh" effective_protocol = "ssh" if force_ssh else self.protocol try: _, _, eff_cmd, _, _ = resolve_timeouts( effective_protocol, self.tags, getattr(self, "_hop_chain_meta", None) or [], timeout=timeout, connect_timeout=connect_timeout, auth_timeout=auth_timeout, _default_cmd_timeout=_default_cmd_timeout, ) except ValueError as e: err = f"Connection failed code: 12\nInvalid timeout configuration: {e}" self.output = err self.status = 1 if logger: logger("error", f"Connection failed: {err}") return err connect = self._connect( timeout=timeout, logger=logger, force_ssh=force_ssh, connect_timeout=connect_timeout, auth_timeout=auth_timeout, _default_cmd_timeout=_default_cmd_timeout, unattended=unattended, attempt_tracker=attempt_tracker, ) now = datetime.datetime.now().strftime('%Y-%m-%d_%H%M%S') if connect is True: if logger: port_str = f":{self.port}" if self.port and effective_protocol not in ["ssm", "kubectl", "docker"] else "" logger("success", f"Connected to {self.unique} at {self.host}{port_str} via: {effective_protocol}") if isinstance(self.tags, dict) and "prompt" in self.tags: prompt = self.tags["prompt"] prompt_pat = re.compile(prompt.encode("utf-8"), re.DOTALL) expects = [prompt_pat, pexpect.EOF, pexpect.TIMEOUT] output = '' result = 0 if not isinstance(commands, list): commands = [commands] if isinstance(self.tags, dict) and "screen_length_command" in self.tags: commands.insert(0, self.tags["screen_length_command"]) self.mylog = io.BytesIO() self.child.logfile_read = self.mylog for c in commands: if vars is not None: try: c = c.format(**vars) except KeyError as e: self.output = f"Error: Variable {e} not defined in task or inventory" self.status = 1 return self.output result = self.child.expect(expects, timeout=eff_cmd) # Only set terminal size on devices without a # screen_length_command (e.g. Linux/bash servers). # Routers already disable pagination via that command. # After setwinsize, consume any SIGWINCH re-render # prompt (~40ms on bash) with a short timeout. if c == commands[0] and (not isinstance(self.tags, dict) or "screen_length_command" not in self.tags): try: self.child.setwinsize(65535, 65535) except Exception: # noqa: BLE001 try: self.child.setwinsize(10000, 10000) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Fallback setwinsize failed in run: %s", exc) self.child.expect(expects, timeout=1) self.child.sendline(c) if result == 2: break if result != 2: result = self.child.expect(expects, timeout=eff_cmd) self.child.close() output = self._logclean(self.mylog.getvalue().decode("utf-8", errors="replace"), True) if logger: logger("output", output) if folder != '': with open(folder + "/" + self.unique + "_" + now + ".txt", "w") as f: f.write(output) self.output = output if result == 2: self.status = 2 else: self.status = 0 return output else: self.output = connect self.status = 1 if logger: logger("error", f"Connection failed: {connect}") if folder != '': with open(folder + "/" + self.unique + "_" + now + ".txt", "w") as f: f.write(connect) return connect @MethodHook def test( self, commands, expected, vars=None, *, folder='', prompt=r'>$|#$|\$$|>.$|#.$|\$.$', timeout=None, logger=None, connect_timeout=None, auth_timeout=None, _default_cmd_timeout=10, unattended=True, attempt_tracker=None, ): ''' Run a command or list of commands on the node, then check if expected value appears on the output after the last command. ### Parameters: - commands (str/list): Commands to run on the node. Should be str or a list of str. You can use variables as {varname} and defining them in optional parameter vars. - expected (str) : Expected text to appear after running all the commands on the node.You can use variables as {varname} and defining them in optional parameter vars. ### Optional Parameters: - vars (dict): Dictionary containing the definition of variables used in commands and expected parameters. Keys: Variable names. Values: strings. ### Optional Named Parameters: - folder (str): Path where output log should be stored, leave empty to not store logs. - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - timeout (int):Time in seconds for expect to wait for prompt/EOF. default 10. ### Returns: bool: true if expected value is found after running the commands false if prompt is found before. ''' now = datetime.datetime.now().strftime("%Y-%m-%d_%H-%M-%S") force_ssh = self.protocol == "mosh" effective_protocol = "ssh" if force_ssh else self.protocol try: _, _, eff_cmd, _, _ = resolve_timeouts( effective_protocol, self.tags, getattr(self, "_hop_chain_meta", None) or [], timeout=timeout, connect_timeout=connect_timeout, auth_timeout=auth_timeout, _default_cmd_timeout=_default_cmd_timeout, ) except ValueError as e: err = f"Connection failed code: 12\nInvalid timeout configuration: {e}" self.result = None self.output = err self.status = 1 if logger: logger("error", f"Connection failed: {err}") return err connect = self._connect( timeout=timeout, logger=logger, force_ssh=force_ssh, connect_timeout=connect_timeout, auth_timeout=auth_timeout, _default_cmd_timeout=_default_cmd_timeout, unattended=unattended, attempt_tracker=attempt_tracker, ) if connect is True: if logger: port_str = f":{self.port}" if self.port and effective_protocol not in ["ssm", "kubectl", "docker"] else "" logger("success", f"Connected to {self.unique} at {self.host}{port_str} via: {effective_protocol}") if isinstance(self.tags, dict) and "prompt" in self.tags: prompt = self.tags["prompt"] prompt_pat = re.compile(prompt.encode("utf-8"), re.DOTALL) expects = [prompt_pat, pexpect.EOF, pexpect.TIMEOUT] output = '' result = 0 if not isinstance(commands, list): commands = [commands] if not isinstance(expected, list): expected = [expected] if isinstance(self.tags, dict) and "screen_length_command" in self.tags: commands.insert(0, self.tags["screen_length_command"]) self.mylog = io.BytesIO() self.child.logfile_read = self.mylog for c in commands: if vars is not None: try: c = c.format(**vars) except KeyError as e: self.output = f"Error: Variable {e} not defined in task or inventory" self.status = 1 return self.output result = self.child.expect(expects, timeout=eff_cmd) if c == commands[0] and (not isinstance(self.tags, dict) or "screen_length_command" not in self.tags): try: self.child.setwinsize(65535, 65535) except Exception: # noqa: BLE001 try: self.child.setwinsize(10000, 10000) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Fallback setwinsize failed in test: %s", exc) self.child.expect(expects, timeout=1) self.child.sendline(c) if result == 2: break if result != 2: result = self.child.expect(expects, timeout=eff_cmd) self.child.close() output = self._logclean(self.mylog.getvalue().decode("utf-8", errors="replace"), True) if logger: logger("output", output) if folder != '': with open(folder + "/" + self.unique + "_" + now + ".txt", "w") as f: f.write(output) self.output = output if result in [0, 1]: # lastcommand = commands[-1] # if vars is not None: # lastcommand = lastcommand.format(**vars) # last_command_index = output.rfind(lastcommand) # cleaned_output = output[last_command_index + len(lastcommand):].strip() self.result = {} for e in expected: if vars is not None: e = e.format(**vars) updatedprompt = re.sub(r'(?<!\\)\$', '', prompt) cleaned_output = output try: newpattern = f".*({updatedprompt}).*{e}.*" cleaned_output = re.sub(newpattern, '', cleaned_output) except re.error: try: escaped_e = re.escape(e) newpattern = f".*({updatedprompt}).*{escaped_e}.*" cleaned_output = re.sub(newpattern, '', cleaned_output) except re.error: pass if e in cleaned_output: self.result[e] = True else: try: if re.search(e, cleaned_output): self.result[e] = True else: self.result[e] = False except re.error: self.result[e] = False self.status = 0 return self.result if result == 2: self.result = None self.status = 2 return output else: self.result = None self.output = connect self.status = 1 return connect @staticmethod def _inject_ssh_timeouts(raw_opts: str, connect_timeout: int | None) -> str: """Append -o ConnectTimeout and -o ServerAliveInterval=15 unless already present.""" opts_str = str(raw_opts).strip() if raw_opts else "" if connect_timeout is None: return opts_str ct_val = validate_strict_timeout_int(connect_timeout, "connect_timeout") tokens = shlex.split(opts_str) if opts_str else [] existing_keys = _extract_ssh_o_keys(tokens) if "connecttimeout" not in existing_keys and "connecttimeout" in _ALLOWED_SSH_O_KEYS: tokens.extend(["-o", f"ConnectTimeout={ct_val}"]) if ( "serveraliveinterval" not in existing_keys and "serveraliveinterval" in _ALLOWED_SSH_O_KEYS ): tokens.extend(["-o", "ServerAliveInterval=15"]) return shlex.join(tokens) def _effective_jumphost_opt(self, connect_timeout: int | None = None) -> str: """Return ProxyCommand option, rebuilding hop chain with connect_timeout when set.""" if ( connect_timeout is not None and getattr(self, "_jumphost_name", "") and getattr(self, "config", "") != "" ): chain_res = self._build_jumphost_chain( self._jumphost_name, self.config, include_meta=True, connect_timeout=connect_timeout, ) raw_cmd = chain_res[0] if raw_cmd: escaped = raw_cmd.replace("\\", "\\\\").replace('"', '\\"') return f'-o ProxyCommand="{escaped}"' return "" return self.jumphost @MethodHook def _generate_ssh_sftp_cmd( self, force_ssh=False, allow_reverse_tunnel_port=None, *, connect_timeout=None, user_override=None, ): self._validate_base_fields(check_port=True) is_from_mosh = ( self.protocol == "mosh" or getattr(self, "_orig_protocol", "") == "mosh" ) if not is_from_mosh: self._validate_ssh_options() proto = "ssh" if force_ssh else self.protocol eff_user = self.user if user_override is None else user_override if eff_user: u_s = str(eff_user) if u_s.startswith("-") or _LEGACY_SSH_UNSAFE_RE.search(u_s): raise ValueError(f"Invalid characters in user: '{u_s}'") cmd = proto if is_from_mosh: host_bare, port_s, raw_opts = self._validate_mosh_ssh_fields( self.host, eff_user, self.port, self.tags, allow_reverse_tunnel_port=allow_reverse_tunnel_port, ) if port_s: cmd += (" -p " if proto == "ssh" else " -P ") + port_s if raw_opts and proto == "sftp": sftp_tokens = [] toks = shlex.split(raw_opts) i = 0 while i < len(toks): t = toks[i] if t in ("-X", "-x", "-Y", "-t", "-A", "-a"): i += 1 elif t == "-m": i += 2 elif t.startswith("-m") and len(t) > 2: i += 1 else: sftp_tokens.append(t) i += 1 opts = shlex.join(sftp_tokens) else: opts = str(raw_opts).strip() if raw_opts else "" opts = self._inject_ssh_timeouts(opts, connect_timeout) if opts: cmd += " " + opts target_h = f"[{host_bare}]" if (proto == "sftp" and ":" in host_bare) else host_bare else: if self.port != "" and self.port is not None: if proto == "ssh": cmd += " -p " + str(self.port) elif proto == "sftp": cmd += " -P " + str(self.port) raw_opts = self.options opts = "" if raw_opts: opts = str(raw_opts).strip() if proto == "sftp": opts = re.sub(r'(?<!\S)-[XxtTAaNf]\b', '', opts).strip() opts = self._inject_ssh_timeouts(opts, connect_timeout) if opts: cmd += " " + opts target_h = self.host jh_opt = self._effective_jumphost_opt(connect_timeout=connect_timeout) if jh_opt: cmd += " " + jh_opt user_host = f"{eff_user}@{target_h}" if eff_user else target_h cmd += f" {user_host}" return cmd @MethodHook def _generate_mosh_cmd(self, *, connect_timeout=None, user_override=None): eff_user = self.user if user_override is None else user_override if str(self.host).startswith("-"): raise ValueError("Host cannot start with '-'") if eff_user and str(eff_user).startswith("-"): raise ValueError("User cannot start with '-'") if not self.host or re.search(r'[\s;|&$`><"\'\\]', str(self.host)): raise ValueError(f"Invalid characters in host: '{self.host}'") if eff_user and re.search(r'[\s;|&$`><"\'\\]', str(eff_user)): raise ValueError(f"Invalid characters in user: '{eff_user}'") cmd_parts = ["mosh"] if isinstance(self.tags, dict): if self.tags.get("mosh_server"): server_bin = str(self.tags["mosh_server"]).strip() if server_bin: cmd_parts.append(f"--server={shlex.quote(server_bin)}") if self.tags.get("mosh_udp_port"): udp_port = str(self.tags["mosh_udp_port"]).strip() if udp_port: if not re.match(r"^\d+(:\d+)?$", udp_port): raise ValueError( f"Invalid mosh_udp_port '{udp_port}': must be PORT or PORT1:PORT2" ) cmd_parts.append(f"-p {shlex.quote(udp_port)}") ssh_parts = ["ssh"] if self.port != "" and self.port is not None: port_s = str(self.port).strip() if port_s: if not re.fullmatch(r"^\d+$", port_s) or not (1 <= int(port_s) <= 65535): raise ValueError(f"Invalid TCP SSH port '{self.port}'") ssh_parts.append(f"-p {port_s}") ssh_opts = "" if isinstance(self.tags, dict) and self.tags.get("mosh_ssh_options"): ssh_opts = str(self.tags["mosh_ssh_options"]).strip() if ssh_opts: if not self._is_unsafe_allowed() and re.search( r'(?:LocalCommand|ProxyCommand|PermitLocalCommand|KnownHostsCommand)', ssh_opts, re.IGNORECASE, ): raise ValueError("mosh_ssh_options cannot contain LocalCommand or ProxyCommand") try: shlex.split(ssh_opts) except ValueError as exc: raise ValueError("Invalid mosh_ssh_options: unbalanced quotes") from exc if connect_timeout is not None: ssh_opts = self._inject_ssh_timeouts(ssh_opts, connect_timeout) if ssh_opts: ssh_parts.append(ssh_opts) jh_opt = self._effective_jumphost_opt(connect_timeout=connect_timeout) if jh_opt: ssh_parts.append(jh_opt) if len(ssh_parts) > 1: raw_ssh = " ".join(ssh_parts) cmd_parts.append(f"--ssh={shlex.quote(raw_ssh)}") if self.options: opts = str(self.options).strip() if opts: if re.search(r'--(?:ssh|server|client)(?:=|\s|$)', opts): raise ValueError("Options cannot override --ssh, --server or --client for mosh") if not self._is_unsafe_allowed() and re.search( r'(?:LocalCommand|ProxyCommand|PermitLocalCommand|KnownHostsCommand)', opts, re.IGNORECASE, ): raise ValueError("Options cannot contain LocalCommand or ProxyCommand") try: shlex.split(opts) except ValueError as exc: raise ValueError("Invalid options: unbalanced quotes") from exc cmd_parts.append(opts) user_host = f"{eff_user}@{self.host}" if eff_user else self.host cmd_parts.extend(["--", user_host]) return " ".join(cmd_parts) @MethodHook def _generate_telnet_cmd(self): self._validate_base_fields(check_port=True) self._validate_options_and_safety() cmd = f"telnet {self.host}" if self.port: cmd += f" {self.port}" if self.options: cmd += f" {self.options}" return cmd @MethodHook def _generate_kube_cmd(self): self._validate_base_fields(check_port=False) self._validate_options_and_safety() kube_command = self.tags.get("kube_command", "/bin/bash") if isinstance(self.tags, dict) else "/bin/bash" if not self._is_unsafe_allowed() and kube_command: k_str = str(kube_command) if any(c in k_str for c in ("\n", "\r", "\x00")): raise ValueError("kube_command cannot contain newlines or null bytes") try: shlex.split(k_str) except ValueError as e: raise ValueError(f"Invalid kube_command: unbalanced quotes ({e})") from e cmd = f"kubectl exec {self.options} {self.host} -it --" cmd += f" {kube_command}" return cmd @MethodHook def _generate_docker_cmd(self): self._validate_base_fields(check_port=False) self._validate_options_and_safety() docker_command = self.tags.get("docker_command", "/bin/bash") if isinstance(self.tags, dict) else "/bin/bash" if not self._is_unsafe_allowed() and docker_command: d_str = str(docker_command) if any(c in d_str for c in ("\n", "\r", "\x00")): raise ValueError("docker_command cannot contain newlines or null bytes") try: shlex.split(d_str) except ValueError as e: raise ValueError(f"Invalid docker_command: unbalanced quotes ({e})") from e cmd = f"docker {self.options} exec -it {self.host}" cmd += f" {docker_command}" return cmd @MethodHook def _generate_ssm_cmd(self): self._validate_base_fields(check_port=False) self._validate_options_and_safety() region = self.tags.get("region", "") if isinstance(self.tags, dict) else "" profile = self.tags.get("profile", "") if isinstance(self.tags, dict) else "" if not self._is_unsafe_allowed(): for field_name, field_val in [("region", region), ("profile", profile)]: if field_val: f_str = str(field_val) if f_str.startswith("-"): raise ValueError(f"SSM tag '{field_name}' cannot start with '-': '{field_val}'") if re.search(r'[\s\x00-\x1f\x7f;|&$`><"\']', f_str): raise ValueError(f"Invalid characters in SSM tag '{field_name}': '{field_val}'") cmd = f"aws ssm start-session --target {self.host}" if region: cmd += f" --region {region}" if profile: cmd += f" --profile {profile}" if self.options: cmd += f" {self.options}" return cmd @MethodHook def _get_cmd( self, force_ssh=False, allow_reverse_tunnel_port=None, *, connect_timeout=None, user_override=None, ): if force_ssh or self.protocol in ["ssh", "sftp"]: return self._generate_ssh_sftp_cmd( force_ssh=force_ssh, allow_reverse_tunnel_port=allow_reverse_tunnel_port, connect_timeout=connect_timeout, user_override=user_override, ) elif self.protocol == "mosh": return self._generate_mosh_cmd( connect_timeout=connect_timeout, user_override=user_override, ) elif self.protocol == "telnet": return self._generate_telnet_cmd() elif self.protocol == "kubectl": return self._generate_kube_cmd() elif self.protocol == "docker": return self._generate_docker_cmd() elif self.protocol == "ssm": return self._generate_ssm_cmd() elif self.protocol == "local": return self.host else: printer.error(f"Invalid protocol: {self.protocol}") sys.exit(1) def _spawn_child(self, args, protocol=None, encoding=None, *, _secrets=()): if protocol is None: protocol = getattr(self, "protocol", "") env = None if protocol == "mosh": env = os.environ.copy() if not any( "utf-8" in env.get(k, "").lower() or "utf8" in env.get(k, "").lower() for k in ("LC_ALL", "LC_CTYPE", "LANG") ): env["LC_ALL"] = "C.UTF-8" env.setdefault("TERM", "xterm-256color") spawn_kwargs = {} if env is not None: spawn_kwargs["env"] = env if encoding is not None: spawn_kwargs["encoding"] = encoding try: return pexpect.spawn(args[0], args[1:], **spawn_kwargs), None except Exception as exc: # noqa: BLE001 sanitized = sanitize_exception( exc, code="SPAWN_ERROR", secrets=_secrets, context_label="Connection failed", ) return None, str(sanitized) def _extract_auth_budgets(self) -> tuple[int, int | None, int | None, int | None]: cfg_dict = ( self.config.config if (self.config and hasattr(self.config, "config") and isinstance(self.config.config, dict)) else {} ) tags_dict = self.tags if isinstance(self.tags, dict) else {} def _pick(key: str, default_val): if key in tags_dict and tags_dict[key] is not None: return tags_dict[key] if key in cfg_dict and cfg_dict[key] is not None: return cfg_dict[key] return default_val max_auth_prompts = validate_strict_int_range( _pick("max_auth_prompts", DEFAULT_MAX_AUTH_PROMPTS), "max_auth_prompts", MIN_AUTH_PROMPTS, MAX_AUTH_PROMPTS_CAP, ) raw_total = _pick("max_total_auth_attempts", None) max_total_auth_attempts = ( None if raw_total is None else validate_strict_int_range( raw_total, "max_total_auth_attempts", MIN_TOTAL_AUTH_ATTEMPTS, MAX_TOTAL_AUTH_ATTEMPTS_CAP, ) ) raw_hop = _pick("max_hop_host_attempts", None) max_hop_host_attempts = ( None if raw_hop is None else validate_strict_int_range( raw_hop, "max_hop_host_attempts", MIN_HOP_HOST_ATTEMPTS, MAX_HOP_HOST_ATTEMPTS_CAP, ) ) raw_global_user = _pick("max_global_user_attempts", None) max_global_user_attempts = ( None if raw_global_user is None else validate_strict_int_range( raw_global_user, "max_global_user_attempts", 1, 1000, ) ) return ( max_auth_prompts, max_total_auth_attempts, max_hop_host_attempts, max_global_user_attempts, ) @staticmethod def _emit_aaa_fallback_log( logger, *, unique: str, host: str, protocol: str, user: str, label: str, secrets: list[str], ) -> None: raw_msg = ( f"[AAA-FALLBACK] Activating backup credentials ({label}) " f"for node={unique} host={host} proto={protocol} user={user or '<default>'}" ) safe_msg = sanitize_log_message(raw_msg, secrets=secrets) if logger: try: logger("warning", safe_msg) return except Exception: # noqa: BLE001 _LOGGER.debug("Fallback logger failed; falling back to stderr") with suppress(Exception): sys.stderr.write(safe_msg + "\n") sys.stderr.flush() def _build_local_decryptor(self): decryptor_cache = {} def _decrypt_one(cipher_text: str) -> str: if not re.match(r'^b["\'].+["\']$', cipher_text, re.DOTALL): return cipher_text if "fn" not in decryptor_cache: keyfile = getattr(self, "key", None) if not keyfile: raise SanitizedAuthError("No RSA key configured", code="AUTH_FAILED") from Crypto.Cipher import PKCS1_OAEP from Crypto.PublicKey import RSA with open(keyfile) as kf: rsa_key = RSA.import_key(kf.read()) decryptor_cache["fn"] = PKCS1_OAEP.new(rsa_key) raw_bytes = ast.literal_eval(cipher_text) return decryptor_cache["fn"].decrypt(raw_bytes).decode("utf-8") return _decrypt_one def _resolve_runtime_credentials( self, *, allow_fallback: bool, unattended: bool, ) -> tuple[list[RuntimeAuthCandidate], list[list[str]], list[str]]: profiles_map = ( getattr(self.config, "profiles", {}) if (getattr(self, "config", "") != "" and self.config is not None) else {} ) local_decrypt = self._build_local_decryptor() passtx_desc = type(self).__dict__.get("_passtx") passtx_mocked = "_passtx" in self.__dict__ or not isinstance(passtx_desc, MethodHook) def _decrypt_plain_list(specs: list[str]) -> list[str]: if not specs: return [] if passtx_mocked or not unattended: return list(self._passtx(specs)) return [local_decrypt(s) for s in specs] def _expand_spec(spec: str | tuple[str, ...]) -> list[str]: items = list(spec) if isinstance(spec, (tuple, list)) else ([spec] if spec != "" else []) out: list[str] = [] for item in items: if not isinstance(item, str) or item == "": continue if is_compose_expression(item): variants = parse_compose_expression( item, profiles=profiles_map, decrypt_fn=local_decrypt, max_depth=MAX_PROFILE_DEPTH, max_variants=MAX_COMPOSE_VARIANTS, ) out.extend(variants) else: out.extend(_decrypt_plain_list([item])) return out candidates_src = list(getattr(self, "_auth_candidates", ())) if not candidates_src: # Compatibility if a subclass or test mutated self.password directly raw_pw_list = self.password if isinstance(self.password, list) else [self.password] non_empty = tuple(p for p in raw_pw_list if isinstance(p, str) and p != "") if non_empty or self.user: candidates_src = [ AuthCandidate( user=str(self.user or ""), password_spec=non_empty if len(non_empty) > 1 else (non_empty[0] if non_empty else ""), is_fallback=False, label="primary", ) ] runtime_candidates: list[RuntimeAuthCandidate] = [] raw_secrets: list[str] = [] for cand in candidates_src: if cand.is_fallback and not allow_fallback: continue if isinstance(cand.password_spec, tuple): raw_secrets.extend(s for s in cand.password_spec if isinstance(s, str) and s) elif isinstance(cand.password_spec, str) and cand.password_spec: raw_secrets.append(cand.password_spec) expanded_pws = _expand_spec(cand.password_spec) raw_secrets.extend(p for p in expanded_pws if isinstance(p, str) and p) if expanded_pws: for pw_val in expanded_pws: runtime_candidates.append( RuntimeAuthCandidate( user=cand.user, password=pw_val, has_password=True, is_fallback=cand.is_fallback, label=cand.label, ) ) else: runtime_candidates.append( RuntimeAuthCandidate( user=cand.user, password="", has_password=False, is_fallback=cand.is_fallback, label=cand.label, ) ) hop_runtime_passwords: list[list[str]] = [] for hop in getattr(self, "_jumphost_hops", ()): h_pws = _expand_spec(hop.get("passwords", ())) raw_secrets.extend(p for p in h_pws if isinstance(p, str) and p) hop_runtime_passwords.append(h_pws) return runtime_candidates, hop_runtime_passwords, raw_secrets def _disambiguate_prompt(self, line: str) -> tuple[str, int | None]: """Classify password prompt line strictly using exact host boundaries.""" tags_dict = self.tags if isinstance(self.tags, dict) else {} target_names = [str(self.host)] if tags_dict.get("fqdn"): target_names.append(str(tags_dict["fqdn"])) matched_target = any( host_exact_re(h).search(line) for h in target_names if h ) matched_hops: list[int] = [] for idx, hop in enumerate(getattr(self, "_jumphost_hops", ())): h_names = [hop.get("host", "")] if hop.get("resolved_fqdn"): h_names.append(str(hop["resolved_fqdn"])) if any(host_exact_re(h).search(line) for h in h_names if h): matched_hops.append(idx) total_matches = len(matched_hops) + (1 if matched_target else 0) if total_matches > 1: return "conflict", None if matched_hops: return "hop", matched_hops[0] if matched_target: return "target", None return "ambiguous", None @MethodHook def _connect( self, debug=False, timeout=None, max_attempts=3, logger=None, force_ssh=False, allow_reverse_tunnel_port=None, *, connect_timeout=None, auth_timeout=None, _default_cmd_timeout=10, _default_max_total_seconds=None, clock=_time_mod.monotonic, unattended=False, attempt_tracker=None, ): self.__dict__.pop("missingtext", None) self.last_fallback_used = False effective_protocol = "ssh" if force_ssh else self.protocol if effective_protocol == "mosh" and shutil.which("mosh") is None: return "Connection failed: mosh binary not found in PATH" hop_meta = getattr(self, "_hop_chain_meta", None) or [] try: validate_strict_timeout_int( max_attempts, "max_attempts", min_val=1, max_val=MAX_STAGE_TIMEOUT_CAP, ) eff_ct, eff_at, _eff_cmd, max_ext, max_total = resolve_timeouts( effective_protocol, self.tags, hop_meta, timeout=timeout, connect_timeout=connect_timeout, auth_timeout=auth_timeout, _default_cmd_timeout=_default_cmd_timeout, _default_max_total_seconds=_default_max_total_seconds, ) except ValueError as e: return f"Connection failed code: 12\nInvalid timeout configuration: {e}" try: ( max_auth_prompts, max_total_auth_attempts, max_hop_host_attempts, max_global_user_attempts, ) = self._extract_auth_budgets() except ValueError as exc: san = sanitize_exception( exc, code="AUTH_FAILED", context_label="invalid auth budget config", ) return str(san) if effective_protocol == "local": cmd = self._get_cmd() args = shlex.split(cmd) child, err = self._spawn_child(args, protocol=effective_protocol) if err: return err self.child = child from pexpect import fdpexpect self.raw_child = fdpexpect.fdspawn(self.child.child_fd) if self.logs != '': self.logfile = self._logfile() return True cfg_dict = ( self.config.config if (self.config and hasattr(self.config, "config") and isinstance(self.config.config, dict)) else {} ) tags_dict = self.tags if isinstance(self.tags, dict) else {} allow_fallback = not (tags_dict.get("allow_fallback") is False) disable_insecure_hk = bool( getattr(self, "disable_fallback_on_insecure_hostkey", False) or tags_dict.get("disable_fallback_on_insecure_hostkey") or cfg_dict.get("disable_fallback_on_insecure_hostkey") ) if ( allow_fallback and disable_insecure_hk and has_insecure_hostkey_checking( self.options, self.tags, getattr(self, "_jumphost_hops", ()), ) ): allow_fallback = False raw_secrets: list[str] = [] try: runtime_candidates, hop_runtime_passwords, raw_secrets = self._resolve_runtime_credentials( allow_fallback=allow_fallback, unattended=unattended, ) except Exception as exc: # noqa: BLE001 san = sanitize_exception( exc, code="AUTH_FAILED", secrets=raw_secrets, context_label="credential resolution failed", ) return str(san) has_configured_passwords = any(c.has_password for c in runtime_candidates) use_auth_chain = bool(unattended or has_configured_passwords) if self.logs != '': self.logfile = self._logfile() default_prompt = r'>$|#$|\$$|>.$|#.$|\$.$' prompt = tags_dict.get("prompt", default_prompt) if tags_dict else default_prompt password_prompt = ( r'[pP]assword:|[uU]sername:' if effective_protocol != 'telnet' else r'[pP]assword:' ) prompt_unanchored = "|".join(t.removesuffix("$") for t in prompt.split("|")) mosh_prompt = r"(?:" + prompt_unanchored + r")\s*(?:\x1b\[[0-9;?]*[a-zA-Z])*$" def _precompile_user_pat(pat_str: str): try: pat_str.encode("ascii") except UnicodeEncodeError: return re.compile(pat_str.encode("utf-8"), re.DOTALL) return pat_str user_prompt_pat = _precompile_user_pat(prompt) mosh_prompt_pat = _precompile_user_pat(mosh_prompt) expects = { "ssh": [ 'yes/no', r'(?m:^(?:(?:ssh|sftp):[^\r\n]{1,256} )?Connection refused(?:\r?\n))', r'(?im:^(?:(?:ssh|sftp|debug\d+):[^\r\n]{1,256}not supported|Permission denied \([^)\r\n]{1,256}\)\.)(?:\r?\n))', r'(?im:^(?:(?:ssh|sftp):[^\r\n]{1,256}Invalid|usage:\s*(?:ssh|sftp)\b[^\r\n]{0,256})(?:\r?\n))', 'ssh-keygen.*"', r'(?im:^(?:(?:ssh|sftp):[^\r\n]{1,256}(?:Operation timed out|Connection timed out)|kex_exchange_identification:[^\r\n]{1,256}timed out|Connection timed out during banner exchange)(?:\r?\n))', r'(?im:^(?:ssh|sftp|ssh_exchange_identification):[^\r\n]{1,256}(?:Resource temporarily unavailable|Name or service not known|Temporary failure in name resolution|No address associated with hostname|unavailable)(?:\r?\n))', r'(?im:^(?:Connection to [^\r\n]{1,256} closed(?: by remote host)?\.?|Connection closed by (?:remote host|foreign host|authenticating user [^\r\n]{1,128}|[^\r\n]{1,256} port \d{1,5})|(?:kex|ssh)_exchange_identification: Connection closed[^\r\n]{0,256})(?:\r?\n))', password_prompt, user_prompt_pat, 'suspend', pexpect.EOF, pexpect.TIMEOUT, r'(?im:^(?:(?:ssh|sftp):[^\r\n]{1,256})?No route to host(?:\r?\n))', r'(?im:^(?:ssh|sftp):[^\r\n]{1,256}resolve hostname[^\r\n]{0,256}(?:\r?\n))', r'(?im:^(?:(?:ssh|sftp):|Unable to negotiate with )[^\r\n]{1,256}no matching[^\r\n]{0,256}(?:\r?\n))', r'(?im:^Bad (?:owner|permissions)[^\r\n]{0,256}(?:\r?\n))', ], "sftp": [ 'yes/no', r'(?m:^(?:(?:ssh|sftp):[^\r\n]{1,256} )?Connection refused(?:\r?\n))', r'(?im:^(?:(?:ssh|sftp|debug\d+):[^\r\n]{1,256}not supported|Permission denied \([^)\r\n]{1,256}\)\.)(?:\r?\n))', r'(?im:^(?:(?:ssh|sftp):[^\r\n]{1,256}Invalid|usage:\s*(?:ssh|sftp)\b[^\r\n]{0,256})(?:\r?\n))', 'ssh-keygen.*"', r'(?im:^(?:(?:ssh|sftp):[^\r\n]{1,256}(?:Operation timed out|Connection timed out)|kex_exchange_identification:[^\r\n]{1,256}timed out|Connection timed out during banner exchange)(?:\r?\n))', r'(?im:^(?:ssh|sftp|ssh_exchange_identification):[^\r\n]{1,256}(?:Resource temporarily unavailable|Name or service not known|Temporary failure in name resolution|No address associated with hostname|unavailable)(?:\r?\n))', r'(?im:^(?:Connection to [^\r\n]{1,256} closed(?: by remote host)?\.?|Connection closed by (?:remote host|foreign host|authenticating user [^\r\n]{1,128}|[^\r\n]{1,256} port \d{1,5})|(?:kex|ssh)_exchange_identification: Connection closed[^\r\n]{0,256})(?:\r?\n))', password_prompt, user_prompt_pat, 'suspend', pexpect.EOF, pexpect.TIMEOUT, r'(?im:^(?:(?:ssh|sftp):[^\r\n]{1,256})?No route to host(?:\r?\n))', r'(?im:^(?:ssh|sftp):[^\r\n]{1,256}resolve hostname[^\r\n]{0,256}(?:\r?\n))', r'(?im:^(?:(?:ssh|sftp):|Unable to negotiate with )[^\r\n]{1,256}no matching[^\r\n]{0,256}(?:\r?\n))', r'(?im:^Bad (?:owner|permissions)[^\r\n]{0,256}(?:\r?\n))', ], "telnet": [ r'[uU]sername:', r'(?im:^(?:telnet:[^\r\n]{1,256} )?(?:Unable to connect to remote host: )?Connection refused(?:\r?\n))', r'(?im:^(?:telnet:[^\r\n]{1,256}not supported|[^\r\n]{0,64}Authentication not supported)(?:\r?\n))', r'(?im:^(?:telnet:|usage:\s*telnet\b)[^\r\n]{0,256}(?:invalid|unrecognized option)[^\r\n]{0,256}(?:\r?\n))', 'ssh-keygen.*"', r'(?im:^(?:telnet:[^\r\n]{1,256}(?:Operation timed out|Connection timed out)|Connection timed out)(?:\r?\n))', r'(?im:^(?:telnet:[^\r\n]{1,256}(?:Name or service not known|Temporary failure in name resolution|unavailable)|[^\r\n]{0,128}: Name or service not known)(?:\r?\n))', r'(?im:^(?:Connection closed by (?:foreign host|remote host)|telnet:[^\r\n]{1,256}closed)(?:\r?\n))', password_prompt, user_prompt_pat, 'suspend', pexpect.EOF, pexpect.TIMEOUT, r'(?im:^(?:telnet:[^\r\n]{1,256})?No route to host(?:\r?\n))', r'(?im:^telnet:[^\r\n]{1,256}resolve hostname[^\r\n]{0,256}(?:\r?\n))', r'(?im:^telnet:[^\r\n]{1,256}no matching[^\r\n]{0,256}(?:\r?\n))', r'(?im:^Bad (?:owner|permissions)[^\r\n]{0,256}(?:\r?\n))', ], "kubectl": [ r'[uU]sername:', r'[rR]efused', r'[Ee]rror', 'DEPRECATED', pexpect.TIMEOUT, password_prompt, user_prompt_pat, pexpect.EOF, "expired|invalid", ], "docker": [ r'[uU]sername:', 'Cannot', r'[Ee]rror', 'failed', 'not a docker command', 'unknown', 'unable to resolve', pexpect.TIMEOUT, password_prompt, user_prompt_pat, pexpect.EOF, ], "ssm": [ r'[uU]sername:', r'(?im:^(?:Cannot (?:perform start-session|connect to instance|start session)[^\r\n]{0,256})(?:\r?\n))', r'(?im:^(?:An error occurred \([^)\r\n]{1,128}\)[^\r\n]{0,256}|aws: error:[^\r\n]{1,512}|Error: (?:Target|An error|Unable|The security token|Invalid|AccessDenied|SessionManager)[^\r\n]{1,256})(?:\r?\n))', r'(?im:^(?:TargetNotConnected[^\r\n]{0,256}|(?:SessionManagerPlugin|Starting session|An error occurred)[^\r\n]{0,256}failed[^\r\n]{0,256})(?:\r?\n))', 'SessionManagerPlugin', r'(?im:^(?:Unknown(?:Error|ClientException)[^\r\n]{0,256}|An error occurred \([^)\r\n]{0,128}Unknown[^)\r\n]{0,128}\)[^\r\n]{0,256}|aws: [^\r\n]{1,256}invalid choice[^\r\n]{0,256})(?:\r?\n))', r'(?im:^(?:Could not resolve host|Unable to locate credentials|Unable to resolve [^\r\n]{1,256})(?:\r?\n))', pexpect.TIMEOUT, password_prompt, user_prompt_pat, pexpect.EOF, ], } expects["mosh"] = [ 'yes/no', r'(?:ssh: connect to host .* port .*: Connection refused|Connection refused)', r'(?:(?:ssh|mosh): .*supported|Permission denied \([^)\r\n]{1,256}\)\.)', r'(?:(?:ssh|mosh): (?:Invalid|usage)|Unknown option:)', 'ssh-keygen.*"', r'(?:ssh: connect to host .* port .*: Connection timed out|mosh: .* timed out)', r'(?:ssh|mosh): .*unavailable', r'(?:Connection to .* closed|Connection closed by remote host)', password_prompt, mosh_prompt_pat, 'suspend', pexpect.EOF, pexpect.TIMEOUT, "No route to host", "resolve hostname", r'(?:ssh|mosh): .*no matching', r"[bB]ad (owner|permissions)", "mosh-server:.*not found|command not found", r"(?:Did not find mosh server startup message|(?:mosh: )?Nothing received from server on UDP port \d+\.?|Nothing received from server)", "needs a UTF-8 native locale to run|requires a UTF-8 locale|locale.*not available", ] compiled_expects = compile_expects(expects) error_indices = { "ssh": [1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 16], "sftp": [1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 16], "telnet": [1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 16], "kubectl": [1, 2, 3, 4, 8], "docker": [1, 2, 3, 4, 5, 6, 7], "ssm": [1, 2, 3, 4, 5, 6, 7], "mosh": [1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 16, 17, 18, 19], } eof_indices = { "ssh": [8, 9, 10, 11], "sftp": [8, 9, 10, 11], "telnet": [8, 9, 10, 11], "kubectl": [5, 6, 7], "docker": [8, 9, 10], "ssm": [8, 9, 10], "mosh": [8, 9, 10, 11], } initial_indices = { "ssh": [0], "sftp": [0], "telnet": [0], "kubectl": [0], "docker": [0], "ssm": [0], "mosh": [0], } def _to_bytes(val) -> bytes: if val is None: return b"" if isinstance(val, bytes): return val return str(val).encode("utf-8", errors="replace") def _to_str(val) -> str: if val is None: return "" if isinstance(val, bytes): return val.decode("utf-8", errors="replace") return str(val) tracker = ( attempt_tracker if attempt_tracker is not None else AuthAttemptTracker( default_max_host_attempts=DEFAULT_MAX_TOTAL_AUTH_ATTEMPTS, default_max_hop_attempts=DEFAULT_MAX_HOP_HOST_ATTEMPTS, clock=clock, ) ) deadline = clock() + max_total budget_warned = False proto_expects = compiled_expects[effective_protocol] pw_prompt_idx = 5 if effective_protocol == "kubectl" else 8 suspend_idx = 10 if effective_protocol in ("ssh", "sftp", "telnet", "mosh") else None stream_limit = MAX_AUTH_STREAM_BYTES if unattended else MAX_PRE_AUTH_BUFFER_BYTES jumphost_hops = getattr(self, "_jumphost_hops", ()) st: dict[str, object] = { "cand_idx": 0, "connect_retries": 0, "eof_fallback_advances": 0, "target_creds_sent": False, "cur_cand": None, "cur_user": "", "handshake_progressed": False, "prompts_this_conn": 0, "cand_sent_pw_this_conn": False, "logged_fallback_this_cand": False, "stage": "connect", "last_observed_bytes_len": 0, } def _handle_username_prompt(child_obj) -> tuple[bool, str | None]: if not use_auth_chain: manual_user = ( (runtime_candidates[0].user if runtime_candidates else "") or str(self.user or "") ) if manual_user: child_obj.sendline(manual_user) st["last_observed_bytes_len"] = 0 return False, None self.missingtext = True return True, None cand_idx_cur = int(st["cand_idx"]) prompts_cur = int(st["prompts_this_conn"]) cur_cand = st["cur_cand"] if st["cand_sent_pw_this_conn"]: if (cand_idx_cur + 1) >= len(runtime_candidates): return False, str(sanitize_exception(None, code="AUTH_FAILED", secrets=raw_secrets)) if prompts_cur >= max_auth_prompts: st["cand_idx"] = cand_idx_cur + 1 return False, "__NEXT__:next_candidate" cand_idx_cur += 1 st["cand_idx"] = cand_idx_cur cur_cand = runtime_candidates[cand_idx_cur] st["cur_cand"] = cur_cand st["cur_user"] = cur_cand.user st["cand_sent_pw_this_conn"] = False st["logged_fallback_this_cand"] = False u_to_send = cur_cand.user if cur_cand is not None else "" if not u_to_send: if (cand_idx_cur + 1) < len(runtime_candidates) and runtime_candidates[cand_idx_cur + 1].user: cand_idx_cur += 1 st["cand_idx"] = cand_idx_cur cur_cand = runtime_candidates[cand_idx_cur] st["cur_cand"] = cur_cand st["cur_user"] = cur_cand.user u_to_send = cur_cand.user st["logged_fallback_this_cand"] = False else: return False, str(sanitize_exception(None, code="NO_CREDS", secrets=raw_secrets)) if not tracker.try_acquire_user(u_to_send, limit=max_global_user_attempts): return False, str( sanitize_exception(None, code="USER_BUDGET_EXHAUSTED", secrets=raw_secrets) ) if cur_cand is not None and cur_cand.is_fallback and not st["logged_fallback_this_cand"]: self._emit_aaa_fallback_log( logger, unique=str(self.unique), host=str(self.host), protocol=effective_protocol, user=u_to_send, label=cur_cand.label, secrets=raw_secrets, ) self.last_fallback_used = True st["logged_fallback_this_cand"] = True child_obj.sendline(u_to_send) st["handshake_progressed"] = True st["stage"] = "auth" st["last_observed_bytes_len"] = 0 return False, None def _handle_target_password_prompt(child_obj) -> tuple[bool, str | None]: cand_idx_cur = int(st["cand_idx"]) prompts_cur = int(st["prompts_this_conn"]) cur_cand = st["cur_cand"] cur_user = str(st["cur_user"]) if not use_auth_chain: self.missingtext = True return True, None if st["cand_sent_pw_this_conn"]: if (cand_idx_cur + 1) >= len(runtime_candidates): return False, str(sanitize_exception(None, code="AUTH_FAILED", secrets=raw_secrets)) nxt = runtime_candidates[cand_idx_cur + 1] if nxt.user == cur_user and prompts_cur < max_auth_prompts: cand_idx_cur += 1 st["cand_idx"] = cand_idx_cur cur_cand = nxt st["cur_cand"] = cur_cand st["cand_sent_pw_this_conn"] = False st["logged_fallback_this_cand"] = False else: st["cand_idx"] = cand_idx_cur + 1 return False, "__NEXT__:next_candidate" if cur_cand is None or not cur_cand.has_password: if (cand_idx_cur + 1) < len(runtime_candidates): nxt = runtime_candidates[cand_idx_cur + 1] if nxt.user == cur_user and prompts_cur < max_auth_prompts: cand_idx_cur += 1 st["cand_idx"] = cand_idx_cur cur_cand = nxt st["cur_cand"] = cur_cand st["cand_sent_pw_this_conn"] = False st["logged_fallback_this_cand"] = False else: st["cand_idx"] = cand_idx_cur + 1 return False, "__NEXT__:next_candidate" else: return False, str(sanitize_exception(None, code="NO_CREDS", secrets=raw_secrets)) if not cur_cand.has_password: return False, str(sanitize_exception(None, code="NO_CREDS", secrets=raw_secrets)) if prompts_cur >= max_auth_prompts: if (cand_idx_cur + 1) < len(runtime_candidates): st["cand_idx"] = cand_idx_cur + 1 return False, "__NEXT__:next_candidate" return False, str(sanitize_exception(None, code="AUTH_FAILED", secrets=raw_secrets)) eff_u = cur_cand.user or str(self.user or "") acquired, budget_err_code = tracker.try_acquire_target_attempt( host=str(self.host), port=str(self.port or ""), protocol=effective_protocol, user=eff_u, host_limit=max_total_auth_attempts, user_limit=max_global_user_attempts, ) if not acquired: return False, str( sanitize_exception( None, code=budget_err_code or "HOST_BUDGET_EXHAUSTED", secrets=raw_secrets, ) ) if cur_cand.is_fallback and not st["logged_fallback_this_cand"]: self._emit_aaa_fallback_log( logger, unique=str(self.unique), host=str(self.host), protocol=effective_protocol, user=eff_u, label=cur_cand.label, secrets=raw_secrets, ) self.last_fallback_used = True st["logged_fallback_this_cand"] = True child_obj.sendline(cur_cand.password) st["cand_sent_pw_this_conn"] = True st["target_creds_sent"] = True st["prompts_this_conn"] = prompts_cur + 1 st["handshake_progressed"] = True st["stage"] = "auth" st["last_observed_bytes_len"] = 0 return False, None while True: remaining = deadline - clock() if remaining <= 0: return _redact_known_secrets( f"Connection failed code: 12\nConnection timeout (global deadline {max_total}s exceeded)", raw_secrets, ) cand_idx_val = int(st["cand_idx"]) cur_cand = runtime_candidates[cand_idx_val] if cand_idx_val < len(runtime_candidates) else None cur_user = cur_cand.user if cur_cand is not None else str(self.user or "") st["cur_cand"] = cur_cand st["cur_user"] = cur_user user_override = ( cur_user if (cand_idx_val > 0 or (cur_user and cur_user != str(self.user or ""))) else None ) cmd = self._get_cmd( force_ssh=force_ssh, allow_reverse_tunnel_port=allow_reverse_tunnel_port, connect_timeout=eff_ct, user_override=user_override, ) st["handshake_progressed"] = False args = shlex.split(cmd) child, err = self._spawn_child( args, protocol=effective_protocol, _secrets=raw_secrets, ) if err: return _redact_known_secrets(err, raw_secrets) connected_ok = False local_mylog = None next_action: str | None = None hop_pw_idx = [0] * len(jumphost_hops) hop_cursor = 0 st["prompts_this_conn"] = 0 st["cand_sent_pw_this_conn"] = False st["logged_fallback_this_cand"] = False transport_error_seen = False try: child.logfile = None child.logfile_send = None if unattended: child.logfile_read = None if isinstance(self.tags, dict) and self.tags.get("console"): child.sendline() if debug: if logger: logger("debug", f"Command:\n{_redact_known_secrets(cmd, raw_secrets)}") local_mylog = io.BytesIO() self.mylog = local_mylog redacted_cmd = _redact_known_secrets(cmd, raw_secrets) local_mylog.write(f"[i] [DEBUG] Command:\r\n {redacted_cmd}\r\n".encode()) if not unattended: child.logfile_read = local_mylog st["stage"] = "connect" progress_extensions = 0 st["last_observed_bytes_len"] = 0 while True: remaining = deadline - clock() if remaining <= 0: return _redact_known_secrets( f"Connection failed code: 12\nConnection timeout (global deadline {max_total}s exceeded)", raw_secrets, ) stage_timeout = eff_ct if st["stage"] == "connect" else eff_at expect_timeout = max(0.001, min(stage_timeout, remaining)) results = child.expect(proto_expects, timeout=expect_timeout) results_value = proto_expects[results] before_bytes = _to_bytes(getattr(child, "before", b"")) after_bytes = _to_bytes(getattr(child, "after", b"")) if len(before_bytes) > stream_limit: return _redact_known_secrets( f"Connection failed code: 12\nPre-auth buffer exceeded maximum size ({stream_limit} bytes)", raw_secrets, ) if results in initial_indices[effective_protocol]: if effective_protocol in ["ssh", "sftp", "mosh"]: child.sendline('yes') st["handshake_progressed"] = True st["last_observed_bytes_len"] = 0 elif effective_protocol in ["telnet", "kubectl", "docker", "ssm"]: should_break, msg_or_action = _handle_username_prompt(child) if msg_or_action == "__NEXT__:next_candidate": next_action = "next_candidate" break if msg_or_action is not None: return msg_or_action if should_break: break elif results in error_indices[effective_protocol]: if results_value == pexpect.TIMEOUT: cur_len = len(before_bytes) bytes_grew = cur_len > int(st["last_observed_bytes_len"]) st["last_observed_bytes_len"] = cur_len remaining = deadline - clock() can_extend = ( bytes_grew and progress_extensions < max_ext and remaining > 0 and not (effective_protocol == "mosh" and st["handshake_progressed"]) ) if can_extend: progress_extensions += 1 if not budget_warned: budget_warned = True if logger: logger( "warning", f"Slow {effective_protocol} handshake making progress; extending connect wait (deadline {max_total}s)", ) continue if ( use_auth_chain and st["stage"] == "auth" and st["target_creds_sent"] and (int(st["cand_idx"]) + 1) < len(runtime_candidates) and remaining > 0 ): st["cand_idx"] = int(st["cand_idx"]) + 1 next_action = "next_candidate" break can_retry = ( not st["target_creds_sent"] and (int(st["connect_retries"]) + 1) < max_attempts and remaining > 0 and not (effective_protocol == "mosh" and st["handshake_progressed"]) ) if can_retry: st["connect_retries"] = int(st["connect_retries"]) + 1 next_action = "retry_connect" break before_str = _to_str(before_bytes) if effective_protocol == "mosh": before_str = self._logclean(before_str, True) if remaining <= 0: after_str = f"Connection timeout (global deadline {max_total}s exceeded)" else: after_str = "Connection timeout" return _redact_known_secrets( f"Connection failed code: {results}\n{before_str.lstrip()}{after_str}".rstrip(), raw_secrets, ) is_perm_denied = ( effective_protocol in ("ssh", "sftp", "mosh") and results == 2 and b"permission denied" in (before_bytes + after_bytes).lower() ) if ( use_auth_chain and is_perm_denied and (int(st["cand_idx"]) + 1) < len(runtime_candidates) and remaining > 0 ): st["cand_idx"] = int(st["cand_idx"]) + 1 next_action = "next_candidate" break transport_error_seen = not is_perm_denied after = _to_str(after_bytes) before = _to_str(before_bytes) readline_val = _to_str(child.readline()) if effective_protocol == "mosh": after = self._logclean(after, True) before = self._logclean(before, True) readline_val = self._logclean(readline_val, True) if ( effective_protocol == "mosh" and results == 18 and ("Nothing received from server" in after or "Nothing received from server" in before) ): err_msg = ( after.strip() if "Nothing received from server" in after else before.strip() ) return _redact_known_secrets( f"Connection failed code: {results}\n{err_msg} β UDP traffic is blocked or unreachable. Verify firewall rules for UDP ports (60000-61000 or mosh_udp_port).", raw_secrets, ) return _redact_known_secrets( f"Connection failed code: {results}\n{before.lstrip()}{after}{readline_val}".rstrip(), raw_secrets, ) elif results in eof_indices[effective_protocol]: if results == pw_prompt_idx: after_lower = after_bytes.lower() if b"username" in after_lower and b"password" not in after_lower: should_break, msg_or_action = _handle_username_prompt(child) if msg_or_action == "__NEXT__:next_candidate": next_action = "next_candidate" break if msg_or_action is not None: return msg_or_action if should_break: break continue if jumphost_hops: prompt_line = normalize_prompt_line(before_bytes, after_bytes) kind, hop_idx = self._disambiguate_prompt(prompt_line) if kind == "conflict": return str( sanitize_exception(None, code="JUMP_AUTH_FAILED", secrets=raw_secrets) ) if kind == "hop": assert hop_idx is not None if st["target_creds_sent"] or hop_idx < hop_cursor: return str( sanitize_exception(None, code="JUMP_AUTH_FAILED", secrets=raw_secrets) ) hop_cursor = hop_idx hop_obj = jumphost_hops[hop_idx] hop_pws = hop_runtime_passwords[hop_idx] if hop_pw_idx[hop_idx] >= len(hop_pws): return str( sanitize_exception(None, code="JUMP_AUTH_FAILED", secrets=raw_secrets) ) if not tracker.try_acquire_hop( hop_obj["host"], hop_obj["port"], hop_obj["protocol"], limit=max_hop_host_attempts, ): return str( sanitize_exception(None, code="HOST_BUDGET_EXHAUSTED", secrets=raw_secrets) ) child.sendline(hop_pws[hop_pw_idx[hop_idx]]) hop_pw_idx[hop_idx] += 1 st["handshake_progressed"] = True st["last_observed_bytes_len"] = 0 continue if kind == "target": hop_cursor = len(jumphost_hops) else: no_pending_hop_pws = all( hop_pw_idx[i] >= len(hop_runtime_passwords[i]) for i in range(hop_cursor, len(jumphost_hops)) ) if ( st["target_creds_sent"] or hop_cursor >= len(jumphost_hops) or no_pending_hop_pws ): hop_cursor = len(jumphost_hops) else: allow_ambig = bool( tags_dict.get("allow_ambiguous_single_hop_prompt", False) ) if len(jumphost_hops) > 1 or not allow_ambig: return str( sanitize_exception( None, code="JUMP_AUTH_FAILED", secrets=raw_secrets, ) ) hop_obj = jumphost_hops[hop_cursor] if not tracker.try_acquire_hop( hop_obj["host"], hop_obj["port"], hop_obj["protocol"], limit=max_hop_host_attempts, ): return str( sanitize_exception( None, code="HOST_BUDGET_EXHAUSTED", secrets=raw_secrets, ) ) child.sendline( hop_runtime_passwords[hop_cursor][hop_pw_idx[hop_cursor]] ) hop_pw_idx[hop_cursor] += 1 st["handshake_progressed"] = True st["last_observed_bytes_len"] = 0 continue should_break, msg_or_action = _handle_target_password_prompt(child) if msg_or_action == "__NEXT__:next_candidate": next_action = "next_candidate" break if msg_or_action is not None: return msg_or_action if should_break: break elif suspend_idx is not None and results == suspend_idx: child.sendline("\r") sleep(2) st["last_observed_bytes_len"] = 0 elif results_value == pexpect.EOF: norm_buf = ( before_bytes.replace(b"\r\n", b"\n").replace(b"\r", b"\n") + b"\n" ) eof_perm_denied = False for err_idx in error_indices[effective_protocol]: err_pat = proto_expects[err_idx] if isinstance(err_pat, re.Pattern): m = err_pat.search(norm_buf) if m: is_pd = ( effective_protocol in ("ssh", "sftp", "mosh") and err_idx == 2 and b"permission denied" in m.group(0).lower() ) if ( use_auth_chain and is_pd and (int(st["cand_idx"]) + 1) < len(runtime_candidates) and remaining > 0 ): eof_perm_denied = True break transport_error_seen = not is_pd b_str = _to_str(norm_buf[: m.start()]) a_str = _to_str(m.group(0)) if effective_protocol == "mosh": b_str = self._logclean(b_str, True) a_str = self._logclean(a_str, True) return _redact_known_secrets( f"Connection failed code: {err_idx}\n{b_str.lstrip()}{a_str}".rstrip(), raw_secrets, ) if eof_perm_denied: st["cand_idx"] = int(st["cand_idx"]) + 1 next_action = "next_candidate" break if use_auth_chain and not transport_error_seen: if st["target_creds_sent"]: if (int(st["cand_idx"]) + 1) < len(runtime_candidates): eof_adv = int(st["eof_fallback_advances"]) if eof_adv < MAX_EOF_FALLBACK_ADVANCES: st["eof_fallback_advances"] = eof_adv + 1 st["cand_idx"] = int(st["cand_idx"]) + 1 next_action = "next_candidate" break return str( sanitize_exception( None, code="EOF_BUDGET_EXHAUSTED", secrets=raw_secrets, ) ) return str( sanitize_exception( None, code="AUTH_FAILED", secrets=raw_secrets, ) ) if effective_protocol != "local": return str( sanitize_exception( None, code="TRANSPORT_ERROR", secrets=raw_secrets, ) ) try: child.sendline() except Exception as exc: # noqa: BLE001 _LOGGER.debug("EOF fallback sendline ignored: %s", type(exc).__name__) break else: cur_cand_now = st["cur_cand"] if ( cur_cand_now is not None and cur_cand_now.is_fallback and not st["logged_fallback_this_cand"] ): self._emit_aaa_fallback_log( logger, unique=str(self.unique), host=str(self.host), protocol=effective_protocol, user=str(st["cur_user"]), label=cur_cand_now.label, secrets=raw_secrets, ) self.last_fallback_used = True st["logged_fallback_this_cand"] = True child.sendline() break if next_action in ("retry_connect", "next_candidate"): continue if isinstance(self.tags, dict) and self.tags.get("post_connect_commands"): cmds = self.tags.get("post_connect_commands") post_commands = [cmds] if isinstance(cmds, str) else cmds for command in post_commands: child.sendline(command) sleep(1) child.readline(0) self.child = child from pexpect import fdpexpect self.raw_child = fdpexpect.fdspawn(self.child.child_fd) connected_ok = True return True except Exception as exc: # noqa: BLE001 san = sanitize_exception( exc, code="AUTH_FAILED", secrets=raw_secrets, context_label="unexpected connection error", ) return str(san) finally: if not connected_ok: try: child.logfile_read = None except Exception as exc: # noqa: BLE001 _LOGGER.debug("Cleanup logfile_read reset failed: %s", type(exc).__name__) try: child.terminate(force=True) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Cleanup terminate failed: %s", type(exc).__name__) if local_mylog is not None and not getattr(local_mylog, "closed", False): try: local_mylog.close() except Exception as exc: # noqa: BLE001 _LOGGER.debug("Cleanup local_mylog close failed: %s", type(exc).__name__)This class generates a node object. Containts all the information and methods to connect and interact with a device using ssh or telnet.
Attributes:
- output (str): Output of the commands you ran with run or test method. - result(bool): True if expected value is found after running the commands using test method. - status (int): 0 if the method run or test run successfully. 1 if connection failed. 2 if expect timeouts without prompt or EOF.Parameters:
- unique (str): Unique name to assign to the node. - host (str): IP address or hostname of the node.Optional Parameters:
- options (str): Additional options to pass the ssh/telnet for connection. - logs (str): Path/file for storing the logs. You can use ${unique},${host}, ${port}, ${user}, ${protocol} as variables. - password (str): Encrypted or plaintext password. - port (str): Port to connect to node, default 22 for ssh and 23 for telnet. - protocol (str): Select ssh, mosh, telnet, kubectl, docker or ssm. Default is ssh. - user (str): Username to of the node. - config (obj): Pass the object created with class configfile with key for decryption and extra configuration if you are using connection manager. - tags (dict) : Tags useful for automation and personal porpuse like "os", "prompt" and "screenleght_command" - jumphost (str): Reference another node to be used as a jumphost - allow_unsafe_options (bool): Explicitly override safety restrictions.Methods
async def inject_commands(self, commands, child_fd, on_inject=None)-
Expand source code
@MethodHook async def inject_commands(self, commands, child_fd, on_inject=None): """ Inject a list of commands into the node's PTY. Handles screen_length_command, history tracking and delays. """ if not commands: return # 0. Clear line os.write(child_fd, b'\x15') await asyncio.sleep(0.1) # 1. Prepare list (prepend screen_length if exists) slc = self.tags.get("screen_length_command") if hasattr(self, 'tags') and isinstance(self.tags, dict) else None to_send = list(commands) if slc and slc not in to_send: # avoid duplicates if already there to_send.insert(0, slc) # 2. Inject one by one for cmd in to_send: # Register in node's official history (SKIP if it's the administrative screen length command) if cmd != slc and hasattr(self, 'cmd_byte_positions') and self.cmd_byte_positions is not None: log_pos = self.mylog.tell() if hasattr(self, 'mylog') else 0 self.cmd_byte_positions.append((log_pos, cmd)) if hasattr(self, 'current_local_stream') and self.current_local_stream is not None: try: await self.current_local_stream.write(f'\x1b]133;B;{log_pos}\x07'.encode()) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Failed writing command boundary marker: %s", exc) # Write physically to PTY os.write(child_fd, (cmd + "\n").encode()) # Notify (e.g., for gRPC or logs) - SKIP for administrative SLC if on_inject and cmd != slc: if asyncio.iscoroutinefunction(on_inject): await on_inject(cmd) else: on_inject(cmd) # Delay to avoid overwhelming the router await asyncio.sleep(0.8)Inject a list of commands into the node's PTY. Handles screen_length_command, history tracking and delays.
def interact(self, debug=False, logger=None)-
Expand source code
@MethodHook def interact(self, debug=False, logger=None): ''' Asynchronous interactive session using Smart Tunnel architecture. Allows multiplexing I/O and handling SIGWINCH events locally without blocking. ''' connect = self._connect(debug=debug, logger=logger) if connect is True: try: self._setup_interact_environment(debug=debug, logger=logger, async_mode=True) local_stream = LocalStream() def resize_callback(rows, cols): try: self.child.setwinsize(rows, cols) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Failed resizing child window: %s", exc) # Build local copilot handler copilot_handler = self._build_local_copilot_handler() asyncio.run(self._async_interact_loop(local_stream, resize_callback, copilot_handler=copilot_handler)) finally: self._teardown_interact_environment() else: if logger: logger("error", str(connect)) else: printer.error(f"Connection failed: {connect!s}") sys.exit(1)Asynchronous interactive session using Smart Tunnel architecture. Allows multiplexing I/O and handling SIGWINCH events locally without blocking.
def run(self,
commands,
vars=None,
*,
folder='',
prompt='>$|#$|\\$$|>.$|#.$|\\$.$',
stdout=False,
timeout=None,
logger=None,
connect_timeout=None,
auth_timeout=None,
unattended=True,
attempt_tracker=None)-
Expand source code
@MethodHook def run( self, commands, vars=None, *, folder='', prompt=r'>$|#$|\$$|>.$|#.$|\$.$', stdout=False, timeout=None, logger=None, connect_timeout=None, auth_timeout=None, _default_cmd_timeout=10, unattended=True, attempt_tracker=None, ): ''' Run a command or list of commands on the node and return the output. ### Parameters: - commands (str/list): Commands to run on the node. Should be str or a list of str. You can use variables as {varname} and defining them in optional parameter vars. ### Optional Parameters: - vars (dict): Dictionary containing the definition of variables used in commands parameter. Keys: Variable names. Values: strings. ### Optional Named Parameters: - folder (str): Path where output log should be stored, leave empty to disable logging. - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - stdout (bool):Set True to send the command output to stdout. default False. - timeout (int):Time in seconds for expect to wait for prompt/EOF. default 10. ### Returns: str: Output of the commands you ran on the node. ''' force_ssh = self.protocol == "mosh" effective_protocol = "ssh" if force_ssh else self.protocol try: _, _, eff_cmd, _, _ = resolve_timeouts( effective_protocol, self.tags, getattr(self, "_hop_chain_meta", None) or [], timeout=timeout, connect_timeout=connect_timeout, auth_timeout=auth_timeout, _default_cmd_timeout=_default_cmd_timeout, ) except ValueError as e: err = f"Connection failed code: 12\nInvalid timeout configuration: {e}" self.output = err self.status = 1 if logger: logger("error", f"Connection failed: {err}") return err connect = self._connect( timeout=timeout, logger=logger, force_ssh=force_ssh, connect_timeout=connect_timeout, auth_timeout=auth_timeout, _default_cmd_timeout=_default_cmd_timeout, unattended=unattended, attempt_tracker=attempt_tracker, ) now = datetime.datetime.now().strftime('%Y-%m-%d_%H%M%S') if connect is True: if logger: port_str = f":{self.port}" if self.port and effective_protocol not in ["ssm", "kubectl", "docker"] else "" logger("success", f"Connected to {self.unique} at {self.host}{port_str} via: {effective_protocol}") if isinstance(self.tags, dict) and "prompt" in self.tags: prompt = self.tags["prompt"] prompt_pat = re.compile(prompt.encode("utf-8"), re.DOTALL) expects = [prompt_pat, pexpect.EOF, pexpect.TIMEOUT] output = '' result = 0 if not isinstance(commands, list): commands = [commands] if isinstance(self.tags, dict) and "screen_length_command" in self.tags: commands.insert(0, self.tags["screen_length_command"]) self.mylog = io.BytesIO() self.child.logfile_read = self.mylog for c in commands: if vars is not None: try: c = c.format(**vars) except KeyError as e: self.output = f"Error: Variable {e} not defined in task or inventory" self.status = 1 return self.output result = self.child.expect(expects, timeout=eff_cmd) # Only set terminal size on devices without a # screen_length_command (e.g. Linux/bash servers). # Routers already disable pagination via that command. # After setwinsize, consume any SIGWINCH re-render # prompt (~40ms on bash) with a short timeout. if c == commands[0] and (not isinstance(self.tags, dict) or "screen_length_command" not in self.tags): try: self.child.setwinsize(65535, 65535) except Exception: # noqa: BLE001 try: self.child.setwinsize(10000, 10000) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Fallback setwinsize failed in run: %s", exc) self.child.expect(expects, timeout=1) self.child.sendline(c) if result == 2: break if result != 2: result = self.child.expect(expects, timeout=eff_cmd) self.child.close() output = self._logclean(self.mylog.getvalue().decode("utf-8", errors="replace"), True) if logger: logger("output", output) if folder != '': with open(folder + "/" + self.unique + "_" + now + ".txt", "w") as f: f.write(output) self.output = output if result == 2: self.status = 2 else: self.status = 0 return output else: self.output = connect self.status = 1 if logger: logger("error", f"Connection failed: {connect}") if folder != '': with open(folder + "/" + self.unique + "_" + now + ".txt", "w") as f: f.write(connect) return connectRun a command or list of commands on the node and return the output.
Parameters:
- commands (str/list): Commands to run on the node. Should be str or a list of str. You can use variables as {varname} and defining them in optional parameter vars.Optional Parameters:
- vars (dict): Dictionary containing the definition of variables used in commands parameter. Keys: Variable names. Values: strings.Optional Named Parameters:
- folder (str): Path where output log should be stored, leave empty to disable logging. - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - stdout (bool):Set True to send the command output to stdout. default False. - timeout (int):Time in seconds for expect to wait for prompt/EOF. default 10.Returns:
str: Output of the commands you ran on the node. def test(self,
commands,
expected,
vars=None,
*,
folder='',
prompt='>$|#$|\\$$|>.$|#.$|\\$.$',
timeout=None,
logger=None,
connect_timeout=None,
auth_timeout=None,
unattended=True,
attempt_tracker=None)-
Expand source code
@MethodHook def test( self, commands, expected, vars=None, *, folder='', prompt=r'>$|#$|\$$|>.$|#.$|\$.$', timeout=None, logger=None, connect_timeout=None, auth_timeout=None, _default_cmd_timeout=10, unattended=True, attempt_tracker=None, ): ''' Run a command or list of commands on the node, then check if expected value appears on the output after the last command. ### Parameters: - commands (str/list): Commands to run on the node. Should be str or a list of str. You can use variables as {varname} and defining them in optional parameter vars. - expected (str) : Expected text to appear after running all the commands on the node.You can use variables as {varname} and defining them in optional parameter vars. ### Optional Parameters: - vars (dict): Dictionary containing the definition of variables used in commands and expected parameters. Keys: Variable names. Values: strings. ### Optional Named Parameters: - folder (str): Path where output log should be stored, leave empty to not store logs. - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - timeout (int):Time in seconds for expect to wait for prompt/EOF. default 10. ### Returns: bool: true if expected value is found after running the commands false if prompt is found before. ''' now = datetime.datetime.now().strftime("%Y-%m-%d_%H-%M-%S") force_ssh = self.protocol == "mosh" effective_protocol = "ssh" if force_ssh else self.protocol try: _, _, eff_cmd, _, _ = resolve_timeouts( effective_protocol, self.tags, getattr(self, "_hop_chain_meta", None) or [], timeout=timeout, connect_timeout=connect_timeout, auth_timeout=auth_timeout, _default_cmd_timeout=_default_cmd_timeout, ) except ValueError as e: err = f"Connection failed code: 12\nInvalid timeout configuration: {e}" self.result = None self.output = err self.status = 1 if logger: logger("error", f"Connection failed: {err}") return err connect = self._connect( timeout=timeout, logger=logger, force_ssh=force_ssh, connect_timeout=connect_timeout, auth_timeout=auth_timeout, _default_cmd_timeout=_default_cmd_timeout, unattended=unattended, attempt_tracker=attempt_tracker, ) if connect is True: if logger: port_str = f":{self.port}" if self.port and effective_protocol not in ["ssm", "kubectl", "docker"] else "" logger("success", f"Connected to {self.unique} at {self.host}{port_str} via: {effective_protocol}") if isinstance(self.tags, dict) and "prompt" in self.tags: prompt = self.tags["prompt"] prompt_pat = re.compile(prompt.encode("utf-8"), re.DOTALL) expects = [prompt_pat, pexpect.EOF, pexpect.TIMEOUT] output = '' result = 0 if not isinstance(commands, list): commands = [commands] if not isinstance(expected, list): expected = [expected] if isinstance(self.tags, dict) and "screen_length_command" in self.tags: commands.insert(0, self.tags["screen_length_command"]) self.mylog = io.BytesIO() self.child.logfile_read = self.mylog for c in commands: if vars is not None: try: c = c.format(**vars) except KeyError as e: self.output = f"Error: Variable {e} not defined in task or inventory" self.status = 1 return self.output result = self.child.expect(expects, timeout=eff_cmd) if c == commands[0] and (not isinstance(self.tags, dict) or "screen_length_command" not in self.tags): try: self.child.setwinsize(65535, 65535) except Exception: # noqa: BLE001 try: self.child.setwinsize(10000, 10000) except Exception as exc: # noqa: BLE001 _LOGGER.debug("Fallback setwinsize failed in test: %s", exc) self.child.expect(expects, timeout=1) self.child.sendline(c) if result == 2: break if result != 2: result = self.child.expect(expects, timeout=eff_cmd) self.child.close() output = self._logclean(self.mylog.getvalue().decode("utf-8", errors="replace"), True) if logger: logger("output", output) if folder != '': with open(folder + "/" + self.unique + "_" + now + ".txt", "w") as f: f.write(output) self.output = output if result in [0, 1]: # lastcommand = commands[-1] # if vars is not None: # lastcommand = lastcommand.format(**vars) # last_command_index = output.rfind(lastcommand) # cleaned_output = output[last_command_index + len(lastcommand):].strip() self.result = {} for e in expected: if vars is not None: e = e.format(**vars) updatedprompt = re.sub(r'(?<!\\)\$', '', prompt) cleaned_output = output try: newpattern = f".*({updatedprompt}).*{e}.*" cleaned_output = re.sub(newpattern, '', cleaned_output) except re.error: try: escaped_e = re.escape(e) newpattern = f".*({updatedprompt}).*{escaped_e}.*" cleaned_output = re.sub(newpattern, '', cleaned_output) except re.error: pass if e in cleaned_output: self.result[e] = True else: try: if re.search(e, cleaned_output): self.result[e] = True else: self.result[e] = False except re.error: self.result[e] = False self.status = 0 return self.result if result == 2: self.result = None self.status = 2 return output else: self.result = None self.output = connect self.status = 1 return connectRun a command or list of commands on the node, then check if expected value appears on the output after the last command.
Parameters:
- commands (str/list): Commands to run on the node. Should be str or a list of str. You can use variables as {varname} and defining them in optional parameter vars. - expected (str) : Expected text to appear after running all the commands on the node.You can use variables as {varname} and defining them in optional parameter vars.Optional Parameters:
- vars (dict): Dictionary containing the definition of variables used in commands and expected parameters. Keys: Variable names. Values: strings.Optional Named Parameters:
- folder (str): Path where output log should be stored, leave empty to not store logs. - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - timeout (int):Time in seconds for expect to wait for prompt/EOF. default 10.Returns:
bool: true if expected value is found after running the commands false if prompt is found before.
class nodes (nodes:Β dict, config='')-
Expand source code
@ClassHook class nodes: ''' This class generates a nodes object. Contains a list of node class objects and methods to run multiple tasks on nodes simultaneously. ### Attributes: - nodelist (list): List of node class objects passed to the init function. - output (dict): Dictionary formed by nodes unique as keys, output of the commands you ran on the node as value. Created after running methods run or test. - result (dict): Dictionary formed by nodes unique as keys, value is True if expected value is found after running the commands, False if prompt is found before. Created after running method test. - status (dict): Dictionary formed by nodes unique as keys, value: 0 if method run or test ended successfully. 1 if connection failed. 2 if expect timeouts without prompt or EOF. - <unique> (obj): For each item in nodelist, there is an attribute generated with the node unique. ''' def __init__(self, nodes: dict, config = ''): ''' ### Parameters: - nodes (dict): Dictionary formed by node information: Keys: Unique name for each node. Mandatory Subkeys: host(str). Optional Subkeys: options(str), logs(str), password(str), port(str), protocol(str), user(str). For reference on subkeys check node class. ### Optional Parameters: - config (obj): Pass the object created with class configfile with key for decryption and extra configuration if you are using connection manager. ''' self.nodelist = [] self.config = config self.fallback_used = {} for n, node_cfg in nodes.items(): this = node(n, **node_cfg, config=config) self.nodelist.append(this) setattr(self, n, this) @MethodHook def _splitlist(self, lst, n): #split a list in lists of n members. for i in range(0, len(lst), n): yield lst[i:i + n] @MethodHook def run( self, commands, vars=None, *, folder=None, prompt=None, stdout=None, parallel=10, timeout=None, on_complete=None, logger=None, connect_timeout=None, auth_timeout=None, _default_cmd_timeout=10, unattended=True, attempt_tracker=None, ): ''' Run a command or list of commands on all the nodes in nodelist. ### Parameters: - commands (str/list): Commands to run on the nodes. Should be str or list of str. You can use variables as {varname} and defining them in optional parameter vars. ### Optional Parameters: - vars (dict): Dictionary containing the definition of variables for each node, used in commands parameter. Keys should be formed by nodes unique names. Use special key name __global__ for global variables. Subkeys: Variable names. Values: strings. ### Optional Named Parameters: - folder (str): Path where output log should be stored, leave empty to disable logging. - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - stdout (bool): Set True to send the command output to stdout. Default False. - parallel (int): Number of nodes to run the commands simultaneously. Default is 10, if there are more nodes that this value, nodes are groups in groups with max this number of members. - timeout (int): Time in seconds for expect to wait for prompt/EOF. default 10. - on_complete (callable): Optional callback called when each node finishes. Receives (unique, output, status). Called from the node's thread so it must be thread-safe. ###Returns: dict: Dictionary formed by nodes unique as keys, Output of the commands you ran on the node as value. ''' args = {} nodesargs = {} args["commands"] = commands if folder is not None: args["folder"] = folder Path(folder).mkdir(parents=True, exist_ok=True) if prompt is not None: args["prompt"] = prompt if stdout is not None and on_complete is None: args["stdout"] = stdout if timeout is not None: args["timeout"] = timeout if connect_timeout is not None: args["connect_timeout"] = connect_timeout if auth_timeout is not None: args["auth_timeout"] = auth_timeout if _default_cmd_timeout != 10: args["_default_cmd_timeout"] = _default_cmd_timeout if unattended is not True: args["unattended"] = unattended output = {} status = {} fallback_used = {} tasks = [] def _run_node(node_obj, node_args, callback): """Wrapper that runs a node and fires the callback on completion.""" node_obj.run(**node_args) if callback: callback(node_obj.unique, node_obj.output, node_obj.status) for n in self.nodelist: nodesargs[n.unique] = deepcopy(args) if attempt_tracker is not None: nodesargs[n.unique]["attempt_tracker"] = attempt_tracker if vars is not None: nodesargs[n.unique]["vars"] = {} if "__global__" in vars: nodesargs[n.unique]["vars"].update(vars["__global__"]) for var_key, var_val in vars.items(): if var_key == "__global__": continue try: if re.search(var_key, n.unique, re.IGNORECASE): nodesargs[n.unique]["vars"].update(var_val) except re.error: if var_key == n.unique: nodesargs[n.unique]["vars"].update(var_val) # Pass the logger to the node nodesargs[n.unique]["logger"] = logger if on_complete: tasks.append(threading.Thread(target=_run_node, args=(n, nodesargs[n.unique], on_complete))) else: tasks.append(threading.Thread(target=n.run, kwargs=nodesargs[n.unique])) taskslist = list(self._splitlist(tasks, parallel)) for t in taskslist: for i in t: i.start() for i in t: i.join() for i in self.nodelist: output[i.unique] = i.output status[i.unique] = i.status fallback_used[i.unique] = bool(getattr(i, "last_fallback_used", False)) self.output = output self.status = status self.fallback_used = fallback_used return output @MethodHook def test( self, commands, expected, vars=None, *, folder=None, prompt=None, parallel=10, timeout=None, on_complete=None, logger=None, connect_timeout=None, auth_timeout=None, _default_cmd_timeout=10, unattended=True, attempt_tracker=None, ): ''' Run a command or list of commands on all the nodes in nodelist, then check if expected value appears on the output after the last command. ### Parameters: - commands (str/list): Commands to run on the node. Should be str or list of str. - expected (str) : Expected text to appear after running all the commands on the node. ### Optional Parameters: - vars (dict): Dictionary containing the definition of variables for each node, used in commands and expected parameters. Keys should be formed by nodes unique names. Use special key name __global__ for global variables. Subkeys: Variable names. Values: strings. ### Optional Named Parameters: - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - parallel (int): Number of nodes to run the commands simultaneously. Default is 10, if there are more nodes that this value, nodes are groups in groups with max this number of members. - timeout (int): Time in seconds for expect to wait for prompt/EOF. default 10. - on_complete (callable): Optional callback called when each node finishes. Receives (unique, output, status). Called from the node's thread so it must be thread-safe. ### Returns: dict: Dictionary formed by nodes unique as keys, value is True if expected value is found after running the commands, False if prompt is found before. ''' args = {} nodesargs = {} args["commands"] = commands args["expected"] = expected if folder is not None: args["folder"] = folder Path(folder).mkdir(parents=True, exist_ok=True) if prompt is not None: args["prompt"] = prompt if timeout is not None: args["timeout"] = timeout if connect_timeout is not None: args["connect_timeout"] = connect_timeout if auth_timeout is not None: args["auth_timeout"] = auth_timeout if _default_cmd_timeout != 10: args["_default_cmd_timeout"] = _default_cmd_timeout if unattended is not True: args["unattended"] = unattended output = {} result = {} status = {} fallback_used = {} tasks = [] def _test_node(node_obj, node_args, callback): """Wrapper that runs a node test and fires the callback on completion.""" node_obj.test(**node_args) if callback: callback(node_obj.unique, node_obj.output, node_obj.status, node_obj.result) for n in self.nodelist: nodesargs[n.unique] = deepcopy(args) if attempt_tracker is not None: nodesargs[n.unique]["attempt_tracker"] = attempt_tracker if vars is not None: nodesargs[n.unique]["vars"] = {} if "__global__" in vars: nodesargs[n.unique]["vars"].update(vars["__global__"]) for var_key, var_val in vars.items(): if var_key == "__global__": continue try: if re.search(var_key, n.unique, re.IGNORECASE): nodesargs[n.unique]["vars"].update(var_val) except re.error: if var_key == n.unique: nodesargs[n.unique]["vars"].update(var_val) nodesargs[n.unique]["logger"] = logger if on_complete: tasks.append(threading.Thread(target=_test_node, args=(n, nodesargs[n.unique], on_complete))) else: tasks.append(threading.Thread(target=n.test, kwargs=nodesargs[n.unique])) taskslist = list(self._splitlist(tasks, parallel)) for t in taskslist: for i in t: i.start() for i in t: i.join() for i in self.nodelist: result[i.unique] = i.result output[i.unique] = i.output status[i.unique] = i.status fallback_used[i.unique] = bool(getattr(i, "last_fallback_used", False)) self.output = output self.result = result self.status = status self.fallback_used = fallback_used return resultThis class generates a nodes object. Contains a list of node class objects and methods to run multiple tasks on nodes simultaneously.
Attributes:
- nodelist (list): List of node class objects passed to the init function. - output (dict): Dictionary formed by nodes unique as keys, output of the commands you ran on the node as value. Created after running methods run or test. - result (dict): Dictionary formed by nodes unique as keys, value is True if expected value is found after running the commands, False if prompt is found before. Created after running method test. - status (dict): Dictionary formed by nodes unique as keys, value: 0 if method run or test ended successfully. 1 if connection failed. 2 if expect timeouts without prompt or EOF. - <unique> (obj): For each item in nodelist, there is an attribute generated with the node unique.Parameters:
- nodes (dict): Dictionary formed by node information: Keys: Unique name for each node. Mandatory Subkeys: host(str). Optional Subkeys: options(str), logs(str), password(str), port(str), protocol(str), user(str). For reference on subkeys check node class.Optional Parameters:
- config (obj): Pass the object created with class configfile with key for decryption and extra configuration if you are using connection manager.Methods
def run(self,
commands,
vars=None,
*,
folder=None,
prompt=None,
stdout=None,
parallel=10,
timeout=None,
on_complete=None,
logger=None,
connect_timeout=None,
auth_timeout=None,
unattended=True,
attempt_tracker=None)-
Expand source code
@MethodHook def run( self, commands, vars=None, *, folder=None, prompt=None, stdout=None, parallel=10, timeout=None, on_complete=None, logger=None, connect_timeout=None, auth_timeout=None, _default_cmd_timeout=10, unattended=True, attempt_tracker=None, ): ''' Run a command or list of commands on all the nodes in nodelist. ### Parameters: - commands (str/list): Commands to run on the nodes. Should be str or list of str. You can use variables as {varname} and defining them in optional parameter vars. ### Optional Parameters: - vars (dict): Dictionary containing the definition of variables for each node, used in commands parameter. Keys should be formed by nodes unique names. Use special key name __global__ for global variables. Subkeys: Variable names. Values: strings. ### Optional Named Parameters: - folder (str): Path where output log should be stored, leave empty to disable logging. - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - stdout (bool): Set True to send the command output to stdout. Default False. - parallel (int): Number of nodes to run the commands simultaneously. Default is 10, if there are more nodes that this value, nodes are groups in groups with max this number of members. - timeout (int): Time in seconds for expect to wait for prompt/EOF. default 10. - on_complete (callable): Optional callback called when each node finishes. Receives (unique, output, status). Called from the node's thread so it must be thread-safe. ###Returns: dict: Dictionary formed by nodes unique as keys, Output of the commands you ran on the node as value. ''' args = {} nodesargs = {} args["commands"] = commands if folder is not None: args["folder"] = folder Path(folder).mkdir(parents=True, exist_ok=True) if prompt is not None: args["prompt"] = prompt if stdout is not None and on_complete is None: args["stdout"] = stdout if timeout is not None: args["timeout"] = timeout if connect_timeout is not None: args["connect_timeout"] = connect_timeout if auth_timeout is not None: args["auth_timeout"] = auth_timeout if _default_cmd_timeout != 10: args["_default_cmd_timeout"] = _default_cmd_timeout if unattended is not True: args["unattended"] = unattended output = {} status = {} fallback_used = {} tasks = [] def _run_node(node_obj, node_args, callback): """Wrapper that runs a node and fires the callback on completion.""" node_obj.run(**node_args) if callback: callback(node_obj.unique, node_obj.output, node_obj.status) for n in self.nodelist: nodesargs[n.unique] = deepcopy(args) if attempt_tracker is not None: nodesargs[n.unique]["attempt_tracker"] = attempt_tracker if vars is not None: nodesargs[n.unique]["vars"] = {} if "__global__" in vars: nodesargs[n.unique]["vars"].update(vars["__global__"]) for var_key, var_val in vars.items(): if var_key == "__global__": continue try: if re.search(var_key, n.unique, re.IGNORECASE): nodesargs[n.unique]["vars"].update(var_val) except re.error: if var_key == n.unique: nodesargs[n.unique]["vars"].update(var_val) # Pass the logger to the node nodesargs[n.unique]["logger"] = logger if on_complete: tasks.append(threading.Thread(target=_run_node, args=(n, nodesargs[n.unique], on_complete))) else: tasks.append(threading.Thread(target=n.run, kwargs=nodesargs[n.unique])) taskslist = list(self._splitlist(tasks, parallel)) for t in taskslist: for i in t: i.start() for i in t: i.join() for i in self.nodelist: output[i.unique] = i.output status[i.unique] = i.status fallback_used[i.unique] = bool(getattr(i, "last_fallback_used", False)) self.output = output self.status = status self.fallback_used = fallback_used return outputRun a command or list of commands on all the nodes in nodelist.
Parameters:
- commands (str/list): Commands to run on the nodes. Should be str or list of str. You can use variables as {varname} and defining them in optional parameter vars.Optional Parameters:
- vars (dict): Dictionary containing the definition of variables for each node, used in commands parameter. Keys should be formed by nodes unique names. Use special key name __global__ for global variables. Subkeys: Variable names. Values: strings.Optional Named Parameters:
- folder (str): Path where output log should be stored, leave empty to disable logging. - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - stdout (bool): Set True to send the command output to stdout. Default False. - parallel (int): Number of nodes to run the commands simultaneously. Default is 10, if there are more nodes that this value, nodes are groups in groups with max this number of members. - timeout (int): Time in seconds for expect to wait for prompt/EOF. default 10. - on_complete (callable): Optional callback called when each node finishes. Receives (unique, output, status). Called from the node's thread so it must be thread-safe.Returns:
dict: Dictionary formed by nodes unique as keys, Output of the commands you ran on the node as value. def test(self,
commands,
expected,
vars=None,
*,
folder=None,
prompt=None,
parallel=10,
timeout=None,
on_complete=None,
logger=None,
connect_timeout=None,
auth_timeout=None,
unattended=True,
attempt_tracker=None)-
Expand source code
@MethodHook def test( self, commands, expected, vars=None, *, folder=None, prompt=None, parallel=10, timeout=None, on_complete=None, logger=None, connect_timeout=None, auth_timeout=None, _default_cmd_timeout=10, unattended=True, attempt_tracker=None, ): ''' Run a command or list of commands on all the nodes in nodelist, then check if expected value appears on the output after the last command. ### Parameters: - commands (str/list): Commands to run on the node. Should be str or list of str. - expected (str) : Expected text to appear after running all the commands on the node. ### Optional Parameters: - vars (dict): Dictionary containing the definition of variables for each node, used in commands and expected parameters. Keys should be formed by nodes unique names. Use special key name __global__ for global variables. Subkeys: Variable names. Values: strings. ### Optional Named Parameters: - prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - parallel (int): Number of nodes to run the commands simultaneously. Default is 10, if there are more nodes that this value, nodes are groups in groups with max this number of members. - timeout (int): Time in seconds for expect to wait for prompt/EOF. default 10. - on_complete (callable): Optional callback called when each node finishes. Receives (unique, output, status). Called from the node's thread so it must be thread-safe. ### Returns: dict: Dictionary formed by nodes unique as keys, value is True if expected value is found after running the commands, False if prompt is found before. ''' args = {} nodesargs = {} args["commands"] = commands args["expected"] = expected if folder is not None: args["folder"] = folder Path(folder).mkdir(parents=True, exist_ok=True) if prompt is not None: args["prompt"] = prompt if timeout is not None: args["timeout"] = timeout if connect_timeout is not None: args["connect_timeout"] = connect_timeout if auth_timeout is not None: args["auth_timeout"] = auth_timeout if _default_cmd_timeout != 10: args["_default_cmd_timeout"] = _default_cmd_timeout if unattended is not True: args["unattended"] = unattended output = {} result = {} status = {} fallback_used = {} tasks = [] def _test_node(node_obj, node_args, callback): """Wrapper that runs a node test and fires the callback on completion.""" node_obj.test(**node_args) if callback: callback(node_obj.unique, node_obj.output, node_obj.status, node_obj.result) for n in self.nodelist: nodesargs[n.unique] = deepcopy(args) if attempt_tracker is not None: nodesargs[n.unique]["attempt_tracker"] = attempt_tracker if vars is not None: nodesargs[n.unique]["vars"] = {} if "__global__" in vars: nodesargs[n.unique]["vars"].update(vars["__global__"]) for var_key, var_val in vars.items(): if var_key == "__global__": continue try: if re.search(var_key, n.unique, re.IGNORECASE): nodesargs[n.unique]["vars"].update(var_val) except re.error: if var_key == n.unique: nodesargs[n.unique]["vars"].update(var_val) nodesargs[n.unique]["logger"] = logger if on_complete: tasks.append(threading.Thread(target=_test_node, args=(n, nodesargs[n.unique], on_complete))) else: tasks.append(threading.Thread(target=n.test, kwargs=nodesargs[n.unique])) taskslist = list(self._splitlist(tasks, parallel)) for t in taskslist: for i in t: i.start() for i in t: i.join() for i in self.nodelist: result[i.unique] = i.result output[i.unique] = i.output status[i.unique] = i.status fallback_used[i.unique] = bool(getattr(i, "last_fallback_used", False)) self.output = output self.result = result self.status = status self.fallback_used = fallback_used return resultRun a command or list of commands on all the nodes in nodelist, then check if expected value appears on the output after the last command.
Parameters:
- commands (str/list): Commands to run on the node. Should be str or list of str. - expected (str) : Expected text to appear after running all the commands on the node.Optional Parameters:
- vars (dict): Dictionary containing the definition of variables for each node, used in commands and expected parameters. Keys should be formed by nodes unique names. Use special key name __global__ for global variables. Subkeys: Variable names. Values: strings.Optional Named Parameters:
- prompt (str): Prompt to be expected after a command is finished running. Usually linux uses ">" or EOF while routers use ">" or "#". The default value should work for most nodes. Change it if your connection need some special symbol. - parallel (int): Number of nodes to run the commands simultaneously. Default is 10, if there are more nodes that this value, nodes are groups in groups with max this number of members. - timeout (int): Time in seconds for expect to wait for prompt/EOF. default 10. - on_complete (callable): Optional callback called when each node finishes. Receives (unique, output, status). Called from the node's thread so it must be thread-safe.Returns:
dict: Dictionary formed by nodes unique as keys, value is True if expected value is found after running the commands, False if prompt is found before.