pyrattle 0.2.0
Windows Defender wrapper
Requires Python: <4.0,>=3.12

# Pyrattle

## Overview

Pyrattle is a Python package designed to interface with Windows Defender, enabling users to perform various malware protection tasks, such as scanning for threats, updating signature definitions, and managing dynamic signatures. It leverages Windows Defender's command-line utility (MpCmdRun.exe) to execute its functions.

## Features
- Perform different types of scans (Quick, Full, Custom)
- Update malware protection signatures from UNC file shares or the Microsoft Malware Protection Center (MMPC)
- Add, list, and remove dynamic signatures for enhanced malware protection
- Flexible configuration for scan options including remediation, boot sector scanning, and more

## Installation
```
pip install pyrattle
```

## Usage
Importing the Package


```
from pyrattle import PyDefender, ScanType
```

## Initializing PyDefender

```
scanner = PyDefender()
# or
scanner = PyDefender(executable_path="C:\\Program Files\\Windows Defender\\MpCmdRun.exe")
```

## Performing a Scan
It can perform multiple kinds of scan:
- **Quick Scan**
    ```
    scan_result = scanner.scan(scan_type=ScanType.QUICK)
    ```
- **Full Scan**
    ```
    scan_result = scanner.scan(scan_type=ScanType.FULL)
    ```

- **Custom Scan**
    ```
    scan_result = scanner.scan(scan_type=ScanType.CUSTOM)
    print(scan_result)
    ```

## Updating Signature Definitions
- **From UNC File Share**
    ```
    success = scanner.updateSignature(unc=True, unc_path="\\\\path\\to\\unc\\share")
    ```

- **From Microsoft Malware Protection Center**
    ```
    success = scanner.updateSignature(mmpc=True)
    ```

## Managing Dynamic Signature
- **Adding a Dynamic Signature**
    ```
    success = scanner.addDynamicSignature(path="C:\\path\\to\\signature\\file")
    print("Signature added successfully:", success)
    ```

- **Listing All Dynamic Signatures**
    ```
    signatures = scanner.listAllDynamicSignatures()
    print("Dynamic Signatures:", signatures)
    ```

- **Removing a Dynamic Signature**
    ```
    success = scanner.removeDynamicSignature(signature_id="signature_id")
    print("Signature removed successfully:", success)
    ```

## API Reference

### PyDefender

#### `scan(scan_type=ScanType.DEFAULT, file=None, disable_remediation=False, boot_sector_scan=False, timeout=30, is_cancel=False)`

Performs a system scan based on the provided parameters.

- **scan_type**: The type of scan to perform (`ScanType.DEFAULT`, `ScanType.QUICK`, `ScanType.FULL`, `ScanType.CUSTOM`).
- **file**: The file or directory to be scanned (required for `ScanType.CUSTOM`).
- **disable_remediation**: If `True`, disables remediation actions for custom scans.
- **boot_sector_scan**: If `True`, enables boot sector scanning (only valid for custom scans).
- **timeout**: Timeout in days (maximum value is 30).
- **is_cancel**: If `True`, attempts to cancel any ongoing quick or full scan.

Returns a `ScanResult` object if successful.

#### `updateSignature(unc=False, unc_path=None, mmpc=False)`

Updates the signature definitions for malware protection.

- **unc**: If `True`, performs the update from a UNC file share.
- **unc_path**: The path to the UNC file share (required if `unc` is `True`).
- **mmpc**: If `True`, performs the update directly from the MMPC.

Returns `True` if the update was successful, `False` otherwise.

#### `addDynamicSignature(path)`

Adds a dynamic signature for malware protection from the specified path.

- **path**: The path to the dynamic signature file.

Returns `True` if the dynamic signature was added successfully, `False` otherwise.

#### `listAllDynamicSignatures()`

Lists all dynamic signatures currently in use.

Returns a list of dynamic signatures.

#### `removeDynamicSignature(signature_id)`

Removes a dynamic signature based on the provided signature ID.

- **signature_id**: The ID of the signature to be removed.

Returns `True` if the signature was removed successfully, `False` otherwise.



## Contributing
Contributions are welcome! Please submit a pull request or open an issue on GitHub.

## License
This project is licensed under the MIT License.