Fix pr1709

I closed #1709 prematurely when testing out some pull request landing techniques. @jhart-r7 and @jvazquez-r7 were both discussing changes to that module there.

This pull request implements most -- but not all -- of those changes, and also cleans up the title, desc, and method definitions.

Please take a look and continue fixing. Items I did not address explicitly are:

https://github.com/rapid7/metasploit-framework/pull/1709/files#L0R631 -- what happens when this returns `nil`?

https://github.com/rapid7/metasploit-framework/pull/1709/files#L0R190
https://github.com/rapid7/metasploit-framework/pull/1709/files#L0R179
https://github.com/rapid7/metasploit-framework/pull/1709/files#L0R141
https://github.com/rapid7/metasploit-framework/pull/1709/files#L0R138

@jvazquez-r7 or @jhart-r7 can you address those?

Sorry for the misfire. I'd rather just edit it after the fact than pull it out, though.