A lightweight yet comprehensive Endpoint Detection and Response (EDR) solution for Linux systems that monitors command execution, analyzes system behavior, and provides actionable security insights with minimal performance impact.
Linux EDR captures process execution data through Linux's kernel tracing capabilities and builds a multi-tiered reporting structure that allows for both real-time threat detection and long-term security trend analysis. By focusing on command execution patterns, it provides valuable security insights without the overhead of traditional EDR solutions.
- Efficient Monitoring: Non-blocking trace reader for
/sys/kernel/tracing/trace_pipewith automatic recovery - Scalable Architecture: Thread-safe event buffer with configurable capacity and age limits
- Smart Data Organization: Process-focused event collection and intelligent command grouping
- Hierarchical Reporting: Tiered reports from 15-minute snapshots to monthly trend analysis
- AI-Enhanced Security: OpenAI integration with gpt-4o-mini for automated threat detection
- Flexible Output: Configurable reporting to JSON files or console
- Production-Ready: Comprehensive error handling with graceful recovery from failures
- Privacy-Focused: Collects only necessary command execution data (see Privacy Policy)
uv pip install git+https://github.com/ParttimeWorks/linux_edr.git@master# Basic monitoring with default settings (requires root)
sudo uv run python -m linux_edr.cli run
# Run in debug mode to see detailed event logs
sudo uv run python -m linux_edr.cli run --debug
# Custom interval and output file
sudo uv run python -m linux_edr.cli run --interval 5 --output events.jsonl
# Using a specific configuration file
sudo uv run python -m linux_edr.cli run --config /etc/linux_edr/custom.ini
# Show current configuration
sudo uv run python -m linux_edr.cli show-configWhen run in standard mode, the tool will:
- Enable syscall tracing for configured events (execve, fork, clone, connect by default)
- Initialize the scheduler with the configured interval
- Start monitoring in the background
- Display minimal output
In debug mode, the tool will:
- Provide more detailed output during initialization
- Show each raw event as it's captured
- Display more information about scheduler operations
This is useful for troubleshooting or understanding what data is being collected.
Linux EDR captures various syscall events and represents them using structured Pydantic models. Here's an example of an ExecveEvent within a report:
{
"report_id": "2023-01-01T12:00:00+00:00",
"window_start": "2023-01-01T11:45:00+00:00",
"window_end": "2023-01-01T12:00:00+00:00",
"total": 150,
"command_counts": {"ls": 50, "cat": 30, "bash": 70},
"events": [
{
"timestamp": "12345.67890",
"pid": 1001,
"command": "ls",
"args": ["-la", "/tmp"]
},
{
"timestamp": "12346.00000",
"pid": 1002,
"child_pid": 1003
},
{
"timestamp": "12347.11111",
"pid": 1004,
"fd": 3,
"address": "1.1.1.1:443"
}
]
}The previous grouping by process name (process_events) in Cell reports might change based on how these structured events are aggregated. The core reporting hierarchy remains.
Linux EDR can be configured using a config.ini file with the following options:
[DEFAULT]
# Path to the kernel trace_pipe
trace_path = /sys/kernel/tracing/trace_pipe
# Report generation interval in minutes
report_interval = 15
# LLM model to use
model = gpt-4o-mini
# Enable debug logging (true/false)
debug = false
[OPENAI]
# Your OpenAI API key (or leave empty to use environment variable)
api_key =
[REPORTS]
# Directory to store hierarchical reports
reports_dir = reports
[ADVANCED]
# Maximum number of events to store before generating an interim report
max_events_buffer = 10000
# Maximum number of summary lines to include in LLM prompt
max_summary_lines = 50
# Whether to include raw event data in reports (true/false)
include_raw_events = true
# Whether to include security findings in reports (true/false)
include_security_findings = true
# Whether to log verbose raw event data in debug mode (true/false)
verbose_debug_logging = true
# Whether to enable syscall tracing (true/false)
enable_syscall_tracing = true
# Comma-separated list of syscalls to trace (enter and exit events will be enabled)
syscalls_to_trace = execve,fork,clone,connectLinux EDR implements a sophisticated multi-tiered reporting system that provides security visibility across different time scales:
| Level | Coverage | Name | Description |
|---|---|---|---|
| 1 | 15 minutes | Cell | Base unit capturing immediate system activity |
| 2 | 16 Cells = 4 hours | Block | Short-term patterns across multiple Cells |
| 3 | 6 Blocks = 24 hours | DailyReport | Consolidated view of a full day's activity |
| 4 | 7 DailyReports | WeeklyReport | Week-long trends with daily breakdowns |
| 5 | ~4 WeeklyReports | MonthlyReport | Strategic view of monthly security posture |
This architecture enables:
- Immediate threat detection at the Cell level
- Context-rich pattern recognition at the Block level
- Daily security posture assessment in DailyReports
- Trend identification in WeeklyReports
- Strategic security planning with MonthlyReports
All reports are automatically stored in JSON format in the configured reports_dir with appropriate subdirectories for each level.
Linux EDR can be installed as a systemd service for automatic startup and management:
# Install as a systemd service (requires root)
sudo ./install_service.sh
# Start and enable the service
sudo systemctl enable linux-edr.service
sudo systemctl start linux-edr.service
# Check service status
sudo systemctl status linux-edr.service
# View logs
sudo journalctl -u linux-edr.service -fTo uninstall the service and remove all related files:
# Uninstall service and clean up (requires root)
sudo ./uninstall_service.shLinux EDR leverages OpenAI's gpt-4o-mini model to analyze process execution patterns and identify potential security threats. The analysis focuses on:
- Unusual command execution patterns and frequencies
- Potential privilege escalation attempts
- Command sequences indicating data exfiltration
- Anomalous network access patterns
- Suspicious file operations or permission changes
Analysis results are saved alongside JSON reports with the .analysis extension, providing actionable insights without requiring manual review of raw data.
Linux EDR is designed with privacy and performance in mind:
- Collects only process execution data, not file contents or user input
- Stores data locally by default with configurable retention
- Transmits data externally only when explicitly configured
- Uses non-blocking I/O and efficient buffering to minimize CPU usage
- Implements backpressure mechanisms to handle high-volume events
- See the full Privacy Policy for details
To ensure reliable operation in production environments, Linux EDR includes:
- Smart retry logic for trace pipe access with configurable backoff
- Graceful handling of permission errors with clear guidance
- Automatic reconnection if trace sources become unavailable
- Thread-safe operations with proper resource management
- Comprehensive logging with configurable verbosity
- Clean shutdown mechanisms that preserve data integrity
- Python 3.11 or later
- uv for dependency management
- Linux kernel with ftrace support
- Appropriate permissions to read from trace_pipe (typically requires root)
linux-edr/
├── linux_edr/
│ ├── __init__.py
│ ├── cli.py # Typer-based CLI interface
│ ├── app.py # Core application logic
│ ├── config.py # Configuration management
│ ├── trace.py # Non-blocking trace reader & parser
│ ├── aggregator.py # Thread-safe event buffering
│ ├── reporter.py # OpenAI integration and output
│ ├── report_manager.py # Hierarchical report handling
│ ├── domain/
│ │ └── models/
│ │ └── events/ # Pydantic models for syscall events
│ │ ├── base.py
│ │ ├── execve.py
│ │ ├── fork.py
│ │ └── ... # other event types
│ └── models.py # Pydantic data models
├── tests/ # Comprehensive test suite
├── docs/ # Documentation
├── linux-edr.service # Systemd service definition
├── pyproject.toml # Project metadata
├── PRIVACY.md # Privacy policy
└── README.md # This file
git clone https://github.com/ParttimeWorks/linux_edr.git
cd linux-edr
uv pip install -e .[dev]pytestmypy linux_edrMIT