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

1. Clone and Setup:

   git clone <repository-url>
   cd KNELSecretsManager
   chmod +x secrets-manager.sh
   

2. Create Configuration:

   cp config/bitwarden-config.conf.sample bitwarden-config.conf
   # Edit bitwarden-config.conf with your actual Bitwarden credentials
   

3. Install Bitwarden CLI (if not already installed):

   ./secrets-manager.sh install
   

4. Test Your Setup:

   ./secrets-manager.sh test
   

5. 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 CLI
• get <secret_name> - Retrieve a specific secret
• list - List all available secrets in your vault
• test - 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:

1. Snap Package (if snapd is available)
2. NPM Global Package (if npm is available)
3. 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:

1. Test all changes thoroughly:

   make ci  # Run full CI pipeline
   

2. Update documentation as needed

3. Follow existing code style and conventions

4. Run security checks:

   make security-check
   

5. 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.