Architecture

Deeprotection (dpshell) is a fully-fledged interactive shell with integrated security enforcement, written in Rust.

High-Level Overview

The codebase is organized into 10 module groups across 47 source files totalling ~10,883 lines of code.

src/
├── builtins/          # 50+ built-in command implementations
├── config/            # TOML configuration deserialization
├── executor/          # fork/execve, pipelines, expansion
├── interactive/       # Reedline editor, highlighter, hinter, completers
├── jobs/              # POSIX job control (fg/bg/jobs)
├── logging/           # JSONL audit logger
├── parser/            # Recursive-descent parser, AST, expansion
├── security/          # Rules, plugins, path protection
├── shell/             # Shell state (history, aliases, vars, functions)
├── main.rs            # REPL loop, script mode, login shell
└── utils.rs           # Prompt generation, startup animation

Execution Flow

sequenceDiagram
    participant User
    participant Reedline
    participant PreExpand
    participant Parser
    participant Mode
    participant RuleEngine
    participant Plugin
    participant PathProt
    participant Auth
    participant Executor
    participant Logger

    User->>Reedline: Raw user input
    Reedline->>PreExpand: Expanded input string
    PreExpand->>PreExpand: expand_alias() / preprocess_heredocs() / expand_line()
    PreExpand->>Parser: Fully expanded string
    Parser->>Parser: Shlex tokenization → AST
    Parser->>Mode: CommandNode AST

    alt mode = disable
        Mode->>Executor: Direct execution
    else mode = permissive / enforcing
        Mode->>RuleEngine: AST + raw input
        RuleEngine->>RuleEngine: check_raw_input() / apply_rules_to_node()
        alt rule matches → block
            RuleEngine-->>Logger: Log block
            RuleEngine-->>User: Command blocked
        else rule matches → replace
            RuleEngine->>Plugin: Replaced command
        else no rule match
            RuleEngine->>Plugin: Original command
        end
        Plugin->>Plugin: Run external plugin (5s timeout)
        Plugin->>PathProt: Plugin result

        alt mode = enforcing
            PathProt->>PathProt: check_node() / resolve_arg()
            alt path requires auth
                PathProt->>Auth: Trigger password auth
                Auth->>User: Prompt for password
                alt auth success
                    Auth->>Executor: Allow execution
                else auth failure
                    Auth-->>Logger: Log failure
                    Auth-->>User: Command blocked
                end
            else path blocked
                PathProt-->>Logger: Log block
                PathProt-->>User: Command blocked
            end
        end

        Executor->>Executor: expand_command_argv() (brace & glob)
        Executor->>PathProt: check_expanded_argv() secondary audit
        PathProt-->>Executor: Allow / Block
    end

Loading

Key Architecture Highlights

Component	Description
Parser	Hand-written recursive-descent parser producing an AST with 11 node types
Executor	Direct fork/execve — no sh -c wrapper, eliminating shell injection vectors
Job Control	Built-in fg, bg, jobs with POSIX process-group management
Security	Three-layer pipeline: raw input → AST rules → post-expansion path audit
Interactive	Powered by reedline with syntax highlighting, autosuggestions, and fuzzy completion
Logging	Thread-safe JSONL file writes with mutex protection

Core Dependencies

Crate	Purpose
reedline	Modern line editor with highlighting, hints, and menus
nucleo	High-performance fuzzy matching for completions
regex	Pattern matching for security rules
serde / toml	Configuration and log serialization
serde_json	JSONL audit log serialization
sha2	SHA-256 password hash verification
rpassword	Secure password input (no terminal echo)
nix	Unix system calls (fork, signal, wait, setpgid)
libc	Low-level Unix API
chrono	Timestamp generation for audit logs