# Deployment Architecture

> Enterprise deployment patterns for the Whisper Splunk add-on: SHC, deployment server, indexer cluster, Splunk Cloud Victoria/Classic.

*Source: https://www.whisper.security/docs/integrations/splunk/deployment-architecture*
*Published: 2026-04-07*
*Last updated: 2026-09-19*

---
This guide covers enterprise deployment patterns for the Whisper Security Add-on: which Splunk roles host which components, deployment server workflows, Search Head Cluster (SHC) configuration, indexer cluster considerations, forwarder compatibility, and Splunk Cloud specifics.

## Where each component runs

The TA runs entirely on search heads. Indexers and forwarders require no additional configuration.

| Component | Search Head | Indexer | Forwarder |
|---|---|---|---|
| Search commands (whisperlookup, whisperquery) | YES | NO | NO |
| Modular inputs (health, baseline, threat intel, watchlist) | YES | NO | NO |
| KV Store collections (enrichment cache, threat intel) | YES | NO | NO |
| API calls (outbound HTTPS to Whisper API) | YES | NO | NO |
| Alert actions (Enrich with Whisper) | YES | NO | NO |
| Dashboards and views | YES | NO | NO |
| Saved searches (correlation, KV Store population) | YES | NO | NO |
| props.conf / transforms.conf | YES | YES* | NO |
| `whisper` index (admin-created, not shipped) | N/A | YES | NO |

*Only if field extractions are needed at index time. For most deployments, search-time extraction (default) is sufficient.

> **The TA does not ship `indexes.conf`:**
> Splunk Cloud Victoria Experience prohibits app-shipped index definitions. The deployment administrator must create the `whisper` index before enabling modular inputs. See [Installation -> Create the whisper index](/docs/integrations/splunk/install#create-the-whisper-index) for step-by-step instructions for Cloud Victoria, Cloud Classic, and Splunk Enterprise.

## API Call Origin

All outbound API calls to the Whisper Knowledge Graph originate exclusively from search heads. Ensure your firewall allows outbound HTTPS (port 443) from search heads to `graph.whisper.security` (or your configured API base URL).

No indexers, forwarders, or other Splunk components make API calls.

## Deployment Server

To deploy the TA via Deployment Server to search heads:

1. Place the TA in the deployment apps directory:
   ```
   $SPLUNK_HOME/etc/deployment-apps/TA-whisper-graph/
   ```

2. Configure `serverclass.conf` to target search heads only:
   ```ini
   [serverClass:whisper_security]
   whitelist.0 = search-head-*.example.com

   [serverClass:whisper_security:app:TA-whisper-graph]
   restartSplunkd = true
   ```

3. Push the deployment:
   ```bash
   splunk reload deploy-server
   ```

Do not deploy to indexers or forwarders -- the TA is not needed there.

## Search Head Cluster (SHC)

### Deploying via SHC Deployer

1. Place the TA on the deployer:
   ```
   $SPLUNK_HOME/etc/shcluster/apps/TA-whisper-graph/
   ```

2. Push the bundle:
   ```bash
   splunk apply shcluster-bundle -target https://<captain>:8089 --answer-yes
   ```

### KV Store Replication

KV Store collections automatically replicate across SHC members. No additional configuration is needed. The TA's `server.conf` includes:

```ini
[shclustering]
conf_replication_include.ta_whisper_graph_settings = true
```

To verify replication status, run the check under [KV Store not replicating across SHC members](/docs/integrations/splunk/troubleshooting#kv-store-not-replicating-across-shc-members) on the Troubleshooting page.

### Modular Input Behavior

Modular inputs run on all SHC members by default. For inputs that should run on only one member (to avoid duplicate data collection), configure the captain to manage input scheduling, or disable inputs on non-captain members.

## Indexer Cluster

No TA installation is required on indexers. The TA runs entirely on search heads.

If you want the `whisper` index on your indexer cluster, create your own `indexes.conf` in a cluster-master apps bundle (the TA does not ship one — Splunk Cloud Victoria forbids it):

```
$SPLUNK_HOME/etc/manager-apps/whisper-indexes/default/indexes.conf
```

The stanza that goes in it, and the command that pushes the bundle, are under [Create the `whisper` index](/docs/integrations/splunk/install#create-the-whisper-index) on the install page. Its `repFactor = auto` setting ensures proper replication across indexer cluster peers.

## Forwarder Compatibility

The TA does not run on universal or heavy forwarders. All data collection is performed by modular inputs running on the search head, which call the Whisper API directly.

Forwarders can send raw network events (e.g., proxy logs, firewall logs) to indexers. Those events can then be enriched at search time using `whisperlookup` on the search head.

## Splunk Cloud

### Victoria Experience

- The TA installs on the search head via the Splunk Cloud self-service app install
- Modular inputs run locally on the search head -- full compatibility
- KV Store is accessible from the search head
- All features work without additional configuration

### Classic Experience (IDM)

In Classic Experience, modular inputs run on the **Inputs Data Manager (IDM)**, a separate Splunk instance that does not have access to KV Store.

The TA uses an **event-based architecture** to support this deployment:

1. **Modular inputs** (`whisper_threat_intel`, `whisper_watchlist`) write enrichment data as events to the `whisper` index instead of writing directly to KV Store
2. **Saved searches** (disabled by default) read these events and populate KV Store collections on the search head via `outputlookup`

To enable the event-based pipeline on Classic Experience:

1. Enable the modular inputs via the TA configuration page
2. Enable the following saved searches:
    - **Whisper - Populate IP Threat Intel KV Store**
    - **Whisper - Populate Domain Threat Intel KV Store**
    - **Whisper - Populate Precomputed Enrichment KV Store**
3. Configure the saved search schedules to run after the input collection intervals

### Firewall Requirements

Allow outbound HTTPS (port 443) from search heads to:

- `graph.whisper.security` (production API)
- Or your configured API base URL

### AppInspect

CI runs the `splunk-appinspect` CLI against the packaged add-on on every commit, with the `cloud`, `private_victoria` and `private_classic` tag sets among others. Re-run on the shipped 1.0.0 package on 2026-08-09, all three report zero failures and zero errors.

**AppInspect is not Cloud Vetting.** AppInspect is automated static analysis that any developer can run; Cloud Vetting is Splunk's own review, including manual checks, and only a Splunk Cloud customer can trigger it by requesting the install. The per-tag results are on [Requirements](/docs/integrations/splunk/install#splunk-cloud-conformance).

## Cloud Compatibility

The TA runs identically on Splunk Enterprise, Splunk Cloud Classic, and Splunk Cloud Victoria. Feature coverage is the same across all three platforms; only the management plane and modular-input host differ.

### Capability matrix

| Capability | Enterprise | Cloud Classic | Cloud Victoria |
|------------|:----------:|:-------------:|:--------------:|
| Search commands (`whisperlookup`, `whisperquery`, `whisperschema`, `whisperevict`, `whisperflush`) | Yes | Yes | Yes |
| Modular inputs (baseline, threat intel, watchlist) | Yes | Yes (on IDM or heavy forwarder) | Yes (on search head) |
| KV Store collections (`whisper_*`) | Yes | Yes | Yes |
| API key in `storage/passwords` | Yes | Yes | Yes |
| Adaptive response action (`whisper_enrich`) | Yes | Yes | Yes |
| CIM field aliases on `whisper:enrichment` | Yes | Yes | Yes |
| Example enrichment templates (`savedsearches.conf`) | Yes | Yes | Yes |
| Investigation macros | Yes | Yes | Yes |
| Dashboard Studio dashboards | Yes | Yes | Yes |
| Custom role (`whisper_user`) | Yes | Yes | Yes |
| Ships an `indexes.conf` | No (admin creates the `whisper` index) | No | No (admin creates via ACS) |

### Cloud Classic vs Cloud Victoria

| Area | Cloud Classic | Cloud Victoria |
|------|---------------|----------------|
| App install | Splunk-managed, ticket-based | ACS-managed, self-service |
| Index creation | Splunk-managed, ticket-based | ACS API or Victoria UI |
| Modular input host | IDM or heavy forwarder | Search head |
| Upgrade cadence | Coordinated with Splunk | Self-service via ACS |

### Which objects need an API key

Search commands and dashboards work on a fresh install with no key configured. Two investigation macros do not: `whisper_cname_chain` and `whisper_spf_chain` are refused unless the search head sends a key.

Configure a key in **Configuration > Account** on every search head that will run them — see [Requirements](/docs/integrations/splunk/install#do-you-need-an-api-key).

## Configuration File Distribution

| Config File | Search Head | Indexer | Notes |
|---|---|---|---|
| `app.conf` | YES | NO | App identity and triggers |
| `commands.conf` | YES | NO | Custom search commands |
| `collections.conf` | YES | NO | KV Store schemas |
| `transforms.conf` | YES | YES* | Lookup definitions |
| `props.conf` | YES | YES* | Field extractions |
| `savedsearches.conf` | YES | NO | Correlation and population searches |
| `macros.conf` | YES | NO | Investigation macros |
| `indexes.conf` (admin-supplied) | NO | YES | Index definitions (NOT shipped — admin creates via ACS/CLI/UI) |
| `authorize.conf` | YES | NO | Custom roles |

*Only needed on indexers if index-time field extractions are configured.

## Troubleshooting

### Inputs Not Running (SHC)

If modular inputs are not collecting data on an SHC:

1. Verify the TA is deployed on all SHC members
2. Check that inputs are enabled: **Settings > Data Inputs > Whisper**
3. Verify API connectivity: run `| whisperquery query="CALL whisper.version()"` from the search bar. It returns the engine version and build time when the search head can reach the API

### Inputs Not Running (Splunk Cloud Classic)

If using Classic Experience with IDM:

1. Verify the event-based saved searches are enabled
2. Check that events are being written: search for `index=whisper sourcetype=whisper:threat_intel`
3. If events exist but KV Store is empty, verify the saved searches are running on schedule

### KV Store Replication Issues (SHC)

If collections are not replicating, verify `server.conf` includes the replication settings above, then run the check under [KV Store not replicating across SHC members](/docs/integrations/splunk/troubleshooting#kv-store-not-replicating-across-shc-members).