Safeshell Sandbox CLI

SafeShell Sandbox CLI

Overview

SafeShell Sandbox CLI is a command-line tool that allows users to safely run untrusted code in an isolated Docker container. It mounts the current working directory into the container, provides an interactive shell, and enforces security measures such as resource limits, network isolation, and running as a non-root user.

Features

Secure Sandbox Environment: Runs untrusted code in a Docker container with limited resources.
Directory Mounting: Mounts your current working directory into the container.
Interactive Shell: Provides access to a container shell (bash or sh).
Security Enhancements: Includes network isolation, non-root user privileges, and resource restrictions (CPU, memory, process limits).
Customizability: Supports custom Docker images, environment variables, and resource configurations.

Installation

Ensure Docker is installed and running on your system.
Install the CLI globally using npm:
```
npm install -g safeshell-sandbox-cli
```

Usage

Basic Command

Start the sandbox:

safeshell-sandbox-cli start

Options

Option	Description	Default
`-i, --image <name>`	Specify a custom Docker image	`ubuntu:latest`
`--no-network`	Disable network access inside the container	Enabled
`--cpu <limit>`	Set CPU limit (in cores, e.g., `1`, `0.5`)	`1`
`--memory <limit>`	Set memory limit (e.g., `512m`, `1g`)	`512m`
`--verbose`	Enable detailed logs for debugging purposes	Disabled

Examples

Start a sandbox with default settings:
```
safeshell-sandbox-cli start  
```

Use a custom Docker image:

safeshell-sandbox-cli start --image alpine

Disable network access:

safeshell-sandbox-cli start --no-network

Limit CPU and memory usage:

safeshell-sandbox-cli start --cpu 0.5 --memory 256m

Security Features

Non-Root User: The container runs as a non-root user (nobody) to minimize privilege escalation risks.
Network Isolation: By default, containers can be started without internet access using --no-network.
Resource Limits: CPU, memory, and process limits are applied to prevent abuse.

Testing

Setup

Install Jest for testing:

npm install --save-dev jest @types/jest ts-jest  
npx ts-jest config:init

Write Tests

Create a test file: tests/docker.test.ts

import { startSandbox } from '../src/docker';

describe('SafeShell Sandbox CLI', () => {
  it('should pull the specified Docker image', async () => {
    const options = { image: 'alpine', network: false, cpu: '1' };
    await expect(startSandbox(options)).resolves.not.toThrow();
  });

  it('should handle invalid Docker image errors', async () => {
    const options = { image: 'invalid-image', network: false, cpu: '1' };
    await expect(startSandbox(options)).rejects.toThrow();
  });

  it('should start a container with limited CPU and memory', async () => {
    const options = { image: 'alpine', network: true, cpu: '0.5', memory: '256m' };
    await expect(startSandbox(options)).resolves.not.toThrow();
  });
});

Run Tests

Execute the tests:

npm test

Project Structure

safeshell-sandbox-cli/  
├── src/  
│   ├── index.ts       # CLI entry point  
│   ├── docker.ts      # Docker integration logic  
│   ├── config.ts      # Configurations and constants  
│   └── utils.ts       # Helper functions  
├── tests/  
│   └── docker.test.ts # Jest tests for Docker functionality  
├── package.json  
├── tsconfig.json  
└── README.md

Future Enhancements

Predefined Scripts: Allow running predefined scripts inside the sandbox.
Plugin Support: Add a plugin system for custom extensions.
GUI Interface: Provide a graphical interface for managing sandboxes.