Scapy development

Project organization

Scapy开发使用Git版本控制系统. Scapy的参考资料库位于https://github.com/secdev/scapy/ .

项目管理由Github完成. 它提供了一个可免费编辑的Wiki (请贡献!),它可以引用项目中的票证,变更集和文件. 它还提供了票务管理服务,该服务用于避免忘记补丁或错误.

How to contribute

Improve the documentation

可以通过以下几种方式改进文档:

  • Adding docstrings to the source code.

  • 在文档中添加用法示例.

Adding Docstrings

Scapy源代码几乎没有解释函数的功能. 通过添加说明以及预期的输入和输出参数,文档字符串有助于为图层开发人员和寻求高级功能的用户节省时间.

scapy.fields.FlagsField类中的docstring示例:

class FlagsField(BitField):
  """ Handle Flag type field

   Make sure all your flags have a label

   Example:
       >>> from scapy.packet import Packet
       >>> class FlagsTest(Packet):
               fields_desc = [FlagsField("flags", 0, 8, ["f0", "f1", "f2", "f3", "f4", "f5", "f6", "f7"])]
       >>> FlagsTest(flags=9).show2()
       ###[ FlagsTest ]###
         flags     = f0+f3
       >>> FlagsTest(flags=0).show2().strip()
       ###[ FlagsTest ]###
         flags     =

   :param name: field's name
   :param default: default value for the field
   :param size: number of bits in the field
   :param names: (list or dict) label for each flag, Least Significant Bit tag's name is written first
   """

它将包含对该类的简短的单行描述,然后是有关其用法的一些指示. 如果可以使用doctest格式,可以添加一个用法示例. 最后,可以在sphinx文档之后添加经典的python签名.

该任务与编写非回归单元测试配合使用.

Documentation

改善文档内容的一种方法是使其与最新版本的Scapy保持同步. 您还可以通过添加自己的用法示例或直接从现有的在线Scapy演示文稿收集的用法示例来提供帮助.

Testing with UTScapy

What is UTScapy?

UTScapy是一个小型Python程序,可读取测试活动,使用Scapy运行活动并生成指示测试状态的报告. 该报告可以采用以下四种格式之一:文本,ansi,HTML或LaTeX.

UTScapy具有三个基本的测试容器,一个单元测试,一个测试集和一个测试活动. 单元测试是将由Scapy或Scapy的衍生作品运行的Scapy命令列表. 评估单元测试中的最后一条命令将确定单个单元测试的最终结果. 测试集是一组具有某种关联的单元测试. 一个测试活动包含一个或多个测试集. 可以给测试集和单元测试关键字以形成逻辑分组. 进行广告活动时,可以通过关键字选择测试. 这使用户可以在所需的分组中运行测试.

对于每个单元测试,测试集和活动,都会计算该测试的CRC32并显示为该测试的签名. 该测试签名足以确定实际的测试运行是预期的,而不是已修改的. 如果您与试图在不更改CRC32的情况下修改或破坏文件的邪恶人打交道,则会对整个文件计算一个全局SHA1.

Syntax of a Test Campaign

表1显示了UTScapy正在寻找的语法指示符. 语法说明符必须作为定义测试的文本文件的每一行的第一个字符出现. 语法说明符后面的文本描述是UTScapy解释的参数. 如果出现的行没有单元格语法,则这些行将被视为Python命令. UTScapy将拒绝没有出现在正确上下文之外的语法说明符的行,并发出警告.

语法说明符

Definition

‘%’

输入测试活动的名称.

‘+’

宣布一个新的测试仪.

‘=’

宣布新的单元测试.

‘~’

宣布当前单元测试的关键字.

‘*’

表示将包含在报告中的评论.

‘#’

解释器丢弃的测试用例注释.

表1-UTScapy语法说明符

测试报告中的注释具有上下文. 每个注释都将与最后定义的测试容器相关联-无论是单个单元测试,测试集还是测试活动. 与特定容器关联的多个注释将串联在一起,并在测试容器公告后立即出现在报告中. 测试文件的一般注释应在宣布测试活动之前出现. 为了使注释与测试活动相关联,它们必须出现在测试活动的声明之后但在任何测试集或单元测试之前. 测试集的注释应该出现在测试集的第一个单元测试的定义之前.

下表显示了测试广告系列的通用格式:

% Test Campaign Name
* Comment describing this campaign


+ Test Set 1
* comments for test set 1

= Unit Test 1
~ keywords
* Comments for unit test 1
# Python statements follow
a = 1
print a
a == 1

缺少定义的UTScapy语法说明符来标识Python语句. Python语句直接馈入Python解释器,就好像在交互式Scapy shell( interact )中进行操作一样. 允许循环,迭代和条件,但必须以空白行终止. 一个测试集可以包括多个单元测试,并且可以为每个活动定义多个测试集. 甚至可以在一个特定的测试定义文件中进行多个测试活动. 使用关键字可以测试整个广告系列的子集. 例如,在开发测试活动期间,用户可能希望用关键字" debug"标记正在开发中的新测试. 一旦测试成功运行至期望的结论,就可以删除关键字" debug". 也可以使用诸如"回归"或"受限"之类的关键字.

重要的是要注意,UTScapy使用最后一条Python语句中的true值作为测试是否通过的指标. 在最后一行可能会出现多个逻辑测试. 如果结果为0或False,则测试失败. 否则,测试通过. 如果需要,使用assert()语句可以强制评估中间值.

表3-UTScapy命令行语法显示了UTScapy的语法:

[root@localhost scapy]# ./UTscapy.py –h
Usage: UTscapy [-m module] [-f {text|ansi|HTML|LaTeX}] [-o output_file]
               [-t testfile] [-k keywords [-k ...]] [-K keywords [-K ...]]
               [-l] [-d|-D] [-F] [-q[q]]
-l              : generate local files
-F              : expand only failed tests
-d              : dump campaign
-D              : dump campaign and stop
-C              : don't calculate CRC and SHA
-q              : quiet mode
-qq             : [silent mode]
-n <testnum>    : only tests whose numbers are given (eg. 1,3-7,12)
-m <module>     : additional module to put in the namespace
-k <kw1>,<kw2>,...      : include only tests with one of those keywords (can be used many times)
-K <kw1>,<kw2>,...      : remove tests with one of those keywords (can be used many times)

表3-UTScapy命令行语法

所有参数都是可选的. 没有关联参数值的参数可以串在一起(即–lqF ). 如果未指定测试文件,则测试定义来自<STDIN>. 同样,如果未指定输出文件,则将其定向到<STDOUT>. 默认输出格式为" ansi". 表4列出了参数,关联的参数值及其对UTScapy的含义.

Argument

参数值

对UTScapy的意义

-t

testfile

输入定义测试活动的测试文件(默认= <STDIN>)

-o

output_file

用于输出测试活动结果的文件(默认= <STDOUT>)

-f

test

ansi,HTML,LaTeX,格式化输出报告(默认= ansi)

-l

在本地生成报告相关文件. 对于HTML,生成JavaScript和样式表

-F

默认情况下,失败的测试用例将首先在HTML输出中扩展

-d

在执行活动之前,打印活动的简短列表

-D

打印简短的广告系列列表并停止. 不执行广告活动

-C

不计算测试签名

-q

执行测试时不要将测试进度更新到屏幕上

-qq

静音模式

-n

testnum

仅执行按编号列出的那些测试. 可以使用–d或–D检索测试编号. 测试可能会以逗号分隔的列表形式列出,并且可能包括范围(例如1、3-7、12)

-m

module

在执行测试之前加载模块. 可用于测试Scapy的衍生作品. 注意:打算以" __main__"执行的派生作品不会被UTScapy以" __main__"调用.

-k

kw1,kw2,...

仅包含关键字" kw1"的测试. 可以指定多个关键字.

-K

kw1,kw2,...

排除关键字" kw1"的测试. 可以指定多个关键字.

表4-UTScapy参数

表5显示了具有多个测试集定义的简单测试活动. 此外,还指定了关键字,以允许执行有限数量的测试用例. 注意,在测试3和5中使用assert()语句检查中间结果. 测试2和5在设计上将失败.

% Example Test Campaign

# Comment describing this campaign
#
# To run this campaign, try:
#   ./UTscapy.py -t example_campaign.txt -f html -o example_campaign.html -F
#

* This comment is associated with the test campaign and will appear
* in the produced output.

+ Test Set 1

= Unit Test 1
~ test_set_1 simple
a = 1
print a

= Unit test 2
~ test_set_1 simple
* this test will fail
b = 2
a == b

= Unit test 3
~ test_set_1 harder
a = 1
b = 2
c = "hello"
assert (a != b)
c == "hello"

+ Test Set 2

= Unit Test 4
~ test_set_2 harder
b = 2
d = b
d is b

= Unit Test 5
~ test_set_2 harder hardest
a = 2
b = 3
d = 4
e = (a * b)**d
# The following statement evaluates to False but is not last; continue
e == 6
# assert evaluates to False; stop test and fail
assert (e == 7)
e == 1296

= Unit Test 6
~ test_set_2 hardest
print e
e == 1296

要查看针对Scapy的示例,请访问http://www.secdev.org/projects/UTscapy . 将页面底部的示例剪切并粘贴到文件demo_campaign.txt ,然后对它运行UTScapy:

./test/run_tests -t demo_campaign.txt -f html -o demo_campaign.html -F -l

检查文件demo_campaign.html生成的输出.

Using tox to test Scapy

tox命令简化了Scapy的测试. 它将自动创建虚拟环境并安装必需的Python模块.

例如,在全新的Debian安装中,以下命令将自动启动所有Scapy单元测试,而无需任何外部依赖项:

tox -- -K vcan_socket -K tcpdump -K tshark -K nmap -K manufdb -K crypto

VIM syntax highlighting for .uts files

scapy/doc/syntax/vim_uts_syntax/ftdetectscapy/doc/syntax/vim_uts_syntax/syntax所有文件复制到~/.vim/并保留文件夹结构.

如果ftdetect / filetype.vim已经存在,则可能需要手动修改此文件.

这些命令将执行安装:

cp -i -v ftdetect/filetype.vim $HOME/.vim/ftdetect/filetype.vim
cp -i -v ftdetect/uts.vim $HOME/.vim/ftdetect/uts.vim
cp -i -v syntax/uts.vim $HOME/.vim/syntax/uts.vim

另外, scapy/doc/syntax/vim_uts_syntax/中的安装脚本会自动执行安装.

Releasing Scapy

在引擎盖下,Scapy版本表示为签名的git标签. 在签署提交之前,希望创建发布的维护者必须:

  • 检查相应的Travis和AppVeyor测试是否通过

  • run ./run_scapy locally

  • run tox

  • 使用scapy/doc/vagrant_ci/的Vagrant设置在BSD上运行单元测试

以v2.4.3为例,可以使用以下命令对发行版进行签名和发布:

git tag -s v2.4.3 -m "Release 2.4.3"
git tag v2.4.3 -v
git push --tags

也可以发布候选版本(RC). 例如,第一个RC将标记为v2.4.3rc1,消息2.4.3 Release Candidate #1 .

在将发布版本上传到PyPi之前,必须将setup.pyauthor_email更改为执行发布版本的维护者的地址. 然后可以使用以下命令:

python3 setup.py sdist
twine check dist/scapy-2.4.3.tar.gz
twine upload dist/scapy-2.4.3.tar.gz