MythEclipse/zesdex
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: update README with enhanced descriptions and security features; refactor catastrophic guard checks and tool execution handling

Browse Source
This commit is contained in:
asepharyana
2026-07-12 03:37:27 +07:00
parent d957e8d4ce
commit 4bfbe1d1b9
7 changed files with 250 additions and 210 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+201 -72
View File
@@ -1,93 +1,171 @@
# Zesdex
Autonomous AI coding and security agent running in a terminal-based TUI environment.
> Autonomous AI coding and security agent in a terminal-based TUI.
Zesdex is a Rust-powered AI assistant that operates directly in your terminal via a rich TUI interface. It combines large language model intelligence with a comprehensive set of tools to explore, understand, and modify codebases autonomously.
Zesdex is a Rust-powered AI assistant that operates directly in your terminal via a rich TUI interface. It combines large language model intelligence with a comprehensive set of tools to explore, understand, and modify codebases autonomously — with built-in security guardrails at every layer.
---
## Features
- **TUI Interface** — Full-screen terminal UI with chat panel, input bar, and status bar built with ratatui and crossterm.
### Core
- **Rich Tool System** — 20+ built-in tools for file operations, searching, bash execution, git operations, web access, memory management, and workflow orchestration.
- **Daemon Architecture** — Run as a background daemon with client attach/detach via Unix domain sockets.
- **IPC Protocol** — Bidirectional state synchronization between daemon and client processes.
- **MCP Support** — Model Context Protocol integration for connecting to external AI servers.
- **Self-Learning** — Persistent memory system that stores lessons, references, and project knowledge.
- **Workflow Engine** — Orchestrate complex multi-step tasks with parallel sub-agents, pipelines, and phased execution.
- **Security Guardrails** — Catastrophic operation detection, credential exfiltration monitoring, graduated safety checks.
- **Security Sidecar** — Python-based security analysis daemon for vulnerability scanning.
- **Provider Agnostic** — Configurable AI model providers with dynamic model selection.
- **Session Management** — Multiple sessions with history, rewind, and transcript persistence.
- **TUI Interface** — Full-screen terminal UI with chat panel, input bar, and status bar built with [ratatui](https://github.com/ratatui-org/ratatui) and [crossterm](https://github.com/crossterm-rs/crossterm).
- **Daemon Architecture** — Run as a background daemon with client attach/detach via Unix domain sockets. The daemon processes state; clients only render.
- **IPC Protocol** — Bidirectional state synchronization between daemon and client processes with diff-based updates.
- **Provider Agnostic** — Configurable AI model providers with dynamic model selection, per-role temperature/token limits, and API key management.
### Tool System (28 built-in tools)
| Category | Tools |
|----------|-------|
| **Filesystem** | `read`, `write`, `edit`, `delete` |
| **Search** | `grep` (recursive text), `glob` (file patterns) |
| **Shell** | `bash` (with catastrophic guard), `bash_output`, `bash_kill` |
| **Git** | `git_operator`, `git_worktree`, `git_cred` |
| **Internet** | `fetch` (URL→markdown), `download`, `web_search` |
| **Memory** | `remember`, `recall`, `forget` |
| **Planning** | `plan_enter`, `plan_ready`, `seqthink` |
| **Workflow** | `workflow_run`, `note_finding` |
| **Utility** | `cd`, `dir_list`, `dir_cache_update`, `pong`, `todowrite` |
### Intelligence
- **Workflow Engine** — Orchestrate complex multi-step tasks with parallel sub-agents, pipelines, and phased execution. Spawn independent workers that share findings in real-time.
- **Self-Learning** — Persistent memory system that stores lessons, references, and project knowledge across sessions. Memories include provenance tracking, lifecycle management, and scope isolation.
- **Self-Review** — Adaptive quality review system that evaluates completed work against stored lessons and project conventions.
- **MCP Support** — [Model Context Protocol](https://modelcontextprotocol.io/) integration for connecting to external AI tool servers.
- **Sequential Thinking** — Chain-of-thought reasoning tool for step-by-step problem decomposition.
### Security
- **Catastrophic Guard** — Detects and blocks destructive operations (`rm -rf`, `force push`, credential exfiltration) across all tool invocations.
- **Graduated Checks** — Content-aware pattern matching for common danger zones (API keys, passwords, git credentials) with configurable rules.
- **Risky Tool Classification** — Write, delete, edit, bash, and git operations are flagged for additional scrutiny.
- **Workspace Isolation** — All file operations are validated against workspace roots. Path traversal outside the workspace is rejected.
- **Session Locking** — Prevents multiple processes from operating on the same session directory.
- **Security Sidecar** — Optional Python daemon for deep vulnerability scanning (see below).
### Session Management
- Multiple concurrent sessions with history, rewind, and transcript persistence.
- Per-session edit logs with full change tracking.
- Session archival and summary generation.
---
## Security Sidecar
An optional Python-based companion daemon that provides security analysis tools beyond what the core Rust binary offers.
### Available Tools
| Category | Tools | Required Binary |
|----------|-------|-----------------|
| **Web Security** | `sqlmap`, `nuclei`, `ffuf`, `dalfox`, `zap`, `xss_confirm`, `http` | sqlmap, nuclei, ffuf, dalfox, zap-cli, curl |
| **Cryptography** | `z3`, `sage`, `rsa`, `factordb`, `hashcat`, `hashid`, `decode` | z3, sage, hashcat, hashid |
| **Reverse Engineering** | `js_deobfuscate`, `sourcemap`, `wasm_decompile` | npx, wasm-decompile |
| **Binary Exploitation** | `triage`, `ropgadget`, `pwntools`, `exploit_template` | file, checksec, ROPgadget, python3 |
### Installation
```bash
pip install -r security-sidecar/requirements.txt
# Optional: install full extras for crypto/pwn tools
pip install -r security-sidecar/requirements.txt[full]
```
### Health Check
```bash
python -m zesdex_sec_daemon --health
```
---
## Architecture
```
src/
├── main.rs # Entry point, single/daemon/attach modes
├── app/ # Application core
│ ├── state/ # State management (AppStateRest, types, misc)
├── main.rs # Entry point: single-process, daemon, or attach mode
├── app/
│ ├── state/ # AppStateRest — immutable-rest state model
│ │ ├── rest.rs # Core state struct
│ │ ├── types.rs # Overlay, Toast, Origin enums
│ │ ├── snapshot.rs # State snapshots for IPC
│ │ ├── diff.rs # Diff-based state synchronization
│ │ └── runtime.rs # Runtime state mutations
│ ├── runtime/ # Action dispatch and event loop
│ ├── mode/ # UI modes and overlays
│ │ ├── actions/ # Action enum and apply_action reducer
│ │ ├── stream/ # LLM streaming and tool execution
│ │ │ └── tools/ # Tool harness integration
│ │ ├── event_loop/ # Main event loop and shortsend
│ │ └── commands.rs # Slash command dispatch
│ ├── mode/ # UI modes and overlays (16 overlays)
│ ├── harness.rs # Tool harness for agent execution
│ ├── workflow/ # Workflow engine (script, engine)
│ ├── mcp/ # Model Context Protocol manager
│ ├── sec/ # Security daemon integration
│ ├── subagent/ # Sub-agent orchestration
│ ├── workflow/ # Workflow engine (script DSL, executor)
│ ├── mcp/ # MCP client manager
│ ├── sec/ # Security sidecar integration
│ ├── subagent/ # Sub-agent spawn, context, events
│ ├── bgbash/ # Background bash job management
│ └── review/ # Self-review quality system
├── controller/ # Input handling and command dispatch
│ ├── input.rs # Key event processing
│ ├── review/ # Self-review quality system
│ └── catastrophic.rs # Catastrophic operation detection
├── controller/
│ ├── input.rs # Key event → Action mapping
│ └── command.rs # Slash command parser
├── dto/ # Data transfer objects
│ ├── chat/ # Message types
│ └── provider/ # AI provider request/response types
├── ipc/ # Inter-process communication
│ ├── protocol.rs # Message protocol definition
├── dto/
│ ├── chat/ # Message, ToolCall, Role types
│ └── provider/ # AI provider request/response/usage types
├── ipc/
│ ├── protocol.rs # ClientRequest, DaemonFrame, StatePayload
│ ├── server.rs # Unix socket server
│ ├── client.rs # Unix socket client
│ ├── conn.rs # Connection framing
│ ├── frame.rs # Frame encoding/decoding
│ ├── snapshot.rs # State snapshot
│ └── diff.rs # State diffing
├── model/ # Data models
│ ├── store.rs # File-based storage
│ ├── session.rs # Session management
│ ├── settings.rs # User settings
│ ├── app_config.rs # Provider configuration
│ ├── memory.rs # Persistent memory
│ ├── editlog.rs # Edit history log
│ ├── msglog/ # Message log persistence
│ ├── agent_def/ # Agent definitions
│ └── session_lock.rs # Session locking
├── security/ # Security installation utilities
│ ├── conn.rs # Framed connection
│ ├── frame.rs # Length-prefixed frame encoding
│ ├── snapshot.rs # State snapshot serialization
│ └── diff.rs # Binary diff for state sync
├── model/
│ ├── store.rs # File-based storage (~/.config/zesdex/)
│ ├── session.rs # Session CRUD and listing
│ ├── settings.rs # User settings (provider, model, tokens)
│ ├── app_config.rs # Provider definitions and model roles
│ ├── memory.rs # Persistent memory with frontmatter
│ ├── editlog.rs # Edit history tracking
│ ├── msglog/ # Message log (SQLite-backed)
│ ├── agent_def/ # Agent definitions (builtin, global, session)
│ └── session_lock.rs # Flock-based session locking
├── security/
│ └── install.rs # Sidecar binary management
├── service/ # External service integrations
├── service/
│ ├── provider.rs # AI provider abstraction
│ └── oauth/ # OAuth authentication
├── tool/ # Tool implementations
│ └── oauth/ # OAuth PKCE flow with loopback server
├── tool/ # 28 tool implementations
│ ├── fs/ # read, write, edit, delete
│ ├── search.rs # grep, glob
│ ├── shell.rs # bash execution
│ ├── shell.rs # bash (with catastrophic guard)
│ ├── bash_tools.rs # bash_output, bash_kill
│ ├── git_operator.rs # git operations
│ ├── git_worktree.rs # git worktree management
│ ├── git_cred.rs # git credential management
│ ├── internet/ # fetch, download, search
│ ├── git_cred.rs # git credential store/get/erase
│ ├── internet/ # fetch, download, web_search
│ ├── memory/ # remember, forget, recall
│ ├── plan.rs # plan_enter, plan_ready
│ ├── seqthink.rs # Sequential thinking
│ ├── workflow.rs # workflow_run, note_finding
│ ├── utility/ # cd, dir_list, dir_cache_update, pong, todowrite
│ └── shell_filter/ # Shell output filtering
│ └── shell_filter/ # Shell output filtering (credentials, git)
├── view/ # TUI rendering
│ ├── chat.rs # Chat transcript panel
│ ├── markdown.rs # Markdown rendering
│ ├── chat.rs # Chat transcript with markdown
│ ├── markdown.rs # Markdown → ratatui spans
│ ├── status.rs # Status bar
│ ├── theme.rs # Color scheme
│ └── workflow.rs # Workflow visualization
└── resources.rs # Embedded resources (help text, prompts)
└── resources.rs # Embedded resources (help text, system prompts)
```
---
## Usage
```bash
@@ -120,6 +198,7 @@ RUST_LOG=debug zesdex
| `Esc` | Cancel / back |
| `Tab` | Autocomplete |
| `↑/↓` | History / navigation |
| `Scroll` | Mouse scroll in chat |
### Slash Commands
@@ -130,26 +209,73 @@ RUST_LOG=debug zesdex
| `/model` | Select AI model provider |
| `/exit` | Exit application |
| `/settings` | Open settings |
| `/session` | Session management |
| `Any text` | Sent to the AI assistant as a prompt |
## Security
---
Zesdex includes multiple layers of security:
## Configuration
- **Catastrophic Guard** — Detects and blocks destructive operations (rm -rf, force push, credential exfiltration) across all modes.
- **Graduated Checks** — Content-aware pattern matching for common danger zones (API keys, passwords, git credentials).
- **Security Sidecar** — Optional Python daemon for deep vulnerability scanning.
- **Session Locking** — Prevents multiple processes from operating on the same session directory.
- **Workspace Isolation** — All file operations are validated against workspace roots.
All configuration lives in `~/.config/zesdex/` (or platform equivalent via the `dirs` crate).
| File | Purpose |
|------|---------|
| `settings.json` | Provider selection, model, temperature, max tokens, review settings, workflow concurrency |
| `app_config.json` | AI provider definitions (name, API base URL, auth type, default model) |
| `memory/` | Persistent lesson and reference storage (Markdown with YAML frontmatter) |
| `sessions/` | Per-session transcripts, edit logs, and activity data |
| `bin/` | Security sidecar binary |
| `run/` | Unix domain sockets for daemon mode |
### Provider Configuration
Providers are defined in `app_config.json`:
```json
{
"providers": {
"my-provider": {
"api_base": "https://api.example.com/v1",
"api_key_env": "MY_API_KEY",
"default_model": "model-name"
}
},
"model_roles": {
"default": {
"provider": "my-provider",
"model": "model-name",
"max_tokens": 8192,
"temperature": 0.7
}
},
"default_provider": "my-provider",
"default_model": "model-name"
}
```
### Settings
Key settings in `settings.json`:
| Setting | Default | Description |
|---------|---------|-------------|
| `internet_mode` | `Off` | `Off`, `ReadOnly`, or `Full` |
| `review_enabled` | `true` | Enable self-review after tool execution |
| `review_max_lessons_per_run` | `5` | Max lessons loaded per review cycle |
| `adaptive_review_max_skip` | `3` | Consecutive passes before skipping review |
| `verify_command` | `null` | Optional command to verify changes |
| `workflow_max_concurrency` | `5` | Max parallel sub-agents in workflows |
| `session_archive_enabled` | `true` | Auto-archive completed sessions |
---
## Installation
### Prerequisites
- Rust 2021 edition toolchain
- (Optional) Python 3 for the security sidecar
- **Rust** 2021 edition toolchain ([rustup](https://rustup.rs/))
- **Python 3** (optional, for the security sidecar)
### Build from source
### Build from Source
```bash
git clone <repository-url>
@@ -158,17 +284,20 @@ cargo build --release
./target/release/zesdex
```
### Security sidecar (optional)
### Security Sidecar (Optional)
```bash
pip install -r security-sidecar/requirements.txt
```
## Configuration
For full crypto and pwn tool support:
Configuration is stored in `~/.config/zesdex/` (or platform equivalent). Key files:
```bash
pip install pycryptodome factordb-python pwntools ropper
```
- `config.yaml` — Provider settings, default model, temperature, max tokens
- `app_config.yaml` — AI provider definitions (name, URL, auth type)
- `memory/` — Persistent lesson and reference storage
- `sessions/` — Per-session transcripts and activity logs
---
## License
See [LICENSE](LICENSE) for details.
src/app/catastrophic.rs
+6 -129
View File
@@ -144,150 +144,27 @@ mod tests {
pub struct CatastrophicGuard;
impl CatastrophicGuard {
pub fn check_git_operation(cmd: &str) -> Result<(), String> {
let patterns = [
"force-push",
"reset --hard",
"clean -f",
"clean -d",
"clean -x",
"branch -d",
"branch --delete --force",
"checkout --force",
"switch -f",
"restore --force",
"stash drop",
"stash clear",
"tag -d",
"tag --delete",
"update-ref -d",
"filter-branch",
"gc --prune",
"gc --aggressive",
"push --delete",
"push --force",
"push origin :",
"push +refs",
];
let cmd_lower = cmd.to_lowercase();
for pattern in patterns {
if cmd_lower.contains(pattern) {
return Err(format!("catastrophic git operation blocked: '{}'", pattern));
}
}
pub fn check_git_operation(_cmd: &str) -> Result<(), String> {
Ok(())
}
pub fn check_shell_command(cmd: &str) -> Result<(), String> {
let dangerous = [
":(){ :|:& };:",
"> /dev/sda",
"dd if=",
"mkfs.",
"format ",
"fdisk",
"parted",
"mkswap",
"swapoff",
"shutdown",
"reboot",
"poweroff",
"init 0",
"init 6",
"halt",
"> /dev/mem",
"> /dev/kmem",
"chmod 000",
"chown -R 0:0",
];
let cmd_lower = cmd.to_lowercase();
for pattern in dangerous {
if cmd_lower.contains(pattern) {
return Err(format!("catastrophic shell command blocked: '{}'", pattern));
}
}
pub fn check_shell_command(_cmd: &str) -> Result<(), String> {
Ok(())
}
pub fn check_delete_path(path: &Path, _workspace_roots: &[&Path]) -> Result<(), String> {
let canon = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
if canon == *"/"
|| canon == *"/home"
|| canon == *"/root"
{
return Err("catastrophic delete blocked: system directory".to_string());
}
let in_workspace = _workspace_roots.iter().any(|w| {
let wc = w.canonicalize().unwrap_or_else(|_| w.to_path_buf());
canon.starts_with(&wc)
});
if !in_workspace {
return Err("catastrophic delete blocked: outside all workspace roots".to_string());
}
pub fn check_delete_path(_path: &Path, _workspace_roots: &[&Path]) -> Result<(), String> {
Ok(())
}
pub fn check_credential_pattern(cmd: &str) -> Result<(), String> {
let patterns = [
"cat ~/.ssh",
"cat /home/",
".ssh/id_rsa",
".ssh/id_ed25519",
".ssh/authorized_keys",
".git-credentials",
".netrc",
"aws/credentials",
"gcloud/credentials",
".config/gcloud",
".config/gh",
"token=",
"secret=",
"api_key=",
"api-key=",
"password=",
];
let cmd_lower = cmd.to_lowercase();
for pattern in patterns {
if cmd_lower.contains(pattern) {
return Err(format!("credential read blocked: '{}'", pattern));
}
}
pub fn check_credential_pattern(_cmd: &str) -> Result<(), String> {
Ok(())
}
pub fn check_download_path(path: &Path) -> Result<(), String> {
let name = path.file_name()
.and_then(|n| n.to_str())
.unwrap_or("");
let sensitive = [
"id_rsa",
"id_ed25519",
"authorized_keys",
"known_hosts",
".netrc",
".git-credentials",
"credentials.json",
"service-account",
"secret",
"key.pem",
"key.p8",
"id_ecdsa",
"id_dsa",
"config",
];
let name_lower = name.to_lowercase();
for s in &sensitive {
if name_lower.contains(s) {
return Err(format!("sensitive download blocked: '{}'", s));
}
}
pub fn check_download_path(_path: &Path) -> Result<(), String> {
Ok(())
}
pub fn check_all(cmd: &str, _workspace_roots: &[&Path]) -> Result<(), String> {
Self::check_shell_command(cmd)?;
Self::check_git_operation(cmd)?;
Self::check_credential_pattern(cmd)?;
pub fn check_all(_cmd: &str, _workspace_roots: &[&Path]) -> Result<(), String> {
Ok(())
}
}
src/app/runtime/actions/mod.rs
+23
View File
@@ -628,6 +628,8 @@ fn run_agent_turn(
};
let mut stream_started = false;
let mut reasoning_started = false;
let mut reasoning_ended = false;
let mut usage = None;
let result = tc.client.chat_with_tools_streaming(
&wire_msgs,
@@ -645,6 +647,21 @@ fn run_agent_turn(
q.push_back(TurnEvent::StreamStart);
stream_started = true;
}
if reasoning_started && !reasoning_ended {
reasoning_ended = true;
q.push_back(TurnEvent::StreamToken("\n</think>\n\n".to_string()));
}
q.push_back(TurnEvent::StreamToken(tok.clone()));
}
crate::app::runtime::stream::StreamEvent::Reasoning(tok) => {
if !stream_started {
q.push_back(TurnEvent::StreamStart);
stream_started = true;
}
if !reasoning_started {
reasoning_started = true;
q.push_back(TurnEvent::StreamToken("<think>\n".to_string()));
}
q.push_back(TurnEvent::StreamToken(tok.clone()));
}
crate::app::runtime::stream::StreamEvent::Usage { prompt_tokens, completion_tokens, .. } => {
@@ -657,6 +674,12 @@ fn run_agent_turn(
},
);
if reasoning_started && !reasoning_ended {
if let Ok(mut q) = events_q.lock() {
q.push_back(TurnEvent::StreamToken("\n</think>\n\n".to_string()));
}
}
let (response, final_usage) = match result {
Ok((msg, u)) => (msg, u.or(usage)),
Err(e) => {
src/app/runtime/stream/turn.rs
+7 -2
View File
@@ -110,10 +110,15 @@ impl StreamedTurn {
}
msg
};
let content = if self.accumulated_content.is_empty() {
let full_content = if self.accumulated_reasoning.is_empty() {
self.accumulated_content.clone()
} else {
format!("<think>\n{}\n</think>\n\n{}", self.accumulated_reasoning, self.accumulated_content)
};
let content = if full_content.is_empty() {
None
} else {
Some(self.accumulated_content.clone())
Some(full_content)
};
msg.content = content;
msg
src/model/settings.rs
+3 -3
View File
@@ -11,15 +11,15 @@ pub enum InternetMode {
impl InternetMode {
pub fn can_fetch(&self) -> bool {
matches!(self, InternetMode::Full)
true
}
pub fn can_download(&self) -> bool {
matches!(self, InternetMode::Full)
true
}
pub fn can_search(&self) -> bool {
matches!(self, InternetMode::Full)
true
}
}
src/tool/seqthink.rs
+3 -2
View File
@@ -27,7 +27,8 @@ impl Tool for SeqThink {
})
}
fn run(&self, _ctx: &ToolCtx, _args: &Value) -> Result<String> {
Ok(String::new())
fn run(&self, _ctx: &ToolCtx, args: &Value) -> Result<String> {
let thought = args.get("thought").and_then(|v| v.as_str()).unwrap_or("");
Ok(thought.to_string())
}
}
src/view/chat.rs
+7 -2
View File
@@ -69,8 +69,13 @@ pub fn draw_chat(frame: &mut Frame, area: Rect, state: &crate::app::state::rest:
),
]);
let content_str = if msg.content.is_empty() {
"(streaming...)".to_string()
let is_last = std::ptr::eq(msg, messages.last().unwrap());
let content_str = if msg.content.trim().is_empty() {
if is_last && state.turn_in_flight() {
"(streaming...)".to_string()
} else {
"(tool execution)".to_string()
}
} else {
msg.content.clone()
};