基于Sphinx的安全測試腳本文檔生成方案

劉岳　張海峰　張良　楊秉杰　邊帥

摘? ?要：論文分析了網(wǎng)絡(luò)安全工作中創(chuàng)建優(yōu)質(zhì)的網(wǎng)絡(luò)安全測試腳本文檔的必要性，對Docstring編寫風(fēng)格進(jìn)行了介紹，并對Sphinx文檔生成系統(tǒng)和reStructuredText標(biāo)記語言進(jìn)行了說明。同時(shí)，提出了一種基于Sphinx的網(wǎng)絡(luò)安全測試腳本文檔生成方案，利用Sphinx的第三方擴(kuò)展、對內(nèi)建注釋工具的有效利用、對注釋字段的針對性擴(kuò)充，使生成注釋文檔更加清晰、規(guī)范，切合網(wǎng)絡(luò)安全人員使用代碼的實(shí)際需求，有效地提高了測試代碼的可維護(hù)性和復(fù)用效率。

關(guān)鍵詞：網(wǎng)絡(luò)安全;測試腳本;文檔;Sphinx

中圖分類號：TP309? ? ? ? ? 文獻(xiàn)標(biāo)識碼：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 引言

文檔是軟件產(chǎn)品的一部分，沒有文檔的軟件就不能稱之為完整的軟件，軟件文檔的編制在軟件開發(fā)工作中占有突出的地位。文檔不僅能幫助開發(fā)人員了解自己的工作進(jìn)度，方便自己和他人閱讀和改進(jìn)軟件，還能夠幫助項(xiàng)目的管理人員管理軟件開發(fā)進(jìn)程、提高軟件開發(fā)的效率和質(zhì)量、改進(jìn)軟件開發(fā)過程。一方面，文檔使得開發(fā)者自身在維護(hù)軟件時(shí)可以了解到軟件開發(fā)時(shí)的思考方法和取舍考慮，便于對代碼的調(diào)整和修改;另一方面，文檔使得其他軟件開發(fā)者便于理解代碼編寫者的想法和考慮，可提高對軟件代碼復(fù)用的準(zhǔn)確度和效率。

網(wǎng)絡(luò)安全測試腳本大多由Python寫成，具有數(shù)量大、功能單元化、較為零亂、不系統(tǒng)的特征。當(dāng)前的Python代碼只有公開發(fā)布的成熟代碼包才有系統(tǒng)的軟件文檔，而網(wǎng)絡(luò)安全測試腳本中，大多只包含有簡略的示意性文檔，經(jīng)常存在格式不統(tǒng)一、不規(guī)范、難于理解的問題，很多測試腳本甚至沒有文檔，嚴(yán)重阻礙了網(wǎng)絡(luò)安全從業(yè)人員對于其他網(wǎng)絡(luò)安全人員所編寫測試腳本的復(fù)用。本文旨在提出一種適用于網(wǎng)絡(luò)安全測試腳本的文檔生成方法，使得文檔更為標(biāo)準(zhǔn)化、規(guī)范化，便于對代碼的理解和使用。

2? Docstring編寫風(fēng)格介紹

Python語言設(shè)置的注釋功能為文檔字符串，即Docstring，用于模塊、函數(shù)、類、方法內(nèi)的注釋。文檔字符串的編寫主要有幾種風(fēng)格。

（1） Epytext：是開源跨平臺的Python模塊文檔自動(dòng)生成工具Epydoc使用的輕量級文本標(biāo)記語言，來對文檔字符串進(jìn)行格式化處理，其風(fēng)格類似于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風(fēng)格：是Google開源項(xiàng)目風(fēng)格指南中的Python風(fēng)格規(guī)范中的注釋規(guī)范所描述的注釋風(fēng)格，詳細(xì)描述了模塊、函數(shù)、參數(shù)、返回值和異常等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風(fēng)格，是Sphinx文檔生成工具使用的標(biāo)記語言，是一種輕量級的文本標(biāo)記語言，具有簡單易讀，所見即所得的特征。

"""

.. 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風(fēng)格：是Sphinx的numpydoc 擴(kuò)展所使用的風(fēng)格，用于NumPy、SciPy等Python包的注釋，使用了reStructuredText標(biāo)記語言的一部分功能，相對于生成文檔，更加注重源注釋的可讀性。

"""

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.

"""

經(jīng)過比較，由于reST是Sphinx文檔生成軟件使用的風(fēng)格，而Sphinx是Python官方網(wǎng)站上Python標(biāo)準(zhǔn)庫文檔使用的生成軟件，該軟件功能強(qiáng)大、擴(kuò)展性好，生成的文檔視覺上清晰明快，且由于一般的Python使用者已經(jīng)習(xí)慣了Python標(biāo)準(zhǔn)庫文檔的閱讀方式，故本文采用reST風(fēng)格的Docstring以及Sphinx作為安全測試腳本文檔生成工具。

3 Sphinx介紹

Sphinx文檔生成工具從一開始就是為了Python文檔的生成而創(chuàng)建，并可以支持多種編程語言。Sphinx支持多種文檔格式的輸出，如Html、LaTeX、ePub等，支持多種插件進(jìn)行功能的擴(kuò)展。在Python語言中，Sphinx可以自動(dòng)地把Docstring轉(zhuǎn)換為文檔。Sphinx使用reStructuredText作為標(biāo)記語言，其使用的標(biāo)記元素分兩種：指令（Directives）和角色（Role）。指令是塊級元素，像段落一樣使用;角色是行內(nèi)元素，可以寫在普通文本之中。Sphinx系統(tǒng)本身在支持指令和角色之外，還支持字段列表（Field Lists）和域（Domains），字段列表用于支持多種注釋字段，而域是一組指令和角色的集合，這些指令和角色相互關(guān)聯(lián)，共同構(gòu)成了適用于某個(gè)領(lǐng)域的特征。Sphinx生成的Python標(biāo)準(zhǔn)庫的文檔如圖1所示。

4 方法說明

為使利用Sphinx生成更加適合于網(wǎng)絡(luò)安全測試腳本的文檔，本文基于測試腳本的應(yīng)用特征，對Sphinx進(jìn)行了功能擴(kuò)展和使用方式改進(jìn)，使得生成的文檔相對于Python標(biāo)準(zhǔn)庫文檔，更加適合網(wǎng)絡(luò)安全測試的應(yīng)用環(huán)境，具體包括幾個(gè)方面。

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

由于很大一部分網(wǎng)絡(luò)安全測試是針對Web服務(wù)器的漏洞或者各類Cms系統(tǒng)漏洞的測試，這些測試腳本的關(guān)鍵代碼是在進(jìn)行Payload的提交，查看返回內(nèi)容。所以，在文檔中更加清楚地描述出Payload提交的情況，可使閱讀文檔的開發(fā)人員更快地抓住代碼的核心。本文在Sphinx系統(tǒng)中添加HTTP Domain第三方擴(kuò)展域，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內(nèi)建字段以及自行添加的Response Characteristic字段，可以清楚地描述出測試請求提交的請求體參數(shù)、請求頭參數(shù)、返回頭參數(shù)、返回內(nèi)容特征以及返回值。

2） 使用Option指令描述腳本調(diào)用參數(shù)

大量網(wǎng)絡(luò)安全測試腳本由于文檔不完善，使用時(shí)甚至無法明確地知道應(yīng)該傳入哪些參數(shù)及怎樣傳參，本文利用Standard Domain中的Option指令以及Sourcecode指令，可清晰地描述腳本文件的使用方式，便于測試腳本的使用。例如，通過Docstring代碼段生成的注釋結(jié)果如圖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） 使用適合測試腳本的字段列表

為使注釋能清楚表述測試腳本的各類元數(shù)據(jù)信息，本文在注釋中添加適合測試腳本的字段列表，這些字段包括目標(biāo)系統(tǒng)名稱、目標(biāo)系統(tǒng)版本、運(yùn)行平臺、漏洞編號，目標(biāo)系統(tǒng)類型、威脅類型、其他參考信息等。其中的運(yùn)行平臺可能包括操作系統(tǒng)平臺，也可能是插入到某網(wǎng)絡(luò)安全測試平臺運(yùn)行，如Metasploit、Pocsuite等，目標(biāo)系統(tǒng)類型可能包括數(shù)據(jù)庫、Web、APP等，威脅類型可能包括DDoS、信息泄露、SQL注入等，如圖4所示。

5 結(jié)束語

本文提出了一個(gè)基于Sphinx的網(wǎng)絡(luò)安全測試腳本文檔生成方案，該方案利用Sphinx系統(tǒng)和reStructuredText標(biāo)記語言，綜合運(yùn)用Sphinx的第三方擴(kuò)展和系統(tǒng)內(nèi)建的注釋工具，生成的注釋文檔更加清晰、規(guī)范，更加適合網(wǎng)絡(luò)安全測試腳本的使用場景，便于使用腳本的網(wǎng)絡(luò)安全人員查找適當(dāng)?shù)臏y試腳本、了解正確的傳參使用方式以及明確測試代碼數(shù)據(jù)提交等核心代碼，可明顯提高測試代碼的復(fù)用效率，也便于腳本編寫者對腳本的維護(hù)。

基金項(xiàng)目

國家互聯(lián)網(wǎng)應(yīng)急中心青年科技基金項(xiàng)目（項(xiàng)目編號：2018Q20）。

參考文獻(xiàn)

[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] 高曉偉，杜晶，王青.源代碼分析注釋的質(zhì)量評價(jià)框架[J].計(jì)算機(jī)系統(tǒng)應(yīng)用，2015，24（10）：1-8.

[4] 陳琪，葛志松，許駿龍.軟件文檔質(zhì)量評價(jià)方法研究[J].電腦知識與技術(shù)，2018，14（30）：60-61+69.

[5] 沈力，劉洪星，李勇華.基于版本控制的中文文檔到代碼跟蹤方法[J/OL].計(jì)算機(jī)應(yīng)用：1-6[2019-02-27].

[6] 霍福華.強(qiáng)化計(jì)算機(jī)軟件文檔質(zhì)量監(jiān)督的探討[J].河北軟件職業(yè)技術(shù)學(xué)院學(xué)報(bào)，2018，20（1）：7-9.

[7] 黃袁，賈楠，周強(qiáng)，陳湘萍，熊英飛，羅笑南.融合結(jié)構(gòu)與語義特征的代碼注釋決策支持方法[J].軟件學(xué)報(bào)，2018，29（8）：2226-2242.

[8] 余海，李斌，王培霞，賈荻，王永吉.基于組合分類算法的源代碼注釋質(zhì)量評估方法[J].計(jì)算機(jī)應(yīng)用，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.