🔐 SecureFlow CLI

SecureFlow is a lightweight, cross-platform CLI tool for securely encrypting and decrypting sensitive files using AES-256 encryption. Built with Go, it provides a simple, reliable way to manage secrets in your projects and CI/CD pipelines.

Perfect for: Environment variables, keystores, SSL certificates, service credentials, API keys, database passwords, and any sensitive configuration files.

✨ Why SecureFlow?

🔒 Strong Security: AES-256-CBC encryption with PBKDF2 key derivation (OpenSSL-compatible)
🚀 Fast & Lightweight: Single binary, no dependencies, instant startup
🌍 Cross-Platform: Works on Linux, macOS, and Windows
🤖 CI/CD Ready: Non-interactive mode designed for automation
📝 Configuration-Based: Simple YAML config for managing multiple files
🧪 Safe Testing: Test decryption without overwriting existing files
📊 Detailed Reports: Track what's encrypted, when, and metadata
💪 Production-Ready: Battle-tested, reliable error handling

🚀 Quick Start

# 1. Install SecureFlow (Linux/macOS)
curl -sSL https://raw.githubusercontent.com/MayR-Labs/secureflow-go/main/install.sh | bash

# 2. Initialize configuration
cd your-project
secureflow init

# 3. Edit secureflow.yaml to list your sensitive files
vim secureflow.yaml

# 4. Encrypt your files
secureflow encrypt

# 5. Commit encrypted files to git
git add enc_keys/ secureflow.yaml
git commit -m "Add encrypted secrets"

# 6. Add originals to .gitignore
echo ".env.prod" >> .gitignore

That's it! Your secrets are now encrypted and safe to commit. Your team can decrypt them with:

secureflow decrypt

🔧 Installation

Quick Install (Linux/macOS)

The easiest way to install SecureFlow:

curl -sSL https://raw.githubusercontent.com/MayR-Labs/secureflow-go/main/install.sh | bash

Or with wget:

wget -qO- https://raw.githubusercontent.com/MayR-Labs/secureflow-go/main/install.sh | bash

Manual Installation

Download Pre-built Binary

Download the appropriate binary for your OS from the Releases page.

Linux (AMD64):

wget https://github.com/MayR-Labs/secureflow-go/releases/latest/download/secureflow-linux-amd64
chmod +x secureflow-linux-amd64
sudo mv secureflow-linux-amd64 /usr/local/bin/secureflow

macOS (Intel):

wget https://github.com/MayR-Labs/secureflow-go/releases/latest/download/secureflow-darwin-amd64
chmod +x secureflow-darwin-amd64
sudo mv secureflow-darwin-amd64 /usr/local/bin/secureflow

macOS (Apple Silicon):

wget https://github.com/MayR-Labs/secureflow-go/releases/latest/download/secureflow-darwin-arm64
chmod +x secureflow-darwin-arm64
sudo mv secureflow-darwin-arm64 /usr/local/bin/secureflow

Windows: Download secureflow-windows-amd64.exe from the Releases page and add it to your PATH.

Build from Source

git clone https://github.com/MayR-Labs/secureflow-go.git
cd secureflow-go
go build -o secureflow
sudo mv secureflow /usr/local/bin/

Local Installation for CI/CD

SecureFlow provides a convenient install-local command that sets up a portable installation without requiring system-wide installation. This is perfect for CI/CD pipelines where you can't or don't want to install binaries globally.

# Run this once to set up local installation
secureflow install-local

This command will:

Download platform-specific executables (Linux, macOS, Windows) to .secureflow/ directory
Create a secureflow.sh launcher script in the current directory
The launcher automatically detects your platform and runs the correct executable

Usage in CI/CD:

# In your CI/CD pipeline
./secureflow.sh decrypt --password "$SECUREFLOW_PASSWORD" --non-interactive
./secureflow.sh encrypt --password "$SECUREFLOW_PASSWORD" --non-interactive

Benefits:

✅ No system installation required
✅ Works across different platforms automatically
✅ Portable - commit .secureflow/ and secureflow.sh to your repo
✅ Perfect for CI/CD environments with restricted permissions

Example: Using in GitHub Actions

Option A: Install during CI/CD run

steps:
  - uses: actions/checkout@v3
  
  - name: Setup SecureFlow locally
    run: |
      wget https://github.com/MayR-Labs/secureflow-go/releases/latest/download/secureflow-linux-amd64
      chmod +x secureflow-linux-amd64
      ./secureflow-linux-amd64 install-local
  
  - name: Decrypt secrets
    run: ./secureflow.sh decrypt --password "${{ secrets.SECUREFLOW_PASSWORD }}" --non-interactive

Option B: Commit installation to repo (no CI/CD setup needed)

# Run locally once
secureflow install-local
git add .secureflow/ secureflow.sh
git commit -m "Add portable SecureFlow"

Then your CI/CD workflow is simply:

steps:
  - uses: actions/checkout@v3
  
  - name: Decrypt secrets
    run: ./secureflow.sh decrypt --password "${{ secrets.SECUREFLOW_PASSWORD }}" --non-interactive

Verify Installation

secureflow --version

💻 Usage

Initialize Configuration

Create a default secureflow.yaml configuration file:

secureflow init

Use a project template for quick setup:

# Interactive template selection
secureflow init

# Or specify a template directly
secureflow init --template flutter
secureflow init --template reactnative
secureflow init --template web
secureflow init --template docker
secureflow init --template k8s
secureflow init --template microservices

Available templates:

default - React Native/Mobile app with Android/iOS files
reactnative - React Native specific configuration
flutter - Flutter mobile app configuration
web - Web application with multiple environments
docker - Docker deployment configuration
k8s - Kubernetes secrets configuration
microservices - Microservices architecture with multiple services

All templates include copy_to: .env for .env.prod files to automatically create .env after decryption.

This generates a configuration file like:

# secureflow.yaml (Flutter template example)
output_dir: enc_keys
test_output_dir: test_dec_keys

files:
  - input: .env.prod
    output: .env.prod.encrypted
    copy_to: .env
  - input: android/app/keystore.jks
    output: keystore.jks.encrypted

Edit this file to match your project's sensitive files.

Encrypt Files

Interactive mode (prompts for password and optional hint):

secureflow encrypt

Non-interactive mode (for scripts and CI/CD):

secureflow encrypt --password "your_password" --non-interactive

Custom config file:

secureflow encrypt --config ./path/to/custom-config.yaml

All encrypted files are saved to enc_keys/ (or your configured output_dir).

Decrypt Files

Interactive mode:

secureflow decrypt

Non-interactive mode (for CI/CD):

secureflow decrypt --password "$ENCRYPTION_PASSWORD" --non-interactive

Custom config file:

secureflow decrypt --config ./custom-config.yaml

Test Decryption

Test decryption without overwriting existing files (decrypts to test_dec_keys/):

secureflow test

Or non-interactively:

secureflow test --password "your_password" --non-interactive

View Help

secureflow --help
secureflow init --help
secureflow encrypt --help
secureflow decrypt --help
secureflow test --help
secureflow install-local --help

📝 Configuration

SecureFlow uses a YAML configuration file (secureflow.yaml) to define which files to encrypt/decrypt.

Basic Configuration

output_dir: enc_keys           # Where encrypted files are stored
test_output_dir: test_dec_keys # Where test decryption outputs go

files:
  - input: .env.production       # Source file (relative to project root)
    output: .env.production.encrypted  # Encrypted filename
    copy_to: .env                # (Optional) Copy decrypted file to this path

  - input: config/database.yml
    output: database.yml.encrypted
    
  - input: ssl/private.key
    output: ssl-private.key.encrypted

Configuration Options

output_dir: Directory for encrypted files (committed to git)
test_output_dir: Directory for test decryption (added to .gitignore)
files: Array of file entries
- input: Path to source file (relative to project root)
- output: Encrypted filename (just filename, not path)
- copy_to: (Optional) Copy decrypted file to this path - useful when apps expect .env but you store .env.prod

The `copy_to` Feature

When decrypting files, SecureFlow can automatically copy the decrypted file to another location. This is particularly useful for environment files where your application expects .env but you store .env.prod or .env.production:

files:
  - input: .env.prod
    output: .env.prod.encrypted
    copy_to: .env  # Automatically creates .env from .env.prod after decryption

After decryption, both .env.prod and .env will exist with identical content.

Example Configurations

See the Configuration Guide for detailed examples including:

Mobile apps (Flutter, React Native)
Web applications
Microservices
Docker deployments
Kubernetes secrets
Multi-environment setups

Quick example configs:

🤖 CI/CD Integration

SecureFlow is designed to work seamlessly in CI/CD pipelines with its non-interactive mode.

Method 1: Local Installation (Recommended)

The easiest approach for CI/CD is to use install-local which creates a portable installation.

Approach A: Download and install during each CI/CD run

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      # Download and setup SecureFlow (no sudo required)
      - name: Setup SecureFlow
        run: |
          wget https://github.com/MayR-Labs/secureflow-go/releases/latest/download/secureflow-linux-amd64
          chmod +x secureflow-linux-amd64
          ./secureflow-linux-amd64 install-local
      
      # Use the launcher script
      - name: Decrypt secrets
        run: |
          ./secureflow.sh decrypt --password "${{ secrets.SECUREFLOW_PASSWORD }}" --non-interactive
      
      # Build and deploy
      - name: Build & Deploy
        run: |
          npm run build
          ./deploy.sh

Approach B: Commit the local installation to your repo (Recommended for simplicity)

Run secureflow install-local once locally, then commit the files:

# Run locally (one-time setup)
secureflow install-local
git add .secureflow/ secureflow.sh
git commit -m "Add portable SecureFlow installation"
git push

Your CI/CD workflow becomes very simple (no installation step needed):

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      # No installation needed - files are already in the repo!
      - name: Decrypt secrets
        run: |
          ./secureflow.sh decrypt --password "${{ secrets.SECUREFLOW_PASSWORD }}" --non-interactive
      
      # Build and deploy
      - name: Build & Deploy
        run: |
          npm run build
          ./deploy.sh

Method 2: Global Installation

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      # Install SecureFlow globally
      - name: Install SecureFlow
        run: |
          wget https://github.com/MayR-Labs/secureflow-go/releases/latest/download/secureflow-linux-amd64
          chmod +x secureflow-linux-amd64
          sudo mv secureflow-linux-amd64 /usr/local/bin/secureflow
      
      # Decrypt secrets
      - name: Decrypt secrets
        run: |
          secureflow decrypt --password "${{ secrets.SECUREFLOW_PASSWORD }}" --non-interactive
      
      # Build and deploy
      - name: Build & Deploy
        run: |
          npm run build
          ./deploy.sh

Supported Platforms

SecureFlow works with all major CI/CD platforms:

GitHub Actions ✅
GitLab CI ✅
Bitbucket Pipelines ✅
Jenkins ✅
CircleCI ✅
Azure Pipelines ✅
Travis CI ✅
Any CI/CD platform that can run shell commands ✅

Complete CI/CD Guide

See our comprehensive CI/CD Usage Guide for:

Platform-specific setup instructions
Best practices for secrets management
Multi-environment configurations
Caching strategies
Security considerations
Troubleshooting CI/CD issues

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

Core Documentation

Configuration Guide - Detailed configuration options, examples, and best practices
CI/CD Usage Guide - Complete guide for integrating SecureFlow into your CI/CD pipelines
Security Guide - Security best practices, encryption details, and compliance considerations
Troubleshooting - Common issues, solutions, and debugging tips

Additional Resources

Examples Directory - Practical usage examples and sample configurations
- Usage Examples - Real-world usage scenarios
- Sample Configs - Configuration templates for different project types

🔐 Security

Encryption Details

Algorithm: AES-256-CBC (Advanced Encryption Standard, 256-bit)
Key Derivation: PBKDF2 with SHA-256
Format: OpenSSL-compatible (Salted__ header + 8-byte salt + encrypted data)
Compatibility: Files can be encrypted/decrypted with OpenSSL

Security Model

Passwords are never stored or logged
Strong encryption (AES-256-CBC) with proper key derivation (PBKDF2)
OpenSSL compatible - industry-standard format
Non-interactive mode for secure CI/CD integration
Clean password handling - passwords cleared from memory after use

Best Practices

✅ DO:

Use strong passwords (16+ characters, mixed case, numbers, symbols)
Store passwords in password managers
Rotate passwords periodically (every 3-6 months)
Use different passwords for different environments
Keep plaintext secrets in .gitignore
Commit only encrypted files to version control

❌ DON'T:

Commit plaintext secrets to git
Share passwords via email or Slack
Reuse passwords across projects
Log or print passwords
Store passwords in code or config files

For comprehensive security guidance, see our Security Guide.

📊 Encryption Reports

Each encryption run generates a report.txt in your output directory with detailed metadata:

Encryption Report
=================
Note: Encrypted secrets for CI/CD
Password Hint: For the wise only
Created at: 2025-10-24
=================

File:           .env.prod
Encrypted As:   .env.prod.encrypted
Size (bytes):   348
Lines:          17
Last Modified:  2025-10-22 11:24:09
----------------------------------------

This helps you track:

What files are encrypted
When they were encrypted
Password hints for team reference
File sizes and metadata

🎯 Common Use Cases

Local Development

Decrypt secrets when setting up a new project:

# Clone project
git clone https://github.com/yourorg/your-project.git
cd your-project

# Install SecureFlow
curl -sSL https://raw.githubusercontent.com/MayR-Labs/secureflow-go/main/install.sh | bash

# Decrypt secrets (get password from team)
secureflow decrypt

CI/CD Deployment

Option 1: Using install-local (recommended)

# One-time setup
secureflow install-local

# In your CI/CD pipeline
./secureflow.sh decrypt --password ${{ secrets.SECUREFLOW_PASSWORD }} --non-interactive

Option 2: Global installation

- name: Decrypt secrets
  run: secureflow decrypt --password ${{ secrets.SECUREFLOW_PASSWORD }} --non-interactive

Portable CI/CD Setup

For teams that want a fully portable solution, commit the local installation to your repo:

# One-time setup in your repository
secureflow install-local
git add .secureflow/ secureflow.sh
git commit -m "Add portable SecureFlow installation"

# Your CI/CD config becomes very simple:
# - name: Decrypt secrets
#   run: ./secureflow.sh decrypt --password "$PASSWORD" --non-interactive

This approach:

✅ No installation step needed in CI/CD
✅ Works across all platforms automatically
✅ Consistent versions across all environments
✅ Faster CI/CD runs (no download/install time)

Team Onboarding

New team member joining:

Install SecureFlow
Clone repository
Get decryption password from team lead (via secure channel)
Run secureflow decrypt
Start working!

Environment Management

Manage secrets across multiple environments:

# Production
secureflow encrypt --config secureflow.prod.yaml --password "$PROD_PASS"

# Staging
secureflow encrypt --config secureflow.staging.yaml --password "$STAGING_PASS"

# Development
secureflow encrypt --config secureflow.dev.yaml --password "$DEV_PASS"

🧩 Project Structure

secureflow-go/
│
├── cmd/                    # CLI commands (Cobra)
│   ├── root.go            # Root command and global flags
│   ├── encrypt.go         # Encryption command
│   ├── decrypt.go         # Decryption command
│   ├── test.go            # Test decryption command
│   ├── init.go            # Initialize config command
│   ├── install_local.go   # Local installation command
│   └── secureflow.sh      # Launcher script template
│
├── internal/              # Internal packages
│   ├── crypto/           # Encryption/decryption logic
│   ├── config/           # Configuration handling
│   └── utils/            # Utilities (file ops, logging)
│
├── docs/                 # Comprehensive documentation
│   ├── configuration.md  # Configuration guide
│   ├── cicd-usage.md    # CI/CD integration guide
│   ├── security.md      # Security best practices
│   └── troubleshooting.md # Troubleshooting guide
│
├── examples/             # Usage examples
│   ├── README.md        # Practical examples
│   └── configs.md       # Sample configurations
│
├── main.go              # Application entry point
├── install.sh           # Installation script
├── go.mod               # Go module definition
├── LICENSE              # MIT License
└── README.md            # This file

🧱 Error Handling

SecureFlow provides clear, actionable error messages:

Missing files → Warns and skips, continues with other files
Wrong password → Clear error message with exit code 1
Invalid YAML → Shows line number and syntax error
Missing directories → Automatically creates them
Interrupts (Ctrl+C) → Graceful exit with cleanup notice

🧪 Development

Run Locally

go run main.go encrypt
go run main.go decrypt
go run main.go test
go run main.go init

Run Tests

go test ./...

With verbose output:

go test ./... -v

Build Binary

go build -o secureflow

Cross-compile for different platforms:

# Linux AMD64
GOOS=linux GOARCH=amd64 go build -o secureflow-linux-amd64

# macOS Intel
GOOS=darwin GOARCH=amd64 go build -o secureflow-darwin-amd64

# macOS Apple Silicon
GOOS=darwin GOARCH=arm64 go build -o secureflow-darwin-arm64

# Windows
GOOS=windows GOARCH=amd64 go build -o secureflow-windows-amd64.exe

🧭 Roadmap

Future enhancements we're considering:

Support for .env key filtering (only encrypt certain variables)
Optional GPG-based encryption backend
Progress bars for large files
Batch re-encryption command
Integration with Flutter build runners
Support for multiple encryption backends
Vault/secret manager integration
Shell completion scripts

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch: git checkout -b feature/AmazingFeature
Make your changes
Run tests: go test ./...
Commit your changes: git commit -m 'Add some AmazingFeature'
Push to the branch: git push origin feature/AmazingFeature
Open a Pull Request

Development Guidelines

Follow Go best practices and conventions
Add tests for new features
Update documentation as needed
Keep commits focused and descriptive
Ensure all tests pass before submitting PR

📄 License

SecureFlow is licensed under the MIT License.

🔗 Links

GitHub Repository - Source code and issues
Latest Releases - Download binaries
Documentation - Comprehensive guides
Examples - Practical usage examples
MayR Labs - Our website
Report Issues - Bug reports and feature requests

🙏 Acknowledgments

SecureFlow is built with these excellent libraries:

Cobra - CLI framework
yaml.v3 - YAML parsing
Go standard library - Crypto, file I/O, and more

Special thanks to all contributors and users who help make SecureFlow better!

⭐ Star Us!

If you find SecureFlow useful, please consider giving us a star on GitHub! It helps others discover the project.

Made with ❤️ by MayR Labs

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github		.github
cmd		cmd
docs		docs
internal		internal
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh
main.go		main.go

License

MayR-Labs/secureflow-go

Folders and files

Latest commit

History

Repository files navigation