Proxmark3 客户端命令行解析规范:Cliparser 集成指南与源码级实现解析

原创2026-09-16 12:39:031,652 阅读
文章标签:网络安全渗透测试嵌入式硬件开发物联网CLI逆向工程

Proxmark3 客户端命令行解析规范:Cliparser 集成指南与源码级实现解析

导读

本文档基于仓库 doc/cliparser.md,系统讲解 Proxmark3(Iceman Fork)客户端如何通过 cliparser 库统一命令行解析与帮助文本格式。文章完整覆盖从历史背景、设计原则、通用选项规范,到 CLIParserInit / argtable 选项表 / CLIExecWithReturn / CLIParserFree / 各类取值宏的完整接入流程,并结合 client/deps/cliparser/cliparser.c 与 client/deps/cliparser/cliparser.h 的源码实现,以及 cmdlfindala.c、cmdhf.c 的真实命令范例,讲透“如何为新命令接入标准 CLI 解析”。读完本文,你可以直接在 Proxmark3 client 中为自己的命令写出风格统一、支持 -h --help、具备彩色帮助文本的参数解析代码。

一、为什么需要 Cliparser:历史背景与统一动机

Proxmark3 客户端在很长一段时间里,各命令的参数解析方式是“各行其是”的混合式自定义解析。文档中列举了典型的混乱样例:

data xxxx h
script run x.lua -h
hf 14a raw -h
hf 14b raw -ss
lf search 1
lf config h H

甚至连收纳进仓库 tools/ 目录的外部工具也各自实现了独立的参数解析。这种风格不统一、帮助文本格式各异、参数含义模糊的状态,正是推动变革的根源。

在官方仓库的讨论(issue #467)中,社区明确了需要统一 CLI 解析的结论,并最终采纳了 @merlokk 提出的基于 argtable3 的 cliparser 库方案。该库被适配并首先应用在 emv、hf fido 等命令上;随后经过 @doegox、@iceman1001、@mrwalker 的多次讨论,cliparser 在 Proxmark3 客户端中的“推荐用法”被明确下来,并沉淀为本文档。其后 @mrwalker 负责整理笔记,形成了当前 doc/cliparser.md 这份规范。

核心结论:cliparser 是当前 Proxmark3 客户端新增命令时推荐(preferred)的 CLI 解析实现方式,同时适用于客户端命令与外部工具。解析器会自动完成格式排版、颜色输出,并自动追加 -h --help 选项,无需手工实现。

从源码结构看,cliparser 作为依赖被收纳在 client/deps/cliparser/ 目录下,其构建接入见 client/deps/cliparser.cmake,客户端大量命令源文件(cmd*.c、cmdlf*.c 等)均通过 #include "cliparser.h" 使用它。

二、设计原则(design comments)

在编写新命令的 CLI 时,应遵循以下设计约定:

  • 选项名尽量全小写(where possible all options should be lowercase)。
  • 长选项(-- 前缀)应保持简短。
  • 避免无选项标识符、直接摆放的参数(即位置参数),尽量都通过具名选项传递。
  • 不要使用 -vv 这类表示“额外详细”的堆叠短选项,需要更详细输出时优先使用调试级别(debug level)。
  • 使用 -- 长选项时不需要等号,cmd --cn 12345 与 cmd --cn=12345 均可解析,但规范建议不要写 =。

三、通用选项规范(common options)

为了让所有命令的交互习惯一致,cliparser 约定了一组跨命令通用的选项(短选项 / 长选项 / 含义):

选项 含义
-h --help 显示帮助
--cn 卡号(card number)
--fn 机构号(facility number)
--q5 目标为 LF T5555/Q5 卡
--em 目标为 LF EM4305/4469 卡
--raw 原始数据
-d --data 提供的十六进制数据
-f --file 提供的文件名
-k --key 提供的密钥
-n --keyno 使用的密钥编号
-p --pwd 提供的密码
-v --verbose 输出更多信息的标志位(不属于 debug)
-1 --buffer 使用采样缓冲区(sample buffer)

新增命令时应优先复用这些语义,避免“同名不同义”。

四、源码接入步骤:从零实现一个 Cliparser 命令

4.1 引入头文件并定义解析器上下文

在命令函数的源文件中包含头文件:

#include "cliparser.h"

在命令函数内部声明上下文指针:

CLIParserContext *ctx;

CLIParserContext 的定义位于 cliparser.h,内部保存 argtable 指针、长度、程序名(programName)、提示语(programHint)、帮助/示例文本(programHelp)以及一块 MAX_INPUT_ARG_LENGTH + 60 的解析缓冲区 buf。

4.2 定义并初始化上下文

CLIParserInit(&ctx, "lf indala clone",
              "clone INDALA UID to T55x7 or Q5/T5555 tag",
              "lf indala clone --heden 888\n"
              "lf indala clone --fc 123 --cn 1337\n"
              "lf indala clone -r a0000000a0002021\n"
              "lf indala clone -l -r 80000001b23523a6c2e31eba3cbee4afb3c6ad1fcf649393928c14e5");

CLIParserInit(ctx, programName, programHint, programHelp) 的三个文本参数含义如下:

  • programName:命令名称,会显示在 usage: 行并作为解析时的 argv[0]。
  • programHint:命令的一句话描述,显示在帮助文本顶部(青色)。
  • programHelp:示例与备注。用 \n 分隔多个示例,用 -> 分隔“示例”与“示例注释”。例如 lf indala clone -r a0000000a0002021 -> this uses raw bytes。渲染时示例默认列宽约 30(超长自动加宽),注释紧跟其后。

从源码看,CLIParserInit(cliparser.c)负责为上下文分配内存并保存三个文本指针。注意:文档中该示例文本在真实仓库 cmdlfindala.c 中已演进为包含警告提示(_RED_("\nWarning, encoding with FC/CN doesn't always work"))与 --4041x 示例的版本,说明 programHelp 中可以自由嵌入颜色宏,渲染时会被拆分换行输出。

4.3 定义选项表(argtable)

void *argtable[] = {
    arg_param_begin,
    arg_lit0("l", "long", "optional - long UID 224 bits"),
    arg_int0("c", "heden", "<decimal>", "Cardnumber for Heden 2L format"),
    arg_str0("r", "raw", "<hex>", "raw bytes"),
    arg_lit0("q", "Q5", "optional - specify writing to Q5/T5555 tag"),
    arg_int0(NULL, "fc", "<decimal>", "Facility Code (26 bit format)"),
    arg_int0(NULL, "cn", "<decimal>", "Cardnumber (26 bit format)"),
    arg_param_end
};

索引规则:因为 -h --help 由 arg_param_begin 宏自动添加,它固定占用 index 0,因此你自行添加的每个选项从 index 1 开始依次编号,取值时按此索引访问。arg_param_begin 与 arg_param_end 在 cliparser.h 中定义为:

#define arg_param_begin arg_lit0("h", "help", "This help")
#define arg_param_end   arg_end(20)

即自动注入 -h/--help 布尔选项,并以可容纳 20 条错误信息的 arg_end(20) 收尾。

4.4 选项类型速查表

所有选项宏的通用形态为 arg_<type><required?>("<short>", "<long>", "<format>", "<description>");某个选项没有短选项或长选项时,用 NULL 占位。完整清单如下:

类型 可选(0 结尾) 必填(1 结尾) 说明
bool arg_lit0("s","l","desc") — 布尔开关,提供即视为 true
int arg_int0("s","l","<format>","desc") arg_int1(...) 有符号整数
double arg_dbl0("s","l","<format>","desc") arg_dbl1(...) 双精度浮点
string(单实例) arg_str0("s","l","<format>","desc") arg_str1(...) 字符串,最多出现 1 次
string(多实例) arg_strx0("s","l","<format>","desc") arg_strx1(...) 字符串,最多 250 个实例;arg_strx1 至少需要 1 个
unsigned(u32/u64) arg_u64_0("s","l","<format>","desc") arg_u64_1(...) 无符号整数

其中多实例字符串宏 arg_strx0 / arg_strx1 定义于 cliparser.h,实际映射为 argtable3 的 arg_strn(short, long, datatype, 最小个数, 250, glossary)。

<format> 是展示给用户的取值说明(如 <decimal>、<hex>、<dec, ms>),会出现在帮助的选项描述里。

4.5 执行解析:CLIExecWithReturn

CLIExecWithReturn(ctx, Cmd, argtable, false);

CLIExecWithReturn(cliparser.h)是一个宏,展开后调用 CLIParserParseString:

if (CLIParserParseString((ctx), (cmd), (atbl), arg_getsize((atbl)), (ifempty))) {
    CLIParserFree((ctx));
    return PM3_ESOFT;
}

其行为包括:

  • 将用户输入的整行字符串按空格拆分成 argv(底层是 CLIParserParseStringEx 中的状态机解析,支持普通参数、- 开头的选项以及单双引号包裹的带空格值);
  • 解析成功返回 PM3_SUCCESS(0),随后继续执行;
  • 解析失败或用户输入 -h --help 时,自动打印帮助文本并释放上下文、返回 PM3_ESOFT,无需手工分支处理;
  • 第四个参数 allowEmptyExec 控制空命令行是否允许执行(例如 hf sniff 传 true,允许直接回车运行,见 cmdhf.c);
  • 若整行超过 MAX_INPUT_ARG_LENGTH(4096 字符)会报 ERROR: Line too long。

4.6 清理:CLIParserFree

从参数表中提取完所有需要的值之后,必须释放上下文:

CLIParserFree(ctx);

宏定义见 cliparser.h:调用 arg_freetable 释放 argtable 并 free(ctx),同时将指针置 NULL,避免悬垂指针。许多取值宏(如 CLIGetHexWithReturn)失败时也会自动执行清理并返回错误码。

4.7 获取选项值(retrieving options)

根据选项类型,使用对应的取值宏(参数为 (ctx, 选项索引) 或 (ctx, 选项索引, 默认值)):

bool 选项——arg_get_lit(ctx, 索引),提供则返回非 0:

bool is_long_uid = arg_get_lit(ctx, 1);

int 选项——arg_get_int_def(ctx, 索引, 默认值),未提供时返回默认值:

int cardnumber = arg_get_int_def(ctx, 2, -1);

uint32——arg_get_u32_def(ctx, 索引, 默认值):

uint32_t cardnumber = arg_get_u32_def(ctx, 2, 0);

uint64——arg_get_u64_def(ctx, 索引, 默认值):

uint64_t cardnumber = arg_get_u64_def(ctx, 2, 0);

这些宏在 cliparser.h 中均有定义:arg_get_int_def 通过先查 count 判断选项是否出现,出现则取 ival[0],否则返回传入的默认值;u32 实际复用 struct arg_u64,arg_get_u64_def 同理。另有 arg_get_dbl_def、arg_get_str、arg_get_str_len 等配套宏。

hex 选项(带返回值,失败即退出函数)——CLIGetHexWithReturn(ctx, 索引, 存储数组, 长度指针):

uint8_t aid[2] = {0};
int aidlen;
CLIGetHexWithReturn(ctx, 2, aid, &aidlen);

该宏(cliparser.h)内部调用 CLIParamHexToBuf,解析失败时打印错误并 CLIParserFree(ctx) 后 return PM3_ESOFT,即“失败自动退出当前命令”。因此调用后可以放心使用 aid/aidlen。

hex 选项(手动转换)——CLIParamHexToBuf(arg_get_str(ctx, 索引), 目标数组, 最大长度, 长度指针):

uint8_t key[24] = {0};
int keylen = 0;
int res_klen = CLIParamHexToBuf(arg_get_str(ctx, 3), key, 24, &keylen);

返回 0 表示转换成功(返回值为错误码而非实际长度,实际长度在 keylen 中)。

string 选项(带返回值,失败即退出函数)——CLIGetStrWithReturn(ctx, 索引, uint8_t*, int*):

uint8_t buffer[100] = {0};
int slen = sizeof(buffer) - 1;  // 必须是希望返回的最大字符数,例如 Buffer Size - 1(需要 null 结尾时)
CLIGetStrWithReturn(ctx, 1, buffer, &slen);

注意:slen 传入的是“最大可返回字符数”,返回后被更新为实际长度。若要求结果以 \0 结尾,务必传入 缓冲区大小 - 1。

string 选项(手动转换,获取 char 数组)——CLIParamStrToBuf:

int slen = 0;
char format[16] = {0};
int res = CLIParamStrToBuf(arg_get_str(ctx, 1), (uint8_t *)format, sizeof(format), &slen);
// res == 0 表示成功;slen 为实际写入的字符数

五、源码级原理深入

5.1 帮助文本的排版与颜色

CLIParserPrintHelp(cliparser.c)统一负责帮助文本渲染:

  • usage: 行使用命令名 + arg_print_syntax 打印语法;
  • options: 部分通过 arg_print_glossary 按 " %-30s %s\n" 对齐,即选项列固定 30 字符宽,保证描述列对齐;
  • examples/notes: 部分将 programHelp 按 \n 切行,用 -> 拆分示例与注释,示例列宽默认 30、超长自动加宽到示例长度 + 5;
  • 颜色通过 _GREEN_、_YELLOW_、_RED_、_CYAN_ 宏实现(定义于客户端 util/ui 头文件),分别用于区块标签、示例、命令名与描述。这些颜色宏同样可以直接嵌入 CLIParserInit 的提示/帮助文本中(如 cmdlfindala.c 的红色警告)。

5.2 字符串解析状态机

CLIParserParseStringEx(cliparser.c)把命令整行拆分为 argv:

  • 自动把 programName 作为 argv[0];
  • 通过 PS_FIRST / PS_ARGUMENT / PS_OPTION / PS_QUOTE 四种状态区分普通参数、- 开头选项与引号包裹内容;
  • 支持 ' 与 " 引号,引号内的空格不会拆词;
  • 超出 4096 字符的输入报 ERROR: Line too long 并拒绝解析。

5.3 字符串 / HEX / BIN 转换器

  • CLIParamStrToBuf(cliparser.c):拼接多实例字符串(最多 250 个),并支持 ~ 家目录展开(expand_tilde_path,读取 HOME/USERPROFILE 环境变量),带长度上限检查;
  • CLIParamHexToBuf(cliparser.c):HEX 字符串转字节数组,错误码 1=无效 HEX、2=参数过长、3=HEX 位数必须为偶数;
  • CLIParamBinToBuf(cliparser.c):二进制字符串转字节数组;
  • arg_get_u64_hexstr_def 等(cliparser.c):支持“HEX 字符串按固定字节长度解析为 u64/u32”并带默认值回退,返回值 1=成功、2=长度不符用默认值、3=可选参数未提供用默认值。

5.4 枚举选项列表:CLIGetOptionList

对于取值来自固定枚举的命令参数(例如 hf sniff 的跳过模式 --smode [none|drop|min|max|avg]),cliparser 提供 CLIParserOption 数组与 CLIGetOptionList:

const CLIParserOption HFSnoopSkipModeOpts[] = {
    {HF_SNOOP_SKIP_NONE, "none"},
    {HF_SNOOP_SKIP_DROP, "drop"},
    {HF_SNOOP_SKIP_MAX,  "min"},
    {HF_SNOOP_SKIP_MIN,  "max"},
    {HF_SNOOP_SKIP_AVG,  "avg"},
    {0, NULL},   // 末尾必须以 {0, NULL} 结束
};

int smode = 0;
if (CLIGetOptionList(arg_get_str(ctx, 3), HFSnoopSkipModeOpts, &smode)) {
    CLIParserFree(ctx);
    return PM3_EINVARG;
}

对应真实代码见 cmdhf.c。CLIGetOptionList(cliparser.c)先将输入转小写,再对 CLIParserOption 数组做精确匹配优先、前缀部分匹配兜底:无任何相似项返回错误码 20,多项相似返回 21。数组名要求小写(见 cliparser.h),最长支持 CLI_MAX_OPTLIST_LEN(50)项;CLIGetOptionListStr 反向把 code 映射回文本,便于回显。

六、完整实战范例:lf indala clone

文档中的示例正是仓库里真实存在的 CmdIndalaClone(cmdlfindala.c),其接入流程如下:

static int CmdIndalaClone(const char *Cmd) {
    CLIParserContext *ctx;
    CLIParserInit(&ctx, "lf indala clone",
                  "clone Indala UID to T55x7 or Q5/T5555 tag using different known formats\n"
                  _RED_("\nWarning, encoding with FC/CN doesn't always work"),
                  "lf indala clone --heden 888\n"
                  "lf indala clone --fc 123 --cn 1337\n"
                  "lf indala clone --fc 123 --cn 1337 --4041x\n"
                  "lf indala clone -r a0000000a0002021\n"
                  "lf indala clone -r 80000001b23523a6c2e31eba3cbee4afb3c6ad1fcf649393928c14e5");

    void *argtable[] = {
        arg_param_begin,
        arg_str0("r", "raw", "<hex>", "raw bytes"),
        arg_int0(NULL, "heden", "<decimal>", "Card number for Heden 2L format"),
        arg_int0(NULL, "fc", "<decimal>", "Facility code (26 bit H10301 format)"),
        arg_int0(NULL, "cn", "<decimal>", "Card number (26 bit H10301 format)"),
        arg_lit0(NULL, "q5", "Optional - specify writing to Q5/T5555 tag"),
        arg_lit0(NULL, "em", "Optional - specify writing to EM4305/4469 tag"),
        arg_lit0(NULL, "4041x", "Optional - specify Indala 4041X format, must use with fc and cn"),
        arg_param_end
    };
    CLIExecWithReturn(ctx, Cmd, argtable, false);

    // raw 参数:HEX 字符串转字节数组(失败自动返回)
    int raw_len = 0;
    uint8_t raw[(7 * 4) + 1];
    CLIGetHexWithReturn(ctx, 1, raw, &raw_len);

    bool is_long_uid = (raw_len == 28);   // 224 bit UID
    bool q5 = arg_get_lit(ctx, 5);
    bool em = arg_get_lit(ctx, 6);
    bool fmt4041x = arg_get_lit(ctx, 7);

    int32_t cardnumber;
    uint8_t fc = 0;
    uint16_t cn = 0;
    bool got_cn = false, got_26 = false;

    if (is_long_uid == false) {
        cardnumber = arg_get_int_def(ctx, 2, -1);   // Heden 参数
        got_cn = (cardnumber != -1);
        fc = arg_get_int_def(ctx, 3, 0);            // 26 bit FC/CN 参数
        cn = arg_get_int_def(ctx, 4, 0);
        got_26 = (fc != 0 && cn != 0);
    }
    CLIParserFree(ctx);
    ...
}

该范例可以清晰看到完整的“五步走”:CLIParserInit → 定义 argtable → CLIExecWithReturn → 取值(CLIGetHexWithReturn + arg_get_lit + arg_get_int_def)→ CLIParserFree。同时它演示了:

  • 只提供长选项(NULL 短选项占位)的写法,如 --fc、--cn、--q5、--em、--4041x;
  • 通过 arg_get_int_def(ctx, n, -1) 的默认值技巧判断“用户是否提供了某个整数选项”;
  • 结合布尔开关 q5/em 做写入目标(T55x7 / Q5 / EM4305)的分支选择,并在取值后进行参数合法性校验(Q5 与 EM 互斥、--4041x 必须配合 fc/cn 等)。

七、总结

cliparser 为 Proxmark3 客户端带来了统一的命令行体验:一致的 -h --help、对齐且带颜色的帮助文本、规范的短/长选项约定,以及可复用的字符串/HEX/BIN 转换与枚举列表匹配能力。新增命令时,只需按“CLIParserInit → argtable 选项表 → CLIExecWithReturn → 取值宏 → CLIParserFree”的固定模式接入即可,既避免了历史代码中参差不齐的自定义解析,也让用户与开发者都能快速上手任意命令。深入阅读 cliparser.c 与 cliparser.h 可进一步理解状态机拆分、帮助渲染与各类转换器的细节;更多真实用法可参考客户端 client/src/ 下大量使用 cliparser 的命令源文件。

登录后查看全文
proxmark3