ecsgen

package module
v0.0.0-...-8e53b5f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 1, 2020 License: Apache-2.0 Imports: 5 Imported by: 0

README

ecsgen

This project aims to create a well defined way to perform code generation on Elastic Common Schema definitions. Originally, this was intended to be specific to Go, but is built in a way that implementing new output generators is easy.

Install

go install github.com/gen0cide/ecsgen/cmd/ecsgen

Usage

To use ecsgen, there are a few options:

--source-file value                   Path to the generated ecs_flat.yml file containing ECS definitions. [$ECSGEN_SOURCE_FILE]
--whitelist value                     Regular expression that denotes which ECS keys to allow into the model. (Can be used multiple times). [$ECSGEN_WHITELIST_VALUE]
--blacklist value                     Regular expression that denotes which ECS keys to explicitly forbid into the model. (Can be used multiple times). [$ECSGEN_BLACKLIST_VALUE]
--output-plugin value                 Enable an output generator plugin. Can be used multiple times. Possible values: debug, gostruct [$ECSGEN_OUTPUT_PLUGIN]

The only required ones are --source-file that points to the ecs_flat.yml ECS definition, as well as at least one --output-plugin.

Examples

Check out the examples/ folder.

Current Output Plugins

The current list of usable output plugins is:

gostruct

Gostruct is used to generate Go code for an ECS object. It has a few options:

--opt-gostruct-package-name value     Name of the Go package for the generated code. [$ECSGEN_OPT_GOSTRUCT_PACKAGE_NAME]
--opt-gostruct-output-dir value       Path to the directory where the generated code should be written. [$ECSGEN_OPT_GOSTRUCT_OUTPUT_DIR]
--opt-gostruct-output-filename value  Destination filename for the generated code. (default: generated_ecs.go) [$ECSGEN_OPT_GOSTRUCT_OUTPUT_FILENAME]
--opt-gostruct-marshal-json           Include a json.Marshaler implementation that removes empty fields. (default: false) [$ECSGEN_OPT_GOSTRUCT_MARSHAL_JSON]

The --opt-gostruct-marshal-json is shown in the examples/go/with-json-marshaling example directory.

Documentation

Index

Constants

View Source 
const Version = `0.0.1`

Version is the version of the ecsgen library.

Variables

View Source 
var DefaultInitialisms = Initialisms{
	"AMI",
	"PPID",
	"PID",
	"PGID",
	"MAC",
	"IP",
	"NAT",
	"IANA",
	"UID",
	"ECS",
	"AS",
	"DLL",
	"OS",
	"DNS",
	"HTTP",
	"PE",
	"JA3",
	"JA3s",
	"VLAN",
	"ISO",
	"MIME",
	"MD5",
	"SHA1",
	"SHA256",
	"SHA512",
	"UUID",
}

DefaultInitialisms are the default initialisms we set. You can set more via init functions by calling the AddIdentifierInitialism function.

View Source 
var ErrSkipChildren = errors.New("node walker: skip remaining children")

ErrSkipChildren is a used as a return value from WalkFuncs to indicate that the callback should not be called for any children of the examined Node.

Functions

func AddIdentifierInitialism 

func AddIdentifierInitialism(s ...string)

AddIdentifierInitialism is used to add custom initializations into the library.

func Walk 

func Walk(root Walkable, fn WalkFunc) error

Walk is a simple depth first walker for traversing the Schema from a starting Node.

Types

type AllowedValue 

type AllowedValue struct {
	Name               string   `config:"name" json:"name,omitempty" yaml:"name,omitempty" mapstructure:"name,omitempty"`
	Description        string   `config:"description" json:"description,omitempty" yaml:"description,omitempty" mapstructure:"description,omitempty"`
	ExpectedEventTypes []string `` /* 151-byte string literal not displayed */
}

AllowedValue defines a field level constrait setting within an ECS schema Definition.

type Definition 

type Definition struct {
	ID               string          `config:"-" json:"id,omitempty" yaml:"id,omitempty" mapstructure:"id,omitempty"`
	AllowedValues    []*AllowedValue `` /* 127-byte string literal not displayed */
	DashedName       string          `config:"dashed_name" json:"dashed_name,omitempty" yaml:"dashed_name,omitempty" mapstructure:"dashed_name,omitempty"`
	Description      string          `config:"description" json:"description,omitempty" yaml:"description,omitempty" mapstructure:"description,omitempty"`
	DocValues        bool            `config:"doc_values" json:"doc_values,omitempty" yaml:"doc_values,omitempty" mapstructure:"doc_values,omitempty"`
	Example          interface{}     `config:"example" json:"example,omitempty" yaml:"example,omitempty" mapstructure:"example,omitempty"`
	FlatName         string          `config:"flat_name" json:"flat_name,omitempty" yaml:"flat_name,omitempty" mapstructure:"flat_name,omitempty"`
	Format           string          `config:"format" json:"format,omitempty" yaml:"format,omitempty" mapstructure:"format,omitempty"`
	IgnoreAbove      int             `config:"ignore_above" json:"ignore_above,omitempty" yaml:"ignore_above,omitempty" mapstructure:"ignore_above,omitempty"`
	Index            bool            `config:"index" json:"index,omitempty" yaml:"index,omitempty" mapstructure:"index,omitempty"`
	InputFormat      string          `config:"input_format" json:"input_format,omitempty" yaml:"input_format,omitempty" mapstructure:"input_format,omitempty"`
	Level            string          `config:"level" json:"level,omitempty" yaml:"level,omitempty" mapstructure:"level,omitempty"`
	MultiFields      []*MultiField   `config:"multi_fields" json:"multi_fields,omitempty" yaml:"multi_fields,omitempty" mapstructure:"multi_fields,omitempty"`
	Name             string          `config:"name" json:"name,omitempty" yaml:"name,omitempty" mapstructure:"name,omitempty"`
	Normalize        []string        `config:"normalize" json:"normalize,omitempty" yaml:"normalize,omitempty" mapstructure:"normalize,omitempty"`
	Order            int             `config:"order" json:"order,omitempty" yaml:"order,omitempty" mapstructure:"order,omitempty"`
	OriginalFieldset string          `` /* 139-byte string literal not displayed */
	OutputFormat     string          `config:"output_format" json:"output_format,omitempty" yaml:"output_format,omitempty" mapstructure:"output_format,omitempty"`
	OutputPrecision  string          `` /* 135-byte string literal not displayed */
	Short            string          `config:"short" json:"short,omitempty" yaml:"short,omitempty" mapstructure:"short,omitempty"`
	Type             string          `config:"type" json:"type,omitempty" yaml:"type,omitempty" mapstructure:"type,omitempty"`
}

Definition represents the YAML definition in the ECS generated "ecs_flat.yml" schema definition. nolint:maligned

type Identifier 

type Identifier struct {
	// contains filtered or unexported fields
}

Identifier is used to create various cases and pluralities of the enums being generated.

func NewIdentifier 

func NewIdentifier(s string) Identifier

NewIdentifier creates a new identifier from a provided string.

func (Identifier) Camel 

func (i Identifier) Camel() string

Camel returns the identifiers camelCase representation.

func (Identifier) Command 

func (i Identifier) Command() string

Command returns the identifiers command-case representation.

func (Identifier) Dotted 

func (i Identifier) Dotted() string

Dotted returns the identifiers dotted.case representation.

func (Identifier) Ident 

func (i Identifier) Ident() flect.Ident

Ident returns the identifiers underlying flect structure.

func (Identifier) Pascal 

func (i Identifier) Pascal() string

Pascal returns the identifiers PascalCase representation.

func (Identifier) Screaming 

func (i Identifier) Screaming() string

Screaming returns the identifiers SCREAMING_CASE representation.

func (Identifier) Snake 

func (i Identifier) Snake() string

Snake returns the identifier's snake_case representation.

func (Identifier) Train 

func (i Identifier) Train() string

Train returns the identifiers TRAIN-CASE representation.

type Initialisms 

type Initialisms []string

Initialisms is a type alias for a slice of strings that is used to create capitalization identifiers for strings used.

type MultiField 

type MultiField struct {
	FlatName string `config:"flat_name" json:"flat_name,omitempty" yaml:"flat_name,omitempty" mapstructure:"flat_name,omitempty"`
	Name     string `config:"name" json:"name,omitempty" yaml:"name,omitempty" mapstructure:"name,omitempty"`
	Norms    bool   `config:"norms" json:"norms,omitempty" yaml:"norms,omitempty" mapstructure:"norms,omitempty"`
	Type     string `config:"type" json:"type,omitempty" yaml:"type,omitempty" mapstructure:"type,omitempty"`
}

MultiField defines a multi-field setting within an ECS schema Definition.

type Node 

type Node struct {
	// Name is the single name of the Node. For example,
	// the Node "client.nat", the name should equal "nat".
	Name string

	// Path is the absolute path from the root of a Node. For example,
	// the Node "client.nat" has a Path equal to "client.nat".
	Path string

	// Parent is a pointer to this Node's parent. For top level objects,
	// this will be nil. For all children this will equal the parent.
	// Example: Node("client.nat").Parent => Node("client")
	Parent *Node

	// Root is a reference to the root namespace.
	Root *Root

	// Children are a map of all child nodes that belong to this node. The key
	// is the Name field of the child, and the value is a pointer to the Node itself.
	// Example: Node("client.nat") has a child ["ip"] => Node("client.nat.ip").
	Children map[string]*Node

	// Definition is used to link back to the source of truth YAML definition
	// that was parsed for this Node. This is garanteed to be non-nil for all Nodes
	// that are of type "field", but is generally nil for objects, as ECS
	// treats them mostly as implicit.
	Definition *Definition
}

Node represents a single element within the ECS definition graph. A node represents either an "object" - something that has child fields - or a "field" - something that represents a simple scalar field. The goal is for all nodes within ECS to be mapped to a tree graph, where each Node represents a vertex. Any vertex with children thus is an "object", and any "leafs" are therefor "fields".

func (*Node) Child 

func (n *Node) Child(name string) *Node

Child is used to resolve a child Node from a specific Node. The name argument should be a relative "Name" and *not* an absolute path. For example, if you wanted to retrieve the "client.nat" child from the "client" Node, you would pass "nat". If the child does not exist, it is created. If it does exist, the existing child is returned. If you pass it an empty string, the Node will simply return itself.

func (*Node) FieldIdent 

func (n *Node) FieldIdent() Identifier

FieldIdent creates an Identifier that can be used as a field reference. This is used to create Go struct fields for every Node. The returned Identifier is equal to NewIdentifier(n.Name).

func (*Node) IsArray 

func (n *Node) IsArray() bool

IsArray is used to determine if the given Node within the ECS schema is actually an array of it's noted data type.

func (*Node) IsImplied 

func (n *Node) IsImplied() bool

IsImplied IsImplied is used to determine if a node is implied via the schema. This is true for the majority of objects in the schema, while false for all fields.

func (*Node) IsObject 

func (n *Node) IsObject() bool

IsObject attempts to determine if the Node is an "object" or a "field" and returns accordingly. This function contains edge-case code within the schema to account for one offs, and should be trusted to do the right thing.

func (*Node) IsTopLevel 

func (n *Node) IsTopLevel() bool

IsTopLevel returns true if the Node has no Parent, therefor indicating it belongs in top level namespace.

func (*Node) ListChildren 

func (n *Node) ListChildren() <-chan *Node

ListChildren implements the Walkable interface.

func (*Node) TypeIdent 

func (n *Node) TypeIdent() Identifier

TypeIdent creates an Identifier based on the Node's type. This is almost never called for fields, but is required for objects. *Node.GoType() uses this to create object types. The returned Identifier is equal to NewIdentifier(n.Path).

type Root 

type Root struct {
	// TopLevel is the top level namespace for nested objects
	TopLevel map[string]*Node

	// Index holds references to each node by absolute path
	Index map[string]*Node
}

Root defines the top level namespace within an ECS schema. It is the top level data structure used to create the schema tree.

func NewRoot 

func NewRoot() *Root

NewRoot creates an empty Root.

func (*Root) Branch 

func (r *Root) Branch(branchpath string) *Node

Branch is used to resolve Nodes within the tree. It will create all previously unknown Node's within the graph to traverse to the specified path. For example, if you passed "client.as.organization.name", it would perform the following lookups: Node("client").Child("as").Child("organization").Child("name").

func (*Root) ListChildren 

func (r *Root) ListChildren() <-chan *Node

ListChildren implements the Walkable interface.

type WalkFunc 

type WalkFunc func(n *Node) error

WalkFunc is the type of the function called for each child of a node.

type Walkable 

type Walkable interface {
	ListChildren() <-chan *Node
}

Walkable represents types that can be walked within ecsgen. This allows walking from arbitrary points within the graph, as well as from the root.

Source Files

View all Source files

Directories

Path Synopsis
cmd
ecsgen
examples
go/basic
Code generated by ecsgen; DO NOT EDIT.
 Code generated by ecsgen; DO NOT EDIT.
go/with-json-marshaling
Code generated by ecsgen; DO NOT EDIT.
 Code generated by ecsgen; DO NOT EDIT.
debug
gostruct

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.