This is a base document to define how modules for Furnace should be built and packaged to be compatible with the platform. This definition is currently a draft so it may change in the future.
One of the main focus of the Furnace project is to make Dev/Sec/Ops life easier. As such, the modules should be built based on a series of premises that should always be kept in mind:
A basic parameters file has to include any relevant details about the module
The compression has to be based on some widely-adopted format
Folder structure should be simple, specific and self explanatory
├── info.yaml├── config.yaml└── module/├── index.js└── ...
As can be seen, it is a really simple folder structure, with an info.yaml and a config.yaml files on the root and a modulefolder with all the code for the module, which can include subfolders.
The chosen compression format is ZIP, with the mentioned folder structure directly at the root level of the ZIP file. Any compression level can be used, but given the fact that the file will only be uncompressed once, using the maximum possible level is suggested. No encryption should be used in the ZIP file.
An MD5 file named module.md5 should be provided along with the module.zip file containing the MD5 sum of the module.zip file.
The module description file (info.yaml) contains basic information about the module, dependencies and its authors.
It is structured as a yaml file. The minimal info.yaml file looks like this:
id: my-moduleversion: 1.0.0category: ingestruntime: nodejs8.10core-version:min: 0.1.0max: 0.3.1meta:name: My Moduledescription: This is the description for the module My Modulekeywords: [my-module, furnace]website: https://projectfurnace.github.ioauthor:name: Project Furnacelicense: MIT
Whereas a more extended version with additional information would look like this:
id: my-moduleversion: 1.0.0category: ingestruntime: nodejs8.10core-version:min: 0.1.0max: 0.3.1meta:name: My Moduledescription: This is the description for the module My Modulekeywords: [my-module, furnace]website: https://projectfurnace.github.ioauthor:name: Project Furnacewebsite: https://twitter.com/projectfurnaceemail: email@example.com:- name: A Contributorwebsite: https://twitter.com/acontributoremail: firstname.lastname@example.org- name: D Contributorlicense: MITdependencies:- my-other-module: >=1.0.1
id (Mandatory, 64 chars, [a-z-_]): A module identifier. It will be used as the ZIP name.
version (Mandatory, 8 chars, [0-9.]): The module version. Should always be incremental and in the format XX.YY.ZZ
category (Mandatory, Fixed list of options): What category this module belongs to. Options are: ingest, enrich, filter, action and sink.
runtime (Mandatory, Fixed list of options): What runtime to be used to run this module. Options are: nodejs6.10, nodejs8.10, python2.7, python3.6, go1.x.
core-version (Mandatory): Used to specify what is the minimum and maximum version of the core this module will work with.
min: The oldest version of Furnace core the module will work with.
max: The newest version of Furnace core the module will work with.
name (Mandatory): The module name that will show both on the UI and in the marketplace.
description (Mandatory): Description for the module to be shown in the marketplace.
keywords: Keywords to associate with the module. Those will be used in the marketplace.
website: Website associated with the module. This will be used in the marketplace.
name (Mandatory): Module author name.
website: Author website.
email: Author email address.
name: Contributor name. website: Contributor website. email: Contributor email address.
license: License for the module
dependencies: A list of other Furnace modules this specific module depends on. Format to specify them is '- module-id: version' where version is the version number preceded by:
>= (higher or equal)
<= (lower or equal)
just the version number itself for an exact match
The configuration parameters file (config.yaml) describes all the configuration parameters the module accepts.
It is structured as a yaml file. If a module has no configurable parameters the file can be empty or missing.
id: my-moduleversion: 1.0.0config-groups:config-group-name:param-id:label: Enrich on fieldmandatory: truetype: singledefault: network.ipv4_srcvisible: truevalidator: '[A-z\._]+'optionset:- network.ipv4_src: Source IP- network.ipv4_dst: Destination IPhelp: Specify the field for which to do the Geo IP lookupother-config-group:other-param-id:label: Tag withmandatory: truetype: textdefault: siemvisible: truevalidator: '[A-z]+'
id (Mandatory, 64 chars, [a-z-_]): A module identifier. It must match the one in info.yaml.
version (Mandatory, 8 chars, [0-9.]): The module version. It must match the one in info.yaml.
config-groups: This groups the different config blocks.
config-group-name: The name of this specific config group as shown in the UI.
param-id: An identifier for the configuration parameter. Will need to match the var name in code.
label: The label to use in the UI.
mandatory: Whether it is mandatory or not to fill this field.
type: What type of field is this. Options are: text, single, multi.
default: The default value for the field.
visible: Whether or not this config parameter is visible in the UI.
validator: A valid regex expression to be used to validate the value provided as configuration parameter.
optionset: List of valid values for the field if those are only a few. Described as a key-value array with the value as the key and the label as the value.
help: Tips for help in the UI.