How teler-sh/teler works
Project Type & Purpose
• teler IDS is a real‐time intrusion detection system focused on analyzing web logs and alerting on potential security threats.
• It is designed as a CLI tool (with a terminal interface) that provides real-time alerting, monitoring, and logging capabilities. It can also be integrated with dashboards and external alerting services (Slack, Mattermost, Telegram, Discord).
• The README confirms its role as a threat analyzer, and it shows that even though version 3 is in the roadmap (with eBPF and teler-waf integration), the current version (v2) is primarily CLI based with support for incremental log processing.
Analyzing the File Structure – Key Components
• Top-Level Indicators: The presence of directories such as “internal”, “pkg”, and “common” shows modular design by functionality.
• Main entry point: main.go – this is the starting point for the application.
• Core Modules (inside the “internal” directory):
– internal/alert: Contains different alerting implementations (e.g., Slack, Discord, Mattermost, Telegram) plus templating and utilities.
– internal/event: Handles event processing; includes both event logic and a “www” subdirectory that seems to serve a dashboard (HTML/JS/CSS) for visualization.
– internal/runner: Manages the core logic for real-time log scanning, connection handling, endpoint management, logs collection, metrics, caching, options handling, and versioning.
• Packages (inside “pkg”):
– pkg/cache, pkg/errors, pkg/logs, pkg/matchers, pkg/metrics, pkg/parsers, pkg/requests, pkg/teler, and pkg/utils: These provide the low-level functionalities utilized by the core modules. They support error handling, matching patterns within logs, configuring parsers, collecting metrics (Prometheus integration), and external HTTP requests.
• Configuration & Resources:
– Files like teler.example.yaml and various configuration examples (e.g., fail2ban configuration) indicate that the system is highly configurable.
– There’s also a “resource” directory containing configuration code.
• Support for Deployment & CI/CD:
– Dockerfile, Makefile, GitHub workflows, and other scripts show that the project maintains structured deployment and CI/CD practices.
a. Main Application (main.go)
– Acts as the orchestrator kicking off all other modules.
b. Runner Module (internal/runner)
– This is the core processing engine: receiving log inputs, validating and parsing them, maintaining connection endpoints, caching, and handling metrics.
c. Alerting Module (internal/alert)
– Works in response to threat detection from the Runner.
– Display branches or sub-components for different alert channel integrations (Slack, Discord, Telegram, Mattermost).
– Indicate bi-directional interactions with the Runner (e.g., sending alerts and receiving configuration parameters).
d. Event Processing Module (internal/event)
– Captures and processes web events; has a static web dashboard as shown in the “internal/event/www” subdirectory.
– Its output can be considered the monitoring visual interface.
e. Utility and Support Libraries (pkg)
– These form the backbone for configuration parsing, error handling, metrics collection (Prometheus) and caching.
– Group these into a “Support Services” or “Infrastructure” block.
f. External Dependencies:
– External monitoring systems like Prometheus (via pkg/metrics) and Zinc logs (via pkg/logs) should also be shown.
– Optionally, include integration options with teler-waf and other security components as noted in the README.
g. Configuration & Resource Loader:
– The project’s configuration (examples like teler.example.yaml) should be shown as an input feeding into multiple modules (runner, alert, etc.).
Architectural Design Patterns & Principles
• Modular Design: Separate concerns are split logically (alerting, event processing, log parsing) across different directories.
• Config-Driven Behavior: Use of YAML example and config files denote a high level of customization.
• Real-Time Processing: Emphasis on incremental log processing and immediate alerting.
• Layered Architecture: Higher-level orchestration in main.go, core logic in runner, and support libraries below.
• Integration Points: Clear external interfaces for alerting and monitoring.
• Main blocks: Core System (main.go & Runner), Alerting System, Event Processing/Dashboard, Utility/Support Services.
Happy diagramming!