LogonTracer

Investigate malicious Windows logon by visualizing and analyzing Windows event log

3,195

488

3,195

View on GitHub

Top Related Projects

grr

5,083

GRR Rapid Response: remote live forensics for incident response

TheHive

3,914

TheHive is a Collaborative Case Management Platform, now distributed as a commercial version

MISP

6,273

MISP (core software) - Open Source Threat Intelligence and Sharing Platform

windows-event-forwarding

1,337

A repository for using windows event forwarding for incident detection and response

Quick Overview

LogonTracer is a tool for visualizing and analyzing Windows active directory event logs. It helps investigate malicious logon by visualizing and analyzing event logs, creating an interactive graph of relationships between accounts and hosts based on Windows event logs.

Pros

Provides a visual representation of logon events, making it easier to identify patterns and anomalies
Supports various log formats, including Windows Event Log and Sysmon
Offers a web-based interface for easy access and collaboration
Includes features for timeline analysis and filtering of events

Cons

Requires significant setup and configuration, which may be challenging for less technical users
Limited to Windows environments and specific log formats
May require substantial system resources for processing large log datasets
Documentation could be more comprehensive for advanced use cases

Getting Started

Clone the repository:

git clone https://github.com/JPCERTCC/LogonTracer.git

Install dependencies:
```
pip install -r requirements.txt
```
Set up Neo4j database:
- Download and install Neo4j
- Create a new database and set a password
Configure LogonTracer:
- Edit config.py to set your Neo4j credentials and other settings
Run LogonTracer:
```
python3 logontracer.py
```
Access the web interface at http://localhost:8080

For detailed instructions and advanced usage, refer to the project's README and documentation.

Competitor Comparisons

Loki

3,773

Loki - Simple IOC and YARA Scanner

Pros of Loki

Broader scope: Detects various types of malware and suspicious files, not limited to logon events
Portable and lightweight: Can be run from a USB stick without installation
Regular updates: Frequently updated with new IOCs and detection rules

Cons of Loki

Less specialized: May not provide as detailed analysis for logon-related events
Higher false positive rate: Due to its broader scope, it may generate more false positives
Resource-intensive: Scanning large systems can be time-consuming and resource-heavy

Code Comparison

LogonTracer (Python):

def get_event_id(self, event):
    return event.get("Event", {}).get("System", {}).get("EventID", None)

Loki (Python):

def scan_path(self, path):
    for root, directories, files in os.walk(path):
        for filename in files:
            try:
                filePath = os.path.join(root, filename)
                self.scan_file(filePath)
            except Exception as e:
                log.error("Error while scanning file %s - %s" % (filePath, e))

The code snippets show that LogonTracer focuses on parsing specific event logs, while Loki scans entire file systems for suspicious files and patterns. This reflects their different approaches: LogonTracer's specialized focus on logon events versus Loki's broader malware detection capabilities.

grr

5,083

GRR Rapid Response: remote live forensics for incident response

Pros of GRR

More comprehensive incident response and remote live forensics capabilities
Scalable architecture for enterprise-level deployments
Active development and support from Google

Cons of GRR

Steeper learning curve and more complex setup
Requires more resources to deploy and maintain
May be overkill for smaller organizations or specific logon analysis tasks

Code Comparison

LogonTracer (Python):

def parse_evtx(evtx_file, output_dir):
    parser = PyEvtxParser(evtx_file)
    for record in parser.records():
        event = xmltodict.parse(record["data"])
        # Process event data

GRR (Python):

class CollectArtifactFlow(flow.GRRFlow):
    def Start(self):
        self.CallClient(
            server_stubs.ArtifactCollector,
            artifact_list=self.args.artifact_list,
            use_tsk=self.args.use_tsk,
            next_state="ProcessResults"
        )

LogonTracer focuses specifically on Windows logon events and provides visualization, while GRR offers a broader range of remote forensics capabilities. LogonTracer is more lightweight and easier to set up for its specific use case, whereas GRR provides a more comprehensive but complex solution for enterprise-level incident response and forensics.

TheHive

3,914

TheHive is a Collaborative Case Management Platform, now distributed as a commercial version

Pros of TheHive

More comprehensive incident response platform with case management capabilities
Integrates with various security tools and threat intelligence platforms
Supports collaboration among team members with real-time updates

Cons of TheHive

Steeper learning curve due to its extensive features
Requires more resources to set up and maintain
May be overkill for organizations primarily focused on logon analysis

Code Comparison

TheHive (Python):

def create_case(title, description, severity):
    case = Case(title=title, description=description, severity=severity)
    case.save()
    return case

LogonTracer (Python):

def parse_event_log(log_file):
    events = []
    for event in win32evtlog.ReadEventLog(log_file):
        events.append(parse_event(event))
    return events

TheHive offers a more comprehensive API for managing cases and incidents, while LogonTracer focuses specifically on parsing and analyzing Windows event logs for logon-related activities.

MISP

6,273

MISP (core software) - Open Source Threat Intelligence and Sharing Platform

Pros of MISP

More comprehensive threat intelligence platform with broader functionality
Larger community and ecosystem for sharing threat data
Supports a wide range of data types and formats for threat intelligence

Cons of MISP

Steeper learning curve due to its complexity
Requires more resources to set up and maintain
May be overkill for organizations primarily focused on logon analysis

Code Comparison

MISP (Python):

@staticmethod
def get_uuid():
    return str(uuid.uuid4())

def __init__(self):
    self.uuid = self.get_uuid()

LogonTracer (JavaScript):

function getUniqueId() {
  return Math.random().toString(36).substr(2, 9);
}

const id = getUniqueId();

While both projects use different languages, this comparison shows how they generate unique identifiers. MISP uses Python's built-in UUID module, while LogonTracer uses a custom JavaScript function for generating a unique string.

windows-event-forwarding

1,337

A repository for using windows event forwarding for incident detection and response

Pros of Windows Event Forwarding

Comprehensive Windows event collection and forwarding solution
Scalable for enterprise environments
Integrates well with existing Windows infrastructure

Cons of Windows Event Forwarding

Limited to Windows environments
Requires more setup and configuration
Less focused on specific threat detection scenarios

Code Comparison

Windows Event Forwarding (WEF.ps1):

$EventCollectorServer = "collector.domain.com"
$SubscriptionList = Get-WEFSubscriptionList -ComputerName $EventCollectorServer
foreach ($Subscription in $SubscriptionList) {
    Write-Host "Subscription: $($Subscription.Name)"
}

LogonTracer (logontracer.py):

def get_event_logs(self):
    for event in self.evtx_file.records():
        if event.get("Event", {}).get("System", {}).get("EventID") in self.event_ids:
            yield event

The Windows Event Forwarding code focuses on managing subscriptions, while LogonTracer's code is tailored for parsing specific event logs related to logon activities.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Concept

LogonTracer v2 is a tool to investigate malicious logon by visualizing and analyzing Windows Active Directory event logs. This tool associates a host name (or an IP address) and account name found in logon-related events and displays it as a graph. This way, it is possible to see in which account login attempt occurs and which host is used.

This tool can visualize the following event IDs related to Windows logon.

Event ID	Description
4624	Successful logon
4625	Logon failure
4662	An operation was performed on an object
4672	Assign special privileges
4719	System audit policy was changed
4720	A user account was created
4726	A user account was deleted
4728 / 4732 / 4756	A member was added to a security-enabled group
4729 / 4733 / 4757	A member was removed from a security-enabled group
4768	Kerberos Authentication (TGT Request)
4769	Kerberos Service Ticket (ST Request)
4776	NTLM Authentication
5137	A directory service object was created
5141	A directory service object was deleted

More details are described in the following documents:

LogonTracer sample

What's New in Version 2.0

AI-Powered Security Analysis

LogonTracer v2.0 integrates an AI analysis engine using OpenAI GPT models to provide intelligent threat detection beyond traditional rule-based approaches.

Security Pattern Analysis â Automatically interprets graph query results and generates risk assessments with MITRE ATT&CK tactic mapping
Autonomous LLM Agent â An iterative AI agent that autonomously generates and executes Cypher queries against the Neo4j graph to discover threats without manual intervention
AI-Generated Sigma Rules â Converts AI analysis findings into deployable Sigma detection rules
Multi-language Support â AI responses can be generated in English, Japanese, or French

Sigma Rule Integration

Bundled Sigma Rules â Includes the full SigmaHQ rule set for scanning EVTX files
Sigma Scan on Upload â Optionally run Sigma rule scanning automatically during EVTX file upload
Sigma Rescan API â Re-scan previously uploaded EVTX files with a specific Sigma rule folder via REST API
Sigma Results View â Dedicated UI page displaying Sigma detection results in an interactive table

Additional Analysis

LogonTracer uses PageRank, Hidden Markov Model, and ChangeFinder to detect malicious hosts and accounts from event logs.

PageRank List

With LogonTracer, it is also possible to display event logs in chronological order.

Timeline

Requirements

Python 3.9 or later (3.12 recommended)
Neo4j 5.x (Community or Enterprise)
OpenAI API key (optional â required only for AI analysis features)
Python modules

numpy
evtx
lxml
scipy
changefinder
flask
hmmlearn>=0.2.8
scikit-learn
elasticsearch-dsl>=7.0.0,<8.0.0
pyyaml
flask-sqlalchemy
flask-login
flask_wtf
flask-limiter
wtforms
GitPython
pysigma>=0.11.0
pysigma-backend-sqlite
openai>=1.0.0
aiohttp
neo4j

Installation

1. Clone the repository

git clone https://github.com/JPCERTCC/LogonTracer.git
cd LogonTracer

2. Install dependencies

pip3 install -r requirements.txt

3. Start Neo4j

Download and start Neo4j. Set the initial password and note the Bolt port (default: 7687).

4. Edit the configuration file

vi config/config.yml

Key settings:

settings:
  logontracer:
    WEB_PORT: "8080"
    default_user: "neo4j"       # Neo4j username for the default LogonTracer account
    default_password: "password" # Change this before first run

  neo4j:
    NEO4J_USER: "neo4j"
    NEO4J_PASSWORD: "password"   # Your Neo4j password
    NEO4J_SERVER: "localhost"
    WS_PORT: "7687"

5. Start the web application

python3 logontracer.py --run

Open your browser at http://localhost:8080.

Usage

Importing Event Logs

Import EVTX file(s)

python3 logontracer.py -e <path/to/Security.evtx> -z <UTC offset> -s <Neo4j server> -u <user> -p <password>

Import XML file(s)

python3 logontracer.py -x <path/to/event.xml> -z <UTC offset> -s <Neo4j server> -u <user> -p <password>

Import from Elasticsearch

python3 logontracer.py --es -s <Neo4j server> -u <user> -p <password> --es-server <ES host:port>

Import with Sigma scanning

Add the --sigma flag to run Sigma rule detection during import:

python3 logontracer.py -e <path/to/Security.evtx> -z 9 -s localhost -u neo4j -p password --sigma

Add additional logs (without deleting existing data)

python3 logontracer.py -e <path/to/Security.evtx> -z 9 -s localhost -u neo4j -p password --add

Web GUI Upload

After starting the web application, click Upload Event Log in the left sidebar. You can:

Select one or more EVTX or XML files
Choose the UTC offset for the log timezone
Enable Add additional files to append data without clearing the database
Enable Run scan using Sigma rules to run Sigma detection automatically after import

Upload

Sigma Scan Results

After uploading with Sigma scanning enabled, or after triggering a rescan via the API, click Sigma Scan Results in the sidebar to view findings.

AI Analysis (v2.0)

Setup

Go to Settings â AI Settings in the navigation bar
Enable AI analysis and enter your OpenAI API key
Select the GPT model and preferred response language

Using AI Analysis

Click AI Analysis in the top navigation to run the autonomous LLM agent
The agent iteratively generates Cypher queries, executes them against the Neo4j database, and reports discovered threats
Click AI History to view the last analysis result
From the AI analysis result panel, click Generate Sigma Rules to convert findings into Sigma detection rules

Web Application Screenshots

Login

Main Graph View

Sample

Dark Mode

Timeline

Navigation Bar

Side Bar

Filter Panel

Diff Graph

Diff Panel

Case Management (Neo4j Enterprise)

With Neo4j Enterprise Edition, LogonTracer supports multiple independent investigation cases â each stored in a separate Neo4j database.

Add New Case â Create a new database for a new investigation
Delete Case â Remove a case database
Add/Delete Access to Case â Grant or revoke per-user access to specific cases
Change Case â Switch the active case in the current session

Docker

Using Docker (single container)

docker run \
  --detach \
  --publish=7474:7474 --publish=7687:7687 --publish=8080:8080 \
  -e LTHOSTNAME=<IP Address> \
  jpcertcc/docker-logontracer

Using Docker Compose

cd docker-compose
docker compose build
docker compose up -d

Using Docker Compose with HTTPS (nginx)

cd docker-compose-with-nginx
docker compose build
docker compose up -d

Using Docker Compose with Elastic Stack

cd docker-compose-with-elasticstack
docker compose build
docker compose up -d

Command Line Options

Option	Description
`-r`, `--run`	Start the web application
`-o PORT`	Web application port (default: 8080)
`--host HOST`	Bind address (default: 0.0.0.0)
`-e EVTX [...]`	Import EVTX file(s)
`-x XML [...]`	Import XML event log file(s)
`-s SERVER`	Neo4j server address (default: localhost)
`-u USER`	Neo4j username (default: neo4j)
`-p PASSWORD`	Neo4j password
`--wsport PORT`	Neo4j Bolt port (default: 7687)
`-z UTC`	Timezone offset (e.g. `9` for JST)
`-f DATE`	Parse logs from this datetime (e.g. `2024-01-01T00:00:00`)
`-t DATE`	Parse logs to this datetime
`--add`	Append data without clearing the database
`--delete`	Clear the database before importing
`--sigma`	Run Sigma rule scanning during import
`--sigma-only`	Run Sigma scan only (no Neo4j processing)
`--sigma-rules PATH`	Path to Sigma rules folder (default: `sigma`)
`--es`	Import data from Elasticsearch
`--postes`	Post analysis results to Elasticsearch
`--es-server HOST:PORT`	Elasticsearch server
`--es-index INDEX`	Elasticsearch index (default: `winlogbeat-*`)
`--es-prefix PREFIX`	Elasticsearch event prefix (default: `winlog`)
`--case NAME`	Case name for Neo4j Enterprise multi-database mode
`-c FILE`	Configuration file path (default: `config/config.yml`)
`--create_user USER`	Create a new Neo4j user
`--create_password PASS`	Password for the new Neo4j user
`--role ROLE`	Role for the new user (`admin`, `architect`, `reader`)
`--delete_user USER`	Delete a Neo4j user
`-l`, `--learn`	Run machine learning analysis (Hidden Markov Model)

Demonstration

The following YouTube video shows how to use LogonTracer.

Documentation

For more details, please check the LogonTracer wiki.

License

LICENSE.txt

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot