时尚指南

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

约定

以下各节文档约定在编写插件时应遵循的约定。

如果本文档中没有定义规则，请遵循PEP8．

快速指南

插件名称

关于中定义的插件名称plugin.spec.yaml文件。注意，这应该是唯一被调用的键名称在整个插件规范中(所有其他插件应该重命名为标题．)

名称：plugin_name.

规则

  • 名称应小写。我的插件
  • 尽可能使用company_product格式
    • 例如rapt7_metasploit.
  • 名称应该简洁，并表示其用途或服务名称
    • e、 g.现在的服务应该是ServiceNOW.
  • 如果不是公司或服务名称，请使用下划线分隔单词
    • 例如获取url
  • 如果服务和网站相同，如果域是足够独特的，则避免顶级域名
    • 例如freegeoip.net应该是免费
  • 如果服务和网站相同，如果域不唯一，请添加顶级域
    • e、 g.ifconfig是unixtool，web服务ifconfig.co应该是unixtoolifconfig_co.
  • 数字在插件名中是有效的
    • 例如geolite2
  • 不允许使用字母数字和下划线以外的字符
  • 名字应该少于四个字

规格

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

缩进

缩进使用两个空格：

         

          亚马尔

           
          

         

          

           

            1

           触发器：
          

          

           

            2

           my_trigger1：
          

          

           

            3.

           废话：
          

          

           

            4

           废话：
          

          

           

            5

           my_trigger2：
          

          

           

            6

           废话：
          

          

           

            7

           废话：

换行符

模式部分:元数据、触发器、操作、连接，应该用换行符分隔。此外，在文件末尾不应该有额外的换行符。

例子：

         

          亚马尔

           
          

         

          

           

            1

           ...
          

          

           

            2

           标签：［“废话”］
          

          

           

            3.

           
          

          

           

            4

           触发器：
          

          

           

            5

           my_trigger1：
          

          

           

            6

           废话：
          

          

           

            7

           废话：
          

          

           

            8

           my_trigger2：
          

          

           

            9

           废话：
          

          

           

            10

           废话：
          

          

           

            11

           
          

          

           

            12

           行动：
          

          

           

            13

           我的行动1：
          

          

           

            14

           废话：
          

          

           

            15

           废话：
          

          

           

            16

           我的行动2：
          

          

           

            17

           废话：
          

          

           

            18

           废话：

引用

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

好:

         

          亚马尔

           
          

         

          

           

            1

           输入：
          

          

           

            2

           大堆：
          

          

           

            3.

           描述：一系列的东西
          

          

           

            4

           类型：“[]字符串”

缺点:

         

          亚马尔

           
          

         

          

           

            1

           输入：
          

          

           

            2

           url：
          

          

           

            3.

           类型：“细绳”#这句话不应该引用
          

          

           

            4

           描述：要下载的URL
          

          

           

            5

           必修的：“对”#这句话不应该引用

标点

不要在句子结尾加上标点符号标题和描述. 它们也不应该出现在任何其他领域。规范帮助部分的正文中应使用标点符号。

标签

要求:*小写字符*允许数字*不允许下划线

         

          亚马尔

           
          

         

          

           

            1

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

提交消息

Git提交应该是描述性的，并描述修复或更改。

规则

  • 使用命令

    • 例如使固定而不是固定的或修复
    • 描述的第一个字母应大写
    • 使用表格：：在可能的情况下

    看Git最佳实践

操作和触发器名称

名称在中指定plugin.spec.yaml文件使用标题钥匙好的风格示例如下：

         

          亚马尔

           
          

         

          

           

            1

           行动：
          

          

           

            2

           匹配字符串：
          

          

           

            3.

           标题：匹配字符串
          

          

           

            4

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

          

           

            5

           匹配号码：
          

          

           

            6

           标题：匹配号码
          

          

           

            7

           描述：匹配文本文件中的数字
          

          

           

            8

           提取：
          

          

           

            9

           标题：提取
          

          

           

            10

           描述：从归档文件中提取文件

规则

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

财产名称

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

常见的

  • 宿主- 中性：当IP地址或域名可以是值时使用。
  • 地址-仅用于IP地址值(IPv4或IPv6)。8.8.8.8
  • 领域-仅用于域名值，例如:www.google.com
  • url- 仅用于URL值例如U.G.https://product.company.com:1234
  • ssl_verify-用于决定是否验证SSL证书的布尔属性

规则

  • 名称应小写。暂停
  • 名称应该简明扼要，能表达其目的，如果可能的话，不要用两个字。国家代码
  • 如果不够简洁，可以使用下划线分隔单词metro_code.
  • 除非API要求，否则不允许使用alpha和下划线以外的字符

输入示例

在Plugin.Spec.YAML和HELP.MD中需要添加输入示例。在Plugin.Spec.yaml和Help.md中的每个输入。这将帮助用户弄清楚输入值的格式。

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

实例类型 示例值
公司 例如组织
域名 example.com
rapid7.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 ==.
恶意软件的文件名 setup.exe.
credential_username_password. {"username": "user1"， "password": "mypassword"} -如果password不是密码，如Jira API密钥-确保你的格式是真实的但经过消毒的密钥
凭证\u密钥\u密钥 {"domain": "example.com"， "token": "9de5069c5afe602b2ea0a04b66beb2c0"} -根据需要更新token以匹配供应商的密钥格式。如果key是MD5哈希(32字符无换行)，则使用的内容echo "Rapid7 InsightConnect" | md5 . txt
credential_asymmetric_key. ----- begin rsa私钥-----
miiepqibaakcaqeajgnoutfphqvx3piu6n9fkmwq3zl + noawb4ymlhudkdebj3au.
+I8QdlqDKBm656UeOCh3r/i9e0ULKxkXDFfKmc3p2Wv+0LVOYGVXZFKUKH0RIAL
A4imyYuL / fweOSGSnQlgYKr99HciTBIdL15SZ32TjYb + PDZBl + 6 zqsw2hynjcqmj
iciC7CAj6gB9SO8x1vMsRkU + rqKuc2r8Uk + qhECw8zR4K66wFuYM17sGUMXUq / pH
Wdievo3q / mdk47nnrx5i2bac7o5rxspkhyy6xer4vbnipl4dgakkanol02a + zv38q
l + xy9wdmWqUIbMiqSbj / k6xxDiPQkTR + / 032 eqidaqabaoibaekpzpbutpqbrj3n
5s1rb71ul85u0oqks2dnvb89xvabb0nll1wsc39yb271phrjorrqpkmwhq08cfrae.
3oxQnh47s+OROxpmyzSidjMICR5TrzJXeYonk0G7JGC+OL3YIEONTZGQXHUQB
3 mfiz45shdv3mxc3lpfs35 xTHM8E /千瓦/ gTfvU3QboQaL1q / taRQYEHvgiutwdZ0
sEFtJ8eAwOBABXiV3QPxnAQgIpwYpbicl3AK15gs5ENK4Rngi2bI7hdmMwDWa6t/
g0CP0TityFq05JUmnaz4wekXxD5EBm776EYNSoxTCaSzTMYwZCITrqXl6Y4 / ogeT
UVSM9ZECGYEA7G8CYYDKDTBYOUIYEKWUELOA2EDXMVYKL8LOPIQ1QOSH/N1
30 nn / GVcvD7QED4p / u0XaMuPm2HVhuXwxu / t9j11DVlKP7QsH9u4pJKziw6NmV5N
/ 9 + mcjdWAH5BqaJtmpF0uoZsWk41JVe0fA7a3FCrXp1U / GD9BKSAD00CgYEAmAio
ChEh7+pD7vutF85u+FqbdjY+KmyFeTPd2717P6i5V6C6lVpcnM7voZlGy0fjoald
E9NTM0VU8FZKUIHKPZW9/LSAV8BgO+vSQrN/IMEmDqol959IxxI/6yzkY5JwYRP
mlwonzu0ekchzg0eu7da1uzrfv4f1nuw + qylrd0cgyeazr07ohdp1jycitd8u3n6
EWh6s6g0sVV5tdp / UszXpMgLyQFnW9ztIvRMU / jmIAzkrm9NFYaHw7DLv9jKd4y0
/59o+ro+kg+TPYSKUMJOKCNFJ9DOQWVZSYR45IDHIVTNYA1ZSYRMVYF3CZ
dw8ePSukzbTRTWYZmGenOrkCgYEAhoO6MdYAweXzH0J8XsDePEzmmcvaauzDl35F
ox4st8fggmomidg gIOAxc1B1381NqnRoUgSi1czZO6BP + q69LbX3PaV9WNqtDp + 5
/ m5z3f4ltajivd41v9hr2i1yx4mwrmslh1acmmmqvvzsteklvez8jd8zogv69ybav.
kdsXa90CgYEAk+6ghpXNku12UANf9MH8loN+35/iPeeoqf0MY5FMVRYx10ZA91Lh
ieAczVhiqzxCtHWhLA4SxE962eg + / awkS4kXLCMuZIESE + jFc7ptUmJjlsOWjv
8 / dquh5yjrks2qxkbwg4hmt3nx6a8syriuyxyqvlbpg8ykngbnaypv4 =
-----结束RSA私钥-----
文件 {“filename”：“”，“content”：“UmFwaWQ3IEluc2lnaHRDb25uZWN0Cg==”}我们可以使用自定义文件名进行操作。例如，如果操作提交PDF，CompanyData.PDF。（内容为：echo“Rapid7 Insightconnect”|Base64.）
哈希型CRC32. 6851CF3C.
MD5散列类型 44D88612FEA8A8F36DE82E1278ABB02F.
SHA1哈希类型 3395856ce81f2b7382dee72602f798b642f14140
哈希类型SHA224 b42ec8b47deb2dc75edebd01132d63f8e8d4cd08e5d26d8bd366bdc5
哈希类型SHA256 275年a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f
散列类型SHA384 038F2E50E33DACEF50D7E503B45C35255FCDBE89A823F9C4417D7C13E8E96A53DD6BD6D7FCC91189C5CDA7253F4455106
哈希类型SHA512 CC805D5FAB1FD71A4AB352A9C533E65FB2DB5B885518F4E565E688447223B8E6B85CB48F3AFAD842726D99239C9E3650C64B0DC9A061D9E507D833277ADA36AB

变更日志

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

下面是一些常用的插件更改的消息约定列表。

  • 支持web服务器模式-支持web服务器模式，即新的父Docker映像，v2插件规范版本，和新的自我。记录器使用
  • 更新到新的凭据类型—支持新的证书类型，如“credential_username_password”、“credential_secret_key”
  • 更新到v2 Python插件架构-用于移植到Python v2 arch
  • 更新到新的秘密密钥凭据类型—用于使用单个新的凭据类型，在本例中特定于credential_secret_key
  • 新建操作<操作标题>-对于新操作，例如新操作从策略中删除
  • 新动作<动作标题>和<动作标题>-查看两个新操作的列表
  • 新建动作<动作标题>，<动作标题>和<动作标题>- 对于两个以上的新操作的列表
  • 新触发<触发标题>-新的触发器
  • 新触发器和- 有关两个新触发器的列表
  • 新建动作<动作标题>，<动作标题>和<动作标题>-对于包含两个以上新触发器的列表
  • 新触发器|新动作，和-对于新触发器和多个操作
  • 修复修复错误，例如修复连接中可能导致有效凭据失败的问题
  • 更新以使用komand/python-3-slim-plugin:2`` Docker镜像以减少插件大小-用于使用新的SDK镜像
  • 运行插件作为最低特权用户-指示用户无人在中的设置Dockerfile

对于多个字符，同时使用|字符连接，例如：

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

错误

见集成时出错指导

触发器

输入

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

         

          亚马尔

           
          

         

          

           

            1

           频率：
          

          

           

            2

           类型：整数
          

          

           

            3.

           描述：轮询频率（秒）
          

          

           

            4

           违约：300
          

          

           

            5

           必修的：错误的

连接

风格

连接遵循与属性名称相同的样式指南。

记录

不使用连接的插件应该删除默认值self.logger.info的声明connection.py主体，并添加经过陈述

         

          Python

           
          

         

          

           

            1

           def连接（自己，参数）：
          

          

           

            2

           “”
          

          

           

            3.

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

          

           

            4

           参数，也可以在self.parameters['key']中访问
          

          

           

            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['key']中访问
          

          

           

            5

           
          

          

           

            6

           下面将设置要访问的var
          

          

           

            7

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

          

           

            8

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

          

           

            9

           废话= self.connection.blah
          

          

           

            10

           “”
          

          

           

            11

           经过

待办事项

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

注意到＃ 去做下面新生成操作的行。添加代码时应删除这些行。

         

          Python

           
          

         

          

           

            1

           进口komand
          

          

           

            2

           从…起．架构进口域查找输入，域查找输出
          

          

           

            3.

           #下面是自定义导入
          

          

           

            4

           
          

          

           

            5

           
          

          

           

            6

           班级域查找（komand．行动）：
          

          

           

            7

           
          

          

           

            8

           def__初始化__（自己）：
          

          

           

            9

           超级的（自己．__班级__，自己）．__初始化__（
          

          

           

            10

           名称＝'domain_lookup'，
          

          

           

            11

           描述＝“查找域名”，
          

          

           

            12

           输入＝域查找输入（），
          

          

           

            13

           输出＝域查找输出（））
          

          

           

            14

           
          

          

           

            15

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

          

           

            16

           #TODO:实现运行函数
          

          

           

            17

           返回｛｝
          

          

           

            18

           
          

          

           

            19

           def测试（自己）：
          

          

           

            20.

           ＃todo：实现测试功能
          

          

           

            21

           返回｛｝

注意到＃ 去做新生成的行connection.py文件如下。这条线应该拆下。

         

          Python

           
          

         

          

           

            1

           进口komand
          

          

           

            2

           从…起．架构进口ConnectionSchema
          

          

           

            3.

           #下面是自定义导入
          

          

           

            4

           
          

          

           

            5

           
          

          

           

            6

           班级联系（komand．联系）：
          

          

           

            7

           
          

          

           

            8

           def__初始化__（自己）：
          

          

           

            9

           超级的（自己．__班级__，自己）．__初始化__（输入＝ConnectionSchema（））
          

          

           

            10

           
          

          

           

            11

           def连接（自己，参数）：
          

          

           

            12

           “”
          

          

           

            13

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

          

           

            14

           参数，也可以在self.parameters['key']中访问
          

          

           

            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 sample .sh
          

          

           

            2

           操作：[域\查找域\黑名单地址\黑名单url \查找地址\查找]
          

          

           

            3.

           触发：[poll_domain_blacklist poll_address_blacklist]
          

          

           

            4

           样本需要样本名称，例如“`./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'.>测试/.json

金桥用于漂亮地打印文件，使其更易于编辑。

规则

  • 所有操作的成功测试
  • 所有操作的故障测试
  • 所有可选输入和所有操作的测试
  • 失败测试的后缀应为_坏的例如png_下载_bad.json
  • 成功测试不应加后缀，例如。png_download.json.

例子

  • 成功:\.json例如domain_lookup.json，github_lookup.json
  • 失败: _ _bad.json例如nxdomain_lookup_bad.json，private_ip_lookup_bad.json

来自csv插入：

         

          

           
          

         

          

           

            1

           测试:
          

          

           

            2

           ├── 1r_filter.json
          

          

           

            3.

           ├──1 r_filter_bad.json
          

          

           

            4

           ├── 1r_filter_bad2.json
          

          

           

            5

           ├── 1r_filter_bad3.json
          

          

           

            6

           ├──1R_FILTER_BAD4.JSON.
          

          

           

            7

           ├──1 r_space_filter.json
          

          

           

            8

           └──csv_filter_bad.json.

依赖关系

Dockerfile

所有插件都可以使用和修改Dockerfile向插件添加依赖项。依赖项通常随运行和/或添加Dockerfile命令。

在下面的示例中，我们需要一个Debian包、一个在python存储库中不可用的自定义python库和一个配置文件，以便插件可以成功运行：

         

          

           
          

         

          

           

            1

           来自Komand / Komand / Python-3-37 -37 -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 update && apt-get install -y whois=5.2.7命令
          

          

           

            11

           执行命令pip install git+https://github.com/komand/python-whois.git@0.4.0
          

          

           

            12

           
          

          

           

            13

           ＃结束包依赖项
          

          

           

            14

           
          

          

           

            15

           ＃添加Plugin Repo的配置文件
          

          

           

            16

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

          

           

            17

           
          

          

           

            18

           ＃安装pip依赖项
          

          

           

            19

           如果[-f要求.txt]运行;然后pip安装-r要求.txt;FI.
          

          

           

            20.

           
          

          

           

            21

           #安装插件
          

          

           

            22

           运行Python setup.py build && python setup.py安装
          

          

           

            23

           
          

          

           

            24

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

          

           

            25

           用户无人
          

          

           

            26

           
          

          

           

            27

           EntryPoint [“/ usr / local / bin / komand_whois”]

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

规则:

  • 需要依赖项包的固定版本
  • Debian软件包,apt-get更新必须在包装安装之前使用
  • 不应该用于Python包安装，除非技术限制

让

较新的插件（v2 arch）使用让文件以获取依赖项。如果插件不包含此文件，则旧的setup . py使用文件。

规则:

  • 中需要依赖包的固定版本让
  • 不要碰setup . py

如。

         

          

           
          

         

          

           

            1

           猫powershell /让美元
          

          

           

            2

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

          

           

            3.

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

          

           

            4

           #见：https://pip.pypa.io/en/stable/user_guide/#requirements-档案
          

          

           

            5

           pywinrm == 0.2.2
          

          

           

            6

           pykerberos==1.2.1
          

          

           

            7

           requests-kerberos = = 0.12.0

setup . py

老普卢金斯(V1arch)使用setup . py文件获取依赖项。如果插件包含让然后，不应修改此文件，请参见上面的部分。

规则:

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

如。

         

          

           
          

         

          

           

            1

           $ cat zeus_tracker / setup.py
          

          

           

            2

           从setuptools导入setup, find_packages
          

          

           

            3.

           
          

          

           

            4

           设置(name = ' zeus_tracker-komand-plugin ',
          

          

           

            5

           版本='0.1.1'，
          

          

           

            6

           description='ZeuS Command&Control Server Tracking'，
          

          

           

            7

           作者：komand，
          

          

           

            8

           author_email = ",
          

          

           

            9

           url=“”，
          

          

           

            10

           包= find_packages (),
          

          

           

            11

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

          

           

            12

           脚本=(“bin / komand_zeus_tracker”)
          

          

           

            13

           ）