Skip to content

yamonco/ward

BranchesTags

Repository files navigation

Ward Security System

Ward Security System

License: MIT

Ward is a lightweight permission management system that protects your terminal interactions with AI assistants and human collaborators. It prevents unauthorized actions while providing intelligent guidance for the next steps.

🤖 Why Ward is Essential

In today's AI-driven development environment, tools like Claude, GitHub Copilot, and ChatGPT have become indispensable partners in coding. However, these powerful AI assistants sometimes attempt actions that could:

  • ❌ Delete important files by mistake
  • ❌ Modify system configurations unintentionally
  • ❌ Execute harmful commands with full system access
  • ❌ Access sensitive data beyond project boundaries
  • ❌ Make irreversible changes without human oversight

Ward acts as a intelligent safety layer that:

  • ✅ Protects your system from AI overreach
  • ✅ Guides AI assistants with clear constraints
  • ✅ Educates both AI and humans about safe operations
  • ✅ Maintains productivity while ensuring security

🚀 Key Features

🛡️ AI Safety & Security

  • Terminal Integration: Seamlessly integrates with your existing shell
  • Command Filtering: Whitelist/blacklist dangerous commands automatically
  • Directory Protection: Restrict AI access to sensitive system directories
  • Real-time Monitoring: Track and log all AI-initiated actions
  • Smart Suggestions: Provide safe alternatives to blocked operations

🤝 AI-Human Collaboration

  • Permission Prompts: AI assistants can ask for permission before actions
  • Contextual Guidance: Intelligent hints about what operations are safe
  • Progress Tracking: Monitor AI work progress with structured feedback
  • Safe Experimentation: Allow AI to work within defined boundaries

⚡ Lightweight & Fast

  • Zero Configuration: Works out of the box with sensible defaults
  • Minimal Overhead: No noticeable impact on terminal performance
  • Simple Setup: One-command installation and activation
  • Cross-platform: Linux, macOS, and Windows support

🎯 Perfect Use Cases

AI Assistant Integration

# Claude wants to modify files - Ward checks permissions
claude> "I'll help you refactor the authentication module"
ward> ✅ Command allowed: ls, cat, grep, sed in src/auth/
ward> 🎯 Suggestion: Use 'ward-cli handle add' to track this task

# Copilot attempts system-wide changes
copilot> "Let me update system configurations"
ward> ❌ BLOCKED: System directory access denied
ward> 💡 Hint: Use 'ward-cli check /etc' to see what's allowed

Team Collaboration Safety

# New team member joins project
developer> "I'll clean up the project structure"
ward> ✅ Basic file operations allowed in current directory
ward> ⚠️  WARNING: rm commands require explicit permission
ward> 📝 Use 'ward-cli comment' to document destructive changes

Learning & Development

# Learning environment for students
student> "I want to understand system internals"
ward> 📚 Safe exploration mode activated
ward> 🔒 Sensitive system areas protected
ward> 💡 Educational hints provided for each command

📦 Installation

Ward offers multiple installation methods. Choose the one that best fits your workflow:

🚀 Quick Install (Recommended)

# One-click installation with Claude Desktop integration
curl -sSL https://raw.githubusercontent.com/yamonco/ward/main/install.sh | bash

# Or clone and run the installer
git clone https://github.com/yamonco/ward.git
cd ward
./install.sh

📦 Package Installation

Choose your preferred installation method:

🔧 UV (Permanent Installation) - Recommended for Daily Use

# Install permanently with UV (system-wide)
uv tool install "git+https://github.com/yamonco/ward.git[mcp]"

# Commands available immediately after installation
ward --version
ward status
ward init

# 🎯 Permanent Installation Benefits:
# ✅ Commands available immediately from PATH
# ✅ Fast execution (no re-download)
# ✅ Persistent across shell sessions
# ✅ Ideal for daily development

⚡ UVX (Temporary/On-demand) - Great for Testing

# Run on-demand with UVX (no installation)
uvx --from git+https://github.com/yamonco/ward.git ward --version
uvx --from git+https://github.com/yamonco/ward.git ward status
uvx --from git+https://github.com/yamonco/ward.git ward init

# 🎯 UVX Usage Benefits:
# ✅ No system changes required
# ✅ Always latest version
# ✅ Isolated from other tools
# ✅ Perfect for CI/CD and testing

🤖 MCP Integration

# UV (Permanent) - Automatic MCP setup
uv tool install "git+https://github.com/yamonco/ward.git[mcp]"
ward-mcp add --target claude-code
ward-mcp add --target claude-desktop

# UVX (Temporary) - Manual MCP setup
uvx --from git+https://github.com/yamonco/ward.git ward-mcp add --target claude-code
uvx --from git+https://github.com/yamonco/ward.git ward-mcp add --target claude-desktop

🏗️ Local Development Installation

# Clone the repository
git clone https://github.com/yamonco/ward.git
cd ward

# Run local installation script
./setup-ward.sh

What the Setup Script Does:

  • ✅ Installs Ward to ~/.ward/ (local only)
  • ✅ Creates local wrapper at ~/.local/bin/ward (optional)
  • ✅ Sets up MCP server for AI integration
  • ✅ No global system changes
  • ✅ No PATH modifications
  • ✅ No system-wide installations

After Installation:

# Use Ward directly
~/.ward/ward --version

# Or add local bin to PATH (optional)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
ward --version

🏁 Quick Start with AI

Choose your preferred installation method:

🔧 Method 1: UV Permanent Installation (Recommended)

Step 1: Install Ward Permanently

# Install Ward with MCP support permanently
uv tool install "git+https://github.com/yamonco/ward.git[mcp]"

# 🎯 UV Benefits:
# ✅ Commands available immediately: ward, ward-mcp, ward-mcp-server
# ✅ Fast execution - no download delays
# ✅ Persistent across all shell sessions
# ✅ Perfect for daily development work

Step 2: Create AI-Safe Environment

# Create AI-ready project
mkdir ai-secure-project
cd ai-secure-project

# Set up AI-friendly policies
ward init

# Verify AI safety setup
ward status

Step 3: Configure AI Integration

# Configure Claude Desktop/Claude Code for AI integration
ward-mcp add --target claude-code
ward-mcp add --target claude-desktop

# Check MCP installation status
ward-mcp status

# 🛡️ Ward Environment Activation (Optional)
ward activate  # Adds 🛡️ to your prompt for visual indication

⚡ Method 2: UVX Temporary Usage (Testing/CI)

Step 1: Run Ward On-Demand

# Create AI-ready project
mkdir ai-secure-project
cd ai-secure-project

# Set up AI-friendly policies with UVX (no installation)
uvx --from git+https://github.com/yamonco/ward.git ward init

# Verify AI safety setup
uvx --from git+https://github.com/yamonco/ward.git ward status

# 🎯 UVX Benefits:
# ✅ No system changes required
# ✅ Always gets the latest version
# ✅ Isolated from other tools
# ✅ Perfect for CI/CD and testing environments

Step 2: Configure AI Integration

# Configure Claude Desktop/Claude Code
uvx --from git+https://github.com/yamonco/ward.git ward-mcp add --target claude-code
uvx --from git+https://github.com/yamonco/ward.git ward-mcp add --target claude-desktop

# Check MCP status
uvx --from git+https://github.com/yamonco/ward.git ward-mcp status

🤖 Step 4: Start AI Collaboration

# Check policies for current directory
ward check  # UV installed
# OR
uvx --from git+https://github.com/yamonco/ward.git ward check  # UVX

# Your AI assistant now works within Ward's security boundaries!
# Claude, Copilot, and ChatGPT automatically receive guidance about allowed operations

🛡️ Visual Distinction with Prompt Enhancement

# Activate Ward environment for visual prompt distinction
ward activate

# Your prompt changes:
# Before: user@hostname:~/project$
# After:  🛡️ user@hostname:~/project$

# Deactivate when done
ward deactivate

🤖 AI Assistant Integration Examples

Claude + Ward Synergy

# Claude wants to help with code refactoring
claude> "I'll analyze and improve your codebase structure"
ward> ✅ AI assistance mode activated
ward> 📊 Current project: 15 files, 3 directories
ward> 🎯 Safe operations: read, analyze, suggest modifications
ward> ❌ Restricted: file deletion, system changes

# Claude gets intelligent guidance
ward> 💡 For refactoring, consider:
#   1. Read existing code with 'cat' and 'grep'
#   2. Create analysis file with suggestions
#   3. Use 'ward-cli handle add' to track changes

GitHub Copilot + Ward Protection

# Copilot suggests system modifications
copilot> "Let me optimize your development environment"
ward> 🔍 Checking suggested commands...
ward> ⚠️  Potentially risky: 'npm install -g some-package'
ward> 🛡️ Protection: Requires manual confirmation
ward> 💡 Safer alternative: 'npm install --save-dev some-package'

ChatGPT + Ward Boundaries

# ChatGPT explores your project
chatgpt> "I'll help you understand the codebase"
ward> 📚 Project Analysis Mode: ON
ward> ✅ Allowed: 'find', 'grep', 'cat', 'head', 'tail'
ward> 📊 Progress: 5/15 files analyzed
ward> 💡 Next suggestion: Check 'README.md' for project overview

🔧 Advanced Configuration

AI-Specific Policy Examples

# AI Development Environment
echo "@description: AI-Optimized Development
@whitelist: ls cat pwd echo grep sed awk git python node npm yarn
@ai_whitelist: handle comment analyze suggest review
@ai_restrictions: no_file_deletion, no_system_access
@ai_guidance_level: detailed
@ai_operation_limit: 50" > .ward

# Learning Environment
echo "@description: Educational AI Sandbox
@whitelist: ls cat echo grep head tail wc find
@ai_mode: educational
@ai_explain_denials: true
@ai_suggest_alternatives: true
@ai_progress_hints: true" > .ward

AI Permission Management

# Allow specific AI operations
ward-cli ai allow "file_modification" --scope "src/"

# Review AI activity
ward-cli ai audit --last 24h

# Set AI operation limits
ward-cli ai limit --operations 100 --timeframe "1 hour"

🛠️ Usage with AI Assistants

Real-time AI Protection

# Ward automatically intercepts and guides AI commands
$ ai_assistant_suggests_delete_ward_config
ward> 🚫 BLOCKED: Attempting to modify Ward configuration
ward> 💡 AI Assistant: This action requires explicit permission
ward> 📋 To proceed: Use 'ward-cli ai override --confirm' with justification

# Ward provides safe alternatives
ward> ✅ Suggested safe alternative:
#   - Review configuration with 'ward-cli config show'
#   - Create backup with 'ward-cli export config-backup.json'
#   - Submit change request with 'ward-cli ai request-change'

AI Task Tracking

# Track AI-assisted work
ward-cli ai track start "API refactoring" --model claude-3.5
ward-cli ai track add-file "modified auth.py" --ai-generated
ward-cli ai track add-comment "Improved error handling" --ai-explanation
ward-cli ai track complete --verified

# Generate AI work report
ward-cli ai report --format markdown --include-suggestions

📊 AI Integration Benefits

Enhanced AI Safety

  • Prevents accidental data loss from AI mistakes
  • Blocks unauthorized system access attempts
  • Provides educational feedback for AI learning
  • Maintains audit trail of all AI operations

Improved AI Productivity

  • Clear boundaries help AI work more effectively
  • Intelligent suggestions speed up development
  • Context-aware guidance reduces trial and error
  • Safe experimentation encourages innovation

Team Collaboration

  • Consistent AI behavior across team members
  • Shared AI policies for project safety
  • Centralized AI activity monitoring and review
  • Onboarding assistance for new AI users

🔧 MCP Integration for AI Assistants

Ward now provides Model Context Protocol (MCP) integration, enabling direct communication with AI assistants through a standardized protocol.

🤖 What is MCP Integration?

MCP allows AI assistants to:

  • Directly access Ward security tools without shell interaction
  • Execute security operations through standardized API calls
  • Receive real-time feedback on policy compliance
  • Work more efficiently with built-in AI guidance

🚀 Quick MCP Setup

🔧 Option 1: UV Permanent Installation

# Install Ward with MCP integration permanently
uv tool install "git+https://github.com/yamonco/ward.git[mcp]"

# 🎯 What gets installed:
# ✅ Ward CLI (ward, ward-mcp, ward-mcp-server)
# ✅ MCP server for AI integration
# ✅ Required dependencies (mcp, fastmcp)
# ✅ Commands available immediately from PATH
# ✅ Persistent across shell sessions

⚡ Option 2: UVX Temporary Usage

# Run Ward with MCP integration on-demand
uvx --from git+https://github.com/yamonco/ward.git ward-mcp status

# 🎯 UVX Benefits:
# ✅ No installation required
# ✅ Always latest version
# ✅ Isolated execution
# ✅ Perfect for testing and CI/CD

🤖 Configure Claude Desktop/Claude Code

UV (Permanent):

ward-mcp add --target claude-code
ward-mcp add --target claude-desktop

UVX (Temporary):

uvx --from git+https://github.com/yamonco/ward.git ward-mcp add --target claude-code
uvx --from git+https://github.com/yamonco/ward.git ward-mcp add --target claude-desktop

✅ Verify MCP Integration

# UV Installed
ward-mcp status

# UVX Temporary
uvx --from git+https://github.com/yamonco/ward.git ward-mcp status

# Show available MCP tools
ward-mcp info

🎯 Supported AI Assistants

Claude Desktop Integration

# Claude will now have access to Ward tools directly:
claude> ward_check ./src
claude> ward_status
claude> ward_create_policy --description "AI development" --ai_mode enabled
claude> ward_allow_operation --operation file_modification --justification "Bug fixes"

Custom AI Integration

# Any MCP-compatible AI can use Ward tools
from mcp import Client

async def use_ward():
    client = Client()

    # Check security policies
    result = await client.call_tool("ward_check", {"path": "./src"})
    print(result.content[0].text)

    # Get system status
    status = await client.call_tool("ward_status", {})
    print(status.content[0].text)

📋 MCP Tools Available

Tool Description Use Case
ward_check Check security policies for a path Verify AI access before operations
ward_status Get overall Ward system status Monitor security state
ward_validate Validate all security policies Ensure policy consistency
ward_allow_operation Allow specific AI operations Grant temporary permissions
ward_ai_log Get recent AI activity log Monitor AI behavior
ward_create_policy Create security policies Set up project constraints

🔧 Advanced MCP Configuration

Claude Desktop/Claude Code Configuration

{
  "mcpServers": {
    "ward-security": {
      "command": "uvx",
      "args": ["git+https://github.com/yamonco/ward.git", "ward-mcp-server"],
      "description": "Ward Security System - AI Assistant Protection"
    }
  }
}

Custom MCP Client Setup

# ward_mcp_client.py
import asyncio
from mcp import Client

class WardSecurityClient:
    def __init__(self):
        self.client = Client()

    async def check_path(self, path: str):
        """Check if path is safe for AI operations"""
        result = await self.client.call_tool("ward_check", {"path": path})
        return result.content[0].text

    async def create_safe_policy(self, description: str, ai_mode: str = "enabled"):
        """Create AI-safe policy"""
        return await self.client.call_tool("ward_create_policy", {
            "description": description,
            "ai_mode": ai_mode,
            "whitelist": ["ls", "cat", "grep", "python", "git"],
            "ai_guidance": True
        })

🎯 MCP Integration Benefits

  • 🚀 Faster AI Response: Direct API calls without shell overhead
  • 🛡️ Enhanced Security: Policy validation at MCP level
  • 📊 Better Monitoring: Structured logging and audit trails
  • 🔧 Flexible Integration: Works with any MCP-compatible AI
  • ⚡ Real-time Feedback: Immediate policy compliance checking

📚 MCP Documentation

🔧 MCP Management Commands

Easy Claude Desktop Integration

# Install Ward with MCP support and configure Claude Desktop automatically
ward-mcp install

# Add Ward to Claude Desktop (if already installed)
ward-mcp add

# Remove Ward from Claude Desktop
ward-mcp remove

# Check installation status
ward-mcp status

# Show available MCP tools
ward-mcp info

Package Management

🔧 UV (Permanent Installation)

# Update to latest version
uv tool install --force "git+https://github.com/yamonco/ward.git[mcp]"

# Uninstall completely
uv tool uninstall ward-security

# Check installed version
ward --version

# List installed UV tools
uv tool list | grep ward

⚡ UVX (Temporary Usage)

# No update needed - always gets latest version
# Just run the command to get latest features

# Clean UVX cache (if needed)
uvx --clear-cache

# Run specific version (if needed)
uvx --from git+https://github.com/yamonco/ward.git@v2.0.3 ward --version

📊 When to Choose Which Method

Use Case Recommendation Why
Daily Development UV Permanent Fast execution, persistent, convenient
CI/CD Pipelines UVX Temporary No installation, always latest, isolated
Testing/Trying UVX Temporary Clean environment, easy cleanup
Team Setup UV Permanent Consistent environment, easy management
Single Project Either Depends on your workflow preference

🚀 Getting Started with AI

  1. Install Ward in your development environment
  2. Set up MCP integration with ward-mcp add
  3. Create AI-safe project policies with ward init
  4. Restart Claude Desktop to activate MCP integration
  5. Start collaborating with your AI assistants
  6. Monitor and refine AI interactions over time

🤝 Contributing

We welcome contributions to enhance AI safety and collaboration! See our CONTRIBUTING.md for guidelines.

  1. Fork this repository
  2. Create a feature branch for AI enhancements
  3. Test thoroughly with various AI assistants
  4. Submit your Pull Request with AI use cases

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🆘 Support

🏢 yamonco

Ward is developed and maintained by yamonco with a focus on AI-human collaboration safety.

❤️ Sponsors

If Ward helps you work safely with AI assistants, please consider supporting us:

Sponsor yamonco

Your support helps us enhance AI safety features and maintain this essential tool for the AI-powered development community.

🤖 Ward Security System - Your AI Assistant's Safety Co-pilot

About

Ward Security System - Enterprise file system protection with directory access control

Resources

Readme

License

MIT license

Contributing

Contributing
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 4

Ward Security System v2.0.3 - User Experience Fixes Latest
Nov 18, 2025
+ 3 releases

Sponsor this project

  •  
Learn more about GitHub Sponsors

Packages

 
 
 

Contributors

Languages