Today, I’m taking on a small yet significant project: cleaning up and improving one of my older repositories on GitHub. It’s a Java bruteforcer I coded about three years ago.

I documented the whole process on YouTube. There, you can see me execute all the steps described below. YouTube refactoring thumbnail

Of course it can’t compete with popular bruteforcers such as hashcat, the password recovery tool that ships with Kali Linux. But it works well anyways. In fact, I managed to use the library to crack encrypted .zip files.

While the code still works well, the repository itself is not in a presentable state. It lacks proper documentation, has a poor directory structure, and doesn’t follow standard project conventions. My goal for today is to make the project more user and developer-friendly, following common conventions.

The Current State of the Repository

Here’s my goal for today:

  • Clean up the repository structure.
  • Add a README file.
  • Refactor the project to use [Apache Maven] for better management.

I’m working on a completely fresh virtual machine, so I’ll be configuring everything from scratch. If you’re following along, you’ll see the full process of setting up a development environment, installing dependencies, and organizing the project.

Setting Up the Development Environment

The first step is installing a few applications to make the environment more comfortable for development. Since I’m working on a new virtual machine, I had to adjust my keyboard settings (I use a German layout) and customize the terminal to fit my preferences.

Next, I installed Vim and Git, which are crucial for navigating and editing files. I also needed to set up Java, as this is a Java-based project.

sudo apt install vim git openjdk-11-jdk tmux

With Java set up, I created a new directory for the project, cloned the GitHub repository, and explored the existing file structure using find. The current project consists of only a few Java files and a password dictionary, so there’s not much to sift through at this point.

What does the Java bruteforcer do?

Before diving into the cleanup, here’s a brief overview of the project. The Java brute-forcer is designed to guess passwords using three different methods:

  1. Pure brute force: It tries every possible combination of characters starting from 0000, 0001, and so on. This method guarantees finding the password, but it can take an extremely long time, depending on the complexity.

  2. Dictionary attack: It uses a predefined list of common passwords, attempting each one. The dictionary file I’m using has 10 million common passwords, which makes it faster than brute force for most cases.

  3. Advanced dictionary attack: This method enhances the dictionary attack by appending special characters, numbers, or changing letter cases. It has a higher chance of success in a relatively short time.

Refactoring with Maven

The project has no build tools at the moment, so the next logical step is to migrate it to Maven. Maven will help manage dependencies and provide a standardized structure. While setting up Maven can be a bit tricky, it’s well worth the effort, especially for future maintenance.

I created a new directory for the Maven project and initialized it using a basic archetype:

mvn archetype:generate -DgroupId=com.example -DartifactId=java-brute-forcer -DarchetypeArtifactId=maven-archetype-quickstart

Maven automatically creates a standard directory layout, which looks like this:

src
 └── main
     └── java
         └── com
             └── example
                 └── App.java

I moved the existing source files into the appropriate directories and deleted the unnecessary files generated by Maven. To generate an executable jar file, I added a plugin, and specified the path of the main method.

In-code refactoring with vim

Browsing the code, two things bug me. First, I am not happy with the package naming space.crack. Rather, I would like a SEO-friendly name. When someone searches for a Java bruteforcer, they should find my repository. I think hirschdaniel.javaBruteforcer is a much better name.

Using :vimgrep I jumped to all occurrences (using :cn) of space.crack. Then using c3w (literally “change 3 words”: “space”, “.”, and “crack”), I replaced the occurrence of space.crack with the new hirschdaniel.javaBruteforcer.

My favorite thing about vim is that you can repeat the last search using n. And you can repeat the last action (in this case renaming 3 words) with .. This makes replacements very fast. Of course, I could’ve just globally replaced all occurrences, but I wanted to see what I replace beforehand.

Of course, I adapted the directory structure accordingly, e.g.

src
 └── main
     └── java
         └── hirschdaniel
             └── javaBruteforcer
                 └── Main.java

Creating a proper README File

While Maven was pulling dependencies and setting up the project, I took the opportunity to write a README.md file. Here’s a simplified version of the README I added:

# Java Brute-Forcer

A Java-based brute forcing tool that supports three distinct methods:

1. **Pure Brute Force**: Tries all possible character combinations.
2. **Dictionary Attack**: Tries all entries from a dictionary file.
3. **Advanced Dictionary Attack**: Enhances the dictionary attack by manipulating entries (e.g., changing case, appending special characters).

## Example Usage
This tool supports multiple character sets for brute force attacks. You can define your own character sets or use the predefined ones. An example dictionary file is also included, containing 10 million common passwords.

Finalizing and Publishing the Project

After this journey, I managed to complete the refactoring, renaming, and re-organizing of my Java Brute Forcer project. It’s now neatly mavenized, and all the main components are clearly structured. You can easily clone, compile, and run the project yourself, and even adapt it to your own use cases. Here’s a quick recap of what we accomplished:

  1. Directory Restructuring: We cleaned up the directory structure, moved the dictionary file into the resources folder, and aligned the Maven setup.

  2. Refactoring and Renaming: The project was renamed to reflect a more descriptive and personal style, from space.crack to hirschdaniel.javaBruteforcer. The internal references were all adjusted accordingly using Vim, as well as replacing the author details with my name.

  3. Maven Configuration: We dealt with issues related to the manifest attribute in the jar file and made sure the correct main class was assigned. A Maven plugin was added to handle this automatically during the build process.

  4. Multithreading and Brute Forcing: The core functionality of the project, which is brute-forcing hashes (such as, but not limited to, SHA-256) was kept intact but enhanced with multithreading to improve speed. The project now runs three concurrent threads to explore different key combinations in parallel.

  5. Writing the README: We created a comprehensive README.md that outlines the three attack methods.

  6. Usage Example: We added a sample usage section along with a screenshot of the tool in action to help users get started quickly.

Result:

Before and after mavenization of the bruteforcer

Next Steps

This version of the project is a significant step towards a cleaner, more professional release. However, there are still a few ideas I’d like to explore in future iterations:

  • Optimization: The brute-forcing speed can be improved further by optimizing at the JVM and machine level.
  • Additional Features: Adding more customizable parameters to fine-tune the brute-forcing process, such as the number of threads or advanced manipulation rules.

For now, the repository is live on GitHub, and anyone can clone it to experiment. It’s always exciting to see where simple projects like this can evolve over time.

If you’re interested in how I work, I suggest taking a look at my Vim setup and how I use terminal-based tools instead of IDEs. I’ve shared my favorite resources, including a highly recommended book on mastering Vim, on my resources page.

With the project now following Maven conventions and a README file in place, it’s much more approachable for future development. The brute-forcer itself remains unchanged, but the overall structure is now clean, and the setup process is easier to understand for anyone who wants to clone or contribute to the project.

That’s it for today. If you’re interested in checking out the repository or contributing, feel free to take a look on GitHub. I’ll continue improving it over time, but for now, it’s in a much better state than it was.