基于Sphinx的安全测试脚本文档生成方案

刘岳　张海峰　张良　杨秉杰　边帅

摘   要：论文分析了网络安全工作中创建优质的网络安全测试脚本文档的必要性，对Docstring编写风格进行了介绍，并对Sphinx文档生成系统和reStructuredText标记语言进行了说明。同时，提出了一种基于Sphinx的网络安全测试脚本文档生成方案，利用Sphinx的第三方扩展、对内建注释工具的有效利用、对注释字段的针对性扩充，使生成注释文档更加清晰、规范，切合网络安全人员使用代码的实际需求，有效地提高了测试代码的可维护性和复用效率。

关键词：网络安全;测试脚本;文档;Sphinx

中图分类号：TP309          文献标识码：A

Method of network security test script documentation creation based on Sphinx

Liu Yue， Zhang Haifeng， Zhang Liang， Yang Bingjie， Bian Shuai

（National Internet Emergency Center， Henan Branch， Henan Zhengzhou 450003）

Abstract： In this paper， the necessity of a high quality network security test script documentation is analyzed. The documenting styles of Python's docstring are introduced， as well as the Sphinx documentation creation tool and the reStructuredText scripting language. A method of network security test script documentation creation based on Sphinx is proposed. This method makes use of third party extensions， making effective utilization of built-in documenting functionalities， and extending specific field lists， which effectively improves the clearness and normativity of documentation. This method fits in with the requirement of security testers in code processing， increasing the test script's maintainability and reuse efficiency.

Key words： network security; script; documentation; Sphinx

1 引言

文檔是软件产品的一部分，没有文档的软件就不能称之为完整的软件，软件文档的编制在软件开发工作中占有突出的地位。文档不仅能帮助开发人员了解自己的工作进度，方便自己和他人阅读和改进软件，还能够帮助项目的管理人员管理软件开发进程、提高软件开发的效率和质量、改进软件开发过程。一方面，文档使得开发者自身在维护软件时可以了解到软件开发时的思考方法和取舍考虑，便于对代码的调整和修改;另一方面，文档使得其他软件开发者便于理解代码编写者的想法和考虑，可提高对软件代码复用的准确度和效率。

网络安全测试脚本大多由Python写成，具有数量大、功能单元化、较为零乱、不系统的特征。当前的Python代码只有公开发布的成熟代码包才有系统的软件文档，而网络安全测试脚本中，大多只包含有简略的示意性文档，经常存在格式不统一、不规范、难于理解的问题，很多测试脚本甚至没有文档，严重阻碍了网络安全从业人员对于其他网络安全人员所编写测试脚本的复用。本文旨在提出一种适用于网络安全测试脚本的文档生成方法，使得文档更为标准化、规范化，便于对代码的理解和使用。

2  Docstring编写风格介绍

Python语言设置的注释功能为文档字符串，即Docstring，用于模块、函数、类、方法内的注释。文档字符串的编写主要有几种风格。

（1） Epytext：是开源跨平台的Python模块文档自动生成工具Epydoc使用的轻量级文本标记语言，来对文档字符串进行格式化处理，其风格类似于Javadoc，比较紧凑。

"""

Return the x intercept of the line M{y=m*x+b}.  The X{x intercept} of a line is the point at which it crosses the x axis （M{y=0}）.

This function can be used in conjuction with L{z_transform} to find an arbitrary function's zeros.

@type  m： number

@param m： The slope of the line.

@type  b： number

@param b： The y intercept of the line.  The X{y intercept} of a line is the point at which it crosses the y axis （M{x=0}）.

@rtype：   number

@return：  the x intercept of the line M{y=m*x+b}.

"""

（2）Google风格：是Google开源项目风格指南中的Python风格规范中的注释规范所描述的注释风格，详细描述了模块、函数、参数、返回值和异常等Python代码组成部分的注释方法。

"""

Retrieves rows pertaining to the given keys from the Table instance represented by big_table.

Args：

big_table： An open Bigtable Table instance.

keys： A sequence of strings representing the key of each table row

to fetch.

other_silly_variable： Another optional variable， that has a much

longer name than the other args， and which does nothing.

Returns：

A dict mapping keys to the corresponding table row data

fetched. Each row is represented as a tuple of strings. For

example：

{'Serak'： （'Rigel VII'， 'Preparer'），

'Zim'： （'Irk'， 'Invader'），

'Lrrr'： （'Omicron Persei 8'， 'Emperor'）}

If a key from the keys argument is missing from the dictionary，

then that row was not found in the table.

Raises：

IOError： An error occurred accessing the bigtable.Table object. """

（3）reST：即reStructuredText風格，是Sphinx文档生成工具使用的标记语言，是一种轻量级的文本标记语言，具有简单易读，所见即所得的特征。

"""

.. py：function：： send_message（sender， recipient， message_body， [priority=1]）

Send a message to a recipient

：param str sender： The person sending the message

：param str recipient： The recipient of the message

：param str message_body： The body of the message

：param priority： The priority of the message， can be a number 1-5

：type priority： integer or None

：return： the message id

：rtype： int

：raises ValueError： if the message_body exceeds 160 characters

：raises TypeError： if the message_body is not a basestring

"""

（4）Numpy风格：是Sphinx的numpydoc 扩展所使用的风格，用于NumPy、SciPy等Python包的注释，使用了reStructuredText标记语言的一部分功能，相对于生成文档，更加注重源注释的可读性。

"""

My numpydoc description of numpydoc format docstring.

Parameters

----------

var1 ： array_like

Array_like means all those objects -- lists， nested lists， etc. --

that can be converted to an array.  We can also refer to

variables like `var1`.

var2 ： int

The type above can either refer to an actual Python type

（e.g. ``int``）， or describe the type of the variable in more

detail， e.g. ``（N，） ndarray`` or ``array_like``.

Returns

-------

type

Explanation of anonymous return value of type ``type``.

Raises

------

BadException

Because you shouldn't have done that.

"""

经过比较，由于reST是Sphinx文档生成软件使用的风格，而Sphinx是Python官方网站上Python标准库文档使用的生成软件，该软件功能强大、扩展性好，生成的文档视觉上清晰明快，且由于一般的Python使用者已经习惯了Python标准库文档的阅读方式，故本文采用reST风格的Docstring以及Sphinx作为安全测试脚本文档生成工具。

3 Sphinx介绍

Sphinx文档生成工具从一开始就是为了Python文档的生成而创建，并可以支持多种编程语言。Sphinx支持多种文档格式的输出，如Html、LaTeX、ePub等，支持多种插件进行功能的扩展。在Python语言中，Sphinx可以自动地把Docstring转换为文档。Sphinx使用reStructuredText作为标记语言，其使用的标记元素分两种：指令（Directives）和角色（Role）。指令是块级元素，像段落一样使用;角色是行内元素，可以写在普通文本之中。Sphinx系统本身在支持指令和角色之外，还支持字段列表（Field Lists）和域（Domains），字段列表用于支持多种注释字段，而域是一组指令和角色的集合，这些指令和角色相互关联，共同构成了适用于某个领域的特征。Sphinx生成的Python标准库的文档如图1所示。

4 方法说明

为使利用Sphinx生成更加适合于网络安全测试脚本的文档，本文基于测试脚本的应用特征，对Sphinx进行了功能扩展和使用方式改进，使得生成的文档相对于Python标准库文档，更加适合网络安全测试的应用环境，具体包括几个方面。

1） 使用HTTP Domain描述Payload提交信息

由于很大一部分网络安全测试是针对Web服务器的漏洞或者各类Cms系统漏洞的测试，这些测试脚本的关键代码是在进行Payload的提交，查看返回内容。所以，在文档中更加清楚地描述出Payload提交的情况，可使阅读文档的开发人员更快地抓住代码的核心。本文在Sphinx系统中添加HTTP Domain第三方扩展域，HTTP Domain包含了大量适合描述HTTP API的指令和角色，如编辑以下Docstring代码段：

.. http：post：： /php/admin_login.php

The posts tagged with `tag` that the user （`user_id`） wrote.

**Example request**：

.. sourcecode：： http

POST /php/admin_login.php HTTP/1.1

Host： example.com

：query admin_id： the id of administrator

：query admin_pass： the password of administrator

：reqheader User-Agent： Mozilla/5.0 （Macintosh; U; Intel Mac OS X 10_6_8; en-us） AppleWebKit/534.50 （KHTML， like Gecko） Version/5.1 Safari/534.50

：resheader Content-Type： this depends on ：mailheader：`Accept` header of request

：response characteristic： "81dc9bdb52d04dc20036dbd8313ed05" in response

：statuscode 200： no error

：statuscode 404： there's no user

生成的注釋文档如图2所示。

利用HTTP Domain中已包含的Sourcecode指令和Query、Reqheader、Resheader、Statuscode内建字段以及自行添加的Response Characteristic字段，可以清楚地描述出测试请求提交的请求体参数、请求头参数、返回头参数、返回内容特征以及返回值。

2） 使用Option指令描述脚本调用参数

大量网络安全测试脚本由于文档不完善，使用时甚至无法明确地知道应该传入哪些参数及怎样传参，本文利用Standard Domain中的Option指令以及Sourcecode指令，可清晰地描述脚本文件的使用方式，便于测试脚本的使用。例如，通过Docstring代码段生成的注释结果如图3所示。

.. code-block：： python

python example.py -i 202.102.245.69 -dest_dir tmp/source -user admin -pwd Dnjdfe -cookie 432d98a83b83290

.. option：： -dest_dir

Destination directory.

.. option：： -i

target ip address.

.. option：： -user

user account name on the target machine.

.. option：： -pwd

account passwd on the target machine.

.. option：： -cookie

effective cookie provided.

3） 使用适合测试脚本的字段列表

为使注释能清楚表述测试脚本的各类元数据信息，本文在注释中添加适合测试脚本的字段列表，这些字段包括目标系统名称、目标系统版本、运行平台、漏洞编号，目标系统类型、威胁类型、其他参考信息等。其中的运行平台可能包括操作系统平台，也可能是插入到某网络安全测试平台运行，如Metasploit、Pocsuite等，目标系统类型可能包括数据库、Web、APP等，威胁类型可能包括DDoS、信息泄露、SQL注入等，如图4所示。

5 结束语

本文提出了一个基于Sphinx的网络安全测试脚本文档生成方案，该方案利用Sphinx系统和reStructuredText标记语言，综合运用Sphinx的第三方扩展和系统内建的注释工具，生成的注释文档更加清晰、规范，更加适合网络安全测试脚本的使用场景，便于使用脚本的网络安全人员查找适当的测试脚本、了解正确的传参使用方式以及明确测试代码数据提交等核心代码，可明显提高测试代码的复用效率，也便于脚本编写者对脚本的维护。

基金项目

国家互联网应急中心青年科技基金项目（项目编号：2018Q20）。

参考文献

[1] Steidl D，Hummel B，Juergens E. Quality analysis of source code comments[J]. 2013 IEEE 21st International Conference on Program Comprehension （ICPC）. 2013.

[2] Khamis N，Witte R，Rilling J. Automatic quality assessment of source code comments：the Javadoc Miner[C]. Natural Language Processing and Information Systems. 2010.

[3] 高曉伟，杜晶，王青.源代码分析注释的质量评价框架[J].计算机系统应用，2015，24（10）：1-8.

[4] 陈琪，葛志松，许骏龙.软件文档质量评价方法研究[J].电脑知识与技术，2018，14（30）：60-61+69.

[5] 沈力，刘洪星，李勇华.基于版本控制的中文文档到代码跟踪方法[J/OL].计算机应用：1-6[2019-02-27].

[6] 霍福华.强化计算机软件文档质量监督的探讨[J].河北软件职业技术学院学报，2018，20（1）：7-9.

[7] 黄袁，贾楠，周强，陈湘萍，熊英飞，罗笑南.融合结构与语义特征的代码注释决策支持方法[J].软件学报，2018，29（8）：2226-2242.

[8] 余海，李斌，王培霞，贾荻，王永吉.基于组合分类算法的源代码注释质量评估方法[J].计算机应用，2016，36（12）：3448-3453+3467.

[9] Fluri B， Wursch M， Gall HC. Do code and comments co–evolve？On the relation between source code and comment changes[C]. 14th Working Conference on Reverse Engineering， WCRE 2007.IEEE. 2007：70-79.