Pyre 之 Pysa Warning Codes 全解析:从 taint.config 规则到 5001 代码注入与 6065 命令行参数注入的实战指南

原创2026-09-28 20:16:531,880 阅读
文章标签:静态分析开发工具代码质量

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.json files 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 类告警(RemoteCodeExecution sink):视为最高优先级,文档明确"可假设服务器完全沦陷",应立即修复:优先用语言级 API、用参数列表代替 shell 字符串、严禁 shell=True、必要时用 shlex.quote 转义;
  • 6065 类告警(ExecArgSink sink):默认形态下仅为"参数注入",但在 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 的告警海洋中快速定位问题本质、评估风险等级并落地修复。

登录后查看全文
pyre-check