loading...

样式指南

此章节涵盖了对插件所有组件代码样式的建议和指南,包括插件的规范文件,代码,依赖项和其它文档。

惯例

以下部分介绍了编写插件时应遵循的惯例。

如果本文档中未定义规则,请遵循PEP8

快速指南

  • 出于安全考虑,在Dockerfile设定最低权限帐户USER nobody
  • 对于日志异常记录,请使用self.log_err(), 输出到stderr
  • 对于普通日志记录,请使用self.log_out(),输出到stdout
  • 类似方法,可以参考SDK/base.py

插件名称

这是关于在plugin.spec.yaml文件中定义插件的名称的。请注意,整个插件规范文件中应该只有一个键值叫name(所有其他相似键都应重命名为title)。

name: plugin_name

规则

  • 名称应为小写,例如 myplugin
  • 尽可能使用类似company_product这样的格式,例如 chariot_base64
  • 名称应简明扼要,代表其目的或服务名,例如ServiceNow应该是 servicenow
  • 如果不是公司或服务名称,请使用下划线来分隔单词,例如 get_url
  • 如果服务和网站相同,如果域名足够独特,请避免使用顶级域名,例如freegeoip.net freegeoip
  • 如果服务和网站相同而域名不是独特的,则添加顶级域名,例如ifconfig是unix工具,web服务ifconfig.co应该是 ifconfig_co
  • 数字在插件名称中有效,例如 geolite2
  • 不允许使用字母数字和下划线以外的字符
  • 名称应为四个单词或更少
  • 规格

    关于plugin.spec.yml文件的样式信息。

    缩进

    使用2个空格进行缩进:

    triggers:
      my_trigger1:
        blah:
          blah:
      my_trigger2:
        blah:
          blah:

    换行

    架构部分:元数据,触发器,动作,连接,应由换行符分隔。此外,文件末尾不应有额外的换行符。

    例:

    ...tags: [ "blah" ]
    triggers:
      my_trigger1:
        blah:
          blah:
      my_trigger2:
        blah:
          blah:
    
      actions:
        my_action1:
          blah:
            blah:
        my_action2:
          blah:
            blah:

    引用

    在所有类型中,只有数组类型需要双引号。

    好:

    input:
      array:
        description: Array of things
        type: "[]string"

    坏:

    input:
      url:
        type: "string" # This shouldn't be quoted
        description: URL to Download
        required: "true" # This shouldn't be quoted

    标点符号

    不要添加句子标点符号titlesdescriptions。他们也不应该出现在任何其他领域。应在规范的帮助部分的正文中使用标点符号。

    标签

    要求:*小写字符*允许的数字*没有下划线

    tags: [ "malware", "ioc", "rat", "trojan", "remote" ]

    提交消息

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

    规则

    • 使用命令,例如Fix代替FixedFixes
    • 第一封描述信应该大写
    • 使用形式:尽可能

    请参阅Git最佳实践

    动作和触发器名称

    plugin.spec.yaml使用title密钥在文件中指定名称。好风格的例子如下:

    actions:
      match_string:
        title: Match String
        description: Match string from a text file
      match_number:
        title: Match Number
        description: Match number from a text file
      extract:
        title: Extract
        description: Extract files from archive

    规则

    • title不应该超过四个字。该描述旨在给出其余细节。
    • 因为它是标题,所以每个单词都title应该首字母大写。这条规则的例外是文章和连词例如。Match StringParse an Assortment
    • 第一个字description应该是第一个字母大写,而不是与title Eg 相同Match string from text file

    属性名称

    属性名称在此处定义。这些包括输入/​​输出变量,动作,触发器和连接名称。

    共同

    • host - 中性:当IP地址或域名可以是值时使用。
    • address - 仅用于IP地址值(例如,IPv4或IPv6) 8.8.8.8
    • domain - 仅用于域名值,例如 www.google.com
    • url - 仅用于url值,例如 https://product.company.com:1234
    • ssl_verify - 布尔属性,用于决定是否验证SSL证书

    规则

    • 名称应为小写,例如 timeout
    • 名称应简明扼要并代表其目的,如果可能,限制为2个字 ountry_code
    • 如果不简洁,请使用下划线分隔单词 metro_code
    • 除非API要求,否则不允许使用字母和下划线以外的字符

    变更日志

    我们在plugin.spec.yaml中插件的help属性的Version部分中记录了changelog历史记录。格式是其中X的表示语义版本和消息文档的改变。x.x.x - <Message>

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

    • Support web server mode - 对于Web服务器模式支持,即新的父级Docker镜像,v2插件规范版本和新的self.logger使用
    • Update to new credential types - 支持新的凭证类型,例如credential_username_password,credential_secret_key
    • Update to v2 Python plugin architecture - 用于移植到Python v2 arch
    • Update to new secret key credential type - 使用单个新凭证类型,特定于此示例中的credential_secret_key
    • New action <Action Title> - 对于新的行动,例如 New action Remove from Policy
    • New actions <Action Title> and <Action Title> - 有关两个新动作的列表
    • New actions <Action Title>, <Action Title> and <Action Title> - 有关两个以上新动作的列表
    • New trigger <Trigger Title> - 对于新的触发器
    • New triggers <Trigger Title> and <Trigger Title> - 有关两个新触发器的列表
    • New actions <Action Title>, <Action Title> and <Action Title> - 有关两个以上新触发器的列表
    • New trigger <Trigger Title> | New actions <Action Title>, <Action Title> and <Action Title> - 用于新触发器和多个动作
    • Fix issue where <bug description> - 对于错误修复,例如 Fix issue in connection that can cause a failure with valid credentials
    • Run plugin as least privileged user-为了表明设置在USER nobodyDockerfile

    对于许多人来说,将它们与|连接起来 人物,例如:

    • Update to v2 Python plugin architecture | Support web server mode | Update to new credential types
    • Update to new credential types | New action Disable User

    错误

    请参阅新的“ 集成错误处理”指南。

    触发

    输入

    对于可用性,所有触发器都应支持一个名为interval的输入,该输入以SDKs语言传递给sleep机制:

    frequency:
      type: integer
      description: "Poll frequency in seconds"
      default: 300
      required: false

    连接

    风格

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

    记录

    默认使用...占位

    def connection(self, data={}):
    	# write your code
    	...

    依赖

    Dockerfile

    所有插件都可以使用修改Dockerfile来为插件添加依赖项。通常使用RUN和/或ADD Dockerfile命令添加依赖项。

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

    规则:

    • 需要固定版本的依赖包
    • 对于Debian软件包,必须在软件包安装之前使用apt-get update
    • 除非技术限制要求,否则不应用于Python包安装

    requirements.txt

    我们使用requirements.txt文件来获取依赖项。

    规则:

    • 需要固定版本的依赖包 requirements.txt

    例如

    $ cat powershell/requirements.txt
    pywinrm==0.2.2
    pykerberos==1.2.1
    requests-kerberos==0.12.0
image-missing