ruleforge-python 0.1.2

Python SDK for Ruleforge policy CLI orchestration and alert integrations.

Ruleforge Python SDK

ruleforge-python is a cross-platform Python SDK for running Ruleforge policies through the existing policy executable.

It provides:

• High-level managed service APIs with restart supervision.
• Low-level wrappers for run, serve, test, fmt, and bundle.
• Typed alert parsing from JSONL output.
• Pluggable alert sinks with optional disk-backed retry queue.

Supported wheel platforms (v1):

• Windows x86_64
• Linux manylinux2014_x86_64
• Linux manylinux2014_aarch64

Note: Windows connectors (winlog, evtx) remain Windows-only CLI features.

Install

pip install ruleforge-python

Quick Start (High Level)

from ruleforge.service import RuleforgeService
from ruleforge.sinks import StdoutSink

svc = RuleforgeService.from_sources_config(
    sources_config="/opt/ruleforge/config/sources.live.json",
    sources_status="/opt/ruleforge/state/ruleforge.sources.status.json",
    sinks=[StdoutSink()],
)

svc.start()
try:
    for alert in svc.iter_alerts():
        print(alert.rule, alert.severity, alert.emit)
finally:
    svc.stop()
    svc.wait()

Quick Start (Low Level)

from ruleforge.cli import run

result = run(
    rules="examples/rules.dsl",
    schema="examples/schema.json",
    input_path="examples/events.jsonl",
)

print("exit:", result.exit_code)
print("alerts:", len(result.alerts))

Binary Resolution

By default the SDK resolves policy in this order:

1. Explicit policy_path= argument.
2. RULEFORGE_POLICY_PATH environment variable.
3. Embedded packaged binary (ruleforge/bin/policy.exe on Windows, ruleforge/bin/policy on Linux).
4. PATH lookup (platform-specific names).

If no executable is found, an actionable BinaryResolutionError is raised.

Packaging Note

Build artifacts (wheel only):

python python/scripts/build_release_artifacts.py \
  --policy-binary-path <path-to-policy-binary> \
  --output-root <cmake-build>/python_package/<config> \
  --clean-dist \
  --skip-tests

Or use the CMake target:

cmake --build cmake-build-debug --config Debug --target package_ruleforge_python

Output location for the CMake target:

cmake-build-debug/python_package/Debug/dist

Stage a profile wheel into the shared release folder:

cmake --build cmake-build-debug --config Debug --target stage_ruleforge_python_wheel

Default staged release folder:

release/python/<RULEFORGE_VERSION>

Verify staged multi-platform bundle before upload:

cmake --build cmake-build-debug --config Debug --target verify_ruleforge_python_release

Manual publish flow (TestPyPI first):

python -m twine upload --repository-url https://test.pypi.org/legacy/ release/python/<version>/*.whl
python -m twine upload release/python/<version>/*.whl

Use API-token auth for uploads:

• TWINE_USERNAME=__token__
• TWINE_PASSWORD=<token>

The packaging flow stages files in a build-only folder and does not modify python/src/ruleforge/bin.

Windows Notifier Pack

The Windows notifier deployment assets are intentionally not shipped inside the Python wheel. Use the canonical pack under:

examples/windows_bad_event_notifier

License

• Package/project license: LICENSE (proprietary).
• Third-party notices: THIRD_PARTY_NOTICES.md.