Instead of embedding static Java serialized objects, Metasploit offers ysoserial-generated binaries with built-in randomization. The benefits of using the Metasploit library include quicker module development, easier-to-read code, and future-proof Java serialized objects.
To use the ysoserial libraries, let's look at an example from the [`hp_imc_java_deserialization`](https://github.com/rapid7/metasploit-framework/blob/master/modules/exploits/windows/http/hp_imc_java_deserialize.rb) module:
In this example, the module calls `cmd_psh_payload` to generate a PowerShell payload, then uses the `ysoserial` library to generate a `JSON1`-based serialized object, before sending it through an HTTP POST request:
In line 3, the module uses the `ysoserial_payload` function, passing the name of the template and the command to be embedded within the template. The function returns a Java serialized object, which can then be passed to the vulnerable application.
### Calling `ysoserial_payload`
The function takes two parameters, a template name and a command:
- The name parameter must be one of the support payloads stored in the `ysoserial` cache. As of this writing, the list includes: `BeanShelll1`, `Clogure`, `CommonBeanutils1`, `CommonsCollections2`, `CommonsCollections3`, `CommonsCollections4`, `CommonsCollections5`, `CommonsCollections6`, `Groovy1`, `Hibernate1`, `JBossInterceptors1`, `JRMPClient`, `JSON1`, `JavassistWeld1`, `Jdk7u21`, `MozillaRhino1`, `Myfaces1`, `ROME`, `Spring1`, `Spring2`, and `Vaadin1`. While `ysoserial` includes 8 other templates that are not listed above, these 8 payloads are unsupported by the library due to the need for complex inputs. Should there be use cases for those 8 templates, please consider opening an issue and submitting a pull request to add support.
- The command parameter will be executed by the remote system. The parameter is OS-agnostic, meaning that the module must determine the OS and architecture, if necessary, before generating a payload.
### Regenerating the ysoserial_payload JSON file (MAINTAINERS ONLY)
**Neither module developers nor users need to concern themselves with the following.**
To avoid invoking Java (and all its dependencies) at runtime, the serialized objects are generated and cached within a JSON file. The JSON file can be refreshed using a standalone Ruby script, which comes prepackaged with a Docker image that handles downloading `ysoserial` and necessary dependencies. The script, `Dockerimage` and a high-level `runme.sh` script is stored within `tools/payloads/ysoserial`. An example run looks like:
At completion, the `data/ysoserial_payloads.json` file is overwritten and the 22 dynamic payloads are ready for use within the framework. Afterward, the developer should follow the standard `git` procedures to `add` and `commit` the new JSON file before generating a pull request and landing the updated JSON into the framework's `master` branch.
