SSH Agent Module

SSH agent management library for V language. Provides secure key handling, agent lifecycle control, and remote integration.

Features

• Manage SSH keys (generate, load, import)
• Single agent per user with auto-cleanup
• Start/stop/reset agent easily
• Diagnostics and status checks
• Push keys to remote nodes & verify access
• Security-first (file permissions, socket handling)

Platform Support

• Linux, macOS
• Windows (not yet supported)

Quick Start

import incubaid.herolib.osal.sshagent

mut agent := sshagent.new()!
mut key := agent.generate('my_key', '')!
key.load()!
println(agent)

Usage

Agent

mut agent := sshagent.new()!
mut agent := sshagent.new(homepath: '/custom/ssh/path')!
mut agent := sshagent.new_single()!

Keys

mut key := agent.generate('my_key', '')!
agent.add('imported_key', privkey)!
key.load()!
if agent.exists(name: 'my_key') { println('Key exists') }
agent.forget('my_key')!

Agent Ops

println(agent.diagnostics())
println(agent.keys_loaded()!)
agent.reset()!

Remote

import incubaid.herolib.builder

mut node := builder.node_new(ipaddr: 'user@remote:22')!
agent.push_key_to_node(mut node, 'my_key')!

Security

• Private keys set to 0600
• Secure sockets & user isolation
• Validated inputs & safe memory handling

Examples

See examples/osal/sshagent/ for demos.

Testing

v test lib/osal/sshagent/

fn agent_check(mut agent SSHAgent) !

Check if SSH agent is properly configured and all is good

fn agent_status() !map[string]string

check if SSH agent is properly configured and running

fn check_system_security() !map[string]string

check_system_security performs basic system security checks

fn get_secure_socket_path(user string) !string

get_secure_socket_path returns a secure socket path for the given user

fn loaded() bool

fn new(args_ SSHAgentNewArgs) !SSHAgent

fn new_single(args_ SSHAgentNewArgs) !SSHAgent

create new SSH agent with single instance guarantee

fn play(mut plbook PlayBook) !

fn remote_auth(mut agent SSHAgent, node_addr string, key_name string) !

Add public key to authorized_keys on remote node

fn remote_copy(mut agent SSHAgent, node_addr string, key_name string) !

Copy private key to remote node

fn sanitize_environment_variables()

sanitize_environment_variables cleans SSH-related environment variables

fn secure_file_permissions(file_path string, is_private bool) !

secure_file_permissions sets appropriate permissions for SSH key files

fn sshkey_check(mut agent SSHAgent, name string) !

Check if SSH key is valid

fn sshkey_create(mut agent SSHAgent, name string, passphrase string) !

Create a new SSH key

fn sshkey_delete(mut agent SSHAgent, name string) !

Delete an SSH key

fn sshkey_load(mut agent SSHAgent, name string) !

Load SSH key into agent

fn validate_file_path(path string, base_dir string) !string

validate_file_path ensures file paths are safe and within expected directories

fn validate_key_name(name string) !string

validate_key_name ensures SSH key names are safe and follow conventions

fn validate_passphrase(passphrase string) !string

validate_passphrase checks passphrase strength (basic validation)

fn validate_private_key(privkey string) !string

validate_private_key checks if the provided string is a valid SSH private key

enum SSHKeyCat {
	ed25519
	rsa
}

struct KeyGetArgs {
pub mut:
	pubkey string
	// privkey string	
	// privkey_path string
	name string
}

struct SSHAgent {
pub mut:
	keys     []SSHKey
	active   bool
	homepath pathlib.Path
}

fn (mut agent SSHAgent) add(name string, privkey_ string) !SSHKey

load the key, they key is content (private key) . a name is required

fn (mut agent SSHAgent) cleanup_orphaned_agents() !

cleanup orphaned ssh-agent processes, means all agents for the logged in user

fn (mut agent SSHAgent) diagnostics() map[string]string

get agent status and diagnostics

fn (mut agent SSHAgent) ensure_single_agent() !

ensure only one SSH agent is running for the current user

fn (mut agent SSHAgent) exists(args KeyGetArgs) bool

fn (mut agent SSHAgent) forget(name string) !

forget the specified key

fn (mut agent SSHAgent) generate(name string, passphrase string) !SSHKey

returns path to sshkey

fn (mut agent SSHAgent) get(args_ KeyGetArgs) ?SSHKey

fn (mut agent SSHAgent) init() !

get all keys from sshagent and from the local .ssh dir

fn (mut agent SSHAgent) is_agent_responsive() bool

check if current agent is responsive

fn (mut agent SSHAgent) keys_loaded() ![]SSHKey

fn (mut agent SSHAgent) load(keypath string) !SSHKey

load key starting from path to private key

fn (mut agent SSHAgent) push_key_to_node(mut node builder.Node, key_name string) !

push SSH public key to a remote node's authorized_keys

fn (mut agent SSHAgent) remove_key_from_node(mut node builder.Node, key_name string) !

remove SSH public key from a remote node's authorized_keys

fn (mut agent SSHAgent) reset() !

unload all ssh keys

fn (mut agent SSHAgent) start_agent_with_socket(socket_path string) !

start new ssh-agent with specific socket path

fn (mut agent SSHAgent) str() string

fn (mut agent SSHAgent) verify_key_access(mut node builder.Node, key_name string) !bool

verify SSH key access to remote node

struct SSHAgentNewArgs {
pub mut:
	homepath string
}

struct SSHKey {
pub mut:
	name   string
	pubkey string
	loaded bool
	email  string
	agent  &SSHAgent @[skip; str: skip]
	cat    SSHKeyCat
}

fn (mut key SSHKey) keypath() !pathlib.Path

fn (mut key SSHKey) keypath_pub() !pathlib.Path

fn (mut key SSHKey) keypub() !string

fn (mut key SSHKey) forget() !

load the key, they key is content, other keys will be unloaded

fn (mut key SSHKey) str() string

fn (mut key SSHKey) load() !