NativeRelay 0.4.0 Beta 1

NativeRelay 0.4.0 Beta 1

NativeRelay 0.4.0 Beta 1 is a prerelease for testing the Windows collector and its integration with the existing NativeRelay event model and CLI. It is intended for evaluation and feedback, not as a claim of complete or lossless operating-system auditing.

This beta is distributed through the GitHub release assets. It is not published to PyPI. Prerelease tags run build and test validation, while the PyPI publishing job is skipped.

What's included

• Windows process start and exit events using WMI trace notifications when available, with Toolhelp process snapshots as a degraded fallback.
• Scoped, recursive Windows file create, modify, delete, and rename notifications using ReadDirectoryChangesW.
• Runtime capability and health reporting, path filtering, bounded-stream loss reporting, and collector shutdown handling.
• Explicit limitations in the shared event model: Windows file notifications use PID 0 to mean the actor is unknown, and Windows file-open events are unsupported.
• Windows collector unit and live integration tests, with GitHub Actions validation on Windows Server 2022 and 2025.
• No new runtime Python dependencies.

Requirements and support status

• Python 3.11 or newer.
• Windows 10 or Windows 11 for the Windows collector. Windows 10 was used for local live testing. Windows Server 2022 and 2025 passed the hosted CI tests.
• Windows 11 client behavior has not been verified. WMI-backed process delivery has also not been verified on a host where the WMI subscription is permitted; local live testing used the Toolhelp polling fallback.
• Linux support remains available with its existing platform-specific requirements and limitations. macOS collection is not included.

See the platform support matrix for capability details and known limits.

Install the beta

Download nativerelay-0.4.0b1-py3-none-any.whl from this GitHub release's Assets section, then install it from PowerShell:

python --version
python -m pip install .\nativerelay-0.4.0b1-py3-none-any.whl

The version command should report Python 3.11 or newer. Do not use pip install nativerelay==0.4.0b1; this beta is not on PyPI.

Try it safely

Start with a temporary directory, not a home directory or a sensitive project:

$scope = Join-Path $env:TEMP "nativerelay-beta-test"
New-Item -ItemType Directory -Force $scope | Out-Null
python -m nativerelay.cli capabilities --scope $scope

Review the capability report before interpreting silence as evidence that nothing happened. Filesystem monitoring should report whether it is available. Process monitoring may report available for WMI tracing or degraded for Toolhelp polling. The polling fallback checks process snapshots every 200 ms and can miss short-lived processes.

In one PowerShell window, start the JSONL event stream:

nativerelay run --format json --scope $scope

In a second window, create, modify, rename, and delete a file inside the same scope:

$scope = Join-Path $env:TEMP "nativerelay-beta-test"
$file = Join-Path $scope "sample.txt"
Set-Content $file "first"
Set-Content $file "changed"
Rename-Item $file "renamed.txt"
Remove-Item (Join-Path $scope "renamed.txt")

Process events cover activity observed after collection starts; already-running processes are not reported as new starts. Stop the stream with Ctrl+C. If testing from a source checkout, run the focused integration tests with:

python -m unittest discover -s tests -p test_windows.py -v

That test creates a temporary child process and temporary files. It requires a working process source and filesystem notifications.

Known limitations

• Windows file events are not attributed to the process that caused them; process.pid is 0 for an unknown actor.
• Windows file-open events are unsupported.
• Toolhelp polling can miss short-lived processes and does not report processes that were already running when collection began.
• WMI process tracing may be unavailable because of host policy or permissions. In that case the collector reports degraded status and uses polling if the fallback is available.
• Rename notifications are emitted as separate source and destination events. Consumers must correlate them if they need a single rename operation.
• Monitoring is limited to the selected directory scope. Native notification overflow or stream drops can cause lost events; the collector reports detected loss but cannot replay missed notifications.
• Windows 11 client behavior and WMI-backed process delivery on an authorized host remain unverified.
• NativeRelay does not provide complete audit coverage, identify AI agents, or capture file contents. Process command-line capture is opt-in and may expose sensitive arguments.

Privacy and safe testing

NativeRelay is local-first and does not require an account, cloud service, or remote telemetry. Use a disposable test directory and avoid enabling command-line capture unless you understand that process arguments can contain secrets. Do not include private file contents, credentials, or unredacted sensitive paths in feedback.

Reporting issues and sharing feedback

Please open a GitHub Discussion for questions, setup help, and general beta feedback. Open a GitHub issue for a reproducible defect.

For collector problems, include:

• Windows edition, version, and build, plus the Python version.
• The command you ran and the event or behavior you expected.
• The relevant capability and health status, including whether process mode was WMI or Toolhelp polling.
• A concise error message or traceback, with usernames and sensitive paths redacted.
• Whether the issue reproduces with a fresh temporary directory.

Please do not attach file contents, credentials, or command lines that may contain secrets.

Validation evidence

• Windows live integration was exercised locally on Windows 10; the local process source used Toolhelp polling because WMI tracing was unavailable.
• The Windows collector test workflow passed on Windows Server 2022 and Windows Server 2025.
• The full local test suite passed: 35 tests, with two Linux-only integration tests skipped.
• The tagged release workflow verified the beta version, ran tests, built and checked the wheel, and skipped the PyPI publishing job.

These results provide useful regression and live-test evidence, but do not replace Windows 11 client or WMI-path validation.