Skip to content
/ litm Public

Linux Incident Time Machine - A tool for generating human-readable, event-based timelines from Linux `audit.log` files. Designed for SOC analysts to quickly understand security events and present findings to management.

License

View license
15 stars 2 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

cumakurt/litm

BranchesTags

Repository files navigation

Linux Incident Time Machine

English | Türkçe

English

A tool for generating human-readable, event-based timelines from Linux audit.log files. Designed for SOC analysts to quickly understand security events and present findings to management.

Linux Incident Time Machine

GitHub: https://github.com/cumakurt/litm

Features

  • Explainability First: Every event includes a human-readable summary that answers:

    • Who performed the action?
    • What did they do?
    • Why is it risky?
    • Is it normal or anomalous?

  • Security Context: Automatic detection of:

    • Privilege escalations (auid != uid)
    • Destructive commands (rm -rf, chmod 777, etc.)
    • Network activity (IP addresses, ports, connections)
    • Critical file access (system files, configuration files)
    • Risk level classification (low/medium/high)
    • Session detection and grouping
    • Command chain analysis
    • Coordinated activities
    • Behavioral anomalies

  • Robust Parsing: Handles:

    • Multi-line audit records
    • Missing correlations (log manipulation detection)
    • Incomplete records
    • Timestamp anomalies

  • SOC-Ready Output:

    • Colored terminal output
    • Emoji risk indicators
    • Time-sorted events
    • Anomaly detection
    • HTML interactive reports
    • PDF export
    • Multiple output formats (human, JSON, CSV, HTML, PDF)

  • Advanced Analysis Features:

    • Custom detection rules engine
    • Command chain analysis
    • Correlation engine for coordinated activities
    • Statistical analysis and user behavior baselines
    • IP address tracking and geolocation
    • Multi-file analysis support

Installation

# Install dependencies
pip install -r requirements.txt

Usage

The application can be run directly:

python litm.py /var/log/audit/audit.log

Project Structure

Linux_Incident_Time_Machine/
├── LICENSE                  # GPL-3.0 License
├── README.md                # This file
├── CHANGELOG.md             # Version history
├── .gitignore               # Git ignore rules
├── requirements.txt         # Production dependencies
├── requirements-dev.txt     # Development dependencies
├── __init__.py              # Package initialization
│
├── litm.py                # Main application (command-line interface)
├── models.py              # Pydantic models for audit events
├── parser.py              # Audit log parser
├── timeline.py            # Timeline generation service
├── config.py              # Configuration management
├── exceptions.py          # Custom exception classes
├── formatters.py          # Output formatters (JSON, CSV, HTML, PDF)
├── metrics.py             # Processing metrics
├── utils.py               # Utility functions (logging, user resolver)
├── rules_engine.py        # Custom detection rules engine
├── command_chain.py       # Command chain analysis
├── correlation.py         # Correlation engine
├── statistics.py          # Statistical analysis and baselines
└── ip_tracker.py          # IP address tracking

Usage

Basic Usage

# Analyze default audit log (/var/log/audit/audit.log)
python litm.py

# Analyze specific audit log file
python litm.py /path/to/audit.log

Filter by Time Range

The --start and --end parameters allow you to analyze events within a specific time window. This is useful for:

  • Investigating incidents that occurred during a specific period
  • Focusing on events around a known incident time
  • Analyzing activity during business hours vs. off-hours
# Events from a specific time
python litm.py --start 2024-01-01T00:00:00

# Events within a time range
python litm.py --start 2024-01-01T00:00:00 --end 2024-01-02T00:00:00

Filter by User

python litm.py --user root

Show Anomalies Only

python litm.py --anomalies

Output Formats

# Human-readable (default)
python litm.py /var/log/audit/audit.log

# JSON output
python litm.py --output json /var/log/audit/audit.log

# CSV output
python litm.py --output csv --output-file events.csv /var/log/audit/audit.log

# HTML interactive report
python litm.py --output html --output-file report.html /var/log/audit/audit.log

# PDF report (requires reportlab)
python litm.py --output pdf --output-file report.pdf /var/log/audit/audit.log

Advanced Analysis Options

# Multi-file analysis - merge multiple audit logs
python litm.py --merge audit1.log audit2.log audit3.log

# Apply custom detection rules
python litm.py --rules /var/log/audit/audit.log

# Command chain analysis for suspicious patterns
python litm.py --command-chains /var/log/audit/audit.log

# Detect coordinated activities and correlations
python litm.py --correlations /var/log/audit/audit.log

# Statistical analysis
python litm.py --statistics /var/log/audit/audit.log

# Behavioral anomaly detection
python litm.py --statistics --behavioral-anomalies /var/log/audit/audit.log

# IP address tracking
python litm.py --ip-tracking /var/log/audit/audit.log

Other Advanced Options

# Show all events including low-risk (verbose mode)
python litm.py --verbose

# Quiet mode (minimal output)
python litm.py --quiet

# Show processing metrics
python litm.py --metrics

# Set log level
python litm.py --log-level DEBUG

Combined Filters and Analysis

# Comprehensive incident analysis with all features
python litm.py --start 2024-01-01T00:00:00 --end 2024-01-02T00:00:00 \
  --user root --anomalies --correlations --command-chains \
  --statistics --behavioral-anomalies --ip-tracking \
  --output html --output-file incident_report.html

# Multi-file analysis with correlations
python litm.py --merge audit1.log audit2.log --correlations \
  --output json --output-file merged_analysis.json

# Command chain analysis for specific user
python litm.py --user suspicious_user --command-chains \
  --statistics --output html --output-file user_analysis.html

Output Format

The tool generates a timeline with the following format:

[HH:MM:SS] ✓ user executed: ls -la
[HH:MM:SS] ⚠ user used sudo to execute: systemctl restart nginx
[HH:MM:SS] 🔥 user executed destructive command: rm -rf /tmp/test
  • ✓ = Low risk
  • ⚠ = Medium risk
  • 🔥 = High risk

Architecture

Components

  1. models.py: Pydantic models for audit events with derived fields

    • Automatic privilege escalation detection
    • Destructive command detection
    • Network activity detection
    • Critical file access detection
    • Risk level computation
    • Human-readable summary generation

  2. parser.py: Audit log parser

    • Multi-line record handling
    • SYSCALL + EXECVE correlation by msg=audit ID
    • Network information extraction (IP, port)
    • File access information extraction
    • Robust against log manipulation
    • Anomaly detection

  3. timeline.py: Timeline generation service

    • Event grouping by auid (authenticated user)
    • Session detection (login → commands → logout)
    • Privilege escalation tracking
    • Anomaly pattern detection

  4. rules_engine.py: Custom detection rules engine

    • Default detection rules (base64 obfuscation, pipe to shell, etc.)
    • Custom regex pattern matching
    • Rule management (add, remove, enable, disable)

  5. command_chain.py: Command chain analysis

    • Suspicious command chain detection
    • Obfuscation detection
    • Download and execute pattern detection

  6. correlation.py: Correlation engine

    • Coordinated activity detection
    • Lateral movement detection
    • IP-based correlation

  7. statistics.py: Statistical analysis

    • User behavior baseline creation
    • Off-hours activity detection
    • Behavioral anomaly detection

  8. ip_tracker.py: IP address tracking

    • IP extraction from events
    • IP statistics
    • Geolocation support (placeholder)

  9. formatters.py: Output formatters

    • JSON, CSV, HTML, PDF formats
    • Interactive HTML reports
    • PDF report generation

  10. litm.py: Command-line interface

    • Colored output
    • Risk indicators
    • Filtering options
    • Summary statistics
    • Integration of all analysis features

Security Considerations

The parser includes robustness against log manipulation:

  • Missing Correlations: Detects when SYSCALL or EXECVE records are missing
  • Timestamp Validation: Flags future timestamps and mismatches
  • Incomplete Records: Handles partial records gracefully
  • Chain of Custody: Warns about potential log tampering

Feature Scope

This tool includes:

✅ Audit log parsing
✅ AUID / UID distinction
✅ Sudo / su detection
✅ Session extraction
✅ Human-readable timeline
✅ Network activity detection
✅ File access tracking
✅ Custom detection rules
✅ Command chain analysis
✅ Correlation engine
✅ Statistical analysis
✅ Behavioral anomaly detection
✅ IP address tracking
✅ Multi-file analysis
✅ HTML/PDF report generation
❌ Machine learning (out of scope)
❌ SIEM integration (out of scope)

Example Output

Linux Incident Time Machine
Analyzing: /var/log/audit/audit.log

Parsed 150 audit events
Showing 23 significant events (filtered 127 routine events)
Use --verbose to show all events

======================================================================
EVENT TIMELINE (23 events)
======================================================================

📅 2025-01-15
[10:23:15] ✓ uid_1000 logged in via pts/0
[10:23:20] ✓ uid_1000 executed: ls -la
[10:25:10] ⚠ uid_1000 used sudo to execute: systemctl restart nginx
    ⚠ Privilege escalation (auid=1000 → uid=0)
[10:26:30] 🔥 uid_1000 executed destructive command: rm -rf /tmp/test
    🔥 Destructive command
    📁 /tmp

======================================================================
SUMMARY
======================================================================

  Total events analyzed: 23
  ✓ Low risk: 15
  ⚠ Medium risk: 5
  🔥 High risk: 3

  ⚠ Privilege escalations: 3
  🔥 Destructive actions: 1

  Time range: 2025-01-15 10:23:15 → 2025-01-15 18:45:30

Development

The codebase follows these principles:

  • Simplicity: No over-engineering, straightforward code
  • Readability: Clear variable names and structure
  • Security: Robust against manipulation and missing data
  • Explainability: Every event tells a story

Running Tests

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Run tests with coverage
pytest tests/ --cov=. --cov-report=html

License

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

Developer

Developed by Cuma KURT

Türkçe

Linux audit.log dosyalarından insan tarafından okunabilir, olay bazlı zaman çizelgeleri (timeline) üreten bir araç. SOC analistlerinin güvenlik olaylarını hızlıca anlaması ve bulgularını yönetime sunması için tasarlanmıştır.

Linux Incident Time Machine

GitHub: https://github.com/cumakurt/litm

Özellikler

  • Açıklanabilirlik Öncelikli: Her olay şu soruları cevaplayan insan okunabilir bir özet içerir:

    • Kim işlemi gerçekleştirdi?
    • Ne yaptı?
    • Neden riskli?
    • Normal mi anormal mi?

  • Güvenlik Bağlamı: Otomatik tespit:

    • Yetki yükseltmeleri (auid != uid)
    • Yıkıcı komutlar (rm -rf, chmod 777, vb.)
    • Ağ aktiviteleri (IP adresleri, portlar, bağlantılar)
    • Kritik dosya erişimleri (sistem dosyaları, yapılandırma dosyaları)
    • Risk seviyesi sınıflandırması (düşük/orta/yüksek)
    • Oturum tespiti ve gruplama
    • Komut zinciri analizi
    • Koordineli aktiviteler
    • Davranışsal anomaliler

  • Dayanıklı Ayrıştırma: İşler:

    • Çok satırlı audit kayıtları
    • Eksik korelasyonlar (log manipülasyonu tespiti)
    • Eksik kayıtlar
    • Zaman damgası anomalileri

  • SOC-Hazır Çıktı:

    • Renkli terminal çıktısı
    • Emoji risk göstergeleri
    • Zaman sıralı olaylar
    • Anomali tespiti
    • İnteraktif HTML raporlar
    • PDF dışa aktarma
    • Çoklu çıktı formatları (human, JSON, CSV, HTML, PDF)

  • Gelişmiş Analiz Özellikleri:

    • Özel tespit kuralları motoru
    • Komut zinciri analizi
    • Koordineli aktiviteler için korelasyon motoru
    • İstatistiksel analiz ve kullanıcı davranış baseline'ları
    • IP adresi takibi ve coğrafi konum
    • Çoklu dosya analizi desteği

Kurulum

# Bağımlılıkları kur
pip install -r requirements.txt

Kullanım

Uygulama doğrudan çalıştırılabilir:

python litm.py /var/log/audit/audit.log

Proje Yapısı

Linux_Incident_Time_Machine/
├── LICENSE                  # GPL-3.0 Lisansı
├── README.md               # Bu dosya
├── CHANGELOG.md            # Versiyon geçmişi
├── .gitignore             # Git ignore kuralları
├── requirements.txt        # Üretim bağımlılıkları
├── requirements-dev.txt    # Geliştirme bağımlılıkları
├── __init__.py            # Paket başlatma
│
├── litm.py                # Ana uygulama (komut satırı arayüzü)
├── models.py              # Audit olayları için Pydantic modelleri
├── parser.py              # Audit log ayrıştırıcı
├── timeline.py            # Zaman çizelgesi üretim servisi
├── config.py              # Konfigürasyon yönetimi
├── exceptions.py          # Özel exception sınıfları
├── formatters.py          # Çıktı formatlayıcıları (JSON, CSV, HTML, PDF)
├── metrics.py             # İşleme metrikleri
├── utils.py               # Yardımcı fonksiyonlar (logging, kullanıcı çözümleyici)
├── rules_engine.py        # Özel tespit kuralları motoru
├── command_chain.py       # Komut zinciri analizi
├── correlation.py          # Korelasyon motoru
├── statistics.py          # İstatistiksel analiz ve baseline'lar
└── ip_tracker.py          # IP adresi takibi

Kullanım

Temel Kullanım

# Varsayılan audit log'u analiz et (/var/log/audit/audit.log)
python litm.py

# Belirli bir audit log dosyasını analiz et
python litm.py /path/to/audit.log

Zaman Aralığı ile Filtreleme

--start ve --end parametreleri belirli bir zaman penceresindeki olayları analiz etmenize olanak tanır. Bu şunlar için kullanışlıdır:

  • Belirli bir dönemde meydana gelen olayları araştırma
  • Bilinen bir olay zamanı etrafındaki olaylara odaklanma
  • İş saatleri vs. mesai dışı aktivite analizi
# Belirli bir zamandan itibaren olaylar
python litm.py --start 2024-01-01T00:00:00

# Zaman aralığındaki olaylar
python litm.py --start 2024-01-01T00:00:00 --end 2024-01-02T00:00:00

Kullanıcı ile Filtreleme

python litm.py --user root

Sadece Anomalileri Göster

python litm.py --anomalies

Çıktı Formatları

# İnsan okunabilir (varsayılan)
python litm.py /var/log/audit/audit.log

# JSON çıktı
python litm.py --output json /var/log/audit/audit.log

# CSV çıktı
python litm.py --output csv --output-file events.csv /var/log/audit/audit.log

# İnteraktif HTML rapor
python litm.py --output html --output-file report.html /var/log/audit/audit.log

# PDF rapor (reportlab gerektirir)
python litm.py --output pdf --output-file report.pdf /var/log/audit/audit.log

Gelişmiş Analiz Seçenekleri

# Çoklu dosya analizi - birden fazla audit log'u birleştir
python litm.py --merge audit1.log audit2.log audit3.log

# Özel tespit kurallarını uygula
python litm.py --rules /var/log/audit/audit.log

# Şüpheli pattern'ler için komut zinciri analizi
python litm.py --command-chains /var/log/audit/audit.log

# Koordineli aktiviteler ve korelasyonları tespit et
python litm.py --correlations /var/log/audit/audit.log

# İstatistiksel analiz
python litm.py --statistics /var/log/audit/audit.log

# Davranışsal anomali tespiti
python litm.py --statistics --behavioral-anomalies /var/log/audit/audit.log

# IP adresi takibi
python litm.py --ip-tracking /var/log/audit/audit.log

Diğer Gelişmiş Seçenekler

# Düşük riskli olaylar dahil tüm olayları göster (verbose modu)
python litm.py --verbose

# Sessiz mod (minimal çıktı)
python litm.py --quiet

# İşleme metriklerini göster
python litm.py --metrics

# Log seviyesini ayarla
python litm.py --log-level DEBUG

Birleşik Filtreler ve Analiz

# Tüm özelliklerle kapsamlı olay analizi
python litm.py --start 2024-01-01T00:00:00 --end 2024-01-02T00:00:00 \
  --user root --anomalies --correlations --command-chains \
  --statistics --behavioral-anomalies --ip-tracking \
  --output html --output-file incident_report.html

# Korelasyonlarla çoklu dosya analizi
python litm.py --merge audit1.log audit2.log --correlations \
  --output json --output-file merged_analysis.json

# Belirli kullanıcı için komut zinciri analizi
python litm.py --user suspicious_user --command-chains \
  --statistics --output html --output-file user_analysis.html

Çıktı Formatı

Araç aşağıdaki formatta bir zaman çizelgesi üretir:

[HH:MM:SS] ✓ kullanıcı çalıştırdı: ls -la
[HH:MM:SS] ⚠ kullanıcı sudo kullanarak çalıştırdı: systemctl restart nginx
[HH:MM:SS] 🔥 kullanıcı yıkıcı komut çalıştırdı: rm -rf /tmp/test
  • ✓ = Düşük risk
  • ⚠ = Orta risk
  • 🔥 = Yüksek risk

Mimari

Bileşenler

  1. models.py: Türetilmiş alanlarla audit olayları için Pydantic modelleri

    • Otomatik yetki yükseltme tespiti
    • Yıkıcı komut tespiti
    • Ağ aktivitesi tespiti
    • Kritik dosya erişimi tespiti
    • Risk seviyesi hesaplama
    • İnsan okunabilir özet üretimi

  2. parser.py: Audit log ayrıştırıcı

    • Çok satırlı kayıt işleme
    • msg=audit ID ile SYSCALL + EXECVE korelasyonu
    • Ağ bilgisi çıkarımı (IP, port)
    • Dosya erişim bilgisi çıkarımı
    • Log manipülasyonuna karşı dayanıklı
    • Anomali tespiti

  3. timeline.py: Zaman çizelgesi üretim servisi

    • Auid (kimlik doğrulanmış kullanıcı) bazlı olay gruplama
    • Oturum tespiti (giriş → komutlar → çıkış)
    • Yetki yükseltme takibi
    • Anomali desen tespiti

  4. rules_engine.py: Özel tespit kuralları motoru

    • Varsayılan tespit kuralları (base64 obfuscation, pipe to shell, vb.)
    • Özel regex pattern eşleştirme
    • Kural yönetimi (ekle, kaldır, etkinleştir, devre dışı bırak)

  5. command_chain.py: Komut zinciri analizi

    • Şüpheli komut zinciri tespiti
    • Obfuscation tespiti
    • İndirme ve çalıştırma pattern tespiti

  6. correlation.py: Korelasyon motoru

    • Koordineli aktivite tespiti
    • Lateral movement tespiti
    • IP tabanlı korelasyon

  7. statistics.py: İstatistiksel analiz

    • Kullanıcı davranış baseline oluşturma
    • Mesai dışı aktivite tespiti
    • Davranışsal anomali tespiti

  8. ip_tracker.py: IP adresi takibi

    • Olaylardan IP çıkarımı
    • IP istatistikleri
    • Coğrafi konum desteği (placeholder)

  9. formatters.py: Çıktı formatlayıcıları

    • JSON, CSV, HTML, PDF formatları
    • İnteraktif HTML raporlar
    • PDF rapor üretimi

  10. litm.py: Komut satırı arayüzü

    • Renkli çıktı
    • Risk göstergeleri
    • Filtreleme seçenekleri
    • Özet istatistikler
    • Tüm analiz özelliklerinin entegrasyonu

Güvenlik Değerlendirmeleri

Ayrıştırıcı log manipülasyonuna karşı dayanıklılık içerir:

  • Eksik Korelasyonlar: SYSCALL veya EXECVE kayıtları eksik olduğunda tespit eder
  • Zaman Damgası Doğrulama: Gelecek zaman damgalarını ve uyumsuzlukları işaretler
  • Eksik Kayıtlar: Kısmi kayıtları zarifçe işler
  • Zincir Kanıtı: Potansiyel log tahrifatı konusunda uyarır

Özellik Kapsamı

Bu araç şunları içerir:

✅ Audit log ayrıştırma
✅ AUID / UID ayrımı
✅ Sudo / su tespiti
✅ Oturum çıkarımı
✅ İnsan okunabilir zaman çizelgesi
✅ Ağ aktivitesi tespiti
✅ Dosya erişim takibi
✅ Özel tespit kuralları
✅ Komut zinciri analizi
✅ Korelasyon motoru
✅ İstatistiksel analiz
✅ Davranışsal anomali tespiti
✅ IP adresi takibi
✅ Çoklu dosya analizi
✅ HTML/PDF rapor üretimi
❌ Makine öğrenmesi (kapsam dışı)
❌ SIEM entegrasyonu (kapsam dışı)

Örnek Çıktı

Linux Incident Time Machine
Analyzing: /var/log/audit/audit.log

Parsed 150 audit events
Showing 23 significant events (filtered 127 routine events)
Use --verbose to show all events

======================================================================
EVENT TIMELINE (23 events)
======================================================================

📅 2025-01-15
[10:23:15] ✓ uid_1000 logged in via pts/0
[10:23:20] ✓ uid_1000 executed: ls -la
[10:25:10] ⚠ uid_1000 used sudo to execute: systemctl restart nginx
    ⚠ Privilege escalation (auid=1000 → uid=0)
[10:26:30] 🔥 uid_1000 executed destructive command: rm -rf /tmp/test
    🔥 Destructive command
    📁 /tmp

======================================================================
SUMMARY
======================================================================

  Total events analyzed: 23
  ✓ Low risk: 15
  ⚠ Medium risk: 5
  🔥 High risk: 3

  ⚠ Privilege escalations: 3
  🔥 Destructive actions: 1

  Time range: 2025-01-15 10:23:15 → 2025-01-15 18:45:30

Geliştirme

Kod tabanı şu ilkelere uyar:

  • Basitlik: Gereksiz karmaşıklık yok, düz kod
  • Okunabilirlik: Net değişken isimleri ve yapı
  • Güvenlik: Manipülasyon ve eksik verilere karşı dayanıklı
  • Açıklanabilirlik: Her olay bir hikaye anlatır

Testleri Çalıştırma

# Geliştirme bağımlılıklarını kur
pip install -r requirements-dev.txt

# Testleri çalıştır
pytest tests/

# Kapsam ile testleri çalıştır
pytest tests/ --cov=. --cov-report=html

Lisans

Bu proje GPL-3.0 Lisansı altında lisanslanmıştır - detaylar için LICENSE dosyasına bakın.

Geliştirici

Geliştiren: Cuma KURT

About

Linux Incident Time Machine - A tool for generating human-readable, event-based timelines from Linux `audit.log` files. Designed for SOC analysts to quickly understand security events and present findings to management.

Topics

linux parser log history audit

Resources

Readme

License

View license
Activity

Stars

15 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages