Building a Real-Time HTTP Intrusion Detection System with teler

Hook

Most web application firewalls cost thousands per year and require complex configurations. teler is a single Go binary that analyzes your nginx logs and detects CVE exploits, suspicious patterns, and known attack vectors using continuously-updated threat intelligence—completely free.

Context

Web servers generate mountains of access logs, but parsing them for security threats typically requires expensive SIEM platforms or security analysts manually grepping through files. Traditional tools like Fail2ban focus on brute-force detection, while enterprise WAFs like ModSecurity require deep integration with your web server and complex rule management. The gap between "no security monitoring" and "enterprise SIEM" leaves many development teams vulnerable.

teler emerged to fill this void: a lightweight, standalone intrusion detection system purpose-built for HTTP threats. Rather than trying to be a comprehensive security platform, it does one thing exceptionally well—it reads web server logs in real-time, applies community-maintained threat intelligence, and alerts you when something malicious appears. It's the kind of tool you can deploy in an afternoon and immediately start catching exploitation attempts you didn't know were happening.

Technical Insight

At its core, teler is a streaming log processor with a plugin-based threat detection engine. It supports multiple log formats out of the box (Common Log Format, combined, JSON) and allows custom format definitions using Go templates. The architecture is remarkably straightforward: logs flow in, detection rules apply pattern matching and threat intelligence lookups, and matches trigger configured outputs.

Here's a minimal configuration that monitors nginx logs for common vulnerabilities:

logfile: /var/log/nginx/access.log
log_format: '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"'

rules:
  - threat:cve
  - threat:bad-crawler
  - threat:directory-bruteforce

notifications:
  - provider: slack
    webhook_url: https://hooks.slack.com/services/YOUR/WEBHOOK/URL

This configuration immediately starts monitoring for CVE exploitation attempts, malicious crawlers, and directory traversal attacks. The real power comes from teler's threat intelligence sources—it automatically fetches and updates detection rules from the teler-resources repository, which includes patterns for thousands of known threats categorized by type.

The detection engine supports several threat categories that map to real attack patterns. The common-web-attack ruleset catches SQLi, XSS, and command injection attempts. The cve ruleset identifies exploitation of specific vulnerabilities like Log4Shell or Spring4Shell. The bad-ip-address category blocks requests from known malicious sources. Each rule category processes logs through different detection methods: regex pattern matching for attack signatures, IP reputation lookups for bad actors, and statistical analysis for directory bruteforce attempts.

For teams that need more control, teler supports custom rules through the DSL (Domain-Specific Language) format:

rules:
  - name: Detect Admin Panel Probing
    condition: or
    rules:
      - method: contains
        element: request
        pattern: /wp-admin
      - method: contains
        element: request
        pattern: /administrator
      - method: contains
        element: request  
        pattern: /phpmyadmin

This flexibility means you can augment community threat intelligence with organization-specific detection logic without forking the codebase.

The incremental processing mode deserves special attention because it solves a critical problem with log-based detection: how do you avoid reprocessing the same logs after restarts? teler maintains a .teler.cache file that tracks the last processed log position. When teler restarts, it resumes from where it left off rather than reanalyzing gigabytes of historical logs. This makes it viable for production environments where the monitoring process might restart due to deployments or system maintenance.

For observability, teler exposes Prometheus metrics that track detection counts by threat category:

teler_threats_detected{category="common_web_attack"} 42
teler_threats_detected{category="cve"} 3  
teler_threats_detected{category="bad_crawler"} 156

These metrics integrate seamlessly with existing monitoring stacks, allowing security teams to build dashboards that visualize attack patterns over time or create alerts when specific threat types spike.

The notification system supports multiple simultaneous channels, so you can send critical CVE detections to PagerDuty while logging everything else to a Slack channel. The alert payloads include full context—the offending request, matched threat category, timestamp, and source IP—giving responders immediate actionable information.

Gotcha

The elephant in the room: teler v2 is in maintenance mode while the team prepares a complete architectural rewrite for v3. The roadmap mentions migrating to eBPF-based detection and deeper integration with teler-waf, which sounds impressive but creates uncertainty. If you're building production infrastructure today, betting on a tool that's explicitly "on hold" requires careful consideration. The current version works well, but you won't see new features or potentially even bug fixes until v3 ships.

More fundamentally, log-based detection is inherently reactive. By the time teler sees an attack in your logs, the malicious request has already hit your application. If you have a zero-day vulnerability, teler might tell you that someone exploited it, but it won't prevent the exploitation. This is why the project also maintains teler-waf, which provides the same detection engine as Go middleware that can actively block requests. For comprehensive protection, you need both: teler-waf to prevent attacks and teler to analyze logs for threats that bypassed your application-level defenses. The log-based approach also means you're dependent on your web server's logging configuration—if nginx drops requests before logging them or if critical request details aren't logged, teler can't detect those attacks.

Verdict

Use if: You're running web applications without sophisticated security monitoring and need immediate visibility into attack patterns; you're comfortable with Go tooling and want something lighter than a full SIEM; you're doing incident response or threat hunting and need to retroactively analyze logs; you want community-maintained threat intelligence without vendor lock-in; you're building a security monitoring stack and need an HTTP-specific component that exports Prometheus metrics. Skip if: You need active attack prevention rather than detection (use teler-waf middleware instead); you require enterprise support and guaranteed maintenance (the v3 rewrite creates risk); you're analyzing extremely high-volume logs that would overwhelm single-process stream parsing; you need detection beyond HTTP/HTTPS traffic; you want a fully-featured SIEM with correlation, forensics, and compliance reporting—teler is purposefully narrow in scope.