crouching_tiger/README.md

<h1 align="center">Welcome to crouching_tiger 👋</h1>
<p>
  <img alt="Version" src="https://img.shields.io/badge/version-0.0.1-blue.svg?cacheSeconds=2592000" />
  <a href="#" target="_blank">
    <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" />
  </a>
</p>

[![built with Codeium](https://codeium.com/badges/main)](https://codeium.com)

> Automating wireless attacks on targets only intermittently available.
> Discovers real mac addresses in a network containing randomly generated ones.

## Goals

There are several of goals/ideal the project would like to achieve. They are:

* [ ] Run in the background for an indefinite period if need be.
* [ ] Provide a scanning feature used to create a properly formatted csv file to store identified
  targets in.

## IMPORTANT NOTE

**YOU MUST HAVE ROOT PERMISSION TO USE**

## Install

To install the script you have several options at your disposal. The only "frivolous" dependency is
the lovely art package for python. If you are interested in this script at all, then you more than
likely already have scapy installed on your system. Since all of these were already available on my
system, no installation was necessary. But for inquiring minds, the installation process is as
follows:

### Install with poetry

A simple `poetry install` should install all the required packages and create the venirtual env for
you. From there all that is needed is to run the script with:

```sh
poetry install
```

### Install with pipenv

Similarly to poetry, `pipenv install` should install all the required packages and create the
venirtual env for you. From there all that is needed is to run the script with:

```sh
pipenv install
```

### Install with pip

This will be more tricky because you will need to install the required packages in the root user's
local python library, and not the system python library. This is done by running the following
commands:

```bash
sudo su
pip3 install --user -r requirements.txt
exit
```

From here on you will need to become the root user before running the script.

## Config

The program is designed to take either flags from the command line of configuration variables from
the configu file. Flags on the command line will override variables set in the configuration file.
The configuration file for the program will be generated for you automatically upon first run. Once
generated, can be found in `/etc/ctiger/config.ini`. A copy of the configuration spec is provided
below:

```python
cfg = """# Crouching Tiger Config File
# PLEASE, DO NOT LEAVE THIS FILE UNTOUCHED!
# TARGETS WILL HAVE TO BE MODIFIED IN ORDER TO WORK!
# ------------------------------------------------------------

# General Settings
# ----------------
interface = string(default='wlan0')
logging_level = option('INFO', 'DEBUG', default='DEBUG')
log_file = string(default='/var/log/ctiger.log')

# ------------------------------------------------------------

# Attack Settings
# ----------------
[ATTACK]
scan_file = string(default='ct_aps.csv')
mon_type = option('create', 'switch', default='switch')
use_daemon = boolean(default=False)

# -----------------------------------------------------------

# Mac Purge Setings
# -----------------
[MAC_PURGE]
if_type = option('create', 'switch', default='switch')
valid_results = string(default='ct_valid.csv')
channel_list = list(default=list(1, 6, 11))
"""
```

The only configuration option that possibly could use some explanation is the option that defines
what type of monitor interface your particular wifi card allows. Not all wireless devices allow
the creation of a secondary wlanXmon interface. Some only allow for the mode of the device to be
changed. This variable is where you designate this type.

## Usage

All runtime flags and subcommands should be described in length by use of the `-h` flag. Further
information of subcommands are described using the subcommand plus the `-h` flag. ex. `poetry run
python3 ctiger.py mac -h`

```sh
sudo $(which poetry) run python3 ctiger.py -h

░█▀▀█ █▀▀█ █▀▀█ █──█ █▀▀ █──█ ─▀─ █▀▀▄ █▀▀▀  ▀▀█▀▀ ─▀─ █▀▀▀ █▀▀ █▀▀█ 
░█─── █▄▄▀ █──█ █──█ █── █▀▀█ ▀█▀ █──█ █─▀█  ─░█── ▀█▀ █─▀█ █▀▀ █▄▄▀ 
░█▄▄█ ▀─▀▀ ▀▀▀▀ ─▀▀▀ ▀▀▀ ▀──▀ ▀▀▀ ▀──▀ ▀▀▀▀  ─░█── ▀▀▀ ▀▀▀▀ ▀▀▀ ▀─▀▀ 
usage: ctiger.py -i $IFACE (-t $TARGET or -f $TARGET_FILE)

Performs various actions on wifi targets.

This program was created with the intent to allow users to attack
wifi targetsthat are only available some of the time, and extract
information from them.

There are three types of actions that can be performed:

2. ATTACK [att] = Will run a scan in the background looking for aps in target list.
      If found will begin capturing a pcap file and deauth attack.

3. Mac_Purge [mac] = Experimental: Scans for wireless devices and acquires their MAC
      addresses. Then transmits a Clear to Send Frame. If the device responds with 
      data frame, then information on the device will be stored and written to file.

options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -i NAME, --interface NAME
                        Interface(s) to scan on
  -f CONFIG_FILE, --file CONFIG_FILE
                        configuration file
  -l {INFO,DEBUG}, --log_level {INFO,DEBUG}
                        Log level
  -z LOG_FILE, --log_file LOG_FILE
                        Log file

actions:
  Action to perform

  {att,mac,scn}         You must use one.
    att                 Attack target
    mac                 Grab Valid addresses

Processing will take several seconds, please be patient.
```

#### For Mac discovery

Many devices use randomly generated mac addresses in order to cloak their real addresses. This
feature attempts to mitigate this strategy by exploiting the 802.11 protocol.

```sh
sudo $(which poetry) run python3 ctiger.py mac -h
░█▀▀█ █▀▀█ █▀▀█ █──█ █▀▀ █──█ ─▀─ █▀▀▄ █▀▀▀  ▀▀█▀▀ ─▀─ █▀▀▀ █▀▀ █▀▀█ 
░█─── █▄▄▀ █──█ █──█ █── █▀▀█ ▀█▀ █──█ █─▀█  ─░█── ▀█▀ █─▀█ █▀▀ █▄▄▀ 
░█▄▄█ ▀─▀▀ ▀▀▀▀ ─▀▀▀ ▀▀▀ ▀──▀ ▀▀▀ ▀──▀ ▀▀▀▀  ─░█── ▀▀▀ ▀▀▀▀ ▀▀▀ ▀─▀▀ 
usage: ctiger.py -i $IFACE (-t $TARGET or -f $TARGET_FILE) mac
       [-h] [-t {create,switch}] [-f VALID_FILE] [-c CHANNELS]

options:
  -h, --help            show this help message and exit
  -t {create,switch}, --type {create,switch}
                        Create new monitor inf or switch mode.
  -f VALID_FILE, --file VALID_FILE
                        File to write results too.
  -c CHANNELS, --channels CHANNELS
                        A single or comma seperated list of channels.
```

## Citations

```text
Hansen, Y. (2018). Python Scapy Dot11. Createspace Independent Publishing Platform.

rpp0. (2024, January 23). rpp0/scapy-fakeap. GitHub. https://github.com/rpp0/scapy-fakeap
```

## Author

👤 **Anoduck**

* Website: http://anoduck.github.io
* Github: [@anoduck](https://github.com/anoduck)

## Show your support

Donate to Lord Mzte for use of his repository hosting service.

***
_This README was generated with ❤️ by [readme-md-generator](https://github.com/kefranabg/readme-md-generator)