Richl-lab / recognize-unusual-logins

This tool is used to find anomalies or suspicious login events, especially to detect lateral movement.

FindMaliciousEvents

This tool is used to find anomalies or suspicious login events, especially to detect lateral movement.
Explore the docs »

View Demo · Report Bug · See docs to add Features

• About The Project
  • Built With
• Getting Started
  • Prerequisites & Installation
• Logon Data
• Usage
  • Examples
  • Demo
• Roadmap
• License
• Contact
• Acknowledgements

About The Project

This tool is used to find anomalies or suspicious login events.

Built With

• R & R-Studio
• Python & Jupyter Notebook/Pycharm
• Shell & Pycharm

Getting Started

Prerequisites & Installation

This tool will only work in Linux (tested with Ubuntu 20.04). To use the tool, R and Python 3.8 needs to be installed. Furthermore, is a requirement an existing python environment in the folder with conditions of the requirements.txt.

To install and configure, use the following script:

. setup.sh

Installs:

• r-base
• python 3.8
• pip
• python3-venv
• wheel and some more python packages (requirments.txt)
• r-packages (dplyr,...)

Configuration:

• virtual environment named maliciousevents
• create ~/.R directory for r site-packages

Optional Configuration:

Add a link to one of your $PATH locations. As example, it can look like:

ln -s -r FindMaliciousEvents.R ~/.local/bin/FindMaliciousEvents   

Logon Data

The data needs the following structure:

Event ID	Host	Time	Logon ID	User	Source	Source Port	Logon Type
Integer	Char	Date	Numeric(hex)	Char	Char	Integer	Integer
4624	1112223	"2021-06-01 00:00:02"	0x233eef	33339993	3333888	0	2

(Default) Users with smaller numbers than 10000 will be removed, because they are interpreted as Well-Known-SIDs. The Software was tested with anonymized Users, Hosts and Sources, so there is no guarantee that it works without that.

Example data can be found here.

Usage

After usage, the r-script should be executable.

With set link:

FindMaliciousEvents args

Without:

FindMaliciousEvents.R args
or
Rscript FindMaliciousEvents.R args

Arguments:

FindMaliciousEvents [File location] [Directory to save] [Options]

For more information and options see:

FindMaliciousEvents --help

Examples

Find unusual logins from 2021-06-01 to 2021-07-01:

FindMaliciousEvents raw_data.csv . -d m 2021-06-01 2021-07-01

Find unusual logins with the use of kNN and rank it:

FindMaliciousEvents raw_data.csv . -m kNN -r

Find unusual logins from a existing feature set, that was created with this software:

FindMaliciousEvents features.csv . -e

Demo

Maintenance

If you want to add new features, see Maintenance Directory. It contains a description to add different kind of features.

Roadmap

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Richard Mey

• Private:[e-mail]
• University:[e-mail]

Project Link/Location:

Github Repository

Acknowledgements

• README Template
• Pyod kNN
• Scikit Isolationforest
• DAGMM