GlobalProtect Automation

A comprehensive macOS automation suite for GlobalProtect VPN connections with Okta/SAML integration, designed for easy configuration and deployment.

📝 Origin: This tool was originally developed for use at Adobe and has been generalized for broader use with GlobalProtect and Okta environments.

Features

Automated VPN Connection: Streamlines GlobalProtect portal entry and authentication
XDG-Compliant: Follows standard directory conventions for configuration and data
Multiple Installation Methods: Install script, Makefile, or manual installation
Configuration Management: YAML-based configuration with fallback support
Comprehensive Testing: Built-in test suite for validation
Quick Access Commands: Wrapper scripts for common operations

Quick Start

Installation

Choose one of the following installation methods:

Method 1: Using Make (Recommended)

make install

Method 2: Using Install Script

./install.sh    # Will automatically offer to configure PATH

Method 3: Manual Installation

# Copy scripts to your PATH
cp bin/globalconnect ~/.local/bin/
cp bin/gc-connect ~/.local/bin/
cp bin/gp-test ~/.local/bin/
chmod +x ~/.local/bin/globalconnect ~/.local/bin/gc-connect ~/.local/bin/gp-test

# Set up configuration
mkdir -p ~/.config/globalprotect-bot
cp config/environment.yaml.template ~/.config/globalprotect-bot/environment.yaml

# Set up data directory and library
mkdir -p ~/.local/share/globalprotect-bot
cp lib/yaml-loader.sh ~/.local/share/globalprotect-bot/

Verify Installation

make test
# or
gp-test

First Use

Configure your VPN settings:
```
gc-connect config
```
Connect to VPN:
```
gc-connect
```

Commands

Once installed, these commands are available in your PATH:

⌨️ Keyboard Shortcuts

You can bind any of these commands to keyboard shortcuts! See utils/README.md for setup instructions using:

Automator (works on all macOS versions)
Shortcuts app (macOS 12+)
Third-party launchers (Alfred, Raycast, etc.)

Quick setup: Use utils/quick-connect.sh in Automator for notifications.

`globalconnect`

Main automation script for GlobalProtect connections.

# Connect with portal URL
globalconnect https://vpn.company.com

# Use configured default portal
globalconnect

# Headless mode (no user interaction)
globalconnect --headless

# With custom timeout
globalconnect --timeout=60

# Show help
globalconnect --help

`gc-connect`

Quick connect wrapper with common operations.

# Interactive connect (default)
gc-connect

# Headless connect
gc-connect headless

# Check status
gc-connect status

# Test connectivity
gc-connect test

# Disconnect
gc-connect disconnect

# Edit configuration
gc-connect config

# Show logs
gc-connect logs

# Show help
gc-connect help

`gp-test`

Test suite for validating installation and functionality.

# Run all tests
gp-test

# Show help
gp-test --help

Configuration

Configuration follows the XDG Base Directory Specification:

Config: ~/.config/globalprotect-bot/
Data/Logs: ~/.local/share/globalprotect-bot/
Binaries: ~/.local/bin/

Configuration Files

The project includes two configuration templates:

Configuration Template: `config/environment.yaml.template`

Generic template ready for customization with your organization's settings:

⚙️ VPN Portal URL placeholder
🔍 Internal test host configuration
🏢 Company details template
📝 Complete configuration options with documentation

Primary Configuration: `environment.yaml`

Edit ~/.config/globalprotect-bot/environment.yaml:

# Company Configuration
company:
  name: "Your Company"
  domain: "company.com"
  
# VPN Configuration
vpn:
  portal_url: "https://vpn.company.com"

# Internal Network Testing
internal_network:
  test_host: "internal.company.com"
  test_protocol: "https"
  test_timeout: 5

# Application Settings
application:
  timeout: 30
  debug: false
  headless: false
  browser: "chrome"

# Logging Configuration
logging:
  level: "INFO"
  keep_days: 7

# Authentication Settings
auth:
  timeout: 300

Legacy Configuration Support

The system also supports the legacy globalconnect-config.conf format for backward compatibility.

Directory Structure

~/.config/globalprotect-bot/          # Configuration
├── environment.yaml                         # Main config file
├── environment.yaml.template               # Template
└── globalconnect-config.conf              # Legacy config (optional)

~/.local/share/globalprotect-bot/    # Data and libraries
├── logs/                                   # Log files
│   └── automation.log
├── temp/                                   # Temporary files
└── yaml-loader.sh                         # Configuration library

~/.local/bin/                               # Executables (in PATH)
├── globalconnect                          # Main script
├── gc-connect                             # Wrapper script
└── gp-test                                # Test script

Development

Project Structure

macos-globalprotect-bot/
├── Makefile                    # Installation automation
├── install.sh                 # Installation script
├── README.md                   # This file
├── bin/                        # Refactored scripts (XDG-compliant)
│   ├── globalconnect          # Main automation script
│   ├── gc-connect             # Quick connect wrapper
│   └── gp-test                # Test suite
├── lib/                        # Libraries
│   └── yaml-loader.sh         # Configuration loader
├── config/                     # Configuration templates
│   ├── environment.yaml.template
│   └── globalconnect-config.conf
└── tests/                      # Original tests (legacy)

Building and Testing

# Check source files
make dev-check

# Install for development
make install

# Run tests
make test

# Check installation
make check

# Clean up
make clean

# Uninstall
make uninstall

Make Targets

make help           # Show all available targets
make install        # Install everything
make uninstall      # Remove installation
make test           # Run test suite
make check          # Check installation status
make config         # Edit configuration
make status         # Check GlobalProtect status
make logs           # Show recent logs
make clean          # Clean temporary files
make version        # Show version info

Features in Detail

Automation Capabilities

Application Detection: Automatically finds GlobalConnect/GlobalProtect
Smart Process Management: Works with existing instances
AppleScript Integration: GUI automation where possible
Fallback Mechanisms: Manual guidance when automation is blocked
Browser Handling: Supports multiple browsers for authentication

Configuration System

YAML Support: Human-readable configuration format
XDG Compliance: Standard directory locations
Environment Variables: Support for runtime configuration
Legacy Compatibility: Backward compatibility with old config format
Validation: Built-in configuration validation

Testing Framework

Comprehensive Tests: Installation, syntax, functionality tests
Dependency Checking: Validates required system components
Network Testing: Connectivity validation
PATH Verification: Ensures proper PATH configuration

Logging and Monitoring

Structured Logging: Timestamped, categorized log entries
Log Rotation: Configurable log retention
Status Monitoring: Connection status checking
Network Validation: Internal network connectivity testing

Troubleshooting

Common Issues

Scripts not found in PATH:

# The installer should have offered to do this automatically
# If not, add to your shell profile (.bashrc, .zshrc, etc.)
export PATH="$HOME/.local/bin:$PATH"

# Or re-run: make install (will ask to configure PATH)

Permission errors:

# Ensure scripts are executable
chmod +x ~/.local/bin/globalconnect ~/.local/bin/gc-connect ~/.local/bin/gp-test

Configuration not found:

# Create default configuration
gc-connect config

AppleScript automation blocked:
- This is normal for security applications
- Follow the manual guidance provided by the script
- Grant accessibility permissions if prompted

Diagnostic Commands

# Check installation
make check
gp-test

# Check configuration
gc-connect info

# View logs
gc-connect logs

# Test connectivity
gc-connect test

# Check status
gc-connect status

Log Files

Logs are written to ~/.local/share/globalprotect-bot/logs/automation.log:

# View recent logs
tail -f ~/.local/share/globalprotect-bot/logs/automation.log

# Or use the wrapper
gc-connect logs

Requirements

macOS: Required (uses macOS-specific tools and APIs)
Bash: 3.2+ (compatible with macOS default)
GlobalProtect/GlobalConnect: Must be installed
curl: For connectivity testing
osascript: For GUI automation (built into macOS)

Security Considerations

No Credential Storage: Scripts do not store or handle credentials
GUI Automation: May require accessibility permissions
AppleScript Limitations: Some operations may be blocked by security policies
Network Testing: Uses configurable internal hosts for validation

Acknowledgments

This tool was originally developed for internal use at Adobe to automate GlobalProtect connections with Okta authentication. It has been generalized and made available for other organizations using similar GlobalProtect and Okta/SAML setups.

License

This project is provided as-is for automation purposes. Please ensure compliance with your organization's security policies and VPN usage guidelines.

Contributing

Test changes thoroughly with make test
Follow XDG directory conventions
Maintain backward compatibility where possible
Update documentation for new features
Ensure cross-compatibility with different macOS versions

Organization Setup

Quick Setup for Your Organization

Copy and customize the configuration template:

git clone <repo-url>/macos-globalprotect-bot.git
cd macos-globalprotect-bot
cp config/environment.yaml.template ~/.config/globalprotect-bot/environment.yaml

Edit the configuration file:

# Edit with your organization's settings
vim ~/.config/globalprotect-bot/environment.yaml

Install and test:
```
make install
gc-connect
```

Configuration customization:

🌐 Your organization's VPN portal URL
🔍 Internal test host for connectivity verification
🏢 Company name and domain
⚙️ Timeout and browser preferences
📝 Authentication and logging settings

Migration from Legacy Version

If upgrading from the original script structure:

Install new version: Run make install
Migrate configuration: Copy settings to ~/.config/globalprotect-bot/environment.yaml
Test installation: Run gp-test
Update workflows: Use new command names (globalconnect, gc-connect)
Clean up old files: Remove old script directories if desired

The new version maintains compatibility with existing workflows while providing better organization and standard compliance.

devstuff/macos-globalprotect-bot