RoboShellGuard: Building an AI-Assisted Command Approval System for SSH Security

By /

How we built a real-time command approval system to make AI automation safer. Please note: This is a preview system and more features will be needed before deploying it to production, but its real and it works!

RoboShellGuard (formerly just Shellguard) is open source and licensed under the GNU General Public License v3.0. You can find the full license text in the project’s repository.

The Problem: AI Agents Gone Wild

Picture this: You’re deploying an AI agent to help manage your infrastructure. It’s 3 AM, the agent decides to “clean up” your production database, and suddenly you’re having the worst morning of your career.

Sound familiar? Not yet? Come back in a year or two if you’re not already having nightmares about it. As AI agents become more common in DevOps workflows, we’re facing a critical challenge: How do we harness the power of AI automation while maintaining control and safety?

Traditional solutions like restricted shells help, but they don’t provide real-time insight, decision-making, or audit trails. That’s why we built RoboShellGuard – an AI-assisted command approval and risk assessment system.

Maybe AI will never be let loose near live, or even test environments, maybe you can just use it on development environments, but if your competitors do you may get little choice, but you don’t have to cut so many corners that disaster is just round one!

What is RoboShellGuard?

RoboShellGuard acts as an intelligent proxy between AI agents and your SSH environments. Think of it as a “human-in-the-loop” system that analyzes commands in real-time using AI for risk assessment. It routes high-risk commands to human operators for approval and provides audit trails for every command and decision. ShellGuard integrates seamlessly with existing AI systems via its simple WebSocket API.

  • Analyzes commands in real-time using AI risk assessment
  • Routes high-risk commands to human operators for approval
  • Provides full audit trails of every command and decision
  • Integrates seamlessly with existing AI systems via WebSocket API

Architecture Overview

ShellGuard is built with Kotlin and Spring Boot, designed for reliability and enterprise deployment. Here’s how it works:

AI Agent → WebSocket API → Risk Assessor → Approval Engine → SSH Execution
     ↓                           ↓              ↓              ↓
   Command              Risk Score      Human Review     Audit Log

Core Components

  1. WebSocket JSON API – Real-time communication with AI agents
  2. Risk Assessment Engine – AI-powered command analysis
  3. Approval Center – Web dashboard for human oversight
  4. Terminal Test Client – Development and testing interface
  5. Audit System – Complete command history and compliance

Getting Started: The Developer Experience

1. Setting Up RoboShellGuard

# Clone the repository
git clone https://github.com/robokeys/shellguard.git
cd shellguard

# Build with Gradle
./gradlew build

# Start the server
./gradlew bootRun

2. Connecting Your AI Agent

The WebSocket API makes integration straightforward:

// Connect to ShellGuard
const ws = new WebSocket('ws://localhost:8080/rkcl/ws');

// Send a command for approval
const command = {
    "command": "LINE"
    "parameter": "systemctl restart nginx",
    "session": "production"
};

ws.send(JSON.stringify(command));

// Handle the response
ws.onmessage = (event) => {
    const response = JSON.parse(event.data);
    
    switch(response.status) {
        case 'PENDING':
            console.log('Command submitted for approval');
            break;
        case 'APPROVED':
            console.log('Command approved:', response.result);
            break;
        case 'REJECTED':
            console.log('Command rejected:', response.reason);
            break;
    }
};

3. Testing with the Terminal Client

ShellGuard includes a built-in test client that uses the same WebSocket interface as production AI agents:

  • Real-time command testing
  • WebSocket connection management
  • Response monitoring
  • Session handling

This ensures your integration testing is as close to production as possible.

Real-World Use Cases

The power of RoboShellGuard lies in its simple, yet robust, protocol-based interface. While we’ll be releasing dedicated clients for specific AI systems in the future, the core of ShellGuard is a simple WebSocket API. This approach provides maximum flexibility, allowing you to integrate with any agent or language you choose.

The RoboShellGuard protocol supports various prefixes to handle different types of input. For example, command strings are sent with a LINE: prefix, while interactive keystrokes, such as an up arrow, use a KEY: prefix. This design gives you a clear and consistent way to send different types of shell input, receive real-time risk assessments, and manage the approval workflow. Commands may also be sent in JSON format.

Below are a few examples demonstrating how an AI agent could use ShellGuard in different scenarios.

1. Infrastructure Management AI

# Example: AI agent managing server deployments
class InfrastructureAgent:
    def __init__(self):
        self.shellguard = ShellGuardClient()

    def deploy_service(self, service_name):
        # High-risk command - will require approval
        result = self.shellguard.execute(
            f"LINE:sudo systemctl stop {service_name}"
        )

        if result.approved:
            # Continue with deployment
            self.shellguard.execute(
                f"LINE:docker pull {service_name}:latest"
            )

2. Database Maintenance Automation

// Example: Automated database cleanup
const maintenanceCommands = [
    "LINE:pg_dump production_db > backup.sql",  // Low risk - auto-approved
    "LINE:DROP TABLE temp_analytics;",          // High risk - needs approval
    "LINE:VACUUM ANALYZE;"                      // Medium risk - configurable
];

for (const cmd of maintenanceCommands) {
    await shellguard.executeWithApproval(cmd);
}

3. Security Response Automation

For commands that require more context, such as a security response, the API can accept a detailed JSON object.

// Example: Automated incident response
class SecurityResponseAgent {
    fun handleSuspiciousActivity(ipAddress: String) {
        // Block suspicious IP - high risk command
        shellGuard.submitCommand(
            command = "LINE”
            parameter = ”iptables -A INPUT -s $ipAddress -j DROP",
            priority = CommandPriority.HIGH,
            reason = "Blocking suspicious IP: $ipAddress"
        )
    }
}

The Risk Assessment Engine

One of RoboShellGuard’s key features is intelligent risk scoring. Commands are analyzed based on:

Risk Factors

  • Privilege level (sudo, root access)
  • Destructive potential (rm, drop, delete operations)
  • System impact (service restarts, network changes)
  • Data sensitivity (database operations, file modifications)

Configurable Rules

Coming soon !

# Example risk assessment configuration
risk_assessment:
  rules:
    - pattern: "sudo rm -rf .*"
      risk_level: CRITICAL
      require_approval: true
    
    - pattern: "systemctl restart .*"
      risk_level: MEDIUM
      require_approval: false
      notify_operators: true
    
    - pattern: "ls .*|ps .*|cat .*"
      risk_level: LOW
      auto_approve: true

Building for Production

Security Considerations

  • Authentication: Integrate with your existing auth systems (Coming soon)
  • Authorization: Role-based approval workflows (Coming soon)
  • Encryption: TLS for all communications (Coming soon)
  • Audit Logging: Immutable command history

Scalability Features

  • Horizontal scaling with Spring Boot
  • Database persistence for audit trails (Coming soon)
  • Load balancing for high-availability
  • Monitoring with built-in metrics

Integration Points

ShellGuard plays well with existing tools:

  • CI/CD pipelines (Jenkins, GitLab CI, GitHub Actions)
  • Monitoring systems (Prometheus, Grafana)
  • Chat ops (Slack, Microsoft Teams)
  • SIEM platforms (Splunk, ELK Stack)

The HTMX-Powered Dashboard

The approval center uses HTMX for real-time updates without heavy JavaScript frameworks:

<!-- Live updating approval queue -->
<div hx-get="/api/pending-approvals" 
     hx-trigger="every 2s"
     hx-target="#approval-queue">
    <!-- Approval cards inserted here -->
</div>

This approach gives us:

  • Instant updates as commands arrive
  • Minimal complexity compared to React/Vue
  • Better performance for real-time dashboards
  • Progressive enhancement that works without JavaScript

What’s Next?

We’re actively developing ShellGuard with planned features including:

  • Machine learning risk models
  • Integration plugins for major platforms
  • Advanced reporting and analytics
  • Multi-tenant support for managed services

Try It Yourself

ShellGuard is open source and ready for production use:

Contributing

RoboShellGuard is open source and licensed under the GNU General Public License v3.0. You can find the full license text in the project’s repository.

We welcome contributions! Areas where we’d love help:

  • Risk assessment algorithms
  • Integration plugins (Terraform, Ansible, etc.)
  • UI/UX improvements
  • Documentation and examples

Final Thoughts

AI automation is inevitable, but it doesn’t have to be uncontrolled. ShellGuard provides the safety net that lets you move fast without breaking things.

The future of DevOps isn’t choosing between human oversight and AI efficiency – it’s combining both intelligently. RoboShellGuard makes that possible today.

Want to learn more? Check out our other tools in the Robokeys ecosystem:

  • RoboKeyTags: Semantic metadata for AI-assisted development
  • Verzanctuary: Safe experimentation without polluting Git history
  • More projects: robokeys.tech

What are your thoughts on AI automation safety? Have you faced similar challenges? Let’s discuss in the comments!

Tags: #ai #automation #devops #security #ssh #kotlin #springboot #opensource

Scroll to Top