风格指南

本样式指南涵盖了所有插件组件的样式，包括插件规范、代码、依赖项和文档。

惯例

下面的章节记录了编写插件时应该遵循的约定。

在本文档中未定义规则，请遵循Pep8．

快速指南

插件名称

关于所定义的插件的名称plugin.spec.yaml文件。请注意，这应该是唯一称为的密钥姓名在整个插件规范中（所有其他插件应该重命名为标题．）

名称:plugin_name

规则

  • 名称应小写。myplugin.
  • 尽可能使用company_product格式
    • 例如rapid7_metasploit
  • 名称应该是简洁的，代表他们的目的或服务
    • 现在就应该服务servicenow
  • 如果不是公司或服务名称，请使用下划线分隔单词
    • 例如get_url.
  • 在服务和网站相同的情况下，如果域名足够独特，避免顶级域名
    • 例如freegeoip.net应该是freegeoip
  • 如果服务和网站是相同的，如果域不是唯一的，则添加顶级域
    • 例如，ifconfig是unixtool, web service ifconfig。公司应该ifconfig_co
  • 数字在插件名中是有效的
    • 例如GeoLite2.
  • 不允许alpha-numeric和下划线以外的字符
  • 名称应该是四个词或更少

规范

的样式信息。plugin.spec.yaml文件。

缩进

使用两个空格进行缩进：

         

          yaml.

           
          

         

          

           

            1

           触发器：
          

          

           

            2

           my_trigger1.：
          

          

           

            3.

           布拉：
          

          

           

            4

           布拉：
          

          

           

            5

           my_trigger2.：
          

          

           

            6

           布拉：
          

          

           

            7

           布拉：

排队休息

架构部分：元数据，触发器，动作，连接应由划线中断分隔。此外，文件末尾不应该有额外的换行符。

例子:

         

          yaml.

           
          

         

          

           

            1

           ......
          

          

           

            2

           标签：［“布拉”］
          

          

           

            3.

           
          

          

           

            4

           触发器：
          

          

           

            5

           my_trigger1.：
          

          

           

            6

           布拉：
          

          

           

            7

           布拉：
          

          

           

            8

           my_trigger2.：
          

          

           

            9

           布拉：
          

          

           

            10.

           布拉：
          

          

           

            11.

           
          

          

           

            12.

           行动：
          

          

           

            13.

           my_action1：
          

          

           

            14.

           布拉：
          

          

           

            15.

           布拉：
          

          

           

            16.

           my_action2：
          

          

           

            17.

           布拉：
          

          

           

            18.

           布拉：

报价

在所有类型中，只有数组类型需要使用双引号。

好的：

         

          yaml.

           
          

         

          

           

            1

           输入：
          

          

           

            2

           数组：
          

          

           

            3.

           描述：一系列的事情
          

          

           

            4

           类型：“[]字符串”

缺点:

         

          yaml.

           
          

         

          

           

            1

           输入：
          

          

           

            2

           URL.：
          

          

           

            3.

           类型：“字符串”#这句话不应该引用
          

          

           

            4

           描述：URL下载
          

          

           

            5

           必需的：“真的”#这句话不应该引用

标点符号

不要在句子结尾加上标点符号标题和描述．它们也不应该存在于任何其他领域。标点符号应用于规格的帮助部分的主体。

标签

要求：*小写字符*编号允许*没有下划线

         

          yaml.

           
          

         

          

           

            1

           标签：［恶意软件，国际奥委会，老鼠，木马，远程］

提交消息

Git提交应描述性并描述修复或更改。

规则

  • 使用命令

    • 例如修复而不是固定或者修复
    • 第一个描述字母应该是大写的
    • 使用形式:<文件>：<描述>在可能的情况下

    看到Git的最佳实践

行动和触发名称

名称在plugin.spec.yaml文件使用标题钥匙。良好风格的例子如下：

         

          yaml.

           
          

         

          

           

            1

           行动：
          

          

           

            2

           match_string.：
          

          

           

            3.

           标题：匹配字符串
          

          

           

            4

           描述：从文本文件中匹配字符串
          

          

           

            5

           match_number：
          

          

           

            6

           标题：匹配数
          

          

           

            7

           描述：匹配数字从一个文本文件
          

          

           

            8

           提炼：
          

          

           

            9

           标题：提取
          

          

           

            10.

           描述：从存档中提取文件

规则

  • 标题应该不超过四个字。该描述旨在给出其余的细节。
  • 每个词标题第一个字母应该大写(例如:匹配字符串因为它是一个标题。)这条规则的例外是冠词和连词。解析各种各样)．
  • 第一个词描述第一个字母应该大写，而不是和标题(如。匹配文本文件的字符串)．

财产名称

属性名在这里定义。这些变量包括输入/输出变量、操作、触发器和连接名。

常见的

  • 主持人—“中性”:当“IP地址”和“域名”都可以输入时使用。
  • 地址-仅用于IP地址值(IPv4或IPv6)。8.8.8.8
  • 域- 仅用于域名值，例如：www.google.com.
  • URL.-仅用于url值，例如https://product.company.com:1234
  • ssl_verify- 布尔属性用于决定是否验证SSL证书

规则

  • 名称应小写。超时
  • 名字应该简洁并表示他们的目的，如果可能的话，限制了2个单词。country_code
  • 如果没有简洁，请使用下划线分开单词metro_code
  • 除非API要求，否则不允许使用alpha和下划线以外的字符

输入例子

在plugin.spec.yaml和help.md中，需要为动作、触发器和连接的每个输入添加输入示例。这将帮助用户确定输入值的格式。

下表列出了一些示例类型和值。

示例类型 示例值
公司 示例组织
域 example.com.
rapt7.com.
URL https://example.com
https://rapid7.com
IP地址 代码块192.0.2.0/24 (TEST-NET-1)、198.51.100.0/24 (TEST-NET-2)和203.0.113.0/24 (TEST-NET-3)在文档中提供了使用。RFC5737.
IP网关 198.51.100.1
IP广播 198.51.100.255
IP CIDR. 198.51.100.0/24
IPv6地址 2001年:db8:1:1:1:1:1:1 (RFC3849-为文件保留的地址)
电子邮件 user@example.com.
数组:[“user1@example.com”、“user2@example.com”]
区分域名:user@rapid7.com、user2@rapid7.com
用户名 user1
全名 示例用户
电话号码 美国电话范围是(800)555-0100到(800)555-0199。这个范围只在例子和小说中使用。
一般的MD5哈希 9DE5069C5AFE602B2EA0A04B66BEB2C0
一般SHA1哈希 02699626 f388ed830012e5b787640e71c56d42d8
字节文件 UmFwaWQ3IEluc2lnaHRDb25uZWN0Cg = =
恶意软件的文件名 安装程序
credential_username_password {“用户名”：“User1”，“密码”：“mypassword”} - 如果密码不是密码，如jira api键 - 确保您的格式是一个现实但消毒的关键
credential_secret_key. {"domain": "example.com"， "token": "9de5069c5afe602b2ea0a04b66beb2c0"} -根据需要更新token以匹配供应商的密钥格式。如果key是MD5哈希(32字符无换行)，则使用的内容echo "Rapid7 InsightConnect" | md5 . txt
credential_asymmetric_key ----- begin rsa私钥-----
MIIEpQIBAAKCAQEAjGnoUtfPHqvX3PIU6N9FKmwQ3Zl + NoaWb4yMLhudkdEBJ3Au
lvoygvxzfkuwkh0rial + I8QdlqDKBm656UeOCh3r / i9e0ULKxkXDFfKmc3p2Wv + 0
A4imyYuL / fweOSGSnQlgYKr99HciTBIdL15SZ32TjYb + PDZBl + 6 zqsw2hynjcqmj
iciC7CAj6gB9SO8x1vMsRkU + rqKuc2r8Uk + qhECw8zR4K66wFuYM17sGUMXUq / pH
WdiEvO3q / mdK47Nrx5i2baC7o5RXspKHYy6Xer4Vbnipl4DgAKkaNOL02a + Zv38Q
l + xy9wdmwquibmiqsbj / k6xxdipqktr + / 032eqidaqabaoibaekpzpbutpqbrj3n
5 s1rb71ul85u0oqks2dnvb89xvabb0nll1wsc39yb271phjorrqpkmwhq08cfrae
3 oxqnh47s + OrOxPMyZSIdjmicr5tRzjXeYOkNk0G7JgC + OL3YieOOnTyZGQxHUqB
3MFIZ45SHDV3MXC3LPFS35 / XTHM8E / GW / GTFVU3QBOQAR1Q / Tarqyehvgiutwdz0
seftj8eawobabxiv3qpxnaqgipwypbicl3ak15gs5enk4rngi2bi7hdmmwdwa6t /
g0cp0tityfq05jumnaz4wekxxd5ebm776eynsoxtcasztmywzcitrqxl6y4 / oget.
uvsm9zecgyea7g8cyydkdtbyoiyekjvkswueloa2edxmvykl8hlopiq1qosh / n1
30nn / gvcvd7qed4p / u0xamupm2hvhuxwxu / t9j11dvlkp7qsh9u4pkziw6nmv5n
/ 9 + mcjdwah5bqajtmpf0uozswk41jve0fa7a3fcrxp1u / gd9bksad00cgyeamaio
CHEH7 + PD7VUTF85U + FQBDJY + KMYFETPD2717P6I5V6C6LVPCNM7VOZLGY0FJOALD
E9NTM0VU8FZKUIIHKPZW9 / LSAV8BGO + VSQRN / IMEMDQOL959IXXI / 6YZKY5JWYRP
mlwoNzU0ekcHzg0eu7DA1uzRfv4F1NUW + QylRd0CgYEAzr07OhdP1jyCItD8U3n6
EWh6s6g0sVV5tdp / UszXpMgLyQFnW9ztIvRMU / jmIAzkrm9NFYaHw7DLv9jKd4y0
/ 590 + ro + kg + tpyskumjokcnfiucofj9doqwvzsyr45idhivtnya1zsyjrmvyf3cz
dw8ePSukzbTRTWYZmGenOrkCgYEAhoO6MdYAweXzH0J8XsDePEzmmcvaauzDl35F
gioaxc1b1381nqnrougsi1czzo6bp + q69lbx3pav9wnqtdp + 5ox4st8fggmomidg
/ m5Z3F4LtajIvD41V9hR2i1yX4mWRmsLh1acmmQvvzSTekLvez8jD8ZOgV69yBaV
kdsXa90CgYEAk + 6 ghpxnku12uanf9mh8lon + 35 / iPeeoqf0MY5FMVRYx10ZA91Lh
IEACZVHIQZXCTHWHLA4SXE962EG + JI / AWKS4KXLCMUZIESE + JFC7PTUMJJLSOWJV
8 / dqUH5yjRKs2qxkBWG4HmT3Nx6A8sYIrUYxyqVLBpG8yKngbnaYPV4 =
-----结束RSA私钥-----
文件 {“filename”：“”，“内容”：“UMFWWQ3IELUC2LNAHRDB25UZWN0CG ==”}我们可以使用自定义文件名拟合以获取动作的目的。例如。如果动作提交了PDF，CompanyData.pdf。（内容是：echo "Rapid7 InsightConnect" | base64）
哈希类型CRC32 6851年cf3c
MD5散列类型 44 d88612fea8a8f36de82e1278abb02f
SHA1哈希类型 3395856CE81F2B7382DEE72602F798B642F14140
哈希类型SHA224 B42EC8B47DEB2DC75EDEBD01132D63F8E8D4CD08E5D26D8BD366BDC5
哈希类型SHA256 275年a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
哈希类型SHA384 038年f2e50e33dacef50d7e503b45c3525fcdbe89a823f9c4417d7c13e8e96a53dd6bd6d7fcc91189c5cda7253f4455106
哈希型SHA512 CC805D5FAB1FD71A4AB352A9C533E65FB2D5385525F32306065CB48F3AB8425CB485C64B0DC9A6505C64B0DCMB48F3ABAD84272625C64B0DC9A6505C64B0DC9A6505C64B0DC9A6505C64B0DC9A061D92ABADA3363327327ABADA336AB

更新日志

我们在插件的帮助属性的版本部分记录更新日志历史plugin.spec.yaml．的格式是. x.x.x——<消息>其中x代表语义版本，并有消息记录更改。

下面是要用于插件的常见更改的消息约定列表。

  • 支持Web服务器模式- 对于Web服务器模式支持，即新父Decker Image，V2插件规范版和新的Self.logger使用
  • 更新到新的凭据类型- 支持新的凭证类型。credential_username_password，credential_secret_key.
  • 更新到v2 python插件架构- 移植到Python v2拱门
  • 更新到新的密钥凭据类型- 在此示例中使用单个新凭据类型，特定于Credential_secret_key
  • 新动作<动作标题>-对于新操作，例如新操作从策略中删除
  • 新操作和-两个新动作的列表
  • 新建动作<动作标题>，<动作标题>和<动作标题>-超过两个新操作的列表
  • 新触发器<触发器标题>-新的触发器
  • 新触发器和-两个新触发器的列表
  • 新建动作<动作标题>，<动作标题>和<动作标题>- 对于两个以上的新触发器的列表
  • 新动作<动作标题>，<动作标题>和<动作标题>-一个新的触发器和多个动作
  • 修复问题- 用于错误修复。解决问题的问题可能导致有效凭据的失败
  • 更新以使用komand/python-3- small -plugin:2 ' ' Docker image to reduce plugin size - For using then new SDK images
  • 运行插件到最不特权的用户—表示用户nobody的设置Dockerfile

同时多次，用a串联它们字符，例如：

  • 更新到v2 Python插件架构|支持web服务器模式|更新到新的凭证类型
  • 更新到新的凭证类型|新动作禁用用户

错误

看到集成中的错误处理指导。

触发器

输入

为了可用性，所有触发器都应该支持调用的输入时间间隔这将在SDK语言中传递给睡眠机制：

         

          yaml.

           
          

         

          

           

            1

           频率：
          

          

           

            2

           类型：整数
          

          

           

            3.

           描述：轮询频率(秒)
          

          

           

            4

           默认：300
          

          

           

            5

           必需的：假

连接

风格

连接按照与属性名称相同的样式指南。

日志记录

不使用连接的插件应删除默认值self.logger.info.来自宣言的connection.py.py.身体并添加一个通过声明。

         

          python

           
          

         

          

           

            1

           def连接（自我，参数个数）：
          

          

           

            2

           ＂＂"
          

          

           

            3.

           连接配置参数以字典的形式提供
          

          

           

            4

           参数或者也可以在self.parameters ['键']
          

          

           

            5

           
          

          

           

            6

           下面将设置要访问的var
          

          

           

            7

           self.blah = self.parameters ['blah']
          

          

           

            8

           在动作和触发文件中如下:
          

          

           

            9

           废话= self.connection.blah
          

          

           

            10.

           ＂＂"
          

          

           

            11.

           #todo：如果不需要连接，则实现连接或“通过”
          

          

           

            12.

           自我．记录器．信息（“连接：连接......”）

下面是它的样子:

         

          python

           
          

         

          

           

            1

           def连接（自我，参数个数）：
          

          

           

            2

           ＂＂"
          

          

           

            3.

           连接配置参数以字典的形式提供
          

          

           

            4

           参数或者也可以在self.parameters ['键']
          

          

           

            5

           
          

          

           

            6

           下面将设置要访问的var
          

          

           

            7

           self.blah = self.parameters ['blah']
          

          

           

            8

           在动作和触发文件中如下:
          

          

           

            9

           废话= self.connection.blah
          

          

           

            10.

           ＂＂"
          

          

           

            11.

           通过

待办事项

在完成所有任务后，删除插件自动生成的TODO行。

注意到#待办事项来自下面新生成操作的行。这些行应该在添加代码时删除。

         

          python

           
          

         

          

           

            1

           进口Komand.
          

          

           

            2

           从．模式进口DomainLookupInput.，DomainLookupOutput.
          

          

           

            3.

           ＃下面的自定义导入
          

          

           

            4

           
          

          

           

            5

           
          

          

           

            6

           类domainlookup.（Komand.．行动）：
          

          

           

            7

           
          

          

           

            8

           def__init__（自我）：
          

          

           

            9

           极好的（自我．__class__进行，自我）．__init__（
          

          

           

            10.

           姓名＝“domain_lookup”，
          

          

           

            11.

           描述＝“查找域名”，
          

          

           

            12.

           输入＝DomainLookupInput.（），
          

          

           

            13.

           输出＝DomainLookupOutput.（））
          

          

           

            14.

           
          

          

           

            15.

           def跑（自我，参数个数＝｛｝）：
          

          

           

            16.

           # TODO:实现运行函数
          

          

           

            17.

           返回｛｝
          

          

           

            18.

           
          

          

           

            19.

           def测试（自我）：
          

          

           

            20.

           # TODO:实现测试功能
          

          

           

            21.

           返回｛｝

注意到#待办事项来自新生成的线条connection.py.py.下面的文件。这条线应该去掉。

         

          python

           
          

         

          

           

            1

           进口Komand.
          

          

           

            2

           从．模式进口connectionschema.
          

          

           

            3.

           ＃下面的自定义导入
          

          

           

            4

           
          

          

           

            5

           
          

          

           

            6

           类联系（Komand.．联系）：
          

          

           

            7

           
          

          

           

            8

           def__init__（自我）：
          

          

           

            9

           极好的（自我．__class__进行，自我）．__init__（输入＝connectionschema.（））
          

          

           

            10.

           
          

          

           

            11.

           def连接（自我，参数个数）：
          

          

           

            12.

           ＂＂"
          

          

           

            13.

           连接配置参数以字典的形式提供
          

          

           

            14.

           参数或者也可以在self.parameters ['键']
          

          

           

            15.

           
          

          

           

            16.

           下面将设置要访问的var
          

          

           

            17.

           self.blah = self.parameters ['blah']
          

          

           

            18.

           在动作和触发文件中如下:
          

          

           

            19.

           废话= self.connection.blah
          

          

           

            20.

           ＂＂"
          

          

           

            21.

           #todo：如果不需要连接，则实现连接或“通过”
          

          

           

            22.

           自我．记录器．信息（“连接：连接......”）

测试

每个插件应包括JSON测试文件测试目录中。这些测试文件用于模拟用户对插件的输入，以测试插件的各种操作和触发器。

的。/ run.sh工具可以用来列出可用的示例并生成它们。

样品列表

         

          

           
          

         

          

           

            1

           $ ./run.sh -c样本
          

          

           

            2

           操作：[domain_lookup domain_blacklist address_blacklist url_lookup address_lookup]
          

          

           

            3.

           触发器:[poll_domain_blacklist poll_address_blacklist]
          

          

           

            4

           样本需要样本名称e.g.``./run.sh -c sample ''

为domain_lookup操作生成一个样本，并将其写入测试目录中。

$ ./run.sh -c sample domain_lookup > tests/domain_lookup.json

生成所有示例并将它们写入测试目录中。

$ ./run.sh -c样本

在事件中。/ run.sh不可用，执行手动生成:

Docker运行komand/: sample | jq '。“>测试/ < testname > . json

JQ.用于漂亮打印文件，使其更容易编辑。

规则

  • 所有操作的成功测试
  • 所有操作的故障测试
  • 测试所有可选输入和所有操作
  • 失败测试应该是后缀_bad例如png_download_bad.json
  • 成功测试不应该提出。png_download.json

例子

  • 成功： _ <动作> .json例如domain_lookup.json，github_lookup.json
  • 失败:< desc > _ <行动> _bad.json例如nxdomain_lookup_bad.json.，private_ip_lookup_bad.json

的例子CSV.插件:

         

          

           
          

         

          

           

            1

           测试：
          

          

           

            2

           ├──1 r_filter.json
          

          

           

            3.

           ├──1r_filter_bad.json.
          

          

           

            4

           ├──1 r_filter_bad2.json
          

          

           

            5

           ├──1r_filter_bad3.json.
          

          

           

            6

           ├──1 r_filter_bad4.json
          

          

           

            7

           ├──1r_space_filter.json.
          

          

           

            8

           └──csv_filter_bad.json

依赖性

Dockerfile

所有插件都可以使用和修改Dockerfile将依赖项添加到插件。依赖项通常添加跑和/或添加Dockerfile命令。

在以下示例中，我们需要一个debian包，一个自定义python库，在Python存储库中不可用，以及配置文件，因此插件可能成功运行：

         

          

           
          

         

          

           

            1

           从komand / komand / python-3-37-slim-plugin
          

          

           

            2

           ＃有关可用SDK父图像的以下文档：https：//komand.github.io/python/sdk.html#version
          

          

           

            3.

           
          

          

           

            4

           标签组织= komand
          

          

           

            5

           标签sdk = python
          

          

           

            6

           标签类型=插件
          

          

           

            7

           
          

          

           

            8

           在这里添加任何自定义包依赖项
          

          

           

            9

           #注意:将pip包添加到requirements.txt
          

          

           

            10.

           运行apt-get更新&& apt-get安装-y whois = 5.2.7
          

          

           

            11.

           运行pip安装git + https：//github.com/komand/python-whois.git@0.4.0
          

          

           

            12.

           
          

          

           

            13.

           #结束包依赖
          

          

           

            14.

           
          

          

           

            15.

           #添加配置文件从插件repo
          

          

           

            16.

           添加./whois.conf /etc/whois.conf.
          

          

           

            17.

           
          

          

           

            18.

           #安装pip依赖项
          

          

           

            19.

           运行if [-f requirements.txt];然后PIP安装-r requirements.txt;fi
          

          

           

            20.

           
          

          

           

            21.

           ＃安装插件
          

          

           

            22.

           运行python setup.py build && python setup.py install
          

          

           

            23.

           
          

          

           

            24.

           #用户运行插件代码。支持的两个用户是:root, nobody
          

          

           

            25.

           用户没人
          

          

           

            26.

           
          

          

           

            27.

           入口点(“/ usr /地方/ bin / komand_whois”)

注意皮普默认情况下安装在Docker映像中，但不应使用此方法安装Python软件包，除非使用下面描述的方法无法找到它们。上面的例子是使用其他方法无法使用的情况。

规则:

  • 需要固定版本的依赖关系包
  • Debian软件包,apt-get更新包安装前必须使用吗
  • 除非技术限制要求，否则不应用于Python包装安装

要求.txt.

较新的插件(v2 arch)使用要求.txt.文件获取依赖项。如果插件不包含此文件，那么旧setup.py.文件使用。

规则:

  • 中需要依赖包的固定版本要求.txt.
  • 请勿触摸setup.py.

例如。

         

          

           
          

         

          

           

            1

           $ cat powershell /要求.txt
          

          

           

            2

           #在这里列出第三方依赖项，用换行符分隔。
          

          

           

            3.

           #所有依赖项必须是版本固定的，例如。请求= = 1.2.0
          

          

           

            4

           ＃查看：https://pip.pypa.io/en/stable/user_guide/#requirements-files
          

          

           

            5

           pywinrm = = 0.2.2
          

          

           

            6

           Pykerberos == 1.2.1
          

          

           

            7

           Requests-Kerberos == 0.12.0

setup.py.

较旧的pllugins（v1.arch)使用setup.py.文件获取依赖项。如果插件包含要求.txt.然后不应修改此文件并查看上述部分。

规则:

  • 中需要依赖包的固定版本setup.py.的install_requires节

例如。

         

          

           
          

         

          

           

            1

           猫zeus_tracker美元/ setup . py
          

          

           

            2

           从setuptools导入setup, find_packages
          

          

           

            3.

           
          

          

           

            4

           设置（name ='zeus_tracker-komand-plugin'，
          

          

           

            5

           version =“0.1.1”,
          

          

           

            6

           描述='Zeus命令和控制服务器跟踪'，
          

          

           

            7

           作者='komand'，
          

          

           

            8

           author_email = ",
          

          

           

            9

           url =''，
          

          

           

            10.

           包= find_packages (),
          

          

           

            11.

           install_requires = ['komand'，'feedparser == 5.2.1'，'lxml == 4.1']，
          

          

           

            12.

           脚本=(“bin / komand_zeus_tracker”)
          

          

           

            13.

           ）