# Install & Configure

> Install the Whisper Security Add-on for Splunk: requirements, Splunkbase install, creating the whisper index, and configuring the account, proxy and logging.

*Source: https://www.whisper.security/docs/integrations/splunk/install*

---
| | |
|---|---|
| **This page describes** | Whisper Security Add-on for Splunk **1.0.0** (`TA-whisper-graph`) |
| **Published** | 1.0.0, release date 2026-04-29 — declared in the shipped `app.manifest` |
| **Verified on** | Splunk Enterprise 10.2 — CI job `test-integration`, container image `splunk/splunk:10.2` |
| **Declared support** | **None.** The package declares no platform floor: `app.manifest` carries no `platformRequirements` block. `supportedDeployments` and `targetWorkloads` are both `["*"]` |
| **Not tested** | Every Splunk Enterprise release other than 10.2 · Splunk Enterprise 9.x in particular, which ships Python 3.9 as its default interpreter and cannot run this package · Splunk Cloud on either management plane — no CI job runs against a Cloud stack |
| **Conformance checks run at build** | `splunk-appinspect` CLI, tag sets `precert`, `cloud`, `private_victoria`, `private_classic`, and `future` (informational) — CI job `appinspect` |
| **Last checked** | 2026-08-09 |

Work through this page in order. The one step people skip is the middle one: the `whisper` index has to exist before the modular inputs will write anything, and the package cannot create it for you.

## Requirements

### Splunk platform versions

A floor was declared once and is gone. The add-on raised its minimum from `>=9.3` to `>=10.0` when it stopped supporting Splunk 9.x's default Python 3.9 interpreter, and the Splunk 9.4 compatibility job was removed from CI at the same time. The `platformRequirements` block was subsequently dropped from the manifest altogether, so nothing in the shipped package states a minimum today. 10.2 is what CI runs against; everything else is untested rather than unsupported, and this page will not pretend otherwise.

### Python

The add-on requires **Python 3.13**, which Splunk Enterprise 10.2 and Splunk Cloud Platform 10.2 ship as an opt-in interpreter. Every extension point (`commands.conf`, `inputs.conf`, `restmap.conf`, `alert_actions.conf`, `app.conf`) declares `python.required = 3.13`, so Splunk selects the 3.13 interpreter automatically.

### Splunk Enterprise Security

Optional. Enterprise Security is required only for the ES-specific objects — the threat-intel collections, the adaptive response action, and the events the baseline input writes to `index=risk`. Everything else works without it. No minimum ES version is declared in the package or exercised in CI, so this page states none.

### Outbound network access

The add-on requires HTTPS (port 443) access to the Whisper Security API:

| Endpoint | Protocol | Port | Purpose |
|----------|----------|------|---------|
| `graph.whisper.security` | HTTPS | 443 | Knowledge Graph API |

Allow outbound HTTPS (TCP 443) from your **search heads** — both the search commands (`whisperlookup`, `whisperquery`, `whisperschema`) and the modular inputs run there. No inbound connectivity is required; the add-on opens no listening ports.

If your Splunk server has no direct internet access, route it through a proxy — see [Proxy configuration](#proxy-configuration) below.

### An index, and an administrator who can create it

The add-on writes events to a Splunk index named `whisper`, and **you must create that index yourself before enabling the modular inputs**. The TA ships no `indexes.conf`, because Splunk Cloud Victoria Experience prohibits app-shipped index definitions — index creation is the deployment administrator's job on every platform, not just Cloud.

That means someone with the `sc_admin` role on Splunk Cloud, or an administrator on Splunk Enterprise, has to be in the room. See [Create the `whisper` index](#create-the-whisper-index) for the procedure on each platform.

### Do you need an API key?

Not to install, and not to test. The `whisperlookup` and `whisperquery` commands work without one.

Two macros do need a key: `whisper_cname_chain` and `whisper_spf_chain`. Both are refused without an account —. Sign in and generate a key at [console.whisper.security/sign-up](https://console.whisper.security/sign-up), then store it as described in [Account setup](#account-setup) below, where it is written to `storage/passwords` encrypted. Everything else in the package works before you do.

## Install the add-on

### Where the add-on runs

The add-on supports three deployment topologies. Install the TA on the **search head** in all cases — search commands and modular inputs both run on the search head.

**Single-instance deployment**

![Diagram](https://whisper.cdn.prismic.io/whisper/afJ9SsBOoF08xdEm_splunk-installation-diagram-0.svg)

Install the TA on the single Splunk instance. All components run on the same machine.

**Distributed deployment**

![Diagram](https://whisper.cdn.prismic.io/whisper/afJ9S8BOoF08xdEo_splunk-installation-diagram-1.svg)

Install the TA on the search head only. Indexers receive indexed events through the normal Splunk data pipeline. No TA installation is needed on indexers or forwarders.

**Splunk Cloud**

![Diagram](https://whisper.cdn.prismic.io/whisper/afJ9TMBOoF08xdEp_splunk-installation-diagram-2.svg)

Install the TA through self-service app installation or work with Splunk Cloud Support.

> **Search head cluster:**
> For search head cluster (SHC) deployments, deploy the TA to all cluster members via the deployer. KV Store collections replicate automatically across cluster members.

For deployment server workflows, indexer clusters, forwarder compatibility and the Victoria/Classic split in more detail, see the [Deployment Architecture](/docs/integrations/splunk/deployment-architecture) guide.

### Install from Splunkbase

The add-on is published on Splunkbase: **[Whisper Security TA on Splunkbase](https://splunkbase.splunk.com/app/8695)**.

**Option 1 — From Splunkbase (recommended):**

1. Download the latest release from [splunkbase.splunk.com/app/8695](https://splunkbase.splunk.com/app/8695).
2. In Splunk Web, navigate to **Apps > Manage Apps > Install app from file** and upload the `.tgz`.
3. Restart Splunk if prompted.

**Option 2 — From Splunk Web:**

1. Navigate to **Apps > Find More Apps** in Splunk Web.
2. Search for "Whisper Security".
3. Click **Install**.

### Splunk Cloud conformance

If you are requesting installation on a Cloud stack, this is what you are handing to Splunk's reviewers. The package is built to Splunk Cloud's app requirements and validated in CI on every commit. What the tool actually ran, re-run on the shipped `TA-whisper-graph-1.0.0.spl` on 2026-08-09:

| Check | Tool | Result |
|---|---|---|
| `precert` tag set | `splunk-appinspect` CLI 4.1.3 | 0 failures, 0 errors, 12 warnings |
| `cloud` tag set | `splunk-appinspect` CLI 4.1.3 | 0 failures, 0 errors, 9 warnings |
| `private_victoria` tag set | `splunk-appinspect` CLI 4.1.3 | 0 failures, 0 errors, 10 warnings |
| `private_classic` tag set | `splunk-appinspect` CLI 4.1.3 | 0 failures, 0 errors, 10 warnings |
| `future` tag set | `splunk-appinspect` CLI 4.1.3 | Informational only — CI runs it with `continue-on-error` and does not gate on it |

Every one of those reports carries `request_id: null`, which is how you tell a local CLI run from a run of the hosted service. These are local runs.

**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 that automated analysis does not cover — and it is triggered by a Splunk Cloud customer requesting the install, not by us. Expect a vetting queue when you request installation on Splunk Cloud.

The Cloud-specific requirements the package already satisfies:

- All credentials stored via `storage/passwords` (encrypted)
- No hardcoded file paths (uses `$SPLUNK_HOME` environment variable)
- No prohibited `.conf` files (`outputs.conf`, `authentication.conf`, etc.)
- No reserved port usage
- No shebang lines in Python files
- No `exec()`, `eval()`, or shell execution
- Uses `sc_admin` role (not `admin`) for Cloud compatibility
- SSL/TLS verification enabled on all network calls

## Create the `whisper` index

This index must exist **before** you enable the [modular inputs](/docs/integrations/splunk/using-it#modular-inputs). Nothing in the package creates it, on any platform.

The default index name is `whisper`, but you can override it via the `whisper_index` macro (see the [macros reference](/docs/integrations/splunk/reference#macros)) and update each modular input to write to a different index if required.

### Splunk Cloud Victoria Experience

Use the Admin Config Service (ACS) API or the Splunk Cloud Console to create the index.

**Via Splunk Cloud Console (recommended):**

1. Log in as a Cloud administrator (`sc_admin` role).
2. Navigate to **Settings > Indexes**.
3. Click **New Index**.
4. Enter:
   - **Index name:** `whisper`
   - **Index data type:** Events
   - **Searchable retention (days):** 180 (6 months) or per your retention policy
5. Click **Save**.

**Via ACS API:**

```bash
curl -X POST https://admin.splunk.com/<stack-name>/adminconfig/v2/indexes \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "whisper",
        "datatype": "event",
        "searchableDays": 180
      }'
```

### Splunk Cloud Classic Experience

1. Log in as a Cloud administrator.
2. Navigate to **Settings > Indexes**.
3. Click **New Index**.
4. Enter:
   - **Index name:** `whisper`
   - **Index data type:** Events
5. Click **Save**.

If self-service index management is not available on your stack, file a ticket with Splunk Cloud Support.

### Splunk Enterprise and on-premises

**Via Splunk Web:**

1. Navigate to **Settings > Indexes**.
2. Click **New Index**.
3. Enter `whisper` as the index name.
4. Configure paths (defaults are typically fine):
   - **Home path:** `$SPLUNK_DB/whisper/db`
   - **Cold path:** `$SPLUNK_DB/whisper/colddb`
   - **Thawed path:** `$SPLUNK_DB/whisper/thaweddb`
5. Optional: set **Frozen time period** to `15552000` (180 days) or your retention policy.
6. Click **Save**.

**Via CLI:**

```bash
$SPLUNK_HOME/bin/splunk add index whisper \
  -homePath '$SPLUNK_DB/whisper/db' \
  -coldPath '$SPLUNK_DB/whisper/colddb' \
  -thawedPath '$SPLUNK_DB/whisper/thaweddb' \
  -frozenTimePeriodInSecs 15552000
```

**Via `indexes.conf` (indexer cluster):**

For indexer clusters, define the index in your cluster master's `master-apps/_cluster/local/indexes.conf` — not in the TA package:

```ini
[whisper]
homePath = $SPLUNK_DB/whisper/db
coldPath = $SPLUNK_DB/whisper/colddb
thawedPath = $SPLUNK_DB/whisper/thaweddb
frozenTimePeriodInSecs = 15552000
repFactor = auto
```

Then push the bundle: `splunk apply cluster-bundle`.

### Verify the index exists

```spl
| rest /services/data/indexes
| search title="whisper"
| table title currentDBSizeMB maxTotalDataSizeMB
```

You should see one row with `title=whisper`. If the result is empty, the index does not exist and the modular inputs will fail with `IndexProcessor - cooked index=whisper not found` errors in `splunkd.log`.

## Configure the add-on

All settings are managed through the Splunk Web UI via the UCC Framework.

![Diagram](https://whisper.cdn.prismic.io/whisper/afJ9ScBOoF08xdEl_splunk-configuration-diagram-0.svg)

### Account setup

1. In Splunk Web, navigate to **Apps > Whisper Security TA > Configuration > Account**.
2. Click **Add** to create a new account.
3. Enter an account name (e.g., `production`), the API base URL, and your API key.
4. Click **Save** — the API key is stored encrypted via Splunk `storage/passwords`.

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| Account Name | Yes | -- | Unique identifier for this account |
| Base URL | Yes | `https://graph.whisper.security` | Whisper API base URL |
| API Key | Yes | -- | Whisper API Key |

### Connection settings

Navigate to **Configuration > Settings** to configure connection parameters:

| Field | Default | Range | Description |
|-------|---------|-------|-------------|
| `Request Timeout (seconds)` | 120 | 5-300 | How long the add-on waits for an API response before it gives up |
| `Proxy URL` | -- | -- | Optional HTTP/HTTPS/SOCKS5 proxy URL |

### Proxy configuration

If your Splunk server does not have direct internet access, configure a proxy in **Configuration > Settings > Proxy URL**:

| Proxy type | URL format | Example |
|-----------|-----------|---------|
| HTTP proxy | `http://host:port` | `http://proxy.internal:8080` |
| HTTPS proxy | `https://host:port` | `https://proxy.internal:8443` |
| SOCKS5 proxy | `socks5://host:port` | `socks5://proxy.internal:1080` |
| Authenticated proxy | `http://user:pass@host:port` | `http://admin:secret@proxy.internal:8080` |

> **Proxy authentication:**
> If your proxy requires authentication, include the credentials in the URL. The proxy URL is stored in Splunk's configuration system (not `storage/passwords`), so use a service account with minimal privileges.

### SSL/TLS

All API communication with `graph.whisper.security` uses HTTPS with a valid certificate. SSL certificate verification is always enabled and is not configurable.

### Logging

The add-on writes logs to `$SPLUNK_HOME/var/log/splunk/`, and Splunk indexes them into `_internal`. Every component — search commands, modular inputs and REST handlers — writes to one shared file, `ta_whisper_graph.log`:

```spl
index=_internal source=*ta_whisper_graph.log
| table _time log_level _raw
| sort -_time
```

Log verbosity follows Splunk's standard logging configuration. To change it, go to **Settings > Server Settings > Server Logging**, search for `whisper`, and set the level (DEBUG, INFO, WARNING, ERROR).

> **Debug logging:**
> Enable DEBUG logging temporarily to diagnose API connectivity or enrichment issues. Remember to set it back to INFO when done -- DEBUG logging generates significant volume.

## Verify it works

Confirm the app is installed and enabled:

```spl
| rest /services/apps/local/TA-whisper-graph
| table label version disabled
```

Confirm the search commands are registered and the account reaches the API:

```spl
| whisperquery query="RETURN 1 AS test LIMIT 1"
```

If you get a result back, you are connected. Then try an enrichment:

```spl
| makeresults | eval dest_host="example.com"
| whisperlookup field=dest_host type=domain
| table dest_host whisper_ip whisper_asn whisper_asn_name
```

## Next steps

- [Using the add-on](/docs/integrations/splunk/using-it) -- Search commands, the enrichment pipeline, and turning on the modular inputs
- [Reference](/docs/integrations/splunk/reference) -- Every shipped command, input, sourcetype, collection, lookup, field and macro
- [ES Integration](/docs/integrations/splunk/es-integration) -- Threat intel collections and correlation searches
- [Dashboards](/docs/integrations/splunk/dashboards) -- What ships in the app's own UI
- [Troubleshooting](/docs/integrations/splunk/troubleshooting) -- When one of the steps above does not do what this page says