Skip to content

Commit

Permalink
Update MITM to CLI option based configuration
Browse files Browse the repository at this point in the history
Instead of the old config file based mechanism
  • Loading branch information
zxlin committed Apr 17, 2022
1 parent 447981a commit 77f1121
Show file tree
Hide file tree
Showing 18 changed files with 541 additions and 705 deletions.
6 changes: 2 additions & 4 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,6 @@ npm-debug.log
node_modules/*

# --------------------
# MITM Config
# MITM
# --------------------
# Ignore the real mitm.js files
config/mitm*.js
!config/mitm_example.js
logs/
4 changes: 2 additions & 2 deletions License.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Copyright 2018 University of Maryland - College Park | Advanced Cybersecurity experience for Students
Copyright 2018 University of Maryland - College Park | Advanced Cybersecurity Experience for Students

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
73 changes: 28 additions & 45 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,8 @@
# Man-in-the-middle SSH Server
# Man-in-the-Middle (MITM) SSH Server

## Objective

Provide students the ability to collect SSH related data (login attempts, keystrokes) without the need for them to build their own SSH server.

See this [wiki page](https://github.com/UMD-ACES/MITM/wiki/Data-Collection) about the information collected by the MITM SSH server.
Provide students with the ability to collect SSH related data (login attempts, keystrokes) without the need to build their own SSH server.

## Expectations

Expand All @@ -16,65 +14,50 @@ This program is not meant to facilitate the following:
* Monitoring
* Data Analysis

However, students may modify this program as they wish including faciliting the above while following the [rules](https://github.com/UMD-ACES/MITM/blob/master/README.md#rules) described at a later section.
However, students may modify this program as they wish to add or change desired functionality.

# Data Collection
This program will collect 3 main types of data:
1. Authentication attempts - including client IP, username, and password
2. Successful logins - client IP
3. Session stream - raw session stream between the client & SSH server
4. Session keystrokes - all the individual keystrokes and the parsed lines

## Resources
## Start the MITM server

Please see the rest of this README page and check out the [wiki](https://github.com/UMD-ACES/MITM/wiki) pages.
Run `node mitm.js -n <container name> -i <container internal IP> -p <MITM listening port>` to start the MITM server.

Run with the `--debug` flag for verbose debug output. This is helpful when first setting up the server.

## Configuration

| Setting | Type | Explanation |
| :--------:| :----: | :------------|
| local | Boolean | Runs the MITM SSH Server without requiring a container. Warning messages will display and there will be limitations (e.g. pty mode is disabled). |
| debug | Boolean | MITM Debug Output. Good option to have enabled when building your honeypot ecosystem. Provides detailed logs of the actions that the MITM takes in real time. |
| logToInstructor.enabled | Boolean | Logging the MITM operations into a DB (must be **enabled** unless otherwise stated by an instructor or TA) |
| logging.streamOutput | String | Folder where the attacker streams are placed (keystrokes, screen display) |
| logging.loginAttempts | String | Folder where all login attempts are being logged |
| logging.logins | String | Folder where all logins are being logged |
| server.maxAttemptsPerConnection | Integer | Number of login attempts before the server force closes on the SSH client |
| server.listenIP | String | The IP address to listen on |
| server.identifier | String | The SSH server identifier string sent to the SSH client |
| server.banner | String | A message sent to clients upon connection to the MITM |
| autoAccess.enabled | Boolean | If true, then enable automatic access to the honeypot after a certain number of login attempts (normal distribution using mean and standard deviation values). Can be manually set in the command line. |
| autoAccess.cacheSize | Integer | Number of attacker IPs to hold when autoAccess is turned "on" . This value is required to not overwhelm the host memory. |
| autoAccess.barrier.normalDist.enabled | Boolean | Enable normal distribution to calculate the login attempt threshold per attacker |
| autoAccess.barrier.normalDist.mean | Integer | Mean number of login attempts before automatic access |
| autoAccess.barrier.normalDist.standardDeviation | Integer | Standard Deviation. Automatic access follows a normal distribution. |
| autoAccess.barrier.fixed.enabled | Boolean | Enable fixed login attempts threshold |
| autoAccess.barrier.fixed.attempts | Number | Number of login attempts |
Run with the `--help` option to see full list of configurable options and defaults.

## Automatic Access

## Start the MITM server
This feature allows an attacker to successfully authenticate after a certain number of login attempts.

View this wiki page to learn about starting the MITM SSH Server (https://github.com/UMD-ACES/MITM/wiki/Spawn-a-MITM-SSH-Server-instance#launch-a-mitm-ssh-server)
Auto-access will only be available for 1 automatic access per MITM process, meaning that once MITM is triggered once, it will be disabled.

## Running MITM in the background
Furthermore, enabling auto-access will essentially disable authentication checks against the SSH server itself until auto-access strategy triggers.

Please check this [wiki page](https://github.com/UMD-ACES/MITM/wiki/Running-in-the-Background) if you would like to run the MITM in the background
Enable auto-access by toggling the `--auto-access` option, then you must configure one of the two strategies available:
1. normal distribution
2. fixed attempt

## Automatic Access
For normal distribution strategy, the server will allow auto-access after `--auto-access-normal-distribution-mean` number of attempts with the consideration of `--auto-access-normal-distribution-std-dev` to randomize the number of attempts required.

Allows an attacker to successfully authenticate after a certain number of login attempts.
For fixed attempt strategy, the server will simply allow auto-access after --auto-access-fixed` number of attempts.

Before using automatic access, please read the following [wiki page](https://github.com/UMD-ACES/MITM/wiki/Automatic-Access)
## Running MITM in the background

## Rules
1. Do not add/edit/delete any code that are in the instructor blocks.
2. You must enable the logToInstructor functionality.
3. If you are having issues with a particular MITM instance, please make sure to communicate the session id
Please check this [wiki page](https://github.com/UMD-ACES/MITM/wiki/Running-in-the-Background) if you would like to run the MITM in the background

## Stay up to date
Run `git pull origin master` inside the /root/MITM directory.

## Documentation
[Wiki Page](https://github.com/UMD-ACES/MITM/wiki)
Run `git pull origin main` inside the /root/MITM directory.

## Authors
Louis-Henri Merino
Franz Payer
Zhi Xiang Lin
## Additional Documentation
Some of the [Wiki Page](https://github.com/UMD-ACES/MITM/wiki) may be out of date, please review the information carefully.

## License
MIT License
47 changes: 0 additions & 47 deletions config/mitm_example.js

This file was deleted.

8 changes: 4 additions & 4 deletions install.sh
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
#!/usr/bin/env bash

sudo apt-get update
sudo apt update

sudo apt-get install -y sudo build-essential curl php-cli gcc g++ make
sudo apt install -y build-essential curl gcc g++ make

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -

sudo apt-get install -y nodejs
sudo apt install -y nodejs

cd "$(dirname "$0")"

Expand Down
11 changes: 0 additions & 11 deletions lxc/add_user.php

This file was deleted.

6 changes: 6 additions & 0 deletions lxc/add_user.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
#!/bin/bash

CONTAINER=$1
USERNAME=$2

lxc-attach -n "$CONTAINER" -- useradd "$USERNAME" -m -s /bin/bash > /dev/null 2>&1 || true
44 changes: 0 additions & 44 deletions lxc/ensure_mount.py

This file was deleted.

11 changes: 0 additions & 11 deletions lxc/execute_command.py

This file was deleted.

15 changes: 0 additions & 15 deletions lxc/load_credentials.php

This file was deleted.

7 changes: 7 additions & 0 deletions lxc/load_credentials.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
#!/bin/bash

CONTAINER=$1
USERNAME=$2
PASSWORD=$3

lxc-attach -n "$CONTAINER" -- usermod -p "$(openssl passwd "$PASSWORD")" "$USERNAME"
1 change: 1 addition & 0 deletions mitm.js
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
require('./server');
Loading

0 comments on commit 77f1121

Please sign in to comment.