Files
connpy/docs/connpy/index.html
T

7092 lines
336 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1">
<meta name="generator" content="pdoc3 0.11.6">
<title>connpy API documentation</title>
<meta name="description" content="&lt;p align=&#34;center&#34;&gt;
&lt;img src=&#34;https://nginx.gederico.dynu.net/images/CONNPY-resized.png&#34; alt=&#34;App Logo&#34;&gt;
&lt;/p&gt; …">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/13.0.0/sanitize.min.css" integrity="sha512-y1dtMcuvtTMJc1yPgEqF0ZjQbhnc/bFhyvIyVNb9Zk5mIGtqVaAB1Ttl28su8AvFMOY0EwRbAe+HCLqj6W7/KA==" crossorigin>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/10up-sanitize.css/13.0.0/typography.min.css" integrity="sha512-Y1DYSb995BAfxobCkKepB1BqJJTPrOp3zPL74AWFugHHmmdcvO+C48WLrUOlhGMc0QG7AE3f7gmvvcrmX2fDoA==" crossorigin>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/default.min.css" crossorigin>
<style>:root{--highlight-color:#fe9}.flex{display:flex !important}body{line-height:1.5em}#content{padding:20px}#sidebar{padding:1.5em;overflow:hidden}#sidebar > *:last-child{margin-bottom:2cm}.http-server-breadcrumbs{font-size:130%;margin:0 0 15px 0}#footer{font-size:.75em;padding:5px 30px;border-top:1px solid #ddd;text-align:right}#footer p{margin:0 0 0 1em;display:inline-block}#footer p:last-child{margin-right:30px}h1,h2,h3,h4,h5{font-weight:300}h1{font-size:2.5em;line-height:1.1em}h2{font-size:1.75em;margin:2em 0 .50em 0}h3{font-size:1.4em;margin:1.6em 0 .7em 0}h4{margin:0;font-size:105%}h1:target,h2:target,h3:target,h4:target,h5:target,h6:target{background:var(--highlight-color);padding:.2em 0}a{color:#058;text-decoration:none;transition:color .2s ease-in-out}a:visited{color:#503}a:hover{color:#b62}.title code{font-weight:bold}h2[id^="header-"]{margin-top:2em}.ident{color:#900;font-weight:bold}pre code{font-size:.8em;line-height:1.4em;padding:1em;display:block}code{background:#f3f3f3;font-family:"DejaVu Sans Mono",monospace;padding:1px 4px;overflow-wrap:break-word}h1 code{background:transparent}pre{border-top:1px solid #ccc;border-bottom:1px solid #ccc;margin:1em 0}#http-server-module-list{display:flex;flex-flow:column}#http-server-module-list div{display:flex}#http-server-module-list dt{min-width:10%}#http-server-module-list p{margin-top:0}.toc ul,#index{list-style-type:none;margin:0;padding:0}#index code{background:transparent}#index h3{border-bottom:1px solid #ddd}#index ul{padding:0}#index h4{margin-top:.6em;font-weight:bold}@media (min-width:200ex){#index .two-column{column-count:2}}@media (min-width:300ex){#index .two-column{column-count:3}}dl{margin-bottom:2em}dl dl:last-child{margin-bottom:4em}dd{margin:0 0 1em 3em}#header-classes + dl > dd{margin-bottom:3em}dd dd{margin-left:2em}dd p{margin:10px 0}.name{background:#eee;font-size:.85em;padding:5px 10px;display:inline-block;min-width:40%}.name:hover{background:#e0e0e0}dt:target .name{background:var(--highlight-color)}.name > span:first-child{white-space:nowrap}.name.class > span:nth-child(2){margin-left:.4em}.inherited{color:#999;border-left:5px solid #eee;padding-left:1em}.inheritance em{font-style:normal;font-weight:bold}.desc h2{font-weight:400;font-size:1.25em}.desc h3{font-size:1em}.desc dt code{background:inherit}.source > summary,.git-link-div{color:#666;text-align:right;font-weight:400;font-size:.8em;text-transform:uppercase}.source summary > *{white-space:nowrap;cursor:pointer}.git-link{color:inherit;margin-left:1em}.source pre{max-height:500px;overflow:auto;margin:0}.source pre code{font-size:12px;overflow:visible;min-width:max-content}.hlist{list-style:none}.hlist li{display:inline}.hlist li:after{content:',\2002'}.hlist li:last-child:after{content:none}.hlist .hlist{display:inline;padding-left:1em}img{max-width:100%}td{padding:0 .5em}.admonition{padding:.1em 1em;margin:1em 0}.admonition-title{font-weight:bold}.admonition.note,.admonition.info,.admonition.important{background:#aef}.admonition.todo,.admonition.versionadded,.admonition.tip,.admonition.hint{background:#dfd}.admonition.warning,.admonition.versionchanged,.admonition.deprecated{background:#fd4}.admonition.error,.admonition.danger,.admonition.caution{background:lightpink}</style>
<style media="screen and (min-width: 700px)">@media screen and (min-width:700px){#sidebar{width:30%;height:100vh;overflow:auto;position:sticky;top:0}#content{width:70%;max-width:100ch;padding:3em 4em;border-left:1px solid #ddd}pre code{font-size:1em}.name{font-size:1em}main{display:flex;flex-direction:row-reverse;justify-content:flex-end}.toc ul ul,#index ul ul{padding-left:1em}.toc > ul > li{margin-top:.5em}}</style>
<style media="print">@media print{#sidebar h1{page-break-before:always}.source{display:none}}@media print{*{background:transparent !important;color:#000 !important;box-shadow:none !important;text-shadow:none !important}a[href]:after{content:" (" attr(href) ")";font-size:90%}a[href][title]:after{content:none}abbr[title]:after{content:" (" attr(title) ")"}.ir a:after,a[href^="javascript:"]:after,a[href^="#"]:after{content:""}pre,blockquote{border:1px solid #999;page-break-inside:avoid}thead{display:table-header-group}tr,img{page-break-inside:avoid}img{max-width:100% !important}@page{margin:0.5cm}p,h2,h3{orphans:3;widows:3}h1,h2,h3,h4,h5,h6{page-break-after:avoid}}</style>
<script defer src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js" integrity="sha512-D9gUyxqja7hBtkWpPWGt9wfbfaMGVt9gnyCvYa+jojwwPHLCzUm5i8rpk7vD7wNee9bA35eYIjobYPaQuKS1MQ==" crossorigin></script>
<script>window.addEventListener('DOMContentLoaded', () => {
hljs.configure({languages: ['bash', 'css', 'diff', 'graphql', 'ini', 'javascript', 'json', 'plaintext', 'python', 'python-repl', 'rust', 'shell', 'sql', 'typescript', 'xml', 'yaml']});
hljs.highlightAll();
/* Collapse source docstrings */
setTimeout(() => {
[...document.querySelectorAll('.hljs.language-python > .hljs-string')]
.filter(el => el.innerHTML.length > 200 && ['"""', "'''"].includes(el.innerHTML.substring(0, 3)))
.forEach(el => {
let d = document.createElement('details');
d.classList.add('hljs-string');
d.innerHTML = '<summary>"""</summary>' + el.innerHTML.substring(3);
el.replaceWith(d);
});
}, 100);
})</script>
</head>
<body>
<main>
<article id="content">
<header>
<h1 class="title">Package <code>connpy</code></h1>
</header>
<section id="section-intro">
<p align="center">
<img src="https://nginx.gederico.dynu.net/images/CONNPY-resized.png" alt="App Logo">
</p>
<h1 id="connpy-v650b1">Connpy (v6.5.0b1)</h1>
<p><a href="https://pypi.org/pypi/connpy/"><img alt="" src="https://img.shields.io/pypi/v/connpy.svg?style=flat-square"></a>
<a href="https://pypi.org/pypi/connpy/"><img alt="" src="https://img.shields.io/pypi/pyversions/connpy.svg?style=flat-square"></a>
<a href="https://pypi.org/pypi/connpy/"><img alt="" src="https://img.shields.io/pypi/dm/connpy.svg?style=flat-square&amp;cacheSeconds=86400"></a>
<a href="https://github.com/fluzzi/connpy"><img alt="" src="https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20docker-blue?style=flat-square"></a>
<a href="https://github.com/fluzzi/connpy"><img alt="" src="https://img.shields.io/badge/backend-gRPC-blue?style=flat-square"></a>
<a href="https://github.com/fluzzi/connpy"><img alt="" src="https://img.shields.io/badge/AI%20Core-LiteLLM-green?style=flat-square"></a>
<a href="https://modelcontextprotocol.io"><img alt="" src="https://img.shields.io/badge/MCP-compatible-orange?style=flat-square"></a>
<a href="https://github.com/fluzzi/connpy/blob/main/LICENSE"><img alt="" src="https://img.shields.io/pypi/l/connpy.svg?style=flat-square"></a></p>
<p><strong>Connpy</strong> is a powerful Connection Manager and Network Automation Platform for Linux, Mac, and Docker. It provides a unified interface for <strong>SSH, SFTP, Mosh, Telnet, kubectl, Docker pods, and AWS SSM</strong>.</p>
<p>The v6 release introduces a comprehensive <strong>AI Copilot</strong> and <strong>AI Playbook Engine</strong>, transforming your terminal into an interactive network assistant that understands your device outputs, configures parameters safely, and runs simulations.</p>
<hr>
<h2 id="1-ai-system">1. 🤖 AI System</h2>
<h3 id="1a-terminal-copilot-ctrlspace">1a. Terminal Copilot (Ctrl+Space)</h3>
<p>Invoke the context-aware AI Copilot directly inside any active terminal session by pressing <strong><code>Ctrl + Space</code></strong>.
* <strong>Context Modes</strong>: Cycles through <code>LINES</code> (sends raw scroll buffer), <code>SINGLE</code> (captures exactly one command + output block), and <code>RANGE</code> (logical group of recent commands) using <strong><code>Ctrl+Up/Down</code></strong>.
* <strong>Slash Commands (<code>/</code>)</strong>: Control the AI persona, safety settings, and mission mode:
* <code>/mission [objective]</code>: Start an autonomous multi-step investigation mission with human approval.
* <code>/cancel</code>: Abort active mission.
* <code>/architect</code> / <code>/engineer</code>: Swaps the agent between high-level strategist and technical executor.
* <code>/trust</code> / <code>/untrust</code>: Configures auto-run behavior for suggested non-destructive commands.
* <code>/os [system]</code>: Manually overrides target OS parsing rules (e.g. <code>/os cisco_ios</code>).
* <code>/prompt [regex]</code>: Overrides command prompt detection bounds.
* <code>/clear</code>: Clear context history.</p>
<h3 id="1b-ai-chat-conn-ai">1b. AI Chat (conn ai)</h3>
<p>Start a standalone persistent session with the AI Copilot. Manage sessions using <code>--list</code>, <code>--resume</code>, <code>--session &lt;id&gt;</code> (to restore a specific history), <code>--delete &lt;id&gt;</code>, or send a quick single-shot question directly from the terminal prompt:</p>
<pre><code class="language-bash">conn ai &quot;how do i check bgp summary on cisco?&quot;
</code></pre>
<h3 id="1c-mcp-integration-client-server">1c. MCP Integration (Client &amp; Server)</h3>
<p>Connect to external data sources and tools dynamically, or expose <code><a title="connpy" href="#connpy">connpy</a></code> as a native MCP server for external agents (Claude Desktop, Cursor, IDEs):</p>
<pre><code class="language-bash"># MCP Client: Manage connected MCP servers
conn ai --mcp # Interactive configuration wizard
conn ai --mcp list # List configured MCP servers
conn ai --mcp add &lt;name&gt; &lt;url&gt; [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) &amp; configuration commands
</code></pre>
<h3 id="1d-local-interactive-shell-conn-shell">1d. Local Interactive Shell (conn shell)</h3>
<p>Launch a local interactive shell with AI Copilot support enabled directly on your host machine:</p>
<pre><code class="language-bash">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
</code></pre>
<ul>
<li><strong>Nested Sessions &amp; Passthrough</strong>: Supports running nested <code>conn</code> / <code><a title="connpy" href="#connpy">connpy</a></code> connections inside <code>conn shell</code>. Automatically detects foreground <code>conn</code> processes and forwards <code>Ctrl+Space</code> down to the active device connection instead of triggering the local Copilot.</li>
<li><strong>Shell Configuration</strong>: Configure default shell command, prompt regex, or OS type via <code>conn config</code>:</li>
</ul>
<pre><code class="language-bash">conn config --shell-command /bin/zsh
conn config --shell-prompt &quot;\$\s*$&quot;
conn config --shell-os ubuntu
</code></pre>
<hr>
<h2 id="2-automation-playbooks">2. ⚙️ Automation &amp; Playbooks</h2>
<h3 id="2a-quick-run-conn-run">2a. Quick Run (conn run)</h3>
<p>Run commands in parallel directly on target nodes or folder structures:</p>
<pre><code class="language-bash">conn run router1 &quot;show interface&quot;
</code></pre>
<h3 id="2b-yaml-playbook-engine">2b. YAML Playbook Engine</h3>
<p>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.</p>
<pre><code class="language-yaml"># example_playbook.yaml
- name: Verify Network Operations
hosts: &quot;@office&quot;
parallel: true
tasks:
- name: Get interface brief
run: &quot;show ip interface brief&quot;
- name: Check OSPF state
run: &quot;show ip ospf neighbor&quot;
test: &quot;FULL&quot;
</code></pre>
<p>Execute using the playbooks runner:</p>
<pre><code class="language-bash">conn run example_playbook.yaml
</code></pre>
<h3 id="2c-ai-assisted-automation">2c. AI-Assisted Automation</h3>
<p>Leverage AI to generate playbook templates (<code>--generate-ai</code>), simulate command changes before execution (<code>--preflight-ai</code>), or analyze consolidated execution logs post-run (<code>--analyze</code>). Use <code>--test "expected text1" "expected text2"</code> to specify assert-style output validations.
* <em>To generate an empty template:</em> <code>conn run --generate</code></p>
<hr>
<h2 id="3-inventory-management">3. 📂 Inventory Management</h2>
<h3 id="3a-nodes">3a. Nodes</h3>
<p>Manage connections using standard commands: add (<code>conn --add node1</code>), edit (<code>conn --mod node1</code>), delete (<code>conn --del node1</code>), show configuration (<code>conn --show node1</code>), or connect (<code>conn node1</code>).</p>
<h3 id="3b-profiles">3b. Profiles</h3>
<p>Define credentials and templates globally and reference them inside node fields using the <code>@profile_name</code> placeholder. Manage profiles interactively or via commands:</p>
<pre><code class="language-bash">conn profile -a profile_name
# Or equivalently:
conn -a profile profile_name
</code></pre>
<p>During the interactive <code>conn --add</code> prompt, you can input <code>@profile_name</code> in the <strong>username</strong> or <strong>password</strong> fields to reference it.</p>
<h3 id="3c-folders-move-copy-list">3c. Folders, Move, Copy, List</h3>
<p>Organize nodes into logical folder hierarchies (<code>@office</code>, <code>@datacenter@office</code>). Move items (<code>conn move [src] [dst]</code>), copy (<code>conn copy [src] [dst]</code>), or list items with custom filters and formatting:</p>
<pre><code class="language-bash">conn list nodes --filter &quot;.*-prod&quot; --format &quot;{name} ({host}) runs {protocol}&quot;
</code></pre>
<h3 id="3d-bulk-export-import">3d. Bulk, Export, Import</h3>
<p>Bulk import connections from formatted text files (<code>conn bulk -f nodes.txt</code>), or export/import connection folders using YAML configurations (<code>conn export @folder &gt; backup.yaml</code> / <code>conn import backup.yaml</code>).</p>
<h3 id="3e-tags-system">3e. Tags System</h3>
<p>Customize connection settings dynamically using tags. Configure per-node settings like custom OS types (<code>os</code>), prompt regex rules (<code>prompt</code>), and page length triggers (<code>screen_length_command</code>).</p>
<pre><code class="language-yaml"># Custom tags dictionary (YANG / VSR context)
tags: { &quot;os&quot;: &quot;cisco_ios&quot;, &quot;prompt&quot;: &quot;.*#&quot;, &quot;screen_length_command&quot;: &quot;terminal length 0&quot; }
</code></pre>
<h3 id="3f-credential-fallback-chain-compose-auth-budgets">3f. Credential Fallback Chain, <code>compose:</code> &amp; Auth Budgets</h3>
<p>Configure automatic backup credentials (<code>fallback</code>) on nodes or <code>@profile</code> templates so both interactive (<code>conn &lt;node&gt;</code>) and unattended (<code>conn run</code> / MCP) sessions switch seamlessly when primary TACACS+/AAA authentication fails (opt-out via <code>tags.allow_fallback: false</code>).
* <strong>Fallback Formats</strong>: Accepts <code>@profile</code>, explicit JSON list/dict entries (<code>[{"user": "backup", "password": "..."}]</code>), or <code>compose:</code> expressions. Nodes referencing multiple profiles inherit <code>fallback</code> with priority from <code>user</code>/<code>password</code> <code>@profile</code> references.
* <strong>Password Composition (<code>compose:</code>)</strong>: Concatenate secrets and literals explicitly using <code>compose:@prof1+@prof2+"suffix"</code> (use <code>@@</code> to escape leading literal <code>@</code>).
* <strong>Anti-Lockout Guardrails (<code>conn config</code>)</strong>: Enforce strict attempt bounds via <code>--max-auth-prompts</code>, <code>--max-total-auth-attempts</code>, <code>--max-hop-host-attempts</code>, <code>--max-global-user-attempts</code>, and <code>--disable-fallback-on-insecure-hostkey</code>.</p>
<hr>
<h2 id="4-protocols-connection-features">4. 🔌 Protocols &amp; Connection Features</h2>
<h3 id="4a-ssh-sftp-mosh-telnet-kubectl-docker-aws-ssm">4a. SSH / SFTP / Mosh / Telnet / kubectl / Docker / AWS SSM</h3>
<p>Connect to various architectures using native protocols:
* <strong>SSH / Telnet</strong>: Standard CLI protocols.
* <strong>Mosh</strong>: Mobile Shell with roaming and local echo support.
* <strong>SFTP</strong>: Transfer files securely (<code>conn --sftp node</code>).
* <strong>Docker</strong>: Connect directly to local container names (host set to container name/ID).
* <strong>Kubernetes (kubectl)</strong>: Connect to pods (namespace customizable via options).
* <strong>AWS SSM</strong>: Connect to EC2 instances using Instance IDs as hosts.</p>
<h3 id="4b-jumphosts">4b. Jumphosts</h3>
<p>Support for single or chained intermediate gateway nodes (SSH, Mosh, SSM, kubectl, or docker jumphosts) to tunnel traffic safely into target environments.</p>
<h3 id="4c-debug-mode-keepalive-logging">4c. Debug Mode, Keepalive, Logging</h3>
<p>Track connection steps (<code>conn --debug node</code>), set idle keepalive intervals (<code>conn config --keepalive &lt;seconds&gt;</code>), or define dynamic output log files using variables like <code>${unique}</code>, <code>${host}</code>, <code>${port}</code>, <code>${user}</code>, <code>${protocol}</code>, or <code>${date 'format'}</code>.</p>
<h3 id="4d-adaptive-multi-hop-timeouts">4d. Adaptive Multi-Hop Timeouts</h3>
<p>Differentiate <code>--connect-timeout</code> and <code>--auth-timeout</code> stages (<code>conn run</code> / <code>conn config</code>), automatically computing topological per-hop latency budgets for chained <code>SSM</code> and <code>Jumphost</code> tunnels with bounded progress extensions on slow handshakes.</p>
<hr>
<h2 id="5-remote-capture-conn-capture-core-plugin">5. 🖥️ Remote Capture (conn capture - Core Plugin)</h2>
<p>Perform remote packet capture (<code>tcpdump</code>) on hosts over secure SSH or Mosh reverse tunnels and stream packets live into your local Wireshark GUI:</p>
<pre><code class="language-bash">conn capture router1 eth0 -w -f &quot;port 80&quot;
</code></pre>
<ul>
<li><strong>Requirements</strong>: Local installation of Wireshark or <code>tshark</code> is required for live piping (<code>-w</code>).</li>
<li><strong>Advanced flags</strong>: Specify network namespaces (<code>--ns &lt;name&gt;</code>), custom filters (<code>-f &lt;filter&gt;</code>), or configure the Wireshark local path (<code>--set-wireshark-path</code>).</li>
</ul>
<hr>
<h2 id="6-context-filtering">6. 🛡️ Context Filtering</h2>
<p>Prevent accidental command execution in production by setting active regex contexts. This hides non-matching inventory items and restricts execution scope:</p>
<pre><code class="language-bash">conn context production -a --regex &quot;.*-prod&quot;
conn context production --set
</code></pre>
<ul>
<li><strong>Manage Contexts</strong>: List defined filters (<code>conn context --ls</code>), show context details (<code>conn context production -s</code>), or delete contexts (<code>conn context production -r</code>).</li>
</ul>
<hr>
<h2 id="7-plugin-system">7. 🔌 Plugin System</h2>
<p>Extend <code><a title="connpy" href="#connpy">connpy</a></code> 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:</p>
<pre><code class="language-bash">conn plugin --add my_plugin script.py
conn plugin --update my_plugin script.py
conn plugin --remote --sync
</code></pre>
<hr>
<h2 id="8-grpc-client-server-architecture">8. ⚙️ gRPC Client-Server Architecture</h2>
<h3 id="8a-server-startstoprestartdebug">8a. Server (start/stop/restart/debug)</h3>
<p>Execute tasks on a centralized remote host. Start gRPC server (<code>conn api -s 50051</code>), stop (<code>conn api -x</code>), restart (<code>conn api -r</code>), or debug in the foreground (<code>conn api -d</code>).</p>
<h3 id="8b-client-config">8b. Client Config</h3>
<p>Shift the local CLI to communicate with a remote server instance:</p>
<pre><code class="language-bash">conn config --service-mode remote
conn config --remote localhost:50051
</code></pre>
<h3 id="8c-user-management-api-tokens">8c. User Management &amp; API Tokens</h3>
<p>Manage server-side user credentials and Personal Access Tokens (PAT) for automated setups:</p>
<pre><code class="language-bash">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 &quot;CI/CD Token&quot; --expires-in 30
conn user --list-tokens
conn user --revoke-token &lt;token_id&gt;
</code></pre>
<p>Use <code>--path</code> to specify custom configuration folders in server Mode B. Pass API tokens via <code>CONNPY_TOKEN</code> environment variable.</p>
<h3 id="8d-sso-oidc">8d. SSO / OIDC</h3>
<p>Configure identity providers (e.g. Authelia, Keycloak) for SSO gRPC authentication using the interactive wizard:</p>
<pre><code class="language-bash">conn sso --add provider_name
</code></pre>
<h3 id="8e-login-logout">8e. Login / Logout</h3>
<p>Authenticate client sessions (<code>conn login [username]</code>), check connection status (<code>conn login --status</code>), or close sessions (<code>conn logout</code>).</p>
<hr>
<h2 id="9-installation-configuration">9. ⚡ Installation &amp; Configuration</h2>
<h3 id="9a-pip-install">9a. pip install</h3>
<pre><code class="language-bash">pip install connpy
</code></pre>
<h3 id="9b-shell-completion-fzf">9b. Shell Completion + FZF</h3>
<p>Install autocompletions and fuzzy-search wrappers into your shell profile:</p>
<pre><code class="language-bash">eval &quot;$(conn config --completion bash)&quot;
eval &quot;$(conn config --fzf-wrapper bash)&quot;
</code></pre>
<h3 id="9c-conn-config-options">9c. conn config options</h3>
<p>View configuration details (<code>conn config</code>) or customize variables like case sensitivity (<code>--allow-uppercase</code>), FZF list picker (<code>--fzf true</code>), configurations directory (<code>--configfolder</code>), or persistent AI API keys and models (<code>--engineer-model</code>).</p>
<h3 id="9d-theming">9d. Theming</h3>
<p>Customize CLI panel styles and colors by pointing to built-in presets or external YAML styles:</p>
<pre><code class="language-bash">conn config --theme /path/to/theme.yaml
</code></pre>
<hr>
<h2 id="10-privacy-security-synchronization-conn-sync">10. 🔒 Privacy, Security &amp; Synchronization (conn sync)</h2>
<p>Encrypts inventory and profiles locally via RSA/OAEP. Backup and sync configurations to Google Drive manually (<code>conn sync --once</code>, <code>--list</code>, <code>--restore</code>) or schedule auto-sync. Segregate restores (<code>--nodes</code> / <code>--config</code>) or sync remote nodes with <code>--sync-remote</code>.</p>
<hr>
<h2 id="11-python-api">11. 🐍 Python API</h2>
<p>Embed connection and automation routines programmatically in Python:</p>
<pre><code class="language-python">import connpy
# 1. Direct single node interaction
router = connpy.node(&quot;router1&quot;, &quot;1.1.1.1&quot;, user=&quot;admin&quot;)
router.run([&quot;show ip int brief&quot;])
print(router.output)
# 2. Parallel nodes execution with variables
config = connpy.configfile()
nodes_info = config.getitem(&quot;@office&quot;, [&quot;router1&quot;, &quot;router2&quot;])
routers = connpy.nodes(nodes_info, config=config)
variables = {
&quot;router1@office&quot;: {&quot;id&quot;: &quot;1&quot;},
&quot;__global__&quot;: {&quot;mask&quot;: &quot;255.255.255.0&quot;}
}
routers.run([&quot;interface lo{id}&quot;, &quot;ip address 10.0.0.{id} {mask}&quot;], variables)
# 3. AI Copilot prompts
myai = connpy.ai(connpy.configfile())
response = myai.ask(&quot;Show BGP status.&quot;)
print(response)
</code></pre>
<p><em>Supports additional programmatic features like <code><a title="connpy.node.test" href="#connpy.node.test">node.test()</a></code>, <code><a title="connpy.node.interact" href="#connpy.node.interact">node.interact()</a></code>, <code><a title="connpy.configfile.encrypt" href="#connpy.configfile.encrypt">configfile.encrypt()</a></code>, <code>connapp</code> embeds, and <code>ClassHook</code> / <code>MethodHook</code> plugin hooks.</em></p>
<hr>
<h2 id="12-docker-deployment">12. 🐳 Docker Deployment</h2>
<p>Run <code><a title="connpy" href="#connpy">connpy</a></code> containerized and silent:</p>
<pre><code class="language-bash">docker compose run --rm connpy-app [command]
</code></pre>
<p>Add <code>alias conn='docker compose run --rm connpy-app'</code> for a transparent container experience.</p>
<hr>
<h2 id="13-license">13. 📜 License</h2>
<p><a href="LICENSE">PolyForm Noncommercial 1.0.0</a></p>
</section>
<section>
<h2 class="section-title" id="header-submodules">Sub-modules</h2>
<dl>
<dt><code class="name"><a title="connpy.ai" href="ai.html">connpy.ai</a></code></dt>
<dd>
<div class="desc"></div>
</dd>
<dt><code class="name"><a title="connpy.auth_utils" href="auth_utils.html">connpy.auth_utils</a></code></dt>
<dd>
<div class="desc"><p>Pure authentication, composition, masking, sanitization, and rate-limit helpers.</p></div>
</dd>
<dt><code class="name"><a title="connpy.cli" href="cli/index.html">connpy.cli</a></code></dt>
<dd>
<div class="desc"></div>
</dd>
<dt><code class="name"><a title="connpy.grpc_layer" href="grpc_layer/index.html">connpy.grpc_layer</a></code></dt>
<dd>
<div class="desc"></div>
</dd>
<dt><code class="name"><a title="connpy.mcp_client" href="mcp_client.html">connpy.mcp_client</a></code></dt>
<dd>
<div class="desc"></div>
</dd>
<dt><code class="name"><a title="connpy.mcp_server" href="mcp_server.html">connpy.mcp_server</a></code></dt>
<dd>
<div class="desc"></div>
</dd>
<dt><code class="name"><a title="connpy.proto" href="proto/index.html">connpy.proto</a></code></dt>
<dd>
<div class="desc"></div>
</dd>
<dt><code class="name"><a title="connpy.services" href="services/index.html">connpy.services</a></code></dt>
<dd>
<div class="desc"></div>
</dd>
<dt><code class="name"><a title="connpy.tunnels" href="tunnels.html">connpy.tunnels</a></code></dt>
<dd>
<div class="desc"></div>
</dd>
<dt><code class="name"><a title="connpy.utils" href="utils.html">connpy.utils</a></code></dt>
<dd>
<div class="desc"></div>
</dd>
</dl>
</section>
<section>
</section>
<section>
</section>
<section>
<h2 class="section-title" id="header-classes">Classes</h2>
<dl>
<dt id="connpy.Plugins"><code class="flex name class">
<span>class <span class="ident">Plugins</span></span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">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, &#34;plugin_preferences.json&#34;)
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, &#34;plugin_preferences.json&#34;)
try:
with open(path, &#34;w&#34;) as f:
json.dump(self.preferences, f, indent=4)
except OSError as e:
printer.error(f&#34;Failed to save plugin preferences: {e}&#34;)
def verify_script(self, file_path):
&#34;&#34;&#34;
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&#39;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: &#39;Parser&#39; and &#39;Entrypoint&#39;. and/or specific class: Preload.
- &#39;Parser&#39; class must only have an &#39;__init__&#39; method and must assign &#39;self.parser&#39;.
- &#39;Entrypoint&#39; class must have an &#39;__init__&#39; 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.
&#34;&#34;&#34;
with open(file_path, &#39;r&#39;) as file:
source_code = file.read()
try:
tree = ast.parse(source_code)
except SyntaxError as e:
return f&#34;Syntax error in file: {e}&#34;
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 &#39;if __name__ == &#34;__main__&#34;:&#39; block
if not (isinstance(node.test, ast.Compare) and
isinstance(node.test.left, ast.Name) and
node.test.left.id == &#39;__name__&#39; and
((hasattr(ast, &#39;Str&#39;) and isinstance(node.test.comparators[0], getattr(ast, &#39;Str&#39;)) and node.test.comparators[0].s == &#39;__main__&#39;) or
(hasattr(ast, &#39;Constant&#39;) and isinstance(node.test.comparators[0], getattr(ast, &#39;Constant&#39;)) and node.test.comparators[0].value == &#39;__main__&#39;))):
return &#34;Only __name__ == __main__ If is allowed&#34;
elif not isinstance(node, (ast.FunctionDef, ast.ClassDef, ast.Import, ast.ImportFrom, ast.Pass)):
return f&#34;Plugin can only have pass, functions, classes and imports. {node} is not allowed&#34; # Reject any other AST types
if isinstance(node, ast.ClassDef):
if node.name == &#39;Parser&#39;:
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 == &#39;__init__&#39; for method in node.body):
return &#34;Parser class should only have __init__ method&#34;
# Check if &#39;self.parser&#39; 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 == &#39;self&#39;]
if &#39;parser&#39; not in assigned_attrs:
return &#34;Parser class should set self.parser&#34;
elif node.name == &#39;Entrypoint&#39;:
has_entrypoint = True
init_method = next((item for item in node.body if isinstance(item, ast.FunctionDef) and item.name == &#39;__init__&#39;), None)
if not init_method or len(init_method.args.args) != 4: # self, args, parser, conapp
return &#34;Entrypoint class should have method __init__ and accept only arguments: args, parser and connapp&#34; # &#39;Entrypoint&#39; __init__ does not have correct signature
elif node.name == &#39;Preload&#39;:
has_preload = True
init_method = next((item for item in node.body if isinstance(item, ast.FunctionDef) and item.name == &#39;__init__&#39;), None)
if not init_method or len(init_method.args.args) != 2: # self, connapp
return &#34;Preload class should have method __init__ and accept only argument: connapp&#34; # &#39;Preload&#39; __init__ does not have correct signature
# Applying the combination logic based on class presence
if has_parser and not has_entrypoint:
return &#34;Parser requires Entrypoint class to be present.&#34;
elif has_entrypoint and not has_parser:
return &#34;Entrypoint requires Parser class to be present.&#34;
if not (has_parser or has_entrypoint or has_preload):
return &#34;No valid class (Parser, Entrypoint, or Preload) found.&#34;
return False # All requirements met, no error
def _import_from_path(self, path):
spec = importlib.util.spec_from_file_location(&#34;module.name&#34;, path)
module = importlib.util.module_from_spec(spec)
sys.modules[&#34;module.name&#34;] = 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(&#34;.py&#34;):
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) == &#34;remote&#34;:
continue
# Construct the full path
filepath = os.path.join(directory, filename)
check_file = self.verify_script(filepath)
if check_file:
printer.error(f&#34;Failed to load plugin: {filename}. Reason: {check_file}&#34;)
continue
else:
self.plugins[root_filename] = self._import_from_path(filepath)
if hasattr(self.plugins[root_filename], &#34;Parser&#34;):
self.plugin_parsers[root_filename] = self.plugins[root_filename].Parser()
plugin = self.plugin_parsers[root_filename]
# Default to RichHelpFormatter if plugin doesn&#39;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], &#34;Preload&#34;):
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(&#34;.py&#34;):
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(&#34;enabled&#34;, True):
continue
pref = self.preferences.get(name, &#34;local&#34;)
if pref != &#34;remote&#34; and name in self.plugins:
continue
if not force_sync and name in subparsers.choices:
continue
cache_path = os.path.join(cache_dir, f&#34;{name}.py&#34;)
# Hash comparison
remote_hash = info.get(&#34;hash&#34;, &#34;&#34;)
local_hash = &#34;&#34;
if os.path.exists(cache_path):
try:
with open(cache_path, &#34;rb&#34;) 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, &#34;w&#34;) as f:
f.write(source)
except Exception as e:
printer.warning(f&#34;Failed to sync remote plugin {name}: {e}&#34;)
continue
# Verify and load
check_file = self.verify_script(cache_path)
if check_file:
printer.warning(f&#34;Remote plugin {name} failed verification: {check_file}&#34;)
continue
module = self._import_from_path(cache_path)
if hasattr(module, &#34;Parser&#34;):
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&#39;s already there.
if name not in subparsers.choices:
subparsers.add_parser(
name,
parents=[plugin.parser],
add_help=False,
help=f&#34;[remote] {plugin.parser.description}&#34;,
usage=plugin.parser.usage,
description=plugin.parser.description,
epilog=plugin.parser.epilog,
formatter_class=fmt
)</code></pre>
</details>
<div class="desc"></div>
<h3>Methods</h3>
<dl>
<dt id="connpy.Plugins.verify_script"><code class="name flex">
<span>def <span class="ident">verify_script</span></span>(<span>self, file_path)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def verify_script(self, file_path):
&#34;&#34;&#34;
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&#39;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: &#39;Parser&#39; and &#39;Entrypoint&#39;. and/or specific class: Preload.
- &#39;Parser&#39; class must only have an &#39;__init__&#39; method and must assign &#39;self.parser&#39;.
- &#39;Entrypoint&#39; class must have an &#39;__init__&#39; 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.
&#34;&#34;&#34;
with open(file_path, &#39;r&#39;) as file:
source_code = file.read()
try:
tree = ast.parse(source_code)
except SyntaxError as e:
return f&#34;Syntax error in file: {e}&#34;
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 &#39;if __name__ == &#34;__main__&#34;:&#39; block
if not (isinstance(node.test, ast.Compare) and
isinstance(node.test.left, ast.Name) and
node.test.left.id == &#39;__name__&#39; and
((hasattr(ast, &#39;Str&#39;) and isinstance(node.test.comparators[0], getattr(ast, &#39;Str&#39;)) and node.test.comparators[0].s == &#39;__main__&#39;) or
(hasattr(ast, &#39;Constant&#39;) and isinstance(node.test.comparators[0], getattr(ast, &#39;Constant&#39;)) and node.test.comparators[0].value == &#39;__main__&#39;))):
return &#34;Only __name__ == __main__ If is allowed&#34;
elif not isinstance(node, (ast.FunctionDef, ast.ClassDef, ast.Import, ast.ImportFrom, ast.Pass)):
return f&#34;Plugin can only have pass, functions, classes and imports. {node} is not allowed&#34; # Reject any other AST types
if isinstance(node, ast.ClassDef):
if node.name == &#39;Parser&#39;:
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 == &#39;__init__&#39; for method in node.body):
return &#34;Parser class should only have __init__ method&#34;
# Check if &#39;self.parser&#39; 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 == &#39;self&#39;]
if &#39;parser&#39; not in assigned_attrs:
return &#34;Parser class should set self.parser&#34;
elif node.name == &#39;Entrypoint&#39;:
has_entrypoint = True
init_method = next((item for item in node.body if isinstance(item, ast.FunctionDef) and item.name == &#39;__init__&#39;), None)
if not init_method or len(init_method.args.args) != 4: # self, args, parser, conapp
return &#34;Entrypoint class should have method __init__ and accept only arguments: args, parser and connapp&#34; # &#39;Entrypoint&#39; __init__ does not have correct signature
elif node.name == &#39;Preload&#39;:
has_preload = True
init_method = next((item for item in node.body if isinstance(item, ast.FunctionDef) and item.name == &#39;__init__&#39;), None)
if not init_method or len(init_method.args.args) != 2: # self, connapp
return &#34;Preload class should have method __init__ and accept only argument: connapp&#34; # &#39;Preload&#39; __init__ does not have correct signature
# Applying the combination logic based on class presence
if has_parser and not has_entrypoint:
return &#34;Parser requires Entrypoint class to be present.&#34;
elif has_entrypoint and not has_parser:
return &#34;Entrypoint requires Parser class to be present.&#34;
if not (has_parser or has_entrypoint or has_preload):
return &#34;No valid class (Parser, Entrypoint, or Preload) found.&#34;
return False # All requirements met, no error</code></pre>
</details>
<div class="desc"><p>Verifies that a given Python script meets specific structural requirements.</p>
<p>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 <strong>name</strong> block)
and that it includes mandatory classes with specific attributes and methods.</p>
<h3 id="arguments">Arguments:</h3>
<pre><code>- file_path (str): The file path of the Python script to be verified.
</code></pre>
<h3 id="returns">Returns:</h3>
<pre><code>- str: A message indicating the type of violation if the script doesn't meet
the requirements, or False if all requirements are met.
</code></pre>
<h3 id="verifications">Verifications:</h3>
<pre><code>- 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.
</code></pre>
<p>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.</p>
<h3 id="exceptions">Exceptions:</h3>
<pre><code> - SyntaxError: If the script contains a syntax error, it is caught and
returned as a part of the error message.
</code></pre></div>
</dd>
</dl>
</dd>
<dt id="connpy.configfile"><code class="flex name class">
<span>class <span class="ident">configfile</span></span>
<span>(</span><span>conf=None, key=None, shared_config=None)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@ClassHook
class configfile:
&#39;&#39;&#39; 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.
&#39;&#39;&#39;
def __init__(self, conf = None, key = None, shared_config = None):
self._mutation_lock = threading.RLock()
self._cache_dirty = False
self._shared_config = shared_config
&#39;&#39;&#39;
### 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
&#39;&#39;&#39;
home = os.path.expanduser(&#34;~&#34;)
defaultdir = home + &#39;/.config/conn&#39;
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 + &#39;/.folder&#39;
try:
with open(pathfile, &#34;r&#34;) as f:
configdir = f.read().strip()
except (FileNotFoundError, IOError):
with open(pathfile, &#34;w&#34;) as f:
f.write(str(defaultdir))
configdir = defaultdir
self.defaultdir = configdir
self.file = configdir + &#39;/config.yaml&#39;
self.key = key or (configdir + &#39;/.osk&#39;)
# Ensure redirected directories exist
Path(configdir).mkdir(parents=True, exist_ok=True)
Path(f&#34;{configdir}/plugins&#34;).mkdir(parents=True, exist_ok=True)
# Backwards compatibility: Migrate from JSON to YAML only for default path
legacy_json = configdir + &#39;/config.json&#39;
legacy_noext = configdir + &#39;/config&#39;
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, &#39;r&#39;) as f:
old_data = json.load(f)
if not self._validate_config(old_data):
printer.warning(f&#34;Legacy config {legacy_file} has invalid structure, skipping migration.&#34;)
else:
with open(self.file, &#39;w&#39;) 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, &#39;r&#39;) as f:
verify = yaml.safe_load(f)
if not self._validate_config(verify):
os.remove(self.file)
printer.warning(&#34;YAML verification failed after migration, keeping legacy config.&#34;)
else:
# Note: cachefile is derived later, we use temp one for migration sync
temp_cache = configdir + &#39;/.config.cache.json&#39;
with open(temp_cache, &#39;w&#39;) as f:
json.dump(old_data, f)
shutil.move(legacy_file, legacy_file + &#34;.backup&#34;)
printer.success(f&#34;Migrated legacy config ({len(old_data.get(&#39;connections&#39;,{}))} folders/nodes) into YAML and Cache successfully!&#34;)
except Exception as e: # noqa: BLE001
if os.path.exists(self.file):
with suppress(OSError):
os.remove(self.file)
printer.warning(f&#34;Failed to migrate legacy config: {e}&#34;)
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 + &#39;/.osk&#39;)
# Sidecar files always live next to the config file (or in the redirected configdir)
self.cachefile = configdir + &#39;/.config.cache.json&#39;
self.fzf_cachefile = configdir + &#39;/.fzf_nodes_cache.txt&#39;
self.folders_cachefile = configdir + &#39;/.folders_cache.txt&#39;
self.profiles_cachefile = configdir + &#39;/.profiles_cache.txt&#39;
if os.path.exists(self.file):
config = self._loadconfig(self.file)
else:
config = self._createconfig(self.file)
self.config = config[&#34;config&#34;]
self.connections = config[&#34;connections&#34;]
self.profiles = config[&#34;profiles&#34;]
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, &#39;_privatekey_obj&#39;, 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, &#39;_publickey_obj&#39;, 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):
&#34;&#34;&#34;Get config setting with shared fallback for inheritable keys.&#34;&#34;&#34;
val = self.config.get(key)
if key == &#34;ai&#34;:
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 &#34;engineer_api_key&#34; in val or &#34;engineer_auth&#34; in val:
base.pop(&#34;engineer_api_key&#34;, None)
base.pop(&#34;engineer_auth&#34;, None)
# If user defines architect credentials, discard shared ones
if &#34;architect_api_key&#34; in val or &#34;architect_auth&#34; in val:
base.pop(&#34;architect_api_key&#34;, None)
base.pop(&#34;architect_auth&#34;, 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):
&#34;&#34;&#34;Strictly validate tags, fallback, and password compose syntax on a node or profile entry.&#34;&#34;&#34;
if not isinstance(entry, dict):
return
if &#34;tags&#34; in entry and entry[&#34;tags&#34;] not in (&#34;&#34;, None):
validate_auth_budget_tags(entry[&#34;tags&#34;])
if &#34;fallback&#34; in entry and entry[&#34;fallback&#34;] not in (None, &#34;&#34;, []):
validate_fallback_entries(entry[&#34;fallback&#34;])
pw = entry.get(&#34;password&#34;)
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):
&#34;&#34;&#34;Recursively validate all connection dicts inside nested folders/subfolders.&#34;&#34;&#34;
if not isinstance(container, dict):
raise TypeError(&#34;Connections container must be a dict&#34;)
for key, val in container.items():
if key == &#34;type&#34; or not isinstance(val, dict):
continue
entry_type = val.get(&#34;type&#34;)
if entry_type in (&#34;folder&#34;, &#34;subfolder&#34;):
self._walk_connections_validate_unlocked(val)
else:
self._validate_config_entry_unlocked(val)
def _validate_config_strict(self, data):
&#34;&#34;&#34;Strictly validate config structure, budgets, and fallback rules; raises on error.&#34;&#34;&#34;
if not isinstance(data, dict):
raise TypeError(&#34;Config root must be a dict&#34;)
required = {&#34;config&#34;, &#34;connections&#34;, &#34;profiles&#34;}
if not required.issubset(data.keys()):
raise ValueError(&#34;Config missing required sections&#34;)
if not isinstance(data[&#34;config&#34;], dict):
raise TypeError(&#34;&#39;config&#39; section must be a dict&#34;)
if not isinstance(data[&#34;connections&#34;], dict):
raise TypeError(&#34;&#39;connections&#39; section must be a dict&#34;)
if not isinstance(data[&#34;profiles&#34;], dict):
raise TypeError(&#34;&#39;profiles&#39; section must be a dict&#34;)
validate_config_auth_settings(data[&#34;config&#34;])
self._walk_connections_validate_unlocked(data[&#34;connections&#34;])
for prof_val in data[&#34;profiles&#34;].values():
if not isinstance(prof_val, dict):
raise TypeError(&#34;Each profile entry must be a dict&#34;)
self._validate_config_entry_unlocked(prof_val)
def _validate_config(self, data):
&#34;&#34;&#34;Verify config data has the required structure.&#34;&#34;&#34;
try:
self._validate_config_strict(data)
except (ValueError, TypeError, SanitizedAuthError):
return False
return True
def _atomic_write_text_unlocked(self, target_path, writer):
&#34;&#34;&#34;Atomically write text file with symlink refusal, 0o600 mode, fsync, and os.replace.&#34;&#34;&#34;
if os.path.islink(target_path):
raise OSError(f&#34;Refusing to write through symlink: {target_path}&#34;)
target_dir = os.path.dirname(os.path.abspath(target_path)) or &#34;.&#34;
os.makedirs(target_dir, exist_ok=True)
fd, tmp_path = tempfile.mkstemp(
dir=target_dir,
prefix=f&#34;.{os.path.basename(target_path)}.&#34;,
suffix=&#34;.tmp&#34;,
)
try:
with os.fdopen(fd, &#34;w&#34;, encoding=&#34;utf-8&#34;) 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 &#34;.&#34;
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 &gt; cache_time:
with open(conf, &#39;r&#39;) 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(&#34;Config file appears corrupt, recovering from cache...&#34;)
with open(self.cachefile, &#39;r&#39;) 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(&#34;Config file is corrupt and no valid cache exists. Creating default config.&#34;)
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, &#39;r&#39;) as f:
data = json.load(f)
if not self._validate_config(data):
# Cache broken, try yaml
with open(conf, &#39;r&#39;) as f:
data = yaml.safe_load(f)
if self._validate_config(data):
return data
# Both broken
printer.error(&#34;Both config and cache are corrupt. Creating default config.&#34;)
return self._createconfig(conf)
return data
def _createconfig(self, conf):
#Create config file (always writes defaults, safe for recovery)
defaultconfig = {&#39;config&#39;: {&#39;case&#39;: False, &#39;idletime&#39;: 30, &#39;fzf&#39;: False}, &#39;connections&#39;: {}, &#39;profiles&#39;: { &#34;default&#34;: { &#34;host&#34;:&#34;&#34;, &#34;protocol&#34;:&#34;ssh&#34;, &#34;port&#34;:&#34;&#34;, &#34;user&#34;:&#34;&#34;, &#34;password&#34;:&#34;&#34;, &#34;options&#34;:&#34;&#34;, &#34;logs&#34;:&#34;&#34;, &#34;tags&#34;: &#34;&#34;, &#34;jumphost&#34;:&#34;&#34;, &#34;fallback&#34;: &#34;&#34;}}}
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 = {
&#34;config&#34;: self.config,
&#34;connections&#34;: self.connections,
&#34;profiles&#34;: 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&#34;Failed to save config: {e}&#34;
# 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._generate_nodes_cache_unlocked(_raise_on_error=True)
self._cache_dirty = False
except (OSError, TypeError, ValueError):
self._cache_dirty = True
return 0, None
def _run_saveconfig_post_hooks(self, conf, result):
&#34;&#34;&#34;Run @MethodHook post-hooks registered for _saveconfig outside _mutation_lock.&#34;&#34;&#34;
cls_desc = type(self).__dict__.get(&#34;_saveconfig&#34;)
cls_post = list(cls_desc.post_hooks) if isinstance(cls_desc, MethodHook) else []
inst_post = (
self.__dict__.get(&#34;_method_post_hooks&#34;, {}).get(&#34;_saveconfig&#34;, [])
if isinstance(self.__dict__.get(&#34;_method_post_hooks&#34;), 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, &#34;__name__&#34;, str(hook))
printer.error(f&#34;_saveconfig Post-hook {hook_name} raised an exception: {e}&#34;)
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):
&#34;&#34;&#34;Run mutator atomically inside _mutation_lock with in-place RAM rollback on error.&#34;&#34;&#34;
save_desc = type(self).__dict__.get(&#34;_saveconfig&#34;)
mocked_save = &#34;_saveconfig&#34; 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(
{
&#34;config&#34;: self.config,
&#34;connections&#34;: self.connections,
&#34;profiles&#34;: self.profiles,
}
)
if mocked_save:
rc = self._saveconfig(self.file)
if rc != 0:
raise OSError(&#34;Failed to save config&#34;)
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):
&#34;&#34;&#34;Rebuild JSON and fzf sidecar caches atomically; returns True on success.&#34;&#34;&#34;
with self._mutation_lock:
snapshot = {
&#34;config&#34;: self.config,
&#34;connections&#34;: self.connections,
&#34;profiles&#34;: 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 _generate_nodes_cache_unlocked(self, nodes=None, folders=None, profiles=None, *, _raise_on_error=False):
try:
if nodes is None:
nodes = self._getallnodes_unlocked()
if folders is None:
folders = self._getallfolders_unlocked()
if profiles is None:
profiles = list(self.profiles.keys())
self._atomic_write_text_unlocked(self.fzf_cachefile, lambda f: f.write(&#34;\n&#34;.join(nodes)))
self._atomic_write_text_unlocked(self.folders_cachefile, lambda f: f.write(&#34;\n&#34;.join(folders)))
self._atomic_write_text_unlocked(self.profiles_cachefile, lambda f: f.write(&#34;\n&#34;.join(profiles)))
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,&#39;wb&#39;) as f:
f.write(key.export_key(&#39;PEM&#39;))
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(&#34;@&#34;)
if not unique.startswith(&#34;@&#34;):
result = {&#34;id&#34;: uniques[0]}
else:
result = {}
if len(uniques) == 2:
result[&#34;folder&#34;] = uniques[1]
if result[&#34;folder&#34;] == &#34;&#34;:
return False
elif len(uniques) == 3:
result[&#34;folder&#34;] = uniques[2]
result[&#34;subfolder&#34;] = uniques[1]
if result[&#34;folder&#34;] == &#34;&#34; or result[&#34;subfolder&#34;] == &#34;&#34;:
return False
elif len(uniques) &gt; 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 &gt;= 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 == &#34;password&#34;:
if isinstance(val, str):
if is_compose_expression(val):
return val
if val.startswith(&#34;@&#34;) 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(&#34;@&#34;)
and item[1:] in self.profiles
):
sub = self._resolve_profile_attr_unlocked(
item[1:],
&#34;password&#34;,
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(&#34;@&#34;) 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 &#34;&#34;
return deepcopy(val)
def _find_inherited_profile_fallback_unlocked(self, raw_user, raw_pw):
&#34;&#34;&#34;Inherit fallback from a primary @profile referenced by node user/password.&#34;&#34;&#34;
candidates = []
for raw_val, field in ((raw_user, &#34;user&#34;), (raw_pw, &#34;password&#34;)):
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(&#34;@&#34;)
and &#34;+&#34; not in candidate_val
):
prof_name = candidate_val[1:]
visited = set()
while prof_name and prof_name not in visited and len(visited) &lt; MAX_PROFILE_DEPTH:
visited.add(prof_name)
prof = self.profiles.get(prof_name)
if not isinstance(prof, dict):
break
prof_fb = prof.get(&#34;fallback&#34;)
if prof_fb in (None, &#34;&#34;, []) and isinstance(prof.get(&#34;tags&#34;), dict):
prof_fb = prof[&#34;tags&#34;].get(&#34;fallback&#34;)
if prof_fb not in (None, &#34;&#34;, []):
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(&#34;@&#34;)
and &#34;+&#34; not in item
),
None,
)
prof_name = next_ref[1:] if next_ref else &#34;&#34;
elif (
isinstance(next_val, str)
and not is_compose_expression(next_val)
and next_val.startswith(&#34;@&#34;)
and &#34;+&#34; not in next_val
):
prof_name = next_val[1:]
else:
break
return None
def _extract_node_fields_unlocked(self, node_dict):
&#34;&#34;&#34;Resolve @profile references on a copied node dict, keeping legacy core.node(**cfg) contract.&#34;&#34;&#34;
raw_user = node_dict.get(&#34;user&#34;)
raw_pw = node_dict.get(&#34;password&#34;)
raw_fb = node_dict.pop(&#34;fallback&#34;, None)
for key, value in list(node_dict.items()):
if key == &#34;password&#34;:
if isinstance(value, str):
if is_compose_expression(value):
continue
if value.startswith(&#34;@&#34;) and value[1:] in self.profiles:
resolved = self._resolve_profile_attr_unlocked(value[1:], &#34;password&#34;)
node_dict[&#34;password&#34;] = resolved if resolved is not None else &#34;&#34;
elif isinstance(value, list):
resolved_pw = []
for item in value:
if (
isinstance(item, str)
and not is_compose_expression(item)
and item.startswith(&#34;@&#34;)
and item[1:] in self.profiles
):
sub = self._resolve_profile_attr_unlocked(item[1:], &#34;password&#34;)
if isinstance(sub, list):
resolved_pw.extend(deepcopy(sub))
elif sub is not None:
resolved_pw.append(deepcopy(sub))
else:
resolved_pw.append(&#34;&#34;)
else:
resolved_pw.append(deepcopy(item))
node_dict[&#34;password&#34;] = resolved_pw
continue
if isinstance(value, str) and value.startswith(&#34;@&#34;):
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 &#34;&#34;
else:
node_dict[key] = &#34;&#34;
elif value == &#34;&#34; and key == &#34;protocol&#34;:
default_proto = self.profiles.get(&#34;default&#34;, {}).get(&#34;protocol&#34;, &#34;ssh&#34;)
node_dict[key] = default_proto if default_proto else &#34;ssh&#34;
tags_fb_present = (
isinstance(node_dict.get(&#34;tags&#34;), dict)
and node_dict[&#34;tags&#34;].get(&#34;fallback&#34;) not in (None, &#34;&#34;, [])
)
if raw_fb in (None, &#34;&#34;, []) 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, &#34;&#34;, []):
resolved_fb = resolve_fallback_entries(raw_fb, self.profiles)
if resolved_fb:
tags_val = node_dict.get(&#34;tags&#34;, &#34;&#34;)
if isinstance(tags_val, dict):
tags_copy = deepcopy(tags_val)
tags_copy[&#34;_fallback&#34;] = resolved_fb
node_dict[&#34;tags&#34;] = tags_copy
elif tags_val in (&#34;&#34;, None):
node_dict[&#34;tags&#34;] = {&#34;_fallback&#34;: resolved_fb}
else:
node_dict[&#34;tags&#34;] = {&#34;_raw&#34;: tags_val, &#34;_fallback&#34;: resolved_fb}
elif isinstance(node_dict.get(&#34;tags&#34;), dict) and node_dict[&#34;tags&#34;].get(&#34;fallback&#34;) not in (None, &#34;&#34;, []):
tags_copy = deepcopy(node_dict[&#34;tags&#34;])
tags_copy[&#34;_fallback&#34;] = resolve_fallback_entries(tags_copy[&#34;fallback&#34;], self.profiles)
node_dict[&#34;tags&#34;] = tags_copy
def getitem_unlocked(self, unique, keys=None, extract=False):
uniques = self._explode_unique_unlocked(unique)
if unique.startswith(&#34;@&#34;):
if uniques.keys() &gt;= {&#34;folder&#34;, &#34;subfolder&#34;}:
folder = self.connections[uniques[&#34;folder&#34;]][uniques[&#34;subfolder&#34;]]
else:
folder = self.connections[uniques[&#34;folder&#34;]]
newfolder = deepcopy(folder)
newfolder.pop(&#34;type&#34;)
for node_name in list(folder.keys()):
if node_name == &#34;type&#34;:
continue
if &#34;type&#34; in newfolder[node_name]:
if newfolder[node_name][&#34;type&#34;] == &#34;subfolder&#34;:
newfolder.pop(node_name)
else:
newfolder[node_name].pop(&#34;type&#34;)
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&#34;{k}{unique}&#34;: v for k, v in newfolder.items()}
if uniques.keys() &gt;= {&#34;folder&#34;, &#34;subfolder&#34;}:
node = self.connections[uniques[&#34;folder&#34;]][uniques[&#34;subfolder&#34;]][uniques[&#34;id&#34;]]
elif &#34;folder&#34; in uniques:
node = self.connections[uniques[&#34;folder&#34;]][uniques[&#34;id&#34;]]
else:
node = self.connections[uniques[&#34;id&#34;]]
newnode = deepcopy(node)
newnode.pop(&#34;type&#34;)
if extract:
self._extract_node_fields_unlocked(newnode)
return newnode
@MethodHook
def getitem(self, unique, keys = None, extract = False):
&#34;&#34;&#34;Get a node or folder of nodes from configfile.&#34;&#34;&#34;
with self._mutation_lock:
return self.getitem_unlocked(unique, keys=keys, extract=extract)
@MethodHook
def getitems(self, uniques, extract = False):
&#39;&#39;&#39;
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.
&#39;&#39;&#39;
if isinstance(uniques, str):
uniques = [uniques]
with self._mutation_lock:
nodes = {}
case_sensitive = self.config.get(&#34;case&#34;, False)
for item in uniques:
target = item if case_sensitive else item.lower()
if target.startswith(&#34;@&#34;):
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=&#39;&#39;,
subfolder=&#39;&#39;,
options=&#39;&#39;,
logs=&#39;&#39;,
password=&#39;&#39;,
port=&#39;&#39;,
protocol=&#39;&#39;,
user=&#39;&#39;,
tags=&#39;&#39;,
jumphost=&#39;&#39;,
fallback=&#39;&#39;,
type=&#34;connection&#34;,
):
entry = {
&#34;host&#34;: host,
&#34;options&#34;: options,
&#34;logs&#34;: logs,
&#34;password&#34;: password,
&#34;port&#34;: port,
&#34;protocol&#34;: protocol,
&#34;user&#34;: user,
&#34;tags&#34;: tags,
&#34;jumphost&#34;: jumphost,
&#34;fallback&#34;: fallback,
&#34;type&#34;: type,
}
if folder == &#39;&#39;:
self.connections[id] = entry
elif subfolder == &#39;&#39;:
self.connections[folder][id] = entry
else:
self.connections[folder][subfolder][id] = entry
@MethodHook
def _connections_add(self,*, id, host, folder=&#39;&#39;, subfolder=&#39;&#39;, options=&#39;&#39;, logs=&#39;&#39;, password=&#39;&#39;, port=&#39;&#39;, protocol=&#39;&#39;, user=&#39;&#39;, tags=&#39;&#39;, jumphost=&#39;&#39;, fallback=&#39;&#39;, type = &#34;connection&#34; ):
#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=&#39;&#39;, subfolder=&#39;&#39;):
if folder == &#39;&#39;:
del self.connections[id]
elif subfolder == &#39;&#39;:
del self.connections[folder][id]
else:
del self.connections[folder][subfolder][id]
@MethodHook
def _connections_del(self,*, id, folder=&#39;&#39;, subfolder=&#39;&#39;):
#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=&#39;&#39;):
if subfolder == &#39;&#39;:
if folder not in self.connections:
self.connections[folder] = {&#34;type&#34;: &#34;folder&#34;}
else:
if subfolder not in self.connections[folder]:
self.connections[folder][subfolder] = {&#34;type&#34;: &#34;subfolder&#34;}
@MethodHook
def _folder_add(self,*, folder, subfolder = &#39;&#39;):
#Add Folder from config
with self._mutation_lock:
self._folder_add_unlocked(folder=folder, subfolder=subfolder)
def _folder_del_unlocked(self, *, folder, subfolder=&#39;&#39;):
if subfolder == &#39;&#39;:
del self.connections[folder]
else:
del self.connections[folder][subfolder]
@MethodHook
def _folder_del(self,*, folder, subfolder=&#39;&#39;):
#Delete folder from config
with self._mutation_lock:
self._folder_del_unlocked(folder=folder, subfolder=subfolder)
def _profiles_add_unlocked(self, *, id, host=&#39;&#39;, options=&#39;&#39;, logs=&#39;&#39;, password=&#39;&#39;, port=&#39;&#39;, protocol=&#39;&#39;, user=&#39;&#39;, tags=&#39;&#39;, jumphost=&#39;&#39;, fallback=&#39;&#39;):
self.profiles[id] = {
&#34;host&#34;: host,
&#34;options&#34;: options,
&#34;logs&#34;: logs,
&#34;password&#34;: password,
&#34;port&#34;: port,
&#34;protocol&#34;: protocol,
&#34;user&#34;: user,
&#34;tags&#34;: tags,
&#34;jumphost&#34;: jumphost,
&#34;fallback&#34;: fallback,
}
@MethodHook
def _profiles_add(self,*, id, host = &#39;&#39;, options=&#39;&#39;, logs=&#39;&#39;, password=&#39;&#39;, port=&#39;&#39;, protocol=&#39;&#39;, user=&#39;&#39;, tags=&#39;&#39;, jumphost=&#39;&#39;, fallback=&#39;&#39;):
#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(&#34;type&#34;) == &#34;connection&#34;]
folders = [k for k, v in self.connections.items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;folder&#34;]
nodes.extend(layer1)
for f in folders:
layer2 = [k + &#34;@&#34; + f for k, v in self.connections[f].items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;connection&#34;]
nodes.extend(layer2)
subfolders = [k for k, v in self.connections[f].items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;subfolder&#34;]
for s in subfolders:
layer3 = [k + &#34;@&#34; + s + &#34;@&#34; + f for k, v in self.connections[f][s].items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;connection&#34;]
nodes.extend(layer3)
if filter:
flat_filter = self._normalize_filter_arg(filter)
flags = re.IGNORECASE if not self.config.get(&#34;case&#34;, 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(&#34;Filter must be a string or a list of strings&#34;)
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(&#34;type&#34;) == &#34;connection&#34;}
folders = [k for k, v in self.connections.items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;folder&#34;]
nodes.update(layer1)
for f in folders:
layer2 = {k + &#34;@&#34; + f: deepcopy(v) for k, v in self.connections[f].items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;connection&#34;}
nodes.update(layer2)
subfolders = [k for k, v in self.connections[f].items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;subfolder&#34;]
for s in subfolders:
layer3 = {k + &#34;@&#34; + s + &#34;@&#34; + f: deepcopy(v) for k, v in self.connections[f][s].items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;connection&#34;}
nodes.update(layer3)
if filter:
flat_filter = self._normalize_filter_arg(filter)
flat_filter = [&#34;^(?!.*@).+$&#34; if item == &#34;@&#34; 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(&#34;Filter must be a string or a list of strings&#34;)
sys.exit(1)
with self._mutation_lock:
return self._getallnodesfull_unlocked(filter=filter, extract=extract)
def _getallfolders_unlocked(self):
folders = [&#34;@&#34; + k for k, v in self.connections.items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;folder&#34;]
subfolders = []
for f in folders:
s = [&#34;@&#34; + k + f for k, v in self.connections[f[1:]].items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;subfolder&#34;]
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) &amp; 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(&#34;type&#34;) == &#34;connection&#34;
and bool(extract_profile_refs_from_value(v) &amp; target_profiles)
]
folders = [k for k, v in self.connections.items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;folder&#34;]
nodes.extend(layer1)
for f in folders:
layer2 = [
k + &#34;@&#34; + f
for k, v in self.connections[f].items()
if isinstance(v, dict)
and v.get(&#34;type&#34;) == &#34;connection&#34;
and bool(extract_profile_refs_from_value(v) &amp; target_profiles)
]
nodes.extend(layer2)
subfolders = [k for k, v in self.connections[f].items() if isinstance(v, dict) and v.get(&#34;type&#34;) == &#34;subfolder&#34;]
for s in subfolders:
layer3 = [
k + &#34;@&#34; + s + &#34;@&#34; + f
for k, v in self.connections[f][s].items()
if isinstance(v, dict)
and v.get(&#34;type&#34;) == &#34;connection&#34;
and bool(extract_profile_refs_from_value(v) &amp; 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):
&#39;&#39;&#39;
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.
&#39;&#39;&#39;
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(&#34;utf-8&#34;))
return str(password)</code></pre>
</details>
<div class="desc"><p>This class generates a configfile object. Containts a dictionary storing, config, nodes and profiles, normaly used by connection manager.</p>
<h3 id="attributes">Attributes:</h3>
<pre><code>- 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.
</code></pre></div>
<h3>Instance variables</h3>
<dl>
<dt id="connpy.configfile.privatekey"><code class="name">prop <span class="ident">privatekey</span></code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@property
def privatekey(self):
if getattr(self, &#39;_privatekey_obj&#39;, 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</code></pre>
</details>
<div class="desc"></div>
</dd>
<dt id="connpy.configfile.publickey"><code class="name">prop <span class="ident">publickey</span></code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@property
def publickey(self):
if getattr(self, &#39;_publickey_obj&#39;, None) is None:
self._publickey_obj = self.privatekey.publickey()
return self._publickey_obj</code></pre>
</details>
<div class="desc"></div>
</dd>
</dl>
<h3>Methods</h3>
<dl>
<dt id="connpy.configfile.encrypt"><code class="name flex">
<span>def <span class="ident">encrypt</span></span>(<span>self, password, keyfile=None)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@MethodHook
def encrypt(self, password, keyfile=None):
&#39;&#39;&#39;
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.
&#39;&#39;&#39;
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(&#34;utf-8&#34;))
return str(password)</code></pre>
</details>
<div class="desc"><p>Encrypts password using RSA keyfile</p>
<h3 id="parameters">Parameters:</h3>
<pre><code>- password (str): Plaintext password to encrypt.
</code></pre>
<h3 id="optional-parameters">Optional Parameters:</h3>
<pre><code>- keyfile (str): Path/file to keyfile. Default is config keyfile.
</code></pre>
<h3 id="returns">Returns:</h3>
<pre><code>str: Encrypted password.
</code></pre></div>
</dd>
<dt id="connpy.configfile.get_effective_setting"><code class="name flex">
<span>def <span class="ident">get_effective_setting</span></span>(<span>self, key, default=None)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def get_effective_setting(self, key, default=None):
&#34;&#34;&#34;Get config setting with shared fallback for inheritable keys.&#34;&#34;&#34;
val = self.config.get(key)
if key == &#34;ai&#34;:
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 &#34;engineer_api_key&#34; in val or &#34;engineer_auth&#34; in val:
base.pop(&#34;engineer_api_key&#34;, None)
base.pop(&#34;engineer_auth&#34;, None)
# If user defines architect credentials, discard shared ones
if &#34;architect_api_key&#34; in val or &#34;architect_auth&#34; in val:
base.pop(&#34;architect_api_key&#34;, None)
base.pop(&#34;architect_auth&#34;, 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</code></pre>
</details>
<div class="desc"><p>Get config setting with shared fallback for inheritable keys.</p></div>
</dd>
<dt id="connpy.configfile.getitem"><code class="name flex">
<span>def <span class="ident">getitem</span></span>(<span>self, unique, keys=None, extract=False)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@MethodHook
def getitem(self, unique, keys = None, extract = False):
&#34;&#34;&#34;Get a node or folder of nodes from configfile.&#34;&#34;&#34;
with self._mutation_lock:
return self.getitem_unlocked(unique, keys=keys, extract=extract)</code></pre>
</details>
<div class="desc"><p>Get a node or folder of nodes from configfile.</p></div>
</dd>
<dt id="connpy.configfile.getitem_unlocked"><code class="name flex">
<span>def <span class="ident">getitem_unlocked</span></span>(<span>self, unique, keys=None, extract=False)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def getitem_unlocked(self, unique, keys=None, extract=False):
uniques = self._explode_unique_unlocked(unique)
if unique.startswith(&#34;@&#34;):
if uniques.keys() &gt;= {&#34;folder&#34;, &#34;subfolder&#34;}:
folder = self.connections[uniques[&#34;folder&#34;]][uniques[&#34;subfolder&#34;]]
else:
folder = self.connections[uniques[&#34;folder&#34;]]
newfolder = deepcopy(folder)
newfolder.pop(&#34;type&#34;)
for node_name in list(folder.keys()):
if node_name == &#34;type&#34;:
continue
if &#34;type&#34; in newfolder[node_name]:
if newfolder[node_name][&#34;type&#34;] == &#34;subfolder&#34;:
newfolder.pop(node_name)
else:
newfolder[node_name].pop(&#34;type&#34;)
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&#34;{k}{unique}&#34;: v for k, v in newfolder.items()}
if uniques.keys() &gt;= {&#34;folder&#34;, &#34;subfolder&#34;}:
node = self.connections[uniques[&#34;folder&#34;]][uniques[&#34;subfolder&#34;]][uniques[&#34;id&#34;]]
elif &#34;folder&#34; in uniques:
node = self.connections[uniques[&#34;folder&#34;]][uniques[&#34;id&#34;]]
else:
node = self.connections[uniques[&#34;id&#34;]]
newnode = deepcopy(node)
newnode.pop(&#34;type&#34;)
if extract:
self._extract_node_fields_unlocked(newnode)
return newnode</code></pre>
</details>
<div class="desc"></div>
</dd>
<dt id="connpy.configfile.getitems"><code class="name flex">
<span>def <span class="ident">getitems</span></span>(<span>self, uniques, extract=False)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@MethodHook
def getitems(self, uniques, extract = False):
&#39;&#39;&#39;
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.
&#39;&#39;&#39;
if isinstance(uniques, str):
uniques = [uniques]
with self._mutation_lock:
nodes = {}
case_sensitive = self.config.get(&#34;case&#34;, False)
for item in uniques:
target = item if case_sensitive else item.lower()
if target.startswith(&#34;@&#34;):
nodes.update(self.getitem_unlocked(target, extract=extract))
else:
nodes[target] = self.getitem_unlocked(target, extract=extract)
return nodes</code></pre>
</details>
<div class="desc"><p>Get a group of nodes from configfile which can be passed to node/nodes class</p>
<h3 id="parameters">Parameters:</h3>
<pre><code>- uniques (str/list): String name that will match hostnames
from the connection manager. It can be a
list of strings.
</code></pre>
<h3 id="optional-parameters">Optional Parameters:</h3>
<pre><code>- extract (bool): If True, extract information from profiles.
Default False.
</code></pre>
<h3 id="returns">Returns:</h3>
<pre><code>dict: Dictionary containing information of node or multiple
dictionaries of multiple nodes.
</code></pre></div>
</dd>
<dt id="connpy.configfile.refresh_cache"><code class="name flex">
<span>def <span class="ident">refresh_cache</span></span>(<span>self)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def refresh_cache(self):
&#34;&#34;&#34;Rebuild JSON and fzf sidecar caches atomically; returns True on success.&#34;&#34;&#34;
with self._mutation_lock:
snapshot = {
&#34;config&#34;: self.config,
&#34;connections&#34;: self.connections,
&#34;profiles&#34;: 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</code></pre>
</details>
<div class="desc"><p>Rebuild JSON and fzf sidecar caches atomically; returns True on success.</p></div>
</dd>
<dt id="connpy.configfile.transactional_update"><code class="name flex">
<span>def <span class="ident">transactional_update</span></span>(<span>self, mutator)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">def transactional_update(self, mutator):
&#34;&#34;&#34;Run mutator atomically inside _mutation_lock with in-place RAM rollback on error.&#34;&#34;&#34;
save_desc = type(self).__dict__.get(&#34;_saveconfig&#34;)
mocked_save = &#34;_saveconfig&#34; 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(
{
&#34;config&#34;: self.config,
&#34;connections&#34;: self.connections,
&#34;profiles&#34;: self.profiles,
}
)
if mocked_save:
rc = self._saveconfig(self.file)
if rc != 0:
raise OSError(&#34;Failed to save config&#34;)
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</code></pre>
</details>
<div class="desc"><p>Run mutator atomically inside _mutation_lock with in-place RAM rollback on error.</p></div>
</dd>
</dl>
</dd>
<dt id="connpy.node"><code class="flex name class">
<span>class <span class="ident">node</span></span>
<span>(</span><span>unique,<br>host,<br>options='',<br>logs='',<br>password='',<br>port='',<br>protocol='',<br>user='',<br>config='',<br>tags='',<br>jumphost='',<br>allow_unsafe_options=None,<br>fallback=None,<br>disable_fallback_on_insecure_hostkey=None)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@ClassHook
class node:
&#39;&#39;&#39; 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.
&#39;&#39;&#39;
def __init__(
self,
unique,
host,
options=&#39;&#39;,
logs=&#39;&#39;,
password=&#39;&#39;,
port=&#39;&#39;,
protocol=&#39;&#39;,
user=&#39;&#39;,
config=&#39;&#39;,
tags=&#39;&#39;,
jumphost=&#39;&#39;,
allow_unsafe_options=None,
fallback=None,
disable_fallback_on_insecure_hostkey=None,
):
&#39;&#39;&#39;
### 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 &#34;os&#34;, &#34;prompt&#34; and &#34;screenleght_command&#34;
- jumphost (str): Reference another node to be used as a jumphost
- allow_unsafe_options (bool): Explicitly override safety restrictions.
&#39;&#39;&#39;
self.config = config
if config == &#39;&#39;:
self.idletime = 0
self.key = None
else:
self.idletime = config.config[&#34;idletime&#34;] if (hasattr(config, &#34;config&#34;) and isinstance(config.config, dict) and &#34;idletime&#34; in config.config) else 0
self.key = getattr(config, &#34;key&#34;, None)
if allow_unsafe_options is not None:
self.allow_unsafe_options = bool(allow_unsafe_options)
elif config != &#39;&#39; and config is not None and hasattr(config, &#34;config&#34;) and isinstance(config.config, dict):
self.allow_unsafe_options = bool(config.config.get(&#34;allow_unsafe_options&#34;, False))
else:
self.allow_unsafe_options = False
self.unique = unique
profiles_map = getattr(config, &#34;profiles&#34;, {}) if (config != &#39;&#39; and config is not None) else {}
attr = {&#34;host&#34;: host, &#34;logs&#34;: logs, &#34;options&#34;:options, &#34;port&#34;: port, &#34;protocol&#34;: protocol, &#34;user&#34;: user, &#34;tags&#34;: tags, &#34;jumphost&#34;: jumphost}
for key, attr_val in attr.items():
profile = re.search(&#34;^@(.*)&#34;, str(attr_val))
if profile and config != &#39;&#39;:
try:
setattr(self, key, deepcopy(profiles_map[profile.group(1)][key]))
except KeyError:
setattr(self, key, &#34;&#34;)
elif attr_val == &#39;&#39; and key == &#34;protocol&#34;:
try:
setattr(self, key, profiles_map[&#34;default&#34;][key])
except (KeyError, AttributeError):
setattr(self, key, &#34;ssh&#34;)
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(&#34;@&#34;)
and config != &#39;&#39;
and item[1:] in profiles_map
):
self.password.append(deepcopy(profiles_map[item[1:]].get(&#34;password&#34;, &#34;&#34;)))
else:
self.password.append(item)
else:
if (
isinstance(password, str)
and not is_compose_expression(password)
and password.startswith(&#34;@&#34;)
and config != &#39;&#39;
and password[1:] in profiles_map
):
resolved_pw = profiles_map[password[1:]].get(&#34;password&#34;, &#34;&#34;)
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, &#34;&#34;, []) and isinstance(self.tags, dict):
if &#34;_fallback&#34; in self.tags:
raw_fallback = self.tags.pop(&#34;_fallback&#34;, None)
elif &#34;fallback&#34; in self.tags:
raw_fallback = self.tags.get(&#34;fallback&#34;)
if raw_fallback not in (None, &#34;&#34;, []):
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 != &#34;&#34;
)
if primary_specs:
candidates.append(
AuthCandidate(
user=str(self.user or &#34;&#34;),
password_spec=primary_specs if len(primary_specs) &gt; 1 else primary_specs[0],
is_fallback=False,
label=&#34;primary&#34;,
)
)
elif self.user:
candidates.append(
AuthCandidate(
user=str(self.user or &#34;&#34;),
password_spec=&#34;&#34;,
is_fallback=False,
label=&#34;primary&#34;,
)
)
for fb_idx, entry in enumerate(resolved_fb_entries, start=1):
fb_user = str(entry.get(&#34;user&#34;) or self.user or &#34;&#34;)
fb_pw = entry.get(&#34;password&#34;, &#34;&#34;)
if isinstance(fb_pw, list):
pw_spec: str | tuple[str, ...] = tuple(str(x) for x in fb_pw if x != &#34;&#34;)
else:
pw_spec = str(fb_pw or &#34;&#34;)
candidates.append(
AuthCandidate(
user=fb_user,
password_spec=pw_spec,
is_fallback=True,
label=f&#34;fallback#{fb_idx}&#34;,
)
)
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 &#34;disable_fallback_on_insecure_hostkey&#34; in self.tags:
self.disable_fallback_on_insecure_hostkey = bool(
self.tags[&#34;disable_fallback_on_insecure_hostkey&#34;]
)
elif (
config != &#39;&#39;
and config is not None
and hasattr(config, &#34;config&#34;)
and isinstance(config.config, dict)
):
self.disable_fallback_on_insecure_hostkey = bool(
config.config.get(&#34;disable_fallback_on_insecure_hostkey&#34;, False)
)
else:
self.disable_fallback_on_insecure_hostkey = False
self._jumphost_name = self.jumphost if (self.jumphost != &#34;&#34; and config != &#39;&#39;) else &#34;&#34;
self._hop_chain_meta = []
self._jumphost_hops: tuple[dict, ...] = ()
if self.jumphost != &#34;&#34; and config != &#39;&#39;:
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(&#39;\\&#39;, &#39;\\\\&#39;).replace(&#39;&#34;&#39;, &#39;\\&#34;&#39;)
self.jumphost = f&#39;-o ProxyCommand=&#34;{escaped}&#34;&#39;
else:
self.jumphost = &#34;&#34;
self.last_fallback_used = False
self.output = &#34;&#34;
self.status = 1
self.result = {}
self.cmd_byte_positions = [(0, None)]
def _collect_jumphost_hops(self, jumphost_name, config, visited=None, depth=0):
&#34;&#34;&#34;Collect structured hop metadata in SSH ProxyCommand prompt order.&#34;&#34;&#34;
if depth &gt;= 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(&#34;jumphost&#34;, &#34;&#34;) != &#34;&#34;:
hops.extend(
self._collect_jumphost_hops(
jh[&#34;jumphost&#34;],
config,
visited,
depth + 1,
)
)
jh_tags = jh.get(&#34;tags&#34;)
resolved_fqdn = &#34;&#34;
if isinstance(jh_tags, dict) and jh_tags.get(&#34;fqdn&#34;):
resolved_fqdn = str(jh_tags[&#34;fqdn&#34;])
hops.append(
{
&#34;name&#34;: jumphost_name,
&#34;host&#34;: str(jh.get(&#34;host&#34;, &#34;&#34;) or &#34;&#34;),
&#34;port&#34;: str(jh.get(&#34;port&#34;, &#34;&#34;) or &#34;&#34;),
&#34;protocol&#34;: str(jh.get(&#34;protocol&#34;, &#34;ssh&#34;) or &#34;ssh&#34;),
&#34;user&#34;: str(jh.get(&#34;user&#34;, &#34;&#34;) or &#34;&#34;),
&#34;options&#34;: str(jh.get(&#34;options&#34;, &#34;&#34;) or &#34;&#34;),
&#34;tags&#34;: deepcopy(jh_tags) if isinstance(jh_tags, dict) else jh_tags,
&#34;resolved_fqdn&#34;: resolved_fqdn,
&#34;passwords&#34;: tuple(p for p in (jh.get(&#34;password&#34;) or []) if p != &#34;&#34;),
}
)
return hops
@staticmethod
def _resolve_jumphost_data(jh_dict, config):
&#39;&#39;&#39;Resolve @profile references and normalize passwords in a jumphost dict.&#39;&#39;&#39;
profiles_map = getattr(config, &#34;profiles&#34;, {}) if config else {}
for key, jh_val in list(jh_dict.items()):
if key == &#34;password&#34;:
continue
profile = re.search(&#34;^@(.*)&#34;, str(jh_val))
if profile:
try:
jh_dict[key] = deepcopy(profiles_map[profile.group(1)][key])
except KeyError:
jh_dict[key] = &#34;&#34;
elif jh_val == &#39;&#39; and key == &#34;protocol&#34;:
try:
jh_dict[key] = profiles_map[&#34;default&#34;][key]
except KeyError:
jh_dict[key] = &#34;ssh&#34;
raw_pw = jh_dict.get(&#34;password&#34;, &#34;&#34;)
if isinstance(raw_pw, list):
resolved = []
for p in raw_pw:
if (
isinstance(p, str)
and not is_compose_expression(p)
and p.startswith(&#34;@&#34;)
and p[1:] in profiles_map
):
resolved.append(deepcopy(profiles_map[p[1:]].get(&#34;password&#34;, &#34;&#34;)))
else:
resolved.append(p)
jh_dict[&#34;password&#34;] = resolved
else:
if (
isinstance(raw_pw, str)
and not is_compose_expression(raw_pw)
and raw_pw.startswith(&#34;@&#34;)
and raw_pw[1:] in profiles_map
):
res = profiles_map[raw_pw[1:]].get(&#34;password&#34;, &#34;&#34;)
jh_dict[&#34;password&#34;] = deepcopy(res) if isinstance(res, list) else [res]
else:
jh_dict[&#34;password&#34;] = [raw_pw]
return jh_dict
def _is_unsafe_allowed(self) -&gt; bool:
if getattr(self, &#34;allow_unsafe_options&#34;, False):
return True
if hasattr(self, &#34;config&#34;) and self.config and hasattr(self.config, &#34;config&#34;) and isinstance(self.config.config, dict):
return bool(self.config.config.get(&#34;allow_unsafe_options&#34;, False))
return False
def _validate_base_fields(self, check_port=True):
&#34;&#34;&#34;Sanitize host, user, and port against argument injection and shell metacharacters.&#34;&#34;&#34;
host_s = str(self.host) if self.host is not None else &#34;&#34;
if not host_s:
raise ValueError(&#34;Host cannot be empty&#34;)
if host_s.startswith(&#34;-&#34;):
raise ValueError(f&#34;Host cannot start with &#39;-&#39;: &#39;{self.host}&#39;&#34;)
host_bare = (
host_s[1:-1]
if (host_s.startswith(&#34;[&#34;) and host_s.endswith(&#34;]&#34;))
else host_s
)
if not host_bare or host_bare.startswith(&#34;-&#34;):
raise ValueError(f&#34;Invalid characters in host: &#39;{self.host}&#39;&#34;)
if _LEGACY_SSH_UNSAFE_RE.search(host_bare):
raise ValueError(f&#34;Invalid characters in host: &#39;{self.host}&#39;&#34;)
user_s = str(self.user) if self.user is not None else &#34;&#34;
if user_s:
if user_s.startswith(&#34;-&#34;):
raise ValueError(f&#34;User cannot start with &#39;-&#39;: &#39;{self.user}&#39;&#34;)
if _LEGACY_SSH_UNSAFE_RE.search(user_s):
raise ValueError(f&#34;Invalid characters in user: &#39;{self.user}&#39;&#34;)
if check_port and self.port != &#34;&#34; and self.port is not None:
if isinstance(self.port, (bool, float)):
raise ValueError(f&#34;Invalid TCP SSH port &#39;{self.port}&#39;&#34;)
port_s = str(self.port).strip()
if port_s and (
not port_s.isascii()
or not re.fullmatch(r&#34;[0-9]+&#34;, port_s, re.ASCII)
or not (1 &lt;= int(port_s) &lt;= 65535)
):
raise ValueError(f&#34;Invalid TCP SSH port &#39;{self.port}&#39;&#34;)
def _validate_options_and_safety(self):
&#34;&#34;&#34;Validate options string for unbalanced quotes and dangerous control characters.&#34;&#34;&#34;
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 (&#34;\n&#34;, &#34;\r&#34;, &#34;\x00&#34;)):
raise ValueError(&#34;Options cannot contain newlines or null bytes&#34;)
try:
shlex.split(opts_str)
except ValueError as e:
raise ValueError(f&#34;Invalid options: unbalanced quotes ({e})&#34;) from e
def _validate_ssh_options(self):
&#34;&#34;&#34;Sanitize SSH options against local command execution directives.&#34;&#34;&#34;
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 = (&#34;ProxyCommand&#34;, &#34;LocalCommand&#34;, &#34;PermitLocalCommand&#34;, &#34;KnownHostsCommand&#34;)
pattern = r&#39;(?:&#39; + &#39;|&#39;.join(dangerous_directives) + r&#39;)&#39;
match = re.search(pattern, opts_str, re.IGNORECASE)
if match:
raise ValueError(f&#34;Disallowed SSH directive in options: &#39;{match.group(0)}&#39;&#34;)
@staticmethod
def _validate_legacy_ssh_hop_fields(host, user, port):
&#34;&#34;&#34;Minimal injection guard for legacy SSH jumphost fields (preserves DOMAIN\\user, %scope, etc.).&#34;&#34;&#34;
host_s = str(host) if host is not None else &#34;&#34;
if host_s.startswith(&#34;-&#34;):
raise ValueError(&#34;Host cannot start with &#39;-&#39;&#34;)
if not host_s or _LEGACY_SSH_UNSAFE_RE.search(host_s):
raise ValueError(f&#34;Invalid characters in host: &#39;{host}&#39;&#34;)
host_bare = (
host_s[1:-1]
if (host_s.startswith(&#34;[&#34;) and host_s.endswith(&#34;]&#34;))
else host_s
)
if not host_bare or host_bare.startswith(&#34;-&#34;):
raise ValueError(f&#34;Invalid characters in host: &#39;{host}&#39;&#34;)
user_s = str(user) if user is not None else &#34;&#34;
if user_s.startswith(&#34;-&#34;):
raise ValueError(&#34;User cannot start with &#39;-&#39;&#34;)
if user_s and _LEGACY_SSH_UNSAFE_RE.search(user_s):
raise ValueError(f&#34;Invalid characters in user: &#39;{user}&#39;&#34;)
port_out = &#34;&#34;
if port != &#34;&#34; and port is not None:
if isinstance(port, (bool, float)):
raise ValueError(f&#34;Invalid TCP SSH port &#39;{port}&#39;&#34;)
port_s = str(port).strip()
if port_s:
if (
not port_s.isascii()
or not re.fullmatch(r&#34;[0-9]+&#34;, port_s, re.ASCII)
or not (1 &lt;= int(port_s) &lt;= 65535)
):
raise ValueError(f&#34;Invalid TCP SSH port &#39;{port}&#39;&#34;)
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,
):
&#34;&#34;&#34;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 &#39;%&#39;).
Returns:
tuple[str, str, str]: (host_bare_str, validated_port_str, validated_ssh_opts_str)
&#34;&#34;&#34;
host_s = str(host) if host is not None else &#34;&#34;
if host_s.startswith(&#34;-&#34;):
raise ValueError(&#34;Host cannot start with &#39;-&#39;&#34;)
if not host_s:
raise ValueError(f&#34;Invalid characters in host: &#39;{host}&#39;&#34;)
if (host_s.startswith(&#34;[&#34;) and host_s.endswith(&#34;]&#34;)) or &#34;:&#34; in host_s:
inner = host_s[1:-1] if (host_s.startswith(&#34;[&#34;) and host_s.endswith(&#34;]&#34;)) else host_s
if &#34;%&#34; in inner or not re.fullmatch(r&#34;[0-9A-Fa-f:.]+&#34;, inner, re.ASCII):
raise ValueError(f&#34;Invalid characters in host: &#39;{host}&#39;&#34;)
try:
ipaddress.IPv6Address(inner)
except ValueError as exc:
raise ValueError(f&#34;Invalid characters in host: &#39;{host}&#39;&#34;) from exc
host_bare = inner
else:
if not re.fullmatch(r&#34;[A-Za-z0-9._-]+&#34;, host_s, re.ASCII):
raise ValueError(f&#34;Invalid characters in host: &#39;{host}&#39;&#34;)
host_bare = host_s
user_s = str(user) if user is not None else &#34;&#34;
if user_s.startswith(&#34;-&#34;):
raise ValueError(&#34;User cannot start with &#39;-&#39;&#34;)
if user_s and not re.fullmatch(
r&#34;[A-Za-z0-9._-]+(?:@[A-Za-z0-9._-]+)?&#34;, user_s, re.ASCII
):
raise ValueError(f&#34;Invalid characters in user: &#39;{user}&#39;&#34;)
port_out = &#34;&#34;
if port != &#34;&#34; and port is not None:
if isinstance(port, (bool, float)):
raise ValueError(f&#34;Invalid TCP SSH port &#39;{port}&#39;&#34;)
port_s = str(port).strip()
if port_s:
if (
not port_s.isascii()
or not re.fullmatch(r&#34;[0-9]+&#34;, port_s, re.ASCII)
or not (1 &lt;= int(port_s) &lt;= 65535)
):
raise ValueError(f&#34;Invalid TCP SSH port &#39;{port}&#39;&#34;)
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&#34;[0-9]+&#34;, r_port_s, re.ASCII)
or not (1 &lt;= int(r_port_s) &lt;= 65535)
):
raise ValueError(
f&#34;Invalid allow_reverse_tunnel_port &#39;{allow_reverse_tunnel_port}&#39;&#34;
)
allowed_r_port = r_port_s
opts_out = &#34;&#34;
raw_opts = tags.get(&#34;mosh_ssh_options&#34;, &#34;&#34;) if isinstance(tags, dict) else &#34;&#34;
if raw_opts:
ssh_opts = str(raw_opts).strip()
if &#34;\x00&#34; in ssh_opts or &#34;\n&#34; in ssh_opts or &#34;\r&#34; in ssh_opts:
raise ValueError(&#34;Disallowed control characters in mosh_ssh_options&#34;)
if ssh_opts:
try:
tokens = shlex.split(ssh_opts)
except ValueError as exc:
raise ValueError(
&#34;Invalid mosh_ssh_options: unbalanced quotes&#34;
) from exc
r_count = 0
exit_fwd_count = 0
out_tokens = []
idx = 0
# Normative branch evaluation order:
# 1. NOARG -&gt; 2. ARG separate -&gt; 3. ARG attached -&gt; 4. -R -&gt; 5. -o/-oXXX -&gt; 6. other
while idx &lt; 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 &gt;= len(tokens) or not tokens[idx + 1].strip():
raise ValueError(
f&#34;Missing argument for ssh option &#39;{tok}&#39; in mosh_ssh_options&#34;
)
arg_val = tokens[idx + 1]
val_re = _SAFE_SSH_PATH_RE if tok == &#34;-i&#34; else _SAFE_SSH_O_VALUE_RE
if arg_val.startswith(&#34;-&#34;) or not val_re.fullmatch(arg_val):
raise ValueError(
f&#34;Invalid argument for ssh option &#39;{tok}&#39; in mosh_ssh_options&#34;
)
out_tokens.extend([tok, arg_val])
idx += 2
elif tok[:2] in _ALLOWED_SSH_ARG_FLAGS and len(tok) &gt; 2:
flag_prefix = tok[:2]
arg_val = tok[2:]
val_re = _SAFE_SSH_PATH_RE if flag_prefix == &#34;-i&#34; else _SAFE_SSH_O_VALUE_RE
if (
not arg_val.strip()
or arg_val.startswith(&#34;-&#34;)
or not val_re.fullmatch(arg_val)
):
raise ValueError(
f&#34;Invalid argument for ssh option &#39;{flag_prefix}&#39; in mosh_ssh_options&#34;
)
out_tokens.append(tok)
idx += 1
elif tok == &#34;-R&#34;:
if (
allowed_r_port is None
or r_count &gt;= 1
or idx + 1 &gt;= len(tokens)
or tokens[idx + 1]
!= f&#34;{allowed_r_port}:localhost:{allowed_r_port}&#34;
):
raise ValueError(
f&#34;Disallowed ssh option in mosh_ssh_options: &#39;{tok}&#39;&#34;
)
r_count += 1
out_tokens.extend([tok, tokens[idx + 1]])
idx += 2
elif tok == &#34;-o&#34; or tok.startswith(&#34;-o&#34;):
if tok == &#34;-o&#34;:
if idx + 1 &gt;= len(tokens) or not tokens[idx + 1].strip():
raise ValueError(
&#34;Missing argument for ssh option &#39;-o&#39; in mosh_ssh_options&#34;
)
opt_spec = tokens[idx + 1]
step = 2
else:
opt_spec = tok[2:]
step = 1
if re.search(r&#34;(?:localcommand|proxycommand)&#34;, opt_spec, re.IGNORECASE):
raise ValueError(
&#34;mosh_ssh_options cannot contain LocalCommand or ProxyCommand&#34;
)
m = re.fullmatch(r&#34;([A-Za-z0-9]+)=(.+)&#34;, 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&#34;Disallowed -o directive in mosh_ssh_options: &#39;{opt_spec}&#39;&#34;
)
key_raw = m.group(1)
key_lower = key_raw.lower()
val_str = m.group(2).strip()
if key_lower == &#34;exitonforwardfailure&#34;:
if (
allowed_r_port is None
or exit_fwd_count &gt;= 1
or val_str.lower() != &#34;yes&#34;
):
raise ValueError(
f&#34;Disallowed -o directive in mosh_ssh_options: &#39;{opt_spec}&#39;&#34;
)
exit_fwd_count += 1
elif key_lower not in _ALLOWED_SSH_O_KEYS:
raise ValueError(
f&#34;Disallowed -o directive in mosh_ssh_options: &#39;{opt_spec}&#39;&#34;
)
if not (strip_non_tunnel_flags and key_lower == &#34;forwardagent&#34;):
if tok == &#34;-o&#34;:
out_tokens.extend([&#34;-o&#34;, f&#34;{key_raw}={val_str}&#34;])
else:
out_tokens.append(f&#34;-o{key_raw}={val_str}&#34;)
idx += step
else:
if re.search(r&#34;(?:localcommand|proxycommand)&#34;, tok, re.IGNORECASE):
raise ValueError(
&#34;mosh_ssh_options cannot contain LocalCommand or ProxyCommand&#34;
)
raise ValueError(
f&#34;Disallowed ssh option in mosh_ssh_options: &#39;{tok}&#39;&#34;
)
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 = &#34;options&#34;,
strip_non_tunnel_flags: bool = False,
allow_unsafe: bool = False,
connect_timeout: int | None = None,
) -&gt; str:
&#34;&#34;&#34;Validate SSH options against _ALLOWED_SSH_O_KEYS and optionally inject ConnectTimeout/ServerAliveInterval.&#34;&#34;&#34;
out_tokens: list[str] = []
if raw_opts:
ssh_opts = str(raw_opts).strip()
if _CONTROL_CHAR_RE.search(ssh_opts):
raise ValueError(f&#34;Disallowed control characters in {field_name}&#34;)
if ssh_opts:
try:
tokens = shlex.split(ssh_opts)
except ValueError as exc:
raise ValueError(f&#34;Invalid {field_name}: unbalanced quotes&#34;) from exc
if allow_unsafe:
out_tokens = list(tokens)
else:
idx = 0
while idx &lt; 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 &gt;= len(tokens) or not tokens[idx + 1].strip():
raise ValueError(
f&#34;Missing argument for ssh option &#39;{tok}&#39; in {field_name}&#34;
)
arg_val = tokens[idx + 1]
val_re = _SAFE_SSH_PATH_RE if tok == &#34;-i&#34; else _SAFE_SSH_O_VALUE_RE
if arg_val.startswith(&#34;-&#34;) or not val_re.fullmatch(arg_val):
raise ValueError(
f&#34;Invalid argument for ssh option &#39;{tok}&#39; in {field_name}&#34;
)
out_tokens.extend([tok, arg_val])
idx += 2
elif tok[:2] in _ALLOWED_SSH_ARG_FLAGS and len(tok) &gt; 2:
flag_prefix = tok[:2]
arg_val = tok[2:]
val_re = _SAFE_SSH_PATH_RE if flag_prefix == &#34;-i&#34; else _SAFE_SSH_O_VALUE_RE
if (
not arg_val.strip()
or arg_val.startswith(&#34;-&#34;)
or not val_re.fullmatch(arg_val)
):
raise ValueError(
f&#34;Invalid argument for ssh option &#39;{flag_prefix}&#39; in {field_name}&#34;
)
out_tokens.append(tok)
idx += 1
elif tok == &#34;-o&#34; or tok.startswith(&#34;-o&#34;):
if tok == &#34;-o&#34;:
if idx + 1 &gt;= len(tokens) or not tokens[idx + 1].strip():
raise ValueError(
f&#34;Missing argument for ssh option &#39;-o&#39; in {field_name}&#34;
)
opt_spec = tokens[idx + 1]
step = 2
else:
opt_spec = tok[2:]
step = 1
if re.search(
r&#34;(?:localcommand|proxycommand|permitlocalcommand|knownhostscommand)&#34;,
opt_spec,
re.IGNORECASE,
):
raise ValueError(
f&#34;{field_name} cannot contain LocalCommand or ProxyCommand&#34;
)
m = re.fullmatch(r&#34;([A-Za-z0-9]+)=(.+)&#34;, 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&#34;Disallowed -o directive in {field_name}: &#39;{opt_spec}&#39;&#34;
)
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&#34;Disallowed -o directive in {field_name}: &#39;{opt_spec}&#39;&#34;
)
if not (strip_non_tunnel_flags and key_lower == &#34;forwardagent&#34;):
if tok == &#34;-o&#34;:
out_tokens.extend([&#34;-o&#34;, f&#34;{key_raw}={val_str}&#34;])
else:
out_tokens.append(f&#34;-o{key_raw}={val_str}&#34;)
idx += step
else:
if re.search(
r&#34;(?:localcommand|proxycommand|permitlocalcommand|knownhostscommand)&#34;,
tok,
re.IGNORECASE,
):
raise ValueError(
f&#34;{field_name} cannot contain LocalCommand or ProxyCommand&#34;
)
raise ValueError(
f&#34;Disallowed ssh option in {field_name}: &#39;{tok}&#39;&#34;
)
if connect_timeout is not None:
ct_val = validate_strict_timeout_int(connect_timeout, &#34;connect_timeout&#34;)
existing_keys = _extract_ssh_o_keys(out_tokens)
if &#34;connecttimeout&#34; not in existing_keys and &#34;connecttimeout&#34; in _ALLOWED_SSH_O_KEYS:
out_tokens.extend([&#34;-o&#34;, f&#34;ConnectTimeout={ct_val}&#34;])
if (
&#34;serveraliveinterval&#34; not in existing_keys
and &#34;serveraliveinterval&#34; in _ALLOWED_SSH_O_KEYS
):
out_tokens.extend([&#34;-o&#34;, &#34;ServerAliveInterval=15&#34;])
return shlex.join(out_tokens) if out_tokens else &#34;&#34;
def _build_jumphost_chain(
self,
jumphost_name,
config,
visited=None,
depth=0,
target_host=&#34;%h&#34;,
target_port=&#34;%p&#34;,
*,
include_meta=False,
connect_timeout=None,
):
&#34;&#34;&#34;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).
&#34;&#34;&#34;
if depth &gt;= 5:
raise ValueError(&#34;Jumphost chain exceeds maximum depth of 5 hops&#34;)
if visited is None:
visited = []
if jumphost_name in visited:
cycle = &#34; -&gt; &#34;.join(visited + [jumphost_name])
raise ValueError(f&#34;Circular jumphost reference detected: {cycle}&#34;)
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 (&#34;host&#34;, &#34;user&#34;, &#34;port&#34;):
fld_val = jh.get(fld_name)
if fld_val not in (None, &#34;&#34;) and _CONTROL_CHAR_RE.search(str(fld_val)):
raise ValueError(f&#34;Control characters disallowed in jumphost {fld_name}&#34;)
jh_tags = jh.get(&#34;tags&#34;)
if isinstance(jh_tags, dict):
for tag_fld in (&#34;profile&#34;, &#34;region&#34;):
tag_val = jh_tags.get(tag_fld)
if tag_val not in (None, &#34;&#34;) and _CONTROL_CHAR_RE.search(str(tag_val)):
raise ValueError(f&#34;Control characters disallowed in jumphost {tag_fld}&#34;)
if connect_timeout is not None:
connect_timeout = validate_strict_timeout_int(connect_timeout, &#34;connect_timeout&#34;)
jh_proto = jh.get(&#34;protocol&#34;, &#34;ssh&#34;)
if jh_proto == &#34;mosh&#34;:
jh_host, jh_port, jh_opts = self._validate_mosh_ssh_fields(
jh.get(&#34;host&#34;, &#34;&#34;),
jh.get(&#34;user&#34;, &#34;&#34;),
jh.get(&#34;port&#34;, &#34;&#34;),
jh.get(&#34;tags&#34;, &#34;&#34;),
strip_non_tunnel_flags=True,
)
if connect_timeout is not None:
jh_opts = self._validate_and_prepare_ssh_options(
jh_opts,
field_name=&#34;mosh_ssh_options&#34;,
strip_non_tunnel_flags=True,
connect_timeout=connect_timeout,
)
elif jh_proto == &#34;ssh&#34;:
jh_host, jh_port = self._validate_legacy_ssh_hop_fields(
jh.get(&#34;host&#34;, &#34;&#34;),
jh.get(&#34;user&#34;, &#34;&#34;),
jh.get(&#34;port&#34;, &#34;&#34;),
)
jh_opts = self._validate_and_prepare_ssh_options(
jh.get(&#34;options&#34;, &#34;&#34;),
field_name=&#34;jumphost options&#34;,
allow_unsafe=self._is_unsafe_allowed(),
connect_timeout=connect_timeout,
)
else:
jh_host = str(jh.get(&#34;host&#34;, &#34;&#34;) or &#34;&#34;)
jh_port = str(jh[&#34;port&#34;]).strip() if jh.get(&#34;port&#34;) not in (&#34;&#34;, None) else &#34;&#34;
jh_opts = jh.get(&#34;options&#34;, &#34;&#34;)
passwords = []
inner_proxy_opt = &#34;&#34;
inner_meta: list[dict[str, str]] = []
# Recursively resolve inner jumphost
if jh.get(&#34;jumphost&#34;, &#34;&#34;) != &#34;&#34;:
if jh_proto not in [&#34;ssh&#34;, &#34;mosh&#34;]:
raise ValueError(
f&#34;Jumphost &#39;{jumphost_name}&#39; uses protocol &#39;{jh_proto}&#39; &#34;
&#34;which does not support chained jumphosts. &#34;
&#34;Only SSH or Mosh jumphosts can have their own jumphosts.&#34;
)
parent_port = jh_port if jh_port != &#34;&#34; else &#34;22&#34;
inner_res = self._build_jumphost_chain(
jh[&#34;jumphost&#34;],
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(&#34;\\&#34;, &#34;\\\\&#34;).replace(&#39;&#34;&#39;, &#39;\\&#34;&#39;)
inner_proxy_opt = f&#39;-o ProxyCommand=&#34;{escaped}&#34;&#39;
# Collect this hop&#39;s passwords
if jh[&#34;password&#34;] != [&#34;&#34;]:
passwords = passwords + jh[&#34;password&#34;]
hop_meta = [*inner_meta, {&#34;name&#34;: jumphost_name, &#34;protocol&#34;: jh_proto}]
t_port = target_port if target_port != &#34;&#34; else &#34;22&#34;
if jh_proto in [&#34;ssh&#34;, &#34;mosh&#34;, &#34;ssm&#34;]:
if target_host == &#34;%h&#34; and t_port == &#34;%p&#34;:
w_target = &#34;%h&#34;
w_port = &#34;%p&#34;
else:
t_host_bare, t_port_norm = self._validate_legacy_ssh_hop_fields(
target_host, &#34;&#34;, t_port
)
w_target = f&#34;[{t_host_bare}]&#34; if &#34;:&#34; in t_host_bare else t_host_bare
w_port = t_port_norm if t_port_norm != &#34;&#34; else &#34;22&#34;
else:
w_target = target_host
w_port = t_port
# Build raw command based on protocol
if jh_proto in [&#34;ssh&#34;, &#34;mosh&#34;]:
cmd = f&#34;ssh -W {w_target}:{w_port}&#34;
if inner_proxy_opt:
cmd += f&#34; {inner_proxy_opt}&#34;
if jh_port != &#34;&#34;:
cmd += f&#34; -p {jh_port}&#34;
if jh_opts != &#34;&#34;:
cmd += f&#34; {jh_opts}&#34;
jh_user = str(jh.get(&#34;user&#34;, &#34;&#34;) or &#34;&#34;)
user_host = f&#34;{jh_user}@{jh_host}&#34; if jh_user else jh_host
cmd += f&#34; {user_host}&#34;
elif jh_proto == &#34;ssm&#34;:
ssm_target = str(jh.get(&#34;host&#34;, &#34;&#34;) or &#34;&#34;)
if (
&#34;..&#34; in ssm_target
or ssm_target.startswith(&#34;-&#34;)
or not _SSM_TARGET_RE.fullmatch(ssm_target)
):
raise ValueError(f&#34;Invalid SSM jumphost target: &#39;{ssm_target}&#39;&#34;)
ssm_user = str(jh.get(&#34;user&#34;, &#34;&#34;) or &#34;&#34;)
if ssm_user and (ssm_user.startswith(&#34;-&#34;) or _LEGACY_SSH_UNSAFE_RE.search(ssm_user)):
raise ValueError(f&#34;Invalid characters in SSM jumphost user: &#39;{ssm_user}&#39;&#34;)
ssm_parts = [
&#34;aws&#34;,
&#34;ssm&#34;,
&#34;start-session&#34;,
&#34;--target&#34;,
ssm_target,
&#34;--document-name&#34;,
&#34;AWS-StartSSHSession&#34;,
&#34;--parameters&#34;,
&#34;portNumber=22&#34;,
]
if isinstance(jh_tags, dict):
for tag_key in (&#34;profile&#34;, &#34;region&#34;):
raw_val = jh_tags.get(tag_key)
if raw_val not in (None, &#34;&#34;):
tag_str = str(raw_val)
if (
&#34;..&#34; in tag_str
or tag_str.startswith(&#34;-&#34;)
or not _SSM_TAG_RE.fullmatch(tag_str)
):
raise ValueError(f&#34;Invalid SSM jumphost {tag_key}: &#39;{tag_str}&#39;&#34;)
ssm_parts.extend([f&#34;--{tag_key}&#34;, tag_str])
ssm_opts_raw = str(jh.get(&#34;options&#34;, &#34;&#34;) or &#34;&#34;).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(&#34;Invalid characters in SSM jumphost options&#34;)
try:
ssm_opt_tokens = shlex.split(ssm_opts_raw)
except ValueError as exc:
raise ValueError(&#34;Invalid SSM jumphost options: unbalanced quotes&#34;) from exc
ssm_parts.extend(ssm_opt_tokens)
ssm_cmd = shlex.join(ssm_parts)
raw_ssh_opts = jh_tags.get(&#34;ssh_options&#34;, &#34;&#34;) if isinstance(jh_tags, dict) else &#34;&#34;
ssh_opts = self._validate_and_prepare_ssh_options(
raw_ssh_opts,
field_name=&#34;ssm ssh_options&#34;,
strip_non_tunnel_flags=True,
allow_unsafe=self._is_unsafe_allowed(),
connect_timeout=connect_timeout,
)
bastion_user_part = f&#34;{ssm_user}@{ssm_target}&#34; if ssm_user else ssm_target
outer_parts = [&#34;ssh&#34;]
if ssh_opts:
outer_parts.extend(shlex.split(ssh_opts))
outer_parts.extend(
[&#34;-o&#34;, f&#34;ProxyCommand={ssm_cmd}&#34;, &#34;-W&#34;, f&#34;{w_target}:{w_port}&#34;, bastion_user_part]
)
cmd = shlex.join(outer_parts)
elif jh_proto in [&#34;kubectl&#34;, &#34;docker&#34;]:
if not jh_host or jh_host.startswith(&#34;-&#34;) or _LEGACY_SSH_UNSAFE_RE.search(jh_host):
raise ValueError(f&#34;Invalid characters in {jh_proto} jumphost host: &#39;{jh_host}&#39;&#34;)
nc_cmd = &#34;nc&#34;
if isinstance(jh_tags, dict) and &#34;nc_command&#34; in jh_tags:
nc_cmd = str(jh_tags[&#34;nc_command&#34;])
if _CONTROL_CHAR_RE.search(nc_cmd) or (
not self._is_unsafe_allowed() and _SSM_UNSAFE_OPTIONS_RE.search(nc_cmd)
):
raise ValueError(f&#34;Invalid nc_command in {jh_proto} jumphost&#34;)
jh_opt_joined = &#34;&#34;
jh_opt_str = str(jh.get(&#34;options&#34;, &#34;&#34;) or &#34;&#34;).strip()
if jh_opt_str:
if _CONTROL_CHAR_RE.search(jh_opt_str):
raise ValueError(f&#34;Control characters disallowed in {jh_proto} options&#34;)
if not self._is_unsafe_allowed() and _SSM_UNSAFE_OPTIONS_RE.search(jh_opt_str):
raise ValueError(f&#34;Invalid characters in {jh_proto} options&#34;)
try:
jh_opt_tokens = shlex.split(jh_opt_str)
except ValueError as exc:
raise ValueError(f&#34;Invalid {jh_proto} options: unbalanced quotes&#34;) from exc
jh_opt_joined = shlex.join(jh_opt_tokens)
if jh_proto == &#34;kubectl&#34;:
cmd = &#34;kubectl exec &#34;
if jh_opt_joined:
cmd += f&#34;{jh_opt_joined} &#34;
cmd += f&#34;{jh_host} -i -- {nc_cmd} {w_target} {w_port}&#34;
else:
cmd = &#34;docker &#34;
if jh_opt_joined:
cmd += f&#34;{jh_opt_joined} &#34;
cmd += f&#34;exec -i {jh_host} {nc_cmd} {w_target} {w_port}&#34;
else:
if include_meta:
return &#34;&#34;, passwords, inner_meta
return &#34;&#34;, 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(&#39;^b[\&#34;\&#39;].+[\&#34;\&#39;]$&#39;, passwd):
dpass.append(passwd)
else:
try:
decrypted = decryptor.decrypt(ast.literal_eval(passwd)).decode(&#34;utf-8&#34;)
dpass.append(decrypted)
except Exception: # noqa: BLE001
printer.error(&#34;Decryption failed: Missing or corrupted key.&#34;)
printer.info(&#34;Verify your RSA key and configuration settings.&#34;)
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(&#34;${unique}&#34;, self.unique)
logfile = logfile.replace(&#34;${host}&#34;, self.host)
logfile = logfile.replace(&#34;${port}&#34;, self.port)
logfile = logfile.replace(&#34;${user}&#34;, self.user)
logfile = logfile.replace(&#34;${protocol}&#34;, self.protocol)
now = datetime.datetime.now()
dateconf = re.search(r&#39;\$\{date \&#39;(.*)\&#39;}&#39;, logfile)
if dateconf:
logfile = re.sub(r&#39;\$\{date (.*)}&#39;,now.strftime(dateconf.group(1)), logfile)
return logfile
@MethodHook
def _logclean(self, logfile, var = False):
&#34;&#34;&#34;Remove special ascii characters and process terminal cursor movements to clean logs.&#34;&#34;&#34;
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, &#34;w&#34;) as f:
f.write(result)
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Failed writing cleaned log %s: %s&#34;, logfile, exc)
return
else:
return result
@MethodHook
def _savelog(self):
&#39;&#39;&#39;Save the log buffer to the file at regular intervals if there are changes.&#39;&#39;&#39;
t = threading.current_thread()
prev_size = 0 # Store the previous size of the buffer
while getattr(t, &#34;do_run&#34;, 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, &#34;w&#34;) as f: # Use &#34;w&#34; 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 &gt;= self.idletime:
self.child.sendcontrol(&#34;e&#34;)
self.lastinput = time()
sleep(1)
def _setup_interact_environment(self, debug=False, logger=None, async_mode=False):
try:
size = re.search(&#39;columns=([0-9]+).*lines=([0-9]+)&#39;,str(os.get_terminal_size()))
self.child.setwinsize(int(size.group(2)),int(size.group(1)))
except OSError:
pass
if logger and self.protocol != &#34;local&#34;:
port_str = f&#34;:{self.port}&#34; if self.port and self.protocol not in [&#34;ssm&#34;, &#34;kubectl&#34;, &#34;docker&#34;] else &#34;&#34;
logger(&#34;success&#34;, f&#34;Connected to {self.unique} at {self.host}{port_str} via: {self.protocol}&#34;)
# Always initialize self.mylog to capture terminal context for the AI Copilot
if not hasattr(self, &#39;mylog&#39;):
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, &#34;logfile&#34;) 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, &#34;missingtext&#34;, False) and not async_mode:
print(self.child.after.decode(), end=&#34;&#34;)
if self.idletime &gt; 0 and not async_mode:
x = threading.Thread(target=self._keepalive)
x.daemon = True
x.start()
if debug and hasattr(self, &#34;mylog&#34;) and not async_mode:
print(self.mylog.getvalue().decode())
def _teardown_interact_environment(self):
if &#39;logfile&#39; in dir(self) and hasattr(self, &#39;mylog&#39;):
with open(self.logfile, &#34;w&#34;) as f:
f.write(self._logclean(self.mylog.getvalue().decode(), True))
def _write_clean_logfile(self, raw_log: str) -&gt; None:
&#34;&#34;&#34;Clean and synchronously write raw log output to self.logfile.&#34;&#34;&#34;
cleaned_log = self._logclean(raw_log, True)
with open(self.logfile, &#34;w&#34;) as f:
f.write(cleaned_log)
def _is_child_connpy_active(self, child_fd: int) -&gt; bool:
if self.protocol != &#34;local&#34;:
return False
try:
fg_pgid = os.tcgetpgrp(child_fd)
if fg_pgid &lt;= 0:
return False
cmdline_path = f&#34;/proc/{fg_pgid}/cmdline&#34;
if os.path.exists(cmdline_path):
with open(cmdline_path, &#34;rb&#34;) as f:
raw_args = f.read().split(b&#34;\x00&#34;)
is_active = False
for raw_arg in raw_args:
arg_str = raw_arg.decode(errors=&#34;ignore&#34;)
if not arg_str:
continue
base_name = os.path.basename(arg_str)
if base_name in [&#34;conn&#34;, &#34;connpy&#34;, &#34;connapp&#34;] or &#34;connpy&#34; in arg_str or &#34;connapp&#34; in arg_str:
is_active = True
break
return is_active
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Failed checking active connpy process: %s&#34;, 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&#39;&#39;
if getattr(self, &#39;missingtext&#39;, False):
# If we are missing the password, we MUST show the password prompt
ghost_buffer = (self.child.after or b&#39;&#39;) + (self.child.buffer or b&#39;&#39;)
else:
# We auto-logged in. Hide the messy password negotiation and just keep any pending live stream.
ghost_buffer = self.child.buffer or b&#39;&#39;
# Fix user&#39;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, &#39;missingtext&#39;, False):
ghost_buffer = ghost_buffer.lstrip(b&#39;\r\n &#39;)
if ghost_buffer:
# Add a single clean newline so it doesn&#39;t merge with the Connected message
await local_stream.write(b&#39;\r\n&#39; + ghost_buffer)
if hasattr(self, &#39;mylog&#39;):
self.mylog.write(b&#39;\n&#39; + ghost_buffer)
self.child.buffer = b&#39;&#39;
self.child.before = b&#39;&#39;
# 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, &#39;mylog&#39;) 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&#39;&#39;)
except BlockingIOError:
pass
except OSError:
child_reader_queue.put_nowait(b&#39;&#39;)
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&#39;\x00&#39; 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=&#39;replace&#39;)
return str(val) if val is not None else &#34;unknown&#34;
node_info = {
&#34;name&#34;: to_str(getattr(self, &#39;unique&#39;, &#39;unknown&#39;)),
&#34;host&#34;: to_str(getattr(self, &#39;host&#39;, &#39;unknown&#39;))
}
if isinstance(getattr(self, &#39;tags&#39;, None), dict):
node_info[&#34;os&#34;] = to_str(self.tags.get(&#34;os&#34;, &#34;unknown&#34;))
node_info[&#34;prompt&#34;] = to_str(self.tags.get(&#34;prompt&#34;, r&#39;&gt;$|#$|\$$|&gt;.$|#.$|\$.$&#39;))
# 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&#39;\x00&#39;, b&#39;&#39;)
if clean_data:
# Track command boundaries when user hits Enter or presses Ctrl+C
if hasattr(self, &#39;mylog&#39;) and (b&#39;\r&#39; in clean_data or b&#39;\n&#39; in clean_data or b&#39;\x03&#39; in clean_data):
pos = self.mylog.tell()
marker_cmd = &#34;CANCELLED&#34; if b&#39;\x03&#39; in clean_data else None
self.cmd_byte_positions.append((pos, marker_cmd))
if hasattr(self, &#39;current_local_stream&#39;) and self.current_local_stream is not None:
try:
await self.current_local_stream.write(f&#39;\x1b]133;B;{pos}\x07&#39;.encode())
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Failed writing OSC 133 marker: %s&#34;, 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, &#39;missingtext&#39;, 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&#39;&#39;) # Re-put EOF later or handle it
break
chunks.append(extra)
except asyncio.QueueEmpty:
break
has_eof = chunks[-1] == b&#39;&#39;
if has_eof:
chunks.pop()
if chunks:
combined_data = b&#39;&#39;.join(chunks)
if skip_newlines:
stripped = combined_data.lstrip(b&#39;\r\n&#39;)
if stripped:
skip_newlines = False
combined_data = stripped
else:
if has_eof:
break
continue
await local_stream.write(combined_data)
if hasattr(self, &#39;mylog&#39;):
self.mylog.write(combined_data)
if has_eof:
break
async def keepalive_task():
while True:
await asyncio.sleep(1)
if time() - self.lastinput &gt;= self.idletime:
try:
self.child.sendcontrol(&#34;e&#34;)
self.lastinput = time()
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Keepalive sendcontrol failed: %s&#34;, 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 &amp; file I/O to a thread to avoid freezing the interaction loop
raw_log = self.mylog.getvalue().decode(errors=&#39;replace&#39;)
await asyncio.to_thread(self._write_clean_logfile, raw_log)
prev_size = current_size
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Periodic savelog sync failed: %s&#34;, 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, &#39;pid&#39;, None)
if child_pid:
new_cwd = os.readlink(f&#34;/proc/{child_pid}/cwd&#34;)
if new_cwd != last_cwd:
last_cwd = new_cwd
try:
os.chdir(new_cwd)
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Failed syncing cwd: %s&#34;, exc)
try:
await local_stream.write(f&#34;\033]7;file://{hostname}{new_cwd}\007&#34;.encode())
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Failed writing OSC 7 update: %s&#34;, exc)
if isinstance(self.tags, dict):
self.tags[&#34;cwd&#34;] = new_cwd
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;pwd_tracker_task iteration failed: %s&#34;, 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 == &#34;local&#34;:
tasks.append(asyncio.create_task(pwd_tracker_task()))
if self.idletime &gt; 0:
tasks.append(asyncio.create_task(keepalive_task()))
if hasattr(self, &#39;logfile&#39;) and hasattr(self, &#39;mylog&#39;):
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, &#39;logfile&#39;) and hasattr(self, &#39;mylog&#39;):
try:
raw_log = self.mylog.getvalue().decode(errors=&#39;replace&#39;)
await asyncio.to_thread(self._write_clean_logfile, raw_log)
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Final savelog sync failed: %s&#34;, exc)
finally:
loop.remove_reader(child_fd)
try:
flags = fcntl.fcntl(child_fd, fcntl.F_GETFL)
fcntl.fcntl(child_fd, fcntl.F_SETFL, flags &amp; ~os.O_NONBLOCK)
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Failed restoring blocking mode on child_fd: %s&#34;, exc)
finally:
self.current_local_stream = None
local_stream.teardown()
@MethodHook
async def inject_commands(self, commands, child_fd, on_inject=None):
&#34;&#34;&#34;
Inject a list of commands into the node&#39;s PTY.
Handles screen_length_command, history tracking and delays.
&#34;&#34;&#34;
if not commands:
return
# 0. Clear line
os.write(child_fd, b&#39;\x15&#39;)
await asyncio.sleep(0.1)
# 1. Prepare list (prepend screen_length if exists)
slc = self.tags.get(&#34;screen_length_command&#34;) if hasattr(self, &#39;tags&#39;) 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&#39;s official history (SKIP if it&#39;s the administrative screen length command)
if cmd != slc and hasattr(self, &#39;cmd_byte_positions&#39;) and self.cmd_byte_positions is not None:
log_pos = self.mylog.tell() if hasattr(self, &#39;mylog&#39;) else 0
self.cmd_byte_positions.append((log_pos, cmd))
if hasattr(self, &#39;current_local_stream&#39;) and self.current_local_stream is not None:
try:
await self.current_local_stream.write(f&#39;\x1b]133;B;{log_pos}\x07&#39;.encode())
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Failed writing command boundary marker: %s&#34;, exc)
# Write physically to PTY
os.write(child_fd, (cmd + &#34;\n&#34;).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):
&#39;&#39;&#39;
Asynchronous interactive session using Smart Tunnel architecture.
Allows multiplexing I/O and handling SIGWINCH events locally without blocking.
&#39;&#39;&#39;
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(&#34;Failed resizing child window: %s&#34;, 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(&#34;error&#34;, str(connect))
else:
printer.error(f&#34;Connection failed: {connect!s}&#34;)
sys.exit(1)
def _build_local_copilot_handler(self):
&#34;&#34;&#34;Build copilot handler for local CLI sessions using rich for rendering.&#34;&#34;&#34;
config = getattr(self, &#39;config&#39;, None) if hasattr(self, &#39;config&#39;) else None
return self._copilot_handler(config)
def _copilot_handler(self, config):
&#34;&#34;&#34;Unified copilot handler for local session.&#34;&#34;&#34;
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, &#39;copilot_history&#39;, None),
session_state=getattr(stream, &#39;copilot_state&#39;, 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[&#39;banner_shown&#39;] = 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, &#39;stop_reading&#39;):
stream.stop_reading()
elif hasattr(stream, &#39;_loop&#39;) and hasattr(stream, &#39;stdin_fd&#39;):
# 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 (&#34;send_all&#34;, &#34;custom&#34;):
cmds_to_send = commands if action == &#34;send_all&#34; else custom_cmd
await self.inject_commands(cmds_to_send, child_fd)
# Dynamic Wait for Device Prompt Settle
prompt_pattern = node_info.get(&#34;prompt&#34;, r&#39;&gt;$|#$|\$$|&gt;.$|#.$|\$.$&#39;)
start_t = time()
last_len = 0
quiet_count = 0
while time() - start_t &lt; 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=&#39;replace&#39;), True).strip()
lines = [line.strip() for line in clean_txt.split(&#39;\n&#39;) if line.strip()]
last_line = lines[-1] if lines else &#34;&#34;
if quiet_count &gt;= 2 and re.search(prompt_pattern, last_line):
break
raw_bytes = self.mylog.getvalue()
continue
if action == &#34;continue&#34;:
continue
break
finally:
print(&#34;\033[2m Returning to session...\033[0m&#34;, flush=True)
# Restart terminal reading to return to interactive SSH/Telnet mode
if hasattr(stream, &#39;start_reading&#39;):
stream.start_reading()
elif hasattr(stream, &#39;_loop&#39;) and hasattr(stream, &#39;stdin_fd&#39;):
stream._loop.add_reader(stream.stdin_fd, stream._read_ready)
os.write(child_fd, b&#39;\x15\r&#39;)
except Exception as e: # noqa: BLE001
import traceback
print(f&#34;\n[ERROR in Copilot Handler] {e}&#34;, flush=True)
traceback.print_exc()
os.write(child_fd, b&#39;\x15\r&#39;)
return handler
@MethodHook
def run(
self,
commands,
vars=None,
*,
folder=&#39;&#39;,
prompt=r&#39;&gt;$|#$|\$$|&gt;.$|#.$|\$.$&#39;,
stdout=False,
timeout=None,
logger=None,
connect_timeout=None,
auth_timeout=None,
_default_cmd_timeout=10,
unattended=True,
attempt_tracker=None,
):
&#39;&#39;&#39;
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 &#34;&gt;&#34; or EOF while
routers use &#34;&gt;&#34; or &#34;#&#34;. 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.
&#39;&#39;&#39;
force_ssh = self.protocol == &#34;mosh&#34;
effective_protocol = &#34;ssh&#34; if force_ssh else self.protocol
try:
_, _, eff_cmd, _, _ = resolve_timeouts(
effective_protocol,
self.tags,
getattr(self, &#34;_hop_chain_meta&#34;, None) or [],
timeout=timeout,
connect_timeout=connect_timeout,
auth_timeout=auth_timeout,
_default_cmd_timeout=_default_cmd_timeout,
)
except ValueError as e:
err = f&#34;Connection failed code: 12\nInvalid timeout configuration: {e}&#34;
self.output = err
self.status = 1
if logger:
logger(&#34;error&#34;, f&#34;Connection failed: {err}&#34;)
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(&#39;%Y-%m-%d_%H%M%S&#39;)
if connect is True:
if logger:
port_str = f&#34;:{self.port}&#34; if self.port and effective_protocol not in [&#34;ssm&#34;, &#34;kubectl&#34;, &#34;docker&#34;] else &#34;&#34;
logger(&#34;success&#34;, f&#34;Connected to {self.unique} at {self.host}{port_str} via: {effective_protocol}&#34;)
if isinstance(self.tags, dict) and &#34;prompt&#34; in self.tags:
prompt = self.tags[&#34;prompt&#34;]
prompt_pat = re.compile(prompt.encode(&#34;utf-8&#34;), re.DOTALL)
expects = [prompt_pat, pexpect.EOF, pexpect.TIMEOUT]
output = &#39;&#39;
result = 0
if not isinstance(commands, list):
commands = [commands]
if isinstance(self.tags, dict) and &#34;screen_length_command&#34; in self.tags:
commands.insert(0, self.tags[&#34;screen_length_command&#34;])
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&#34;Error: Variable {e} not defined in task or inventory&#34;
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 &#34;screen_length_command&#34; 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(&#34;Fallback setwinsize failed in run: %s&#34;, 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(&#34;utf-8&#34;, errors=&#34;replace&#34;), True)
if logger:
logger(&#34;output&#34;, output)
if folder != &#39;&#39;:
with open(folder + &#34;/&#34; + self.unique + &#34;_&#34; + now + &#34;.txt&#34;, &#34;w&#34;) 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(&#34;error&#34;, f&#34;Connection failed: {connect}&#34;)
if folder != &#39;&#39;:
with open(folder + &#34;/&#34; + self.unique + &#34;_&#34; + now + &#34;.txt&#34;, &#34;w&#34;) as f:
f.write(connect)
return connect
@MethodHook
def test(
self,
commands,
expected,
vars=None,
*,
folder=&#39;&#39;,
prompt=r&#39;&gt;$|#$|\$$|&gt;.$|#.$|\$.$&#39;,
timeout=None,
logger=None,
connect_timeout=None,
auth_timeout=None,
_default_cmd_timeout=10,
unattended=True,
attempt_tracker=None,
):
&#39;&#39;&#39;
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 &#34;&gt;&#34; or EOF while
routers use &#34;&gt;&#34; or &#34;#&#34;. 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.
&#39;&#39;&#39;
now = datetime.datetime.now().strftime(&#34;%Y-%m-%d_%H-%M-%S&#34;)
force_ssh = self.protocol == &#34;mosh&#34;
effective_protocol = &#34;ssh&#34; if force_ssh else self.protocol
try:
_, _, eff_cmd, _, _ = resolve_timeouts(
effective_protocol,
self.tags,
getattr(self, &#34;_hop_chain_meta&#34;, None) or [],
timeout=timeout,
connect_timeout=connect_timeout,
auth_timeout=auth_timeout,
_default_cmd_timeout=_default_cmd_timeout,
)
except ValueError as e:
err = f&#34;Connection failed code: 12\nInvalid timeout configuration: {e}&#34;
self.result = None
self.output = err
self.status = 1
if logger:
logger(&#34;error&#34;, f&#34;Connection failed: {err}&#34;)
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&#34;:{self.port}&#34; if self.port and effective_protocol not in [&#34;ssm&#34;, &#34;kubectl&#34;, &#34;docker&#34;] else &#34;&#34;
logger(&#34;success&#34;, f&#34;Connected to {self.unique} at {self.host}{port_str} via: {effective_protocol}&#34;)
if isinstance(self.tags, dict) and &#34;prompt&#34; in self.tags:
prompt = self.tags[&#34;prompt&#34;]
prompt_pat = re.compile(prompt.encode(&#34;utf-8&#34;), re.DOTALL)
expects = [prompt_pat, pexpect.EOF, pexpect.TIMEOUT]
output = &#39;&#39;
result = 0
if not isinstance(commands, list):
commands = [commands]
if not isinstance(expected, list):
expected = [expected]
if isinstance(self.tags, dict) and &#34;screen_length_command&#34; in self.tags:
commands.insert(0, self.tags[&#34;screen_length_command&#34;])
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&#34;Error: Variable {e} not defined in task or inventory&#34;
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 &#34;screen_length_command&#34; 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(&#34;Fallback setwinsize failed in test: %s&#34;, 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(&#34;utf-8&#34;, errors=&#34;replace&#34;), True)
if logger:
logger(&#34;output&#34;, output)
if folder != &#39;&#39;:
with open(folder + &#34;/&#34; + self.unique + &#34;_&#34; + now + &#34;.txt&#34;, &#34;w&#34;) 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&#39;(?&lt;!\\)\$&#39;, &#39;&#39;, prompt)
cleaned_output = output
try:
newpattern = f&#34;.*({updatedprompt}).*{e}.*&#34;
cleaned_output = re.sub(newpattern, &#39;&#39;, cleaned_output)
except re.error:
try:
escaped_e = re.escape(e)
newpattern = f&#34;.*({updatedprompt}).*{escaped_e}.*&#34;
cleaned_output = re.sub(newpattern, &#39;&#39;, 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) -&gt; str:
&#34;&#34;&#34;Append -o ConnectTimeout and -o ServerAliveInterval=15 unless already present.&#34;&#34;&#34;
opts_str = str(raw_opts).strip() if raw_opts else &#34;&#34;
if connect_timeout is None:
return opts_str
ct_val = validate_strict_timeout_int(connect_timeout, &#34;connect_timeout&#34;)
tokens = shlex.split(opts_str) if opts_str else []
existing_keys = _extract_ssh_o_keys(tokens)
if &#34;connecttimeout&#34; not in existing_keys and &#34;connecttimeout&#34; in _ALLOWED_SSH_O_KEYS:
tokens.extend([&#34;-o&#34;, f&#34;ConnectTimeout={ct_val}&#34;])
if (
&#34;serveraliveinterval&#34; not in existing_keys
and &#34;serveraliveinterval&#34; in _ALLOWED_SSH_O_KEYS
):
tokens.extend([&#34;-o&#34;, &#34;ServerAliveInterval=15&#34;])
return shlex.join(tokens)
def _effective_jumphost_opt(self, connect_timeout: int | None = None) -&gt; str:
&#34;&#34;&#34;Return ProxyCommand option, rebuilding hop chain with connect_timeout when set.&#34;&#34;&#34;
if (
connect_timeout is not None
and getattr(self, &#34;_jumphost_name&#34;, &#34;&#34;)
and getattr(self, &#34;config&#34;, &#34;&#34;) != &#34;&#34;
):
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(&#34;\\&#34;, &#34;\\\\&#34;).replace(&#39;&#34;&#39;, &#39;\\&#34;&#39;)
return f&#39;-o ProxyCommand=&#34;{escaped}&#34;&#39;
return &#34;&#34;
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 == &#34;mosh&#34;
or getattr(self, &#34;_orig_protocol&#34;, &#34;&#34;) == &#34;mosh&#34;
)
if not is_from_mosh:
self._validate_ssh_options()
proto = &#34;ssh&#34; 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(&#34;-&#34;) or _LEGACY_SSH_UNSAFE_RE.search(u_s):
raise ValueError(f&#34;Invalid characters in user: &#39;{u_s}&#39;&#34;)
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 += (&#34; -p &#34; if proto == &#34;ssh&#34; else &#34; -P &#34;) + port_s
if raw_opts and proto == &#34;sftp&#34;:
sftp_tokens = []
toks = shlex.split(raw_opts)
i = 0
while i &lt; len(toks):
t = toks[i]
if t in (&#34;-X&#34;, &#34;-x&#34;, &#34;-Y&#34;, &#34;-t&#34;, &#34;-A&#34;, &#34;-a&#34;):
i += 1
elif t == &#34;-m&#34;:
i += 2
elif t.startswith(&#34;-m&#34;) and len(t) &gt; 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 &#34;&#34;
opts = self._inject_ssh_timeouts(opts, connect_timeout)
if opts:
cmd += &#34; &#34; + opts
target_h = f&#34;[{host_bare}]&#34; if (proto == &#34;sftp&#34; and &#34;:&#34; in host_bare) else host_bare
else:
if self.port != &#34;&#34; and self.port is not None:
if proto == &#34;ssh&#34;:
cmd += &#34; -p &#34; + str(self.port)
elif proto == &#34;sftp&#34;:
cmd += &#34; -P &#34; + str(self.port)
raw_opts = self.options
opts = &#34;&#34;
if raw_opts:
opts = str(raw_opts).strip()
if proto == &#34;sftp&#34;:
opts = re.sub(r&#39;(?&lt;!\S)-[XxtTAaNf]\b&#39;, &#39;&#39;, opts).strip()
opts = self._inject_ssh_timeouts(opts, connect_timeout)
if opts:
cmd += &#34; &#34; + opts
target_h = self.host
jh_opt = self._effective_jumphost_opt(connect_timeout=connect_timeout)
if jh_opt:
cmd += &#34; &#34; + jh_opt
user_host = f&#34;{eff_user}@{target_h}&#34; if eff_user else target_h
cmd += f&#34; {user_host}&#34;
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(&#34;-&#34;):
raise ValueError(&#34;Host cannot start with &#39;-&#39;&#34;)
if eff_user and str(eff_user).startswith(&#34;-&#34;):
raise ValueError(&#34;User cannot start with &#39;-&#39;&#34;)
if not self.host or re.search(r&#39;[\s;|&amp;$`&gt;&lt;&#34;\&#39;\\]&#39;, str(self.host)):
raise ValueError(f&#34;Invalid characters in host: &#39;{self.host}&#39;&#34;)
if eff_user and re.search(r&#39;[\s;|&amp;$`&gt;&lt;&#34;\&#39;\\]&#39;, str(eff_user)):
raise ValueError(f&#34;Invalid characters in user: &#39;{eff_user}&#39;&#34;)
cmd_parts = [&#34;mosh&#34;]
if isinstance(self.tags, dict):
if self.tags.get(&#34;mosh_server&#34;):
server_bin = str(self.tags[&#34;mosh_server&#34;]).strip()
if server_bin:
cmd_parts.append(f&#34;--server={shlex.quote(server_bin)}&#34;)
if self.tags.get(&#34;mosh_udp_port&#34;):
udp_port = str(self.tags[&#34;mosh_udp_port&#34;]).strip()
if udp_port:
if not re.match(r&#34;^\d+(:\d+)?$&#34;, udp_port):
raise ValueError(
f&#34;Invalid mosh_udp_port &#39;{udp_port}&#39;: must be PORT or PORT1:PORT2&#34;
)
cmd_parts.append(f&#34;-p {shlex.quote(udp_port)}&#34;)
ssh_parts = [&#34;ssh&#34;]
if self.port != &#34;&#34; and self.port is not None:
port_s = str(self.port).strip()
if port_s:
if not re.fullmatch(r&#34;^\d+$&#34;, port_s) or not (1 &lt;= int(port_s) &lt;= 65535):
raise ValueError(f&#34;Invalid TCP SSH port &#39;{self.port}&#39;&#34;)
ssh_parts.append(f&#34;-p {port_s}&#34;)
ssh_opts = &#34;&#34;
if isinstance(self.tags, dict) and self.tags.get(&#34;mosh_ssh_options&#34;):
ssh_opts = str(self.tags[&#34;mosh_ssh_options&#34;]).strip()
if ssh_opts:
if not self._is_unsafe_allowed() and re.search(
r&#39;(?:LocalCommand|ProxyCommand|PermitLocalCommand|KnownHostsCommand)&#39;,
ssh_opts,
re.IGNORECASE,
):
raise ValueError(&#34;mosh_ssh_options cannot contain LocalCommand or ProxyCommand&#34;)
try:
shlex.split(ssh_opts)
except ValueError as exc:
raise ValueError(&#34;Invalid mosh_ssh_options: unbalanced quotes&#34;) 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) &gt; 1:
raw_ssh = &#34; &#34;.join(ssh_parts)
cmd_parts.append(f&#34;--ssh={shlex.quote(raw_ssh)}&#34;)
if self.options:
opts = str(self.options).strip()
if opts:
if re.search(r&#39;--(?:ssh|server|client)(?:=|\s|$)&#39;, opts):
raise ValueError(&#34;Options cannot override --ssh, --server or --client for mosh&#34;)
if not self._is_unsafe_allowed() and re.search(
r&#39;(?:LocalCommand|ProxyCommand|PermitLocalCommand|KnownHostsCommand)&#39;,
opts,
re.IGNORECASE,
):
raise ValueError(&#34;Options cannot contain LocalCommand or ProxyCommand&#34;)
try:
shlex.split(opts)
except ValueError as exc:
raise ValueError(&#34;Invalid options: unbalanced quotes&#34;) from exc
cmd_parts.append(opts)
user_host = f&#34;{eff_user}@{self.host}&#34; if eff_user else self.host
cmd_parts.extend([&#34;--&#34;, user_host])
return &#34; &#34;.join(cmd_parts)
@MethodHook
def _generate_telnet_cmd(self):
self._validate_base_fields(check_port=True)
self._validate_options_and_safety()
cmd = f&#34;telnet {self.host}&#34;
if self.port:
cmd += f&#34; {self.port}&#34;
if self.options:
cmd += f&#34; {self.options}&#34;
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(&#34;kube_command&#34;, &#34;/bin/bash&#34;) if isinstance(self.tags, dict) else &#34;/bin/bash&#34;
if not self._is_unsafe_allowed() and kube_command:
k_str = str(kube_command)
if any(c in k_str for c in (&#34;\n&#34;, &#34;\r&#34;, &#34;\x00&#34;)):
raise ValueError(&#34;kube_command cannot contain newlines or null bytes&#34;)
try:
shlex.split(k_str)
except ValueError as e:
raise ValueError(f&#34;Invalid kube_command: unbalanced quotes ({e})&#34;) from e
cmd = f&#34;kubectl exec {self.options} {self.host} -it --&#34;
cmd += f&#34; {kube_command}&#34;
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(&#34;docker_command&#34;, &#34;/bin/bash&#34;) if isinstance(self.tags, dict) else &#34;/bin/bash&#34;
if not self._is_unsafe_allowed() and docker_command:
d_str = str(docker_command)
if any(c in d_str for c in (&#34;\n&#34;, &#34;\r&#34;, &#34;\x00&#34;)):
raise ValueError(&#34;docker_command cannot contain newlines or null bytes&#34;)
try:
shlex.split(d_str)
except ValueError as e:
raise ValueError(f&#34;Invalid docker_command: unbalanced quotes ({e})&#34;) from e
cmd = f&#34;docker {self.options} exec -it {self.host}&#34;
cmd += f&#34; {docker_command}&#34;
return cmd
@MethodHook
def _generate_ssm_cmd(self):
self._validate_base_fields(check_port=False)
self._validate_options_and_safety()
region = self.tags.get(&#34;region&#34;, &#34;&#34;) if isinstance(self.tags, dict) else &#34;&#34;
profile = self.tags.get(&#34;profile&#34;, &#34;&#34;) if isinstance(self.tags, dict) else &#34;&#34;
if not self._is_unsafe_allowed():
for field_name, field_val in [(&#34;region&#34;, region), (&#34;profile&#34;, profile)]:
if field_val:
f_str = str(field_val)
if f_str.startswith(&#34;-&#34;):
raise ValueError(f&#34;SSM tag &#39;{field_name}&#39; cannot start with &#39;-&#39;: &#39;{field_val}&#39;&#34;)
if re.search(r&#39;[\s\x00-\x1f\x7f;|&amp;$`&gt;&lt;&#34;\&#39;]&#39;, f_str):
raise ValueError(f&#34;Invalid characters in SSM tag &#39;{field_name}&#39;: &#39;{field_val}&#39;&#34;)
cmd = f&#34;aws ssm start-session --target {self.host}&#34;
if region:
cmd += f&#34; --region {region}&#34;
if profile:
cmd += f&#34; --profile {profile}&#34;
if self.options:
cmd += f&#34; {self.options}&#34;
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 [&#34;ssh&#34;, &#34;sftp&#34;]:
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 == &#34;mosh&#34;:
return self._generate_mosh_cmd(
connect_timeout=connect_timeout,
user_override=user_override,
)
elif self.protocol == &#34;telnet&#34;:
return self._generate_telnet_cmd()
elif self.protocol == &#34;kubectl&#34;:
return self._generate_kube_cmd()
elif self.protocol == &#34;docker&#34;:
return self._generate_docker_cmd()
elif self.protocol == &#34;ssm&#34;:
return self._generate_ssm_cmd()
elif self.protocol == &#34;local&#34;:
return self.host
else:
printer.error(f&#34;Invalid protocol: {self.protocol}&#34;)
sys.exit(1)
def _spawn_child(self, args, protocol=None, encoding=None, *, _secrets=()):
if protocol is None:
protocol = getattr(self, &#34;protocol&#34;, &#34;&#34;)
env = None
if protocol == &#34;mosh&#34;:
env = os.environ.copy()
if not any(
&#34;utf-8&#34; in env.get(k, &#34;&#34;).lower() or &#34;utf8&#34; in env.get(k, &#34;&#34;).lower()
for k in (&#34;LC_ALL&#34;, &#34;LC_CTYPE&#34;, &#34;LANG&#34;)
):
env[&#34;LC_ALL&#34;] = &#34;C.UTF-8&#34;
env.setdefault(&#34;TERM&#34;, &#34;xterm-256color&#34;)
spawn_kwargs = {}
if env is not None:
spawn_kwargs[&#34;env&#34;] = env
if encoding is not None:
spawn_kwargs[&#34;encoding&#34;] = encoding
try:
return pexpect.spawn(args[0], args[1:], **spawn_kwargs), None
except Exception as exc: # noqa: BLE001
sanitized = sanitize_exception(
exc,
code=&#34;SPAWN_ERROR&#34;,
secrets=_secrets,
context_label=&#34;Connection failed&#34;,
)
return None, str(sanitized)
def _extract_auth_budgets(self) -&gt; tuple[int, int | None, int | None, int | None]:
cfg_dict = (
self.config.config
if (self.config and hasattr(self.config, &#34;config&#34;) 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(&#34;max_auth_prompts&#34;, DEFAULT_MAX_AUTH_PROMPTS),
&#34;max_auth_prompts&#34;,
MIN_AUTH_PROMPTS,
MAX_AUTH_PROMPTS_CAP,
)
raw_total = _pick(&#34;max_total_auth_attempts&#34;, None)
max_total_auth_attempts = (
None
if raw_total is None
else validate_strict_int_range(
raw_total,
&#34;max_total_auth_attempts&#34;,
MIN_TOTAL_AUTH_ATTEMPTS,
MAX_TOTAL_AUTH_ATTEMPTS_CAP,
)
)
raw_hop = _pick(&#34;max_hop_host_attempts&#34;, None)
max_hop_host_attempts = (
None
if raw_hop is None
else validate_strict_int_range(
raw_hop,
&#34;max_hop_host_attempts&#34;,
MIN_HOP_HOST_ATTEMPTS,
MAX_HOP_HOST_ATTEMPTS_CAP,
)
)
raw_global_user = _pick(&#34;max_global_user_attempts&#34;, None)
max_global_user_attempts = (
None
if raw_global_user is None
else validate_strict_int_range(
raw_global_user,
&#34;max_global_user_attempts&#34;,
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],
) -&gt; None:
raw_msg = (
f&#34;[AAA-FALLBACK] Activating backup credentials ({label}) &#34;
f&#34;for node={unique} host={host} proto={protocol} user={user or &#39;&lt;default&gt;&#39;}&#34;
)
safe_msg = sanitize_log_message(raw_msg, secrets=secrets)
if logger:
try:
logger(&#34;warning&#34;, safe_msg)
return
except Exception: # noqa: BLE001
_LOGGER.debug(&#34;Fallback logger failed; falling back to stderr&#34;)
with suppress(Exception):
sys.stderr.write(safe_msg + &#34;\n&#34;)
sys.stderr.flush()
def _build_local_decryptor(self):
decryptor_cache = {}
def _decrypt_one(cipher_text: str) -&gt; str:
if not re.match(r&#39;^b[&#34;\&#39;].+[&#34;\&#39;]$&#39;, cipher_text, re.DOTALL):
return cipher_text
if &#34;fn&#34; not in decryptor_cache:
keyfile = getattr(self, &#34;key&#34;, None)
if not keyfile:
raise SanitizedAuthError(&#34;No RSA key configured&#34;, code=&#34;AUTH_FAILED&#34;)
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[&#34;fn&#34;] = PKCS1_OAEP.new(rsa_key)
raw_bytes = ast.literal_eval(cipher_text)
return decryptor_cache[&#34;fn&#34;].decrypt(raw_bytes).decode(&#34;utf-8&#34;)
return _decrypt_one
def _resolve_runtime_credentials(
self,
*,
allow_fallback: bool,
unattended: bool,
) -&gt; tuple[list[RuntimeAuthCandidate], list[list[str]], list[str]]:
profiles_map = (
getattr(self.config, &#34;profiles&#34;, {})
if (getattr(self, &#34;config&#34;, &#34;&#34;) != &#34;&#34; and self.config is not None)
else {}
)
local_decrypt = self._build_local_decryptor()
passtx_desc = type(self).__dict__.get(&#34;_passtx&#34;)
passtx_mocked = &#34;_passtx&#34; in self.__dict__ or not isinstance(passtx_desc, MethodHook)
def _decrypt_plain_list(specs: list[str]) -&gt; 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, ...]) -&gt; list[str]:
items = list(spec) if isinstance(spec, (tuple, list)) else ([spec] if spec != &#34;&#34; else [])
out: list[str] = []
for item in items:
if not isinstance(item, str) or item == &#34;&#34;:
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, &#34;_auth_candidates&#34;, ()))
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 != &#34;&#34;)
if non_empty or self.user:
candidates_src = [
AuthCandidate(
user=str(self.user or &#34;&#34;),
password_spec=non_empty if len(non_empty) &gt; 1 else (non_empty[0] if non_empty else &#34;&#34;),
is_fallback=False,
label=&#34;primary&#34;,
)
]
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=&#34;&#34;,
has_password=False,
is_fallback=cand.is_fallback,
label=cand.label,
)
)
hop_runtime_passwords: list[list[str]] = []
for hop in getattr(self, &#34;_jumphost_hops&#34;, ()):
h_pws = _expand_spec(hop.get(&#34;passwords&#34;, ()))
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) -&gt; tuple[str, int | None]:
&#34;&#34;&#34;Classify password prompt line strictly using exact host boundaries.&#34;&#34;&#34;
tags_dict = self.tags if isinstance(self.tags, dict) else {}
target_names = [str(self.host)]
if tags_dict.get(&#34;fqdn&#34;):
target_names.append(str(tags_dict[&#34;fqdn&#34;]))
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, &#34;_jumphost_hops&#34;, ())):
h_names = [hop.get(&#34;host&#34;, &#34;&#34;)]
if hop.get(&#34;resolved_fqdn&#34;):
h_names.append(str(hop[&#34;resolved_fqdn&#34;]))
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 &gt; 1:
return &#34;conflict&#34;, None
if matched_hops:
return &#34;hop&#34;, matched_hops[0]
if matched_target:
return &#34;target&#34;, None
return &#34;ambiguous&#34;, 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(&#34;missingtext&#34;, None)
self.last_fallback_used = False
effective_protocol = &#34;ssh&#34; if force_ssh else self.protocol
if effective_protocol == &#34;mosh&#34; and shutil.which(&#34;mosh&#34;) is None:
return &#34;Connection failed: mosh binary not found in PATH&#34;
hop_meta = getattr(self, &#34;_hop_chain_meta&#34;, None) or []
try:
validate_strict_timeout_int(
max_attempts,
&#34;max_attempts&#34;,
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&#34;Connection failed code: 12\nInvalid timeout configuration: {e}&#34;
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=&#34;AUTH_FAILED&#34;,
context_label=&#34;invalid auth budget config&#34;,
)
return str(san)
if effective_protocol == &#34;local&#34;:
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 != &#39;&#39;:
self.logfile = self._logfile()
return True
cfg_dict = (
self.config.config
if (self.config and hasattr(self.config, &#34;config&#34;) and isinstance(self.config.config, dict))
else {}
)
tags_dict = self.tags if isinstance(self.tags, dict) else {}
allow_fallback = not (tags_dict.get(&#34;allow_fallback&#34;) is False)
disable_insecure_hk = bool(
getattr(self, &#34;disable_fallback_on_insecure_hostkey&#34;, False)
or tags_dict.get(&#34;disable_fallback_on_insecure_hostkey&#34;)
or cfg_dict.get(&#34;disable_fallback_on_insecure_hostkey&#34;)
)
if (
allow_fallback
and disable_insecure_hk
and has_insecure_hostkey_checking(
self.options,
self.tags,
getattr(self, &#34;_jumphost_hops&#34;, ()),
)
):
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=&#34;AUTH_FAILED&#34;,
secrets=raw_secrets,
context_label=&#34;credential resolution failed&#34;,
)
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 != &#39;&#39;:
self.logfile = self._logfile()
default_prompt = r&#39;&gt;$|#$|\$$|&gt;.$|#.$|\$.$&#39;
prompt = tags_dict.get(&#34;prompt&#34;, default_prompt) if tags_dict else default_prompt
password_prompt = (
r&#39;[pP]assword:|[uU]sername:&#39; if effective_protocol != &#39;telnet&#39; else r&#39;[pP]assword:&#39;
)
prompt_unanchored = &#34;|&#34;.join(t.removesuffix(&#34;$&#34;) for t in prompt.split(&#34;|&#34;))
mosh_prompt = r&#34;(?:&#34; + prompt_unanchored + r&#34;)\s*(?:\x1b\[[0-9;?]*[a-zA-Z])*$&#34;
def _precompile_user_pat(pat_str: str):
try:
pat_str.encode(&#34;ascii&#34;)
except UnicodeEncodeError:
return re.compile(pat_str.encode(&#34;utf-8&#34;), re.DOTALL)
return pat_str
user_prompt_pat = _precompile_user_pat(prompt)
mosh_prompt_pat = _precompile_user_pat(mosh_prompt)
expects = {
&#34;ssh&#34;: [
&#39;yes/no&#39;,
r&#39;(?m:^(?:(?:ssh|sftp):[^\r\n]{1,256} )?Connection refused(?:\r?\n))&#39;,
r&#39;(?im:^(?:(?:ssh|sftp|debug\d+):[^\r\n]{1,256}not supported|Permission denied \([^)\r\n]{1,256}\)\.)(?:\r?\n))&#39;,
r&#39;(?im:^(?:(?:ssh|sftp):[^\r\n]{1,256}Invalid|usage:\s*(?:ssh|sftp)\b[^\r\n]{0,256})(?:\r?\n))&#39;,
&#39;ssh-keygen.*&#34;&#39;,
r&#39;(?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))&#39;,
r&#39;(?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))&#39;,
r&#39;(?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))&#39;,
password_prompt,
user_prompt_pat,
&#39;suspend&#39;,
pexpect.EOF,
pexpect.TIMEOUT,
r&#39;(?im:^(?:(?:ssh|sftp):[^\r\n]{1,256})?No route to host(?:\r?\n))&#39;,
r&#39;(?im:^(?:ssh|sftp):[^\r\n]{1,256}resolve hostname[^\r\n]{0,256}(?:\r?\n))&#39;,
r&#39;(?im:^(?:(?:ssh|sftp):|Unable to negotiate with )[^\r\n]{1,256}no matching[^\r\n]{0,256}(?:\r?\n))&#39;,
r&#39;(?im:^Bad (?:owner|permissions)[^\r\n]{0,256}(?:\r?\n))&#39;,
],
&#34;sftp&#34;: [
&#39;yes/no&#39;,
r&#39;(?m:^(?:(?:ssh|sftp):[^\r\n]{1,256} )?Connection refused(?:\r?\n))&#39;,
r&#39;(?im:^(?:(?:ssh|sftp|debug\d+):[^\r\n]{1,256}not supported|Permission denied \([^)\r\n]{1,256}\)\.)(?:\r?\n))&#39;,
r&#39;(?im:^(?:(?:ssh|sftp):[^\r\n]{1,256}Invalid|usage:\s*(?:ssh|sftp)\b[^\r\n]{0,256})(?:\r?\n))&#39;,
&#39;ssh-keygen.*&#34;&#39;,
r&#39;(?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))&#39;,
r&#39;(?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))&#39;,
r&#39;(?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))&#39;,
password_prompt,
user_prompt_pat,
&#39;suspend&#39;,
pexpect.EOF,
pexpect.TIMEOUT,
r&#39;(?im:^(?:(?:ssh|sftp):[^\r\n]{1,256})?No route to host(?:\r?\n))&#39;,
r&#39;(?im:^(?:ssh|sftp):[^\r\n]{1,256}resolve hostname[^\r\n]{0,256}(?:\r?\n))&#39;,
r&#39;(?im:^(?:(?:ssh|sftp):|Unable to negotiate with )[^\r\n]{1,256}no matching[^\r\n]{0,256}(?:\r?\n))&#39;,
r&#39;(?im:^Bad (?:owner|permissions)[^\r\n]{0,256}(?:\r?\n))&#39;,
],
&#34;telnet&#34;: [
r&#39;[uU]sername:&#39;,
r&#39;(?im:^(?:telnet:[^\r\n]{1,256} )?(?:Unable to connect to remote host: )?Connection refused(?:\r?\n))&#39;,
r&#39;(?im:^(?:telnet:[^\r\n]{1,256}not supported|[^\r\n]{0,64}Authentication not supported)(?:\r?\n))&#39;,
r&#39;(?im:^(?:telnet:|usage:\s*telnet\b)[^\r\n]{0,256}(?:invalid|unrecognized option)[^\r\n]{0,256}(?:\r?\n))&#39;,
&#39;ssh-keygen.*&#34;&#39;,
r&#39;(?im:^(?:telnet:[^\r\n]{1,256}(?:Operation timed out|Connection timed out)|Connection timed out)(?:\r?\n))&#39;,
r&#39;(?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))&#39;,
r&#39;(?im:^(?:Connection closed by (?:foreign host|remote host)|telnet:[^\r\n]{1,256}closed)(?:\r?\n))&#39;,
password_prompt,
user_prompt_pat,
&#39;suspend&#39;,
pexpect.EOF,
pexpect.TIMEOUT,
r&#39;(?im:^(?:telnet:[^\r\n]{1,256})?No route to host(?:\r?\n))&#39;,
r&#39;(?im:^telnet:[^\r\n]{1,256}resolve hostname[^\r\n]{0,256}(?:\r?\n))&#39;,
r&#39;(?im:^telnet:[^\r\n]{1,256}no matching[^\r\n]{0,256}(?:\r?\n))&#39;,
r&#39;(?im:^Bad (?:owner|permissions)[^\r\n]{0,256}(?:\r?\n))&#39;,
],
&#34;kubectl&#34;: [
r&#39;[uU]sername:&#39;,
r&#39;[rR]efused&#39;,
r&#39;[Ee]rror&#39;,
&#39;DEPRECATED&#39;,
pexpect.TIMEOUT,
password_prompt,
user_prompt_pat,
pexpect.EOF,
&#34;expired|invalid&#34;,
],
&#34;docker&#34;: [
r&#39;[uU]sername:&#39;,
&#39;Cannot&#39;,
r&#39;[Ee]rror&#39;,
&#39;failed&#39;,
&#39;not a docker command&#39;,
&#39;unknown&#39;,
&#39;unable to resolve&#39;,
pexpect.TIMEOUT,
password_prompt,
user_prompt_pat,
pexpect.EOF,
],
&#34;ssm&#34;: [
r&#39;[uU]sername:&#39;,
r&#39;(?im:^(?:Cannot (?:perform start-session|connect to instance|start session)[^\r\n]{0,256})(?:\r?\n))&#39;,
r&#39;(?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))&#39;,
r&#39;(?im:^(?:TargetNotConnected[^\r\n]{0,256}|(?:SessionManagerPlugin|Starting session|An error occurred)[^\r\n]{0,256}failed[^\r\n]{0,256})(?:\r?\n))&#39;,
&#39;SessionManagerPlugin&#39;,
r&#39;(?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))&#39;,
r&#39;(?im:^(?:Could not resolve host|Unable to locate credentials|Unable to resolve [^\r\n]{1,256})(?:\r?\n))&#39;,
pexpect.TIMEOUT,
password_prompt,
user_prompt_pat,
pexpect.EOF,
],
}
expects[&#34;mosh&#34;] = [
&#39;yes/no&#39;,
r&#39;(?:ssh: connect to host .* port .*: Connection refused|Connection refused)&#39;,
r&#39;(?:(?:ssh|mosh): .*supported|Permission denied \([^)\r\n]{1,256}\)\.)&#39;,
r&#39;(?:(?:ssh|mosh): (?:Invalid|usage)|Unknown option:)&#39;,
&#39;ssh-keygen.*&#34;&#39;,
r&#39;(?:ssh: connect to host .* port .*: Connection timed out|mosh: .* timed out)&#39;,
r&#39;(?:ssh|mosh): .*unavailable&#39;,
r&#39;(?:Connection to .* closed|Connection closed by remote host)&#39;,
password_prompt,
mosh_prompt_pat,
&#39;suspend&#39;,
pexpect.EOF,
pexpect.TIMEOUT,
&#34;No route to host&#34;,
&#34;resolve hostname&#34;,
r&#39;(?:ssh|mosh): .*no matching&#39;,
r&#34;[bB]ad (owner|permissions)&#34;,
&#34;mosh-server:.*not found|command not found&#34;,
r&#34;(?:Did not find mosh server startup message|(?:mosh: )?Nothing received from server on UDP port \d+\.?|Nothing received from server)&#34;,
&#34;needs a UTF-8 native locale to run|requires a UTF-8 locale|locale.*not available&#34;,
]
compiled_expects = compile_expects(expects)
error_indices = {
&#34;ssh&#34;: [1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 16],
&#34;sftp&#34;: [1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 16],
&#34;telnet&#34;: [1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 16],
&#34;kubectl&#34;: [1, 2, 3, 4, 8],
&#34;docker&#34;: [1, 2, 3, 4, 5, 6, 7],
&#34;ssm&#34;: [1, 2, 3, 4, 5, 6, 7],
&#34;mosh&#34;: [1, 2, 3, 4, 5, 6, 7, 12, 13, 14, 15, 16, 17, 18, 19],
}
eof_indices = {
&#34;ssh&#34;: [8, 9, 10, 11],
&#34;sftp&#34;: [8, 9, 10, 11],
&#34;telnet&#34;: [8, 9, 10, 11],
&#34;kubectl&#34;: [5, 6, 7],
&#34;docker&#34;: [8, 9, 10],
&#34;ssm&#34;: [8, 9, 10],
&#34;mosh&#34;: [8, 9, 10, 11],
}
initial_indices = {
&#34;ssh&#34;: [0],
&#34;sftp&#34;: [0],
&#34;telnet&#34;: [0],
&#34;kubectl&#34;: [0],
&#34;docker&#34;: [0],
&#34;ssm&#34;: [0],
&#34;mosh&#34;: [0],
}
def _to_bytes(val) -&gt; bytes:
if val is None:
return b&#34;&#34;
if isinstance(val, bytes):
return val
return str(val).encode(&#34;utf-8&#34;, errors=&#34;replace&#34;)
def _to_str(val) -&gt; str:
if val is None:
return &#34;&#34;
if isinstance(val, bytes):
return val.decode(&#34;utf-8&#34;, errors=&#34;replace&#34;)
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 == &#34;kubectl&#34; else 8
suspend_idx = 10 if effective_protocol in (&#34;ssh&#34;, &#34;sftp&#34;, &#34;telnet&#34;, &#34;mosh&#34;) else None
stream_limit = MAX_AUTH_STREAM_BYTES if unattended else MAX_PRE_AUTH_BUFFER_BYTES
jumphost_hops = getattr(self, &#34;_jumphost_hops&#34;, ())
st: dict[str, object] = {
&#34;cand_idx&#34;: 0,
&#34;connect_retries&#34;: 0,
&#34;eof_fallback_advances&#34;: 0,
&#34;target_creds_sent&#34;: False,
&#34;cur_cand&#34;: None,
&#34;cur_user&#34;: &#34;&#34;,
&#34;handshake_progressed&#34;: False,
&#34;prompts_this_conn&#34;: 0,
&#34;cand_sent_pw_this_conn&#34;: False,
&#34;logged_fallback_this_cand&#34;: False,
&#34;stage&#34;: &#34;connect&#34;,
&#34;last_observed_bytes_len&#34;: 0,
}
def _handle_username_prompt(child_obj) -&gt; tuple[bool, str | None]:
if not use_auth_chain:
manual_user = (
(runtime_candidates[0].user if runtime_candidates else &#34;&#34;)
or str(self.user or &#34;&#34;)
)
if manual_user:
child_obj.sendline(manual_user)
st[&#34;last_observed_bytes_len&#34;] = 0
return False, None
self.missingtext = True
return True, None
cand_idx_cur = int(st[&#34;cand_idx&#34;])
prompts_cur = int(st[&#34;prompts_this_conn&#34;])
cur_cand = st[&#34;cur_cand&#34;]
if st[&#34;cand_sent_pw_this_conn&#34;]:
if (cand_idx_cur + 1) &gt;= len(runtime_candidates):
return False, str(sanitize_exception(None, code=&#34;AUTH_FAILED&#34;, secrets=raw_secrets))
if prompts_cur &gt;= max_auth_prompts:
st[&#34;cand_idx&#34;] = cand_idx_cur + 1
return False, &#34;__NEXT__:next_candidate&#34;
cand_idx_cur += 1
st[&#34;cand_idx&#34;] = cand_idx_cur
cur_cand = runtime_candidates[cand_idx_cur]
st[&#34;cur_cand&#34;] = cur_cand
st[&#34;cur_user&#34;] = cur_cand.user
st[&#34;cand_sent_pw_this_conn&#34;] = False
st[&#34;logged_fallback_this_cand&#34;] = False
u_to_send = cur_cand.user if cur_cand is not None else &#34;&#34;
if not u_to_send:
if (cand_idx_cur + 1) &lt; len(runtime_candidates) and runtime_candidates[cand_idx_cur + 1].user:
cand_idx_cur += 1
st[&#34;cand_idx&#34;] = cand_idx_cur
cur_cand = runtime_candidates[cand_idx_cur]
st[&#34;cur_cand&#34;] = cur_cand
st[&#34;cur_user&#34;] = cur_cand.user
u_to_send = cur_cand.user
st[&#34;logged_fallback_this_cand&#34;] = False
else:
return False, str(sanitize_exception(None, code=&#34;NO_CREDS&#34;, secrets=raw_secrets))
if not tracker.try_acquire_user(u_to_send, limit=max_global_user_attempts):
return False, str(
sanitize_exception(None, code=&#34;USER_BUDGET_EXHAUSTED&#34;, secrets=raw_secrets)
)
if cur_cand is not None and cur_cand.is_fallback and not st[&#34;logged_fallback_this_cand&#34;]:
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[&#34;logged_fallback_this_cand&#34;] = True
child_obj.sendline(u_to_send)
st[&#34;handshake_progressed&#34;] = True
st[&#34;stage&#34;] = &#34;auth&#34;
st[&#34;last_observed_bytes_len&#34;] = 0
return False, None
def _handle_target_password_prompt(child_obj) -&gt; tuple[bool, str | None]:
cand_idx_cur = int(st[&#34;cand_idx&#34;])
prompts_cur = int(st[&#34;prompts_this_conn&#34;])
cur_cand = st[&#34;cur_cand&#34;]
cur_user = str(st[&#34;cur_user&#34;])
if not use_auth_chain:
self.missingtext = True
return True, None
if st[&#34;cand_sent_pw_this_conn&#34;]:
if (cand_idx_cur + 1) &gt;= len(runtime_candidates):
return False, str(sanitize_exception(None, code=&#34;AUTH_FAILED&#34;, secrets=raw_secrets))
nxt = runtime_candidates[cand_idx_cur + 1]
if nxt.user == cur_user and prompts_cur &lt; max_auth_prompts:
cand_idx_cur += 1
st[&#34;cand_idx&#34;] = cand_idx_cur
cur_cand = nxt
st[&#34;cur_cand&#34;] = cur_cand
st[&#34;cand_sent_pw_this_conn&#34;] = False
st[&#34;logged_fallback_this_cand&#34;] = False
else:
st[&#34;cand_idx&#34;] = cand_idx_cur + 1
return False, &#34;__NEXT__:next_candidate&#34;
if cur_cand is None or not cur_cand.has_password:
if (cand_idx_cur + 1) &lt; len(runtime_candidates):
nxt = runtime_candidates[cand_idx_cur + 1]
if nxt.user == cur_user and prompts_cur &lt; max_auth_prompts:
cand_idx_cur += 1
st[&#34;cand_idx&#34;] = cand_idx_cur
cur_cand = nxt
st[&#34;cur_cand&#34;] = cur_cand
st[&#34;cand_sent_pw_this_conn&#34;] = False
st[&#34;logged_fallback_this_cand&#34;] = False
else:
st[&#34;cand_idx&#34;] = cand_idx_cur + 1
return False, &#34;__NEXT__:next_candidate&#34;
else:
return False, str(sanitize_exception(None, code=&#34;NO_CREDS&#34;, secrets=raw_secrets))
if not cur_cand.has_password:
return False, str(sanitize_exception(None, code=&#34;NO_CREDS&#34;, secrets=raw_secrets))
if prompts_cur &gt;= max_auth_prompts:
if (cand_idx_cur + 1) &lt; len(runtime_candidates):
st[&#34;cand_idx&#34;] = cand_idx_cur + 1
return False, &#34;__NEXT__:next_candidate&#34;
return False, str(sanitize_exception(None, code=&#34;AUTH_FAILED&#34;, secrets=raw_secrets))
eff_u = cur_cand.user or str(self.user or &#34;&#34;)
acquired, budget_err_code = tracker.try_acquire_target_attempt(
host=str(self.host),
port=str(self.port or &#34;&#34;),
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 &#34;HOST_BUDGET_EXHAUSTED&#34;,
secrets=raw_secrets,
)
)
if cur_cand.is_fallback and not st[&#34;logged_fallback_this_cand&#34;]:
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[&#34;logged_fallback_this_cand&#34;] = True
child_obj.sendline(cur_cand.password)
st[&#34;cand_sent_pw_this_conn&#34;] = True
st[&#34;target_creds_sent&#34;] = True
st[&#34;prompts_this_conn&#34;] = prompts_cur + 1
st[&#34;handshake_progressed&#34;] = True
st[&#34;stage&#34;] = &#34;auth&#34;
st[&#34;last_observed_bytes_len&#34;] = 0
return False, None
while True:
remaining = deadline - clock()
if remaining &lt;= 0:
return _redact_known_secrets(
f&#34;Connection failed code: 12\nConnection timeout (global deadline {max_total}s exceeded)&#34;,
raw_secrets,
)
cand_idx_val = int(st[&#34;cand_idx&#34;])
cur_cand = runtime_candidates[cand_idx_val] if cand_idx_val &lt; len(runtime_candidates) else None
cur_user = cur_cand.user if cur_cand is not None else str(self.user or &#34;&#34;)
st[&#34;cur_cand&#34;] = cur_cand
st[&#34;cur_user&#34;] = cur_user
user_override = (
cur_user
if (cand_idx_val &gt; 0 or (cur_user and cur_user != str(self.user or &#34;&#34;)))
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[&#34;handshake_progressed&#34;] = 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[&#34;prompts_this_conn&#34;] = 0
st[&#34;cand_sent_pw_this_conn&#34;] = False
st[&#34;logged_fallback_this_cand&#34;] = 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(&#34;console&#34;):
child.sendline()
if debug:
if logger:
logger(&#34;debug&#34;, f&#34;Command:\n{_redact_known_secrets(cmd, raw_secrets)}&#34;)
local_mylog = io.BytesIO()
self.mylog = local_mylog
redacted_cmd = _redact_known_secrets(cmd, raw_secrets)
local_mylog.write(f&#34;[i] [DEBUG] Command:\r\n {redacted_cmd}\r\n&#34;.encode())
if not unattended:
child.logfile_read = local_mylog
st[&#34;stage&#34;] = &#34;connect&#34;
progress_extensions = 0
st[&#34;last_observed_bytes_len&#34;] = 0
while True:
remaining = deadline - clock()
if remaining &lt;= 0:
return _redact_known_secrets(
f&#34;Connection failed code: 12\nConnection timeout (global deadline {max_total}s exceeded)&#34;,
raw_secrets,
)
stage_timeout = eff_ct if st[&#34;stage&#34;] == &#34;connect&#34; 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, &#34;before&#34;, b&#34;&#34;))
after_bytes = _to_bytes(getattr(child, &#34;after&#34;, b&#34;&#34;))
if len(before_bytes) &gt; stream_limit:
return _redact_known_secrets(
f&#34;Connection failed code: 12\nPre-auth buffer exceeded maximum size ({stream_limit} bytes)&#34;,
raw_secrets,
)
if results in initial_indices[effective_protocol]:
if effective_protocol in [&#34;ssh&#34;, &#34;sftp&#34;, &#34;mosh&#34;]:
child.sendline(&#39;yes&#39;)
st[&#34;handshake_progressed&#34;] = True
st[&#34;last_observed_bytes_len&#34;] = 0
elif effective_protocol in [&#34;telnet&#34;, &#34;kubectl&#34;, &#34;docker&#34;, &#34;ssm&#34;]:
should_break, msg_or_action = _handle_username_prompt(child)
if msg_or_action == &#34;__NEXT__:next_candidate&#34;:
next_action = &#34;next_candidate&#34;
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 &gt; int(st[&#34;last_observed_bytes_len&#34;])
st[&#34;last_observed_bytes_len&#34;] = cur_len
remaining = deadline - clock()
can_extend = (
bytes_grew
and progress_extensions &lt; max_ext
and remaining &gt; 0
and not (effective_protocol == &#34;mosh&#34; and st[&#34;handshake_progressed&#34;])
)
if can_extend:
progress_extensions += 1
if not budget_warned:
budget_warned = True
if logger:
logger(
&#34;warning&#34;,
f&#34;Slow {effective_protocol} handshake making progress; extending connect wait (deadline {max_total}s)&#34;,
)
continue
if (
use_auth_chain
and st[&#34;stage&#34;] == &#34;auth&#34;
and st[&#34;target_creds_sent&#34;]
and (int(st[&#34;cand_idx&#34;]) + 1) &lt; len(runtime_candidates)
and remaining &gt; 0
):
st[&#34;cand_idx&#34;] = int(st[&#34;cand_idx&#34;]) + 1
next_action = &#34;next_candidate&#34;
break
can_retry = (
not st[&#34;target_creds_sent&#34;]
and (int(st[&#34;connect_retries&#34;]) + 1) &lt; max_attempts
and remaining &gt; 0
and not (effective_protocol == &#34;mosh&#34; and st[&#34;handshake_progressed&#34;])
)
if can_retry:
st[&#34;connect_retries&#34;] = int(st[&#34;connect_retries&#34;]) + 1
next_action = &#34;retry_connect&#34;
break
before_str = _to_str(before_bytes)
if effective_protocol == &#34;mosh&#34;:
before_str = self._logclean(before_str, True)
if remaining &lt;= 0:
after_str = f&#34;Connection timeout (global deadline {max_total}s exceeded)&#34;
else:
after_str = &#34;Connection timeout&#34;
return _redact_known_secrets(
f&#34;Connection failed code: {results}\n{before_str.lstrip()}{after_str}&#34;.rstrip(),
raw_secrets,
)
is_perm_denied = (
effective_protocol in (&#34;ssh&#34;, &#34;sftp&#34;, &#34;mosh&#34;)
and results == 2
and b&#34;permission denied&#34; in (before_bytes + after_bytes).lower()
)
if (
use_auth_chain
and is_perm_denied
and (int(st[&#34;cand_idx&#34;]) + 1) &lt; len(runtime_candidates)
and remaining &gt; 0
):
st[&#34;cand_idx&#34;] = int(st[&#34;cand_idx&#34;]) + 1
next_action = &#34;next_candidate&#34;
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 == &#34;mosh&#34;:
after = self._logclean(after, True)
before = self._logclean(before, True)
readline_val = self._logclean(readline_val, True)
if (
effective_protocol == &#34;mosh&#34;
and results == 18
and (&#34;Nothing received from server&#34; in after or &#34;Nothing received from server&#34; in before)
):
err_msg = (
after.strip()
if &#34;Nothing received from server&#34; in after
else before.strip()
)
return _redact_known_secrets(
f&#34;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).&#34;,
raw_secrets,
)
return _redact_known_secrets(
f&#34;Connection failed code: {results}\n{before.lstrip()}{after}{readline_val}&#34;.rstrip(),
raw_secrets,
)
elif results in eof_indices[effective_protocol]:
if results == pw_prompt_idx:
after_lower = after_bytes.lower()
if b&#34;username&#34; in after_lower and b&#34;password&#34; not in after_lower:
should_break, msg_or_action = _handle_username_prompt(child)
if msg_or_action == &#34;__NEXT__:next_candidate&#34;:
next_action = &#34;next_candidate&#34;
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 == &#34;conflict&#34;:
return str(
sanitize_exception(None, code=&#34;JUMP_AUTH_FAILED&#34;, secrets=raw_secrets)
)
if kind == &#34;hop&#34;:
assert hop_idx is not None
if st[&#34;target_creds_sent&#34;] or hop_idx &lt; hop_cursor:
return str(
sanitize_exception(None, code=&#34;JUMP_AUTH_FAILED&#34;, 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] &gt;= len(hop_pws):
return str(
sanitize_exception(None, code=&#34;JUMP_AUTH_FAILED&#34;, secrets=raw_secrets)
)
if not tracker.try_acquire_hop(
hop_obj[&#34;host&#34;],
hop_obj[&#34;port&#34;],
hop_obj[&#34;protocol&#34;],
limit=max_hop_host_attempts,
):
return str(
sanitize_exception(None, code=&#34;HOST_BUDGET_EXHAUSTED&#34;, secrets=raw_secrets)
)
child.sendline(hop_pws[hop_pw_idx[hop_idx]])
hop_pw_idx[hop_idx] += 1
st[&#34;handshake_progressed&#34;] = True
st[&#34;last_observed_bytes_len&#34;] = 0
continue
if kind == &#34;target&#34;:
hop_cursor = len(jumphost_hops)
else:
no_pending_hop_pws = all(
hop_pw_idx[i] &gt;= len(hop_runtime_passwords[i])
for i in range(hop_cursor, len(jumphost_hops))
)
if (
st[&#34;target_creds_sent&#34;]
or hop_cursor &gt;= len(jumphost_hops)
or no_pending_hop_pws
):
hop_cursor = len(jumphost_hops)
else:
allow_ambig = bool(
tags_dict.get(&#34;allow_ambiguous_single_hop_prompt&#34;, False)
)
if len(jumphost_hops) &gt; 1 or not allow_ambig:
return str(
sanitize_exception(
None,
code=&#34;JUMP_AUTH_FAILED&#34;,
secrets=raw_secrets,
)
)
hop_obj = jumphost_hops[hop_cursor]
if not tracker.try_acquire_hop(
hop_obj[&#34;host&#34;],
hop_obj[&#34;port&#34;],
hop_obj[&#34;protocol&#34;],
limit=max_hop_host_attempts,
):
return str(
sanitize_exception(
None,
code=&#34;HOST_BUDGET_EXHAUSTED&#34;,
secrets=raw_secrets,
)
)
child.sendline(
hop_runtime_passwords[hop_cursor][hop_pw_idx[hop_cursor]]
)
hop_pw_idx[hop_cursor] += 1
st[&#34;handshake_progressed&#34;] = True
st[&#34;last_observed_bytes_len&#34;] = 0
continue
should_break, msg_or_action = _handle_target_password_prompt(child)
if msg_or_action == &#34;__NEXT__:next_candidate&#34;:
next_action = &#34;next_candidate&#34;
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(&#34;\r&#34;)
sleep(2)
st[&#34;last_observed_bytes_len&#34;] = 0
elif results_value == pexpect.EOF:
norm_buf = (
before_bytes.replace(b&#34;\r\n&#34;, b&#34;\n&#34;).replace(b&#34;\r&#34;, b&#34;\n&#34;) + b&#34;\n&#34;
)
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 (&#34;ssh&#34;, &#34;sftp&#34;, &#34;mosh&#34;)
and err_idx == 2
and b&#34;permission denied&#34; in m.group(0).lower()
)
if (
use_auth_chain
and is_pd
and (int(st[&#34;cand_idx&#34;]) + 1) &lt; len(runtime_candidates)
and remaining &gt; 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 == &#34;mosh&#34;:
b_str = self._logclean(b_str, True)
a_str = self._logclean(a_str, True)
return _redact_known_secrets(
f&#34;Connection failed code: {err_idx}\n{b_str.lstrip()}{a_str}&#34;.rstrip(),
raw_secrets,
)
if eof_perm_denied:
st[&#34;cand_idx&#34;] = int(st[&#34;cand_idx&#34;]) + 1
next_action = &#34;next_candidate&#34;
break
if use_auth_chain and not transport_error_seen:
if st[&#34;target_creds_sent&#34;]:
if (int(st[&#34;cand_idx&#34;]) + 1) &lt; len(runtime_candidates):
eof_adv = int(st[&#34;eof_fallback_advances&#34;])
if eof_adv &lt; MAX_EOF_FALLBACK_ADVANCES:
st[&#34;eof_fallback_advances&#34;] = eof_adv + 1
st[&#34;cand_idx&#34;] = int(st[&#34;cand_idx&#34;]) + 1
next_action = &#34;next_candidate&#34;
break
return str(
sanitize_exception(
None,
code=&#34;EOF_BUDGET_EXHAUSTED&#34;,
secrets=raw_secrets,
)
)
return str(
sanitize_exception(
None,
code=&#34;AUTH_FAILED&#34;,
secrets=raw_secrets,
)
)
if effective_protocol != &#34;local&#34;:
return str(
sanitize_exception(
None,
code=&#34;TRANSPORT_ERROR&#34;,
secrets=raw_secrets,
)
)
try:
child.sendline()
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;EOF fallback sendline ignored: %s&#34;, type(exc).__name__)
break
else:
cur_cand_now = st[&#34;cur_cand&#34;]
if (
cur_cand_now is not None
and cur_cand_now.is_fallback
and not st[&#34;logged_fallback_this_cand&#34;]
):
self._emit_aaa_fallback_log(
logger,
unique=str(self.unique),
host=str(self.host),
protocol=effective_protocol,
user=str(st[&#34;cur_user&#34;]),
label=cur_cand_now.label,
secrets=raw_secrets,
)
self.last_fallback_used = True
st[&#34;logged_fallback_this_cand&#34;] = True
child.sendline()
break
if next_action in (&#34;retry_connect&#34;, &#34;next_candidate&#34;):
continue
if isinstance(self.tags, dict) and self.tags.get(&#34;post_connect_commands&#34;):
cmds = self.tags.get(&#34;post_connect_commands&#34;)
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=&#34;AUTH_FAILED&#34;,
secrets=raw_secrets,
context_label=&#34;unexpected connection error&#34;,
)
return str(san)
finally:
if not connected_ok:
try:
child.logfile_read = None
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Cleanup logfile_read reset failed: %s&#34;, type(exc).__name__)
try:
child.terminate(force=True)
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Cleanup terminate failed: %s&#34;, type(exc).__name__)
if local_mylog is not None and not getattr(local_mylog, &#34;closed&#34;, False):
try:
local_mylog.close()
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Cleanup local_mylog close failed: %s&#34;, type(exc).__name__)</code></pre>
</details>
<div class="desc"><p>This class generates a node object. Containts all the information and methods to connect and interact with a device using ssh or telnet.</p>
<h3 id="attributes">Attributes:</h3>
<pre><code>- 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.
</code></pre>
<h3 id="parameters">Parameters:</h3>
<pre><code>- unique (str): Unique name to assign to the node.
- host (str): IP address or hostname of the node.
</code></pre>
<h3 id="optional-parameters">Optional Parameters:</h3>
<pre><code>- 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.
</code></pre></div>
<h3>Methods</h3>
<dl>
<dt id="connpy.node.inject_commands"><code class="name flex">
<span>async def <span class="ident">inject_commands</span></span>(<span>self, commands, child_fd, on_inject=None)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@MethodHook
async def inject_commands(self, commands, child_fd, on_inject=None):
&#34;&#34;&#34;
Inject a list of commands into the node&#39;s PTY.
Handles screen_length_command, history tracking and delays.
&#34;&#34;&#34;
if not commands:
return
# 0. Clear line
os.write(child_fd, b&#39;\x15&#39;)
await asyncio.sleep(0.1)
# 1. Prepare list (prepend screen_length if exists)
slc = self.tags.get(&#34;screen_length_command&#34;) if hasattr(self, &#39;tags&#39;) 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&#39;s official history (SKIP if it&#39;s the administrative screen length command)
if cmd != slc and hasattr(self, &#39;cmd_byte_positions&#39;) and self.cmd_byte_positions is not None:
log_pos = self.mylog.tell() if hasattr(self, &#39;mylog&#39;) else 0
self.cmd_byte_positions.append((log_pos, cmd))
if hasattr(self, &#39;current_local_stream&#39;) and self.current_local_stream is not None:
try:
await self.current_local_stream.write(f&#39;\x1b]133;B;{log_pos}\x07&#39;.encode())
except Exception as exc: # noqa: BLE001
_LOGGER.debug(&#34;Failed writing command boundary marker: %s&#34;, exc)
# Write physically to PTY
os.write(child_fd, (cmd + &#34;\n&#34;).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)</code></pre>
</details>
<div class="desc"><p>Inject a list of commands into the node's PTY.
Handles screen_length_command, history tracking and delays.</p></div>
</dd>
<dt id="connpy.node.interact"><code class="name flex">
<span>def <span class="ident">interact</span></span>(<span>self, debug=False, logger=None)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@MethodHook
def interact(self, debug=False, logger=None):
&#39;&#39;&#39;
Asynchronous interactive session using Smart Tunnel architecture.
Allows multiplexing I/O and handling SIGWINCH events locally without blocking.
&#39;&#39;&#39;
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(&#34;Failed resizing child window: %s&#34;, 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(&#34;error&#34;, str(connect))
else:
printer.error(f&#34;Connection failed: {connect!s}&#34;)
sys.exit(1)</code></pre>
</details>
<div class="desc"><p>Asynchronous interactive session using Smart Tunnel architecture.
Allows multiplexing I/O and handling SIGWINCH events locally without blocking.</p></div>
</dd>
<dt id="connpy.node.run"><code class="name flex">
<span>def <span class="ident">run</span></span>(<span>self,<br>commands,<br>vars=None,<br>*,<br>folder='',<br>prompt=&#x27;&gt;$|#$|\\$$|&gt;.$|#.$|\\$.$&#x27;,<br>stdout=False,<br>timeout=None,<br>logger=None,<br>connect_timeout=None,<br>auth_timeout=None,<br>unattended=True,<br>attempt_tracker=None)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@MethodHook
def run(
self,
commands,
vars=None,
*,
folder=&#39;&#39;,
prompt=r&#39;&gt;$|#$|\$$|&gt;.$|#.$|\$.$&#39;,
stdout=False,
timeout=None,
logger=None,
connect_timeout=None,
auth_timeout=None,
_default_cmd_timeout=10,
unattended=True,
attempt_tracker=None,
):
&#39;&#39;&#39;
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 &#34;&gt;&#34; or EOF while
routers use &#34;&gt;&#34; or &#34;#&#34;. 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.
&#39;&#39;&#39;
force_ssh = self.protocol == &#34;mosh&#34;
effective_protocol = &#34;ssh&#34; if force_ssh else self.protocol
try:
_, _, eff_cmd, _, _ = resolve_timeouts(
effective_protocol,
self.tags,
getattr(self, &#34;_hop_chain_meta&#34;, None) or [],
timeout=timeout,
connect_timeout=connect_timeout,
auth_timeout=auth_timeout,
_default_cmd_timeout=_default_cmd_timeout,
)
except ValueError as e:
err = f&#34;Connection failed code: 12\nInvalid timeout configuration: {e}&#34;
self.output = err
self.status = 1
if logger:
logger(&#34;error&#34;, f&#34;Connection failed: {err}&#34;)
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(&#39;%Y-%m-%d_%H%M%S&#39;)
if connect is True:
if logger:
port_str = f&#34;:{self.port}&#34; if self.port and effective_protocol not in [&#34;ssm&#34;, &#34;kubectl&#34;, &#34;docker&#34;] else &#34;&#34;
logger(&#34;success&#34;, f&#34;Connected to {self.unique} at {self.host}{port_str} via: {effective_protocol}&#34;)
if isinstance(self.tags, dict) and &#34;prompt&#34; in self.tags:
prompt = self.tags[&#34;prompt&#34;]
prompt_pat = re.compile(prompt.encode(&#34;utf-8&#34;), re.DOTALL)
expects = [prompt_pat, pexpect.EOF, pexpect.TIMEOUT]
output = &#39;&#39;
result = 0
if not isinstance(commands, list):
commands = [commands]
if isinstance(self.tags, dict) and &#34;screen_length_command&#34; in self.tags:
commands.insert(0, self.tags[&#34;screen_length_command&#34;])
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&#34;Error: Variable {e} not defined in task or inventory&#34;
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 &#34;screen_length_command&#34; 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(&#34;Fallback setwinsize failed in run: %s&#34;, 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(&#34;utf-8&#34;, errors=&#34;replace&#34;), True)
if logger:
logger(&#34;output&#34;, output)
if folder != &#39;&#39;:
with open(folder + &#34;/&#34; + self.unique + &#34;_&#34; + now + &#34;.txt&#34;, &#34;w&#34;) 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(&#34;error&#34;, f&#34;Connection failed: {connect}&#34;)
if folder != &#39;&#39;:
with open(folder + &#34;/&#34; + self.unique + &#34;_&#34; + now + &#34;.txt&#34;, &#34;w&#34;) as f:
f.write(connect)
return connect</code></pre>
</details>
<div class="desc"><p>Run a command or list of commands on the node and return the output.</p>
<h3 id="parameters">Parameters:</h3>
<pre><code>- 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.
</code></pre>
<h3 id="optional-parameters">Optional Parameters:</h3>
<pre><code>- vars (dict): Dictionary containing the definition of variables
used in commands parameter.
Keys: Variable names.
Values: strings.
</code></pre>
<h3 id="optional-named-parameters">Optional Named Parameters:</h3>
<pre><code>- 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 "&gt;" or EOF while
routers use "&gt;" 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.
</code></pre>
<h3 id="returns">Returns:</h3>
<pre><code>str: Output of the commands you ran on the node.
</code></pre></div>
</dd>
<dt id="connpy.node.test"><code class="name flex">
<span>def <span class="ident">test</span></span>(<span>self,<br>commands,<br>expected,<br>vars=None,<br>*,<br>folder='',<br>prompt=&#x27;&gt;$|#$|\\$$|&gt;.$|#.$|\\$.$&#x27;,<br>timeout=None,<br>logger=None,<br>connect_timeout=None,<br>auth_timeout=None,<br>unattended=True,<br>attempt_tracker=None)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@MethodHook
def test(
self,
commands,
expected,
vars=None,
*,
folder=&#39;&#39;,
prompt=r&#39;&gt;$|#$|\$$|&gt;.$|#.$|\$.$&#39;,
timeout=None,
logger=None,
connect_timeout=None,
auth_timeout=None,
_default_cmd_timeout=10,
unattended=True,
attempt_tracker=None,
):
&#39;&#39;&#39;
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 &#34;&gt;&#34; or EOF while
routers use &#34;&gt;&#34; or &#34;#&#34;. 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.
&#39;&#39;&#39;
now = datetime.datetime.now().strftime(&#34;%Y-%m-%d_%H-%M-%S&#34;)
force_ssh = self.protocol == &#34;mosh&#34;
effective_protocol = &#34;ssh&#34; if force_ssh else self.protocol
try:
_, _, eff_cmd, _, _ = resolve_timeouts(
effective_protocol,
self.tags,
getattr(self, &#34;_hop_chain_meta&#34;, None) or [],
timeout=timeout,
connect_timeout=connect_timeout,
auth_timeout=auth_timeout,
_default_cmd_timeout=_default_cmd_timeout,
)
except ValueError as e:
err = f&#34;Connection failed code: 12\nInvalid timeout configuration: {e}&#34;
self.result = None
self.output = err
self.status = 1
if logger:
logger(&#34;error&#34;, f&#34;Connection failed: {err}&#34;)
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&#34;:{self.port}&#34; if self.port and effective_protocol not in [&#34;ssm&#34;, &#34;kubectl&#34;, &#34;docker&#34;] else &#34;&#34;
logger(&#34;success&#34;, f&#34;Connected to {self.unique} at {self.host}{port_str} via: {effective_protocol}&#34;)
if isinstance(self.tags, dict) and &#34;prompt&#34; in self.tags:
prompt = self.tags[&#34;prompt&#34;]
prompt_pat = re.compile(prompt.encode(&#34;utf-8&#34;), re.DOTALL)
expects = [prompt_pat, pexpect.EOF, pexpect.TIMEOUT]
output = &#39;&#39;
result = 0
if not isinstance(commands, list):
commands = [commands]
if not isinstance(expected, list):
expected = [expected]
if isinstance(self.tags, dict) and &#34;screen_length_command&#34; in self.tags:
commands.insert(0, self.tags[&#34;screen_length_command&#34;])
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&#34;Error: Variable {e} not defined in task or inventory&#34;
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 &#34;screen_length_command&#34; 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(&#34;Fallback setwinsize failed in test: %s&#34;, 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(&#34;utf-8&#34;, errors=&#34;replace&#34;), True)
if logger:
logger(&#34;output&#34;, output)
if folder != &#39;&#39;:
with open(folder + &#34;/&#34; + self.unique + &#34;_&#34; + now + &#34;.txt&#34;, &#34;w&#34;) 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&#39;(?&lt;!\\)\$&#39;, &#39;&#39;, prompt)
cleaned_output = output
try:
newpattern = f&#34;.*({updatedprompt}).*{e}.*&#34;
cleaned_output = re.sub(newpattern, &#39;&#39;, cleaned_output)
except re.error:
try:
escaped_e = re.escape(e)
newpattern = f&#34;.*({updatedprompt}).*{escaped_e}.*&#34;
cleaned_output = re.sub(newpattern, &#39;&#39;, 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</code></pre>
</details>
<div class="desc"><p>Run a command or list of commands on the node, then check if expected value appears on the output after the last command.</p>
<h3 id="parameters">Parameters:</h3>
<pre><code>- 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.
</code></pre>
<h3 id="optional-parameters">Optional Parameters:</h3>
<pre><code>- vars (dict): Dictionary containing the definition of variables
used in commands and expected parameters.
Keys: Variable names.
Values: strings.
</code></pre>
<h3 id="optional-named-parameters">Optional Named Parameters:</h3>
<pre><code>- 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 "&gt;" or EOF while
routers use "&gt;" 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.
</code></pre>
<h3 id="returns">Returns:</h3>
<pre><code>bool: true if expected value is found after running the commands
false if prompt is found before.
</code></pre></div>
</dd>
</dl>
</dd>
<dt id="connpy.nodes"><code class="flex name class">
<span>class <span class="ident">nodes</span></span>
<span>(</span><span>nodes: dict, config='')</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@ClassHook
class nodes:
&#39;&#39;&#39; 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.
- &lt;unique&gt; (obj): For each item in nodelist, there is an attribute
generated with the node unique.
&#39;&#39;&#39;
def __init__(self, nodes: dict, config = &#39;&#39;):
&#39;&#39;&#39;
### 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.
&#39;&#39;&#39;
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,
):
&#39;&#39;&#39;
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 &#34;&gt;&#34; or EOF while routers
use &#34;&gt;&#34; or &#34;#&#34;. 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&#39;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.
&#39;&#39;&#39;
args = {}
nodesargs = {}
args[&#34;commands&#34;] = commands
if folder is not None:
args[&#34;folder&#34;] = folder
Path(folder).mkdir(parents=True, exist_ok=True)
if prompt is not None:
args[&#34;prompt&#34;] = prompt
if stdout is not None and on_complete is None:
args[&#34;stdout&#34;] = stdout
if timeout is not None:
args[&#34;timeout&#34;] = timeout
if connect_timeout is not None:
args[&#34;connect_timeout&#34;] = connect_timeout
if auth_timeout is not None:
args[&#34;auth_timeout&#34;] = auth_timeout
if _default_cmd_timeout != 10:
args[&#34;_default_cmd_timeout&#34;] = _default_cmd_timeout
if unattended is not True:
args[&#34;unattended&#34;] = unattended
output = {}
status = {}
fallback_used = {}
tasks = []
def _run_node(node_obj, node_args, callback):
&#34;&#34;&#34;Wrapper that runs a node and fires the callback on completion.&#34;&#34;&#34;
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][&#34;attempt_tracker&#34;] = attempt_tracker
if vars is not None:
nodesargs[n.unique][&#34;vars&#34;] = {}
if &#34;__global__&#34; in vars:
nodesargs[n.unique][&#34;vars&#34;].update(vars[&#34;__global__&#34;])
for var_key, var_val in vars.items():
if var_key == &#34;__global__&#34;:
continue
try:
if re.search(var_key, n.unique, re.IGNORECASE):
nodesargs[n.unique][&#34;vars&#34;].update(var_val)
except re.error:
if var_key == n.unique:
nodesargs[n.unique][&#34;vars&#34;].update(var_val)
# Pass the logger to the node
nodesargs[n.unique][&#34;logger&#34;] = 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, &#34;last_fallback_used&#34;, 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,
):
&#39;&#39;&#39;
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 &#34;&gt;&#34; or EOF while
routers use &#34;&gt;&#34; or &#34;#&#34;. 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&#39;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.
&#39;&#39;&#39;
args = {}
nodesargs = {}
args[&#34;commands&#34;] = commands
args[&#34;expected&#34;] = expected
if folder is not None:
args[&#34;folder&#34;] = folder
Path(folder).mkdir(parents=True, exist_ok=True)
if prompt is not None:
args[&#34;prompt&#34;] = prompt
if timeout is not None:
args[&#34;timeout&#34;] = timeout
if connect_timeout is not None:
args[&#34;connect_timeout&#34;] = connect_timeout
if auth_timeout is not None:
args[&#34;auth_timeout&#34;] = auth_timeout
if _default_cmd_timeout != 10:
args[&#34;_default_cmd_timeout&#34;] = _default_cmd_timeout
if unattended is not True:
args[&#34;unattended&#34;] = unattended
output = {}
result = {}
status = {}
fallback_used = {}
tasks = []
def _test_node(node_obj, node_args, callback):
&#34;&#34;&#34;Wrapper that runs a node test and fires the callback on completion.&#34;&#34;&#34;
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][&#34;attempt_tracker&#34;] = attempt_tracker
if vars is not None:
nodesargs[n.unique][&#34;vars&#34;] = {}
if &#34;__global__&#34; in vars:
nodesargs[n.unique][&#34;vars&#34;].update(vars[&#34;__global__&#34;])
for var_key, var_val in vars.items():
if var_key == &#34;__global__&#34;:
continue
try:
if re.search(var_key, n.unique, re.IGNORECASE):
nodesargs[n.unique][&#34;vars&#34;].update(var_val)
except re.error:
if var_key == n.unique:
nodesargs[n.unique][&#34;vars&#34;].update(var_val)
nodesargs[n.unique][&#34;logger&#34;] = 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, &#34;last_fallback_used&#34;, False))
self.output = output
self.result = result
self.status = status
self.fallback_used = fallback_used
return result</code></pre>
</details>
<div class="desc"><p>This class generates a nodes object. Contains a list of node class objects and methods to run multiple tasks on nodes simultaneously.</p>
<h3 id="attributes">Attributes:</h3>
<pre><code>- 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.
- &lt;unique&gt; (obj): For each item in nodelist, there is an attribute
generated with the node unique.
</code></pre>
<h3 id="parameters">Parameters:</h3>
<pre><code>- 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.
</code></pre>
<h3 id="optional-parameters">Optional Parameters:</h3>
<pre><code>- config (obj): Pass the object created with class configfile with key
for decryption and extra configuration if you are using
connection manager.
</code></pre></div>
<h3>Methods</h3>
<dl>
<dt id="connpy.nodes.run"><code class="name flex">
<span>def <span class="ident">run</span></span>(<span>self,<br>commands,<br>vars=None,<br>*,<br>folder=None,<br>prompt=None,<br>stdout=None,<br>parallel=10,<br>timeout=None,<br>on_complete=None,<br>logger=None,<br>connect_timeout=None,<br>auth_timeout=None,<br>unattended=True,<br>attempt_tracker=None)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@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,
):
&#39;&#39;&#39;
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 &#34;&gt;&#34; or EOF while routers
use &#34;&gt;&#34; or &#34;#&#34;. 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&#39;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.
&#39;&#39;&#39;
args = {}
nodesargs = {}
args[&#34;commands&#34;] = commands
if folder is not None:
args[&#34;folder&#34;] = folder
Path(folder).mkdir(parents=True, exist_ok=True)
if prompt is not None:
args[&#34;prompt&#34;] = prompt
if stdout is not None and on_complete is None:
args[&#34;stdout&#34;] = stdout
if timeout is not None:
args[&#34;timeout&#34;] = timeout
if connect_timeout is not None:
args[&#34;connect_timeout&#34;] = connect_timeout
if auth_timeout is not None:
args[&#34;auth_timeout&#34;] = auth_timeout
if _default_cmd_timeout != 10:
args[&#34;_default_cmd_timeout&#34;] = _default_cmd_timeout
if unattended is not True:
args[&#34;unattended&#34;] = unattended
output = {}
status = {}
fallback_used = {}
tasks = []
def _run_node(node_obj, node_args, callback):
&#34;&#34;&#34;Wrapper that runs a node and fires the callback on completion.&#34;&#34;&#34;
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][&#34;attempt_tracker&#34;] = attempt_tracker
if vars is not None:
nodesargs[n.unique][&#34;vars&#34;] = {}
if &#34;__global__&#34; in vars:
nodesargs[n.unique][&#34;vars&#34;].update(vars[&#34;__global__&#34;])
for var_key, var_val in vars.items():
if var_key == &#34;__global__&#34;:
continue
try:
if re.search(var_key, n.unique, re.IGNORECASE):
nodesargs[n.unique][&#34;vars&#34;].update(var_val)
except re.error:
if var_key == n.unique:
nodesargs[n.unique][&#34;vars&#34;].update(var_val)
# Pass the logger to the node
nodesargs[n.unique][&#34;logger&#34;] = 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, &#34;last_fallback_used&#34;, False))
self.output = output
self.status = status
self.fallback_used = fallback_used
return output</code></pre>
</details>
<div class="desc"><p>Run a command or list of commands on all the nodes in nodelist.</p>
<h3 id="parameters">Parameters:</h3>
<pre><code>- 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.
</code></pre>
<h3 id="optional-parameters">Optional Parameters:</h3>
<pre><code>- 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.
</code></pre>
<h3 id="optional-named-parameters">Optional Named Parameters:</h3>
<pre><code>- 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 "&gt;" or EOF while routers
use "&gt;" 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.
</code></pre>
<h3 id="returns">Returns:</h3>
<pre><code>dict: Dictionary formed by nodes unique as keys, Output of the
commands you ran on the node as value.
</code></pre></div>
</dd>
<dt id="connpy.nodes.test"><code class="name flex">
<span>def <span class="ident">test</span></span>(<span>self,<br>commands,<br>expected,<br>vars=None,<br>*,<br>folder=None,<br>prompt=None,<br>parallel=10,<br>timeout=None,<br>on_complete=None,<br>logger=None,<br>connect_timeout=None,<br>auth_timeout=None,<br>unattended=True,<br>attempt_tracker=None)</span>
</code></dt>
<dd>
<details class="source">
<summary>
<span>Expand source code</span>
</summary>
<pre><code class="python">@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,
):
&#39;&#39;&#39;
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 &#34;&gt;&#34; or EOF while
routers use &#34;&gt;&#34; or &#34;#&#34;. 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&#39;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.
&#39;&#39;&#39;
args = {}
nodesargs = {}
args[&#34;commands&#34;] = commands
args[&#34;expected&#34;] = expected
if folder is not None:
args[&#34;folder&#34;] = folder
Path(folder).mkdir(parents=True, exist_ok=True)
if prompt is not None:
args[&#34;prompt&#34;] = prompt
if timeout is not None:
args[&#34;timeout&#34;] = timeout
if connect_timeout is not None:
args[&#34;connect_timeout&#34;] = connect_timeout
if auth_timeout is not None:
args[&#34;auth_timeout&#34;] = auth_timeout
if _default_cmd_timeout != 10:
args[&#34;_default_cmd_timeout&#34;] = _default_cmd_timeout
if unattended is not True:
args[&#34;unattended&#34;] = unattended
output = {}
result = {}
status = {}
fallback_used = {}
tasks = []
def _test_node(node_obj, node_args, callback):
&#34;&#34;&#34;Wrapper that runs a node test and fires the callback on completion.&#34;&#34;&#34;
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][&#34;attempt_tracker&#34;] = attempt_tracker
if vars is not None:
nodesargs[n.unique][&#34;vars&#34;] = {}
if &#34;__global__&#34; in vars:
nodesargs[n.unique][&#34;vars&#34;].update(vars[&#34;__global__&#34;])
for var_key, var_val in vars.items():
if var_key == &#34;__global__&#34;:
continue
try:
if re.search(var_key, n.unique, re.IGNORECASE):
nodesargs[n.unique][&#34;vars&#34;].update(var_val)
except re.error:
if var_key == n.unique:
nodesargs[n.unique][&#34;vars&#34;].update(var_val)
nodesargs[n.unique][&#34;logger&#34;] = 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, &#34;last_fallback_used&#34;, False))
self.output = output
self.result = result
self.status = status
self.fallback_used = fallback_used
return result</code></pre>
</details>
<div class="desc"><p>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.</p>
<h3 id="parameters">Parameters:</h3>
<pre><code>- 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.
</code></pre>
<h3 id="optional-parameters">Optional Parameters:</h3>
<pre><code>- 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.
</code></pre>
<h3 id="optional-named-parameters">Optional Named Parameters:</h3>
<pre><code>- prompt (str): Prompt to be expected after a command is finished
running. Usually linux uses "&gt;" or EOF while
routers use "&gt;" 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.
</code></pre>
<h3 id="returns">Returns:</h3>
<pre><code>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.
</code></pre></div>
</dd>
</dl>
</dd>
</dl>
</section>
</article>
<nav id="sidebar">
<div class="toc">
<ul>
<li><a href="#connpy-v650b1">Connpy (v6.5.0b1)</a><ul>
<li><a href="#1-ai-system">1. 🤖 AI System</a><ul>
<li><a href="#1a-terminal-copilot-ctrlspace">1a. Terminal Copilot (Ctrl+Space)</a></li>
<li><a href="#1b-ai-chat-conn-ai">1b. AI Chat (conn ai)</a></li>
<li><a href="#1c-mcp-integration-client-server">1c. MCP Integration (Client &amp; Server)</a></li>
<li><a href="#1d-local-interactive-shell-conn-shell">1d. Local Interactive Shell (conn shell)</a></li>
</ul>
</li>
<li><a href="#2-automation-playbooks">2. ⚙️ Automation &amp; Playbooks</a><ul>
<li><a href="#2a-quick-run-conn-run">2a. Quick Run (conn run)</a></li>
<li><a href="#2b-yaml-playbook-engine">2b. YAML Playbook Engine</a></li>
<li><a href="#2c-ai-assisted-automation">2c. AI-Assisted Automation</a></li>
</ul>
</li>
<li><a href="#3-inventory-management">3. 📂 Inventory Management</a><ul>
<li><a href="#3a-nodes">3a. Nodes</a></li>
<li><a href="#3b-profiles">3b. Profiles</a></li>
<li><a href="#3c-folders-move-copy-list">3c. Folders, Move, Copy, List</a></li>
<li><a href="#3d-bulk-export-import">3d. Bulk, Export, Import</a></li>
<li><a href="#3e-tags-system">3e. Tags System</a></li>
<li><a href="#3f-credential-fallback-chain-compose-auth-budgets">3f. Credential Fallback Chain, compose: &amp; Auth Budgets</a></li>
</ul>
</li>
<li><a href="#4-protocols-connection-features">4. 🔌 Protocols &amp; Connection Features</a><ul>
<li><a href="#4a-ssh-sftp-mosh-telnet-kubectl-docker-aws-ssm">4a. SSH / SFTP / Mosh / Telnet / kubectl / Docker / AWS SSM</a></li>
<li><a href="#4b-jumphosts">4b. Jumphosts</a></li>
<li><a href="#4c-debug-mode-keepalive-logging">4c. Debug Mode, Keepalive, Logging</a></li>
<li><a href="#4d-adaptive-multi-hop-timeouts">4d. Adaptive Multi-Hop Timeouts</a></li>
</ul>
</li>
<li><a href="#5-remote-capture-conn-capture-core-plugin">5. 🖥️ Remote Capture (conn capture - Core Plugin)</a></li>
<li><a href="#6-context-filtering">6. 🛡️ Context Filtering</a></li>
<li><a href="#7-plugin-system">7. 🔌 Plugin System</a></li>
<li><a href="#8-grpc-client-server-architecture">8. ⚙️ gRPC Client-Server Architecture</a><ul>
<li><a href="#8a-server-startstoprestartdebug">8a. Server (start/stop/restart/debug)</a></li>
<li><a href="#8b-client-config">8b. Client Config</a></li>
<li><a href="#8c-user-management-api-tokens">8c. User Management &amp; API Tokens</a></li>
<li><a href="#8d-sso-oidc">8d. SSO / OIDC</a></li>
<li><a href="#8e-login-logout">8e. Login / Logout</a></li>
</ul>
</li>
<li><a href="#9-installation-configuration">9. ⚡ Installation &amp; Configuration</a><ul>
<li><a href="#9a-pip-install">9a. pip install</a></li>
<li><a href="#9b-shell-completion-fzf">9b. Shell Completion + FZF</a></li>
<li><a href="#9c-conn-config-options">9c. conn config options</a></li>
<li><a href="#9d-theming">9d. Theming</a></li>
</ul>
</li>
<li><a href="#10-privacy-security-synchronization-conn-sync">10. 🔒 Privacy, Security &amp; Synchronization (conn sync)</a></li>
<li><a href="#11-python-api">11. 🐍 Python API</a></li>
<li><a href="#12-docker-deployment">12. 🐳 Docker Deployment</a></li>
<li><a href="#13-license">13. 📜 License</a></li>
</ul>
</li>
</ul>
</div>
<ul id="index">
<li><h3><a href="#header-submodules">Sub-modules</a></h3>
<ul>
<li><code><a title="connpy.ai" href="ai.html">connpy.ai</a></code></li>
<li><code><a title="connpy.auth_utils" href="auth_utils.html">connpy.auth_utils</a></code></li>
<li><code><a title="connpy.cli" href="cli/index.html">connpy.cli</a></code></li>
<li><code><a title="connpy.grpc_layer" href="grpc_layer/index.html">connpy.grpc_layer</a></code></li>
<li><code><a title="connpy.mcp_client" href="mcp_client.html">connpy.mcp_client</a></code></li>
<li><code><a title="connpy.mcp_server" href="mcp_server.html">connpy.mcp_server</a></code></li>
<li><code><a title="connpy.proto" href="proto/index.html">connpy.proto</a></code></li>
<li><code><a title="connpy.services" href="services/index.html">connpy.services</a></code></li>
<li><code><a title="connpy.tunnels" href="tunnels.html">connpy.tunnels</a></code></li>
<li><code><a title="connpy.utils" href="utils.html">connpy.utils</a></code></li>
</ul>
</li>
<li><h3><a href="#header-classes">Classes</a></h3>
<ul>
<li>
<h4><code><a title="connpy.Plugins" href="#connpy.Plugins">Plugins</a></code></h4>
<ul class="">
<li><code><a title="connpy.Plugins.verify_script" href="#connpy.Plugins.verify_script">verify_script</a></code></li>
</ul>
</li>
<li>
<h4><code><a title="connpy.configfile" href="#connpy.configfile">configfile</a></code></h4>
<ul class="">
<li><code><a title="connpy.configfile.encrypt" href="#connpy.configfile.encrypt">encrypt</a></code></li>
<li><code><a title="connpy.configfile.get_effective_setting" href="#connpy.configfile.get_effective_setting">get_effective_setting</a></code></li>
<li><code><a title="connpy.configfile.getitem" href="#connpy.configfile.getitem">getitem</a></code></li>
<li><code><a title="connpy.configfile.getitem_unlocked" href="#connpy.configfile.getitem_unlocked">getitem_unlocked</a></code></li>
<li><code><a title="connpy.configfile.getitems" href="#connpy.configfile.getitems">getitems</a></code></li>
<li><code><a title="connpy.configfile.privatekey" href="#connpy.configfile.privatekey">privatekey</a></code></li>
<li><code><a title="connpy.configfile.publickey" href="#connpy.configfile.publickey">publickey</a></code></li>
<li><code><a title="connpy.configfile.refresh_cache" href="#connpy.configfile.refresh_cache">refresh_cache</a></code></li>
<li><code><a title="connpy.configfile.transactional_update" href="#connpy.configfile.transactional_update">transactional_update</a></code></li>
</ul>
</li>
<li>
<h4><code><a title="connpy.node" href="#connpy.node">node</a></code></h4>
<ul class="">
<li><code><a title="connpy.node.inject_commands" href="#connpy.node.inject_commands">inject_commands</a></code></li>
<li><code><a title="connpy.node.interact" href="#connpy.node.interact">interact</a></code></li>
<li><code><a title="connpy.node.run" href="#connpy.node.run">run</a></code></li>
<li><code><a title="connpy.node.test" href="#connpy.node.test">test</a></code></li>
</ul>
</li>
<li>
<h4><code><a title="connpy.nodes" href="#connpy.nodes">nodes</a></code></h4>
<ul class="">
<li><code><a title="connpy.nodes.run" href="#connpy.nodes.run">run</a></code></li>
<li><code><a title="connpy.nodes.test" href="#connpy.nodes.test">test</a></code></li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
</main>
<footer id="footer">
<p>Generated by <a href="https://pdoc3.github.io/pdoc" title="pdoc: Python API documentation generator"><cite>pdoc</cite> 0.11.6</a>.</p>
</footer>
</body>
</html>