Shadow-OS

Shadow-OS is a ptrace-based Linux sandbox and live syscall monitor. It traces a target process, scores risk, and renders a real-time TUI with security telemetry. It is not a virtual machine.

Highlights

• Process-level virtualization model with syscall visibility.
• Live TUI for syscalls, process tree, console output, and resource gauges.
• Security test mode that returns a plain-English summary.
• Optional AI shell for natural-language commands.

What It Is

• A process-level sandbox and telemetry system built on ptrace.
• A real-time security dashboard for syscall behavior.
• A test harness that summarizes file and network behavior in plain English.

What It Is Not

• A full VM or hypervisor.
• A guest OS emulator.
• A deterministic execution replay engine.

Architecture (High Level)

• Tracer (ptrace): intercepts syscalls and collects events.
• Security modules: scoring, policy checks, honeypots, YARA, entropy.
• Monitor modules: CPU/memory, network connection tracking.
• VFS policy layer: allow/deny rules and COW overlay (reporting in tests).
• TUI dashboard: renders events and provides a shell prompt.

Flow of Events (TUI Mode)

1. CLI loads shadow_policy.json and creates a Tracer.
2. TUI thread starts rendering; main thread handles ptrace events.
3. When you enter a command, the UI sends an AppCommand to spawn it.
4. The tracer spawns the process under ptrace and begins syscall interception.
5. Syscalls are scored, classified, and forwarded to the UI state.
6. Resource stats are polled and gauges updated.
7. Security alerts and console output are appended to the UI console.
8. In test mode, file and network events are summarized when the root PID exits.

Virtualization Model (Process-Level) Shadow-OS provides virtualization-like control at the process boundary:

• Syscall interception lets the engine observe and score behavior in real time.
• VFS policy rules define allowed and denied paths.
• Copy-on-write (COW) overlay is designed for safe writes to a sandbox root.
• Namespace and chroot utilities exist for mount and PID isolation.

Important Note Some virtualization features are currently reporting-only or partially wired. The test mode reports VFS policy outcomes but does not hard-block syscalls yet. Namespace/chroot hooks exist but are not enabled by default in the spawn path.

Modes

Mode	What you get	Limitations	When to use
TUI	Live dashboard and console capture	No stdin forwarding to target	Monitoring non-interactive commands
Headless	Direct interactive target	No TUI dashboard	Interactive shells, REPLs, curses apps

Quick Start (Ubuntu Terminal)

# From the project root
cargo build

# TUI mode (non-interactive targets only)
cargo run --

# Headless mode (interactive targets)
cargo run -- --headless run /bin/bash

TUI Shell Usage The TUI includes a simple shell prompt.

• It splits on whitespace only.
• It does not support quotes, pipes, or redirection.
• Interactive programs will not work in the TUI.

Built-in commands:

• clear clears the console panel.
• theme cycles UI themes.
• help toggles the help overlay.
• quit or exit closes the TUI.
• monitor <pid> focuses console output on a specific PID.
• snapshot <pid> triggers a snapshot placeholder.
• ai ... manages AI shell settings (see below).
• test <command> [args...] or scan <command> [args...] runs a security test with a plain-English summary.

To run a target, type a command at the prompt:

shadow-os> /bin/ls -la

Security Test Mode (Virtualized Analysis) Run a command or script under a security test that summarizes behavior in plain English.

Examples:

shadow-os> test /bin/ls -la
shadow-os> test ./scripts/sample.py
shadow-os> scan ./scripts/sample.sh --dry-run

Test summary includes:

• File access (allowed/denied/redirected/honeypot).
• Suspicious or blocked syscall list hits.
• Network connections observed.
• Packet hints (HTTP/TLS/DNS/SSH) from syscall payload sampling.
• Peak CPU and memory usage.
• Hardware requirement check (cores/RAM/virtualization flags).

Notes:

• Test mode evaluates VFS policy and reports allow/deny; enforcement is not yet hard-blocking.
• Script files are auto-run via interpreter when not executable (e.g., .py -> python3).
• Network test mode can be configured via test.network_mode in shadow_policy.json: monitor (default), loopback_only, or block_all.

AI Shell (Experimental) Shadow-OS can translate plain-English requests into commands in the TUI shell.

Build with AI support:

cargo build --features ai

Enable AI mode:

• Set "ai.enabled": true in shadow_policy.json, or
• Type ai on inside the TUI shell.

Examples:

shadow-os> list files in /etc
shadow-os> show disk usage for /var

By default, AI mode translates all inputs when enabled. Use ! to force a raw command:

shadow-os> !/bin/ls -la

Prefer prefix-only translation:

shadow-os> ai mode prefix
shadow-os> ?show open network ports

Key AI settings in shadow_policy.json:

• ai.endpoint (OpenAI-compatible chat endpoint, e.g., https://api.openai.com/v1/chat/completions or http://localhost:11434/v1/chat/completions)
• ai.model (model name for your provider)
• ai.api_key_env (env var name for API key, or null for local providers)
• ai.timeout_ms, ai.temperature, ai.max_tokens

Limitations:

• The TUI shell does not support pipes, redirection, or quotes, so AI outputs are constrained to single commands.

Demo command script: see docs/demo-commands.md.

CLI Usage

shadow-os [--headless] [--config <path>] [--record <file>] [--replay <file>] <command>

Subcommands:

• run <binary> [args...]
• show-config
• validate-config <path>
• snapshot <name>
• restore <name>

Examples:

# Headless run with an explicit subcommand
cargo run -- --headless run /bin/ls -la

# Implicit run (no subcommand)
cargo run -- /bin/ls -la

# TUI shell (then type commands at the prompt)
cargo run --

Configuration Default configuration is in shadow_policy.json and can be printed with:

cargo run -- show-config

Main sections in shadow_policy.json:

• features toggles major capabilities. Many flags are aspirational or partially implemented.
• engine tracing details (follow forks, timeouts, buffer sizes).
• security risk thresholds and blocked syscalls.
• vfs virtual filesystem allow/deny lists and sandbox root paths.
• monitor resource limits and audit log locations.
• ui refresh rate and display limits.
• test hardware requirement thresholds for security test mode.
• runtime target and snapshot defaults.

Important paths you may need to adjust:

• vfs.root_dir and vfs.cow_dir default to /tmp/shadow-os/....
• monitor.audit_log_path defaults to /var/log/shadow-os/audit.json and may require root.

Record and Replay

• --record <file> records syscall events.
• --replay <file> loads and replays recorded events into the history buffer.

Replay is currently a history load, not a deterministic execution replay.

Project Layout

• src/engine/ tracing, syscall handling, and process supervision.
• src/security/ heuristics and risk analysis.
• src/monitor/ CPU and memory monitoring.
• src/ui/ TUI dashboard and shell.
• shadow_policy.json default configuration.

Troubleshooting ptrace permission errors:

sudo sysctl -w kernel.yama.ptrace_scope=0

Or run with sudo.

No output in TUI:

• Expected for interactive programs because stdin is disabled.
• Use --headless for shells, REPLs, or curses applications.

Command parsing failures in TUI:

• The shell does not support quotes or pipes. Use headless mode for complex commands.

Limitations

• TUI is non-interactive by design.
• This is not a VM or full hypervisor.
• Snapshot and restore are placeholders.
• Some panels and feature flags are stubs or partially implemented.
• Test mode reports VFS policy outcomes; syscall blocking is not enforced yet.
• Network test mode uses syscall sampling and risk-based termination, not full packet capture or netns isolation.

Detailed Demonstration Guide Use this script for a thorough demo. It assumes Ubuntu and the repo root.

Pre-flight:

• Confirm ptrace permissions.
• Build once to avoid delays during the demo.

sudo sysctl -w kernel.yama.ptrace_scope=0
cargo build

Part 1: Explain the model (30 to 60 seconds) Say: "Shadow-OS is a ptrace-based sandbox. It traces syscalls in real time, scores risk, and lets us observe process behavior live. It is process-level virtualization, not a VM. There is no guest OS, so it is fast and lightweight."

Part 2: Start the TUI

cargo run --

Call out:

• Syscall stream panel updating live.
• Process tree panel showing traced PIDs.
• Threat level panel and counters.
• Console output panel for stdout/stderr.

Part 3: Run safe targets in the TUI At the prompt:

shadow-os> /bin/ls -la
shadow-os> /bin/uname -a
shadow-os> /bin/cat /etc/hosts

Point out:

• Each command generates syscalls immediately.
• Output appears in the console panel.
• Process tree updates during execution.

Part 4: Show view switching Use F1 to F9 to cycle through views. Explain that some panels are placeholders depending on the current feature set.

Part 5: Show headless interactive mode

cargo run -- --headless run /bin/bash

In the shell:

echo "interactive input works in headless"
exit

Explain:

• TUI mode disables stdin to prevent terminal corruption.
• Headless mode is the correct path for interactive programs.

Part 6: Record and replay (optional)

cargo run -- --headless --record /tmp/shadow-trace.json run /bin/ls
cargo run -- --headless --replay /tmp/shadow-trace.json run /bin/ls

Explain:

• The trace file is loaded and shown in history.
• Replay is not yet a deterministic execution replay.

Part 7: Wrap up Press Ctrl+Q to exit the TUI, or exit in headless mode.

License MIT