Metadata-Version: 2.4
Name: iocx-registry-keys
Version: 1.0.0
Summary: High-performance iocx plugin for detecting Windows Registry keys, values, and persistence locations.
Author: MalX Labs
License: MIT
Project-URL: Homepage, https://iocx.dev
Project-URL: Repository, https://github.com/iocx-dev/iocx-registry-keys
Keywords: iocx,iocx-plugin,registry,windows-registry,registry-keys,registry-values,registry-persistence,autorun,persistence,malware-analysis,dfir,ioc-extraction,security
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: iocx>=0.4.0
Dynamic: license-file

# iocx-registry-keys

A high‑performance plugin for the `iocx` engine that extracts Windows Registry **keys**, **value types** and **persistence locations** from Windows PE files and raw text.

This plugin is designed for malware analysis, DFIR workflows, and automated IOC extraction pipelines. It provides fast, regex-safe detection with full test coverage and predictable performance.

---

## Features

✔ Registry Keys

Detects Windows registry paths such as:

```
HKCU\Software\Example
HKLM\System\CurrentControlSet\Services\Tcpip
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows
```

✔ Registry Value Types

Identifies common registry value types:

```
REG_SZ
REG_DWORD
REG_BINARY
REG_QWORD
REG_MULTI_SZ
REG_EXPAND_SZ
```

✔ Persistence Locations

Extracts autorun and service-based persistence keys, including:

```
HKCU\Software\Microsoft\Windows\CurrentVersion\Run
HKLM\Software\Microsoft\Windows\CurrentVersion\RunOnce
HKCU\Software\Microsoft\Windows\CurrentVersion\Policies\Explorer\Run
```

✔ High Performance

All detectors are optimized to avoid backtracking and scale linearly with input size.

## Installation

Install from PyPI:

```bash
pip install iocx-registry-keys
```
This plugin is automatically discovered by `iocx` via entry points.

## Usage

### Extracting from raw text

```python
from iocx import Engine

engine = Engine()
result = engine.extract("HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run")

print(result["iocs"])
```

### Extracting from a Windows PE file 

```python
from iocx import Engine

engine = Engine()
result = engine.extract(malware_sample.exe)

print(result["iocs"])
```

Output:

```json
{
  "registry.persistence": [
    "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run"
  ],
  "registry.keys": [],
  "registry.values": []
}
```

## Development

### Install dependencies

```bash
make install
```

### Run tests

```bash
make test
```
```bash
make test-performance
```

### Run coverage

```bash
make test-coverage
```

### Run security checks
```bash
make security
```

This runs:

- pip-audit for dependency vulnerabilities
- bandit for static code security analysis

## Performance

This plugin includes a full performance suite.

Example results on a typical machine:

```
registry-keys 1MB mixed-content:       ~0.002s
registry-values 1MB mixed-content:     ~0.001s
registry-persistence 1MB mixed-content ~0.002s
```

Performance remains stable even on pathological inputs.

## License

MIT License. See LICENSE for details
