Temporary SSH Access for AI Agent Support#

Defense-in-depth temporary SSH access for AI agents — combines certificate TTL, OS account expiration, command-restricted dispatch, and automated cleanup. Zero session artifacts survive — all agent accounts, keys, certificates, dispatch shells, and cleanup timers are destroyed on session end or TTL expiry. The CA private key is a persistent operator-side credential requiring separate protection (see Security Considerations).

Platform: Linux (requires standard user-management tools).

Prerequisites#

Scripts check for required tools at startup and report what is missing. Install them on common distributions:

Debian / Ubuntu:

bash

sudo apt-get update && sudo apt-get install -y openssh-client coreutils passwd at e2fsprogs procps

Alpine Linux:

bash

apk add openssh-keygen bash shadow coreutils util-linux procps at e2fsprogs

RHEL / CentOS / Fedora:

bash

sudo dnf install -y openssh-clients coreutils shadow-utils at e2fsprogs procps-ng

ToolPackage (Debian)Package (Alpine)Requiredssh-keygen``openssh-client``openssh-keygenYesuseradd / userdel``passwd``shadowYespasswd``passwd``shadowYespkill``procps``procpsYesgetent``libc-bin``musl-utilsYesat``at``atOne of at or systemd-run``shred``coreutils``coreutilsOptional (falls back to rm)chattr``e2fsprogs``e2fsprogsOptional (for immutable authorized_keys)

If a required tool is missing, the script exits with an error listing missing dependencies. Optional tools produce warnings but do not block execution.

Target Host Requirements#

The target server (the machine the agent will SSH into) must have:

• sshd running and reachable on port 22 (or a configured port)
• ~/.ssh/ directory for the user whose authorized_keys will receive the agent's public key (the agent's one-liner creates this if missing)
• For CA-based access: TrustedUserCAKeys configured in /etc/ssh/sshd_config pointing to the CA public key

If the target is a fresh container or VM, install and start sshd first:

bash

# Alpine
apk add openssh && ssh-keygen -A && rc-service sshd start

# Debian/Ubuntu
apt-get install -y openssh-server && systemctl start sshd

When to Use#

• An AI agent needs temporary shell access to diagnose or remediate a remote server
• You require auditable, time-boxed access that self-revokes
• You need to restrict what the agent can execute — no arbitrary commands
• You want zero persistent credentials once the session ends

Agent-Initiated Access Flow (Recommended)#

When an AI agent determines it needs shell access, it briefly states its intent: "I need shell access to [target] to [reason]. I'll generate a temporary key — you decide where it goes. What username should I connect as?" Then:

1. Verify target is reachable — nc -z -w 2 TARGET 22 (or equivalent). If the port is closed, stop and inform the user: "Port 22 is not open on [target]. Please start sshd, then I'll continue."

2. Check for existing session — look for stale keys in /tmp/agent_access_key*. If found, test connectivity ( ssh -i /tmp/agent_access_key ... 'echo ok'). If the key still works, skip to step 7. If expired or revoked, shred stale keys and continue.

3. Generate keypair locally — Ed25519, stored in /tmp/ with a session-tagged comment.

4. Ask for the connect username — default to the current user on the target, not root. Ask: "What username should I connect as? (default: your current user)". If the task requires root, inform the user: "This task requires root. Please add the key to root's authorized_keys (or use sudo)."

5. Present public key with expiry — provide a one-liner with expiry-time for crash safety. The one-liner creates ~/.ssh/ if absent and is tailored to the target username: text

   mkdir -p ~/.ssh && chmod 700 ~/.ssh && echo 'expiry-time="YYYYMMDDHHMMSS" ssh-ed25519 AAAA... agent-session-SID' >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys
   
   

   expiry-time (OpenSSH 8.2+) ensures the key is server-rejected after the timestamp, even if the agent crashes and never cleans up.

   Important: The one-liner must run as the target user so ~/.ssh/ resolves to the correct home directory. If adding the key for a different account (e.g., root), either su - root first or use the absolute path (e.g., /root/.ssh/authorized_keys).

6. User adds the key — the user decides where and how to grant access (maintains control).

7. Verify connection — connect as the agreed username: ssh -i /tmp/agent_access_key USER@TARGET 'echo ok'

8. Schedule dead-man cleanup — immediately after connecting, schedule automatic key removal on the target: bash

   echo "sed -i '/agent-session-SID/d' ~/.ssh/authorized_keys" | at now + 4 hours
   
   

   This fires independently of the agent. If the agent finishes early, it cancels the job and cleans up itself.

9. Run fast recon — OS, key packages, screen/ tmux availability. Under 10 seconds.

10. Create shared session — start a screen or tmux session on the target so the user can attach and observe in real time.

11. Work — run diagnostics, remediation, or other tasks within the granted scope.

12. Clean up — remove the public key from authorized_keys, cancel the at job, destroy the local keypair.

Crash Safety (Simple Mode)#

Two independent mechanisms protect against agent crashes:

SafeguardFires without agent?Mechanismexpiry-time in authorized_keysYesServer-side — OpenSSH rejects the key after the timestampScheduled at jobYesRuns on target's scheduler — removes the key entry on timer

If the agent crashes and restarts, it reuses the stale keys from /tmp/ (step 2) rather than re-provisioning, avoiding repeated user interaction.

This flow requires no script transfer to the target and leaves no persistent artifacts. For stronger guarantees (certificate TTL, command restriction, scheduled cleanup), layer the CA-based workflow below on top.

Observability#

After establishing access, the agent should create a shared terminal session:

bash

# On the target — agent creates a named session
screen -dmS agent-work
screen -S agent-work -X multiuser on
screen -S agent-work -X acladd root

# User attaches to watch
screen -x agent-work

If screen is unavailable, tmux works similarly:

bash

tmux new-session -d -s agent-work
# User attaches:
tmux attach -t agent-work

The agent should check for screen/ tmux availability during initial recon and install if needed (with user permission).

Architecture: Defense in Depth#

Four independent expiration and restriction mechanisms ensure no single failure leaves access open:

LayerMechanismWhat It Does1SSH Certificate TTLCryptographically enforced expiry ( -V +Nh) — server rejects expired certs2OS Account Expirationuseradd --expiredate — login denied after date3Forced Command / Safe DispatchExact command-name matching, path-restricted arguments, no eval4Scheduled Cleanupat or systemd-run timer — removes account, keys, and config after TTL

Quick Start#

All scripts run on the operator's machine (the admin/signing host), not on the target server. Only public artifacts (CA public key, dispatch shell, agent account) are deployed to the target.

bash

# 1. One-time: Initialize the SSH Certificate Authority (run on admin/signing host)
sudo bash scripts/setup-ca.sh

# 2a. Preview what would happen (no changes made):
sudo bash scripts/grant-access.sh --host TARGET_HOST --duration 4h --agent-pubkey /path/to/agent_key.pub --dry-run

# 2b. Grant access using the agent's existing public key (recommended):
sudo bash scripts/grant-access.sh --host TARGET_HOST --duration 4h --agent-pubkey /path/to/agent_key.pub

# 2c. Or generate a keypair (you must securely deliver the private key to the agent):
sudo bash scripts/grant-access.sh --host TARGET_HOST --duration 4h --allow diagnostic

# 3. Revoke access: Immediately revoke before TTL expires (if needed)
sudo bash scripts/revoke-access.sh --session SESSION_ID

# 4. Audit: Scan for orphaned artifacts from previous sessions
sudo bash scripts/audit.sh

Detailed Workflow#

Phase 1: Certificate Authority Setup (One-Time)#

Run scripts/setup-ca.sh once on the signing host (your admin machine, not the target server).

This script:

1. Generates an Ed25519 CA key pair at /etc/ssh/agent_ca (private) and /etc/ssh/agent_ca.pub (public)
2. Sets strict permissions ( chmod 400) on the private key
3. Outputs the public key for distribution to target servers

On each target server, add to /etc/ssh/sshd_config:

text

TrustedUserCAKeys /etc/ssh/agent_ca.pub

Then restart sshd to trust certificates signed by your CA.

Phase 2: Granting Access#

Run scripts/grant-access.sh to provision a temporary session:

Step 2a: Create Ephemeral Agent Account

bash

# Create account with OS-level expiration (Layer 2)
# Account suffix uses 4 bytes of entropy (8 hex chars) with collision check
sudo useradd \
  --expiredate "$(date -d '+5 hours' +%Y-%m-%d)" \
  --shell /bin/bash \
  --create-home \
  --comment "AI Agent Support [SESSION_ID]" \
  agent_support_XXXXXXXX

• Account name includes a random 8-hex-char suffix with collision detection
• --expiredate sets an OS-level hard cutoff (rounded to midnight — a safety net, not the primary TTL)
• Home directory resolved via getent passwd (no eval)

Step 2b: Key Material

Recommended: Agent provides its own public key ( --agent-pubkey)

The agent retains its private key — no secret transfer required. The script signs the agent's public key with the CA (or installs it in authorized_keys).

bash

sudo bash scripts/grant-access.sh --host TARGET --duration 4h --agent-pubkey /path/to/agent.pub

Alternative: Script generates a keypair

If --agent-pubkey is omitted, the script generates an ephemeral Ed25519 keypair in /tmp/. The operator must then securely deliver the private key to the agent.

bash

ssh-keygen -t ed25519 -N "" -f /tmp/agent_session_XXXX -C "agent-support-SESSION_ID"

• Empty passphrase ( -N "") — the AI agent cannot enter passphrases interactively
• Keypair persists in /tmp/ until cleanup (securely deleted with shred -u)

Step 2c: Sign Certificate with TTL (Layer 1)

bash

# Sign the public key with the CA, enforcing time limit
ssh-keygen -s /etc/ssh/agent_ca \
  -I "agent-support-SESSION_ID" \
  -n agent_support_XXXXXXXX \
  -V +4h \
  -O no-port-forwarding \
  -O no-x11-forwarding \
  -O no-agent-forwarding \
  -O no-pty \
  -O force-command=/usr/local/bin/agent-support-shell-SESSION_ID \
  /path/to/agent.pub

Certificate options explained:

• -s /etc/ssh/agent_ca — sign with the CA private key
• -I "agent-support-SESSION_ID" — identity string for audit logs
• -n agent_support_XXXXXXXX — principal must match the account name
• -V +4h — certificate valid for exactly 4 hours (cryptographic enforcement)
• -O no-port-forwarding — prevent SSH tunneling
• -O no-x11-forwarding — no GUI forwarding
• -O no-agent-forwarding — no agent key forwarding
• -O no-pty — omit if the agent needs an interactive shell ( --with-pty)
• -O force-command=... — all commands routed through the safe dispatch shell

Step 2d: Command Restriction Shell (Layer 3)

Each session receives its own restriction shell at /usr/local/bin/agent-support-shell-SESSION_ID. The shell uses safe dispatch — no eval, no prefix matching:

1. Shell metacharacters blocked — ;, |, &, $, backticks, (), {}, <>, \ all rejected before parsing
2. Command parsed into name + arguments via read -ra
3. Command name matched exactly via case statement (not prefix matching)
4. Subcommands validated for multi-part commands ( systemctl status allowed, systemctl enable denied)
5. Path arguments validated against allowed directory prefixes
6. Commands executed directly as "$COMMAND" "${ARGS[@]}" with a 5-minute timeout
7. Absolute paths rejected as command names (prevents /sbin/shutdown)

For broader access profiles, use the --allow flag:

ProfileCommands PermitteddiagnosticRead-only: system info, logs (path-restricted to /var/log/, /proc/, /sys/, /run/, /tmp/), service status, network diagnostics, Docker inspectremediationDiagnostic + service restarts, process kills, file operations (path-restricted to /etc/, /var/, /tmp/), Docker management, curl/wgetfullUnrestricted (use with extreme caution — no restriction shell installed)

Step 2e: Schedule Automatic Cleanup (Layer 4)

bash

# Scheduled via at(1) or systemd-run with ceiling-rounded delay
echo "bash /usr/local/sbin/agent-cleanup-SESSION_ID.sh" | at now + 80 minutes

Each session receives its own cleanup script ( agent-cleanup-SESSION_ID.sh) to prevent concurrent-session collisions.

Phase 3: Agent Connects#

The AI agent uses the session credentials:

bash

# With agent-provided key:
ssh -i ~/.ssh/agent_key agent_support_XXXXXXXX@TARGET_HOST 'uptime'

# With generated key:
ssh -i /tmp/agent_session_XXXX agent_support_XXXXXXXX@TARGET_HOST 'df -h'

Phase 4: Access Revocation#

Access terminates automatically through multiple independent mechanisms and can also be revoked on demand.

Automatic Expiration

• Certificate TTL (Layer 1): Server rejects the cert after -V window. Server logs: error: Certificate invalid: expired
• Account expiration (Layer 2): OS denies login after --expiredate. Logs: User account has expired
• Scheduled cleanup (Layer 4): Removes account, keys, support shell, and cleanup script

Immediate Revocation

bash

sudo bash scripts/revoke-access.sh --session SESSION_ID
# or
sudo bash scripts/revoke-access.sh --user agent_support_XXXXXXXX
# or revoke all:
sudo bash scripts/revoke-access.sh --all

The revocation script:

1. Locks the account ( usermod -L)
2. Kills active SSH sessions for the user
3. Removes immutable-file protections ( chattr -i)
4. Archives session logs to /var/log/agent-support-archive/
5. Removes the account and home directory ( userdel -r)
6. Securely deletes session keys ( shred -u; falls back to rm -f)
7. Cancels scheduled cleanup timers and removes session-specific files

Phase 5: Audit#

All agent activity is logged to /var/log/agent-support.log with sanitized entries (via printf '%q' to prevent log injection):

text

[2026-03-15T16:00:00Z] SESSION_START: 20260315160000-a1b2c3d4 user=agent_support_e5f6g7h8 host=TARGET ttl=4h profile=diagnostic
[2026-03-15T16:00:05Z] AGENT_EXEC: uptime
[2026-03-15T16:00:10Z] AGENT_EXEC: df\ -h
[2026-03-15T16:00:15Z] AGENT_BLOCKED: rm\ -rf\ /
[2026-03-15T20:00:00Z] SESSION_END: 20260315160000-a1b2c3d4 reason=ttl_expired

Manual Approach (Without Scripts)#

Grant Access Manually#

bash

# 1. Create temporary account (expires tomorrow as safety net)
sudo useradd --expiredate "$(date -d '+1 day' +%Y-%m-%d)" \
  --shell /bin/bash --create-home agent_support

# 2. Accept the agent's public key (recommended) or generate a keypair
# Option A: Agent provides their pubkey
PUBKEY="/path/to/agent_pubkey.pub"
# Option B: Generate
ssh-keygen -t ed25519 -N "" -f /tmp/agent_key -C "agent-support"
PUBKEY="/tmp/agent_key.pub"

# 3. Sign with CA (4-hour window, restricted)
ssh-keygen -s /etc/ssh/agent_ca \
  -I "agent-manual-session" \
  -n agent_support \
  -V +4h \
  -O no-port-forwarding \
  -O no-x11-forwarding \
  -O no-agent-forwarding \
  "$PUBKEY"

# 4. Verify the certificate
ssh-keygen -L -f "${PUBKEY%.pub}-cert.pub"

# 5. Schedule cleanup
echo "userdel -r agent_support && shred -u /tmp/agent_key*" | at now + 5 hours

# 6. Deliver the certificate (and private key if generated) to the AI agent

Revoke Access Manually#

bash

# Lock the account immediately
sudo usermod -L agent_support

# Kill active sessions
sudo pkill -u agent_support

# Remove account and home directory
sudo userdel -r agent_support

# Destroy session keys
shred -u /tmp/agent_key /tmp/agent_key-cert.pub /tmp/agent_key.pub 2>/dev/null

# Remove scheduled cleanup
atq | grep agent && atrm JOB_NUMBER

Alternative: authorized_keys-Only Approach (No CA)#

For environments where a CA is not feasible:

bash

sudo bash scripts/grant-access.sh --host TARGET --duration 4h --no-ca --agent-pubkey /path/to/agent.pub

This installs the agent's public key in authorized_keys with the following restrictions:

text

expiry-time="YYYYMMDDHHMMSS",restrict,command="/usr/local/bin/agent-support-shell-SID" ssh-ed25519 AAAA...

• expiry-time — key rejected after this UTC timestamp
• restrict — disables port/agent/X11 forwarding and PTY allocation
• command="..." — forces all commands through the safe dispatch shell
• chattr +i makes the file immutable to prevent modification

Limitation: expiry-time is server-side only and lacks cryptographic enforcement. Always pair with chattr +i.

Security Considerations#

AI Agent-Specific Concerns#

1. No passphrase on session keys — mitigated by short-lived certificates (hours, not days), immediate key destruction, and immutable authorized_keys

2. Command injection — the dispatch shell blocks all shell metacharacters, matches command names exactly via case (not prefix), validates argument paths against directory allowlists, resolves symlinks before comparison, and rejects absolute paths as command names; commands execute directly without eval

3. Key delivery — use --agent-pubkey (recommended) so the private key never leaves the agent; if generating keys, the operator must deliver the private key securely

4. Scope creep — start with diagnostic; escalate to remediation or full only when explicitly needed

5. Symlink traversal — path validation resolves symlinks via readlink -f before checking directory prefixes; a symlink from /var/log/evil → /etc/shadow is resolved and rejected

Break-Glass Recovery#

If the agent loses access mid-session (certificate expired, context lost, network failure):

1. Console access — use hypervisor/cloud console (LXC lxc-attach, AWS SSM, GCP serial console) to regain access
2. Revoke stale sessions — run sudo bash scripts/revoke-access.sh --all to clean up orphaned accounts
3. Re-provision — run grant-access.sh again for a fresh session

Critical rule: never disable existing access paths (e.g., root SSH) before verifying the agent's own access works. Always keep at least one independent recovery path available.

General Hardening#

• Keep the CA private key on a separate, secured host — never on the target server
• Use Ed25519 keys for all operations
• Set MaxSessions 1 for the agent account in sshd_config
• Set MaxAuthTries 3 to limit brute-force attempts
• Set AuthenticationMethods publickey to restrict to key-based auth
• Enable LogLevel VERBOSE in sshd_config
• Monitor /var/log/auth.log and /var/log/agent-support.log during active sessions

Troubleshooting#

SymptomCauseFixCertificate invalid: expiredCertificate TTL elapsedRe-run grant-access.sh for a new sessionCertificate invalid: name is not a listed principalUsername mismatch between cert -n and accountEnsure -n matches the created account nameUser account has expiredOS-level --expiredate passedCreate a new account with later expiryPermission denied (publickey)CA public key not in TrustedUserCAKeysVerify server config and restart sshdWARNING: UNPROTECTED PRIVATE KEY FILEKey file permissions too openchmod 600 /tmp/agent_session_XXXX``Shell metacharacters are not allowedAgent sent ;, |, $, etc.Send simple commands without shell operatorsCommand not in allowlistAgent tried an unlisted commandUse a broader --allow profile or add the commandPath outside allowed directoriesAgent accessed a path outside allowed prefixesRestrict to /var/log/, /proc/, /sys/ (diagnostic) or add /etc/ (remediation)Missing required dependenciesLinux tools not installedInstall openssh-client, coreutils, at or systemd``Connection reset by peer (before auth)IP auto-blocked by brute-force protectionUnblock the IP (fail2ban, Synology autoblock, etc.), then retryKey added but auth failsAuthorizedKeysFile points elsewhereCheck sshd_config; Proxmox uses /etc/pve/priv/authorized_keys

Platform-Specific Notes#

Synology DSM — not fully compatible. DSM wraps sshd behind synorelayd, which intercepts SSH on port 22 and may silently block connections after repeated failures:

• Dual sshd instances: port 22 (via synorelayd) and port 222 (SFTP-only, pubkey)
• Home directories at /var/services/homes/USER/ (symlinked from /volume1/homes/USER/)
• DSM may reset sshd_config on service restart
• Default home directory permissions are 777 — SSH silently rejects pubkey auth; fix with chmod 755
• PubkeyAuthentication yes must be explicitly uncommented in sshd_config
• Connect as admin (not root) via the DSM-configured SSH port
• If connections reset, restart synorelayd: sudo /usr/syno/bin/synosystemctl restart synorelayd

Proxmox VE — may store authorized keys in /etc/pve/priv/authorized_keys instead of ~/.ssh/. Check AuthorizedKeysFile in sshd_config.

Files Reference#

FileLocationPurposesetup-ca.sh``scripts/One-time CA key pair generation (warns on key age >90 days)grant-access.sh``scripts/Provision temporary agent access (supports --dry-run, sshd pre-flight check)revoke-access.sh``scripts/Immediate access revocation with post-removal verificationaudit.sh``scripts/Scan for orphaned artifacts (accounts, keys, shells, at jobs)CA private key/etc/ssh/agent_caSigns session certificates (keep secure)CA public key/etc/ssh/agent_ca.pubDistributed to target serversSupport shell/usr/local/bin/agent-support-shell-SIDPer-session command dispatchCleanup script/usr/local/sbin/agent-cleanup-SID.shPer-session auto-cleanupSession log/var/log/agent-support.logAudit trail of all agent commandsArchive/var/log/agent-support-archive/Archived logs from expired sessions

Security Manifest#

CategoryDetailsEnvironment variablesNone accessedExternal endpointsNone — this skill makes zero network callsLocal files read/etc/passwd (user lookup), /etc/ssh/agent_ca (CA signing), agent public key (if provided)Local files written/etc/ssh/agent_ca{,.pub} (setup-ca.sh), /usr/local/bin/agent-support-shell-SID (per-session), /usr/local/sbin/agent-cleanup-SID.sh (per-session), /tmp/agent_session_SID{,.pub,-cert.pub} (ephemeral keys), /var/log/agent-support.log (audit), ~agent/.ssh/authorized_keys (no-ca mode)OS state mutatedCreates/deletes Linux user accounts ( useradd/ userdel), schedules cleanup timers ( at/ systemd-run)Data transmittedNo data leaves the local machine. All operations are local to the host.

Trust & Privacy#

This skill operates entirely offline — no telemetry, no analytics, no data transmitted to external services. All sensitive material (private keys, certificates) is destroyed after session expiration via shred -u (falling back to rm -f). Audit logs remain on the local filesystem under /var/log/ for operator review.