Spark Operations Bot, also known as Cisco Infrastructure Chat Ops (CICO).
This bot leverages the Spark Bot framework found here. It has two primary functions:
The bot is able to provide an overall health of your environment, which can include Meraki, Spark Calling, and Umbrella. It will tell you if you have any network devices down in your Meraki network, and optionally give you a way to cross-launch directly into the Meraki dashboard to troubleshoot. It will show how many phones are configured in Spark Call, and how many are offline by device type. And, it will show you if there is any malicious traffic detected by Umbrella.
The bot is able to give you a status of an individual user, which can include Meraki, Spark Calling, and Umbrella. It will show you the device(s) detected for that user in the Meraki dashboard clients list (also including Systems Manager if available), optionally giving you a way to cross-launch directly into the Meraki dashboard to troubleshoot any issues on the network device. It also lists any phones configured for that user in Spark Call, also with an optional link to cross-launch back into the Meraki dashboard for troubleshooting. Finally, it is able to show you whether there is any malicious traffic detected for that specific user in Umbrella.
If you don't already have a Cisco Spark account, go ahead and register for one. They are free. You'll need to start by adding your bot to the Cisco Spark website.
https://developer.ciscospark.com/add-app.html
Create a virtualenv and install the module
virtualenv venv
source venv/bin/activate
pip install -r requirements.txt
git clone https://github.com/meraki/spark-operations-bot.git
ngrok will make easy for you to develop your code with a live bot.
If you are running a Mac with Homebrew, you can easily install via "brew cask install ngrok". Additional installation instructions can be found here: https://ngrok.com/download
After you've installed ngrok, in another window start the service
ngrok http 5000
You should see a screen that looks like this:
ngrok by @inconshreveable (Ctrl+C to quit)
Session Status online
Version 2.2.4
Region United States (us)
Web Interface http://127.0.0.1:4040
Forwarding http://this.is.the.url.you.need -> localhost:5000
Forwarding **https://this.is.the.url.you.need** -> localhost:5000
Connections ttl opn rt1 rt5 p50 p90
2 0 0.00 0.00 0.77 1.16
HTTP Requests
-------------
POST / 200 OK
Log in to the Meraki Dashboard. Choose your organization if prompted to do so.
On the left Navigation bar, go to Organization and select Settings.
Scroll down to the Dashboard API Access section, and turn on API Access.
Log in to the Meraki Dashboard. Choose your organization if prompted to do so.
Under your username, select My profile
If you have only a single Organization, this step is not required. If you have multiple Organizations, and you do not provide this value, the first network (alphabetically) will be used. You can use Postman to run this GET:
Or you can do it from the command line, with a curl command like this:
curl --header "X-Cisco-Meraki-API-Key: put-your-meraki-api-token-here" https://dashboard.meraki.com/api/v0/organizations/
You should see output with one or more networks like this:
[{"id":your-meraki-org-id-here,"name":"Your Meraki Network"}]
Copy your Meraki organization ID to use for the environment variables below.
Note: This bot has only been tested with a "Combined" Meraki Network or a standalone Meraki SM Network (no 'health' information is shown for SM-only networks). If you attempt to use the bot with separate wired/wireless/appliance networks, it will likely not work correctly.
Log in to the Meraki Dashboard. Choose your oganization if prompted to do so.
On the left navigation pane, locate the dropdown arrow representing the currently selected Network.
Log in to the Meraki Dashboard. Choose your oganization if prompted to do so.
On the left navigation pane, navigate to Network-Wide and Clients.
Log in to the Meraki Dashboard. Choose your oganization if prompted to do so.
On the left navigation pane, navigate to Systems Manager and Clients
Go to https://admin.ciscospark.com, and log in with a user that has Full Admin rights to your Spark Call organization.
Select Users on the left, then find your Admin user and click on that user. An overview box will slide in.
Click "Roles and Security"
Ensure that your Admin user has "Full administrator privileges" marked
Go to https://developer.ciscospark.com, and log in with a user that has Full Admin rights to your Spark Call organization.
In the upper right, click the user portrait, then click the "Copy" button to copy your Token for the environment variables below.
By default, when performing a "check <username>", the bot will match clients in Spark Call where some portion of the First Name, Last Name, User Name, or Display Name match.
Log in to the Spark Call Dashboard.
On the left navigation pane, click on Users. From the list, you can see the First Name, Last Name, Display Name, and Email for the clients.
Please reference the Umbrella documentation for information on how to set up your S3 bucket. https://support.umbrella.com/hc/en-us/articles/231248448-Cisco-Umbrella-Log-Management-in-Amazon-S3
Please reference the Umbrella documentation for information on how to enable S3 Log Export. https://support.umbrella.com/hc/en-us/articles/231248448-Cisco-Umbrella-Log-Management-in-Amazon-S3
Access Amazon Identiy and Access Management (IAM) here:
https://console.aws.amazon.com/iam
Click on the link for Users: 1 (or, whatever quantity of users you have defined)
Click Add User
Give your user a name, and check the box for "Programmatic access"
Click the button for "Attach existing policies directly", then search for or scroll to AmazonS3ReadOnlyAccess, and check the box next to that. Then click Next.
Verify the settings, then click Create user.
Save your Access Key ID and Secret Access Key to add to the required Environment Variables.
In Amazon AWS, access the bucket you are utilizing for Umbrella log exports. Click on the Management tab after selecting the bucket.
Click "Add lifecycle rule"
Give your lifecycle a rule, then click through until the Expiration tab.
Check "Current version", check "Expire current version of object", and set the duration to 1 day. Click through and save the lifecycle rule.
By default, when performing a "check <username>", the bot will match clients in Umbrella based on their host name.
Log in to the Umbrella Dashboard.
On the left navigation pane, click on Identities and Roaming Computers.
Go to https://console.amp.cisco.com, and log in with a user that has Full Admin rights to your AMP for Endpoints organization.
In the top menu, click Accounts dropdown menu, then click the "API Credentials" menu option.
Click the button for "New API Credential".
Give your API Credential a recognizable name, leave the Scope as "Read-only", then click the "Create" button.
Save the Client ID and API Key for the environment variables below.
There are several ways to run the bot. Use one of the methods below to start up the bot. Once it's running, you can start interacting with it!
If you are in a 1:1 space with your bot, you can simply type either health or check
The easiest way to use this module is to set a few environment variables. On Windows, use "set" instead of "export". See the ngrok section below if you do not have a web server already facing the Internet. These are the Environment variables that are required to run the bot itself (app.py):
# Required for Bot Operation
export SPARK_BOT_URL=https://mypublicsite.io *(your public facing webserver, or the forwarding address from ngrok)*
export SPARK_BOT_TOKEN=<your bot token>
export SPARK_BOT_EMAIL=<your bot email>
export SPARK_BOT_APP_NAME=<your bot name>
export SPARK_BOT_HELP_MSG=<Optional, used to customize Bot Help Banner>
# Enable Meraki Integration
export MERAKI_API_TOKEN=<Meraki Dashboard API token>
export MERAKI_ORG=<Meraki Dashboard Organization ID>
export MERAKI_HTTP_USERNAME=<Optional; Meraki Dashboard username>
export MERAKI_HTTP_PASSWORD=<Optional; Meraki Dashboard password>
# Enable Spark Call Integration
export SPARK_API_TOKEN=<Spark Call Admin API token>
# Enable Umbrella Integration
export S3_BUCKET=<Amazon S3 bucket name; used for Umbrella log import>
export S3_ACCESS_KEY_ID=<Amazon S3 access key ID; used for Umbrella log import>
export S3_SECRET_ACCESS_KEY=<Amazon S3 secret access key; used for Umbrella log import>
# Enable AMP for Endpoints Integration
export A4E_CLIENT_ID=<AMP for Endpoints 3rd Party API Client ID>
export A4E_CLIENT_SECRET=<AMP for Endpoints API Key>
Now launch your bot!!
python app.py
First, make a copy of the .env.sample file, naming it .env, and editing it to set your environment variables.
You can build the container yourself:
docker build -t joshand/spark-operations-bot .
docker run -p 5000:5000 -it --env-file .env joshand/spark-operations-bot
Or, you can use the published container:
./start.sh