TSYS Secrets Manager
A comprehensive bash script solution for managing secrets at TSYS using the Bitwarden CLI. This tool provides automated installation, configuration, and secure secret retrieval from your Bitwarden vault.
Features
- Automated Installation: Automatically detects and installs Bitwarden CLI via multiple methods (snap, npm, direct download)
- Configuration Management: Uses secure configuration files for server and authentication details
- Multiple Commands: Support for installation, secret retrieval, listing, and testing
- Robust Error Handling: Comprehensive error codes and detailed logging
- Security-First: Proper session management, cleanup, and credential handling
- Cross-Platform: Designed for Linux environments with multiple installation fallbacks
Quick Start
-
Clone and Setup:
git clone <repository-url> cd KNELSecretsManager chmod +x secrets-manager.sh
-
Create Configuration:
cp config/bitwarden-config.conf.sample bitwarden-config.conf # Edit bitwarden-config.conf with your actual Bitwarden credentials
-
Install Bitwarden CLI (if not already installed):
./secrets-manager.sh install
-
Test Your Setup:
./secrets-manager.sh test
-
Retrieve Secrets:
./secrets-manager.sh get APIKEY-pushover
Configuration
Create a bitwarden-config.conf
file based on the provided sample in the config/
directory:
# Bitwarden server URL
BW_SERVER_URL="https://pwvault.turnsys.com"
# API credentials (from Bitwarden account settings)
BW_CLIENTID="your_client_id_here"
BW_CLIENTSECRET="your_client_secret_here"
# Master password
BW_PASSWORD="your_master_password_here"
Security Note: The actual configuration file is automatically ignored by git to prevent credential exposure.
Usage
Command Reference
./secrets-manager.sh [OPTIONS] COMMAND [ARGS]
Commands
install
- Install Bitwarden CLIget <secret_name>
- Retrieve a specific secretlist
- List all available secrets in your vaulttest
- Test configuration and connectivity
Options
-c, --config FILE
- Use specific config file (default:./bitwarden-config.conf
)-h, --help
- Show help message-v, --version
- Show version information
Examples
# Install Bitwarden CLI
./secrets-manager.sh install
# Test your configuration
./secrets-manager.sh test
# Get a specific secret
./secrets-manager.sh get APIKEY-pushover
# List all available secrets
./secrets-manager.sh list
# Use a custom config file
./secrets-manager.sh --config /path/to/custom.conf get my-secret
Using in Scripts
#!/bin/bash
# Example: Load API key into environment variable
export PUSHOVER_API="$(./secrets-manager.sh get APIKEY-pushover)"
# Use the secret in your application
curl -X POST "https://api.pushover.net/1/messages.json" \
-d "token=$PUSHOVER_API" \
-d "user=your_user_key" \
-d "message=Hello from TSYS!"
Installation Methods
The script automatically tries multiple installation methods in order:
- NPM Global Package (if npm is available)
- Direct Binary Download (fallback method)
Error Codes
Code | Description |
---|---|
10 | Configuration file not found |
20 | Bitwarden CLI not installed |
30 | Bitwarden CLI installation failed |
40 | Server configuration failed |
50 | Session/unlock failed |
60 | Secret not found |
70 | Login failed |
Logging
All operations are logged to /tmp/secrets-manager.sh.log
for debugging and audit purposes.
Security Considerations
- Configuration files containing credentials are automatically gitignored
- Session tokens are properly cleaned up on script exit
- Master passwords are handled securely without shell history exposure
- All sensitive operations include proper error handling
Legacy Scripts
Repository Structure
KNELSecretsManager/
├── secrets-manager.sh # Main secrets management script
├── README.md # This documentation
├── LICENSE # License information
├── Makefile # Build and test automation
├── .gitignore # Git ignore rules
├── bin/ # Legacy scripts and utilities
│ ├── poc.sh # Original proof of concept
│ └── prod.sh # ChatGPT-assisted production attempt
├── config/ # Configuration templates
│ └── bitwarden-config.conf.sample # Sample configuration
├── tests/ # Test suite
│ └── test-secrets-manager.sh # Comprehensive test framework
└── docs/ # Documentation
└── ADR-Node.md # Architecture Decision Records
The main secrets-manager.sh
script combines the best features of the legacy implementations while adding robust error handling, installation management, and improved security.
Testing
This project includes a comprehensive test suite designed to work both standalone and when vendored into shell scripting frameworks.
Running Tests
# Run all tests
./tests/test-secrets-manager.sh run
# Run tests in CI mode (no colors)
./tests/test-secrets-manager.sh --ci run
# Using Make (recommended)
make test # Run all tests
make test-ci # Run in CI mode
make lint # Run shellcheck
make all # Run deps, lint, and tests
Test Coverage
The test suite covers:
- Script existence and permissions
- Command-line argument parsing
- Help and version output
- Error handling and exit codes
- Configuration file validation
- Bitwarden CLI dependency checks
- Performance and startup time
- Vendor integration compatibility
Vendor Integration Testing
When this project is vendored into other shell scripting frameworks:
# Test as vendored dependency
make vendor-test
# Or manually
mkdir /tmp/vendor-test
cp secrets-manager.sh tests/test-secrets-manager.sh config/bitwarden-config.conf.sample /tmp/vendor-test/
cd /tmp/vendor-test && ./test-secrets-manager.sh --ci run
Development Testing
# Setup development environment
make dev-setup
# Run tests with development config
make dev-test
Architecture Decision Records
This project includes ADRs for key architectural decisions:
- ADR-001: Node.js Version Management Strategy - Analysis of MISE vs system packages for Node.js version management
Contributing
When contributing to this project:
-
Test all changes thoroughly:
make ci # Run full CI pipeline
-
Update documentation as needed
-
Follow existing code style and conventions
-
Run security checks:
make security-check
-
Ensure compatibility with vendor integration:
make vendor-test
Development Commands
make help # Show all available commands
make install # Install dependencies
make dev-setup # Setup development environment
make lint # Run shellcheck
make security-check # Basic security validation
make clean # Clean temporary files
make docs # Generate documentation
License
See LICENSE file for details.