### CONTRIBUTING # Contributor's guide First of all, thank you for contributing! Please follow these steps to contribute: 1. Find an issue that needs assistance by searching for the [Help Wanted](https://github.com/epi052/feroxbuster/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) tag 2. Let us know you're working on it by posting a comment on the issue 3. Follow the [Contribution guidelines](#contribution-guidelines) to start working on the issue Remember to feel free to ask for help by leaving a comment within the Issue. Working on your first pull request? You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github). ###### If you've found a bug that is not on the board, [follow these steps](README.md#found-a-bug). --- ## Contribution guidelines - [Prerequisites](#prerequisites) - [Forking the project](#forking-the-project) - [Creating a branch](#creating-a-branch) - [Setting up for recon-pipeline development](#setting-up-for-recon-pipeline-development) - [Making changes](#making-changes) - [Static code analysis](#static-code-analysis) - [Running the test suite](#running-the-test-suite) - [Squashing your commits](#squashing-your-commits) - [Creating a pull request](#creating-a-pull-request) - [How we review and merge pull requests](#how-we-review-and-merge-pull-requests) - [Next steps](#next-steps) - [Other resources](#other-resources) - [Advice](#advice) ### Forking the project #### Setting up your system 1. Install your favorite `git` client 2. Create a parent projects directory on your system. For this guide, it will be assumed that it is `~/projects`. #### Forking feroxbuster 1. Go to the top-level feroxbuster repository: 2. Click the "Fork" button in the upper right hand corner of the interface ([more details here](https://help.github.com/articles/fork-a-repo/)) 3. After the repository has been forked, you will be taken to your copy of the feroxbuster repo at `your_username/feroxbuster` #### Cloning your fork 1. Open a terminal / command line / Bash shell in your projects directory (_e.g.: `~/projects/`_) 2. Clone your fork of feroxbuster, making sure to replace `your_username` with your GitHub username. This will download the entire feroxbuster repo to your projects directory. ```sh $ git clone https://github.com/your_username/feroxbuster.git ``` #### Set up your upstream 1. Change directory to the new feroxbuster directory (`cd feroxbuster`) 2. Add a remote to the official feroxbuster repo: ```sh $ git remote add upstream https://github.com/epi052/feroxbuster.git ``` Now you have a local copy of the feroxbuster repo! #### Maintaining your fork Now that you have a copy of your fork, there is work you will need to do to keep it current. ##### **Rebasing from upstream** Do this prior to every time you create a branch for a PR: 1. Make sure you are on the `main` branch > ```sh > $ git status > On branch main > Your branch is up-to-date with 'origin/main'. > ``` > If your aren't on `main`, resolve outstanding files and commits and checkout the `main` branch > ```sh > $ git checkout main > ``` 2. Do a pull with rebase against `upstream` > ```sh > $ git pull --rebase upstream main > ``` > This will pull down all of the changes to the official main branch, without making an additional commit in your local repo. 3. (_Optional_) Force push your updated main branch to your GitHub fork > ```sh > $ git push origin main --force > ``` > This will overwrite the main branch of your fork. ### Creating a branch Before you start working, you will need to create a separate branch specific to the issue or feature you're working on. You will push your work to this branch. #### Naming your branch Name the branch something like `23-xxx` where `xxx` is a short description of the changes or feature you are attempting to add and `23` corresponds to the Issue you're working on. #### Adding your branch To create a branch on your local machine (and switch to this branch): ```sh $ git checkout -b [name_of_your_new_branch] ``` and to push to GitHub: ```sh $ git push origin [name_of_your_new_branch] ``` ##### If you need more help with branching, take a look at _[this](https://github.com/Kunena/Kunena-Forum/wiki/Create-a-new-branch-with-git-and-manage-branches)_. ### Setting up for feroxbuster development For doing feroxbuster development, all you really need is `rust` installed on your system (I'll leave the choice of IDE to you, but VS Code and JetBrains both have very nice rust plugins). #### Install rustup The primary way that folks install Rust is through a tool called Rustup, which is a Rust installer and version management tool. ```sh curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh rustup update ``` After running the two commands above, you should be able to run `cargo`. ```shell script $> cargo --version cargo 1.45.0 (744bd1fbb 2020-06-15) ``` ### Making changes It's your time to shine! #### How to find code in the feroxbuster codebase to fix/edit The feroxbuster project directory structure is pretty simple and straightforward. All actual code for feroxbuster is located underneath the `src` directory. Integration tests are in the `tests` directory. There are various other files in the root directory, but these are primarily related to continuous integration and release deployment. ### Static code analysis feroxbuster uses the [`clippy`](https://rust-lang.github.io/rust-clippy/) code linter. The command that will ultimately be used in the CI pipeline for linting is `cargo clippy --all-targets --all-features -- -D warnings -A clippy::mutex-atomic`. Before submitting a Pull Request, the above command should be run. Please do not ignore any linting errors in code you write or modify, as they are meant to **help** by ensuring a clean and simple code base. ### Running the test suite When you're ready to share your code, run the test suite: ```sh $ cd ~/projects/feroxbuster $ cargo test ``` and ensure all tests pass. Test coverage can be checked using [grcov](https://github.com/mozilla/grcov). Installation and execution are summarized below. ```sh cargo install grcov rustup component add llvm-tools rustup install nightly rustup default nightly export CARGO_INCREMENTAL=0 export RUSTFLAGS="-Cinstrument-coverage -Clink-dead-code -Ccodegen-units=1 -Coverflow-checks=off" export LLVM_PROFILE_FILE="target/debug/coverage/profraw/feroxbuster-%p-%m.profraw" export RUSTDOCFLAGS="-Cpanic=abort" rm -r target/debug/coverage/profraw cargo build cargo test grcov . --source-dir . --keep-only "src/*" --binary-path ./target/debug/ -t html --branch --ignore-not-existing -o ./target/debug/coverage/ firefox target/debug/coverage/index.html ``` ### Squashing your commits When you make a pull request, it is preferable for all of your changes to be in one commit. Github has made it very simple to squash commits now as it's [available through the web interface](https://stackoverflow.com/a/43858707) at pull request submission time. ### Creating a pull request #### What is a pull request? A pull request (PR) is a method of submitting proposed changes to the feroxbuster repo (or any repo, for that matter). You will make changes to copies of the files which make up feroxbuster in a personal fork, then apply to have them accepted by the feroxbuster team. #### Need help? GitHub has a good guide on how to contribute to open source [here](https://opensource.guide/how-to-contribute/). ##### Editing via your local fork 1. Perform the maintenance step of rebasing `main` 2. Ensure you're on the `main` branch using `git status`: ```sh $ git status On branch main Your branch is up-to-date with 'origin/main'. nothing to commit, working directory clean ``` 1. If you're not on main or your working directory is not clean, resolve any outstanding files/commits and checkout main `git checkout main` 2. Create a branch off of `main` with git: `git checkout -B branch/name-here` 3. Edit your file(s) locally with the editor of your choice 4. Check your `git status` to see unstaged files 5. Add your edited files: `git add path/to/filename.ext` You can also do: `git add .` to add all unstaged files. Take care, though, because you can accidentally add files you don't want added. Review your `git status` first. 6. Commit your edits: `git commit -m "Brief description of commit"`. 7. Squash your commits, if there are more than one 8. Push your commits to your GitHub Fork: `git push -u origin branch/name-here` 9. Once the edits have been committed, you will be prompted to create a pull request on your fork's GitHub page 10. By default, all pull requests should be against the `main` branch 11. Submit a pull request from your branch to feroxbuster's `main` branch 12. The title (also called the subject) of your PR should be descriptive of your changes and succinctly indicate what is being fixed - Examples: `Add test cases for Unicode support`; `Correct typo in overview documentation` 13. In the body of your PR include a more detailed summary of the changes you made and why - If the PR is meant to fix an existing bug/issue, then, at the end of your PR's description, append the keyword `closes` and #xxxx (where xxxx is the issue number). Example: `closes #1337`. This tells GitHub to close the existing issue if the PR is merged. 14. Creating the PR causes our continuous integration (CI) systems to automatically run all of the unit tests on all supported OSes. You should watch your PR to make sure that all unit tests pass. 15. If any unit tests fail, you should look at the details and fix the failures. You can then push the fix to the same branch in your fork. The PR will automatically get updated and the CI system will automatically run all of the unit tests again. ### How we review and merge pull requests 1. If your changes can merge without conflicts and all unit tests pass, then your pull request (PR) will have a big green checkbox which says something like "All Checks Passed" next to it. If this is not the case, there will be a link you can click on to get details regarding what the problem is. It is your responsibility to make sure all unit tests are passing. Generally a Maintainer will not QA a pull request unless it can merge without conflicts and all unit tests pass. 2. If a Maintainer reviews a pull request and confirms that the new code does what it is supposed to do without seeming to introduce any new bugs, and doesn't present any backward compatibility issues, they will merge the pull request. ### Next steps #### If your PR is accepted Once your PR is accepted, you may delete the branch you created to submit it. This keeps your working fork clean. You can do this with a press of a button on the GitHub PR interface. You can delete the local copy of the branch with: `git branch -D branch/to-delete-name` #### If your PR is rejected Don't worry! You will receive solid feedback from the Maintainers as to why it was rejected and what changes are needed. Many pull requests, especially first pull requests, require correction or updating. If you have a local copy of the repo, you can make the requested changes and amend your commit with: `git commit --amend` This will update your existing commit. When you push it to your fork you will need to do a force push to overwrite your old commit: `git push --force` Be sure to post in the PR conversation that you have made the requested changes. ### Other resources - [Searching for your issue on GitHub](https://help.github.com/articles/searching-issues/) - [Creating a new GitHub issue](https://help.github.com/articles/creating-an-issue/) ### Advice Here is some advice regarding what makes a good pull request (PR) from our perspective: - Multiple smaller PRs divided by topic are better than a single large PR containing a bunch of unrelated changes - Good unit/functional tests are very important - Accurate documentation is also important - It's best to create a dedicated branch for a PR, use it only for that PR, and delete it once the PR has been merged - It's good if the branch name is related to the PR contents, even if it's just "fix123" or "add_more_tests" - Code coverage of the unit tests matters, so try not to decrease it - Think twice before adding dependencies to third-party libraries because it could affect a lot of users ## Acknowledgement Thanks to the awesome guys at [cmd2](https://github.com/python-cmd2/cmd2) for their fantastic `CONTRIBUTING` file from which we have borrowed heavily. --- ### README > [!WARNING] > **Security Notice – Domain Impersonation** > > The domain **feroxbuster.com** is **NOT affiliated** with this project, its maintainers, or any official feroxbuster releases. > > Official feroxbuster downloads are distributed **ONLY** through: > > - [https://github.com/epi052/feroxbuster](https://github.com/epi052/feroxbuster/releases) (open source) > - [https://www.feroxbuster.pro](https://www.feroxbuster.pro) (commercial) > - package repositories listed in this README > - package repositories listed in the [installation docs](https://epi052.github.io/feroxbuster-docs/installation/android/) > > We do **not** distribute software from feroxbuster.com, and we cannot vouch for the authenticity or safety of files hosted there. > If you downloaded feroxbuster from any other domain, we strongly recommend deleting it and reinstalling from an official source.


feroxbuster

A simple, fast, recursive content discovery tool written in Rust

github downloads

Releases  Example Usage  Contributing  Documentation  Pro

--- > [!TIP] > **Documentation has moved!** — Instead of having a 1300 line `README.md` (sorry...), feroxbuster's documentation has moved to GitHub Pages. The move to hosting documentation on Pages should make it a LOT easier to find the information you're looking for, whatever that may be. Please check it out for anything you need beyond a quick-start. > > **[View the full documentation →](https://epi052.github.io/feroxbuster-docs/overview)** ## What the heck is a ferox anyway? Ferox is short for Ferric Oxide. Ferric Oxide, simply put, is rust. The name rustbuster was taken, so I decided on a variation. ## What's it do tho? `feroxbuster` is a tool designed to perform [Forced Browsing](https://owasp.org/www-community/attacks/Forced_browsing). Forced browsing is an attack where the aim is to enumerate and access resources that are not referenced by the web application, but are still accessible by an attacker. `feroxbuster` uses brute force combined with a wordlist to search for unlinked content in target directories. These resources may store sensitive information about web applications and operational systems, such as source code, credentials, internal network addressing, etc... This attack is also known as Predictable Resource Location, File Enumeration, Directory Enumeration, and Resource Enumeration. ## Quick Start This section will cover the minimum amount of information to get up and running with feroxbuster. Please refer the the [documentation](https://epi052.github.io/feroxbuster-docs/overview/), as it's much more comprehensive. ### Installation There are quite a few other [installation methods](https://epi052.github.io/feroxbuster-docs/installation/android/), but these snippets should cover the majority of users. #### Kali If you're using kali, this is the preferred install method. Installing from the repos adds a [**ferox-config.toml**](https://epi052.github.io/feroxbuster-docs/configuration/ferox-config-toml/) in `/etc/feroxbuster/`, adds command completion for bash, fish, and zsh, includes a man page entry, and installs `feroxbuster` itself. ``` sudo apt update && sudo apt install -y feroxbuster ``` #### Linux (32 and 64-bit) & MacOS Install to a particular directory ``` curl -sL https://raw.githubusercontent.com/epi052/feroxbuster/main/install-nix.sh | bash -s $HOME/.local/bin ``` Install to current working directory ``` curl -sL https://raw.githubusercontent.com/epi052/feroxbuster/main/install-nix.sh | bash ``` #### MacOS via Homebrew ``` brew install feroxbuster ``` #### Windows x86_64 ``` Invoke-WebRequest https://github.com/epi052/feroxbuster/releases/latest/download/x86_64-windows-feroxbuster.exe.zip -OutFile feroxbuster.zip Expand-Archive .\feroxbuster.zip .\feroxbuster\feroxbuster.exe -V ``` #### Windows via Winget ``` winget install epi052.feroxbuster ``` #### Windows via Chocolatey ``` choco install feroxbuster ``` #### All others Please refer the the [documentation](https://epi052.github.io/feroxbuster-docs/overview). ### Updating feroxbuster (new in v2.9.1) ``` ./feroxbuster --update ``` ## Example Usage Here are a few brief examples to get you started. Please note, feroxbuster can do a **lot more** than what's listed below. As a result, there are **many more** examples, with **demonstration gifs** that highlight specific features, in the [documentation](https://epi052.github.io/feroxbuster-docs/overview). ### Multiple Values Options that take multiple values are very flexible. Consider the following ways of specifying extensions: ``` ./feroxbuster -u http://127.1 -x pdf -x js,html -x php txt json,docx ``` The command above adds .pdf, .js, .html, .php, .txt, .json, and .docx to each url All of the methods above (multiple flags, space separated, comma separated, etc...) are valid and interchangeable. The same goes for urls, headers, status codes, queries, and size filters. ### Include Headers ``` ./feroxbuster -u http://127.1 -H Accept:application/json "Authorization: Bearer {token}" ``` ### IPv6, non-recursive scan with INFO-level logging enabled ``` ./feroxbuster -u http://[::1] --no-recursion -vv ``` ### Read urls from STDIN; pipe only resulting urls out to another tool ``` cat targets | ./feroxbuster --stdin --silent -s 200 301 302 --redirects -x js | fff -s 200 -o js-files ``` ### Proxy traffic through Burp ``` ./feroxbuster -u http://127.1 --insecure --proxy http://127.0.0.1:8080 ``` ### Proxy traffic through a SOCKS proxy (including DNS lookups) ``` ./feroxbuster -u http://127.1 --proxy socks5h://127.0.0.1:9050 ``` ### Pass auth token via query parameter ``` ./feroxbuster -u http://127.1 --query token=0123456789ABCDEF ``` ### Set the Content-Type of the body automatically with --data-json --data-urlencoded ``` ./feroxbuster -u http://127.1 --data-json '{"some": "payload"}' ./feroxbuster -u http://127.1 --data-json @payload.json ./feroxbuster -u http://127.1 --data-urlencoded 'some=payload' ./feroxbuster -u http://127.1 --data-urlencoded @file.payload ``` > [!TIP] > For realsies, there used to be over 1300 lines in this README, but it's all been moved to the [new documentation site](https://epi052.github.io/feroxbuster-docs/overview). Go check it out! > > **[View the full documentation →](https://epi052.github.io/feroxbuster-docs/overview)** ## Contributors Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Joona Hoikkala
Joona Hoikkala
📖		 J Savage
J Savage
🚇 📖		 Thomas Gotwig
Thomas Gotwig
🚇 📖		 Spike
Spike
🚇 📖		 Evan Richter
Evan Richter
💻 📖		 AG
AG
🤔 📖		 Nicolas Thumann
Nicolas Thumann
💻 📖
Tom Matthews
Tom Matthews
📖		 bsysop
bsysop
📖		 Brian Sizemore
Brian Sizemore
💻		 Alexandre ZANNI
Alexandre ZANNI
🚇 📖		 Craig
Craig
🚇		 EONRaider
EONRaider
🚇		 wtwver
wtwver
🚇
Tib3rius
Tib3rius
🐛 🤔		 0xdf
0xdf
🐛		 secure-77
secure-77
🐛		 Sophie Brun
Sophie Brun
🚇		 black-A
black-A
🤔		 Nicolas Krassas
Nicolas Krassas
🤔		 N0ur5
N0ur5
🤔 🐛
mchill
mchill
🐛		 Naman
Naman
🐛		 Ayoub Elaich
Ayoub Elaich
🐛		 Henry
Henry
🐛		 SleepiPanda
SleepiPanda
🐛		 Bad Requests
Bad Requests
🐛		 Dominik Nakamura
Dominik Nakamura
🚇
Muhammad Ahsan
Muhammad Ahsan
🐛		 cortantief
cortantief
🐛 💻		 Daniel Saxton
Daniel Saxton
🤔 💻		 n0kovo
n0kovo
🤔 🐛		 Justin Steven
Justin Steven
🤔		 7047payloads
7047payloads
💻		 unkn0wnsyst3m
unkn0wnsyst3m
🤔
0x08
0x08
🤔		 kusok
kusok
🤔 💻		 godylockz
godylockz
🤔 💻		 Ryan Montgomery
Ryan Montgomery
🤔		 ippsec
ippsec
🤔		 James
James
🐛		 Jason Haddix
Jason Haddix
🤔 🐛
Limn0
Limn0
🐛		 0xdf
0xdf
🐛 🤔		 Flangyver
Flangyver
🤔		 PeakyBlinder
PeakyBlinder
🤔		 Postmodern
Postmodern
🤔		 O
O
💻		 John-John Tedro
John-John Tedro
💻
kmanc
kmanc
🐛 💻		 hakdogpinas
hakdogpinas
🤔		 多可悲
多可悲
🤔		 Aidan Hall
Aidan Hall
💻 🚇		 João Ciocca
João Ciocca
🐛 🤔		 f3rn0s
f3rn0s
🐛		 LongCat
LongCat
🤔
xaeroborg
xaeroborg
🤔		 Luoooio
Luoooio
🤔		 Aan
Aan
💻 🚇 🤔		 Simon
Simon
🐛		 Nicolas Christin
Nicolas Christin
🐛		 DrDv
DrDv
🐛		 Antoine Roly
Antoine Roly
🤔
Himadri Bhattacharjee
Himadri Bhattacharjee
💻 🤔		 Samy Lahfa
Samy Lahfa
🤔		 sectroyer
sectroyer
🐛 🤔		 ktecv2000
ktecv2000
🐛		 Andrea De Murtas
Andrea De Murtas
💻		 sawmj
sawmj
🐛		 Zach Hanson
Zach Hanson
🐛
Olivier Cervello
Olivier Cervello
🤔		 RavySena
RavySena
🤔		 Florian Stuhlmann
Florian Stuhlmann
🐛		 Mister7F
Mister7F
🤔		 manugramm
manugramm
🐛		 ArthurMuraro
ArthurMuraro
🐛		 Shadow
Shadow
🐛
dirhamgithub
dirhamgithub
🐛		 FieldOfRice
FieldOfRice
🚇		 Matt
Matt
🤔		 Sam Leonard
Sam Leonard
💻		 Rewinter
Rewinter
🤔		 deadloot
deadloot
🤔		 Spidle
Spidle
🤔
Julián Gómez
Julián Gómez
🤔 🚇 📖		 Petros
Petros
🐛		 Ryan
Ryan
🚇 📖		 wikamp-collaborator
wikamp-collaborator
🤔 🚇		 Lino
Lino
🐛 🤔		 Dan Salmon
Dan Salmon
🤔		 swordfish0x0
swordfish0x0
🤔
Patrick Klein
Patrick Klein
🤔		 Raymond
Raymond
🤔		 zer0x64
zer0x64
💻		 zar3bski
zar3bski
💻 🤔		 karanabe
karanabe
📖 💻		 h121h
h121h
🤔		 s0i37
s0i37
🤔
Wilco
Wilco
🐛		 HenriBom
HenriBom
🐛		 R̝͖̱͖͕̤̰̯͙ͫ͒̀ͮȁ̤͔̝̘̪̻͕̝̖ͧͪͤu̗̠̜̩̗͇͑̀ͣ̃͂̔͂c̫͔͚̲̬̓̂̿͌̿͊̐͗h͚̲̤̟͓̟̥̊ͬͪ̏̍̍ T̟̜̞͉͙̙ͣ́ͪ͗̓̇ͭo͍̰͎̼͓̟̽ͧ̓̉ͬ̐͐b͇̖̳̫̰̗̭͍ͧ̄̄̌̈i̙̪̤̝̟͓̹̋̽͋̀ͧ̒a͕̭̱͎̪̦̤ͤ͊̊̑ͣ̄s̪̯͖̰̯͍ͫ̋͑̄ͭͅͅ
R̝͖̱͖͕̤̰̯͙ͫ͒̀ͮȁ̤͔̝̘̪̻͕̝̖ͧͪͤu̗̠̜̩̗͇͑̀ͣ̃͂̔͂c̫͔͚̲̬̓̂̿͌̿͊̐͗h͚̲̤̟͓̟̥̊ͬͪ̏̍̍ T̟̜̞͉͙̙ͣ́ͪ͗̓̇ͭo͍̰͎̼͓̟̽ͧ̓̉ͬ̐͐b͇̖̳̫̰̗̭͍ͧ̄̄̌̈i̙̪̤̝̟͓̹̋̽͋̀ͧ̒a͕̭̱͎̪̦̤ͤ͊̊̑ͣ̄s̪̯͖̰̯͍ͫ̋͑̄ͭͅͅ
🐛 🤔 📖		 4FunAndProfit
4FunAndProfit
🤔		 lidorelias3
lidorelias3
🤔		 Adnan Ullah Khan (auk0x01)
Adnan Ullah Khan (auk0x01)
💻		 Martin Žember
Martin Žember
🐛
pg9051
pg9051
📖		 Sebastiaan Speck
Sebastiaan Speck
🐛 📖		 OpenSourceKyle
OpenSourceKyle
📖 🐛		 Antonio
Antonio
💻 🐛		 Redacean
Redacean
🐛		 ghsdpolley
ghsdpolley
🐛		 Daniel Aldam
Daniel Aldam
💻
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! ---