Thanks for your interest in NativeRelay.
NativeRelay is an open-source project exploring a common event layer over native operating-system telemetry for developer tools.
The project is still early, so contributions that improve the design, research, documentation, and platform understanding are just as valuable as implementation work.
NativeRelay has an initial Linux implementation. Linux integration verification and collector reliability are current priorities; macOS and Windows remain future collectors.
- CN_PROC and fanotify live integration testing
- Kernel permission and coverage research
- Process connector loss reporting
- fanotify path and event handling review
- Reliable create/delete/rename telemetry research
- ETW research
- File I/O providers
- Process attribution
- Event correlation
- Permission requirements
- Collector design
- Testing across Windows versions
- Endpoint Security research
- Process events
- File events
- Entitlements and permissions
- Deployment requirements
- Collector design
- Testing across supported macOS versions
- Event-model design
- Capability representation
- Collector interfaces
- Serialization
- Event streaming
- API design
- Cross-platform normalization
- CLI development
- Testing infrastructure
- Examples
- Documentation
- Developer experience
You do not need to implement a collector to contribute.
If you know a platform's native telemetry system, a useful contribution might simply answer:
- What events can it actually observe?
- Can events be attributed to a process?
- What permissions are required?
- What information is available?
- What information is unavailable?
- Can events be lost?
- How are events correlated?
- What operating-system versions are supported?
- What deployment restrictions exist?
Please include links to authoritative documentation or reproducible experiments where possible.
Research should distinguish between:
Documented capability
Observed behavior
Inference
This is important because NativeRelay is intended to represent actual evidence rather than assumptions.
For significant architectural or platform changes, open a discussion or issue first.
This is especially useful for:
- new event families
- changes to the common event model
- new platform collectors
- breaking API changes
- new dependencies
- changes to privacy behavior
- changes that affect multiple collectors
Small fixes and documentation improvements generally do not need prior discussion.
Contributions should follow the project's design principles.
In particular:
If a platform cannot provide equivalent telemetry, expose that limitation.
A collector should report what the operating system tells us.
Higher-level interpretation belongs to consuming applications.
Native APIs and platform-specific behavior should remain inside the relevant collector whenever practical.
Do not collect file contents or other sensitive information when the observation does not require it.
A collector should not claim support for an event simply because the underlying API appears capable of producing it.
The repository is organized around these implementation areas:
NativeRelay/
├── docs/
│ ├── architecture.md
│ ├── event-model.md
│ ├── platform-support.md
│ └── design-principles.md
├── nativerelay/
│ ├── model.py
│ ├── collector.py
│ ├── stream.py
│ └── cli.py
├── collectors/
│ └── linux/
├── tests/
├── pyproject.toml
├── README.md
├── ROADMAP.md
├── CONTRIBUTING.md
└── LICENSE
The implementation structure may change as the project develops.
A good pull request should explain:
- What changed.
- Why it changed.
- Which platform or component it affects.
- How it was tested.
- Any limitations that remain.
For platform-specific changes, include the relevant OS version and environment where practical.
For example:
Platform: Linux
Kernel: 6.x
Collector: fanotify
Test environment: local development machine
Changes should include appropriate tests where practical.
At minimum, contributors should test:
- event construction
- normalization
- capability reporting
- error handling
- collector behavior
- platform-specific edge cases
Platform collectors should also include integration tests where the environment allows them.
Documentation is part of the implementation.
If a change introduces:
- a new event
- a new capability
- a new platform behavior
- a permission requirement
- a limitation
- a new API
update the relevant documentation with the change.
Do not rely on the implementation alone to communicate platform behavior.
Use clear commit messages that describe the change.
Examples:
feat: add linux file collector
fix: preserve process attribution
docs: clarify fanotify limitations
test: add file event normalization tests
refactor: isolate collector interface
The exact convention may evolve as the project grows.
When reporting a bug, include:
- operating system
- OS version
- NativeRelay version or commit
- collector being used
- reproduction steps
- expected behavior
- actual behavior
- relevant logs or events
Avoid including sensitive file paths, credentials, tokens, or private system information.
Do not publicly disclose a suspected security vulnerability before it has been reviewed.
See SECURITY.md for the project's security-reporting process.
If you are new to the project, useful starting points include:
- improving documentation
- testing existing behavior
- researching a platform API
- adding examples
- improving error messages
- adding event-model tests
- reproducing platform-specific behavior
- improving the CLI
You do not need to understand the entire codebase before contributing.
NativeRelay particularly welcomes contributors familiar with:
- Linux kernel interfaces
- eBPF
fanotify- Windows ETW
- Windows internals
- macOS Endpoint Security
- Rust systems programming
- security telemetry
- observability infrastructure
If you understand one of these areas deeply, your platform knowledge may be more valuable than a large code contribution.
Use GitHub Discussions for questions, architectural proposals, platform research, and ideas that would benefit from community input.
Issues should generally be used for concrete bugs and actionable implementation work.
By contributing to NativeRelay, you agree that your contributions will be licensed under the project's MIT License.