SecureShell

<div align="center">
  <img src="SecureShell.png" alt="SecureShell Logo" width="200"/>
  
  # SecureShell

  [![npm version](https://badge.fury.io/js/secureshell-ts.svg)](https://www.npmjs.com/package/secureshell-ts)
  [![PyPI version](https://badge.fury.io/py/secureshell.svg)](https://pypi.org/project/secureshell/)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
  [![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)](https://www.python.org/)

  **A plug-and-play security layer for LLMs and Agents that prevents dangerous command execution.**
</div>

SecureShell acts as "sudo for LLMs" - a drop-in zero-trust gatekeeper that evaluates every shell command before execution. It blocks hallucinated commands, prevents platform mismatches (e.g., Unix commands on Windows), and helps agents learn from mistakes.

## Why SecureShell?

LLM agents with shell access can hallucinate dangerous commands like `rm -rf /` or `dd if=/dev/zero`. SecureShell solves this by:

- **Zero-Trust Gatekeeper** - Every command treated as untrusted until validated by independent gatekeeper
- **Platform-Aware** - Automatically blocks Unix commands on Windows (and vice versa)
- **Risk Classification** - GREEN/YELLOW/RED tiers with automatic handling
- **Agent Learning** - Clear feedback helps agents self-correct
- **Drop-in Integration** - Plug into LangChain, LangGraph, MCP, or use standalone
- **Multi-LLM Support** - Works with any LLM provider

## Quick Start

### TypeScript

```bash
npm install secureshell-ts
```

```typescript
import { SecureShell, OpenAIProvider } from 'secureshell-ts';

const shell = new SecureShell({
    provider: new OpenAIProvider({
        apiKey: process.env.OPENAI_API_KEY,
        model: 'gpt-4.1-mini'
    }),
    template: 'development'
});

const result = await shell.execute(
    'ls -la',
    'L