NecroScope

NecroScope is a Python-based tool for ingesting Linux kernel logs, extracting structured error information, and producing human-readable or machine-readable analysis results.

The v1 design is CLI-first and intentionally modular. Log ingestion, analysis, and output formatting are strictly separated. LLM support is stubbed out and not used in v1. NecroScope does not require network access or an LLM to function.

What NecroScope does (v1)

• Load kernel logs from a file, .gz compressed logs, or standard input
• Normalize and parse log lines into structured events
• Extract global metadata such as kernel version and command lines
• Group kernel errors into error blocks (Oops, panic, WARN, BUG, etc.)
• Apply rule-based analysis to classify severity and provide diagnostic hints
• Emit results as plain text or structured JSON
• Optionally anonymize output for sharing

What NecroScope does not do (v1)

• Fetch logs or attachments from bug trackers
• Automatically unpack sosreport or apport archives
• Require an LLM, network access, or external services
• Provide a web UI or store logs
• Persist results or maintain historical analysis state

V1 limitations

These are current implementation limits in v1:

• Multi-boot detection is not supported - all events are assigned to boot 0
• Wall clock timestamp parsing is not implemented; only dmesg offsets are parsed
• Hostname extraction is not implemented
• Compressed log support is limited to .gz
• LLM support and the web API are stubs and not used by the CLI

Installation

Developer installation (recommended)

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e ".[dev]"

Editable install without dev extras

pip install -e .

Usage

Analyze a kernel log file:

necro-scope analyze /path/to/dmesg.txt

Run from source without installing:

python -m necro_scope.cli analyze tests/data/dmesg_warn_cut_here_excerpt.log

Analyze logs from standard input:

dmesg | necro-scope analyze -

Emit JSON output:

necro-scope analyze /path/to/dmesg.txt --json

Run with LLM usage disabled (reserved flag, LLM not used in v1):

necro-scope analyze /path/to/dmesg.txt --no-llm

For the full list of options, see:

necro-scope analyze --help

Project layout

Core code lives under src/necro_scope/:

• ingestion/ - log loading, parsing, error block detection
• analysis/ - rule engine, severity scoring, stacktrace interpretation
• output/ - text and JSON formatters and schemas
• models/ - internal data model definitions
• providers/ - heuristic summarizer and interfaces
• llm/ - LLM stubs, not used in v1
• web/ - web API stubs, not enabled in v1

The authoritative v1 design is documented in ARCHITECTURE.md.

Privacy

Kernel logs may contain sensitive information such as hostnames, usernames, IP addresses, or serial numbers. Use --anonymize-output before sharing output publicly.

Development

Run the test suite:

pytest

The project uses a src/ layout. Tests are configured to run directly from a working tree without requiring an installed package.

License

NecroScope is licensed under the Apache License, Version 2.0. See LICENSE and NOTICE for details.