SSH Remote Execution

mop ssh is Mopheus's built-in, policy-governed remote execution and file transfer tool. It provides AI agents and engineers with a secure, auditable, and topology-aware remote operations channel.

In traditional incident management and operations workflows, agents running remote commands face critical security and management dilemmas:

• Credential leakage risk — Plaintext private keys or passwords embedded directly in task prompts or environment variables;
• Disconnection between assets and endpoints — When diagnosing an alert, agents struggle to locate which physical host actually runs a degraded microservice or database;
• Lack of auditability and blast-radius control — No mechanism prevents agents from arbitrarily attempting connections or executing destructive operations against unmanaged hosts.

Mopheus resolves these challenges through IT Asset Center (mop asset) and SSH Remote Executor (mop ssh). Each asset can have multiple named SSH accounts managed separately from ordinary asset manifests.

Zero-Trust Credential ArchitectureCopy Anchor Link

Mopheus SSH stores account metadata and encrypted authentication payloads per asset and username, separately from ordinary asset attributes.

┌───────────────────────────────────────────────────────────────────────────────────────────┐
│                                  Mopheus AI Agent / Task                                  │
└──────────┬───────────────────────────────────┬───────────────────────────────────┬────────┘
           │ 1. Topology causal discovery      │ 2. User key custody & injection   │ 3. Command execution & transfer
           ▼                                   ▼                                   ▼
┌─────────────────────┐             ┌─────────────────────┐             ┌─────────────────────┐
│ mop asset           │             │ mop user            │             │ mop ssh             │
│ (IT Asset Graph)    │             │ (config-file/key)   │             │ (Governed SSH)      │
├─────────────────────┤             ├─────────────────────┤             ├─────────────────────┤
│ • Logical/phys      │             │ • Ed25519/RSA       │             │ • Name/alias res    │
│ • Account metadata  │             │ • Encrypted secret  │             │ • User selection    │
│ • Topology drill    │             │ • Ephemeral inject  │             │ • exec / upload     │
└─────────────────────┘             └─────────────────────┘             └─────────────────────┘

1. Keep SSH credentials out of asset manifests. Use mop asset apply for asset data and a separate restricted-permission file for passwords or private keys.
2. Manage SSH accounts with mop asset credential add|update|list|import. A credential is identified by asset ID and username; optional connectHost, connectPort, jumpAssetId, and jumpUsername are stored with it.
3. Protect credential transport with application-layer X25519/HKDF/AES-GCM envelopes for writes and SSH connection reads. Secrets are decrypted only in the CLI/server/provider process and never by metadata list or status commands.

Declare credentials beside assets in the same manifest and link each account with assetId (set the file mode to 0600):

version: mopheus.io/v1alpha1
kind: AssetManifest
metadata:
  workspace: production
  environment: prod
assets:
  - id: host:db-node-01
    concept: Host
    name: Database node
    attributes:
      management_ip: 10.0.2.11
credentials:
  - assetId: host:db-node-01
    username: deploy
    authType: password
    connectPort: 22
    jumpAssetId: host:bastion-01
    jumpUsername: ops
    secret:
      password: replace-in-protected-file

Apply both with mop asset apply -f assets.yaml. Credentials can also be kept in a separate mode 0600 file passed with --credentials-file. Asset exports never include credentials.

Asset-Driven Target ResolutionCopy Anchor Link

When executing mop ssh, you do not need to manually construct IP addresses and port numbers. Mopheus supports multi-dimensional target resolution:

• Standard Asset ID: e.g., host:mopheus-prod-cn, host:db-node-01
• Asset Name: e.g., mopheus-prod-server
• Aliases: e.g., prod-node1, jumpbox-cn
• IP Address: e.g., 10.10.2.11

Logical Assets vs. Physical Hosting AssetsCopy Anchor Link

Mopheus strictly separates logical assets (such as Service, Database) from physical hosting assets (such as Host, Container):

• Logical assets do not possess physical SSH endpoints; use topology to find a host with a configured SSH account.
• Directing mop ssh at a logical asset triggers a helpful safety block advising the agent to drill down.
• Agents execute mop asset topology <logical-id> to discover downstream runs_on edges, identify the physical Host node running the service, and connect to that host.

Command ReferenceCopy Anchor Link

1. Inspect Authorized HostsCopy Anchor Link

List all assets in the current workspace configured with valid SSH credentials:

mop ssh list

Each configured username is listed as its own host row, 100 per page by default. Tables show the current page and total count; JSON includes page, page size, and total pages. Use --page and --per-page to navigate or change the page size. --search filters asset names, IDs, aliases, and connection addresses on the server. Use --user to select an account when an asset has multiple usernames.

Inspect account metadata without revealing a password or private key:

mop ssh credential get host:db-node-01 --user deploy

Review legacy SSH URI metadata before migration. The report omits URI passwords and raw references:

mop asset credential inventory --output json

2. Remote Command Execution (mop ssh exec)Copy Anchor Link

Execute non-interactive shell commands on the target host:

# Check remote host uptime and load average
mop ssh exec host:mopheus-prod-cn -- uptime

# Inspect disk space utilization
mop ssh exec host:mopheus-prod-cn -- df -h

# Check Docker container status
mop ssh exec host:mopheus-prod-cn -- docker ps

# Format output as JSON (for programmatic agent parsing)
mop ssh exec host:mopheus-prod-cn --json -- uname -a

# Set a execution timeout in seconds (prevents commands from hanging)
mop ssh exec host:mopheus-prod-cn --timeout 15 -- journalctl -u nginx -n 50

# Preview the final remote command without opening an SSH connection
mop ssh exec --dry-run host:mopheus-prod-cn -- printf '%s' 'hello world'

--dry-run prints the shell command sent by the transport without opening an SSH connection or executing it. With --script, it lists the upload target, execution command, and cleanup command without uploading the script.

SSH Command PolicyCopy Anchor Link

The workspace SSH command policy settings manage deny rules for mop ssh exec. Rules are organized into groups, with one rule per entry. Separate workspace permissions control rule creation, updates, and deletion. Policy tests parse commands or scripts without connecting to a host or executing the input.

Backend-owned rules appear in the System defaults tab. Their definitions cannot be edited or deleted, but workspace administrators can enable or disable each rule. Root recursive forced deletion and dd writes directly to /dev/ are enabled by default; filesystem formatting with mkfs, piping curl/wget downloads directly into a shell, and common shell fork bombs are disabled by default to avoid disrupting normal operations. Disabling the workspace policy switch affects user rules only; enabled system rules remain active.

The CLI can inspect the policy and groups, and test commands without opening an SSH connection:

mop ssh policy show --workspace production
mop ssh policy group list --workspace production
mop ssh policy test --command 'rm -rf /' --workspace production

3. Secure File Upload and Download (mop ssh upload / download)Copy Anchor Link

With ssh exec --script, provide the local script file. --remote-path selects the remote upload directory and defaults to /tmp; the root directory / is rejected. The uploaded file keeps the local basename. Explicit commands must include the resulting remote script path. If no command is specified, the CLI uses sh; it removes the remote script afterward:

mop ssh exec --script ./scripts/health_check.sh --remote-path /tmp host:mopheus-prod-cn
mop ssh exec --script ./scripts/collect.py --remote-path /tmp host:mopheus-prod-cn -- python3 -u /tmp/collect.py --output /tmp/report.json

Transfer diagnostic scripts or operational artifacts between the local sandbox and remote host via SFTP:

# Upload a local diagnostic script to the remote temporary directory
mop ssh upload host:mopheus-prod-cn ./scripts/health_check.sh /tmp/health_check.sh

# Download diagnostic dumps or generated logs to the local workspace
mop ssh download host:mopheus-prod-cn /tmp/diagnostic_report.json ./report.json

Agent Operational SOP and Safety GuardrailsCopy Anchor Link

Autonomous agents running diagnostics must strictly comply with the following safety guardrails:

1. Drill Down to Physical Hosts: For application-level alerts (e.g., db:settle-oracle-rac error), first query mop asset topology db:settle-oracle-rac to identify the host host:db-node-01 before invoking mop ssh.
2. Strict Fail-Fast on Auth Failure: If a key is missing or authentication is rejected (Permission Denied), immediately stop execution and report the missing key name to the user. Never attempt password guessing or recursive retries.
3. Prohibition of Credential Scraping: Scraping local disks for private keys (e.g. running find / -name "*id_rsa*", grep -r "BEGIN RSA") or launching brute-force attacks is strictly forbidden.
4. Least-Impact Execution: Prefer non-blocking, read-only diagnostic commands (such as tail -n 100, top -b -n 1).

Practical Incident ScenariosCopy Anchor Link

Scenario 1: Emergency Host Resource TriageCopy Anchor Link

# 1. Check CPU load
mop ssh exec host:app-node-01 -- uptime

# 2. Identify top 5 memory-consuming processes
mop ssh exec host:app-node-01 -- ps aux --sort=-%mem | head -n 6

# 3. Check root and log partition disk space
mop ssh exec host:app-node-01 -- df -h / /var/log

Scenario 2: Capturing Crash LogsCopy Anchor Link

# Inspect the last 50 error entries from systemd service
mop ssh exec host:app-node-01 -- journalctl -u mopheus-daemon -n 50 --no-pager

Scenario 3: Diagnostic Script DistributionCopy Anchor Link

# Deploy diagnostic tool and extract results
mop ssh upload host:app-node-01 ./collect_stats.py /tmp/collect_stats.py
mop ssh exec host:app-node-01 -- python3 /tmp/collect_stats.py --out /tmp/stats.json
mop ssh download host:app-node-01 /tmp/stats.json ./stats.json