mysec

A CLI tool to sync environment variable secrets with cloud secret stores and GitHub.

Related Projects

The mysec CLI tool is inspired by and compatible with these UDX projects:

• UDX Worker - A secure, multi-cloud-compatible Docker image for CI/CD workflows
• UDX Worker Node.js - Node.js worker service application
• UDX Atlas Engine - Service orchestration and management
• UDX mcurl - CLI tool for making HTTP requests

Installation

npm install -g @udx/mysec

Usage

Initialize Configuration

mysec init

This will create a configuration file at ~/.udx/mysec.yml if it doesn't exist.

Sync Secrets

mysec sync

This will:

1. Fetch secrets from Google Cloud Secret Manager
2. Check GitHub repositories for secrets referenced in workflows
3. Update your local environment file (e.g., ~/.zshrc)

Check for Missing Secrets

mysec check

This will check your GitHub repositories for secrets referenced in workflows, README.md, or package.json that aren't configured.

List Configured Secrets

mysec list

Configuration

The configuration file is located at ~/.udx/mysec.yml and has the following structure:

providers:
  gcp:
    enabled: true
    projectId: your-gcp-project-id
  github:
    enabled: true
    repos:
      - owner/repo
vaults:
  default: gcp
secrets:
  API_KEY: gcp/project-id/api-key
  GITHUB_TOKEN: gcp/project-id/github-token
local:
  shell: zsh
  envFile: ~/.zshrc

Secret Reference Format

Secrets are referenced using a URL-like format:

• Google Cloud Secret Manager: gcp/{project-id}/{secret-name}
• GitHub Actions: github/{owner}/{repo}/{secret-name}

Authentication

Google Cloud Secret Manager

Authentication with Google Cloud uses the standard Google Cloud authentication methods:

1. Set the GCP_CREDS environment variable with the JSON service account key (recommended)
2. Or set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the path of your service account key file
3. Or set the GKE_SA_KEY environment variable with the JSON service account key (for backward compatibility)
4. Or use gcloud CLI: gcloud auth application-default login

See API Documentation for more details on the configuration format and environment variables.

Using GKE_SA_KEY

The GKE_SA_KEY environment variable is the recommended way to authenticate with Google Cloud Secret Manager, especially in CI/CD environments:

# Set the GKE_SA_KEY environment variable with your service account JSON
export GKE_SA_KEY='{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\nkey-content\n-----END PRIVATE KEY-----\n",
  "client_email": "[email protected]",
  "client_id": "client-id",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/service-account%40your-project-id.iam.gserviceaccount.com"
}'

# Then run mysec commands
mysec sync

Setting up GCP Secret Manager Permissions

If your service account lacks Secret Manager permissions, you'll need to enable the API and grant the necessary roles:

# Login with your Google account
gcloud auth login

# Set your project
gcloud config set project YOUR_PROJECT_ID

# Enable the Secret Manager API
gcloud services enable secretmanager.googleapis.com

# Grant Secret Manager access permissions
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:YOUR_SERVICE_ACCOUNT_EMAIL" \
  --role="roles/secretmanager.secretAccessor"

# Grant Secret Manager creation permissions
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member="serviceAccount:YOUR_SERVICE_ACCOUNT_EMAIL" \
  --role="roles/secretmanager.secretVersionAdder"

Replace YOUR_PROJECT_ID with your GCP project ID and YOUR_SERVICE_ACCOUNT_EMAIL with your service account email address.

GitHub

Authentication with GitHub requires a personal access token with appropriate permissions:

1. Set the GITHUB_TOKEN or GITHUB_PAT environment variable

Examples

Sync All Secrets

mysec sync

Check for Missing Secrets in a Repository

cd ~/repos/my-repo
mysec check

Add a New Secret

# Add to Google Cloud Secret Manager and update local config
export MY_NEW_SECRET=value
mysec sync

Docker Usage

You can also use mysec in a Docker container:

Building the Docker Image

# Create a Dockerfile
cat > Dockerfile << 'DOCKERFILE'
FROM node:18-alpine

WORKDIR /app

# Install dependencies
RUN apk add --no-cache git

# Install mysec globally
RUN npm install -g @udx/mysec

# Create config directory
RUN mkdir -p /root/.udx

# Create a simple config file
RUN echo -e "providers:\n  gcp:\n    enabled: true\n    projectId: your-project-id\n  github:\n    enabled: true\n    repos:\n      - owner/repo\nvaults:\n  default: gcp\nsecrets: {}\nlocal:\n  shell: sh\n  envFile: /root/.profile" > /root/.udx/mysec.yml

# Set working directory
WORKDIR /workspace

# Default command
CMD ["mysec", "--help"]
DOCKERFILE

# Build the image
docker build -t mysec .

Running the Container

# Run with help command
docker run --rm mysec

# Run with specific command
docker run --rm mysec mysec list

# Mount your config file
docker run --rm -v ~/.udx:/root/.udx mysec mysec sync

# Mount your local environment file to update it
docker run --rm -v ~/.udx:/root/.udx -v ~/.zshrc:/root/.zshrc mysec mysec sync

# Use with Google Cloud authentication
docker run --rm \
  -v ~/.udx:/root/.udx \
  -v ~/.config/gcloud:/root/.config/gcloud \
  -e GOOGLE_APPLICATION_CREDENTIALS=/root/.config/gcloud/application_default_credentials.json \
  mysec mysec sync

# Or use with GCP_CREDS environment variable (recommended)
docker run --rm \
  -v ~/.udx:/root/.udx \
  -e GCP_CREDS='{"type":"service_account","project_id":"your-project-id",...}' \
  mysec mysec sync

# Or use with GKE_SA_KEY environment variable (for backward compatibility)
docker run --rm \
  -v ~/.udx:/root/.udx \
  -e GKE_SA_KEY='{"type":"service_account","project_id":"your-project-id",...}' \
  mysec mysec sync

Using as Part of CI/CD Pipeline

# Example GitHub Actions workflow
name: Sync Secrets

on:
  schedule:
    - cron: '0 0 * * *'  # Daily at midnight

jobs:
  sync-secrets:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
      
      - name: Set up Google Cloud Auth
        uses: google-github-actions/auth@v1
        with:
          credentials_json: ${{ secrets.GCP_CREDS }}  # GCP_CREDS is the recommended environment variable
      
      - name: Install mysec
        run: npm install -g @udx/mysec
      
      - name: Create config
        run: |
          mkdir -p ~/.udx
          echo "providers:
            gcp:
              enabled: true
              projectId: ${{ secrets.GCP_PROJECT_ID }}
            github:
              enabled: true
              repos:
                - ${{ github.repository }}
          vaults:
            default: gcp
          secrets: {}" > ~/.udx/mysec.yml
      
      - name: Sync secrets
        run: mysec sync
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Service Mode

You can run mysec as a service to continuously monitor for secret changes:

# Start the service
mysec service start

# Check service status
mysec service status

# Stop the service
mysec service stop

The service mode will:

1. Monitor your environment files for changes
2. Detect new potential secrets based on naming patterns
3. Sync changes between local environment and remote vaults
4. Optionally auto-sync discovered secrets to your configured vault

PM2 Configuration

The service uses PM2 for process management. You can customize the configuration in ecosystem.config.cjs:

module.exports = {
  apps: [{
    name: 'mysec-monitor',
    script: './lib/service/service-runner.js',
    instances: 1,
    autorestart: true,
    max_memory_restart: '100M',
    env: {
      NODE_ENV: 'production',
      DEBUG: 'mysec:service',
      MYSEC_POLL_INTERVAL: '60000', // 1 minute
      MYSEC_AUTO_SYNC: 'false'      // Set to true to auto-sync discovered secrets
    }
  }]
};

Auto-Sync Mode

When running in service mode, mysec can automatically detect and sync new secrets:

# Start with auto-sync enabled
MYSEC_AUTO_SYNC=true mysec service start

# Or configure in ecosystem.config.cjs
env: {
  MYSEC_AUTO_SYNC: 'true'
}

The auto-sync feature will:

1. Detect environment variables that match secret patterns (API keys, tokens, etc.)
2. Automatically store them in your configured default vault
3. Update your configuration to track these secrets
4. Keep them in sync across environments