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

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!
**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 *ShellGuard *– 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 ShellGuard?

ShellGuard 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 intelligent 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

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

Getting Started: The Developer Experience

1. Setting Up ShellGuard

# 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;
    }
};

1. 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 ShellGuard 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 ShellGuard 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 ShellGuard’s key features is intelligent risk scoring. Commands can be 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 (comming 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:

GitHub: github.com/robokeys/shellguard
Documentation: Full user guide PDF https://robokeys.tech/assets/About%20Robokeys%20ShellGuard.pdf
ShellGuard Product Page: https://robokeys.tech/shellguard.html
Live Demo: Coming soon!

Contributing

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.
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. ShellGuard 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: https://robokeys.tech

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