AmuletEX

Zero-trust RBAC sandboxing. Chrono-Graveyard intercept. Terminal-only human key. AmuletEX turns AI agent risk on your machine into observable, reversible, mathematically contained engineering.

Comment

⭐ AmuletEX

Agent-Aware Sandboxed Virtual File Manager with Real-Time Control Dashboard

AmuletEX is a Rust-based Virtual File System (VFS) with kernel-level FUSE integration and a real-time Obsidian-Gold web dashboard, designed to protect your sensitive data from autonomous AI agents. By enforcing a zero-trust RBAC token system and a "Chrono-Graveyard" soft-delete engine, it transforms reactive security into a mathematically enforced fortress — while giving human operators a live, beautiful control plane to monitor every move an agent makes.

🚨 The Problem: Speed vs. Security in the Agentic Era

Today, autonomous AI agents spend more time executing filesystem actions than human developers. Behind the scenes, these tools are constantly issuing system calls — reading files, writing code, modifying configurations — almost entirely outside of human visibility.

In the race to ship products faster, developers are aggressively granting broad filesystem access to AI agents without understanding the blast radius. This "speed trap" has real consequences: recent assessments show security vulnerabilities have tripled since the mass adoption of agentic coding tools. If an agent hallucinates, suffers a prompt injection attack, or operates with a misconfigured token, it can silently exfiltrate SSH keys, overwrite .env files with production credentials, or wipe critical project data before you even realize something went wrong.

To mitigate this, security-conscious developers have been forced to run their AI agents inside clunky Virtual Machines or isolated containers. But this introduces massive friction to the developer experience and kills the velocity that made AI coding tools valuable in the first place.

The Question: What if you could keep the speed of running agents directly on your local machine, but physically guarantee they couldn't destroy your system?

💡 The Solution (Inspiration)

This exact dilemma inspired AmuletEX.

Imagine an AI coding agent with write access to your local filesystem. It's been given a task. Halfway through, it misreads context from a prompt injection buried in a third-party library. Without you knowing, it deletes your SSH keys, overwrites your .env with new values, and attempts to exfiltrate your credentials.json — all within seconds.

What do you do?

AmuletEX acts as an autonomous guardrail system — a "hardened amulet" around your filesystem. It ensures that even the most capable AI agents are physically and mathematically restricted from crossing defined boundaries, causing irreversible damage, or exfiltrating secrets. Developers can run their agents at full speed on their local host machine, with a live dashboard showing every single filesystem action in real time — and a human operator override that no agent can ever obtain.

🚀 What It Does

AmuletEX layers multiple independent security mechanisms that hold even if any single layer is bypassed:

  • 🔮 Agentic RBAC Token System: Per-agent cryptographic tokens with granular Read, Write, Delete, Admin permissions and precise path-level allowed_paths / blocked_paths lists. Tokens are maintained in a server-side registry — not client-side — preventing any client tampering or self-escalation.
  • ⏰ Chrono-Graveyard: Every deletion is intercepted and rerouted to a timestamped graveyard directory with a 24-hour TTL auto-purge. An agent can never permanently destroy a file within the TTL window. Human operators can restore any graveyard entry instantly from the dashboard. Agents are categorically — mathematically — blocked from accessing the graveyard at all.
  • 🎯 Pattern-Based Categorical Blocking: Filename pattern matching blocks access to id_rsa, .env, credentials, prod.env, and similar sensitive files regardless of what an agent's token says. These are pre-token, categorical refusals.
  • 🌐 Real-Time Obsidian-Gold Web Dashboard: The primary human interface. Streams live agent events via persistent WebSocket. Operators see every file read, write, block, and deletion as it happens. Includes full token management, graveyard restoration, prohibited path control, and a file explorer — all unlocked only with the dynamic session key.
  • 🔑 Dynamic Human Operator Session Key: On every server start, AmuletEX generates a random session key (amulet_op_xxxxxxxx) printed only to the terminal stderr. The dashboard is fully blurred and locked until this key is entered. No agent can obtain it — by design.
  • 🤖 Headless JSON CLI (Agent Interface): The intended interface for AI agents. Agents call amuletex --headless --token <TOKEN> --cmd <CMD> --path <PATH> for all filesystem operations. Responses are structured JSON with Base64-encoded file content for safe programmatic piping. The agent never touches the filesystem directly.
  • ⚡ FUSE Kernel Integration: On Linux, AmuletEX mounts as a kernel filesystem, routing every process's file operations through its security middleware at the OS level — with no agent cooperation required.

Key Innovation: We implement mathematical blocking for graveyard access. If an agent token is present and the target path is the graveyard, access is categorically impossible — not a permission flag that can be escalated, but a structural invariant baked into the authorization logic. Even Admin tokens cannot cross this boundary.

🤖 How Agents Are Actually Enforced

This is the question that matters: what stops a capable AI agent from just ignoring AmuletEX and accessing the filesystem directly?

The answer is layered, and each layer is independent:

Layer 1 — FUSE (Linux, strongest)

On Linux, AmuletEX mounts as a kernel-level FUSE filesystem. Every process on the machine — including AI agents — is forced through AmuletEX's security middleware for all file operations at the OS syscall level. No cooperation from the agent is required. The agent cannot "choose" to bypass it any more than it can choose to bypass the kernel.

Layer 2 — System Prompt Enforcement (Cross-Platform)

On Windows and in any environment without FUSE, agents are constrained through their system prompt / tool configuration. The agent is instructed that amuletex --headless is its only sanctioned filesystem interface. All direct file operations are out of scope. This is the same model used by Model Context Protocol (MCP) servers — the agent's filesystem tool calls are routed through AmuletEX, which then enforces token permissions server-side.

Layer 3 — The Dashboard Is Agent-Proof by Design

Even if a sophisticated agent uses browser automation (Playwright, Puppeteer) to try to reach the web dashboard:

  • The agent's automation browser runs in a fully isolated browser profile. It cannot share local storage, cookies, or session state with the human operator's open browser window. It will be met with the same blurred, locked passcode gate.
  • The dynamic session key is printed only to backend stderr — a terminal process the agent has no access to.
  • If the agent attempts to brute-force the passcode input, a thread-safe rate limiter triggers a 30-second lockout after 3 failed attempts and broadcasts a Security Breach alert to the dashboard.

Layer 4 — Server-Side Token Registry

Agent tokens are registered and enforced server-side, not client-side. An agent cannot modify its own token permissions, forge a new token, or pass token: null to impersonate the human operator. The server validates every request against its in-memory registry — no client value is trusted.

🛠️ How We Built It

  • Language: Rust (Edition 2021) — memory safety, ownership guarantees, zero-cost async for intensive file I/O.
  • Async Runtime: tokio for concurrent file operations and WebSocket handling.
  • Headless CLI: clap for the structured agent command interface.
  • Web API: axum 0.7 with WebSocket support and tower-http for CORS middleware.
  • Dashboard: React 18 + Vite, vanilla CSS with the Obsidian-Gold glassmorphism design system — fully custom modal and alert components replacing all native browser popups.
  • Security Engine: Custom RBAC in rbac.rs — normalize_path_to_string, is_path_under_or_equal, validate_token_for_read/write, categorical graveyard lockdown.
  • Data: serde + serde_json for token persistence, chrono for TTL management, dirs for cross-platform home directory detection.
  • FUSE: fuser 0.14 with abi-7-31 features (Linux only, platform-gated with #[cfg]).
  • Crypto: aes-gcm + rand + uuid for token generation and session key creation.
  • Legacy TUI: ratatui + crossterm — a full-screen terminal interface still available as a fallback for terminal-only environments, though the web dashboard is the primary human interface.

🚧 Challenges We Ran Into

  1. Windows UNC Path Bypass (Critical Security Flaw): This was the most dangerous bug we encountered. On Windows, std::fs::canonicalize() returns paths with a \\?\ UNC prefix and backslash separators — e.g. \\?\C:\Users\project\sandbox\private. Our initial RBAC blocked-path comparison used path.starts_with(blocked), which silently failed against UNC paths even when the logical path was identical. A sandboxed agent could navigate directly into sandbox/private/ — a directory that was supposed to be categorically blocked — simply because Windows represented the path differently. We built a custom normalize_path_to_string function that strips UNC prefixes, converts all backslashes to forward slashes, lowercases the entire string, and trims trailing separators. Path boundary checks now use is_path_under_or_equal which compares component-safe normalized strings, making the block 100% reliable across all Windows path representations.

  2. FUSE Cross-Platform Parity: FUSE is a Linux kernel feature. On Windows, cargo build must conditionally exclude the entire fuse_handler module and the fuser / libc crate dependencies. We implemented platform-conditional compilation (#[cfg(not(target_os = "windows"))]) across the module tree, providing clear WSL and WinFsp guidance to Windows users while preserving the full kernel-level experience on Linux.

  3. Human Operator Logging as "Anonymous": In the real-time activity event log, the human operator appeared as Anonymous instead of a named identity. The headless CLI correctly attributed events to the agent_name field inside the token, but the dashboard — operating without a token — had no identity to show. We added an operator_identity field to the dashboard session state that is populated on successful key verification, so human operator events are correctly attributed in the log stream.

✨ Accomplishments We're Proud Of

  • Airtight Windows Path Security: Building the normalize_path_to_string + is_path_under_or_equal engine that closes a class of path-bypass vulnerabilities unique to Windows canonicalize() output is our most critical security contribution. All 7 unit tests pass, including dedicated cases for UNC normalization and component-boundary matching.
  • Multi-Layer Agent Containment: FUSE interception, system prompt enforcement, a terminal-only session key, a brute-force rate limiter, and a server-side token registry — each layer is independently airtight, and together they create containment an AI agent genuinely cannot reason its way out of.
  • Mathematical Graveyard Lockdown: The graveyard access block is not a permission entry in a table. It is a structural invariant in the authorization code. It cannot be token-forged, admin-overridden, or misconfigured out of existence.
  • Premium Custom Modal System: We replaced every native browser alert(), confirm(), and prompt() dialog with a purpose-built glassmorphism modal system — maintaining the Obsidian-Gold aesthetic even at the most security-critical moments.
  • Dynamic Session Key Architecture: The human operator key regenerates on every server start and is printed only to stderr. A running agent process has no mechanism to read terminal output from a separate session. The authentication boundary is physically enforced, not just logically enforced.

🧠 What We Learned

  • Windows is a Different Security Universe: Path canonicalization, UNC prefixes, backslash vs. forward-slash, and case insensitivity make Windows a completely different security target than Linux. Any filesystem security tool must treat Windows path normalization as a first-class concern — not an afterthought.
  • Structural Boundaries Outlast Permission Systems: Permissions can be misconfigured, escalated, or forgotten. A mathematical invariant — "if a token is present, graveyard access is impossible, full stop" — cannot be misconfigured.
  • Agent Enforcement is a Layered Problem: No single mechanism is sufficient. FUSE covers Linux at the kernel level. System prompts cover agent tool configuration. The dashboard's terminal-key architecture covers the UI boundary. Rate limiting covers brute-force. Together, they form a containment system that doesn't have a single point of failure.
  • Rust Ownership is a Security Feature: The borrow checker prevented entire classes of race conditions in concurrent file operations. Predictable, low-latency performance under intensive I/O throughput comes for free.

🔮 What's Next for AmuletEX

  • WinFsp Integration: Native kernel-level FUSE support on Windows without requiring WSL — bringing system-wide OS-level interception to Windows developers.
  • MCP Server Mode: Exposing AmuletEX as a Model Context Protocol server so AI coding tools can declare their intended filesystem operations as structured tool calls, enabling pre-flight RBAC approval before any file is touched.
  • Signed Audit Logs: Cryptographically signed, tamper-evident event logs of all agent filesystem interactions for enterprise compliance and incident forensics.
  • Encryption at Rest: AES-256-GCM encryption of all graveyard contents so deleted secrets remain secrets even if the graveyard directory is discovered.
  • Token Expiry Alerts: Real-time dashboard notifications when agent tokens approach expiry, with one-click renewal for human operators.
  • Cloud Graveyard Sync: Optional encrypted sync of graveyard entries to S3/Cloudflare R2 for cross-machine recovery and backup.

Built With

  • aes-gcm
  • axum
  • chrono
  • crossterm
  • dirs
  • fuser
  • rand
  • ratatui
  • react18
  • reversible
  • rust
  • serde
  • serde-json
  • tokio
  • uuid
  • vanillacss
  • vite
  • websocket
Share this project:

Updates