docs: archived — moved to KNEL/secrets per #769
This commit is contained in:
@@ -1,267 +1,7 @@
|
|||||||
# TSYS Secrets Manager
|
# KNELSecretsManager (ARCHIVED — moved to KNEL/secrets)
|
||||||
|
|
||||||
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.
|
This body of work moved to **[KNEL/secrets](https://git.knownelement.com/KNEL/secrets)**
|
||||||
|
per the 2026-09-03 repo split ([#769](https://projects.knownelement.com/issues/769));
|
||||||
|
content ported as (secret-scanned clean).
|
||||||
|
|
||||||
## Features
|
This repo is historical. New secrets-management work happens in KNEL/secrets (#770).
|
||||||
|
|
||||||
- **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**:
|
|
||||||
```bash
|
|
||||||
git clone <repository-url>
|
|
||||||
cd KNELSecretsManager
|
|
||||||
chmod +x secrets-manager.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Create Configuration**:
|
|
||||||
```bash
|
|
||||||
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):
|
|
||||||
```bash
|
|
||||||
./secrets-manager.sh install
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **Test Your Setup**:
|
|
||||||
```bash
|
|
||||||
./secrets-manager.sh test
|
|
||||||
```
|
|
||||||
|
|
||||||
5. **Retrieve Secrets**:
|
|
||||||
```bash
|
|
||||||
./secrets-manager.sh get APIKEY-pushover
|
|
||||||
```
|
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
Create a `bitwarden-config.conf` file based on the provided sample in the `config/` directory:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 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
|
|
||||||
|
|
||||||
```bash
|
|
||||||
./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
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 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
|
|
||||||
|
|
||||||
```bash
|
|
||||||
#!/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. **NPM Global Package** (if npm is available)
|
|
||||||
2. **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
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 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:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 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
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 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](docs/ADR-Node.md) - Analysis of MISE vs system packages for Node.js version management
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
When contributing to this project:
|
|
||||||
|
|
||||||
1. **Test all changes thoroughly**:
|
|
||||||
```bash
|
|
||||||
make ci # Run full CI pipeline
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Update documentation as needed**
|
|
||||||
3. **Follow existing code style and conventions**
|
|
||||||
4. **Run security checks**:
|
|
||||||
```bash
|
|
||||||
make security-check
|
|
||||||
```
|
|
||||||
|
|
||||||
5. **Ensure compatibility with vendor integration**:
|
|
||||||
```bash
|
|
||||||
make vendor-test
|
|
||||||
```
|
|
||||||
|
|
||||||
## Development Commands
|
|
||||||
|
|
||||||
```bash
|
|
||||||
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](LICENSE) file for details.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user