[v1.1] SSH key injection for private repository access

[frankbria]

Problem

E2B sandboxes cannot clone or access private repositories because SSH keys are not available in the sandbox environment.

Use Case

• Projects with private npm packages
• Monorepos with private submodules
• Teams using private GitHub/GitLab repositories

Proposed Solution

CLI Flag

parallel-cc sandbox-run --repo . --prompt "Task" \
  --ssh-key ~/.ssh/id_ed25519

Implementation

1. Read SSH key file content (with user confirmation)
2. Create ~/.ssh directory in sandbox
3. Write private key with correct permissions (600)
4. Add known hosts entries for common providers
5. Optionally configure ~/.ssh/config

Security Considerations

• Never log SSH key contents
• Warn user before transmitting key to sandbox
• Clear key from sandbox after execution
• Support SSH_AUTH_SOCK forwarding as alternative (if E2B supports)

Files to Modify

• src/cli.ts - Add --ssh-key flag
• src/e2b/sandbox-manager.ts - SSH key injection
• src/e2b/file-sync.ts - Exclude .ssh from normal sync

Acceptance Criteria

• SSH key can be injected via CLI flag
• Private repository access works in sandbox
• Security warnings displayed appropriately
• Key cleaned up after execution
• Documentation includes security guidance

Dependencies

• Depends on [v1.1] Auto-configure git identity in E2B sandboxes #23 (git identity configuration)

[traycerai]

Plan

Observations

The codebase has a mature E2B sandbox integration with strong security patterns including input sanitization, path validation, and credential scanning. SSH keys are currently excluded from file sync via ALWAYS_EXCLUDE patterns (.ssh/id_*, id_rsa, etc.) in file:src/e2b/file-sync.ts. Git identity configuration already exists in file:src/e2b/claude-runner.ts (lines 577-584), setting user.name and user.email for sandbox commits. The CLI uses commander for argument parsing, and the sandbox manager provides sandbox.files.write() and sandbox.commands.run() methods for file operations and command execution.

Approach

Implement SSH key injection as an opt-in security feature with explicit user consent. The --ssh-key flag will read a local SSH private key, display a security warning, inject it into the sandbox's ~/.ssh directory with correct permissions (600), configure known hosts for common Git providers, and ensure cleanup after execution. This approach maintains the existing security-first design while enabling private repository access. The implementation leverages existing patterns: CLI option parsing, file validation, sandbox file operations, and security warnings similar to credential scanning.

Implementation Steps

1. Add CLI Flag to sandbox-run Command

File: file:src/cli.ts

Add the --ssh-key option to the sandbox-run command (around line 1383):

.option('--ssh-key <path>', 'Path to SSH private key for private repository access (e.g., ~/.ssh/id_ed25519)')

2. Create SSH Key Injection Module

File: file:src/e2b/ssh-key-injector.ts (new file)

Create a new module with the following exports:

• validateSSHKeyPath(keyPath: string): Promise<void>

  • Validate the SSH key file exists and is readable
  • Check file permissions (warn if too permissive, e.g., not 600/400)
  • Verify it's a valid SSH private key format (check for BEGIN markers)
  • Throw descriptive errors for invalid keys

• displaySecurityWarning(keyPath: string): Promise<boolean>

  • Display a clear warning about transmitting SSH keys to E2B sandbox
  • List security implications (key will be in sandbox, transmitted over network)
  • Prompt user for explicit confirmation (y/n)
  • Return true if user confirms, false otherwise
  • Skip prompt if --json flag is set (require explicit --confirm-ssh-key flag instead)

• injectSSHKey(sandbox: Sandbox, keyPath: string, logger: Logger): Promise<SSHInjectionResult>

  • Read SSH private key content from local file
  • Create ~/.ssh directory in sandbox: mkdir -p ~/.ssh && chmod 700 ~/.ssh
  • Write private key to ~/.ssh/id_rsa (or appropriate name based on key type)
  • Set correct permissions: chmod 600 ~/.ssh/id_rsa
  • Add known hosts entries for GitHub, GitLab, Bitbucket:

    ssh-keyscan github.com >> ~/.ssh/known_hosts
    ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
    ssh-keyscan bitbucket.org >> ~/.ssh/known_hosts
    

  • Optionally create ~/.ssh/config with:

    Host *
      StrictHostKeyChecking accept-new
      UserKnownHostsFile ~/.ssh/known_hosts
    

  • Return result with success status and key fingerprint (for logging)

• cleanupSSHKey(sandbox: Sandbox, logger: Logger): Promise<void>

  • Remove SSH key: rm -rf ~/.ssh/id_*
  • Remove known hosts: rm -f ~/.ssh/known_hosts
  • Remove config: rm -f ~/.ssh/config
  • Log cleanup completion
  • Handle errors gracefully (log warnings but don't fail)

• Types:

  interface SSHInjectionResult {
    success: boolean;
    keyFingerprint?: string;
    error?: string;
  }

3. Integrate SSH Key Injection into sandbox-run Workflow

File: file:src/cli.ts

In the sandbox-run command action (around line 1600, after sandbox creation and upload):

1. Validate SSH key option (after line 1617, before execution):

   • If --ssh-key is provided, validate the key path
   • Display security warning and get user confirmation
   • Exit if user declines or validation fails

2. Inject SSH key (after workspace upload, before Claude execution):

   • Call injectSSHKey() with sandbox instance and key path
   • Log injection success with key fingerprint (redacted)
   • Handle injection failures gracefully

3. Cleanup SSH key (in finally block, after sandbox termination):

   • Call cleanupSSHKey() to remove key from sandbox
   • Ensure cleanup happens even if execution fails

4. Update Logger for Sensitive Data Handling

File: file:src/logger.ts

Add a method to redact sensitive patterns from log messages:

• redactSensitive(message: string): string

  • Replace SSH key content patterns with [REDACTED]
  • Replace key fingerprints with partial display (first 8 chars + ...)
  • Use regex patterns to detect and redact:
    • BEGIN.*PRIVATE KEY blocks
    • Long base64 strings (potential key material)
    • Patterns matching ssh-rsa, ssh-ed25519 followed by long strings

• Update existing log methods (info, debug, warn, error) to call redactSensitive() before logging

5. Update File Sync Exclusions

File: file:src/e2b/file-sync.ts

The ALWAYS_EXCLUDE array already contains SSH key patterns (lines 63-69). No changes needed - SSH keys will continue to be excluded from normal file sync, ensuring they're only injected when explicitly requested via --ssh-key flag.

6. Add Security Documentation

File: file:README.md or file:docs/SSH_KEY_USAGE.md (new file)

Document SSH key injection feature:

• Security Considerations:

  • SSH keys are transmitted to E2B sandbox over encrypted connection
  • Keys are stored temporarily in sandbox memory/disk
  • Keys are cleaned up after execution
  • Never commit SSH keys to repositories
  • Use deploy keys or read-only keys when possible

• Usage Examples:

  # Basic usage with SSH key
  parallel-cc sandbox-run --repo . --prompt "Clone private repo" \
    --ssh-key ~/.ssh/id_ed25519
  
  # With OAuth and git-live
  parallel-cc sandbox-run --repo . --prompt "Update dependencies" \
    --ssh-key ~/.ssh/deploy_key --auth-method oauth --git-live

• Best Practices:

  • Use dedicated deploy keys for CI/CD
  • Rotate keys regularly
  • Use keys with minimal permissions (read-only when possible)
  • Monitor key usage in E2B dashboard

• Troubleshooting:

  • "Permission denied (publickey)" → Check key is added to GitHub/GitLab
  • "Bad permissions" → Ensure local key has 600 permissions
  • "Invalid key format" → Verify key file is valid SSH private key

7. Add Tests

File: file:tests/e2b/ssh-key-injector.test.ts (new file)

Create unit tests for SSH key injection:

• validateSSHKeyPath():

  • Valid key file passes validation
  • Non-existent file throws error
  • Invalid key format throws error
  • Overly permissive permissions trigger warning

• injectSSHKey():

  • Successfully creates .ssh directory
  • Writes key with correct permissions
  • Adds known hosts entries
  • Creates SSH config file

• cleanupSSHKey():

  • Removes all SSH-related files
  • Handles missing files gracefully
  • Logs cleanup completion

• Integration test:

  • Full workflow: inject → use key → cleanup
  • Verify key works for git operations
  • Verify cleanup removes all traces

8. Update CLI Help and Documentation

File: file:src/cli.ts

Update the sandbox-run command description (around line 1354) to include SSH key usage:

SSH Key Injection:
  --ssh-key <path>        Inject SSH private key for private repository access
                          (requires user confirmation, cleaned up after execution)

Add example to command description:

# Private repository access
parallel-cc sandbox-run --repo . --prompt "Clone private deps" --ssh-key ~/.ssh/id_ed25519

Security Flow Diagram

sequenceDiagram
    participant User
    participant CLI
    participant SSHInjector
    participant Sandbox
    participant Logger

    User->>CLI: sandbox-run --ssh-key ~/.ssh/id_ed25519
    CLI->>SSHInjector: validateSSHKeyPath()
    SSHInjector-->>CLI: ✓ Valid key
    
    CLI->>SSHInjector: displaySecurityWarning()
    SSHInjector->>User: ⚠️ SSH key will be transmitted to sandbox
    User->>SSHInjector: Confirm (y/n)
    SSHInjector-->>CLI: ✓ Confirmed
    
    CLI->>Sandbox: Create sandbox
    CLI->>Sandbox: Upload workspace
    
    CLI->>SSHInjector: injectSSHKey()
    SSHInjector->>Sandbox: mkdir -p ~/.ssh && chmod 700 ~/.ssh
    SSHInjector->>Sandbox: Write key with chmod 600
    SSHInjector->>Sandbox: ssh-keyscan (known_hosts)
    SSHInjector->>Logger: Log success (redacted)
    SSHInjector-->>CLI: ✓ Key injected
    
    CLI->>Sandbox: Execute Claude Code
    Note over Sandbox: Private repos accessible
    
    CLI->>SSHInjector: cleanupSSHKey()
    SSHInjector->>Sandbox: rm -rf ~/.ssh/id_*
    SSHInjector->>Logger: Log cleanup
    SSHInjector-->>CLI: ✓ Cleaned up
    
    CLI->>Sandbox: Terminate sandbox

Loading

Implementation Checklist

• Add --ssh-key CLI option to sandbox-run command
• Create file:src/e2b/ssh-key-injector.ts module with validation, injection, and cleanup functions
• Integrate SSH key injection into sandbox-run workflow (validate → warn → inject → cleanup)
• Update file:src/logger.ts to redact sensitive SSH key content from logs
• Verify file:src/e2b/file-sync.ts exclusions prevent accidental SSH key uploads
• Add security documentation to README or separate docs file
• Create unit tests in file:tests/e2b/ssh-key-injector.test.ts
• Update CLI help text and examples
• Test with real private repositories (GitHub, GitLab, Bitbucket)
• Verify cleanup removes all SSH key traces from sandbox

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a mature E2B sandbox integration with strong security patterns including input sanitization, path validation, and credential scanning. SSH keys are currently **excluded** from file sync via `ALWAYS_EXCLUDE` patterns (`.ssh/id_*`, `id_rsa`, etc.) in `file:src/e2b/file-sync.ts`. Git identity configuration already exists in `file:src/e2b/claude-runner.ts` (lines 577-584), setting `user.name` and `user.email` for sandbox commits. The CLI uses `commander` for argument parsing, and the sandbox manager provides `sandbox.files.write()` and `sandbox.commands.run()` methods for file operations and command execution.

## Approach

Implement SSH key injection as an **opt-in security feature** with explicit user consent. The `--ssh-key` flag will read a local SSH private key, display a security warning, inject it into the sandbox's `~/.ssh` directory with correct permissions (600), configure known hosts for common Git providers, and ensure cleanup after execution. This approach maintains the existing security-first design while enabling private repository access. The implementation leverages existing patterns: CLI option parsing, file validation, sandbox file operations, and security warnings similar to credential scanning.

## Implementation Steps

### 1. Add CLI Flag to `sandbox-run` Command

**File:** `file:src/cli.ts`

Add the `--ssh-key` option to the `sandbox-run` command (around line 1383):

```
.option('--ssh-key <path>', 'Path to SSH private key for private repository access (e.g., ~/.ssh/id_ed25519)')
```

### 2. Create SSH Key Injection Module

**File:** `file:src/e2b/ssh-key-injector.ts` (new file)

Create a new module with the following exports:

- **`validateSSHKeyPath(keyPath: string): Promise<void>`**
  - Validate the SSH key file exists and is readable
  - Check file permissions (warn if too permissive, e.g., not 600/400)
  - Verify it's a valid SSH private key format (check for `BEGIN` markers)
  - Throw descriptive errors for invalid keys

- **`displaySecurityWarning(keyPath: string): Promise<boolean>`**
  - Display a clear warning about transmitting SSH keys to E2B sandbox
  - List security implications (key will be in sandbox, transmitted over network)
  - Prompt user for explicit confirmation (y/n)
  - Return `true` if user confirms, `false` otherwise
  - Skip prompt if `--json` flag is set (require explicit `--confirm-ssh-key` flag instead)

- **`injectSSHKey(sandbox: Sandbox, keyPath: string, logger: Logger): Promise<SSHInjectionResult>`**
  - Read SSH private key content from local file
  - Create `~/.ssh` directory in sandbox: `mkdir -p ~/.ssh && chmod 700 ~/.ssh`
  - Write private key to `~/.ssh/id_rsa` (or appropriate name based on key type)
  - Set correct permissions: `chmod 600 ~/.ssh/id_rsa`
  - Add known hosts entries for GitHub, GitLab, Bitbucket:
    ```
    ssh-keyscan github.com >> ~/.ssh/known_hosts
    ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
    ssh-keyscan bitbucket.org >> ~/.ssh/known_hosts
    ```
  - Optionally create `~/.ssh/config` with:
    ```
    Host *
      StrictHostKeyChecking accept-new
      UserKnownHostsFile ~/.ssh/known_hosts
    ```
  - Return result with success status and key fingerprint (for logging)

- **`cleanupSSHKey(sandbox: Sandbox, logger: Logger): Promise<void>`**
  - Remove SSH key: `rm -rf ~/.ssh/id_*`
  - Remove known hosts: `rm -f ~/.ssh/known_hosts`
  - Remove config: `rm -f ~/.ssh/config`
  - Log cleanup completion
  - Handle errors gracefully (log warnings but don't fail)

- **Types:**
  ```typescript
  interface SSHInjectionResult {
    success: boolean;
    keyFingerprint?: string;
    error?: string;
  }
  ```

### 3. Integrate SSH Key Injection into `sandbox-run` Workflow

**File:** `file:src/cli.ts`

In the `sandbox-run` command action (around line 1600, after sandbox creation and upload):

1. **Validate SSH key option** (after line 1617, before execution):
   - If `--ssh-key` is provided, validate the key path
   - Display security warning and get user confirmation
   - Exit if user declines or validation fails

2. **Inject SSH key** (after workspace upload, before Claude execution):
   - Call `injectSSHKey()` with sandbox instance and key path
   - Log injection success with key fingerprint (redacted)
   - Handle injection failures gracefully

3. **Cleanup SSH key** (in finally block, after sandbox termination):
   - Call `cleanupSSHKey()` to remove key from sandbox
   - Ensure cleanup happens even if execution fails

### 4. Update Logger for Sensitive Data Handling

**File:** `file:src/logger.ts`

Add a method to redact sensitive patterns from log messages:

- **`redactSensitive(message: string): string`**
  - Replace SSH key content patterns with `[REDACTED]`
  - Replace key fingerprints with partial display (first 8 chars + `...`)
  - Use regex patterns to detect and redact:
    - `BEGIN.*PRIVATE KEY` blocks
    - Long base64 strings (potential key material)
    - Patterns matching `ssh-rsa`, `ssh-ed25519` followed by long strings

- **Update existing log methods** (`info`, `debug`, `warn`, `error`) to call `redactSensitive()` before logging

### 5. Update File Sync Exclusions

**File:** `file:src/e2b/file-sync.ts`

The `ALWAYS_EXCLUDE` array already contains SSH key patterns (lines 63-69). **No changes needed** - SSH keys will continue to be excluded from normal file sync, ensuring they're only injected when explicitly requested via `--ssh-key` flag.

### 6. Add Security Documentation

**File:** `file:README.md` or `file:docs/SSH_KEY_USAGE.md` (new file)

Document SSH key injection feature:

- **Security Considerations:**
  - SSH keys are transmitted to E2B sandbox over encrypted connection
  - Keys are stored temporarily in sandbox memory/disk
  - Keys are cleaned up after execution
  - Never commit SSH keys to repositories
  - Use deploy keys or read-only keys when possible

- **Usage Examples:**
  ```bash
  # Basic usage with SSH key
  parallel-cc sandbox-run --repo . --prompt "Clone private repo" \
    --ssh-key ~/.ssh/id_ed25519

  # With OAuth and git-live
  parallel-cc sandbox-run --repo . --prompt "Update dependencies" \
    --ssh-key ~/.ssh/deploy_key --auth-method oauth --git-live
  ```

- **Best Practices:**
  - Use dedicated deploy keys for CI/CD
  - Rotate keys regularly
  - Use keys with minimal permissions (read-only when possible)
  - Monitor key usage in E2B dashboard

- **Troubleshooting:**
  - "Permission denied (publickey)" → Check key is added to GitHub/GitLab
  - "Bad permissions" → Ensure local key has 600 permissions
  - "Invalid key format" → Verify key file is valid SSH private key

### 7. Add Tests

**File:** `file:tests/e2b/ssh-key-injector.test.ts` (new file)

Create unit tests for SSH key injection:

- **`validateSSHKeyPath()`:**
  - Valid key file passes validation
  - Non-existent file throws error
  - Invalid key format throws error
  - Overly permissive permissions trigger warning

- **`injectSSHKey()`:**
  - Successfully creates `.ssh` directory
  - Writes key with correct permissions
  - Adds known hosts entries
  - Creates SSH config file

- **`cleanupSSHKey()`:**
  - Removes all SSH-related files
  - Handles missing files gracefully
  - Logs cleanup completion

- **Integration test:**
  - Full workflow: inject → use key → cleanup
  - Verify key works for git operations
  - Verify cleanup removes all traces

### 8. Update CLI Help and Documentation

**File:** `file:src/cli.ts`

Update the `sandbox-run` command description (around line 1354) to include SSH key usage:

```
SSH Key Injection:
  --ssh-key <path>        Inject SSH private key for private repository access
                          (requires user confirmation, cleaned up after execution)
```

Add example to command description:

```
# Private repository access
parallel-cc sandbox-run --repo . --prompt "Clone private deps" --ssh-key ~/.ssh/id_ed25519
```

## Security Flow Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant SSHInjector
    participant Sandbox
    participant Logger

    User->>CLI: sandbox-run --ssh-key ~/.ssh/id_ed25519
    CLI->>SSHInjector: validateSSHKeyPath()
    SSHInjector-->>CLI: ✓ Valid key
    
    CLI->>SSHInjector: displaySecurityWarning()
    SSHInjector->>User: ⚠️ SSH key will be transmitted to sandbox
    User->>SSHInjector: Confirm (y/n)
    SSHInjector-->>CLI: ✓ Confirmed
    
    CLI->>Sandbox: Create sandbox
    CLI->>Sandbox: Upload workspace
    
    CLI->>SSHInjector: injectSSHKey()
    SSHInjector->>Sandbox: mkdir -p ~/.ssh && chmod 700 ~/.ssh
    SSHInjector->>Sandbox: Write key with chmod 600
    SSHInjector->>Sandbox: ssh-keyscan (known_hosts)
    SSHInjector->>Logger: Log success (redacted)
    SSHInjector-->>CLI: ✓ Key injected
    
    CLI->>Sandbox: Execute Claude Code
    Note over Sandbox: Private repos accessible
    
    CLI->>SSHInjector: cleanupSSHKey()
    SSHInjector->>Sandbox: rm -rf ~/.ssh/id_*
    SSHInjector->>Logger: Log cleanup
    SSHInjector-->>CLI: ✓ Cleaned up
    
    CLI->>Sandbox: Terminate sandbox
```

## Implementation Checklist

- [ ] Add `--ssh-key` CLI option to `sandbox-run` command
- [ ] Create `file:src/e2b/ssh-key-injector.ts` module with validation, injection, and cleanup functions
- [ ] Integrate SSH key injection into `sandbox-run` workflow (validate → warn → inject → cleanup)
- [ ] Update `file:src/logger.ts` to redact sensitive SSH key content from logs
- [ ] Verify `file:src/e2b/file-sync.ts` exclusions prevent accidental SSH key uploads
- [ ] Add security documentation to README or separate docs file
- [ ] Create unit tests in `file:tests/e2b/ssh-key-injector.test.ts`
- [ ] Update CLI help text and examples
- [ ] Test with real private repositories (GitHub, GitLab, Bitbucket)
- [ ] Verify cleanup removes all SSH key traces from sandbox

---

Execution Information

Branch: main
Commit: 136df60

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#1 - Add native sandboxing integration option [merged]
#14 - feat: Add early E2B API key validation to fail fast [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!