fn_registry/docs/capabilities/ssh.md

Capability: ssh

Operar hosts remotos via SSH. Cubre: CRUD de ~/.ssh/config (ssh_config_add_entry, ssh_config_find, ssh_config_remove), conexiones reutilizables (SSHConn), ejecucion remota (ssh_run, ssh_check), transferencia (scp_put, scp_get), port-forwarding, y orquestacion de deploys (setup_vps_app, deploy_app_remote).

Funciones

ID	Firma	Que hace
audit_ssh_config_bash_cybersecurity	audit_ssh_config(config_path: string) -> void	Audita la configuración de sshd_config evaluando parámetros de seguridad críticos (PermitRootLogin, PasswordAuthentication, Port, MaxAuthTries, X11Forwarding, AllowUsers). También revisa intentos de login fallidos en los logs y lista las claves autorizadas del usuario actual.
docker_compose_remote_deploy_bash_infra	docker_compose_remote_deploy(host: string, remote_dir: string, branch: string, compose_files: string) -> json	Despliega un stack Docker Compose en un host remoto via SSH. Verifica conectividad, hace git pull del branch indicado, actualiza imagenes con docker-compose pull y levanta/recrea los servicios modificados con docker-compose up -d. Soporta compose files adicionales. Retorna JSON con status, containers corriendo y duracion.
rsync_deploy_bash_infra	rsync_deploy(local_dir: string, ssh_alias: string, remote_dir: string) -> json	Sincroniza un directorio local a un host remoto via rsync+SSH. Excluye archivos de desarrollo y bases de datos locales. Crea el directorio remoto si no existe.
setup_registry_api_bash_infra	setup_registry_api(ssh_host: string, api_token: string, basic_auth_user: string, basic_auth_pass: string) -> json	Deploy completo de registry_api en VPS con Docker + Traefik (Coolify proxy). Sincroniza el repo via rsync, genera el hash bcrypt para basicAuth, sube el traefik-dynamic.yml, crea el .env con el token, hace docker compose build+up y verifica el health check.
setup_vps_app_go_infra	func SetupVPSApp(conn SSHConn, cfg DeployConfig) error	Orquesta el setup inicial de una app en un VPS remoto: verifica SSH, crea dirs y usuario, sube binario, instala systemd unit y hace health check.
ssh_check_go_infra	func SSHCheck(conn SSHConn) error	Verifica conectividad SSH ejecutando un comando noop en el host remoto. Timeout de 5 segundos.
ssh_config_add_entry_go_infra	func SSHConfigAddEntry(entries []SSHConfigEntry, entry SSHConfigEntry) ([]SSHConfigEntry, error)	Añade un nuevo SSHConfigEntry a la lista. Error si el alias ya existe.
ssh_config_find_go_infra	func SSHConfigFind(entries []SSHConfigEntry, alias string) (SSHConfigEntry, bool)	Busca un entry por alias en la lista de SSHConfigEntry.
ssh_config_parse_go_infra	func SSHConfigParse(content string) []SSHConfigEntry	Parsea el contenido de un archivo ~/.ssh/config y retorna una lista de SSHConfigEntry.
ssh_config_read_go_infra	func SSHConfigRead() ([]SSHConfigEntry, error)	Lee y parsea ~/.ssh/config. Retorna lista vacia si el archivo no existe.
ssh_config_remove_entry_go_infra	func SSHConfigRemoveEntry(entries []SSHConfigEntry, alias string) ([]SSHConfigEntry, error)	Elimina un entry por alias de la lista. Error si el alias no existe.
ssh_config_render_go_infra	func SSHConfigRender(entries []SSHConfigEntry) string	Convierte una lista de SSHConfigEntry al formato texto de ~/.ssh/config.
ssh_config_write_go_infra	func SSHConfigWrite(entries []SSHConfigEntry) error	Escribe entries a ~/.ssh/config con backup automatico del archivo previo.
ssh_download_go_infra	func SSHDownload(conn SSHConn, remotePath, localPath string) error	Descarga un archivo del host remoto al filesystem local via scp.
ssh_exec_go_infra	func SSHExec(conn SSHConn, command string) (string, string, int, error)	Ejecuta un comando en el host remoto via SSH. Retorna stdout, stderr y exit code separados.
ssh_tunnel_close_go_infra	func SSHTunnelClose(pid int) error	Cierra un tunel SSH enviando SIGTERM al proceso por PID.
ssh_tunnel_open_go_infra	func SSHTunnelOpen(conn SSHConn, localPort int, remoteHost string, remotePort int) (int, error)	Abre un tunel SSH (local port forwarding) en background. Retorna el PID del proceso para cerrarlo despues.
ssh_upload_go_infra	func SSHUpload(conn SSHConn, localPath, remotePath string) error	Sube un archivo local al host remoto via scp.
validate_git_ssh_uri_py_core	def validate_git_ssh_uri(url: str) -> None	Valida el formato de una URI SSH de git (git@host:path). Lanza ValueError si la URI es invalida.

Ejemplo canonico

Anadir host nuevo + comprobar + ejecutar comando

./fn run ssh_config_add_entry \
  --alias organic-machine \
  --hostname 1.2.3.4 \
  --user deploy \
  --identity-file ~/.ssh/organic_ed25519

./fn run ssh_check --host organic-machine
./fn run ssh_run --host organic-machine --cmd "systemctl status nginx"

Transferencia + deploy

./fn run scp_put --host organic-machine --src ./build/myapp --dst /opt/apps/myapp/myapp
./fn run systemd_restart --host organic-machine --unit myapp.service
./fn run wait_for_http https://myapp.example.com/health 30

Fronteras

• NO genera ni rota llaves SSH automaticamente. Asume llave ya generada con ssh-keygen.
• NO valida fingerprints de host. Confianza inicial es responsabilidad del operador (acepta el prompt manualmente o usa StrictHostKeyChecking=no con conciencia del riesgo).
• NO orquesta multi-hop / jump hosts mas alla del ProxyJump del config. Para bastion compleja, edita ~/.ssh/config a mano.
• NO maneja credenciales con password. Solo auth por llave. Tunneling password-based via sshpass queda fuera (ver cybersecurity/audit_ssh_config para auditar).