Splunk Cisco App Navigator (SCAN) Setup Automation

Prerequisites

Tool or access	Purpose	Verify
Bash and Python 3	Run bundled setup and validation helpers	bash --version && python3 --version
Required product/platform access	Inspect or configure the selected target	Complete the documented preflight
Credential files for live modes	Keep secrets out of chat	Verify paths only

Workflow Overview

┌───────────┐   ┌───────────────┐   ┌───────────────┐   ┌─────────────────┐
│ Preflight │ → │ Render/review │ → │ Apply/handoff │ → │ Validate evidence │
└───────────┘   └───────────────┘   └───────────────┘   └─────────────────┘

When to Activate

• SCAN, Cisco App Navigator, product catalog, ecosystem intelligence, or splunk-cisco-app-navigator setup in Splunk.
• Preview and review the cisco scan setup workflow before any live apply phase.
• Diagnose failed prerequisites, generated assets, configuration, or validation evidence.

Scope

Follow the documented read-only or render-first path whenever it is available. This skill does not imply permission to mutate live systems. Require explicit apply flags, protected credentials, and operator review for state changes.

Examples

Inspect the supported setup modes before selecting one:

bash skills/cisco-scan-setup/scripts/setup.sh --help

Expected output: usage, supported modes, and required arguments are displayed without changing the target environment.

Inspect validation modes before running completion checks:

bash skills/cisco-scan-setup/scripts/validate.sh --help

Expected output: offline, live, and completion options are displayed when the skill supports them; help exits without mutation.

Troubleshooting

Issue	Cause	Resolution
Preflight fails	A required tool or access path is missing	Resolve it before rendering or applying
Rendered assets are incomplete	Required non-secret inputs are absent	Complete intake and render again
Apply is blocked	Review, credentials, or explicit acceptance is missing	Use the documented handoff
Validation is incomplete	Live evidence is unavailable	Record the gap and keep completion open

Shared add-on completion gate

Whenever this workflow installs, configures, or hands off a registry-listed Splunk app or add-on, follow the shared completion gate. Package delivery alone is not success. Apply every relevant ingest and dashboard check; for a management-only app, record why ingest is not applicable and validate its shipped views and saved searches instead.

Automates the Splunk Cisco App Navigator (splunk-cisco-app-navigator).

SCAN is a management and catalog app, not a data-ingestion TA. It provides a unified product catalog UI for 93+ Cisco products, ecosystem intelligence dashboards, and 42+ saved searches for catalog analysis. It does not create indexes, configure data inputs, or require vendor-specific credentials.

Package Model

Splunkbase is the public install source; splunk-ta/ is the local cache for offline installs and package review. SCAN is listed on Splunkbase as app ID 8566. Use splunk-app-install with the Splunkbase ID when a fresh download or public Cloud install is available:

bash skills/splunk-app-install/scripts/install_app.sh \
  --source splunkbase --app-id 8566

For offline Enterprise installs or private review copies, place the downloaded package in splunk-ta/ and run this skill's setup.sh; it installs the newest matching local package. The product repo's cisco-product-setup catalog uses a checked-in normalized fixture of SCAN's public S3 products.conf, with the source timestamp, minimum SCAN version, raw source SHA-256, and fixture SHA-256 recorded in scan_source.json. Clean-clone catalog builds therefore do not depend on an ignored vendor archive or live network access.

For Splunk Cloud (ACS), prefer the Splunkbase install path. Use private app upload only for pre-vetted local packages. After installation, use this skill to verify the catalog, run the initial sync, and validate the deployment.

Package Verification Boundary

The reviewed SCAN baseline is 1.0.30, which is also the current public release. That package was downloaded, unpacked, and inspected here, so the shared installer's default pin needs no review override. Local catalog generation still does not upgrade or approve the app package: fixture refresh and package review remain separate controls. When Splunkbase publishes a newer release, re-check products.conf, lookup/sync behavior, saved searches, and shipped dashboards before advancing the pin.

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 skills/shared/scripts/setup_credentials.sh

SCAN requires no vendor-specific secrets. The S3 bucket used for catalog sync (is4s.s3.amazonaws.com) is publicly readable. The only credentials needed are for the Splunk management REST API.

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). Catalog sync requires outbound HTTPS to is4s.s3.amazonaws.com.

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)
App name	splunk-cisco-app-navigator
Credentials	Project-root credentials file (falls back to ~/.splunk/credentials)
Skill scripts	skills/cisco-scan-setup/scripts/ (relative to repo root)

Remote Splunk Connection

To run against a remote Splunk instance:

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

Splunk Authentication

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

bash skills/cisco-scan-setup/scripts/validate.sh

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

bash skills/shared/scripts/setup_credentials.sh

Setup Workflow

SCAN is a catalog app with no indexes, no data inputs, and no account configuration. Setup is simpler than typical data-ingestion TAs.

Step 1: Install App

bash skills/cisco-scan-setup/scripts/setup.sh

Installs the app from splunk-ta/, verifies it is visible in Splunk Web, and confirms the product catalog loads via REST.

For Splunk Cloud, install the package as a private app through ACS first, then run setup.sh for post-install verification.

Step 2: Initial Catalog Sync (Optional)

To trigger an immediate sync of products.conf and the Splunkbase lookup from S3 (requires outbound HTTPS to is4s.s3.amazonaws.com):

bash skills/cisco-scan-setup/scripts/setup.sh --sync

This runs | synccatalog dryrun=false and | synclookup via the Splunk REST API. Without --sync, the app's daily scheduled search handles this automatically.

Step 3: Validate

bash skills/cisco-scan-setup/scripts/validate.sh

Checks: app installation, app version, product catalog stanza count, Splunkbase lookup, S3 sync connectivity, saved searches, and scheduled sync job status.

Key Components

Component	Description
products.conf	Product catalog with 93+ Cisco product stanzas
scan_splunkbase_apps.csv.gz	Synced Splunkbase ecosystem lookup
synccatalog	Custom search command: syncs products.conf from S3
synclookup	Custom search command: syncs Splunkbase CSV from S3
42+ saved searches	Catalog analysis, gap analysis, compatibility, migration
Ecosystem Intelligence	Dashboard Studio analytics dashboard

Dashboard

The Ecosystem Intelligence dashboard is a Dashboard Studio view included in the package. It appears in Splunk Web automatically after installation — no import or manual activation step is needed.

To access it: Apps → Splunk Cisco App Navigator → Ecosystem Intelligence

SCAN does not collect data, so the dashboard visualizes catalog metadata rather than time-series events. It does not require index configuration or data input enablement.

If the dashboard appears blank after installation, trigger an initial catalog sync:

bash skills/cisco-scan-setup/scripts/setup.sh --sync

On Splunk Cloud, the dashboard is available immediately after the ACS private app upload completes.

Key Learnings / Known Issues

1. No indexes or inputs: SCAN is a catalog/management app. It does not create indexes, configure data inputs, or ingest data. This makes setup significantly simpler than other Cisco TAs.
2. S3 outbound connectivity: The synccatalog and synclookup commands require HTTPS access to is4s.s3.amazonaws.com. If the search head cannot reach S3, catalog sync will fail but the app still functions with its shipped default catalog.
3. synccatalog dryrun is required: Despite searchbnf.conf marking dryrun as optional, the Python command yields an error event and exits early if dryrun is omitted, producing no useful output. Always pass dryrun=true or dryrun=false explicitly.
4. min_app_version gating: The S3 products.conf may include a min_app_version header. If the installed app version is below this threshold, synccatalog skips the update. Upgrade the app first.
5. SHC replication: server.conf includes products in SHC conf replication so catalog updates propagate across cluster members.
6. Lookup replication denied: distsearch.conf excludes the large scan_splunkbase_apps.csv.gz from search-head replication. Each SHC member must run synclookup independently (or use the scheduled search).
7. Splunkbase listing available: SCAN is Splunkbase app ID 8566. Keep a local package in splunk-ta/ when you need offline Enterprise installs or package review. It is not required for deterministic catalog generation.
8. Restart behavior: SCAN does not create indexes, so a restart is typically only needed if Splunk requires one after app installation.
9. Non-atomic sync: synccatalog writes the file before reloading. A failure after write but before reload leaves the file updated on disk without Splunk seeing the changes. POST to the _reload endpoint (/services/configs/conf-products/_reload) to force Splunk to pick up the already-written file. Run | synccatalog dryrun=true separately to diagnose version state, not to trigger a reload.
10. cisco-product-setup dependency: The cisco-product-setup skill reads the checksum-pinned normalized SCAN public-catalog fixture at build-time to generate catalog.json. At runtime, live SCAN features (installed app detection, data flow validation, legacy debt auditing) require the app to be installed.