Cisco Intersight Setup

---
name: cisco-intersight-setup
description: Use when configuring or validating Cisco Intersight audit, inventory, alarm, or metrics inputs in Splunk.
compatibility: >-
  Splunk Cloud Platform 10.5.2605: conditional. Follow documented package,
  entitlement, topology, and customer-managed runtime guardrails; self-managed
  paths remain on the public 10.4 baseline.
metadata:
  splunk_cloud_10_5: "conditional"
  compatibility_verified: "2026-08-20"
---

# Cisco Intersight TA Setup Automation

## Prerequisites

| Tool or access | Purpose | Verify |
|---|---|---|
| Bash, `curl`, and `jq` | Run setup and REST configuration helpers | `command -v bash curl jq` |
| Splunk administrative access | Create the index, account, and inputs | Confirm search-tier REST access |
| Intersight API client | Authorize selected APIs | Store the secret in a protected file |

## Workflow Overview

```text
┌───────────┐   ┌────────────┐   ┌──────────────────┐   ┌───────────────┐
│ Preflight │ → │ Install TA │ → │ Configure inputs │ → │ Validate data │
└───────────┘   └────────────┘   └──────────────────┘   └───────────────┘
```

## When to Activate

- Onboard Cisco Intersight audit, alarm, inventory, or metrics data.
- Configure `Splunk_TA_Cisco_Intersight` with an OAuth client.
- Diagnose missing Intersight events, metrics, or dashboard panels.

## Scope

This skill configures the Splunk add-on and validates its data path. It does
not create Intersight API clients, expose client secrets in chat, or change UCS
or HyperFlex infrastructure. Keep credentials file-backed.

## Examples

Run readiness checks before configuring an account:

```bash
bash skills/cisco-intersight-setup/scripts/validate.sh
```

Expected output: local tools, Splunk connectivity, package state, and account
prerequisites are reported without changing the deployment.

Run strict completion validation after enabling inputs:

```bash
bash skills/cisco-intersight-setup/scripts/validate.sh --completion
```

Expected output: account, input, index, source type, data, and dashboard checks
report `[PASS]`; absent evidence exits nonzero.

## Troubleshooting

| Issue | Cause | Resolution |
|---|---|---|
| OAuth fails | Client or endpoint is wrong | Verify the client and secret file |
| Metrics are absent | Metric input/index is disabled | Review metric settings |
| Inputs repeatedly error | Scope, clock, or network issue | Inspect logs and test reachability |
| Empty dashboards | Macro/index is wrong | Validate data, then align dashboards |

## TA Completion Gate

For every TA/add-on or dashboard companion run, satisfy the shared
[TA completion gate](../shared/ta_completion_gate.md): configure and enable the
data ingest path owned by this skill or its required companion, validate events
or metrics in the target indexes/source types, and verify any
pre-built/package-shipped dashboards are visible, macro-aligned, and returning
data. If the package ships no dashboards, record that evidence explicitly and
hand off dashboard use to the consuming app, ES/ITSI/ARI content, or readiness
doctor.

Automates the **Cisco Intersight Add-On for Splunk** (`Splunk_TA_Cisco_Intersight`).

## Package Model

**Pull from Splunkbase first, fall back to `splunk-ta/`.** Use
`splunk-app-install` with `--source splunkbase --app-id 7828`; the shared
installer defaults to the repository-verified package. If Splunkbase is
unavailable, fall back to the local package in `splunk-ta/`.

The repo-verified `3.1.1` release explicitly advertises `10.5` and is
Cloud-compatible. The newer public `3.2.0` listing advertises versions only
through `10.4`. On Splunk Cloud `10.5`, keep the shared installer's verified
`3.1.1` pin. The setup wrapper reads the actual installed version before any
REST mutation and refuses an unverified selection unless
`--accept-unsupported-platform` is backed by documented vendor approval for
the exact package and stack; the override is not compatibility certification.

After installation, use this skill to configure the account, inputs, macros,
and validation over search-tier REST. Any `splunk-ta/_unpacked/` tree is
review-only.

## Agent Behavior — Credentials

**The agent must NEVER ask for passwords, API keys, or secrets in chat.**

Splunk credentials are read automatically from the project-root `credentials` file
(falls back to `~/.splunk/credentials`). If neither exists, guide the user to create it:

```bash
bash skills/shared/scripts/setup_credentials.sh
```

For Intersight credentials (OAuth2 Client Secret), instruct the user to write the
secret to a temporary file:

```bash
# User creates the file themselves (agent never sees the secret)
bash skills/shared/scripts/write_secret_file.sh /tmp/intersight_client_secret
```

Then the agent passes `--client-secret-file /tmp/intersight_client_secret` to the configure
script. After the account is created, delete the temp file.

The agent may freely ask for non-secret values: account names, hostnames, client IDs, etc.

For prerequisite collection, use `skills/cisco-intersight-setup/template.example`
as the intake worksheet. Copy it to `template.local`, fill in non-secret values
there, and keep the completed file local only.

## Environment

Setup and validation use the Splunk search-tier REST API and can run from any
host with network access to the Splunk management port (`8089`). In Splunk
Cloud, app installation, index creation, and restarts are handled through ACS
instead of the search-tier REST endpoints.

| Item | Value |
|------|-------|
| Search-tier API | `SPLUNK_SEARCH_API_URI` env var (legacy alias: `SPLUNK_URI`) |
| Cloud stack | `SPLUNK_CLOUD_STACK` for Cloud installs (`SPLUNK_PLATFORM` is only an override for hybrid runs) |
| TA app name | `Splunk_TA_Cisco_Intersight` |
| Credentials | Project-root `credentials` file (falls back to `~/.splunk/credentials`) |
| Skill scripts | `skills/cisco-intersight-setup/scripts/` (relative to repo root) |

### Remote Splunk Connection

To run against a remote Splunk instance:

```bash
export SPLUNK_SEARCH_API_URI="https://splunk-host:8089"
```

## Splunk Authentication

Scripts read Splunk credentials from the project-root `credentials` file. They
fall back to `~/.splunk/credentials` automatically.
No environment variables or command-line password arguments are needed:

```bash
bash skills/cisco-intersight-setup/scripts/validate.sh
```

If credentials are not yet configured, run the setup script first:

```bash
bash skills/shared/scripts/setup_credentials.sh
```

## Setup Workflow

### Step 1: Create Index and Macro

```bash
bash skills/cisco-intersight-setup/scripts/setup.sh
```

Creates one index, updates the search macro, and ensures the app is visible in
Splunk Web. When run interactively (TTY), the script prompts to continue with
account configuration after the initial setup completes.

No `sudo` required when running as the `splunk` user.
In Splunk Cloud, the setup script creates this index through ACS.

| Index | Macro | Purpose | Max Size |
|-------|-------|---------|----------|
| `intersight` | `cisco_intersight_index` | All Intersight data | 512 GB |

Partial runs: `--indexes-only` or `--macros-only`.

### Step 2: Configure Account

Before running, the agent must **ask the user** for non-secret values:
- Account name (e.g., "CVF_Intersight")
- Intersight hostname (default: `intersight.com` for SaaS)
- OAuth2 Client ID
- Whether to create default inputs (true/false)

For the OAuth2 Client Secret, instruct the user to write it to a temp file and
pass `--client-secret-file`. The agent never sees the secret.

Accounts are created via the Splunk REST API, which handles credential encryption
automatically through the TA's custom REST handlers:

```bash
bash skills/cisco-intersight-setup/scripts/configure_account.sh \
  --name "MY_INTERSIGHT" \
  --hostname "intersight.com" \
  --client-id "YOUR_CLIENT_ID" \
  --client-secret-file /tmp/intersight_client_secret
```

Copy/paste secret-file prep command:

```bash
bash skills/shared/scripts/write_secret_file.sh /tmp/intersight_client_secret
```

REST endpoint: `/servicesNS/nobody/Splunk_TA_Cisco_Intersight/Splunk_TA_Cisco_Intersight_account`

### Step 3: Enable Inputs

```bash
bash skills/cisco-intersight-setup/scripts/setup.sh --enable-inputs \
  --account "MY_INTERSIGHT" --index "intersight" --input-type all
```

| Input Type | Inputs Enabled | Index |
|------------|---------------|-------|
| `audit_alarms` | 2 (audit logs, alarms) | `intersight` |
| `inventory` | 3 (general inventory, ports/interfaces, pools) | `intersight` |
| `metrics` | 2 (device metrics, network metrics) | `intersight` |
| `all` | 7 (all of the above) | `intersight` |

The app package provides its own dashboards. This setup flow creates the index,
macro, account, and inputs needed for those dashboards to populate; it does not
generate separate custom dashboards.

### Step 4: Restart If Required

On Splunk Enterprise, restart Splunk after new index creation.
On Splunk Cloud, check `acs status current-stack` and only run
`acs restart current-stack` when ACS reports `restartRequired=true`.

### Step 5: Validate

```bash
bash skills/cisco-intersight-setup/scripts/validate.sh --completion
```

Checks: app installation, indexes, macros, accounts, inputs, data flow, settings.

## Dashboards

The app ships dashboards in the package. They appear in Splunk Web
automatically after installation.

To access them: **Apps → Splunk Add-on for Cisco Intersight**

**Prerequisites for dashboards to show data:**

1. The `intersight` index must exist (queried by dashboards through the
   `cisco_intersight_index` macro) and inputs must be enabled.
2. The Intersight account must be configured and actively polling.
3. The `setup.sh` macro update step must have run to wire the correct index.

On **Splunk Cloud**, dashboards are available immediately after ACS installs
the app. Macro updates run over search-tier REST.

## Sourcetypes

| Sourcetype | Content |
|---|---|
| `cisco:intersight:auditrecords` | Audit trail (login, logout, CRUD operations) |
| `cisco:intersight:alarms` | Active and historical alarms |
| `cisco:intersight:compute` | Server inventory (blades, rack units) |
| `cisco:intersight:networkelements` | Fabric Interconnects and network devices |
| `cisco:intersight:profiles` | Server/chassis/switch profiles |
| `cisco:intersight:targets` | Connected targets and claimed devices |
| `cisco:intersight:contracts` | Support contract information |
| `cisco:intersight:licenses` | License entitlements |
| `cisco:intersight:advisories` | Security advisories (PSIRTs) |
| `cisco:intersight:networkobjects` | Network configuration objects |
| `cisco:intersight:pools` | IP/MAC/UUID/IQN/FC/Resource pools |
| `cisco:intersight:metrics` | Performance metrics (CPU, memory, fan, temp, network) |
| `cisco:intersight:custom:inventory` | Custom API inventory queries |
| `cisco:intersight:custom:metrics` | Custom API metrics queries |

## MCP Server Integration

Load custom tools into the MCP Server. Credentials come from the project-root
`credentials` file or the `~/.splunk/credentials` fallback:

```bash
bash skills/cisco-intersight-setup/scripts/load_mcp_tools.sh
```

## Key Learnings / Known Issues

1. **OAuth2 authentication**: Intersight uses Client ID + Client Secret (not
   username/password). The TA's REST handler encrypts the secret automatically.
2. **Restart behavior differs by platform**: Enterprise requires a Splunk
   restart after new index creation. Splunk Cloud uses ACS restart checks.
3. **No sudo needed**: Scripts run fine as the `splunk` OS user.
4. **SSL verification**: The `ssl_validation` setting defaults to `true` in
   `splunk_ta_cisco_intersight_settings.conf`.
5. **Default inputs**: The account creation UI has a "Create Default Inputs"
   checkbox. The script defaults to not creating them (use `--create-defaults`).
6. **KVStore inventory**: The TA stores inventory snapshots in KVStore collections
   for dashboard lookups — this is normal and expected.
7. **Custom inputs**: Up to 10 custom inputs can query arbitrary Intersight API
   endpoints (set via `MAX_INPUT_LIMIT` in settings).
8. **CIM compliance**: Audit records map to Authentication and Change CIM models.
   Alarms map to the Alerts CIM model. Metrics map to Performance.
9. **ACS deployment verification**: After ACS install, verify the app identity
   via REST (`configs/conf-app/package`). ACS can occasionally deploy the wrong
   app content into an app directory. If `app.conf` shows a different app ID,
   uninstall and reinstall the app individually.
10. **Visibility after ACS install**: The app may default to `visible=false`
    after ACS install, making it invisible in Splunk Web. The setup script now
    sets `visible=true` automatically. The standalone fix is a POST to
    `/services/apps/local/Splunk_TA_Cisco_Intersight` with `visible=true`.
11. **Interactive continuation**: When run from a TTY, `setup.sh` prompts to
    continue with account configuration after the initial setup completes. This
    is skipped in non-interactive (piped) contexts.

## Additional Resources

- [reference.md](reference.md) — Complete input catalog, account fields, sizing
- [mcp_tools.json](mcp_tools.json) — MCP tool definitions

## Validation Modes

Run `scripts/validate.sh` for diagnostics. Use `--completion` (alias `--strict`)
to require an account, enabled input, event data, aligned index macro, and
visible package dashboards.