File Manager Secure

Perform safe file operations with path validation, dry-run previews, recoverable trash deletes, batch confirmations, and audit logging to prevent data loss.

Security Scan

The skill's stated behavior (safe file ops) roughly matches the included code, but there are unexplained inconsistencies (missing files, mismatched allowed paths, undocumented env usage) that warrant caution before installing.

Purpose & Capability

Name and description (safe file operations with dry-run, trash, path validation) align with the code in scripts/file_manager.py, which implements validation, dry-run planning, trash, logging, and search. However, SKILL.md lists additional helper modules (path_validator.py, trash_manager.py, operation_planner.py) and resources that are not present in the package — the implementation is a single monolithic script. Also SKILL.md advertises allowed dirs (Downloads, Documents) but the shipped code's ALLOWED_DIRS is limited to the workspace only. These mismatches are unexplained and reduce confidence that the package is complete and consistent.

Instruction Scope

SKILL.md provides CLI-style usage examples (file-secure ...) but no CLI wrapper or entrypoint is present in the manifest; only a Python script is bundled. The SKILL.md describes working in Downloads/Documents, yet the code enforces only a workspace directory. The code will read file contents (up to 1MB) when performing content search and will log operations to a log file under the workspace. There are no instructions or code that transmit data externally, but the mismatch between SKILL.md and shipped code means the runtime behavior an agent will follow may differ from documentation; the agent may not have the CLI described without additional code.

Install Mechanism

There is no install spec and no external downloads; the code is bundled with the skill. This is the lowest-risk install mechanism (nothing fetched from arbitrary URLs).

Credentials

The skill declares no required environment variables or credentials. The code does, however, honor an optional OPENCLAW_WORKSPACE env var to set WORKSPACE (defaulting to ~/.openclaw/workspace). That env var is not documented in requires.env. If an operator or environment sets OPENCLAW_WORKSPACE to a sensitive location, the skill's allowed-directory checks and operations would apply relative to that location — so the env var is a powerful knob. No other credentials or unrelated envs are requested.

Persistence & Privilege

The skill is not forced-always; model invocation is allowed (default). It writes logs, trash, and backups inside its own WORKSPACE paths only. It does not request system-wide configuration changes or other skills' secrets.

What to consider before installing

Before installing, verify these points: 1) The package lists additional modules and reference docs in SKILL.md but only ships scripts/file_manager.py — ask the publisher for the missing files or an explanation (single-file consolidation). 2) Confirm how the CLI is exposed: SKILL.md shows a file-secure command but there is no wrapper/entrypoint in the manifest; you may need to run the Python script directly. 3) Check the default WORKSPACE path and whether OPENCLAW_WORKSPACE is set in your environment — do NOT set OPENCLAW_WORKSPACE to a system or home directory containing sensitive data unless you trust the code. 4) Test the skill in a sandboxed environment (or with a temporary, isolated workspace) to confirm behavior, especially search (it reads file contents up to 1MB) and restore/empty-trash functionality. 5) If you rely on the Downloads/Documents behavior shown in SKILL.md, request clarification or updated code — currently the code restricts operations to the workspace only. 6) If you need higher assurance, have someone with code-review skills inspect the full file_manager.py implementation (and request the missing referenced modules) to ensure there is no hidden I/O or external communication.

name: file-manager-secure description: Safe file operations with validation, dry-run mode, and trash recovery. Alternative to dangerous rm/mv/cp commands.

---

File Manager Secure

Overview

Secure file management with data loss prevention:

• Dry-run mode — Preview all operations before execution
• Trash/recycle — Recoverable deletion instead of permanent rm
• Path validation — Prevent traversal attacks and forbidden paths
• Batch confirmation — Review file list before bulk operations
• Operation logging — Complete audit trail

Security Model

Layer 1: Path Sanitization

def validate_path(path: str) -> Path:
    # Resolve to absolute
    full_path = Path(path).resolve()
    
    # Check forbidden patterns
    FORBIDDEN_PATTERNS = [
        r"\.\.",           # Parent directory traversal
        r"~/.ssh",
        r"~/.gnupg",
        r"~/.aws",
        r"~/.docker",
        r"~/.kube",
        r"\.env",
        r"secret",
        r"token",
        r"credential",
        r"/etc/passwd",
        r"/etc/shadow",
        r"C:\\Windows\\System32",
        r"REGISTRY\\",
    ]
    
    # Must be within workspace or explicit allowlist
    WORKSPACE = Path.home() / ".openclaw" / "workspace"
    ALLOWED_DIRS = [WORKSPACE, Path.home() / "Downloads", Path.home() / "Documents"]
    
    for allowed in ALLOWED_DIRS:
        try:
            full_path.relative_to(allowed)
            return full_path
        except ValueError:
            continue
    
    raise PermissionError(f"Path {path} is outside allowed directories")

Layer 2: Operation Dry-Run

@dataclass
class FileOperation:
    op: str  # 'copy', 'move', 'delete', 'rename'
    source: Path
    dest: Optional[Path]
    size: int
    confirm_required: bool

# All operations return preview first
operations = plan_operations(files, action='delete')
show_preview(operations)  # User reviews
execute_with_confirmation(operations)  # Only after OK

Layer 3: Trash Recovery

TRASH_DIR = WORKSPACE / ".trash"

def safe_delete(path: Path):
    # Move to trash with metadata
    trash_entry = TRASH_DIR / f"{timestamp}_{path.name}"
    metadata = {
        "original_path": str(path),
        "deleted_at": timestamp,
        "size": path.stat().st_size,
    }
    shutil.move(path, trash_entry)
    save_metadata(trash_entry, metadata)
    # Auto-cleanup after 30 days

Layer 4: Bulk Protection

MAX_BULK_OPERATIONS = 50  # Require confirmation above this
MAX_TOTAL_SIZE = 100 * 1024 * 1024  # 100MB limit

# For large operations, require explicit --force flag

Capabilities

1. List Directory

# Safe ls with filters
file-secure list /path/to/dir --type *.csv --sort size --reverse

2. Search Files

# Content and name search
file-secure search "pattern" --in=/path --type=md --content  # Search in content
file-secure search "dataset*" --in=/path --type=csv            # Search by name

3. Copy Files (Dry-run first)

file-secure copy source.csv backup/          # Preview mode
file-secure copy source.csv backup/ --exec   # Execute after preview
file-secure copy *.csv backup/ --exec       # Bulk with confirmation

4. Move Files (Dry-run first)

file-secure move old/ processed/ --exec
file-secure move *.tmp trash/ --exec        # Safe to trash, recoverable

5. Delete Files → Trash (Recoverable)

file-secure delete old.csv                   # Move to trash
file-secure delete *.log --older-than=30d    # Delete old files
file-secure restore old.csv                  # Restore from trash
file-secure empty-trash                      # Permanent delete (with warning)

6. Analyze Directory

file-secure analyze datasets/               # Size by type, largest files
file-secure analyze datasets/ --duplicates  # Find duplicates

7. Backup/Restore

file-secure backup important.csv
file-secure restore important.csv.bak

Workflow

Safe Delete Process

1. Scan — Find matching files
2. Preview — Show list with sizes and total
3. Confirm — User reviews and approves
4. Trash — Move to recoverable trash
5. Log — Record operation
6. Verify — Confirm files moved

Safe Copy/Move Process

1. Dry-run — Show source → dest mapping
2. Conflict check — Detect overwrites
3. Confirm — User approves
4. Execute — Perform operations
5. Verify — Check results

Resources

scripts/

• file_manager.py — Main operations with safety layers
• path_validator.py — Path sanitization
• trash_manager.py — Trash operations and recovery
• operation_planner.py — Dry-run and batch planning

references/

• security_model.md — Complete security architecture
• recovery_guide.md — How to restore deleted files