Add translate_sid processor (#16013)

* Add translate_sid processor to Winlogbeat

The `translate_sid` processor translates a Windows security identifier (SID)
into an account name. It retrieves the name of the account associated with the
SID, the first domain on which the SID is found, and the type of account.

Closes #7451

libbeat/cmd/instance/imports_common.go

@@ -35,5 +35,6 @@ import (
 	_ "github.com/elastic/beats/libbeat/processors/extract_array"
 	_ "github.com/elastic/beats/libbeat/processors/fingerprint"
 	_ "github.com/elastic/beats/libbeat/processors/registered_domain"
+	_ "github.com/elastic/beats/libbeat/processors/translate_sid"
 	_ "github.com/elastic/beats/libbeat/publisher/includes" // Register publisher pipeline modules
 )

libbeat/docs/processors-list.asciidoc

@@ -95,6 +95,9 @@ endif::[]
 ifndef::no_truncate_fields_processor[]
 * <<truncate-fields, `truncate_fields`>>
 endif::[]
+ifdef::no_translate_sid_processor[]
+* <<processor-translate-sid, `translate_sid`>>
+endif::[]
 //# end::processors-list[]
 
 //# tag::processors-include[]
@@ -191,6 +194,9 @@ endif::[]
 ifndef::no_truncate_fields_processor[]
 include::{libbeat-processors-dir}/actions/docs/truncate_fields.asciidoc[]
 endif::[]
+ifdef::no_translate_sid_processor[]
+include::{libbeat-processors-dir}/translate_sid/docs/translate_sid.asciidoc[]
+endif::[]
 
 //# end::processors-include[]
 

libbeat/docs/shared-beats-attributes.asciidoc

@@ -6,6 +6,7 @@
 :libbeat-processors-dir: {beats-root}/libbeat/processors
 :libbeat-outputs-dir: {beats-root}/libbeat/outputs
 :x-filebeat-processors-dir: {beats-root}/x-pack/filebeat/processors
+:winlogbeat-processors-dir: {beats-root}/winlogbeat/processors
 
 :cm-ui: Central Management
 :libbeat-docs: Beats Platform Reference

libbeat/processors/translate_sid/config.go

@@ -0,0 +1,41 @@
+// Licensed to Elasticsearch B.V. under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Elasticsearch B.V. licenses this file to you under
+// the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package translate_sid
+
+import "github.com/pkg/errors"
+
+type config struct {
+	Field             string `config:"field"  validate:"required"`
+	AccountNameTarget string `config:"account_name_target"`
+	AccountTypeTarget string `config:"account_type_target"`
+	DomainTarget      string `config:"domain_target"`
+	IgnoreMissing     bool   `config:"ignore_missing"`
+	IgnoreFailure     bool   `config:"ignore_failure"`
+}
+
+func (c *config) Validate() error {
+	if c.AccountNameTarget == "" && c.AccountTypeTarget == "" && c.DomainTarget == "" {
+		return errors.New("at least one target field must be configured " +
+			"(set account_name_target, account_type_target, and/or domain_target)")
+	}
+	return nil
+}
+
+func defaultConfig() config {
+	return config{}
+}

libbeat/processors/translate_sid/doc.go

@@ -0,0 +1,20 @@
+// Licensed to Elasticsearch B.V. under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Elasticsearch B.V. licenses this file to you under
+// the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// Package translate_sid provides a Beat processor for converting Windows
+// security identifiers (SIDs) to account names.
+package translate_sid

libbeat/processors/translate_sid/docs/translate_sid.asciidoc

@@ -0,0 +1,46 @@
+[[processor-translate-sid]]
+=== Translate SID
+
+beta[]
+
+The `translate_sid` processor translates a Windows security identifier (SID)
+into an account name. It retrieves the name of the account associated with the
+SID, the first domain on which the SID is found, and the type of account. This
+is only available on Windows.
+
+Every account on a network is issued a unique SID when the account is first
+created. Internal processes in Windows refer to an account's SID rather than
+the account's user or group name and these values sometimes appear in logs.
+
+If the SID is invalid (malformed) or does not map to any account on the local
+system or domain then this will result in the processor returning an error
+unless `ignore_failure` is set.
+
+[source,yaml]
+----
+processors:
+- translate_sid:
+    field: winlog.event_data.MemberSid
+    account_name_target: user.name
+    domain_target: user.domain
+    ignore_missing: true
+    ignore_failure: true
+----
+
+The `translate_sid` processor has the following configuration settings:
+
+.Translate SID options
+[options="header"]
+|======
+| Name                  | Required | Default    | Description
+| `field`               | yes      |            | Source field containing a Windows security identifier (SID).
+| `account_name_target` | yes*     |            | Target field for the account name value.
+| `account_type_target` | yes*     |            | Target field for the account type value.
+| `domain_target`       | yes*     |            | Target field for the domain value.
+| `ignore_missing`      | no       | false      | Ignore errors when the source field is missing.
+| `ignore_failure`      | no       | false      | Ignore all errors produced by the processor.
+|======
+
+* At least one of `account_name_target`, `account_type_target`, and
+`domain_target` is required to be configured.
+

libbeat/processors/translate_sid/translatesid.go

@@ -0,0 +1,124 @@
+// Licensed to Elasticsearch B.V. under one or more contributor
+// license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright
+// ownership. Elasticsearch B.V. licenses this file to you under
+// the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+// +build windows
+
+package translate_sid
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/pkg/errors"
+	"go.uber.org/multierr"
+	"golang.org/x/sys/windows"
+
+	"github.com/elastic/beats/libbeat/beat"
+	"github.com/elastic/beats/libbeat/common"
+	"github.com/elastic/beats/libbeat/logp"
+	"github.com/elastic/beats/libbeat/processors"
+	jsprocessor "github.com/elastic/beats/libbeat/processors/script/javascript/module/processor"
+	"github.com/elastic/beats/winlogbeat/sys"
+)
+
+const logName = "processor.translate_sid"
+
+var errInvalidType = errors.New("SID field value is not a string")
+
+func init() {
+	processors.RegisterPlugin("translate_sid", New)
+	jsprocessor.RegisterPlugin("TranslateSID", New)
+}
+
+type processor struct {
+	config
+	log *logp.Logger
+}
+
+// New returns a new translate_sid processor for converting windows SID values
+// to names.
+func New(cfg *common.Config) (processors.Processor, error) {
+	c := defaultConfig()
+	if err := cfg.Unpack(&c); err != nil {
+		return nil, errors.Wrap(err, "fail to unpack the translate_sid configuration")
+	}
+
+	return newFromConfig(c)
+}
+
+func newFromConfig(c config) (*processor, error) {
+	return &processor{
+		config: c,
+		log:    logp.NewLogger(logName),
+	}, nil
+}
+
+func (p *processor) String() string {
+	return fmt.Sprintf("translate_sid=[field=%s, account_name_target=%s, account_type_target=%s, domain_target=%s]",
+		p.Field, p.AccountNameTarget, p.AccountTypeTarget, p.DomainTarget)
+}
+
+func (p *processor) Run(event *beat.Event) (*beat.Event, error) {
+	err := p.translateSID(event)
+	if err == nil || p.IgnoreFailure || (p.IgnoreMissing && common.ErrKeyNotFound == errors.Cause(err)) {
+		return event, nil
+	}
+	return event, err
+}
+
+func (p *processor) translateSID(event *beat.Event) error {
+	v, err := event.GetValue(p.Field)
+	if err != nil {
+		return err
+	}
+	sidString, ok := v.(string)
+	if !ok {
+		return errInvalidType
+	}
+
+	// All SIDs starting with S-1-15-3 are capability SIDs. Active Directory
+	// does not resolve them so don't try.
+	// Reference: https://support.microsoft.com/en-us/help/243330/well-known-security-identifiers-in-windows-operating-systems
+	if strings.HasPrefix(sidString, "S-1-15-3-") {
+		return windows.ERROR_NONE_MAPPED
+
+	}
+
+	sid, err := windows.StringToSid(sidString)
+	if err != nil {
+		return err
+	}
+
+	// XXX: May want to introduce an in-memory cache if the lookups are time consuming.
+	account, domain, accountType, err := sid.LookupAccount("")
+	if err != nil {
+		return err
+	}
+
+	// Do all operations even if one fails.
+	var errs []error
+	if _, err = event.PutValue(p.AccountNameTarget, account); err != nil {
+		errs = append(errs, err)
+	}
+	if _, err = event.PutValue(p.AccountTypeTarget, sys.SIDType(accountType).String()); err != nil {
+		errs = append(errs, err)
+	}
+	if _, err = event.PutValue(p.DomainTarget, domain); err != nil {
+		errs = append(errs, err)
+	}
+	return multierr.Combine(errs...)
+}