vaultwarden-ssh-agent/README.md

Vaultwarden SSH Agent Script

A PowerShell script that automatically loads SSH keys from your Vaultwarden vault into your SSH agent. This script provides a secure way to manage and load your SSH keys by storing them in your Vaultwarden vault and loading them into your SSH agent when needed.

Prerequisites

• PowerShell 5.1 or later
• Bitwarden CLI installed and available in PATH
• SSH agent running on your system
• A Vaultwarden (self-hosted Bitwarden) instance

Installation

1. Download the script file (vaultwarden-ssh-agent.ps1) to your preferred location
2. Ensure you have the Bitwarden CLI installed:

winget install Bitwarden.CLI
# or
choco install bitwarden-cli

Configuration

Initial Setup

Create a folder named 'ssh-agent' in your Vaultwarden vault

For each SSH key you want to manage:

• Create a new item in the 'ssh-agent' folder
• Paste the public key in the notes field
• Attach the private key as a file attachment

Note: If you haven't configured the Bitwarden CLI for your Vaultwarden instance yet, don't worry! The script will automatically prompt you for your server URL during the first run.

Key Item Structure

Each SSH key in Vaultwarden should be structured as follows:

• Folder: Must be in the 'ssh-agent' folder
• Name: A descriptive name for your SSH key
• Notes: Contains the public key (required)
• Attachment: The private key file (required)

Usage

• Basic Usage: .\vaultwarden-ssh-agent.ps1
• To run with detailed debugging information use -Debug switch.

Session Management:

• Reuses existing sessions when available
• Automatically handles login/unlock operations
• Stores session token as environment variable

Key Validation:

• Validates both public and private key formats
• Secure Memory Handling: Implements secure handling for sensitive data
• Detailed Reporting: Provides summary of successful and failed key additions

Security Features

• Secure handling of private keys using SecureString
• Proper cleanup of sensitive data from memory
• Session token management
• Key format validation before loading

Error Handling

The script includes comprehensive error handling:

• Validates Vaultwarden configuration
• Verifies key formats
• Reports failed operations
• Provides detailed debug output when needed
• Troubleshooting

Common Issues

"ssh-agent folder not found"

• Create a folder named ssh-agent in your Vaultwarden vault

"Failed to add key"

• Verify the SSH agent is running
• Check key format
• Run with -Debug flag for more information

Note on Security

Never share your private keys Keep your Vaultwarden master password secure Regularly rotate your SSH keys Monitor SSH agent contents with ssh-add -l

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please open an issue in the repository.

License

This script is available under the MIT License. See the LICENSE file for more details.