Adding ebpf capability now
This commit is contained in:
Harshavardhan Musanalli
233
EBPF_README.md
Normal file
233
EBPF_README.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# eBPF Integration for Linux Diagnostic Agent
|
||||
|
||||
The Linux Diagnostic Agent now includes comprehensive eBPF (Extended Berkeley Packet Filter) capabilities for advanced system monitoring and investigation during diagnostic sessions.
|
||||
|
||||
## eBPF Capabilities
|
||||
|
||||
### Available Monitoring Types
|
||||
|
||||
1. **System Call Tracing** (`syscall_trace`)
|
||||
- Monitors all system calls made by processes
|
||||
- Useful for debugging process behavior and API usage
|
||||
- Can filter by process ID or name
|
||||
|
||||
2. **Network Activity Tracing** (`network_trace`)
|
||||
- Tracks TCP/UDP send/receive operations
|
||||
- Monitors network connections and data flow
|
||||
- Identifies network-related bottlenecks
|
||||
|
||||
3. **Process Monitoring** (`process_trace`)
|
||||
- Tracks process creation, execution, and termination
|
||||
- Monitors process lifecycle events
|
||||
- Useful for debugging startup issues
|
||||
|
||||
4. **File System Monitoring** (`file_trace`)
|
||||
- Monitors file open, create, delete operations
|
||||
- Tracks file access patterns
|
||||
- Can filter by specific paths
|
||||
|
||||
5. **Performance Monitoring** (`performance`)
|
||||
- Collects CPU, memory, and I/O metrics
|
||||
- Provides detailed performance profiling
|
||||
- Uses perf integration when available
|
||||
|
||||
6. **Security Event Monitoring** (`security_event`)
|
||||
- Detects privilege escalation attempts
|
||||
- Monitors security-relevant system calls
|
||||
- Tracks suspicious activities
|
||||
|
||||
## How eBPF Integration Works
|
||||
|
||||
### AI-Driven eBPF Selection
|
||||
|
||||
The AI agent can automatically request eBPF monitoring by including specific fields in its diagnostic response:
|
||||
|
||||
```json
|
||||
{
|
||||
"response_type": "diagnostic",
|
||||
"reasoning": "Need to trace network activity to diagnose connection timeout issues",
|
||||
"commands": [
|
||||
{"id": "basic_net", "command": "ss -tulpn", "description": "Current network connections"},
|
||||
{"id": "net_config", "command": "ip route show", "description": "Network configuration"}
|
||||
],
|
||||
"ebpf_capabilities": ["network_trace", "syscall_trace"],
|
||||
"ebpf_duration_seconds": 15,
|
||||
"ebpf_filters": {
|
||||
"comm": "nginx",
|
||||
"path": "/etc"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### eBPF Trace Execution
|
||||
|
||||
1. eBPF traces run in parallel with regular diagnostic commands
|
||||
2. Multiple eBPF capabilities can be activated simultaneously
|
||||
3. Traces collect structured JSON events in real-time
|
||||
4. Results are automatically parsed and included in the diagnostic data
|
||||
|
||||
### Event Data Structure
|
||||
|
||||
eBPF events follow a consistent structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"timestamp": 1634567890000000000,
|
||||
"event_type": "syscall_enter",
|
||||
"process_id": 1234,
|
||||
"process_name": "nginx",
|
||||
"user_id": 1000,
|
||||
"data": {
|
||||
"syscall": "openat",
|
||||
"filename": "/etc/nginx/nginx.conf"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Installation and Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
The agent automatically detects available eBPF tools and capabilities. For full functionality, install:
|
||||
|
||||
**Ubuntu/Debian:**
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install bpftrace linux-tools-generic linux-tools-$(uname -r)
|
||||
sudo apt install bcc-tools python3-bcc # Optional, for additional tools
|
||||
```
|
||||
|
||||
**RHEL/CentOS/Fedora:**
|
||||
```bash
|
||||
sudo dnf install bpftrace perf bcc-tools python3-bcc
|
||||
```
|
||||
|
||||
**openSUSE:**
|
||||
```bash
|
||||
sudo zypper install bpftrace perf
|
||||
```
|
||||
|
||||
### Automated Setup
|
||||
|
||||
Use the included helper script:
|
||||
|
||||
```bash
|
||||
# Check current eBPF capabilities
|
||||
./ebpf_helper.sh check
|
||||
|
||||
# Install eBPF tools (requires root)
|
||||
sudo ./ebpf_helper.sh install
|
||||
|
||||
# Create monitoring scripts
|
||||
./ebpf_helper.sh setup
|
||||
|
||||
# Test eBPF functionality
|
||||
sudo ./ebpf_helper.sh test
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Network Issue Diagnosis
|
||||
|
||||
When describing network problems, the AI may automatically request network tracing:
|
||||
|
||||
```
|
||||
User: "Web server is experiencing intermittent connection timeouts"
|
||||
|
||||
AI Response: Includes network_trace and syscall_trace capabilities
|
||||
eBPF Output: Real-time network send/receive events, connection attempts, and related system calls
|
||||
```
|
||||
|
||||
### Performance Issue Investigation
|
||||
|
||||
For performance problems, the AI can request comprehensive monitoring:
|
||||
|
||||
```
|
||||
User: "System is running slowly, high CPU usage"
|
||||
|
||||
AI Response: Includes process_trace, performance, and syscall_trace
|
||||
eBPF Output: Process execution patterns, performance metrics, and system call analysis
|
||||
```
|
||||
|
||||
### Security Incident Analysis
|
||||
|
||||
For security concerns, specialized monitoring is available:
|
||||
|
||||
```
|
||||
User: "Suspicious activity detected, possible privilege escalation"
|
||||
|
||||
AI Response: Includes security_event, process_trace, and file_trace
|
||||
eBPF Output: Security-relevant events, process behavior, and file access patterns
|
||||
```
|
||||
|
||||
## Filtering Options
|
||||
|
||||
eBPF traces can be filtered for focused monitoring:
|
||||
|
||||
- **Process ID**: `{"pid": "1234"}` - Monitor specific process
|
||||
- **Process Name**: `{"comm": "nginx"}` - Monitor processes by name
|
||||
- **File Path**: `{"path": "/etc"}` - Monitor specific path (file tracing)
|
||||
|
||||
## Integration with Existing Workflow
|
||||
|
||||
eBPF monitoring integrates seamlessly with the existing diagnostic workflow:
|
||||
|
||||
1. **Automatic Detection**: Agent detects available eBPF capabilities at startup
|
||||
2. **AI Decision Making**: AI decides when eBPF monitoring would be helpful
|
||||
3. **Parallel Execution**: eBPF traces run alongside regular diagnostic commands
|
||||
4. **Structured Results**: eBPF data is included in command results for AI analysis
|
||||
5. **Contextual Analysis**: AI correlates eBPF events with other diagnostic data
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Permission Errors:**
|
||||
- Most eBPF operations require root privileges
|
||||
- Run the agent with `sudo` for full eBPF functionality
|
||||
|
||||
**Tool Not Available:**
|
||||
- Use `./ebpf_helper.sh check` to verify available tools
|
||||
- Install missing tools with `./ebpf_helper.sh install`
|
||||
|
||||
**Kernel Compatibility:**
|
||||
- eBPF requires Linux kernel 4.4+ (5.0+ recommended)
|
||||
- Some features may require newer kernel versions
|
||||
|
||||
**Debugging eBPF Issues:**
|
||||
```bash
|
||||
# Check kernel eBPF support
|
||||
sudo ./ebpf_helper.sh check
|
||||
|
||||
# Test basic eBPF functionality
|
||||
sudo bpftrace -e 'BEGIN { print("eBPF works!"); exit(); }'
|
||||
|
||||
# Verify debugfs mount (required for ftrace)
|
||||
sudo mount -t debugfs none /sys/kernel/debug
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- eBPF monitoring provides deep system visibility
|
||||
- Traces may contain sensitive information (file paths, process arguments)
|
||||
- Traces are stored temporarily in `/tmp/nannyagent/ebpf/`
|
||||
- Old traces are automatically cleaned up after 1 hour
|
||||
- Consider the security implications of detailed system monitoring
|
||||
|
||||
## Performance Impact
|
||||
|
||||
- eBPF monitoring has minimal performance overhead
|
||||
- Traces are time-limited (typically 10-30 seconds)
|
||||
- Event collection is optimized for efficiency
|
||||
- Heavy tracing may impact system performance on resource-constrained systems
|
||||
|
||||
## Contributing
|
||||
|
||||
To add new eBPF capabilities:
|
||||
|
||||
1. Extend the `EBPFCapability` enum in `ebpf_manager.go`
|
||||
2. Add detection logic in `detectCapabilities()`
|
||||
3. Implement trace command generation in `buildXXXTraceCommand()`
|
||||
4. Update capability descriptions in `FormatSystemInfoWithEBPFForPrompt()`
|
||||
|
||||
The eBPF integration is designed to be extensible and can accommodate additional monitoring capabilities as needed.
|
||||
Reference in New Issue
Block a user