In this document: 

Overview

The purpose of this document is to describe:

  • How the Webhook platform processes events, incidents, and detections

  • How tags are used within agent 3.0

  • How tags are used with Log Relay, cloud based logging, and flows

  • How to use the transform configuration file

  • How to use the Webhook configuration file

Security incidents, detections, and events are supported by the Armor Webhook platform. Configuration files allow you to subscribe to events, detections, and incidents. Subscribed topics are then enriched with default values, values from the Armor tags implementation, and related to a Kibana link (if applicable). Each type of transform is labeled in the transformation configuration as: add_tag, add_dynamic_tag, and add_log_search_url. In addition, Webhook destinations can be configured with uri, header(s), and on_error email destinations.

Tags Usage With Agent 3.0

The latest Armor Agent supports new Command Line Interface (CLI) functions and customization, such as the selection of security services to install and leverage. In addition, tags can be created directly using the agent CLI as well as creating them directly with POST requests to the Armor Tags API.

Below are the steps required to install and add tags through the Armor Core Agent.

  1. Install the Armor Agent

    1. Linux

      $ sudo mkdir /opt/armor && sudo curl -o /tmp/armor-linux.tar.gz https://agent.armor.com/latest/armor-linux.tar.gz && sudo tar zxvf /tmp/armor-linux.tar.gz -C /opt/armor && sudo /opt/armor/armor register --license XXXXX-XXXXX-XXXXX-XXXXX-XXXXX --region us-east-1

    2. Windows

      [System.Reflection.Assembly]::LoadWithPartialName("System.IO.Compression.FileSystem");[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12;mkdir c:\.armor\opt; Invoke-WebRequest https://agent.armor.com/latest/armor-windows.zip -outfile c:\.armor\opt\armor-windows.zip;[System.IO.Compression.ZipFile]::ExtractToDirectory('c:\.armor\opt\armor-windows.zip','c:\.armor\opt'); c:\.armor\opt\armor.exe register --license XXXXX-XXXXX-XXXXX-XXXXX-XXXXX --region us-east-1

  2. After installation, tags can be managed through the CLI command: ./armor tags create-tags

    # ./armor tags create-tags key=value,key2=value2

Tags Usage For Log Relay, Coud Based Logging, and Flows

Tags for Log Relay, cloud based logging, and flows are handled manually in the Armor platform. End users are required to gather unique IDs which Armor will use to create the resources in the tags endpoint. Once the correct tagging resource IDs are loaded, the Armor Webhook platform will automatically load them into enrichment for the detection of future security incidents.

Log Relay

Log Relay tags are identified using the Armor core instance ID of the Log Relay appliance and the corresponding unique identifier of the device sending the logs (found here).


The tags endpoint is then called with the Log Relay core instance ID and the device specific unique identifier e.g. (4f730b6e-1336-4302-b5bf-957478c4eb3d and host.example.com):

POST /tags/4f730b6e-1336-4302-b5bf-957478c4eb3d::host.example.com
//Request Body:
{
    "tags":
        [
            {"Key":"id","Value":"companyX"},
            {"Key":"index","Value":"production"}
        ]
}
If the full resource Id (4f730b6e-1336-4302-b5bf-957478c4eb3d::host.example.com) is not found, the base Log Relay core instance id (4f730b6e-1336-4302-b5bf-957478c4eb3d) is referenced for tags information.
If no tag resource Id is found, then add_dynamic_tag will not add any fields to the Webhook payload.

Cloud Based Logs

Cloud based logs (e.g. Guard Duty and AWS Cloud Trail) are assigned unique identifiers from the Armor platform and require a log into AMP to gain access to them. The identifiers can be accessed from “HOSTNAME” column at https://portal.armor.com/security/log-management?activeTab=tab-External-Sources.


The tags endpoint is then called with:

POST /tags/guardduty--#######8823--multi-azs
//Request Body:
{
    "tags":
        [
            {"Key":"id","Value":"companyX"},
            {"Key":"index","Value":"production"}
        ]
}


Flows

Flow log collection is new to Armor and is subject to change as we update ingestion methods and device support. Currently, AWS VPC Flow logs are the only supported flow type. As customer flows are enabled in the Armor Platform, a flow collector endpoint is assigned in the SIEM. This endpoint binds all flow traffic to the specific customer account. Tagging is implemented at the customer account level when leveraging add_dynamic_tag to enrich flow logs in the Webhook platform.

To gather the flow unique ID for the customer account, you will need an account on the Armor platform with IMC access. The flow configuration is available at: https://portal.armor.com/security/log-management?activeTab=tab-Flow-Sources. Flows can be activated for the customer account at https://portal.armor.com/security/log-management/new-source.

Enable Flows for Customer Account

https://portal.armor.com/security/log-management/new-source

Gather Unique Identifier for Flows

https://portal.armor.com/security/log-management?activeTab=tab-Flow-Sources

The tags endpoint is then called with

POST /tags/siem_flow_107
//Request Body:
{
    "tags":
        [
            {"Key":"id","Value":"companyX"},
            {"Key":"index","Value":"production"}
        ]
}


How To Use the Transform Configuration File

The transform configuration file is loaded into each customer account subscribed to one or all of the account and child account detection, incidents, and/or events.

Whitelisting or blacklisting of child accounts at the parent level is not supported. All child accounts are automatically processed and require the end user to filter accounts or events if required.

The configuration is broken into 6 parts: org_id, name, format, events, defaults, and transform.

  • org_id

    • Used by Armor to track the account for which the configuration applies.

  • name

    • A short name describing the transform configuration

  • format

    • Can be DEFAULT or SPLUNK

  • events

    • Contains a string array of types of data which will be added to the payload and sent to the Webhook endpoints.

    • security_incident

      • Armor incidents are security detections which have been processed by Armor to be escalated as a full incident.

    • security_detection

      • Security detections are any correlated detection in the Armor platform which hasn’t been escalated to an incident.

    • security_event

      • The raw events which belong to the correlated detection or incident.

  • defaults

    • Use this section to define properties which are added to event, detection, or incident that is processed by the Webhook platform. NOTE: Transform configs are applied at the account level.

    • “type": "add_tag"

      • add_tag is the only supported type in defaults.

    • "key": "[nested].key"

      • Defines the name of the property added to the payload object

    • "value": "Alpha"

      • The value that is placed in the property or nested property.

  • transform

    • Use this section to define transforms that require the lookup of additional data to complete.

    • add_dynamic_tag

      • Supports the Armor Tags API to enrich events.

    • add_log_search_url

      • Supports events which have the “eventId” property and can add linkable Kibana queries directly to the correlated event.

{
  "org_id": 1000,
  "name": "Hello world config",
  "format": "splunk",
  "events": [
    "security_incident",
    "security_detection",
    "security_event"
  ],
  "defaults": [
    {
      "type": "add_tag",
      "key": "rcn_idx",
      "value": "Alpha"
    },
    {
      "type": "add_tag",
      "key": "rax_id",
      "value": "Lotlux"
    },
    {
      "type": "add_tag",
      "key": "rms_id",
      "value": "Cardify"
    },
    {
      "type": "add_tag",
      "key": "provider_id",
      "value": "Home Ing"
    }
  ],
  "transform": [
    {
      "type": "add_dynamic_tag",
      "key": "index",
      "value": "{{index}}"
    },
    {
      "type": "add_dynamic_tag",
      "key": "[event].rax_id",
      "value": "{{rax_id}}"
    },
    {
      "type": "add_dynamic_tag",
      "key": "[event].rms_id",
      "value": "{{rms_id}}"
    },
    {
      "type": "add_dynamic_tag",
      "key": "[event].provider_id",
      "value": "{{provider_id}}"
    },
    {
      "type": "add_dynamic_tag",
      "key": "[event].provider_type",
      "value": "{{provider_type}}"
    },
    {
      "type": "add_log_search_url",
      "key": "link_event_kibana",
      "value": "event_uuid"
    }
  ]
}


How To Use the Webhook Configuration File

The Webhook configuration file is loaded into each customer account subscribing to one or all of the account and child account detections, incidents, and/or events. It contains the target of the Webhook and error handling options.

The configuration is broken into 6 parts: org_id, name, on_error, and values. At release, on_error supports ‘email’ type only and values only supports a single uri and any number of defined header types. All headers are added to the Webhook request automatically.

  • org_id Used by Armor to track the account for which the configuration applies.

  • name A short name describing the Webhook configuration

  • on_error Use this section to define how errors can be received if the destination is unavailable or inaccessible for delivery.

    • “type": "email"

      • email is the only supported type.

    • "key": "value"

      • The email address where errors are sent

  • values This section contains the uri and header(s) for the target destination Webhook.

    • "type": "uri" The full URI (with port and scheme) of the target destination Webhook.

    • "type": "header" Allows the control of headers placed in the request to the target destination. Headers are loaded “as is” with no attempt sanitize what gets placed in the request. This allows for full customization of any header formats.

{
    "org_id": 3468,
    "name": "Splunk HEC 01",
    "on_error": {
       "type": "email",
       "value": "something@domain.tld"
    },
    "values": [
      {
        "type": "uri",
        "key": "endpoint",
        "value": "https://x:hec_access_token@hec.rackspace.com:8080"
      },
      {
        "type": "header",
        "key": "Authorization",
        "value": "Splunk hec_access_token"
      },
      {
        "type": "header",
        "key": "Accept",
        "value": "value2"
      }
   ]
}