resrm/SECURITY.md

resrm Threat Model and Security Scope

resrm is a command-line filesystem utility. It is designed to be executed intentionally by an operator, sometimes with elevated privileges, as a safer replacement for common rm usage. By default it moves files and directories into a per-user trash area and records minimal JSON metadata so they can later be listed, inspected, restored, pruned, or permanently emptied.

Because of that design, resrm's security model is different from that of a network service, web application, daemon, sandbox, or setuid program. resrm does not attempt to defend against arbitrary local compromise of the account executing it. If an attacker can control the command line, environment, current working directory, installed Python package, metadata file, trash directory, or Python runtime used by the operator, they may be able to influence what resrm does. That situation is considered a local trust-boundary failure outside resrm's intended security model.

resrm is not a secure deletion tool. It moves files by default and permanently removes files only when requested or when pruning/emptying trash. It does not overwrite storage blocks, wipe free space, defeat snapshots, or guarantee that file contents cannot be recovered by other means.

Core Assumptions

resrm assumes that the person running the tool understands what they are asking it to do.

In particular:

• If resrm is run as root, the root user is assumed to control and understand the command line, environment, current working directory, target paths, trash metadata, and installed Python package being used.
• If --skip-trash is used, the operator is intentionally bypassing the recoverable trash path and requesting permanent deletion.
• If --empty is used, the operator is intentionally permanently deleting the current user's trash contents.
• If RESRM_TRASH_LIFE is set, the operator is intentionally controlling the automatic trash retention period.
• The per-user metadata.json file and files/ directory are trusted local state for the user that owns them.
• The operator is expected to understand the impact of running filesystem removal and restore commands as root.

What resrm Stores

resrm stores trashed files and directories in a local per-user trash area.

For the current effective user, the default locations are:

normal users: ~/.local/share/resrm/files
root:         /root/.local/share/resrm/files
metadata:     <trash base>/metadata.json

For each trashed item, metadata currently includes:

• A random UUID hex id.
• The resolved original path as orig_path.
• The deletion timestamp as timestamp.

The file or directory contents are moved into:

<trash base>/files/<id>

resrm does not store:

• File hashes.
• A metadata schema version.
• ACLs as separate structured metadata.
• Extended attributes as separate structured metadata.
• Capabilities as separate structured metadata.
• SELinux, AppArmor, or other MAC labels as separate structured metadata.
• A cryptographic integrity record for metadata or trashed contents.
• A transaction log for crash recovery.

Some filesystem metadata may remain attached to the moved file or directory depending on the filesystem, platform, and shutil.move() behaviour. resrm does not model that metadata independently.

What Is In Scope

resrm tries to protect careful users and administrators from common accidental deletion mistakes while preserving familiar rm-style ergonomics.

In-scope security concerns include:

• Default removal should move files and directories to trash rather than permanently deleting them.
• --skip-trash should be the explicit path for immediate permanent deletion.
• --empty and automatic pruning should operate within the current user's configured resrm trash directory.
• Restore should not overwrite an existing original path; it should fall back to the current directory when the original path exists.
• Non-root users should not be given a false impression that they can manage root-owned files without sudo.
• Root-owned path handling should be explicit and understandable.
• Directory removal should require -r unless behaviour is intentionally redesigned.
• Symlink handling should avoid surprising target deletion in permanent-delete paths.
• Metadata parsing failures should not cause arbitrary code execution.
• Shell completion should use local metadata only and should not execute metadata contents.
• resrm should not automatically run sudo or otherwise escalate privileges.
• Python and subprocess-free implementation paths should avoid shell injection concerns for ordinary path names.

These measures are defense-in-depth. They are intended to reduce accidental permanent deletion, unexpected overwrite, unsafe restore behaviour, and misleading privilege behaviour when resrm is used normally.

What Is Out Of Scope

The following are generally out of scope and should not be reported as resrm vulnerabilities unless they also bypass one of resrm's explicit hardening mechanisms:

• A malicious local user who can already control the invoking user's command line, shell environment, current working directory, Python environment, installed package, or filesystem permissions.
• A root user intentionally deleting dangerous paths with --skip-trash.
• A root user intentionally emptying root's trash with --empty.
• A user intentionally setting RESRM_TRASH_LIFE to a short retention period.
• A user relying on resrm as a backup system after trash has been emptied, pruned, moved, corrupted, or manually edited.
• A user relying on resrm for secure deletion or anti-forensic wiping.
• A user relying on resrm to preserve ACLs, xattrs, capabilities, MAC labels, hard-link relationships, or every filesystem-specific attribute across moves and restores.
• A user relying on resrm as a sandbox for untrusted local users or untrusted path names selected by an attacker.
• A compromised system where an attacker already controls the user's trash directory, metadata file, shell, Python packages, environment, or filesystem namespace.
• Reports that amount to "if root runs this tool with malicious options, root can delete or move important files."

resrm is a tool for users and administrators, not a sandbox for hostile local users. It cannot make unsafe local trust decisions safe if the operator's own execution environment is already attacker-controlled.

Trusted Trash Metadata

resrm metadata is stored in a local JSON file named metadata.json under the user's trash base. This file should be treated as trusted local user state.

Metadata can contain filesystem paths and deletion timestamps. It does not contain a complete copy of filesystem metadata, but it can still reveal sensitive operational details such as filenames, directory layouts, and deletion times.

Before running restore, especially as root, the operator should be confident that the selected trash metadata is the intended local state and has not been tampered with.

resrm does not treat an arbitrary attacker-supplied metadata.json as untrusted input to be safely enforced. If an attacker can edit metadata, they may be able to influence restore destinations or make restore fail.

Default Trash Mode

Default removal moves an existing path to a UUID-named location under the selected trash directory and appends a metadata entry.

resrm file
resrm -r directory

For root-owned paths, a non-root process prints a permission message and refuses the default trash operation:

resrm: permission denied: 'path' (root-owned file, try sudo)

When possible, default trash mode chooses the trash base from the file owner's home directory. This is intended to support sudo workflows where root removes a user-owned file but the file remains associated with that user's resrm trash.

This is convenience behaviour, not a privilege boundary. Operators should still understand which user owns the file, which effective user is running the process, and which trash area will receive the moved object.

Permanent Deletion Paths

resrm has three permanent deletion mechanisms:

resrm --skip-trash PATH     immediate permanent deletion
resrm --empty               permanently remove current user's trash contents
automatic pruning           remove entries older than RESRM_TRASH_LIFE days

These operations are not recoverable by resrm.

--skip-trash uses shutil.rmtree() for directories and Path.unlink() for non-directories and symlinks. It is the operator's responsibility to use this only when immediate deletion is intended.

--empty removes entries inside the current user's trash file directory and clears current metadata.

Automatic pruning runs at the start of every resrm invocation. The retention period defaults to 7 days, falls back to 7 for invalid values, and has a minimum of 1 day.

Restore Behaviour

Restore uses trusted metadata to find the trashed object and original path.

resrm --restore <id-or-basename>

Candidate lookup works as follows:

1. exact basename match against the stored original path
2. id prefix match against the stored UUID

If multiple candidates match, resrm prompts for a selection.

Restore starts with the stored original path. If that path already exists, resrm restores to the current working directory using the original basename instead. This avoids direct overwrite of the original path.

Restore creates parent directories for the selected destination. Because restore destinations come from trusted metadata, metadata tampering is considered a local trust failure rather than something resrm promises to sandbox.

Symlinks And Filesystem Races

resrm operates on a live filesystem. Concurrent filesystem changes can affect what exists at the moment a remove, restore, empty, or prune operation runs.

Current symlink behaviour is operation-specific:

• Default trash mode uses shutil.move(), which normally moves the symlink itself when the path argument is a symlink.
• --skip-trash deletes symlink path entries with Path.unlink() rather than recursively deleting their targets.
• --inspect uses lstat() and displays symlink targets with os.readlink().
• Some ownership checks use stat() and therefore follow symlinks.

Reports that identify concrete symlink target deletion, unintended overwrite, or privilege-impacting time-of-check/time-of-use behaviour in normal resrm operations are useful. Reports that require the operator's account or root environment to already be attacker-controlled are usually out of scope.

Local Compromise

resrm includes guardrails against some dangerous local mistakes because it handles deletion-like operations. For example, default removal uses trash instead of immediate deletion, directories require -r, restore avoids overwriting an existing original path, and resrm does not automatically escalate privileges.

However, local compromise cannot be ruled out completely for a CLI filesystem tool. If an attacker can influence the user's shell, environment, metadata file, trash directory, Python packages, current working directory, or command-line arguments, they may be able to influence resrm's behaviour.

Such scenarios are treated as local compromise or operator trust failures, not as vulnerabilities in resrm by themselves.

Security Report Guidance

Useful vulnerability reports include issues where resrm behaves unsafely despite the documented trust model. Examples include:

• Default resrm PATH permanently deletes a file instead of moving it to trash under normal conditions.
• --skip-trash on a symlink deletes the target rather than the symlink path itself.
• Restore overwrites an existing original path without explicit operator approval.
• --empty removes files outside the current user's resrm trash directory.
• Automatic pruning removes files outside the current user's resrm trash directory.
• A non-root user can use normal resrm behaviour to move or delete root-owned files without appropriate filesystem permissions.
• Shell completion or metadata parsing executes code from metadata.
• Ordinary path names cause shell injection or command execution.
• A failed safety check is silently ignored and resrm proceeds with a dangerous permanent deletion.

Less useful reports, and normally out of scope, include:

• "Root can delete important files with --skip-trash."
• "A user can empty their own trash with --empty."
• "A user can set RESRM_TRASH_LIFE=1 and old trash is pruned."
• "A user can manually delete or corrupt their own trash directory."
• "A malicious local user can compromise resrm after already controlling the invoking user's environment, Python packages, or filesystem permissions."
• "resrm does not securely wipe deleted file contents from disk."
• "resrm does not guarantee backup-grade recovery after pruning, emptying, metadata tampering, or filesystem failure."

Reports about concrete bypasses of resrm's guardrails are welcome. The project does not treat intentional administrator-controlled execution as a vulnerability by itself.