• Introduction
• Features
• Requirements
• Installation
  • Building From Source
  • Arch Linux Package Installation
• Configuration
  • TOML Configuration File
  • Permissions
• Usage
  • Commands
    • Screenshot of the Help Command
    • Explanation of Each Command
  • Daemon / Systemd Service
• Data Storage Structure
• Examples
  • Quick Dump Example
  • Clearing Data
  • Viewing File Sizes
• Logging & Debugging
• FAQ
• Troubleshooting
• Contributing
• License
• Author / Maintainer
• Acknowledgments

Mouse Entropy is a command-line tool designed primarily for Arch-based Linux systems to capture and store raw mouse event data. It can be useful for various purposes, such as:

1. Generating entropy from user mouse movements.
2. Analyzing mouse usage patterns.
3. Collecting mouse input for testing or further research on human-computer interaction.

The tool reads events from the Linux mouse input device (/dev/input/mice by default) in real time and saves them to binary files. Data can then be easily dumped to CSV format for offline analysis.

• Real-time capturing of mouse data from /dev/input/mice.
• Configurable storage (directory structure, permissions, file sizes).
• Easy-to-use CLI with subcommands for starting, stopping, clearing, dumping, and summarizing data sizes.
• Automatic file rotation after configurable max file size is reached, preventing single large files.
• Daily folder structure for easy organization, e.g. data/YYYY/MM/DD.
• CSV export for offline analysis.
• Arch Linux systemd service for hands-off, daemonized operation.

• Rust (if building from source)
• Cargo (if building from source)
• Arch Linux or an Arch-based distribution (for the provided .service file and PKGBUILD usage).
• Privileges: You typically need to run as root or be a member of the input group to access /dev/input/mice.

1. Clone this repository:

   git clone https://github.com/anto18671/mouse-entropy.git

2. Navigate to the project folder:

   cd mouse-entropy

3. Build in release mode:

   cargo build --release

4. Optionally, install it system-wide:

   sudo install -Dm755 target/release/mouse-entropy /usr/bin/mouse-entropy

5. Copy or move the default config file:

   sudo mkdir -p /etc/mouse-entropy
   sudo cp mouse-entropy.toml /etc/mouse-entropy/

A PKGBUILD file is provided for Arch-based systems. You can build and install it using your favorite AUR helper or with the standard makepkg workflow.

1. Download (or clone) the PKGBUILD and related files (mouse-entropy.install, .service, .toml, etc.).

2. Run:

   makepkg -si

   This command will:

   • Build the package.
   • Prompt to install it (-i).
   • Place the binary into /usr/bin/mouse-entropy.
   • Place the default config into /etc/mouse-entropy/mouse-entropy.toml.
   • Place the systemd service into /usr/lib/systemd/system/mouse-entropy.service.

Once installed, you have a fully functional mouse-entropy command-line tool.

The default configuration file is stored in:

/etc/mouse-entropy/mouse-entropy.toml

Below is an example TOML file with annotations:

[storage]
base_directory = "data"             # Directory where recorded data is stored
directory_permissions = 448         # Decimal equivalent of 0o700 => drwx------
file_permissions = 384              # Decimal equivalent of 0o600 => -rw-------
max_file_size_mb = 2                # Maximum size of each data chunk file
store_4_bytes = false               # If true => store 4 bytes per event ([button, dx, dy, 0])
device_path = "/dev/input/mice"     # Path to the mouse device file

Key Points:

• base_directory: Where all data is stored. Can be absolute or relative.
• directory_permissions: The directory permissions in decimal format. 448 = 0o700.
• file_permissions: The file permissions in decimal format. 384 = 0o600.
• max_file_size_mb: Once a data file hits this size, a new file is created.
• store_4_bytes: Whether to store 3 or 4 bytes per event. The 4th byte is a zero-byte placeholder.
• device_path: The input device. On many Linux systems, /dev/input/mice is used for aggregated mouse movements.

• If using the default device_path = "/dev/input/mice", you need read access to this special file.
  • Typically, you must run mouse-entropy as root or be in the input group.
• The stored data and directories are created with the specified permissions (e.g., 0o700 for directories and 0o600 for files by default).

mouse-entropy is a command-line tool with multiple subcommands. Once installed, you can type mouse-entropy --help or just run it to see usage instructions.

Below is a screenshot of the help command output, followed by a detailed explanation for each subcommand.

$ mouse-entropy --help

Usage: mouse-entropy <COMMAND>

Commands:
  start    Start capturing mouse data in the foreground
  stop     Stop capturing (stub; real implementation depends on daemonization)
  clear    Clear all recorded data
  dump     Dump data as CSV (optionally for one specific YYYY-MM-DD)
  size     Summarize the size of all recorded data
  help     Print this message or the help of the given subcommand(s)

(Imagine a screenshot image here in your final README, showing the same content. Replace this code block with an actual screenshot or keep it as text if you prefer.)

1. start

   • Launches real-time capturing of mouse events from the configured device_path.
   • Stores the binary event data into daily subfolders, splitting files when they exceed max_file_size_mb.
   • Output continues until you interrupt (Ctrl + C) or otherwise kill the process.

2. stop

   • A stub subcommand. In future or alternative daemonized approaches, this could stop a running service or kill a process by PID file. Currently, use Ctrl + C or systemd to stop.

3. clear

   • Removes all recorded data in the configured base_directory.
   • Warning: This is irreversible.

4. dump

   • Converts stored binary data to CSV output, either to stdout or a specified file.
   • Optionally specify a date (YYYY-MM-DD) to only dump a single day's data.
     • Example: mouse-entropy dump --date 2025-01-01 --output data_2025_01_01.csv
   • If no date is specified, all days in base_directory are read and dumped.

5. size

   • Recursively walks the storage directories to calculate total usage by day, month, and year.
   • Shows a summary of how large your stored data has become.

Running mouse-entropy start manually will keep it in the foreground. For a persistent service, especially on an Arch-based system, you can use the included systemd unit file:

1. Enable and start the service:

   sudo systemctl enable mouse-entropy.service
   sudo systemctl start mouse-entropy.service

2. Check logs:

   journalctl -u mouse-entropy.service

3. Stop the service:

   sudo systemctl stop mouse-entropy.service

With systemd managing the process, it will automatically restart on reboots and run in the background.

When mouse-entropy start is running, it creates subdirectories under base_directory following this pattern:

base_directory/
└── YYYY
    └── MM
        └── DD
            ├── YYYY-MM-DD-00001.bin
            ├── YYYY-MM-DD-00002.bin
            └── ...

For each day, each chunk file is named:

YYYY-MM-DD-xxxxx.bin

Where xxxxx is a 5-digit zero-padded index (e.g., 00001).

Each .bin file contains a raw sequence of 3 or 4 bytes per mouse event. The first byte is the button flags, and the second and third bytes are the signed dx, dy (movements). If store_4_bytes is true, a zero-padding byte is added as the fourth byte.

Let's say you have been capturing data for a while and now want to convert a single day's data to CSV.

mouse-entropy dump --date 2025-01-01 --output january_1_data.csv

The resulting CSV file january_1_data.csv might look like this:

button,dx,dy
8,1,-1
8,1,0
8,1,2
8,1,1
...

• button: The raw button byte.
• dx and dy: Movement deltas (signed 8-bit integers).

To remove all collected data:

mouse-entropy clear

By default, it removes whatever is in base_directory (as configured by your TOML file). Use with caution.

If you’d like to see how much data has been collected so far:

mouse-entropy size

Example output might be:

Year 2025 Month 01 Day 01 => 12345 bytes
Year 2025 Month 01 Day 02 => 45678 bytes
Year 2025 Month 01 => 58023 bytes
Year 2025 => 58023 bytes
Total across all years/months/days => 58023 bytes

This tool doesn’t provide extensive logging by default. However, if you run it in the foreground (i.e., mouse-entropy start directly), you can see:

• Basic console messages (starting, capturing, file rotation).
• Error messages if the device can’t be opened or read.

For systemd logging, use journalctl -u mouse-entropy.service.

1. Why do I need root privileges to capture mouse events?
   By default, most Linux systems restrict read access to /dev/input/mice. You can change group permissions for the input group or run as root.

2. How can I run this automatically on boot?
   Use the included systemd service file:

   sudo systemctl enable mouse-entropy.service
   sudo systemctl start mouse-entropy.service

3. How do I parse the raw .bin files without dumping to CSV?
   Each record is 3 or 4 bytes. You can parse them in your own scripts if desired:

   • Byte 0: Button bits.
   • Byte 1: dx (signed).
   • Byte 2: dy (signed).
   • Byte 3 (optional): Zero padding if store_4_bytes = true.

4. Can I store data somewhere other than data/?
   Yes, simply change the base_directory in /etc/mouse-entropy/mouse-entropy.toml.

5. What about security concerns with storing raw mouse data?

   • We store local files with restricted permissions (by default 0700 for directories, 0600 for files).
   • If you’re worried about the sensitivity of this data, ensure you have appropriate backups and protections.

• Permission Denied when reading /dev/input/mice:
  Make sure you run as root or have read permissions on that device.
• No data is being generated:
  Check system logs (journalctl -u mouse-entropy.service) or run in the foreground to see errors. Perhaps your device path is different from /dev/input/mice.
• Files are not rotating:
  Confirm max_file_size_mb in your config. Large mouse inactivity means it might take a while to reach the threshold.

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a new branch for your feature/bug fix.
3. Make and test your changes.
4. Submit a Pull Request describing the changes.

Please open an issue first if you plan a significant change or need guidance.

This project is licensed under the MIT License.
Feel free to use, modify, and distribute this software in accordance with the MIT license terms.

• Author: Anthony Therrien

Contributions by the open-source community are greatly appreciated.

• Rust for making safe, performant CLIs easy.
• Arch Linux for providing a lightweight, DIY approach that fosters tools like this.

Feel free to leave a star on the GitHub repository if you find this project useful!