How to Set Up SSH Key-Based Authentication for Remote Log Access in LogSentinelAI

To enable SSH key-based authentication in LogSentinelAI, generate an SSH key pair, configure the environment variables in your .env file, and set REMOTE_LOG_MODE=ssh to allow the RemoteSSHLogMonitor class to securely pull logs from remote servers.

LogSentinelAI supports reading log files from remote machines via SSH connections, enabling centralized monitoring without requiring local file system access. This guide explains how to configure SSH key-based authentication using the environment-based configuration system and core classes in the call518/logsentinelai repository.

Understanding the SSH Architecture

LogSentinelAI implements remote log access through three integrated components defined in the source code.

DEFAULT_REMOTE_SSH_CONFIG — Defined in src/logsentinelai/core/config.py, this dictionary loads SSH connection parameters from environment variables, including host, port, user, key path, optional password, and timeout values.

RemoteSSHLogMonitor — Located in src/logsentinelai/core/ssh.py, this low-level class wraps the Paramiko library to manage SSH sessions. It provides methods for connection validation, file metadata retrieval, and byte-accurate log reading.

RealtimeLogMonitor — Found in src/logsentinelai/core/monitoring.py, this class acts as the public entry point for real-time analysis. When REMOTE_LOG_MODE is set to "ssh", it instantiates RemoteSSHLogMonitor to handle remote log ingestion, rotation detection, and chunking.

Step-by-Step Configuration

Generate an SSH Key Pair

If you do not already have an SSH key pair for LogSentinelAI, generate one using the Ed25519 algorithm for enhanced security:

ssh-keygen -t ed25519 -f ~/.ssh/logsentinelai_key -N ""

Add the public key (logsentinelai_key.pub) to the remote server's ~/.ssh/authorized_keys file to enable key-based authentication.

Configure Environment Variables

Copy the environment template and populate the SSH-specific variables:

cp .env.template .env

Edit .env to include these required settings:

REMOTE_LOG_MODE=ssh
REMOTE_SSH_HOST=your.remote.host
REMOTE_SSH_PORT=22
REMOTE_SSH_USER=your_user
REMOTE_SSH_KEY_PATH=~/.ssh/logsentinelai_key

# Optional: REMOTE_SSH_PASSWORD=your_password

# Optional: REMOTE_SSH_TIMEOUT=10

The DEFAULT_REMOTE_SSH_CONFIG dictionary in src/logsentinelai/core/config.py automatically imports these values at runtime.

Verify the SSH Connection

Test the connection before running full analysis. The RemoteSSHLogMonitor.test_connection() method executes a harmless echo command on the remote host to validate authentication:

from logsentinelai.core.ssh import RemoteSSHLogMonitor
from logsentinelai.core.config import DEFAULT_REMOTE_SSH_CONFIG

ssh_cfg = DEFAULT_REMOTE_SSH_CONFIG
monitor = RemoteSSHLogMonitor(ssh_cfg, "/var/log/syslog")

assert monitor.test_connection(), "SSH connection failed"

Alternatively, the CLI performs this verification automatically during initialization when RealtimeLogMonitor._initialize_ssh_monitor is invoked.

Run Remote Log Analysis

Execute LogSentinelAI with the SSH configuration active:

logsentinelai linux-system \
    --log-path /var/log/syslog \
    --mode realtime

Because REMOTE_LOG_MODE=ssh is set, the RealtimeLogMonitor class (as implemented in src/logsentinelai/core/monitoring.py) creates a RemoteSSHLogMonitor instance and begins streaming new log lines from the remote file.

Programmatic Access with RemoteSSHLogMonitor

For custom implementations, instantiate the SSH monitor directly to handle remote log access:

from logsentinelai.core.ssh import RemoteSSHLogMonitor
from logsentinelai.core.config import DEFAULT_REMOTE_SSH_CONFIG

# Initialize the monitor with configuration and remote path

monitor = RemoteSSHLogMonitor(
    DEFAULT_REMOTE_SSH_CONFIG,
    remote_log_path="/var/log/auth.log"
)

# Retrieve file metadata for rotation detection

size = monitor.get_file_size()
inode = monitor.get_file_inode()

# Read new content from a specific byte offset

new_lines = monitor.read_from_position(size)
for line in new_lines:
    process(line)

The RemoteSSHLogMonitor abstracts all SSH session management, requiring only the configuration dictionary and absolute remote file path.

Summary

• SSH key-based authentication relies on three core components: DEFAULT_REMOTE_SSH_CONFIG for settings management, RemoteSSHLogMonitor for connection handling, and RealtimeLogMonitor for orchestration.
• Configuration occurs through environment variables in .env, with REMOTE_SSH_KEY_PATH specifying the private key location and REMOTE_LOG_MODE=ssh enabling remote mode.
• The RemoteSSHLogMonitor class in src/logsentinelai/core/ssh.py exposes test_connection(), get_file_size(), get_file_inode(), and read_from_position() for robust remote file operations.
• LogSentinelAI uses the Paramiko library to establish secure SSH sessions and perform byte-accurate log reading from remote servers.

Frequently Asked Questions

What SSH library does LogSentinelAI use?

LogSentinelAI uses Paramiko as its underlying SSH client library. The RemoteSSHLogMonitor class in src/logsentinelai/core/ssh.py wraps Paramiko to manage connection establishment, authentication, and file operations on remote hosts.

Can I use password authentication instead of SSH keys?

Yes. While SSH key-based authentication is recommended for security, you can configure password authentication by setting the REMOTE_SSH_PASSWORD variable in your .env file. The RemoteSSHLogMonitor validates the configuration and attempts authentication using available credentials, though key-based auth takes precedence in typical Paramiko workflows.

How does LogSentinelAI handle log rotation on remote servers?

The RemoteSSHLogMonitor tracks file metadata using get_file_size() and get_file_inode() methods to detect changes in the underlying file. When RealtimeLogMonitor detects that the inode has changed or the file size has decreased (indicating rotation), it reinitializes the file handle and begins reading from the new file instance.

Where are SSH connection settings defined?

SSH connection settings are defined in the .env file based on the template provided in .env.template. These values populate the DEFAULT_REMOTE_SSH_CONFIG dictionary in src/logsentinelai/core/config.py, which serves as the single source of truth for host, port, username, key path, and timeout configurations across the application.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}