Troubleshooting

Common errors

API

Error: whisperquery: Query rejected: write operation detected

• Cause: The Cypher query contains a write keyword (CREATE, DELETE, SET, MERGE, etc.)
• Fix: The Knowledge Graph is read-only. Remove any write operations from your query.

Error: whisperquery: Query validation failed: query must include LIMIT clause

• Cause: Missing LIMIT in the Cypher query
• Fix: Add LIMIT N to the end of your query to control result set size.

Error: Whisper API error 400: Invalid Cypher syntax

• Cause: Malformed Cypher query
• Fix: Check your query syntax.

Cache issues

Symptom: Enrichment returns stale data

• Fix: Flush the cache: | whisperflush collection=cache
• The default cache TTL is 1 hour. Adjust if needed.

Symptom: whisperflush returns permission error

• Cause: The whisperflush command requires admin or sc_admin role
• Fix: Run the command as a user with appropriate privileges.

Configuration issues

Symptom: App shows "not fully configured" after saving account

• Cause: The is_configured flag in local/app.conf was not set to true after saving the account. This is handled automatically by the UCC setup hook when you save an account through the Configuration page.
• Fix:
  1. Navigate to Configuration > Account and save the account again. The setup hook will retry setting the flag.
  2. If the issue persists, manually set is_configured=true via the REST API:

  curl -k -u admin:<password> \
    https://localhost:8089/servicesNS/nobody/TA-whisper-security/configs/conf-app/install \
    -d is_configured=true
  

  Copy
  3. Refresh the browser.

Symptom: Test Connectivity shows "Connected -- Plan: Anonymous" with a warning about unrecognized API key

• Cause: The API key you entered is invalid, expired, or incorrectly copied. The API accepted the connection but did not recognize the key, falling back to the Anonymous plan with a 2-hop depth limit.
• Fix: Verify your API key at console.whisper.security. Copy the key again and ensure there are no extra spaces or line breaks.

ES integration issues

Symptom: Correlation searches are not generating results

• Fix:
  1. Verify searches are enabled: ES > Configure > Content > Content Management
  2. Check that enrichment data exists: | inputlookup whisper_ip_intel
  3. Verify the threat intel input is running and collecting data
  4. Check search logs for errors: index=_internal source=*scheduler* savedsearch_name="Whisper*"

Symptom: Risk events are not appearing in the Risk Index

• Fix:
  1. Verify the risk index exists and is configured in ES
  2. Check that action.risk is enabled on the correlation search
  3. Review the adaptive response action logs

Dashboard issues

Symptom: Dashboards show "No results found"

• Fix:
  1. Verify that the underlying data is being collected (check for whisper:attack_surface events)
  2. Check the time range picker — default may be too narrow
  3. Ensure the compliance query inputs are running

Finding TA logs

The Whisper Security Add-on logs are written by the UCC framework to Splunk's internal index under the sourcetype ta_whisper_security. This is the UCC default naming convention and differs from the whisper:* sourcetype pattern used for indexed data.

Search for TA logs:

index=_internal sourcetype="ta_whisper_security"

Filter by log level:

index=_internal sourcetype="ta_whisper_security" log_level=ERROR

View recent TA activity:

index=_internal sourcetype="ta_whisper_security"
| table _time log_level component message
| sort -_time
| head 50

These logs include modular input execution, API calls, configuration changes, and error details. The Health & Operations dashboard also includes a TA Logs panel that displays recent log entries from this sourcetype.

Note: Do not confuse sourcetype="ta_whisper_security" (TA operational logs in index=_internal) with sourcetype="whisper:health" or other whisper:* sourcetypes (indexed data in index=whisper).

Diagnostic commands

Check API connectivity:

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

Check cache status:

| inputlookup whisper_enrichment_cache
| stats count, min(cached_at) AS oldest, max(cached_at) AS newest

Check threat intel collections:

| inputlookup whisper_ip_intel | stats count
| append [| inputlookup whisper_domain_intel | stats count]

Check modular input status:

index=_internal source=*whisper* sourcetype=splunkd
| stats latest(_time) AS last_run, count by source

Check the adaptive response alert action log:

The whisper_enrich alert action writes to $SPLUNK_HOME/var/log/splunk/ta_whisper_security.log (the shared log file for all TA components).

tail -f $SPLUNK_HOME/var/log/splunk/ta_whisper_security.log

Verify Knowledge Graph schema:

| whisperschema mode=labels

Asset cache management (development)

After modifying JavaScript, CSS, or HTML files in the add-on, both client-side and server-side caches must be cleared for changes to take effect.

Client cache bump

Navigate to the following URL in your browser to bump the client cache version:

http://<splunk_host>:<port>/en-US/_bump

Click "Bump version" to invalidate all cached static assets. This forces browsers to re-fetch updated files.

Server cache refresh

Refresh the server-side asset cache by navigating to:

http://<splunk_host>:<port>/en-US/debug/refresh

This reloads all app assets from disk without requiring a Splunk restart.

Development-only cache settings

For active development, you can disable asset caching entirely by adding these settings to local/web.conf:

[settings]
cacheEntriesLimit = 0
cacheBytesLimit = 0

Warning: Never disable caching in production environments. These settings significantly degrade Splunk Web performance and are intended only for local development.

Recommended workflow

After any UI file change during development:

1. Save the modified file(s)
2. Navigate to /_bump and click "Bump version"
3. Navigate to /debug/refresh
4. Hard-refresh the browser (Cmd+Shift+R on macOS, Ctrl+Shift+R on Windows/Linux)

File precedence and customization

Splunk merges configuration files from multiple locations using a defined precedence order. This matters when you're customizing the Whisper Security Add-on.

Precedence order (lowest to highest)

1. system/default/ -- Splunk platform defaults
2. app/default/ -- Add-on shipped defaults (TA-whisper-security)
3. system/local/ -- System-wide admin overrides
4. app/local/ -- Per-app admin overrides
5. user/default/ -- User-specific defaults (rare)
6. user/local/ -- User-specific overrides

Settings in higher-precedence locations override those in lower locations. The add-on ships all configuration in default/ -- admin customizations should go in the app's local/ directory.

Settings safe to override in local/

These configuration files can be safely customized by admins:

Example: Enable a correlation search:

# local/savedsearches.conf
[Whisper - DNS Infrastructure Change Correlation]
disabled = 0

Example: Override the default index macro:

# local/macros.conf
[whisper_index]
definition = index=my_custom_whisper_index

Settings NOT safe to override

Do not modify these files in local/ -- doing so may break add-on functionality:

Resetting customizations

To revert all customizations for a specific configuration file:

1. Navigate to $SPLUNK_HOME/etc/apps/TA-whisper-security/local/
2. Delete the specific .conf file (e.g., savedsearches.conf)
3. Restart Splunk to apply the reset

To reset all customizations:

rm -rf $SPLUNK_HOME/etc/apps/TA-whisper-security/local/
$SPLUNK_HOME/bin/splunk restart

Note: This removes all local overrides. Back up the local/ directory first if you want to preserve any settings.

Known issues

Collecting logs for support

When reporting an issue, collect the following logs to help diagnose the problem.

Step 1: Export TA logs

index=_internal source=*ta_whisper_security.log earliest=-24h
| table _time log_level component message
| sort -_time

Step 2: Export health check history

index=whisper sourcetype=whisper:health earliest=-7d
| table _time status error_message response_time_ms node_count edge_count

Step 3: Check modular input status

index=_internal source=*splunkd.log ExecProcessor whisper earliest=-24h
| table _time log_level message

Step 4: Generate a diagnostic bundle

$SPLUNK_HOME/bin/splunk diag --collect app:TA-whisper-security

This collects app configuration, logs, and KV Store metadata (but not credentials or customer data).

Step 5: Open a support ticket

Open a support ticket at console.whisper.security/support and attach the diagnostic bundle and log exports.

Getting help

• Support: console.whisper.security/support
• Whisper Security: whisper.security