Alma Linux Remote Plugin

Use this project to manage remote Linux hosts from Alma with safety controls.

Capabilities

• SSH connection test
• Single/batch command execution
  • Primary tools: run_command, run_batch
  • Compatibility aliases: execute_command, execute_batch
• Upload/download files via SFTP
• Service status and journal logs
• Dangerous command protection:
  • Manual approval workflow (approval_id)
  • Operator RBAC allowlist (approval.allowed_operators)
  • Optional one-time confirmation token mode
• Command policy hardening:
  • policy.strict_policy=false (compatible mode)
  • policy.strict_policy=true (normalized/token-level matching)
• Host key verification policy (ssh.host_key_policy):
  • known_hosts (RejectPolicy + optional known_hosts_required)
  • reject (strict reject unknown hosts)
  • auto_add (compatibility mode)
• Server profile docs:
  • First remote access auto-creates server_profiles/<IP>.md
  • Subsequent remote calls read this profile before connect
• Audit logging (JSONL) with SIEM-friendly fields and safety:
  • request_id / trace_id / operator_ip
  • Sensitive fields redacted (password/token/secret/key/passphrase)
  • stdout/stderr truncated for log safety
• Persistent SSH sessions (stateful shell):
  • open_session, list_sessions, close_session
  • run_command_in_session, write_session, read_session, resize_session
  • Session metadata persistence (session.storage_file)
• Real terminal bridge (xterm.js + WebSocket):
  • start_terminal_ws returns ws://.../terminal/<session_id>
  • stop_terminal_ws unregisters a session or stops the WS server
• Session key injection:
  • send_keys_to_session supports ESC/UP/DOWN/LEFT/RIGHT/TAB/ENTER
• Thread-session binding layer:
  • bind_thread_session, get_thread_session, unbind_thread_session
  • ensure_thread_session (auto-open and bind when missing)
• NL -> command bridge:
  • plan_command_from_text (plan only)
  • execute_text_in_session (plan + run in persistent session)

Install

git clone https://github.com/adfoke/alma-linux-remote-plugin.git
cd alma-linux-remote-plugin
uv sync --all-extras

Quick Start

uv run python demo_cli.py --config ./examples/hosts.example.yaml handle health
uv run python demo_cli.py --config ./examples/hosts.example.yaml tools
uv run python demo_cli.py --config ./examples/hosts.example.yaml handle execute_command '{"host_name":"prod-web-1","command":"uptime"}'
uv run python demo_cli.py --config ./examples/hosts.example.yaml handle open_session '{"host_name":"prod-web-1"}'
uv run python demo_cli.py --config ./examples/hosts.example.yaml handle list_sessions '{"status":"all"}'
uv run python demo_cli.py --config ./examples/hosts.example.yaml plan-text thread-a prod-web-1 "帮我看下磁盘和内存"
uv run python demo_cli.py --config ./examples/hosts.example.yaml exec-text thread-a prod-web-1 "查看 nginx 状态和最近日志"
uv run python demo_cli.py --config ./examples/hosts.example.yaml handle send_keys_to_session '{"session_id":"<SESSION_ID>","keys":["ESC",":wq","ENTER"]}'

English doc: README.en.md

Safety Workflow (dangerous command)

1. Run dangerous command → receive approval_required and approval_id
2. Approver calls approve_request with allowed operator
3. Re-run command with approval_id

Code Audit Notes

• plugin.py now uses _with_connected_client(...) to consolidate repeated connect/close patterns.
• Added focused tests for ssh_client.py and terminal_ws.py to keep critical path coverage high.

Quality Gate

uv run ruff check src tests demo_cli.py
uv run pytest --cov=src/alma_linux_remote_plugin --cov-report=term-missing --cov-fail-under=65

Main Entrypoint

• Runtime adapter: src/alma_linux_remote_plugin/runtime_adapter.py
• Plugin metadata: plugin.yaml