Native TypeScript implementation of SecureShell - AI-powered command execution gatekeeper
npm install secureshell-tsbash
npm install secureshell-ts
`
Quick Start
`typescript
import { SecureShell, OpenAIProvider } from 'secureshell-ts';
// Initialize with OpenAI provider
const shell = new SecureShell({
provider: new OpenAIProvider({
apiKey: process.env.OPENAI_API_KEY,
model: 'gpt-4.1-mini'
}),
template: 'development'
});
// Execute a command with AI gatekeeping
const result = await shell.execute(
'ls -la',
'List files to check project structure'
);
if (result.success) {
console.log(result.stdout);
} else {
console.error('Blocked:', result.gatekeeper_reasoning);
}
await shell.close();
`
Platform-Aware Command Evaluation
SecureShell automatically detects your OS and blocks platform-incompatible commands:
`typescript
// On Windows, this will be DENIED by the gatekeeper
const result = await shell.execute('rm -rf file.txt', 'Delete file');
// Gatekeeper: "DENY - rm is a Unix command that will fail on Windows"
// The gatekeeper suggests Windows alternatives
// Agent can self-correct and try: 'del file.txt'
`
Supported LLM Providers
`typescript
import {
OpenAIProvider,
AnthropicProvider,
GeminiProvider,
DeepSeekProvider,
GroqProvider,
OllamaProvider,
LlamaCppProvider
} from 'secureshell-ts';
// OpenAI (GPT-4, GPT-4o, etc.)
new OpenAIProvider({ apiKey: '...', model: 'gpt-4.1-mini' })
// Anthropic Claude
new AnthropicProvider({ apiKey: '...', model: 'claude-sonnet-4-5' })
// Google Gemini
new GeminiProvider({ apiKey: '...', model: 'gemini-2.5-flash' })
// DeepSeek
new DeepSeekProvider({ apiKey: '...', model: 'deepseek-chat' })
// Groq
new GroqProvider({ apiKey: '...', model: 'llama-3.3-70b-versatile' })
// Ollama (local)
new OllamaProvider({ model: 'llama3', endpoint: 'http://localhost:11434' })
// LlamaCpp (local)
new LlamaCppProvider({ model: 'llama3', endpoint: 'http://localhost:8080' })
`
Framework Integrations
$3
`typescript
import { SecureShell, OpenAIProvider, createSecureShellTool } from 'secureshell-ts';
import { createAgent } from 'langchain';
const shell = new SecureShell({
provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
template: 'development',
config: { debugMode: true }
});
const tool = createSecureShellTool(shell);
const agent = createAgent({
model: 'gpt-4.1-mini',
tools: [tool]
});
await agent.invoke({
messages: [{ role: 'user', content: 'List files in current directory' }]
});
`
$3
`typescript
import { SecureShell, OpenAIProvider, createSecureShellMCPTool } from 'secureshell-ts';
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
const shell = new SecureShell({
provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
template: 'development'
});
const server = new Server({ name: 'secureshell-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
const mcpTool = createSecureShellMCPTool(shell);
// Register tool with MCP server
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [{ name: mcpTool.name, description: mcpTool.description, inputSchema: mcpTool.inputSchema }]
}));
`
Security Templates
Choose a security profile that fits your use case:
`typescript
// Maximum security - blocks most commands
new SecureShell({ template: 'paranoid' })
// Balanced for production
new SecureShell({ template: 'production' })
// Flexible for development
new SecureShell({ template: 'development' })
// Automation-friendly
new SecureShell({ template: 'ci_cd' })
`
Configuration
$3
`yaml
secureshell.yaml
security:
gatekeeper_enabled: true
risk_threshold: "YELLOW"
allowlist:
- "ls"
- "pwd"
- "echo"
blocklist:
- "rm -rf /"
- "dd"
sandbox:
allowed_paths:
- "/workspace"
blocked_paths:
- "/etc"
- "/sys"
`
`typescript
import { loadConfig } from 'secureshell-ts';
const config = loadConfig('./secureshell.yaml');
const shell = new SecureShell({ config });
`
$3
`typescript
const shell = new SecureShell({
config: {
debugMode: true,
riskThreshold: 'YELLOW',
allowlist: ['ls', 'pwd', 'cat'],
blocklist: ['rm', 'dd'],
sandbox: {
allowedPaths: ['/workspace'],
blockedPaths: ['/etc', '/sys']
}
}
});
`
Audit Logging
All command executions are logged in JSONL format:
`json
{
"timestamp": "2026-01-30T01:00:00.000Z",
"command": "ls -la",
"risk_tier": "GREEN",
"gatekeeper_decision": "ALLOW",
"success": true,
"exit_code": 0
}
`
Logs are automatically rotated when they exceed the configured size limit.
Examples
The SDK includes comprehensive examples in the repository:
- Provider Examples - All 7 LLM providers
- Integration Examples - LangChain, LangGraph, MCP
- Feature Demos - Templates, allowlist/blocklist, challenge mode
API Reference
$3
`typescript
class SecureShell {
constructor(options?: {
provider?: BaseLLMProvider;
config?: SecureShellConfig;
template?: SecurityTemplate;
allowedPaths?: string[];
blockedPaths?: string[];
osInfo?: string;
});
async execute(command: string, reasoning: string): Promise;
async close(): Promise;
getOSInfo(): string;
}
`
$3
`typescript
interface ExecutionResult {
success: boolean;
command: string;
stdout: string;
stderr: string;
exit_code: number;
risk_tier: RiskTier;
gatekeeper_decision?: GatekeeperDecision;
gatekeeper_reasoning?: string;
}
``