Initial concept release (#1)

Releasing initial concept release with support for the following options and transformations.

## Options:
```
  -f value
        Read additional files for input.
  -i value
        Starting index for transformations if applicable. Accepts ranges separated by '-'. (default 0)
  -k value
        Only keep items in a file.
  -m int
        Minimum numerical frequency to include in output.
  -r value
        Only keep items not in a file.
  -rm string
        Replacement mask for transformations if applicable. (default "uldsb")
  -t string
        Transformation to apply to input.
  -tf value
        Read additional files for transformations if applicable.
  -u value
        Read additional URLs for input.
  -v    Show verbose output when possible.

The '-f', '-k', '-r', '-tf', and '-u' flags can be used multiple times.
```

## Transformations:
```
  -t append
  -t append-remove
  -t append-shift
  -t prepend
  -t prepend-remove
  -t prepend-shift
  -t insert -i [index]
  -t overwrite -i [index]
  -t toggle -i [index]
  -t encode
  -t mask -rm [uldsb] -v
  -t dehex
  -t hex
  -t remove -rm [uldsb] -v
  -t retain -rm [uldsb] -tf [file]
  -t match -tf [file]
  -t fuzzy-swap -tf [file]
  -t swap -tf [file]
```

Author: JakeWnuk

.dockerignore

@@ -0,0 +1,7 @@
+*.swp
+README.md
+Dockerfile
+.git
+.gitattributes
+.gitignore
+LICENSE

.gitignore

@@ -0,0 +1 @@
+*.swp

Dockerfile

@@ -0,0 +1,18 @@
+FROM golang:alpine as build-env
+RUN mkdir src/app
+WORKDIR /src/app
+ADD ./main.go .
+ADD ./go.mod .
+ADD ./go.sum .
+ADD ./pkg ./pkg
+RUN go build .
+
+FROM alpine
+RUN addgroup --gid 10001 --system nonroot \
+    && adduser  --uid 10000 --system --ingroup nonroot --home /home/nonroot nonroot; \
+    apk update; apk add --no-cache tini bind-tools
+
+COPY --from=build-env /src/app/ptt /sbin/ptt
+ENTRYPOINT ["/sbin/tini", "--", "/sbin/ptt"]
+WORKDIR /data
+USER nonroot

README.md

@@ -1,2 +1,113 @@
-# ptt
- password transformation tool
+ `ptt` or Password Transformation Tool is a multi-tool for working with files, URLs, and standard input for password cracking.
+
+## Features:
+- Transform input strings with various modes.
+- Creates `Hashcat` rules and masks from input strings.
+- Transforms input strings with a variety of functions for password cracking.
+- Accepts input from standard input, files, and URLs.
+- Works with multiple files and URLs for input and transformations.
+- All transformations support multibyte characters.
+
+```
+$ ptt -h
+Usage of Password Transformation Tool (ptt) version (0.0.0):
+
+ptt [options] [...]
+Accepts standard input and/or additonal arguments.
+
+Options:
+  -f value
+        Read additional files for input.
+  -i value
+        Starting index for transformations if applicable. Accepts ranges separated by '-'. (default 0)
+  -k value
+        Only keep items in a file.
+  -m int
+        Minimum numerical frequency to include in output.
+  -r value
+        Only keep items not in a file.
+  -rm string
+        Replacement mask for transformations if applicable. (default "uldsb")
+  -t string
+        Transformation to apply to input.
+  -tf value
+        Read additional files for transformations if applicable.
+  -u value
+        Read additional URLs for input.
+  -v    Show verbose output when possible.
+
+The '-f', '-k', '-r', '-tf', and '-u' flags can be used multiple times.
+
+Transformation Modes:
+  -t append
+        Transforms input into append rules.
+  -t append-remove
+        Transforms input into append-remove rules.
+  -t append-shift
+        Transforms input into append-shift rules.
+  -t prepend
+        Transforms input into prepend rules.
+  -t prepend-remove
+        Transforms input into prepend-remove rules.
+  -t prepend-shift
+        Transforms input into prepend-shift rules.
+  -t insert -i [index]
+        Transforms input into insert rules starting at index.
+  -t overwrite -i [index]
+        Transforms input into overwrite rules starting at index.
+  -t toggle -i [index]
+        Transforms input into toggle rules starting at index.
+  -t encode
+        Transforms input by URL, HTML, and Unicode escape encoding.
+  -t mask -rm [uldsb] -v
+        Transforms input by masking characters with provided mask.
+  -t dehex
+        Transforms input by decoding $HEX[...] formatted strings.
+  -t hex
+        Transforms input by encoding strings into $HEX[...] format.
+  -t remove -rm [uldsb] -v
+        Transforms input by removing characters with provided mask characters.
+  -t retain -rm [uldsb] -tf [file]
+        Transforms input by creating masks that still retain strings from file.
+  -t match -tf [file]
+        Transforms input by keeping only strings with matching masks from a mask file.
+  -t fuzzy-swap -tf [file]
+        Transforms input by swapping tokens with fuzzy matches from another file.
+  -t swap -tf [file]
+        Transforms input by swapping tokens with exact matches from a ':' separated file.
+```
+
+## Getting Started:
+
+>[!NOTE]
+> This tool is still in development and considered early access. Please report any issues, bugs, or feature requests to the GitHub repository.
+
+Documentation on usage and examples can be found in the `/docs` directory or on the repository here: [link](https://github.com/JakeWnuk/ptt/docs)
+
+## Install:
+
+### Source:
+Fast method with Go installed:
+```
+TODO
+```
+Slow method with Go installed:
+```
+git clone https://github.com/JakeWnuk/ptt && cd ptt && go build ./main.go && mv ./ptt ~/go/bin/ptt && ptt
+```
+
+### Docker:
+Pull the latest image from Docker Hub:
+```
+docker run -it -v ${PWD}:/data jwnuk/ptt
+``` 
+Build the Docker image from the Dockerfile:
+```
+git clone https://github.com/JakeWnuk/ptt && cd ptt && docker build -t ptt . && docker run -it -v ${PWD}:/data ptt
+```
+
+### Binary:
+Download the latest release from the GitHub repository:
+```
+TODO
+```

docs/USAGE.md

@@ -0,0 +1 @@
+TODO

go.mod

@@ -0,0 +1,5 @@
+module ptt
+
+go 1.22.0
+
+require golang.org/x/net v0.24.0

go.sum

@@ -0,0 +1,2 @@
+golang.org/x/net v0.24.0 h1:1PcaxkF854Fu3+lvBIx5SYn9wRlBzzcnHZSiaFFAb0w=
+golang.org/x/net v0.24.0/go.mod h1:2Q7sJY5mzlzWjKtYUEXSlBWCdyaioyXzRB2RtU8KVE8=

main.go

@@ -0,0 +1,123 @@
+// Package main controls the user interaction logic for the application
+package main
+
+import (
+	"bufio"
+	"flag"
+	"fmt"
+	"os"
+	"ptt/pkg/format"
+	"ptt/pkg/models"
+	"ptt/pkg/transform"
+	"ptt/pkg/utils"
+	"sync"
+)
+
+var version = "0.0.0"
+var wg sync.WaitGroup
+var mutex = &sync.Mutex{}
+var retain models.FileArgumentFlag
+var remove models.FileArgumentFlag
+var readFiles models.FileArgumentFlag
+var readURLs models.FileArgumentFlag
+var transformationFiles models.FileArgumentFlag
+var intRange models.IntRange
+var primaryMap map[string]int
+var err error
+
+func main() {
+	// Parse command line arguments
+	flag.Usage = func() {
+		fmt.Fprintf(os.Stderr, "Usage of Password Transformation Tool (ptt) version (%s):\n\n", version)
+		fmt.Fprintf(os.Stderr, "ptt [options] [...]\nAccepts standard input and/or additonal arguments.\n\n")
+		fmt.Fprintf(os.Stderr, "Options:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(os.Stderr, "\nThe '-f', '-k', '-r', '-tf', and '-u' flags can be used multiple times.\n")
+		fmt.Fprintf(os.Stderr, "\nTransformation Modes:\n")
+		fmt.Fprintf(os.Stderr, "  -t append\n\tTransforms input into append rules.\n")
+		fmt.Fprintf(os.Stderr, "  -t append-remove\n\tTransforms input into append-remove rules.\n")
+		fmt.Fprintf(os.Stderr, "  -t append-shift\n\tTransforms input into append-shift rules.\n")
+		fmt.Fprintf(os.Stderr, "  -t prepend\n\tTransforms input into prepend rules.\n")
+		fmt.Fprintf(os.Stderr, "  -t prepend-remove\n\tTransforms input into prepend-remove rules.\n")
+		fmt.Fprintf(os.Stderr, "  -t prepend-shift\n\tTransforms input into prepend-shift rules.\n")
+		fmt.Fprintf(os.Stderr, "  -t insert -i [index]\n\tTransforms input into insert rules starting at index.\n")
+		fmt.Fprintf(os.Stderr, "  -t overwrite -i [index]\n\tTransforms input into overwrite rules starting at index.\n")
+		fmt.Fprintf(os.Stderr, "  -t toggle -i [index]\n\tTransforms input into toggle rules starting at index.\n")
+		fmt.Fprintf(os.Stderr, "  -t encode\n\tTransforms input by URL, HTML, and Unicode escape encoding.\n")
+		fmt.Fprintf(os.Stderr, "  -t mask -rm [uldsb] -v\n\tTransforms input by masking characters with provided mask.\n")
+		fmt.Fprintf(os.Stderr, "  -t dehex\n\tTransforms input by decoding $HEX[...] formatted strings.\n")
+		fmt.Fprintf(os.Stderr, "  -t hex\n\tTransforms input by encoding strings into $HEX[...] format.\n")
+		fmt.Fprintf(os.Stderr, "  -t remove -rm [uldsb] -v\n\tTransforms input by removing characters with provided mask characters.\n")
+		fmt.Fprintf(os.Stderr, "  -t retain -rm [uldsb] -tf [file]\n\tTransforms input by creating masks that still retain strings from file.\n")
+		fmt.Fprintf(os.Stderr, "  -t match -tf [file]\n\tTransforms input by keeping only strings with matching masks from a mask file.\n")
+		fmt.Fprintf(os.Stderr, "  -t fuzzy-swap -tf [file]\n\tTransforms input by swapping tokens with fuzzy matches from another file.\n")
+		fmt.Fprintf(os.Stderr, "  -t swap -tf [file]\n\tTransforms input by swapping tokens with exact matches from a ':' separated file.\n")
+	}
+
+	// Define command line flags
+	verbose := flag.Bool("v", false, "Show verbose output when possible.")
+	minimum := flag.Int("m", 0, "Minimum numerical frequency to include in output.")
+	transformation := flag.String("t", "", "Transformation to apply to input.")
+	replacementMask := flag.String("rm", "uldsb", "Replacement mask for transformations if applicable.")
+	flag.Var(&retain, "k", "Only keep items in a file.")
+	flag.Var(&remove, "r", "Only keep items not in a file.")
+	flag.Var(&readFiles, "f", "Read additional files for input.")
+	flag.Var(&transformationFiles, "tf", "Read additional files for transformations if applicable.")
+	flag.Var(&intRange, "i", "Starting index for transformations if applicable. Accepts ranges separated by '-'. (default 0)")
+	flag.Var(&readURLs, "u", "Read additional URLs for input.")
+	flag.Parse()
+
+	// Parse any retain, remove, or transformation file arguments
+	fs := &models.RealFileSystem{}
+	retainMap := utils.ReadFilesToMap(fs, retain)
+	removeMap := utils.ReadFilesToMap(fs, remove)
+	readFilesMap := utils.ReadFilesToMap(fs, readFiles)
+	transformationFilesMap := utils.ReadFilesToMap(fs, transformationFiles)
+	readURLsMap, err := utils.ReadURLsToMap(readURLs)
+	if err != nil {
+		fmt.Println("Error reading URLs:", err)
+		return
+	}
+
+	// Read from stdin if provided
+	stat, _ := os.Stdin.Stat()
+	if (stat.Mode() & os.ModeCharDevice) == 0 {
+		primaryMap, err = utils.LoadStdinToMap(bufio.NewScanner(os.Stdin))
+		if err != nil {
+			fmt.Println("Error reading from stdin:", err)
+			return
+		}
+	}
+
+	// Combine stdin with any additional files
+	if len(primaryMap) == 0 && len(readFilesMap) == 0 && len(readURLsMap) == 0 {
+		flag.Usage()
+		return
+	} else if len(primaryMap) == 0 {
+		primaryMap = utils.CombineMaps(readFilesMap, readURLsMap)
+	} else {
+		primaryMap = utils.CombineMaps(primaryMap, readFilesMap, readURLsMap)
+	}
+
+	// Apply transformation if provided
+	if *transformation != "" {
+		primaryMap = transform.TransformationController(primaryMap, *transformation, intRange.Start, intRange.End, *verbose, *replacementMask, transformationFilesMap)
+	}
+
+	// Process retain and remove maps if provided
+	if len(retainMap) > 0 || len(removeMap) > 0 {
+		primaryMap, err = format.RetainRemove(primaryMap, retainMap, removeMap)
+		if err != nil {
+			fmt.Println("Error processing retain and remove flags:", err)
+			return
+		}
+	}
+
+	// Remove items under minimum frequency if provided
+	if *minimum > 0 {
+		primaryMap = format.RemoveMinimumFrequency(primaryMap, *minimum)
+	}
+
+	// Print output to stdout
+	format.PrintArrayToSTDOUT(primaryMap, *verbose)
+}