Skip to content

FEATURES_GUIDE.md

Latest commit

 

History

History
283 lines (210 loc) · 6.8 KB

FEATURES_GUIDE.md

File metadata and controls

283 lines (210 loc) · 6.8 KB

ChillShell Feature Guide

This guide explains:

  • what each feature does
  • how to use it
  • limits you should know

The goal is simple: help you demo confidently in hackathons and avoid confusion during testing.

1. Core Idea

ChillShell is a safety layer for terminal commands. It checks command risk before execution and helps users avoid destructive mistakes.

You can use it in two ways:

  • Web app analyzer (frontend + backend API)
  • SafeShell CLI (terminal tool)

2. Web App Features

2.1 Command Analyzer

What it does:

  • Takes a command input
  • Calculates risk score (0 to 100)
  • Gives decision: ALLOW, WARN, BLOCK
  • Shows blast radius, explanation, and safer alternatives

How to use:

  1. Open Analyzer page
  2. Enter command
  3. Select current directory and user level
  4. Click Analyze

Limitations:

  • Rule-based engine, not full command execution simulation
  • Very unusual custom scripts may not be fully understood
  • Real environment permissions are not actually tested in backend

2.2 Script Mode Analyzer

What it does:

  • If input has multiple lines, it treats each line as script line
  • Evaluates line-by-line risk
  • Finds highest-risk line
  • Summarizes line count and risky line

How to use:

  1. Paste multiline command/script in analyzer textarea
  2. Click Analyze
  3. Review Script Mode panel

Limitations:

  • Works best for shell-like command lines, not full programming languages
  • Ignores comments and empty lines
  • Does not execute script; analysis is static

2.3 Explainability Timeline

What it does:

  • Shows how risk score was built step by step
  • Examples: base risk, flag impact, target impact, user-level adjustment, pattern boost

How to use:

  1. Analyze any command
  2. Open Explainability Timeline panel
  3. Read each score contribution in order

Limitations:

  • Timeline is deterministic from rules, not from runtime behavior
  • If a command has hidden behavior not matched by rules, timeline may miss it

2.4 Command Chain Visualizer

What it does:

  • Splits chains like cmd1 && cmd2 ; cmd3 | cmd4
  • Shows step-level risk
  • Shows operator links to next step

How to use:

  1. Analyze chained command
  2. Review chain panel step by step

Limitations:

  • Not a full shell parser
  • Complex quoting/escaping can still be tricky

2.5 Playground Mode

What it does:

  • Compares same command in two directories
  • Helps show how context changes risk

How to use:

  1. Enter command
  2. Pick Context A and Context B
  3. Run Simulation

Limitations:

  • Uses current risk model assumptions
  • Does not read full filesystem state for backend web mode

2.6 Dashboard and Learning Mode

What it does:

  • Dashboard shows risk trends and command usage patterns
  • Learning mode gives XP-like progression and concept snippets

How to use:

  1. Sign in
  2. Run analyses
  3. Open Dashboard and Learning pages

Limitations:

  • Insights depend on stored history quality
  • Learning hints are basic mapping, not deep tutoring yet

3. Backend Engine Features

3.1 Wider Command Coverage

What it does:

  • Handles Linux, Windows, and cross-platform command families
  • Includes delete, permission, service, registry, package, container, kubernetes, transfer commands

How to use:

  • Send command to analyze endpoint

Limitations:

  • Still finite list of rules and patterns
  • New niche tools need added rules

3.2 Deep Pattern Detection

What it does:

  • Detects dangerous patterns like:
    • rm recursive root wipe
    • raw disk write patterns
    • remote pipe-to-shell
    • broad delete operations
    • high-risk container flags
    • suspicious secret transfer paths

How to use:

  • Analyze realistic command strings

Limitations:

  • Pattern-based, so obfuscated edge cases can bypass detection

3.3 Context and OS-aware Scoring

What it does:

  • Uses current directory and user level
  • Uses OS metadata when provided

How to use:

  • Provide userLevel and currentDir in request
  • Optionally pass osPlatform, osVersion, elevated

Limitations:

  • Context is user-provided; wrong context gives wrong risk estimate

4. SafeShell CLI Features

4.1 safe run

What it does:

  • Analyze and optionally execute command from terminal

Useful options:

  • --dry-run: analyze only
  • --learn: show extra learning details
  • --predict: deterministic pre-check
  • --tree: show affected tree
  • --auto-fix: use safer alternative if available

How to use:

  • safe run --dry-run "rm -rf /"

Limitations:

  • Real execution still uses local shell behavior
  • If command itself is malformed for your shell, shell errors can happen

4.2 safe predict

What it does:

  • Predicts risk from deterministic rules + local history
  • Can show tree with vulnerability highlights

How to use:

  • safe predict "command"
  • safe predict --tree --depth 2 "command"

Limitations:

  • Prediction is estimate, not execution proof
  • History-based weighting can bias if history is noisy

4.3 Tree Vulnerability Highlighting

What it does:

  • Highlights vulnerable files in tree view
  • Adds labels like VULN: reason
  • Shows quick vulnerable file summary panel

How to use:

  • safe predict --tree "rm -rf ."
  • safe run --dry-run --tree "command"

Current heuristic examples:

  • .env
  • ssh key files
  • cert/key files
  • sensitive auth artifacts

Limitations:

  • Scan depth and entry limits are bounded for performance
  • It is heuristic and cannot guarantee complete secret discovery

4.4 safe guard (Live Guard)

What it does:

  • Installs shell hooks so normal commands route through SafeShell first
  • Mainly guards rm and rmdir in PowerShell setup

How to use:

  1. safe guard --print
  2. safe guard --install
  3. Restart terminal
  4. Test with risky command

Limitations:

  • Shell profile based, not system-wide kernel enforcement
  • If aliases are bypassed, guard can be bypassed
  • PowerShell del alias is tricky due built-in alias behavior; direct del interception is less reliable than rm/rmdir

4.5 History, Login, Snapshot, Restore

What it does:

  • history: view local command analysis history
  • login: save auth token
  • snapshot: save local state
  • restore: return to earlier local state

How to use:

  • safe history
  • safe login
  • safe snapshot
  • safe restore

Limitations:

  • Snapshot scope is local SafeShell state only
  • Not a full machine snapshot/rollback

5. API Endpoints

Current backend endpoints:

  • POST /api/analyze
  • GET /api/history?userId=...
  • POST /api/save-command

Limitations:

  • Analyze endpoint trusts request payload context
  • Without extra hardening, it is not a full policy enforcement gateway

6. Practical Testing Checklist

  1. Backend and frontend running
  2. Analyze single dangerous command
  3. Analyze multiline script
  4. Check timeline events
  5. Test chain command
  6. Test CLI run and predict
  7. Test CLI tree and vulnerable file marks
  8. Install guard and test rm interception

7. Important Safety Note

This project is a strong safety assistant, not a perfect prevention system. Always combine it with:

  • backups
  • least privilege
  • review process
  • production change controls