# fxcm/ssh-agent-helper architecture

> Architecture diagram of the GitHub repository fxcm/ssh-agent-helper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fxcm/ssh-agent-helper
- Repository: https://github.com/fxcm/ssh-agent-helper

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entities
    U["User/Administrator"]:::external
    F["Nagios Server"]:::external
    G["External SSH Server"]:::external

    subgraph "Management Layer"
        A["ssh-agent-helper"]:::script
        B["check_ssh_key (Nagios Plugin)"]:::script
        I["README.md"]:::doc
        H["build.sh"]:::script
    end

    subgraph "Runtime Layer"
        C(("ssh-agent Process")):::process
        D["run-with-agent"]:::script
    end

    subgraph "Application Layer"
        E["Target Program"]:::process
    end

    %% Connections
    U -->|"start agent+load key"| A
    A -->|"spawns ssh-agent process"| C
    A -->|"ssh-add loads key"| C
    C -->|"UNIX socket SSH_AUTH_SOCK"| D
    D -->|"exports SSH_AUTH_SOCK and launches"| E
    E -->|"SSH agent authentication"| G

    F -->|"invokes check_ssh_key"| B
    B -->|"connects via SSH_AUTH_SOCK"| C
    B -->|"returns status"| F

    %% Click Events
    click A "https://github.com/fxcm/ssh-agent-helper/tree/master/ssh-agent-helper"
    click D "https://github.com/fxcm/ssh-agent-helper/tree/master/run-with-agent"
    click B "https://github.com/fxcm/ssh-agent-helper/tree/master/check_ssh_key"
    click H "https://github.com/fxcm/ssh-agent-helper/blob/master/build.sh"
    click I "https://github.com/fxcm/ssh-agent-helper/blob/master/README.md"

    %% Styles
    classDef script fill:#f9f,stroke:#333,stroke-width:1px
    classDef process fill:#ff9,stroke:#333,stroke-width:1px
    classDef external fill:#9ff,stroke:#333,stroke-width:1px
    classDef doc fill:#efe,stroke:#333,stroke-width:1px
```
