Configuration

teler requires a minimum of configuration to process and/or log analysis, and execute threats and/or alerts. See teler.example.yaml for an example.

Log Formats

Because we use gonx package to parse the log, you can write any log format. As an examples:

Apache

log_format: |
  $remote_addr - $remote_user [$time_local] "$request_method $request_uri $request_protocol" $status $body_bytes_sent "$http_referer" "$http_user_agent"

Nginx

log_format: |
  $remote_addr $remote_user - [$time_local] "$request_method $request_uri $request_protocol"
  $status $body_bytes_sent "$http_referer" "$http_user_agent"

Nginx Ingress

log_format: |
  $remote_addr - [$remote_addr] $remote_user - [$time_local]
  "$request_method $request_uri $request_protocol" $status $body_bytes_sent
  "$http_referer" "$http_user_agent" $request_length $request_time
  [$proxy_upstream_name] $upstream_addr $upstream_response_length $upstream_response_time $upstream_status $req_id

Amazon S3

log_format: |
  $bucket_owner $bucket [$time_local] $remote_addr $requester $req_id $operationration $key
  "$request_method $request_uri $request_protocol" $status $error_code $body_bytes_sent -
  $total_time - "$http_referer" "$http_user_agent" $version_id $host_id
  $signature_version $cipher_suite $http_auth_type $http_host_header $tls_version

Elastic LB

log_format: |
  $time_local $elb_name $remote_addr $upstream_addr $request_processing_time
  $upstream_processing_time $response_processing_time $status $upstream_status $body_received_bytes $body_bytes_sent
  "$request_method $request_uri $request_protocol" "$http_user_agent" $cipher_suite $tls_version

CloudFront

log_format: |
  $date $time $edge_location  $body_bytes_sent  $remote_addr
  $request_method $http_host_header $requst_uri $status
  $http_referer $http_user_agent  $request_query  $http_cookie  $edge_type  $req_id
  $http_host_header $ssl_protocol $body_bytes_sent  $response_processing_time $http_host_forwarded
  $tls_version  $cipher_suite $edge_result_type $request_protocol $fle_status $fle_encrypted_fields
  $http_port  $time_first_byte  $edge_detail_result_type
  $http_content_type  $request_length $request_length_start $request_length_end

How to Write Log Format?

See Log Format.

Threat rules

Cache

By default, teler will fetch external resources every time you run it, but you can switch external resources to be cached or not.

rules:
  cache: true

If you choose to cache resources, it’s stored under user-level cache directory of cross-platform and will be updated every day, see resources.

Excludes

We include resources for predetermined threats, including:

  • Common Web Attack
  • CVE
  • Bad IP Address
  • Bad Referrer
  • Bad Crawler
  • Directory Bruteforce

You can disable any type of threat in the excludes configuration (case-sensitive).

rules:
  threat:
    excludes:
      - "Bad IP Address"

The above format detects threats that are not included as bad IP address, and will not analyze logs/ send alerts for that type.

Whitelists

You can also add whitelists to teler configuration.

rules:
  threat:
    whitelists:
      - "(curl|Go-http-client|okhttp)/*"
      - "^/wp-login\\\\.php"

It covers the entire HTTP request and processed as regExp, please write it with caution!

⚠️ NOTES:
We whitelist in their respective element & patterns DO NOT apply as a whole. This means that if you whitelist an IP (pattern) and activate Bad IP Address detection, then the whitelist is valid - if Bad IP Address matches the given IP whitelist. But if your intention is to whitelist the IP from all types of threats - it won’t!
But if the alert detects a Common Web Attack and comes from an IP pattern, it will NOT be whitelisted. Because Common Web Attack detects from request URL/path, so you must enter a request URL/path patterns in order for the whitelist to apply to that threat.

Customs

In case the engine-based (default) rules don’t detect or you want to create custom rules:

rules:
  threat:
    customs:
      - name: "Log4j Attack"
        condition: or
        rules:
          - element: "request_uri"
            pattern: \$\{.*:\/\/.*\/?\w+?\}

          - element: "http_referer"
            pattern: \$\{.*:\/\/.*\/?\w+?\}

          - element: "http_user_agent"
            pattern: \$\{.*:\/\/.*\/?\w+?\}

      - name: "Large File Upload"
        condition: and
        rules:
          - element: "body_bytes_sent"
            selector: true
            pattern: \d{6,}

          - element: "request_method"
            pattern: P(OST|UT)

Explanations:

  • name will be used as a threat category.
  • conditioned from custom threat rules (value: or, and, default: or)
  • element is which part of the log we will match the (regEx) pattern
  • selector is only as a display & pointer to which element we will use as a measure that the threat is in which part of the log
    • If there is no selector in the rules, then the first matching element will be used as the selector.

⚠️ NOTES: Custom threat rules don’t go through the whitelists.

Notification

We provide alert notification options:

  • Slack,
  • Telegram
  • Discord

Configure the notification alerts needed on:

notifications:
  slack:
    token: "xoxb-..."
    color: "#ffd21a"
    channel: "G30SPKI"

  telegram:
    token: "123456:ABC-DEF1234...-..."
    chat_id: "-111000"

  discord:
    token: "NkWkawkawkawkawka.X0xo.n-kmZwA8aWAA"
    color: "16312092"
    channel: "700000000000000..."

You can also choose to disable alerts or want to be sent where the alerts are.

alert:
  active: true
  provider: "slack"

Metrics

teler also supports metrics by using Prometheus.

Prometheus

You can configure the host, port and endpoint to use Prometheus metrics in the configuration file.

metrics:
  prometheus:
    active: false
    host: "localhost"
    port: 9099
    endpoint: "/metrics"

Logs

We also provide several logging options:

File:

logs:
  file:
    active: false
    json: false
    path: "/path/to/output.log"

Zinc also supported:

logs:
  zinc:
    active: false
    host: "localhost"
    port: 4080
    ssl: false
    username: "admin"
    password: "Complexpass#123"
    index: "lorem-ipsum-index"