parasite

Agent Architecture

Module Map

src/
├── main.rs       CLI args, TLS setup, mDNS registration, server start
├── server.rs     TCP listener, TLS accept, spawn per-client tasks
├── session.rs    Per-client dispatch loop (auth + message handling)
├── pty.rs        PTY session creation and I/O
└── file_ops.rs   Directory operations with path validation

Startup Flow

1. Parse CLI arguments (--listen, --daemon, --token)
2. Load config from ~/.config/parasite/config.toml (auto-generated on first run)
3. Initialize rustls crypto provider
4. Load or generate TLS certificate (~/.parasite/agent-cert.pem)
5. Load or generate auth token (~/.parasite/agent-token)
6. Register mDNS service for LAN discovery
7. Start TCP server on configured address (default from config.network.agent_port)

Per-Client Session

Each connected client gets its own handle_client task with:

• An authenticated TLS stream (reader/writer split)
• A HashMap<SessionId, ShellSession> for PTY sessions
• Three MPSC channels: network messages, PTY output, exit notifications

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│ Network      │────>│ Dispatch     │────>│ PTY Sessions │
│ Reader Task  │     │ Loop         │     │              │
└──────────────┘     └──────┬───────┘     └──────────────┘
                            │
                     ┌──────┴───────┐
                     │ File Ops     │
                     │ (sync/async) │
                     └──────────────┘

PTY Management

The agent uses portable-pty for cross-platform PTY support:

pub struct PtySession {
    master: Box<dyn MasterPty + Send>,
    child: Box<dyn Child + Send + Sync>,
    writer: Box<dyn Write + Send>,
}

• Open: Creates a PTY pair, spawns the user’s shell (from $SHELL or /bin/bash)
• Read: A spawn_blocking task reads PTY output in configurable chunks (config.buffers.pty_read_buffer_size)
• Write: Input from the client is written to the PTY master
• Resize: Terminal dimensions are forwarded to the PTY
• Exit: When the child process exits, the exit code is sent to the client

Terminal type is set via config.terminal.term (default: xterm-256color).

File Operations

All directory operations are in file_ops.rs with path validation:

Handler	Validates	Operation
handle_dir_list	validate_path	Read directory entries (dirs only)
handle_dir_create	validate_new_path	Create a new directory
handle_dir_rename	Both old/new	Rename/move a directory
handle_dir_delete	validate_path	Recursively delete a directory
handle_dir_search	validate_path	DFS search by name (configurable depth/results)

DirSearch runs in spawn_blocking since it performs recursive filesystem traversal.

Path Validation

Every file operation validates that the resolved path is within $HOME:

1. Resolve ~ → $HOME
2. Canonicalize (resolve .., symlinks)
3. Verify canonical.starts_with(home)
4. Extra: prevent deletion of $HOME itself

System Info

The agent collects system information using the sysinfo crate:

• Hostname, OS name, OS version
• CPU count
• Total/used memory
• Total/used disk space (aggregated across all disks)

mDNS Registration

The agent registers itself as a _parasite._tcp.local. service with properties:

• agent_id — hostname
• hostname — hostname
• token — auth token
• version — service version string