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

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

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

關鍵詞：網(wǎng)絡安全;測試腳本;文檔;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 引言

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

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

2? Docstring編寫風格介紹

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

（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風格規(guī)范中的注釋規(guī)范所描述的注釋風格，詳細描述了模塊、函數(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風格，是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.

"""

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

3 Sphinx介紹

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

4 方法說明

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

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

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

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

大量網(wǎng)絡安全測試腳本由于文檔不完善，使用時甚至無法明確地知道應該傳入哪些參數(shù)及怎樣傳參，本文利用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） 使用適合測試腳本的字段列表

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

5 結束語

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

基金項目

國家互聯(lián)網(wǎng)應急中心青年科技基金項目（項目編號：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] 高曉偉，杜晶，王青.源代碼分析注釋的質(zhì)量評價框架[J].計算機系統(tǒng)應用，2015，24（10）：1-8.

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

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

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

[7] 黃袁，賈楠，周強，陳湘萍，熊英飛，羅笑南.融合結構與語義特征的代碼注釋決策支持方法[J].軟件學報，2018，29（8）：2226-2242.

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