logwatch-analyzer 0.1.1

A CLI tool to analyze journalctl logs with specific parsers and LLM integration.

LogWatch Analyzer

LogWatch Analyzer is a command-line tool to analyze system logs from journalctl on Linux systems. It uses a YAML configuration file to define specific analysis tasks and can leverage a Large Language Model (LLM) via Ollama, Gemini, or other providers for in-depth analysis and report generation.

Features

• Configurable Analysis: Define which logs to analyze directly in the config.yaml file.
• Specific Parsers: Includes optimized parsers for common events like failed SSH logins and kernel errors.
• LLM Integration: Utilizes a Large Language Model for generic analysis and generating human-readable reports.
• Flexible Output: Displays results in formatted tables in the terminal or generates reports in Markdown format.
• Simple CLI Interface: Easy to use with arguments to list tasks, run specific ones, and set time windows.

Installation

You can install LogWatch Analyzer from PyPI:

pip install logwatch-analyzer

Configuration

To use LogWatch Analyzer, you need a config.yaml file. The script looks for this file in the following locations, in order of priority:

1. ~/.config/logwatch/config.yaml (Recommended for users)
2. config.yaml in the current directory where you run the command.

Create the file in one of these locations. The recommended approach is to create a user-specific configuration:

mkdir -p ~/.config/logwatch
touch ~/.config/logwatch/config.yaml

Then, paste the following content into your config.yaml file and customize it to your needs.

# File di configurazione per LogWatch

# Sezione per la configurazione dei provider LLM
llm_providers:
  ollama:
    type: "ollama"
    api_url: "http://localhost:11434/api/generate"
    model: "gemma3:12b"

  gemma:
    type: "gemma"
    # L'URL per Gemmma-3-27b-it. Cambialo se vuoi usare un altro modello.
    api_url: "https://generativelanguage.googleapis.com/v1beta/models/gemma-3-27b-it:generateContent"
    # La chiave API verrà letta dalla variabile d'ambiente specificata qui.
    api_key_env: "GEMINI_API_KEY"

  gemini:
    type: "gemini"
    # L'URL per Gemini 1.5 Flash. Cambialo se vuoi usare un altro modello.
    api_url: "https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent"
    # La chiave API verrà letta dalla variabile d'ambiente specificata qui.
    api_key_env: "GEMINI_API_KEY"

  openrouter:
    type: "openrouter"
    api_url: "https://openrouter.ai/api/v1/"
    # Puoi cambiare il modello qui. Esempi: "google/gemma-2-9b-it", "anthropic/claude-3-haiku"
    model: "qwen/qwen-2.5-coder-32b-instruct:free"
    #model: "deepseek/deepseek-chat-v3-0324:free"
    #model: "openai/gpt-oss-20b:free"
    api_key_env: "OPENROUTER_API_KEY"

# Scegli quale provider LLM usare tra quelli definiti sopra.
active_llm_provider: "gemini"


# Definizione dei task di analisi dei log
logs:
  - name: "SSH Failed Logins"
    command: "journalctl -u sshd -p err -o json --no-pager --since '1 day ago'"
    parser: "ssh_parser"
    # Filtri per ignorare log irrilevanti (esempi)
    filters:
      - "pam_unix(sshd:auth): authentication failure" # Spesso ridondante se si guarda solo "Failed password"

  - name: "Sudo Usage"
    command: "journalctl /usr/bin/sudo -o json --no-pager --since '1 day ago'"
    parser: "llm_parser"
    filters:
      - "pam_unix(sudo:session): session opened for user root"
      - "pam_unix(sudo:session): session closed for user root"

  - name: "Kernel Errors"
    command: "journalctl -k -p err -o json --no-pager --since '1 day ago'"
    parser: "kernel_parser"
    filters: []

  - name: "General System Analysis"
    command: "journalctl -p err -o json --no-pager --since '1 hour ago'"
    parser: "llm_parser"
    filters: []

Usage

The tool is available as the logwatch command.

List all available tasks

To see a list of all tasks defined in your config.yaml:

logwatch --list

Run a specific task

To execute a single analysis task:

logwatch --task "SSH Failed Logins"

Run all tasks

To run all tasks in sequence:

logwatch

Generate a Report File

For tasks that use the llm_parser, you can save the generated report to a Markdown file:

logwatch --task "Sudo Usage" --output report_sudo.md

Override the Time Window

You can specify a different time range from the one in the configuration file on the fly:

logwatch --task "Kernel Errors" --since "2 hours ago"

License

This project is licensed under the MIT License. See the LICENSE file for details.