docs: enhance usage documentation with debug mode and configuration details

Adds documentation for standard and debug run modes, expands configuration options to include syscall tracing settings, and improves usage examples with clearer explanations of operation modes.

Author: scc-tw

README.md

@@ -35,9 +35,12 @@ uv pip install git+https://github.com/ParttimeWorks/linux_edr.git@v1.0.0
 ## Usage
 
 ```bash
-# Basic monitoring with default settings
+# 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
 
@@ -48,6 +51,23 @@ sudo uv run python -m linux_edr.cli run --config /etc/linux_edr/custom.ini
 sudo uv run python -m linux_edr.cli show-config
 ```
 
+### Standard Run Mode
+
+When run in standard mode, the tool will:
+1. Enable syscall tracing for configured events (execve, fork, clone, connect by default)
+2. Initialize the scheduler with the configured interval
+3. Start monitoring in the background
+4. Display minimal output
+
+### Debug Run Mode
+
+In debug mode, the tool will:
+1. Provide more detailed output during initialization
+2. Show each raw event as it's captured
+3. Display more information about scheduler operations
+
+This is useful for troubleshooting or understanding what data is being collected.
+
 ## Data Structure
 
 Linux EDR groups execve events by process name and maintains the full command line for context:
@@ -85,9 +105,6 @@ model = gpt-4o-mini
 # Enable debug logging (true/false)
 debug = false
 
-# Path to save JSON reports (empty for no file output)
-output_file = 
-
 [OPENAI]
 # Your OpenAI API key (or leave empty to use environment variable)
 api_key = 
@@ -105,6 +122,18 @@ 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,connect
 ```
 
 ## Hierarchical Reporting Architecture

docs/usage.md

@@ -8,13 +8,101 @@ The Linux EDR tool can be run directly using the Python module.
 # 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 5-minute reporting interval and save reports to a file
 sudo uv run python -m linux_edr.cli run --interval 5 --output /var/log/linux-edr-events.jsonl
 
 # Use a specific configuration file
 sudo uv run python -m linux_edr.cli run --config /etc/linux_edr/my_config.ini
 ```
 
+### Standard Run Mode
+
+When run in standard mode, the tool will:
+1. Enable syscall tracing for configured events (execve, fork, clone, connect by default)
+2. Initialize the scheduler with the configured interval
+3. Start monitoring in the background
+4. Display minimal output
+
+Example output:
+```
+Enabling ftrace event: /sys/kernel/tracing/events/syscalls/sys_enter_execve/enable
+Enabling ftrace event: /sys/kernel/tracing/events/syscalls/sys_exit_execve/enable
+Enabling ftrace event: /sys/kernel/tracing/events/syscalls/sys_enter_fork/enable
+Enabling ftrace event: /sys/kernel/tracing/events/syscalls/sys_exit_fork/enable
+Enabling ftrace event: /sys/kernel/tracing/events/syscalls/sys_enter_clone/enable
+Enabling ftrace event: /sys/kernel/tracing/events/syscalls/sys_exit_clone/enable
+Enabling ftrace event: /sys/kernel/tracing/events/syscalls/sys_enter_connect/enable
+Enabling ftrace event: /sys/kernel/tracing/events/syscalls/sys_exit_connect/enable
+Successfully enabled 8 syscall trace events
+Adding job tentatively -- it will be properly scheduled when the scheduler starts
+Linux EDR initialized with interval=15m
+Added job "LinuxEDRApp._summarize" to job store "default"
+Scheduler started
+```
+
+### Debug Run Mode
+
+In debug mode, the tool will:
+1. Provide more detailed output during initialization
+2. Show each raw event as it's captured
+3. Display more information about scheduler operations
+
+This is useful for troubleshooting or understanding what data is being collected.
+
+## Configuration File
+
+Linux EDR uses a `config.ini` file with the following sections and options:
+
+```ini
+[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,connect
+```
+
+You can customize this file and specify its location using the `--config` parameter when running the tool.
+
 ## Viewing Configuration
 
 To see the effective configuration (after loading defaults, file settings, and command-line overrides):