ByteArrayFromHex.md

自定义byte[]类型数据(Hex)（ByteArrayFromHex）

• 类别：custom　别名：—　优先级：200
• 作者：—
• 依赖：commons-codec:commons-codec（org.apache.commons.codec.binary.Hex，工具自带）

作用

把用户提供的一段十六进制（Hex）字符串解码为 byte[]，作为链的**数据源（最内层产物）**直接返回。与 ByteArrayFromBase64 功能对称，只是编码方式换成 Hex——适合承载以十六进制形式表达的原始字节（如内存中 dump 的序列化流、class 文件）。

链接标签

• 入口 tags：CustomBytePayload、END
  • CustomBytePayload —— 声明产出为「自定义字节负载」，被 UserCustomPayload（gadgetTags={"CustomBytePayload"}，mode = HTTP Server / TCP Server）收纳。
  • END —— 终结标签，表示这是链的叶子/源头，内部不再调用下一环。
• 衔接 nextTags：（空）—— 链尾数据源，后面不接 gadget。
• excludes：（空）

源码剖析

@GadgetTags(tags={"CustomBytePayload", "END"})
@GadgetAnnotation(name="自定义byte[]类型数据(Hex)", description="会自动对字符串进行Hex解码操作", priority=200)
public class ByteArrayFromHex implements Gadget {
    @Param(name="十六进制字符串", description="会通过该字符串进行Hex解码操作")
    public String hexString;

    public Object getObject() throws DecoderException {
        return Hex.decodeHex((String)this.hexString);            // 十六进制解码为 byte[]
    }

    @Override
    public Object invoke(GadgetContext context, GadgetChain chain) throws Exception {
        return this.getObject();                                  // 纯数据源，不 chain.doCreate
    }
}

关键点：

• invoke 同样不调用 chain.doCreate(context)，直接返回解码字节，符合 END 语义。
• Hex.decodeHex 来自 commons-codec，要求输入长度为偶数且仅含合法十六进制字符，否则抛出 DecoderException（源码 getObject 已在签名上声明该受检异常）。因此填入的 Hex 串不能带空格/换行/0x 前缀，需为紧凑的偶数长度串。
• 产物类型为 byte[]，消费方必须是接受原始字节的 UserCustomPayload。

参数（@Param）

字段	名称	说明	默认	可选值
hexString	十六进制字符串	会通过该字符串进行 Hex 解码，结果即最终 byte[] 负载；须为偶数长度、纯十六进制字符	无	任意合法 Hex 文本

适用版本与原理要点

• 与目标环境版本无关，属生成端的「离线数据封装」构件，只做一次 Hex 解码。
• description 明确「会自动对字符串进行Hex解码操作」；使用者仅需提供紧凑 Hex 串。
• 注意与 Base64 版的差异：Hex 无容错，格式不合法会直接 DecoderException；体积也比 Base64 大（每字节 2 个字符）。

所属预设链

自由构件，未直接出现在 51 条预设链中。面向 UserCustomPayload 的自定义数据生成场景。

关联

• 消费方 Payload：UserCustomPayload（CustomBytePayload → HTTP Server / TCP Server）。
• 同族（同产 byte[] 数据源）：ByteArrayFromBase64（Base64 编码，带容错）、ByteArrayFromUploadFile（从上传文件取 Base64）。
• 字符串版本：CustomString。