How alexforman1/forensicscanner works
Project Type and Purpose
• ForensicScanner is a Python-based desktop application (CLI + GUI) for offline forensic log analysis.
• It processes various log formats, applies pattern-based detection, and augments results with local LLM inference.
File Structure
• Top-level entry points:
• main.py – CLI launcher
• gui.py – GUI launcher
• Core modules (duplicated in src/ and root):
• log_parser.py – pattern matching engine
• ai_analyzer.py – local LLM integration
• searcher.py – search/filter logic
• summarize.py – report/summarization
• config/ – baseline rules, network rules
• models/ – directory for GGUF LLM files
• logs/ – runtime logs and test samples
• src/utils/ – shared helper functions (memory management, I/O)
• settings.json – user defaults
• requirements.txt – Python dependencies
Main Components and Responsibilities
A. User Interfaces
– CLI Interface (main.py)
– Tkinter GUI (gui.py + src/gui/)
B. Core Engines (backend)
– Log Parser: reads file → tokenizes → pattern matching → severity scoring
– AI Analyzer: loads local GGUF model → context-aware analysis → recommendations
– Searcher: filters findings (severity, category, time window)
– Summarizer: aggregates and formats final report
C. Configuration Layer
– settings.json, baseline.yaml, network_rules.json → parameterize parsing & scoring
D. Model Storage
– models/ directory hosting .gguf files (Mistral, Llama)
E. Logging & Persistence
– logs/ directory for audit trail, debugging
F. Utilities
– src/utils for resource monitoring (psutil), chunked file I/O, common helpers
Component Interactions and Data Flow
1. User invokes CLI or GUI →
2. CLI/GUI launcher loads settings.json and config files →
3. File input passed to Log Parser →
4. Parser emits structured events/findings →
5. Findings flow into AI Analyzer (optional) →
6. Combined results fed to Searcher & Summarizer →
7. Output displayed (GUI panel or terminal via rich) and/or saved to disk →
8. Every step logs to logs/*.log for audit
Architectural Patterns and Principles
• Modular Pipeline: discrete stages (parsing → AI → filtering → summarization)
• Plug-in Style: AI models are drop-in (.gguf), rules configurable via YAML/JSON
• Separation of Concerns: UI vs. core logic vs. configuration vs. persistence
• Resource Efficiency: chunked processing, multi-threading, memory threshold monitoring
Relevant Technologies & Libraries
• Python 3.8+
• llama-cpp-python for local GGUF inference
• Tkinter (tkinterdnd2) for GUI + drag-and-drop
• rich for CLI output formatting
• psutil for system resource monitoring
• pandas (optional) for data manipulation in summarization
Final Advice
• Be exhaustive: capture all core modules and data flows.
• Fallback paths: e.g., AI Analyzer is optional if no model present.
• Resource-monitoring loop around heavy stages (parser, AI).
• Thread usage and chunked processing for performance clarity.