Cisco Meraki Collector

collectors/ciscomeraki/.jshintrc

@@ -0,0 +1,15 @@
+{
+  "esversion": 8,
+  "shadow": "outer",
+  "undef": true,
+  "unused": "vars",
+  "node":  true,
+  "predef": [
+    "it",
+    "describe",
+    "before",
+    "after",
+    "beforeEach",
+    "afterEach"
+  ]
+}

collectors/ciscomeraki/.npmrc

@@ -0,0 +1 @@
+package-lock=false

collectors/ciscomeraki/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2019 ALERT LOGIC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

collectors/ciscomeraki/Makefile

@@ -0,0 +1,6 @@
+AWS_LAMBDA_FUNCTION_NAME ?= alertlogic-ciscomeraki-collector
+AWS_LAMBDA_PACKAGE_NAME ?= al-ciscomeraki-collector.zip
+AWS_LAMBDA_CONFIG_PATH ?= ./al-ciscomeraki-collector.json
+AWS_CFN_TEMPLATE_PATH ?= ./cfn/ciscomeraki-collector.template
+
+-include ../collector.mk

collectors/ciscomeraki/README.md

@@ -0,0 +1,149 @@
+# Ciscomeraki collector
+Alert Logic Ciscomeraki AWS Based API Poll (PAWS) Log Collector Library.
+
+# Overview
+This repository contains the AWS JavaScript Lambda function and CloudFormation 
+Template (CFT) for deploying a log collector in AWS which will poll Ciscomeraki (Network Events) service API to collect and 
+forward logs to the Alert Logic CloudInsight backend services.
+
+# Installation
+
+# Cisco Meraki Dashboard Log Collection Setup
+
+Instructions for setting up log collection from Cisco Meraki Dashboard using its API.
+
+## Prerequisites
+
+1. **Cisco Meraki Dashboard Account**: You need to have access to a Cisco Meraki Dashboard account with administrative privileges.
+2. **API Key**: Generate an API key from the Cisco Meraki Dashboard. Follow [this guide](https://developer.cisco.com/meraki/api-v1/authorization/) to obtain your API key.
+
+## Setup Steps
+
+1. **Enable API Access**:
+   - Log in to your [Cisco Meraki Dashboard](https://dashboard.meraki.com) account.
+   - You need to have access to organizational level administrative privileges.
+   -  Get the Organization ID at the bottom of the page ![ScreenShot](./docs/Ciscomerakiorg.png).
+   - Navigate to *Organization > Settings*.
+   - Under *Dashboard API access*, enable API access ![ScreenShot](./docs/Ciscomeraki_img1.png).
+
+2. **Generate API Key**:
+   - Go to *My Profile*.
+   - Under *API access*, generate a new API key ![ScreenShot](./docs/Ciscomeraki_img2.png).
+
+3. **Collect Network Events**:
+   - Refer to the [Cisco Meraki Dashboard API documentation](https://developer.cisco.com/meraki/api/) for details on how to use the API to retrieve [network events](https://developer.cisco.com/meraki/api-v1/get-network-events/).
+   - Example API endpoint: `GET /organizations/{organizationId}/networks/{networkId}/events`
+
+4. **Handle Authentication**:
+   - Include your API key in the request headers for authentication.
+   - Example: `X-Cisco-Meraki-API-Key: YOUR_API_KEY`
+
+### Rate Limits
+- Cisco Meraki Dashboard imposes rate limits on API requests to ensure fair usage and prevent abuse. Refer to the [Rate Limits documentation](https://developer.cisco.com/meraki/api-v1/rate-limit/) for details on the specific limits for different endpoints.
+- Ensure that your application adheres to these rate limits to avoid throttling errors.
+
+### Organization Call Budget
+- Each Meraki organization has a call budget of **10 requests per second**, regardless of the number of API applications interacting with that organization. 
+
+### Throttling Errors
+- Throttling errors occur when your API requests exceed the allowed rate limit. When a throttling error occurs, the API will return an HTTP 429 status code along with an error message.
+- Refer to the [Throttling Errors documentation](https://developer.cisco.com/meraki/api/#/rest/guides/throttling-errors) for information on how to handle throttling errors and retry mechanisms.
+
+### 2. API Docs
+
+1. [Network Events](https://developer.cisco.com/meraki/api-v1/get-network-events/)
+
+   This endpoint allows you to retrieve network events from **all networks** within an organization, filtered by specific product types such as "appliance", "switch", and more. These events provide insights into network changes, device status updates, and other relevant activities.
+
+
+API URLs required for Ciscomeraki collector for Example
+
+|     URL                              |
+|--------------------------------------|
+|   https://n219.meraki.com/organizations/{organizationId}/networks/{networkId}/events   |            
+
+## Support
+
+If you encounter any issues or have questions, please reach out to Cisco Meraki support or refer to their documentation.
+
+Refer to [CF template readme](./cfn/README.md) for installation instructions.
+
+# How it works
+
+## Update Trigger
+
+The `Updater` is a timer triggered function that runs a deployment sync operation 
+every 12 hours in order to keep the collector lambda function up to date.
+The `Updater` syncs from the Alert Logic S3 bucket where you originally deployed from.
+
+## Collection Trigger
+
+The `Collector` function is an AWS lambda function which is triggered by SQS which contains collection state message.
+During each invocation the function polls 3rd party service log API and sends retrieved data to 
+AlertLogic `Ingest` service for further processing.
+
+## Checkin Trigger
+
+The `Checkin` Scheduled Event trigger is used to report the health and status of 
+the Alert Logic AWS lambda collector to the `Azcollect` back-end service based on 
+an AWS Scheduled Event that occurs every 15 minutes.
+
+
+# Development
+
+## Creating New Collector Types
+run `npm run create-collector <<name>> <<version>>` to create a skeleton collector in the `collectors` folder.
+
+## Build collector
+Clone this repository and build a lambda package by executing:
+```
+$ git clone https://github.com/alertlogic/paws-collector.git
+$ cd paws-collector/collectors/ciscomeraki
+$ make deps test package
+```
+
+The package name is *al-ciscomeraki-collector.zip*
+
+## Debugging
+
+To get a debug trace, set an Node.js environment variable called DEBUG and
+specify the JavaScript module/s to debug.
+
+E.g.
+
+```
+export DEBUG=*
+export DEBUG=index
+```
+
+Or set an environment variable called "DEBUG" in your AWS stack (using the AWS 
+console) for a collector AWS Lambda function, with value "index" or "\*".
+
+See [debug](https://www.npmjs.com/package/debug) for further details.
+
+## Invoking locally
+
+In order to invoke lambda locally please follow the [instructions](https://docs.aws.amazon.com/lambda/latest/dg/sam-cli-requirements.html) to install AWS SAM.
+AWS SAM uses `default` credentials profile from `~/.aws/credentials`.
+
+  1. Encrypt the key using aws cli:
+```
+aws kms encrypt --key-id KMS_KEY_ID --plaintext AIMS_SECRET_KEY
+```
+  2. Include the encrypted token, and `KmsKeyArn` that you used in Step 1 inside my SAM yaml:
+```
+    KmsKeyArn: arn:aws:kms:us-east-1:xxx:key/yyy
+    Environment:
+        Variables:
+```
+  3. Fill in environment variables in `env.json` (including encrypted AIMS secret key) and invoke locally:
+
+```
+cp ./local/env.json.tmpl ./local/env.json
+vi ./local/env.json
+make test
+make sam-local
+```
+  4. Please see `local/event.json` for the event payload used for local invocation.
+Please write your readme here
+

collectors/ciscomeraki/al-ciscomeraki-collector.json

@@ -0,0 +1,6 @@
+{
+    "Runtime": {
+        "path": "Runtime",
+        "value": "nodejs18.x"
+    }
+}

collectors/ciscomeraki/cfn/ciscomeraki-collector.template

@@ -0,0 +1,115 @@
+{
+    "AWSTemplateFormatVersion": "2010-09-09",
+    "Description": "Alert Logic template for creating a CiscoMeraki log collector",
+    "Parameters": {
+        "AlertlogicAccessKeyId": {
+            "Description": "Alert Logic Access Key Id obtained from AIMS",
+            "Type": "String"
+        },
+        "AlertlogicSecretKey": {
+            "Description": "Alert Logic Secret Key returned from AIMS for the Access Key Id",
+            "Type": "String",
+            "NoEcho": true
+        },
+        "AlApplicationId": {
+            "Description": "Alert Logic Application Id for collector logs",
+            "Type": "String",
+            "Default": "ciscomeraki"
+        },
+        "AlApiEndpoint": {
+            "Description": "Alert Logic API endpoint",
+            "Type": "String",
+            "Default": "api.global-services.global.alertlogic.com",
+            "AllowedValues": [
+                "api.global-services.global.alertlogic.com",
+                "api.global-integration.product.dev.alertlogic.com"
+            ]
+        },
+        "AlDataResidency": {
+            "Description": "Alert Logic Data Residency",
+            "Type": "String",
+            "Default": "default",
+            "AllowedValues": ["default"]
+        },
+        "PackagesBucketPrefix": {
+            "Description": "S3 bucket name prefix where collector packages are located.",
+            "Type": "String",
+            "Default": "imran-s3-aletlogic-collectors"
+        },
+        "PawsCollectorTypeName": {
+            "Description": "A collector type name. For example, okta, auth0",
+            "Type": "String",
+            "Default": "ciscomeraki"
+        },
+        "AlertlogicCustomerId": {
+            "Description": "Optional. Alert Logic customer ID which collected data should be reported for. If not set customer ID is derived from AIMs tokens",
+            "Type": "String",
+            "Default": ""
+        },
+        "CollectorId": {
+            "Description": "Optional. A collector UUID if known.",
+            "Type": "String",
+            "Default": "none"
+        },
+        "CiscoMerakiEndpoint": {
+            "Description": "Cisco Meraki API URL to poll.  For Example https://n149.meraki.com/api/v1",
+            "Type": "String"
+        },
+        "CiscoMerakiClientId": {
+            "Description": "Cisco Meraki Client ID for oauth2 authentication type",
+            "Type": "String"
+        },
+        "CiscoMerakiSecret": {
+            "Description": "Cisco Meraki Client Secret API Key for authentication.",
+            "Type": "String",
+            "NoEcho": true
+        },
+        "CiscoMerakiOrgKey": {
+            "Description": "Cisco Meraki Organisation Key, used for collection of network events",
+            "Type": "String",
+            "Default": ""
+        },
+        "CiscoMerakiProductTypes": {
+            "Description": "Define Product Types. Please pass JSON formatted list of product types. Possible values are [\"appliances\",\"switch\",\"systemsManager\"]",
+            "Type": "String",
+            "Default": ""
+        },
+        "CollectionStartTs": {
+            "Description": "Timestamp when log collection starts. For example, 2019-11-21T16:00:00Z",
+            "Type": "String",
+            "Default" : "",
+            "AllowedPattern" : "(?:^\\d{4}(-\\d{2}){2}T(\\d{2}:){2}\\d{2}Z$)?"
+        }
+    },
+    "Resources":{
+      "CiscoMerakiCollectorStack" : {
+        "Type" : "AWS::CloudFormation::Stack",
+        "Properties" : {
+          "TemplateURL" : {"Fn::Join" : ["", [
+                    "https://s3.amazonaws.com/",
+                    {"Ref":"PackagesBucketPrefix"}, "-us-east-1",
+                    "/cfn/paws-collector.template"
+               ]]},
+          "Parameters" : {
+            "AlertlogicAccessKeyId" : { "Ref":"AlertlogicAccessKeyId" },
+            "AlertlogicSecretKey" : { "Ref":"AlertlogicSecretKey" },
+            "AlApplicationId" : { "Ref":"AlApplicationId" },
+            "AlApiEndpoint" : { "Ref":"AlApiEndpoint" },
+            "AlDataResidency" : { "Ref":"AlDataResidency" },
+            "PackagesBucketPrefix" : { "Ref":"PackagesBucketPrefix" },
+            "PawsCollectorTypeName" : "ciscomeraki",
+            "AlertlogicCustomerId" : { "Ref":"AlertlogicCustomerId" },
+            "CollectorId" : { "Ref":"CollectorId" },
+            "PollingInterval" : 60,
+            "PawsEndpoint" : { "Ref":"CiscoMerakiEndpoint" },
+            "PawsAuthType" : "oauth2",
+            "PawsClientId" : "",
+            "CollectorParamString1" : { "Ref":"CiscoMerakiProductTypes" },
+            "CollectorParamString2" : { "Ref":"CiscoMerakiOrgKey" },
+            "PawsSecret" : { "Ref":"CiscoMerakiSecret" },
+            "CollectionStartTs" : { "Ref":"CollectionStartTs" }
+          }
+        }
+      }
+   }
+}