🛡️ Overwatch - Secure AI CLI Wrapper

Overwatch is a universal security wrapper for AI CLI tools that adds Javelin Guardrails protection to any AI command-line interface.

⚠️ Platform Support:

• macOS: Full support (Apple Silicon and Intel) with pre-built binaries
• Linux: Supported - requires building from source (see below)
• Windows: Coming soon

Features

• 🔒 Universal AI Tool Wrapping - Secure any AI CLI tool (Claude, llm, aider, etc.)
• 🛡️ Javelin Guardrails Integration - Enterprise-grade security and compliance
• 🚀 Zero Configuration - Works out of the box with sensible defaults
• 🔄 Transparent Proxy - Automatically routes AI requests through security layer
• 📊 Policy Enforcement - Apply custom security policies to AI interactions
• 🎯 MCP Support - Full Model Context Protocol support with security

Installation

macOS (Pre-built binaries)

npm install -g @getjavelin/overwatch

Linux (Build from source)

On Linux, you need to build the proxy binary from source first:

# Install Rust if not already installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and build
git clone https://github.com/getjavelin/javelin-ramparts.git
cd javelin-ramparts
cargo build --release -p ramparts-proxy

# Install the binary
sudo cp target/release/ramparts-proxy /usr/local/bin/

# Now install Overwatch
npm install -g @getjavelin/overwatch

Quick Start

1. Install

npm install -g @getjavelin/overwatch

During installation, you'll be prompted to configure Javelin Guardrails:

🔧 Javelin Guardrails Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Get your API key:
  👉 https://sandbox.javelin.live

Enter your Javelin API Key: ****
Javelin API URL [https://sandbox.javelin.live]:

✅ Configuration saved successfully!

Configuration is saved to ~/.overwatch/config.json and used automatically.

2. Use Overwatch

Simply prefix any AI CLI tool with overwatch:

# Secure Claude CLI - ALL LLM and MCP calls intercepted
overwatch claude "Hello, how are you?"

# Secure llm CLI
overwatch llm "What is the weather today?"

# Secure Gemini
overwatch gemini "Explain quantum computing"

# Works with ANY AI tool
overwatch <your-ai-tool> [args...]

What happens:

• ✅ Loads credentials from ~/.overwatch/config.json
• ✅ Applies default security policy automatically
• ✅ Proxy auto-starts on available port (8081+)
• ✅ Environment variables set to route ALL API calls through proxy
• ✅ Your AI tool runs normally
• ✅ Every LLM call (OpenAI, Anthropic, Google, etc.) → secured
• ✅ Every MCP call (tools, resources, prompts) → secured
• ✅ All requests validated with Javelin Guardrails
• ✅ Secrets automatically blocked/redacted in responses
• ✅ Responses flow back to your tool

No exports needed! Configuration is automatic.

Security Policies

Default Policy (Automatic)

Overwatch automatically installs and applies a comprehensive security policy during installation:

• 📋 Installed to: ~/.overwatch/default-policy.yaml
• 🔄 Auto-updated: Policy file is refreshed on each npm install
• ✅ Secret Detection in Prompts - Blocks prompts containing API keys, tokens, passwords (local + cloud)
• ✅ Secret Detection in Responses - Redacts API keys, AWS keys, SSH keys, JWTs, etc.
• ✅ Jailbreak Protection - Blocks prompt injection and jailbreak attempts
• ✅ SSRF Protection - Blocks requests to private IP ranges
• ✅ File System Protection - Restricts access to sensitive directories (.ssh, .aws, /etc, etc.)
• ✅ Tool Restrictions - Blocks dangerous tools (shell, exec, delete, etc.)
• ✅ MCP Server Controls - Per-server tool and resource restrictions

No configuration needed! The default policy is installed and applied automatically.

Secret Detection (Defense-in-Depth)

Overwatch provides two layers of secret detection:

1. Local Policy (Fast) - Blocks secrets in prompts before they reach the LLM

   • Instant blocking using regex patterns
   • Works offline (no API call needed)
   • Configurable via llm.blockSecrets in policy file

2. Javelin Guardrails (Comprehensive) - Cloud-based AI detection

   • Advanced ML-based PII and secret detection
   • Detects obfuscated or encoded secrets
   • Provides detailed threat analysis

Example blocked prompts:

# ❌ BLOCKED by local policy (instant)
overwatch claude "Use my HF_TOKEN=hf_abc123xyz to download the dataset"

# ❌ BLOCKED by local policy (instant)
overwatch claude "Here's my API_KEY=sk-1234567890 for testing"

# ❌ BLOCKED by Javelin Guardrails (cloud)
overwatch claude "My social security number is 123-45-6789"

To disable local secret blocking (keep Javelin cloud detection only):

# In ~/.overwatch/default-policy.yaml
llm:
  blockSecrets: false  # Disable local secret detection

Custom Policies (Optional)

You can customize the policy by:

1. Editing the default policy directly:

   # Edit the installed default policy
   nano ~/.overwatch/default-policy.yaml

2. Creating a custom policy and updating config:

   # Create your custom policy
   cp ~/.overwatch/default-policy.yaml ~/.overwatch/my-policy.yaml
   nano ~/.overwatch/my-policy.yaml
   
   # Update config.json to use it
   # Edit "policyFile" field in ~/.overwatch/config.json

3. Using environment variable (temporary override):

   export OVERWATCH_POLICY_FILE=./my-policy.yaml
   overwatch claude "test"

Example custom policy (my-policy.yaml):

version: 1
defaultAction: allow

# Block secrets in responses
responseGuards:
  action: block  # or 'redact'
  secretPatterns:
    - type: api_key
      regex: '(?i)(api[_-]?key|apikey)[\s:=]+["\']?([a-zA-Z0-9_\-]{20,})["\']?'
    - type: aws_key
      regex: 'AKIA[0-9A-Z]{16}'

# Restrict file access
fs:
  allow:
    - "${workspace}/**"  # Only workspace files
  deny:
    - "~/.ssh/**"        # Block SSH keys
    - "~/.aws/**"        # Block AWS credentials

# Block dangerous tools
tools:
  deny:
    - "shell"
    - "bash"
    - "exec"

See the default policy file for a complete example.

Configuration

Config File

Configuration is stored in ~/.overwatch/config.json:

{
  "javelin": {
    "apiKey": "your-api-key",
    "apiUrl": "https://sandbox.javelin.live"
  },
  "policyFile": "~/.overwatch/default-policy.yaml",
  "version": "1.0",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Files installed in ~/.overwatch/:

• config.json - Main configuration file
• default-policy.yaml - Default security policy (auto-installed)

Config Commands

# Configure credentials (interactive)
overwatch config set

# Show current configuration
overwatch config show

# Get specific value
overwatch config get JAVELIN_API_KEY

Environment Variables (Optional Overrides)

| Variable | Description | Default | |----------|-------------|---------| | OVERWATCH_POLICY_FILE | Override policy file | From config.json or ~/.overwatch/default-policy.yaml | | OVERWATCH_PROXY_PORT | Use specific proxy port | Auto (8081+) | | OVERWATCH_AUTO_START_PROXY | Disable auto-start | true | | OVERWATCH_VERBOSE | Enable verbose logging | false |

Note: JAVELIN_API_KEY and JAVELIN_API_URL environment variables are ignored. Use overwatch config set to configure credentials.

Examples

Installation & Setup

# Install Overwatch
npm install -g @getjavelin/overwatch

# On first use, Overwatch will prompt for Javelin API credentials
# Or configure manually:
overwatch config set

Basic Usage

# No exports needed! Just use overwatch
# First time you run it, you'll be prompted for Javelin API key
overwatch claude "What is 2+2?"
overwatch llm "Explain AI"
overwatch gemini "Write a haiku"

With Custom Policy

# Use custom policy file
export OVERWATCH_POLICY_FILE=./my-policy.yaml
overwatch claude "Generate a sample API key"  # Blocked by policy

Check Configuration

# Show current config
overwatch config show

# Get specific value
overwatch config get JAVELIN_API_KEY

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

Proprietary - see LICENSE for details.

Support

• 📧 Email: [email protected]
• 💬 Discord: Join our community
• 📚 Docs: https://docs.getjavelin.com
• 🐛 Issues: GitHub Issues

Related Projects

• Javelin - Enterprise AI Gateway
• Ramparts - MCP Security Scanner
• MCP - Model Context Protocol

Made with ❤️ by Javelin