Pyre 之 Pysa Warning Codes 全解析:从 taint.config 规则到 5001 代码注入与 6065 命令行参数注入的实战指南
Pyre 之 Pysa Warning Codes 全解析:从 taint.config 规则到 5001 代码注入与 6065 命令行参数注入的实战指南
Pysa 是 Pyre(pyre-check)内置的污点分析(taint analysis)引擎,它跟踪数据从 sources(污染源)流向 sinks(汇聚点)的全过程,并为每一组"source 到 sink"的跟踪规则分配唯一的数字警告代码(warning code)。当 Pysa 发现一条危险数据流时,就会以该代码的形式输出安全问题(issue)。本文以 warning_codes 文档目录 为主线,系统讲解 warning code 的产生机制、以 taint.config(即 taint_config.json)为唯一真源的规则体系,并逐条剖析其中两个极具代表性的代码——**5001(代码注入 / 远程代码执行)**与 6065(命令行参数注入),结合仓库中真实的 .pysa 模型文件与配置,让读者既能理解告警语义,也能掌握从规则定义到模型标注再到修复落地的完整链路。
Warning Code 是什么:Pysa 数据流分析的"告警编码体系"
要理解 warning code,先要理解 Pysa 的工作原理。Pysa 是一个污点分析引擎,它把代码中的敏感数据抽象为两类端点:
- Sources(源头):污染数据产生的地方,例如用户的 HTTP 请求参数、Cookie、数据库查询返回结果等;
- Sinks(汇聚点):数据一旦到达就变得危险的位置,例如
eval、os.system、SQL 拼接、模板渲染等。
Pysa 在分析时跟踪从 source 到 sink 的数据流(taint flow),并为"我们要跟踪的每一组 sources 到 sinks"分配一个唯一代码。当发现一条 flow 时,Pysa 就会输出一条与该唯一代码关联的 issue。正如 warning_codes/overview.md 开篇所述:
Pysa tracks data flows from a set of sources to sinks. Each set of sources we track to sinks is assigned a unique code. When Pysa finds a flow, it emits issues associated with the unique code.
这意味着:同一种漏洞形态(如 SQL 注入)在不同 source 组合下会得到不同的代码。例如同样是 SQL 注入,UserControlled(用户可控数据)作为 source 时是 5005,而 DataFromInternet(来自网络的响应数据)作为 source 时则是 5305。代码的差异直接反映了"污染源的性质",方便安全团队按风险等级分流处理。
规则代码的唯一真源:taint.config(taint_config.json)
overview 文档还给出了一个关键事实:这些 warning code 的唯一真源(source of truth)是运行中使用的 taint.config 文件:
The source of truth for these warning codes is the
taint_config.jsonfiles used in a given run.
在 Pysa 的工程实践中,这个文件通常命名为 taint.config(即 JSON 文档)。仓库中的真实示例位于 stubs/taint/core_privacy_security/taint.config,它完整定义了 sources、sinks、features、transforms、rules 等核心概念:
sources:声明所有污染源类型,例如UserControlled(用户请求可控数据)、CLIUserControlled(命令行参数)、DataFromInternet(HTTP 响应数据)、ServerSecrets(服务端密钥)、AWSAccessKey/GoogleAPIKey(硬编码凭据)等;sinks:声明所有汇聚点类型,例如RemoteCodeExecution(可直接导致代码执行的输入点)、ExecArgSink(流入命令行参数的输入点)、SQL、XSS、FileSystem_ReadWrite等;rules:把 source 与 sink 组合成告警规则,并绑定唯一code、name与message_format;features/transforms:用于描述污点中途经过的变换(如shell_escape表示经过shlex.quote转义、FileOperation表示文件内容被读取),用于过滤误报或标记数据形态变化。
以规则 5001 为例,它在 stubs/taint/core_privacy_security/taint.config 中是这样定义的:
{
"code": 5001,
"message_format": "Data from [{$sources}] source(s) may reach [{$sinks}] sink(s)",
"name": "Possible shell injection",
"sinks": ["RemoteCodeExecution"],
"sources": ["UserControlled"]
}
即:当 UserControlled(用户可控数据)流入 RemoteCodeExecution(可执行代码/命令的汇聚点)时,触发代码 5001。同理,规则 6065 定义为 sources: ["UserControlled"]、sinks: ["ExecArgSink"],名称为 "Commandline arguments injection may result in RCE"。
值得一提的是,仓库中还存在一个"空规则"配置 stubs/taint/common/taint.config,其注释说明了另一层机制:
UserControlled, Test, Demo sources are predefined. Same for Demo, Test and RemoteCodeExecution sinks
即 UserControlled、Test、Demo 等 source 以及 Demo、Test、RemoteCodeExecution 等 sink 是预定义的,即使配置文件中不显式声明也可以直接使用。这解释了为什么 5001 文档 与 6065 文档 中描述的规则可以直接引用 UserControlled 与 RemoteCodeExecution。
注意:从文档表述看,运行时的配置文件被称为
taint_config.json;在仓库目录结构中,该文件实际以taint.config命名(JSON 内容)。两者指的是同一份"规则真源"。
5001:代码注入(Code Injection)——直达 RCE 的最高危告警
5001 文档 是 warning codes 目录中第一份详细的告警说明。其 TL;DR 直接给出了风险定性:
该类别表示用户控制的输入流入了允许代码或 shell 命令执行的 sink,这会直接导致远程代码执行(RCE),通常可以认为服务器已被完全攻陷。
5001 覆盖两条具体的数据流形态,下面分别结合源码模型说明。
RCE via Code Injection(eval / exec)
最简单的 RCE 形态是:用户输入流入 eval 或 exec 这类"解释并运行 Python 代码"的函数。
文档给出的脆弱代码示例(Django 视图风格):
def update_search_account_filtering(request: HttpRequest) -> HttpResponse:
...
if action in ["delete", "add", "update"]:
...
filter_by_username = eval(request.POST.get("filter_by_username", "True"))
request.POST.get("filter_by_username", "True") 是典型的 UserControlled 数据,而 eval 会将其当作 Python 代码执行——攻击者完全控制 filter_by_username 参数即等于完全控制服务器。
在仓库源码中,这条规则对应的模型定义位于 stubs/taint/core_privacy_security/rce_sinks.pysa:
# RCE sinks
if sys.version >= (3, 13, 0):
def eval(source: TaintSink[RemoteCodeExecution], /, globals, locals): ...
else:
def eval(source: TaintSink[RemoteCodeExecution], globals, locals, /): ...
if sys.version >= (3, 13, 0):
def exec(source: TaintSink[RemoteCodeExecution], /, globals, locals, *, closure): ...
elif sys.version >= (3, 11, 0):
def exec(source: TaintSink[RemoteCodeExecution], globals, locals, /, *, closure): ...
else:
def exec(source: TaintSink[RemoteCodeExecution], globals, locals, /): ...
可以看到:eval / exec 的第一个参数(source)被声明为 TaintSink[RemoteCodeExecution],且模型按 Python 版本(3.11、3.13)分别处理了参数位置差异。也就是说,只要任意数据流入这两个函数的第一参数,就会被标记为到达 RemoteCodeExecution 汇聚点,从而命中规则 5001。
文档给出的推荐修复方案是:
- 极少数场景才有必要使用
eval/exec,更不应该允许用户控制其内容,通常建议不要使用这些函数处理用户输入; - 如果只是求值 Python 数据类型,可以改用
ast.literal_eval——它对任意用户输入仍然可能造成拒绝服务(DOS)攻击,但无法被利用来实现代码执行。
RCE via Command Injection(os.system)
第二种形态是用户输入流入在系统 shell 中执行的命令。只要用户能控制命令的一部分,就可能追加任意命令执行。
文档给出的示例(对用户提供的文本运行 spellcheck 程序):
def spellcheck(request: HttpRequest):
command = f"/usr/bin/spellcheck -l {request.GET['text']}"
return os.system(command)
攻击者可以提交 'test' && rm -rf / 这样的路径,最终被 shell 执行的是:
/usr/bin/spellcheck -l 'test' && rm -rf /
由于命令在系统 shell 中执行,rm -rf / 会在 spellcheck 执行完毕后继续执行,造成灾难性后果。
对应的模型定义同样在 stubs/taint/core_privacy_security/rce_sinks.pysa 中:
def os.system(command: TaintSink[RemoteCodeExecution]): ...
os.system 的唯一参数被直接标为 RemoteCodeExecution sink——这完全符合文档描述:"用户输入流入在系统 shell 中执行的命令"。
5001 的推荐修复:优先使用语言级 API,切勿 shell=True
文档给出的修复原则非常明确:
一般来说,我们推荐避免创建子进程,优先使用语言本身提供的 API;如果必须创建子进程,推荐使用
subprocess.run这类可以把"可执行文件"与"参数"分离的 API。切记不要添加shell=True参数,否则代码仍然像前例一样脆弱。
安全版本示例:
def spellcheck(request: HttpRequest):
command = ["/usr/bin/spellcheck", "-l", request.GET['text']]
subprocess.run(command)
同时文档给出了一个重要提示:即便参数与可执行文件分离,可执行文件本身的某些参数仍可能引发代码执行(例如 find 的 -exec 参数),因此最终安全性还取决于被调用的程序。
6065:命令行参数注入(Commandline Arguments Injection)
6065 文档 描述的是与 5001 相邻但严重程度略低的另一类问题。其 TL;DR 写道:
该类别表示用户控制的输入流入了用于执行外部进程的命令行参数。与 5001 不同,它只在特定情况下导致 RCE(例如设置了
shell=True,或执行了某些特定二进制)。
为什么 subprocess 默认是安全的
文档指出:subprocess.Popen、subprocess.run、subprocess.call 等函数默认就能防止 5001 所描述的命令注入问题——args 参数中除第一个(代表可执行文件)之外的值只被当作参数,而不会被当作系统 shell 中解释的命令。但这一安全行为可以被 shell=True 手动绕过,从而重新引入命令注入问题。
脆弱代码示例:
def spellcheck(request: HttpRequest):
command = "/usr/bin/spellcheck -l {}".format(request.GET['text'])
return subprocess.run(command, shell=True)
攻击者同样可以提交 'test' && rm -rf /,由于 shell=True,命令会在系统 shell 中执行,效果与 5001 的 os.system 案例完全一致。
从源码看 6065 的检测机制:ExecArgSink 与 shell 标记
规则 6065 在 stubs/taint/core_privacy_security/taint.config 中的定义是:
{
"code": 6065,
"message_format": "Data from [{$sources}] source(s) may reach [{$sinks}] sink(s)",
"name": "Commandline arguments injection may result in RCE",
"sinks": ["ExecArgSink"],
"sources": ["UserControlled"]
}
而对应的 subprocess 系列模型定义于 stubs/taint/core_privacy_security/rce_sinks.pysa,这是理解 6065 检测精度的关键:
def subprocess.run(
args: TaintSink[ExecArgSink, ViaTypeOf[args], ViaValueOf[shell, WithTag["shell"]]],
executable: TaintSink[ExecArgSink],
cwd: TaintSink[ExecArgSink],
env: TaintSink[ExecEnvSink],
*,
input: TaintSink[ExecArgSink],
): ...
def subprocess.call(
args: TaintSink[ExecArgSink, ViaTypeOf[args], ViaValueOf[shell, WithTag["shell"]]],
...
): ...
def subprocess.Popen.__init__(
self,
args: TaintSink[ExecArgSink, ViaTypeOf[args], ViaValueOf[shell, WithTag["shell"]]],
...
): ...
逐项解读这个模型声明:
args: TaintSink[ExecArgSink, ...]:args参数(即命令行参数)被标为ExecArgSink,这正是规则 6065 的 sink——默认情况下,用户数据流入args就会触发 6065;ViaTypeOf[args]与ViaValueOf[shell, WithTag["shell"]]:分析器会同时检查args的类型与shell参数的具体取值,并为"通过shell=True传入"的流打上shell标签——这正是文档所说"通过指定shell=True手动绕过默认安全行为"的检测落地;env: TaintSink[ExecEnvSink]:环境变量参数对应规则 6064("Environment variable or import injection may result in RCE")中的ExecEnvSink;executable/cwd/input也被标记为ExecArgSink,保证各种注入面都被覆盖。
此外模型还把 subprocess.getstatusoutput、subprocess.getoutput 的参数直接标为 TaintSink[RemoteCodeExecution, ViaTypeOf[cmd]](见同一文件的第 108–110 行),因为它们本质上是字符串命令在 shell 中执行,与 os.system 同级,会命中规则 5001 而非 6065。
6065 的推荐修复
文档给出的修复方案:
一般推荐避免创建子进程,优先使用语言 API;如果必须创建子进程,推荐使用
subprocess.run这类安全 API 并避免shell=True。如果实在无法避免,则必须用shlex.quote对用户可控的值做 shell 转义。
安全版本示例:
def spellcheck(request: HttpRequest):
command = ["/usr/bin/spellcheck", "-l", request.GET['text']]
subprocess.run(command)
同样的附注依然适用:参数分离不等于绝对安全,可执行文件本身的参数(如 find -exec)仍可能引发代码执行。
值得注意的是,仓库的 features 定义中正好有 shell_escape("taint passed through a function producing a shell escaped string example shlex.quote",见 stubs/taint/core_privacy_security/taint.config),说明 Pysa 能够识别经过 shlex.quote 转义后的流并为其打上该 feature,用于后续的过滤与降噪。
围绕 RCE 的同类 Warning Codes 一览
结合 stubs/taint/core_privacy_security/taint.config 中真实的规则定义,以下代码与 5001 / 6065 同属"命令/代码执行"风险族系,可作为排查时的对照表:
| Code | 规则名称 | Sources | Sinks | 备注 |
|---|---|---|---|---|
| 5001 | Possible shell injection | UserControlled |
RemoteCodeExecution |
用户数据直达代码/命令执行点(eval、exec、os.system) |
| 5041 | Possible shell injection via command line arguments | CLIUserControlled |
RemoteCodeExecution |
命令行参数作为 source 的 shell 注入 |
| 5301 | Possible shell injection | DataFromInternet |
RemoteCodeExecution |
网络响应数据作为 source 的 shell 注入 |
| 6064 | Environment variable or import injection may result in RCE | UserControlled |
ExecEnvSink, ExecImportSink |
流入环境变量或 import 函数 |
| 5364 | Environment variable or import injection may result in RCE | DataFromInternet |
ExecEnvSink, ExecImportSink |
网络响应数据版本 |
| 6065 | Commandline arguments injection may result in RCE | UserControlled |
ExecArgSink |
用户数据流入 subprocess 命令行参数 |
| 5365 | Commandline arguments injection may result in RCE | DataFromInternet |
ExecArgSink |
网络响应数据版本 |
| 6066 | Unsafe deserialization may result in RCE | UserControlled |
ExecDeserializationSink |
反序列化(pickle / yaml.load 等),含 7 跳距离过滤 |
| 5366 | Unsafe deserialization may result in RCE | DataFromInternet |
ExecDeserializationSink |
网络响应数据版本,含 5 跳距离过滤 |
| 5067 | Unsafe UserControlled file handle before content deserialization may result in RCE | UserControlled |
FileContentDeserializationSink |
用户控制文件句柄后内容反序列化 |
| 5367 | External/Internet request response data controls file handle before content deserialization may result in RCE | DataFromInternet |
FileContentDeserializationSink |
网络响应数据版本 |
| 6809 | SQL query output flows into a RCE sink | SQLControlled |
RemoteCodeExecution |
数据库查询结果流入 RCE 点 |
从 5xxx 到 6xxx 的编号规律可以看出:5xxx 以 UserControlled 为主 source,6xxx 则细化了执行类 sink(ExecArgSink、ExecEnvSink、ExecDeserializationSink),而 53xx 系列代表 DataFromInternet(外部网络数据)作为污染源的同类问题。
模型文件如何"喂养"规则:更多真实 RCE 汇聚点
除了标准库,仓库还通过第三方模型把大量真实世界库的 API 标记为 RCE / 参数注入汇聚点。以 stubs/third_party_taint/rce_sinks.pysa 为例:
# paramiko module
def paramiko.proxy_command.ProxyCommand.__init__(self, command_line: TaintSink[RemoteCodeExecution]): ...
def paramiko.client.SSHClient.exec_command(
self,
command: TaintSink[RemoteCodeExecution],
): ...
# pexpect module
def pexpect.spawn.__init__(
self,
command: TaintSink[RemoteCodeExecution],
args: TaintSink[ExecArgSink],
): ...
def pexpect.spawn.sendline(self, s: TaintSink[RemoteCodeExecution]): ...
# jsonpickle library unsafe deserialization with RCE
def jsonpickle.decode(string: TaintSink[ExecDeserializationSink]): ...
def jsonpickle.loads(string: TaintSink[ExecDeserializationSink]): ...
# asyncssh module
async def asyncssh.connection.SSHClientConnection.create_process(
*args: TaintSink[RemoteCodeExecution],
input: TaintSink[ExecArgSink],
): ...
可以看到 paramiko(SSH 命令执行)、pexpect(交互式进程控制)、asyncssh(异步 SSH)等库的"命令执行"型 API 全部被标记为 RemoteCodeExecution sink,其 args/input 等参数则标记为 ExecArgSink——它们与 subprocess 一样会命中 5001 或 6065 族系规则。这意味着:即便业务代码没有直接用 os.system,只要用户数据流入这些库的命令执行 API,同样会得到告警。仓库中的集成测试目录 stubs/integration_test/test_taint 存放了对应规则的验证模型与配置文件,可用于理解这些告警的实际触发形态。
在工程中如何定位与处理这些告警
1. 确认规则来自哪份配置
warning code 的唯一真源是本次分析所加载的 taint.config(文档中写作 taint_config.json)。在 Pyre 工程中,模型与配置文件的位置由 .pyre_configuration 中的 taint_models_path 指定。客户端分析参数 taint_model_paths 也支持显式传入(见 client/commands/analyze.py 与 get_taint_models_path() 调用),仓库内预置配置可参考 stubs/taint/common/taint.config 与 stubs/taint/core_privacy_security/taint.config。
2. 根据代码分级响应
- 5001 类告警(
RemoteCodeExecutionsink):视为最高优先级,文档明确"可假设服务器完全沦陷",应立即修复:优先用语言级 API、用参数列表代替 shell 字符串、严禁shell=True、必要时用shlex.quote转义; - 6065 类告警(
ExecArgSinksink):默认形态下仅为"参数注入",但在shell=True或特定二进制(如find -exec)场景下会升级为 RCE,同样需要尽快修复; - 6066 / 5366 类告警(反序列化):pickle、
yaml.load等反序列化路径也可导致 RCE(相关模型见 stubs/taint/core_privacy_security/rce_sinks.pysa 中的pickle.loads、yaml.load定义),避免对不可信输入反序列化,或改用安全 Loader / 数据格式。
3. 关注 message_format 与距离过滤
所有规则统一使用 "Data from [{$sources}] source(s) may reach [{$sinks}] sink(s)" 作为消息模板(部分规则如 5027、5034 有定制文案)。部分规则带 filters.maximum_source_distance / maximum_sink_distance(例如 6066 为 7 跳、5366 为 5 跳),用于限制 source/sink 之间的传播距离,抑制长路径误报。理解这些过滤条件,有助于判断一条告警是"跨了很多跳的弱证据"还是"近距离强证据"。
小结
Warning codes 是 Pysa 把污点分析结论"翻译"给工程团队的通用语言:规则定义在 taint.config(taint_config.json)中,sources 与 sinks 的组合决定代码编号,.pysa 模型文件把真实 API(eval、exec、os.system、subprocess.*、paramiko、pexpect 等)挂接到这些 sink 上。本文详解的 **5001(代码注入,直达 RCE)**与 **6065(命令行参数注入,特定条件下升级 RCE)**是其中最具代表性的一对:前者强调"不要用用户输入拼 shell 字符串",后者强调"参数列表 + 绝不 shell=True"。掌握代码背后的配置与模型机制,就能在 Pyre / Pysa 的告警海洋中快速定位问题本质、评估风险等级并落地修复。