sysmaid 0.7.8

For Windows powerusers: A Python-based DSL designed to easily discover and govern unruly background applications and services.

SysMaid

简体中文

SysMaid is a high-level win32 api abstraction layer for Windows, allowing users to discover and optimize the system's background environment by writing simple Python scripts. It acts like a uBlock Origin for process management, designed to address the background resource abuse by "must-use software" and aims to become the most comprehensive AutoRun ecosystem on Windows.

Downloaded file disappeared?

Due to SysMaid's behavior involving system-level process monitoring and operations, some antivirus software (like Windows Defender) may misreport it as a potential threat. To ensure the program runs correctly, it is strongly recommended to add your script, the packaged .exe file, or its directory to your antivirus software's whitelist.

Core Features

• Concise Rule Definition: Intuitively define monitoring rules using Python decorators.
• Process and Service Monitoring: Easily monitor the status of specified processes, such as whether a window exists or if a process has exited.
• Automated Actions: Automatically execute actions when conditions are met, such as killing a process, stopping a service, or locking an encrypted volume.
• Extensibility: Easily add new conditions and actions to meet more complex needs.

Quick Start

Installation

pip install sysmaid

Usage

Create a Python file (e.g., my_rules.py) and add your rules:

import sysmaid as maid

if __name__ == "__main__":
    # Rule 1: Kill Canva.exe if it's running without a window
    Canva = maid.attend('Canva.exe')
    @Canva.has_no_window
    def _():
        maid.kill_process('Canva.exe')

    # Rule 2: Stop the related service when GameViewer.exe exits
    GameViewer = maid.attend('GameViewer.exe')
    @GameViewer.is_exited
    def _():
        maid.stop_service('GameViewerService')

    # Rule 3: Kill CrossDeviceResume.exe when it is running
    CrossDeviceResume = maid.attend('CrossDeviceResume.exe')
    @CrossDeviceResume.is_running
    def _():
        maid.kill_process('CrossDeviceResume.exe')

    # Rule 4: When Macrium Reflect finishes a backup or exits, automatically lock the backup drive (D:) and close the program
    # (Requires BitLocker to be enabled on drive D)
    Screen = maid.attend('Screen')
    Screen.stop()  # The screen listener is resource-intensive, so it's disabled by default
    @Screen.has_windows_look_like('samples\\MacriumSuccess.png')
    def _():
        maid.kill_process('Reflect.exe')

    Macrium = maid.attend('Reflect.exe')
    @Macrium.is_running
    def _():
        Screen.start()  # maid.attend instances can be started and stopped by rules
    @Macrium.is_exited
    def _():
        maid.lock_volume('D')
        Screen.stop()   # Stop has lower priority than Start and is reference-counted, ensuring safe parallel use

    # Rule 5: When CPU usage exceeds 80% for 10 consecutive seconds, report the top 5 CPU-consuming processes and log them.
    Cpu = maid.attend('cpu')
    @Cpu.is_too_busy(over=80, duration=10)
    # You can also specify per-logical-processor thresholds to resolve average utilization calculation errors on heterogeneous CPUs.
    # @Cpu.is_too_busy(over=[40,40,40,40,70,70,70,70], duration=5)
    def _():
        TopProcesses = maid.get_top_processes(5)
        maid.alarm(TopProcesses)
        maid.write_file('logs/TopProcesses.log',TopProcesses)

    # Set log level and start monitoring
    maid.set_log_level('INFO')
    maid.start()

Then run it:

python my_rules.py

Deployment: Packaging as a Background Service

To achieve true "background standby" and auto-start on boot, it is recommended to use Nuitka to package your rule script into a standalone .exe executable. Nuitka compiles the Python script into C code, generating an efficient, dependency-free program.

Install Nuitka:

pip install nuitka

Packaging Command:

nuitka --standalone --windows-uac-admin --windows-console-mode=disable --mingw64 your_rules.py

• --standalone: Creates a standalone folder with all dependencies included.
• --windows-uac-admin: Requests administrator privileges, which are necessary for operations like stopping services.
• --windows-console-mode=disable: Creates a windowless background application that won't show a black console window when run.
• --mingw64: Force the use of the MinGW64 compiler to prevent errors caused by Nuitka failing to find a C compiler.
• your_rules.py: Your rule script filename.

The output folder after a successful build is named your_rules.dist . To enable auto-start on boot, create a shortcut for the .exe file inside this folder and move it to the system's "Startup" folder.

Future Plans

SysMaid's goal extends beyond simple process management. We hope to develop it into the most comprehensive AutoRun ecosystem on Windows, including but not limited to:

• Richer trigger conditions (e.g., network activity, CPU/memory usage).
• More diverse response actions (e.g., modifying the registry, file operations).
• Providing a graphical user interface to make it accessible for users unfamiliar with programming.
• ...

Contributing

Contributions of any kind are welcome! If you have good ideas or find a bug, please feel free to submit an Issue or Pull Request. To capture logs, you can run the script directly in a Python environment and ensure the logging level is set to INFO or higher.

License

This project is open-sourced under the GPLv3 License.