Thank you for your interest in contributing to Merlin. This document outlines some basic guidelines for submitting your contributions. This is a living document and it will be updated regularly as the project matures.

Getting Started

Go is slightly unique due to the way it imports packages. Simply forking Merlin and getting to work will result in problems due to imports. The proper way to work with a Go repository after forking it is:

  1. Grab Merlin into your GOPATH go get

  2. Rename the current origin remote to upstream git remote rename origin upstream

  3. Add your fork as origin git remote add origin<your user name>/merlin

An excellent blog post by Scott Mansfield can be found on his blog.


Commands executed against an agent should be logged in the agent log. The results of messages executed on an agent, to include errors and successes, should also be sent back to the server and logged in the agent’s log file. Command results can be sent back using the “CmdResults” message structure.

Commands only affecting the server should be entered into the server’s log file.

When adding a new feature, ensure the associated activities are also logged.

User Interface Messages

  • Informational messages are white and start with [i]

  • Warning and Error messages are red and start with [!]

  • Verbose messages (those that are not a warning or error) are yellow and start with [-]

  • Success messages are green and start with [+]

  • Informational messages are white and start with [i]

  • Debug messages are red and start with (in all caps) [DEBUG]. These messages go above verbose logging and are used to track down problems or print out raw data.

  • Messages should be left aligned and rest against the message type symbol

Agent Messages

Merlin Agents are designed to run on a compromised host during a penetration test. As such, the agent should never display any messages to user on standard out or standard error unless verbose messages are enable.

Pull Requests

  • Pull requests (PR) should be submitted to the dev branch

  • Be sure to pull down any changes from dev prior to creating a PR

  • All pull request will require a review and approval prior to being accepted and merged into dev

  • Ensure all code is free from spelling and grammatical errors

  • Ensure code passes golint

  • Ensure code compiles without errors

  • Ensure all errors are handled

  • Error checking should be done as soon as possible

  • Update the usage() function if applicable

  • Ensure log entries are created in the respective log files


Thank you to everyone that has contributed to Merlin. Your contributions help keep Merlin great and valuable. Merlin contributors can be viewed here.