rds_ssm_connect 1.3.9 → 1.5.0

package/.github/workflows/npm-publish.yml

@@ -2,6 +2,7 @@ name: Publish Package to npmjs
 on:
   release:
     types: [published]
+  workflow_dispatch:
 jobs:
   build:
     runs-on: ubuntu-latest

package/CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**rds_ssm_connect** is a Node.js CLI tool that enables secure connections to AWS RDS databases through AWS Systems Manager (SSM) port forwarding via bastion hosts. The tool reads AWS profiles from the user's config, retrieves database credentials from AWS Secrets Manager, and automatically sets up port forwarding through a bastion instance.
+
+## Key Architecture
+
+### Entry Point
+- `connect.js` - Main executable (shebang: `#!/usr/bin/env node`)
+  - Reads AWS profiles from `~/.aws/config`
+  - Uses `inquirer` for interactive environment selection
+  - Executes AWS commands via `aws-vault` wrapper
+  - Establishes SSM port forwarding session
+
+### Configuration
+- `envPortMapping.js` - Environment-to-port mapping configuration
+  - Maps environment suffixes (dev, stage, prod, team1-5, qa1-5, etc.) to local port numbers (5433-5452)
+  - Defines default database name: `emr`
+  - Defines AWS region: `us-east-2`
+  - **Critical**: When adding new environments, update this mapping to assign unique ports
+
+### Core Flow
+1. Read AWS profiles from `~/.aws/config`
+2. Prompt user to select environment (AWS profile)
+3. Query Secrets Manager for RDS credentials (secrets starting with `rds!cluster`)
+4. Find running bastion instance (tagged with `Name=*bastion*`)
+5. Get RDS Aurora cluster endpoint (cluster IDs ending with `-rds-aurora`)
+6. Start SSM port forwarding session
+7. Display connection details for database client
+
+## Development Commands
+
+### Installation
+```bash
+npm install
+```
+
+### Testing
+```bash
+npm test
+```
+Tests cover:
+- AWS config parsing
+- Port mapping logic
+- Credentials validation
+- Retry configuration validation
+
+### Local Testing
+```bash
+node connect.js
+```
+
+### Global Installation (for testing as installed package)
+```bash
+npm install -g .
+rds_ssm_connect
+```
+
+### Publishing
+Package is published to npm via GitHub Actions workflow (`.github/workflows/npm-publish.yml`) when a release is created.
+
+## Prerequisites for Running
+
+- `aws-vault` - Required for AWS credential management
+- AWS CLI - Required for AWS API calls
+- Node.js (ES modules enabled via `"type": "module"` in package.json)
+- Properly configured `~/.aws/config` with named profiles
+
+## AWS Resource Naming Conventions
+
+The application relies on specific AWS resource naming patterns:
+- **Secrets**: Must start with `rds!cluster`
+- **Bastion instances**: Must be tagged with `Name=*bastion*` and in `running` state
+- **RDS clusters**: DBClusterIdentifier must end with `-rds-aurora` and be in `available` state
+
+## Important Notes
+
+- Port assignment is based on longest-matching environment suffix (e.g., `my-team-dev` matches `dev` → port 5433)
+- The tool keeps the SSM session running until Ctrl+C is pressed
+- Default port is 5432 if no environment suffix matches
+- All AWS operations use the `us-east-2` region by default
+
+## Error Handling & Recovery
+
+### TargetNotConnected Recovery
+The application automatically handles the race condition where a bastion instance appears running but SSM agent is not connected:
+
+1. Detects `TargetNotConnected` error (exit code 254)
+2. Terminates the disconnected bastion instance
+3. Waits for ASG to spin up a new instance (max 20 retries @ 15s intervals)
+4. Verifies SSM agent is online using `describe-instance-information`
+5. Retries port forwarding with new instance (max 2 retries)
+
+### Configuration Constants
+All retry/timeout values are configurable in `RETRY_CONFIG`:
+- `BASTION_WAIT_MAX_RETRIES`: 20 (time to wait for new instance)
+- `BASTION_WAIT_RETRY_DELAY_MS`: 15000 (delay between instance checks)
+- `PORT_FORWARDING_MAX_RETRIES`: 2 (connection retry attempts)
+- `SSM_AGENT_READY_WAIT_MS`: 10000 (stabilization time after agent online)
+
+### Process Cleanup
+The application registers handlers for `SIGINT`, `SIGTERM`, and `exit` events to properly clean up child processes (SSM sessions) to prevent zombie processes.

package/connect.js

@@ -10,6 +10,34 @@ import { envPortMapping, REGION, TABLE_NAME } from './envPortMapping.js'
 
 const execAsync = promisify(exec)
 
+// Configuration constants
+const RETRY_CONFIG = {
+  BASTION_WAIT_MAX_RETRIES: 20,
+  BASTION_WAIT_RETRY_DELAY_MS: 15000,
+  PORT_FORWARDING_MAX_RETRIES: 2,
+  SSM_AGENT_READY_WAIT_MS: 10000
+}
+
+// Store active child processes for cleanup
+let activeChildProcesses = []
+
+// Handle graceful shutdown
+function setupProcessCleanup () {
+  const cleanup = () => {
+    console.log('\nCleaning up active connections...')
+    activeChildProcesses.forEach(child => {
+      if (child && !child.killed) {
+        child.kill('SIGTERM')
+      }
+    })
+    process.exit(0)
+  }
+
+  process.on('SIGINT', cleanup)
+  process.on('SIGTERM', cleanup)
+  process.on('exit', cleanup)
+}
+
 async function readAwsConfig () {
   const awsConfigPath = path.join(os.homedir(), '.aws', 'config')
   try {
@@ -36,7 +64,171 @@ async function runCommand (command) {
   }
 }
 
+async function sleep (ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+async function terminateBastionInstance (ENV, instanceId) {
+  console.log(`Terminating disconnected bastion instance: ${instanceId}`)
+  const terminateCommand = `aws-vault exec ${ENV} -- aws ec2 terminate-instances --region ${REGION} --instance-ids ${instanceId}`
+  await runCommand(terminateCommand)
+  console.log('Bastion instance terminated. ASG will spin up a new instance...')
+}
+
+async function waitForNewBastionInstance (ENV, oldInstanceId, maxRetries = RETRY_CONFIG.BASTION_WAIT_MAX_RETRIES, retryDelay = RETRY_CONFIG.BASTION_WAIT_RETRY_DELAY_MS) {
+  console.log('Waiting for new bastion instance to be ready...')
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    console.log(`Checking for new bastion instance (attempt ${attempt}/${maxRetries})...`)
+
+    const instanceIdCommand = `aws-vault exec ${ENV} -- aws ec2 describe-instances --region ${REGION} --filters "Name=tag:Name,Values='*bastion*'" "Name=instance-state-name,Values=running" --query "Reservations[].Instances[].[InstanceId] | [0][0]" --output text`
+    const newInstanceId = await runCommand(instanceIdCommand)
+
+    if (newInstanceId && newInstanceId !== oldInstanceId && newInstanceId !== 'None') {
+      console.log(`New bastion instance found: ${newInstanceId}`)
+
+      // Verify SSM agent is ready
+      const isReady = await waitForSSMAgentReady(ENV, newInstanceId)
+      if (isReady) {
+        return newInstanceId
+      } else {
+        console.log('SSM agent not ready yet, will retry...')
+      }
+    }
+
+    if (attempt < maxRetries) {
+      await sleep(retryDelay)
+    }
+  }
+
+  return null
+}
+
+async function waitForSSMAgentReady (ENV, instanceId, maxRetries = 10, retryDelay = 3000) {
+  console.log('Verifying SSM agent status...')
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    const ssmStatusCommand = `aws-vault exec ${ENV} -- aws ssm describe-instance-information --region ${REGION} --filters "Key=InstanceIds,Values=${instanceId}" --query "InstanceInformationList[0].PingStatus" --output text`
+    const status = await runCommand(ssmStatusCommand)
+
+    if (status === 'Online') {
+      console.log('SSM agent is online and ready.')
+      // Additional wait for agent to stabilize
+      await sleep(RETRY_CONFIG.SSM_AGENT_READY_WAIT_MS)
+      return true
+    }
+
+    console.log(`SSM agent status: ${status || 'Unknown'} (attempt ${attempt}/${maxRetries})`)
+
+    if (attempt < maxRetries) {
+      await sleep(retryDelay)
+    }
+  }
+
+  console.log('Warning: SSM agent did not report Online status, but proceeding anyway.')
+  return false
+}
+
+function monitorPortForwardingSession (child) {
+  const state = {
+    stderrOutput: '',
+    targetNotConnectedError: false,
+    sessionEstablished: false
+  }
+
+  child.stdout.on('data', (data) => {
+    const output = data.toString()
+
+    // Detect when session is actually established
+    if (output.includes('Starting session with SessionId:')) {
+      state.sessionEstablished = true
+      console.log('Port forwarding session established.')
+      console.log('Press Ctrl+C to end the session.')
+    }
+
+    if (!output.includes('Starting session with SessionId:') && !output.includes('Port 5433 opened for sessionId')) {
+      console.log(output)
+    }
+  })
+
+  child.stderr.on('data', (data) => {
+    const errorOutput = data.toString()
+    state.stderrOutput += errorOutput
+
+    // Check for TargetNotConnected error
+    if (errorOutput.includes('TargetNotConnected') || errorOutput.includes('is not connected')) {
+      state.targetNotConnectedError = true
+    }
+
+    console.error(errorOutput)
+  })
+
+  return state
+}
+
+async function handleTargetNotConnectedError (ENV, instanceId, rdsEndpoint, portNumber, retryCount, maxRetries) {
+  console.log(`\nDetected TargetNotConnected error. Attempting recovery (retry ${retryCount + 1}/${maxRetries})...`)
+
+  // Terminate the disconnected instance
+  await terminateBastionInstance(ENV, instanceId)
+
+  // Wait for new instance to be ready
+  const newInstanceId = await waitForNewBastionInstance(ENV, instanceId)
+
+  if (!newInstanceId) {
+    throw new Error('Failed to find new bastion instance after waiting.')
+  }
+
+  // Retry with new instance
+  console.log('Retrying port forwarding with new bastion instance...')
+  return await startPortForwarding(ENV, newInstanceId, rdsEndpoint, portNumber, retryCount + 1, maxRetries)
+}
+
+function executePortForwardingCommand (ENV, instanceId, rdsEndpoint, portNumber) {
+  const portForwardingCommand = `aws-vault exec ${ENV} -- aws ssm start-session --target ${instanceId} --document-name AWS-StartPortForwardingSessionToRemoteHost --parameters "host=${rdsEndpoint},portNumber='5432',localPortNumber='${portNumber}'" --cli-connect-timeout 0`
+
+  console.log('Starting port forwarding session...')
+  const child = exec(portForwardingCommand)
+
+  // Register child process for cleanup
+  activeChildProcesses.push(child)
+
+  return child
+}
+
+async function startPortForwarding (ENV, instanceId, rdsEndpoint, portNumber, retryCount = 0, maxRetries = RETRY_CONFIG.PORT_FORWARDING_MAX_RETRIES) {
+  return new Promise((resolve, reject) => {
+    const child = executePortForwardingCommand(ENV, instanceId, rdsEndpoint, portNumber)
+    const sessionState = monitorPortForwardingSession(child)
+
+    child.on('close', async (code) => {
+      // Remove from active processes
+      activeChildProcesses = activeChildProcesses.filter(p => p !== child)
+
+      try {
+        // Handle TargetNotConnected error with retry
+        if (code === 254 && sessionState.targetNotConnectedError && retryCount < maxRetries) {
+          await handleTargetNotConnectedError(ENV, instanceId, rdsEndpoint, portNumber, retryCount, maxRetries)
+          resolve()
+        } else if (code !== 0) {
+          console.log(`Port forwarding session ended with code ${code}`)
+          reject(new Error(`Port forwarding failed with code ${code}`))
+        } else {
+          console.log(`Port forwarding session ended with code ${code}`)
+          resolve()
+        }
+      } catch (error) {
+        console.error('Error during recovery:', error)
+        reject(error)
+      }
+    })
+  })
+}
+
 async function main () {
+  // Setup process cleanup handlers
+  setupProcessCleanup()
+
   try {
     const ENVS = await readAwsConfig()
 
@@ -69,7 +261,23 @@ async function main () {
 
     const secretsGetCommand = `aws-vault exec ${ENV} -- aws secretsmanager get-secret-value --region ${REGION} --secret-id "${SECRET_NAME}" --query SecretString --output text`
     const secretString = await runCommand(secretsGetCommand)
-    const CREDENTIALS = JSON.parse(secretString)
+
+    if (!secretString) {
+      console.error('Failed to retrieve secret value from Secrets Manager.')
+      return
+    }
+
+    let CREDENTIALS
+    try {
+      CREDENTIALS = JSON.parse(secretString)
+      if (!CREDENTIALS.username || !CREDENTIALS.password) {
+        throw new Error('Missing username or password in credentials')
+      }
+    } catch (error) {
+      console.error('Failed to parse credentials from Secrets Manager:', error.message)
+      return
+    }
+
     const USERNAME = CREDENTIALS.username
     const PASSWORD = CREDENTIALS.password
 
@@ -83,7 +291,7 @@ async function main () {
     const instanceIdCommand = `aws-vault exec ${ENV} -- aws ec2 describe-instances --region ${REGION} --filters "Name=tag:Name,Values='*bastion*'" "Name=instance-state-name,Values=running" --query "Reservations[].Instances[].[InstanceId] | [0][0]" --output text`
     const INSTANCE_ID = await runCommand(instanceIdCommand)
 
-    if (!INSTANCE_ID) {
+    if (!INSTANCE_ID || INSTANCE_ID === 'None') {
       console.error('Failed to find a running instance with tag Name=*bastion*.')
       return
     }
@@ -91,33 +299,12 @@ async function main () {
     const rdsEndpointCommand = `aws-vault exec ${ENV} -- aws rds describe-db-clusters --region ${REGION} --query "DBClusters[?Status=='available' && ends_with(DBClusterIdentifier, '-rds-aurora')].Endpoint | [0]" --output text`
     const RDS_ENDPOINT = await runCommand(rdsEndpointCommand)
 
-    if (!RDS_ENDPOINT) {
+    if (!RDS_ENDPOINT || RDS_ENDPOINT === 'None') {
       console.error('Failed to find the RDS endpoint.')
       return
     }
 
-    const portForwardingCommand = `aws-vault exec ${ENV} -- aws ssm start-session --target ${INSTANCE_ID} --document-name AWS-StartPortForwardingSessionToRemoteHost --parameters "host=${RDS_ENDPOINT},portNumber='5432',localPortNumber='${portNumber}'" --cli-connect-timeout 0`
-
-    console.log('Starting port forwarding session...')
-    const child = exec(portForwardingCommand)
-
-    child.stdout.on('data', (data) => {
-      const output = data.toString()
-      if (!output.includes('Starting session with SessionId:') && !output.includes('Port 5433 opened for sessionId')) {
-        console.log(output)
-      }
-    })
-
-    child.stderr.on('data', (data) => {
-      console.error(data.toString())
-    })
-
-    child.on('close', (code) => {
-      console.log(`Port forwarding session ended with code ${code}`)
-    })
-
-    console.log('Port forwarding session established.')
-    console.log('Press Ctrl+C to end the session.')
+    await startPortForwarding(ENV, INSTANCE_ID, RDS_ENDPOINT, portNumber)
   } catch (error) {
     console.error(`Error: ${error.message}`)
     console.error('Exiting due to unhandled error')

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "rds_ssm_connect",
-  "version": "1.3.9",
+  "version": "1.5.0",
   "type": "module",
   "dependencies": {
-    "@aws-sdk/client-ec2": "^3.830.0",
-    "@aws-sdk/client-rds": "^3.830.0",
-    "@aws-sdk/client-ssm": "^3.830.0",
-    "glob": "^11.0.3",
-    "inquirer": "^12.6.3",
-    "rimraf": "^6.0.1"
+    "@aws-sdk/client-ec2": "^3.943.0",
+    "@aws-sdk/client-rds": "^3.943.0",
+    "@aws-sdk/client-ssm": "^3.943.0",
+    "glob": "^13.0.0",
+    "inquirer": "^13.0.2",
+    "rimraf": "^6.1.2"
   },
   "bin": {
     "rds_ssm_connect": "./connect.js"
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
   }
 }

package/test/connect.test.js

@@ -0,0 +1,185 @@
+import { describe, it, before, after } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFile } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { writeFile, mkdir, rm } from 'fs/promises'
+
+// Test AWS config parsing
+describe('AWS Config Parsing', () => {
+  let testConfigDir
+
+  before(async () => {
+    testConfigDir = join(tmpdir(), `test-aws-config-${Date.now()}`)
+    await mkdir(testConfigDir, { recursive: true })
+  })
+
+  after(async () => {
+    await rm(testConfigDir, { recursive: true, force: true })
+  })
+
+  it('should parse AWS config profiles correctly', async () => {
+    const configContent = `
+[profile dev]
+region = us-east-2
+
+[profile stage]
+region = us-east-2
+
+[profile prod]
+region = us-east-1
+`
+    const configPath = join(testConfigDir, 'config')
+    await writeFile(configPath, configContent)
+
+    const content = await readFile(configPath, { encoding: 'utf-8' })
+    const profiles = content
+      .split(/\r?\n/)
+      .filter(line => line.startsWith('[') && line.endsWith(']'))
+      .map(line => line.slice(1, -1))
+      .map(line => line.replace('profile ', '').trim())
+
+    assert.deepEqual(profiles, ['dev', 'stage', 'prod'])
+  })
+
+  it('should handle empty config file', async () => {
+    const configPath = join(testConfigDir, 'empty-config')
+    await writeFile(configPath, '')
+
+    const content = await readFile(configPath, { encoding: 'utf-8' })
+    const profiles = content
+      .split(/\r?\n/)
+      .filter(line => line.startsWith('[') && line.endsWith(']'))
+      .map(line => line.slice(1, -1))
+      .map(line => line.replace('profile ', '').trim())
+
+    assert.deepEqual(profiles, [])
+  })
+
+  it('should handle malformed config entries', async () => {
+    const configContent = `
+[profile valid-env]
+region = us-east-2
+
+this is not a profile
+[another-invalid
+
+[profile another-valid]
+`
+    const configPath = join(testConfigDir, 'malformed-config')
+    await writeFile(configPath, configContent)
+
+    const content = await readFile(configPath, { encoding: 'utf-8' })
+    const profiles = content
+      .split(/\r?\n/)
+      .filter(line => line.startsWith('[') && line.endsWith(']'))
+      .map(line => line.slice(1, -1))
+      .map(line => line.replace('profile ', '').trim())
+
+    assert.deepEqual(profiles, ['valid-env', 'another-valid'])
+  })
+})
+
+// Test port mapping logic
+describe('Port Mapping', () => {
+  it('should map environment suffix to correct port', () => {
+    const envPortMapping = {
+      dev: '5433',
+      stage: '5434',
+      'pre-prod': '5435',
+      prod: '5436',
+      team1: '5442'
+    }
+
+    const testCases = [
+      { env: 'my-project-dev', expected: '5433' },
+      { env: 'my-project-stage', expected: '5434' },
+      { env: 'my-project-prod', expected: '5436' },
+      { env: 'my-project-team1', expected: '5442' },
+      { env: 'unknown-env', expected: '5432' } // default
+    ]
+
+    testCases.forEach(({ env, expected }) => {
+      const allEnvSuffixes = Object.keys(envPortMapping).sort((a, b) => b.length - a.length)
+      const matchedSuffix = allEnvSuffixes.find(suffix => env.endsWith(suffix))
+      const portNumber = envPortMapping[matchedSuffix] || '5432'
+
+      assert.equal(portNumber, expected, `Failed for env: ${env}`)
+    })
+  })
+
+  it('should handle longest matching suffix', () => {
+    const envPortMapping = {
+      dev: '5433',
+      'perf-dev': '5440'
+    }
+
+    const env = 'my-project-perf-dev'
+    const allEnvSuffixes = Object.keys(envPortMapping).sort((a, b) => b.length - a.length)
+    const matchedSuffix = allEnvSuffixes.find(suffix => env.endsWith(suffix))
+    const portNumber = envPortMapping[matchedSuffix] || '5432'
+
+    // Should match 'perf-dev' not 'dev'
+    assert.equal(portNumber, '5440')
+  })
+})
+
+// Test credentials parsing
+describe('Credentials Parsing', () => {
+  it('should parse valid credentials JSON', () => {
+    const secretString = JSON.stringify({
+      username: 'testuser',
+      password: 'testpass123'
+    })
+
+    const credentials = JSON.parse(secretString)
+
+    assert.equal(credentials.username, 'testuser')
+    assert.equal(credentials.password, 'testpass123')
+  })
+
+  it('should detect missing username', () => {
+    const secretString = JSON.stringify({
+      password: 'testpass123'
+    })
+
+    const credentials = JSON.parse(secretString)
+
+    assert.ok(!credentials.username, 'Username should be missing')
+  })
+
+  it('should detect missing password', () => {
+    const secretString = JSON.stringify({
+      username: 'testuser'
+    })
+
+    const credentials = JSON.parse(secretString)
+
+    assert.ok(!credentials.password, 'Password should be missing')
+  })
+
+  it('should throw on malformed JSON', () => {
+    const secretString = '{ invalid json }'
+
+    assert.throws(() => {
+      JSON.parse(secretString)
+    }, SyntaxError)
+  })
+})
+
+// Test retry configuration
+describe('Retry Configuration', () => {
+  it('should have valid retry values', () => {
+    const RETRY_CONFIG = {
+      BASTION_WAIT_MAX_RETRIES: 20,
+      BASTION_WAIT_RETRY_DELAY_MS: 15000,
+      PORT_FORWARDING_MAX_RETRIES: 2,
+      SSM_AGENT_READY_WAIT_MS: 10000
+    }
+
+    assert.ok(RETRY_CONFIG.BASTION_WAIT_MAX_RETRIES > 0, 'Max retries should be positive')
+    assert.ok(RETRY_CONFIG.BASTION_WAIT_RETRY_DELAY_MS > 0, 'Retry delay should be positive')
+    assert.ok(RETRY_CONFIG.PORT_FORWARDING_MAX_RETRIES >= 0, 'Max retries should be non-negative')
+    assert.ok(RETRY_CONFIG.SSM_AGENT_READY_WAIT_MS > 0, 'SSM wait should be positive')
+  })
+})