How fxcm/ssh-agent-helper works
Project Type and Purpose
• Type: A set of command-line utilities (scripts) that manage an SSH agent, wrap other programs to use it, and monitor its state.
• Purpose:
• Securely load SSH keys into an agent (without leaving them password-less)
• Provide a wrapper so programs can find/use the agent
• Provide a Nagios check to ensure the agent is running with a loaded key
File Structure
Top-level items:
• ssh-agent-helper – Script to start an ssh-agent and load a key
• run-with-agent – Wrapper to set SSH_AUTH_SOCK and launch your program
• check_ssh_key – Nagios plugin to verify agent/socket status
• build.sh – Packaging build script for FreeBSD/Linux
• README.md, .gitignore – Documentation and VCS ignores
README for Insights
• Three core components, exactly matching the scripts above.
• Usage patterns: how arguments flow, environment variables (SSH_AUTH_SOCK), external dependencies (ssh-add, ssh-agent, Nagios).
Main Components & Their Interactions
A. User / Administrator
– Initiates ssh-agent-helper
– Invokes run-with-agent to launch arbitrary programs
– Interprets Nagios alerts from check_ssh_key
B. ssh-agent-helper Script
– Prompts for key passphrase
– Spawns ssh-agent process
– Calls ssh-add to load the key into that agent
– Exports SSH_AUTH_SOCK (socket path) for later use
C. ssh-agent Process
– Maintains private key in memory
– Listens on a UNIX socket (SSH_AUTH_SOCK)
D. run-with-agent Script
– Reads or accepts the SSH_AUTH_SOCK variable
– Exports it into the environment of the target program
– Launches the target program (e.g., scp, sftp, git)
E. Target Program
– Uses SSH_AUTH_SOCK to authenticate to remote SSH servers
F. check_ssh_key (Nagios Plugin)
– Connects to SSH_AUTH_SOCK
– Runs ssh-add -l (or similar) to verify a key is loaded
– Returns OK/WARNING/CRITICAL to Nagios
G. External SSH Server
– Receives authentication via the agent forwarded credentials
Relationships and Data Flow
• ssh-agent-helper → ssh-agent (spawn)
• ssh-agent-helper → ssh-add (load key into agent)
• ssh-agent exposes UNIX socket → run-with-agent reads it
• run-with-agent → Target Program (inherits SSH_AUTH_SOCK)
• Target Program ↔ External SSH Server (using agent auth)
• Nagios Server → check_ssh_key → ssh-agent socket → returns status
Architectural Patterns & Design Principles
• Wrapper Pattern: run-with-agent isolates environment setup.
• Monitoring Plugin Pattern: check_ssh_key cleanly integrates with Nagios.
• Separation of Concerns: each script does one job.
• Principle of Least Privilege: agent runs as user, keys remain encrypted until needed.
Relevant Technologies & Dependencies
• Bash (or sh) scripts
• ssh-agent, ssh-add, ssh, scp, sftp
• UNIX domain sockets (SSH_AUTH_SOCK)
• Nagios plugin interface (exit codes, output format)