Source for the ViewDNS Add-on for Splunk. It enriches Splunk searches, alerts and Enterprise Security
investigations with the ViewDNS.info API: 22 lookups, a viewdns search command, an alert/adaptive response action,
a viewdns:enrichment sourcetype and the "ViewDNS Investigate" dashboard.
- Install from Splunkbase: https://splunkbase.splunk.com/app/10461
- User guide (install, configuration, command syntax and examples, lookup reference, credit usage, Splunk Cloud):
package/README.md. It ships inside the add-on. - Release notes:
RELEASE_NOTES.md
Requires Docker with Compose v2 and Python 3.9+.
python3 -m venv .venv
.venv/bin/pip install splunk-add-on-ucc-framework==6.6.1 splunk-sdk==2.1.1 requests pytest pytest-cov splunk-appinspect
scripts/build.sh # -> dist/TA-viewdns-1.0.0.tar.gz
cp .env.example .env # set SPLUNK_PASSWORD (and VIEWDNS_API_KEY for the smoke test)
docker compose up -d # Splunk 9.4 with the add-on installed; first start takes 3-5 minutes
docker compose ps # wait until STATUS shows (healthy)Then:
- Open http://localhost:8000 and log in as
adminwithSPLUNK_PASSWORDfrom.env. On Windows with WSL2,localhostworks from the Windows browser too. - Go to Apps → ViewDNS Add-on for Splunk → Configuration and save your ViewDNS API key.
- Try the ViewDNS Investigate dashboard (the app's home page) or a search:
| makeresults | eval ip="8.8.8.8" | viewdns action=reverseip field=ip limit=5 | viewdnsaccount - To test as a non-admin, create a user with the
viewdns_userrole (Settings → Users). A user with only theuserrole gets the "not allowed to run ViewDNS lookups" message.
Splunk 10.6 (Python 3.13) as a second instance on http://localhost:18000 (REST on 18089):
docker compose --profile splunk10 up -d splunk10After changing code, rebuild and reinstall into the running instance(s):
scripts/build.sh && scripts/reinstall.sh # Splunk 9.4
SPLUNK_CONTAINER=viewdns-splunk10 scripts/reinstall.sh # Splunk 10.6Helper scripts (they run inside the container, so no ports or certificates are involved):
| Script | Purpose |
|---|---|
scripts/build.sh [version] |
Build with ucc-gen and package into dist/ (see below). |
scripts/reinstall.sh |
Install the built package into the running container and restart Splunk. |
scripts/splunk_search.sh '<spl>' |
Run a search as admin; prints JSON results. |
scripts/search_as.sh <user> <password> '<spl>' |
Run a search as any user; prints messages and results. |
scripts/splunk_rest.sh <curl args> |
Call the Splunk REST API as admin. |
All of them target viewdns-splunk unless SPLUNK_CONTAINER is set.
Stop / reset:
docker compose --profile splunk10 down # stop, keep data
docker compose --profile splunk10 down -v # stop and delete all Splunk data (API key, cache, indexes)globalConfig.json UCC: configuration page (settings, proxy, logging) and the alert action
package/ add-on source (copied into the build)
app.manifest
README.md user guide (generated from docs/README.template.md; shipped)
bin/
viewdns.py `viewdns` streaming search command
viewdnsaccount.py `viewdnsaccount` generating command (account balance, free)
ta_viewdns_lookup_handler.py REST endpoint /services/ta_viewdns/lookup (capability viewdns_lookup)
ta_viewdns_settings_handler.py validates the API key when the configuration is saved
ta_viewdns/
client.py ViewDNS HTTP client: retries, typed errors, key scrubbing
actions.py the 22 lookups: validation, API call, parsing
enrich.py engine: dedupe, KV cache, credit guard, fatal errors, circuit breaker
remote.py caller side of the REST endpoint (used by commands and the alert)
output.py shapes results into events (mv / rows)
splunk_env.py settings/secrets, KV store cache, logging
modalert_viewdns_enrichment_helper.py the ViewDNS Enrichment alert action
default/ commands, searchbnf, props, transforms, collections, authorize, savedsearches,
dashboard (data/ui/views/viewdns_investigate.xml), nav
metadata/default.meta
static/, appserver/static/ icons
build/append/ stanzas appended to UCC-generated conf files (UCC overwrites, doesn't merge)
scripts/ build and Docker helpers
tests/unit/ pytest unit tests (mocked HTTP; fixtures in tests/fixtures/)
tests/smoke/smoke_test.py live API smoke test (not shipped)
tools/ dev tools: icon generator, README/reference generator
docs/ README template (source of package/README.md)
docker-compose.yml local Splunk 9.4 (+ optional 10.6)
scripts/build.sh # version from globalConfig.json
scripts/build.sh 1.0.1 # explicit versionThe script:
- Stages the build in a temporary directory on a native filesystem, so file modes are right even when the repo is on a Windows drive under WSL.
- Runs
ucc-gen build, installingpackage/lib/requirements.txtwith--no-binary=charset-normalizerso the package contains no compiled.sofiles. - Patches the UCC-generated settings REST handler to use
ViewDNSSettingsHandler, the key check on save. UCC has no hook for this on settings tabs, and the script fails loudly if UCC's output changes shape. - Appends
build/append/*.confto the generated conf files. - Strips
__pycache__, fails on any compiled binary, sets modes (dirs 755, files 644,bin/*.py755) and runsucc-gen packageintodist/.
output/TA-viewdns/ keeps an unpacked copy for inspection.
app.conf has check_for_updates = true (from meta.checkForUpdates in globalConfig.json), as Splunkbase
requires. For a private build installed directly into a Splunk Cloud stack instead of from Splunkbase, set it to
false.
Pinned dependencies (package/lib/requirements.txt):
- solnlib is pinned to 7.0.0 because 8.x pulls in grpcio (a compiled binary) and OpenTelemetry.
urllib3<2is required by splunktaucclib.
After changing lookups, regenerate the user guide's reference table:
.venv/bin/python tools/gen_readme.pyUnit tests: mocked HTTP; fixtures are the XSOAR pack's test data plus live captures (live_*.json) and the API
documentation samples (docs_*.json).
.venv/bin/python -m pytest # 179 tests
.venv/bin/python -m pytest --cov=package/bin # with coverageLive smoke test (real API, hard budget of 30 HTTP calls, never shipped):
VIEWDNS_API_KEY=<key> .venv/bin/python tests/smoke/smoke_test.py # 20 calls, 16 queries
VIEWDNS_API_KEY=<key> .venv/bin/python tests/smoke/smoke_test.py --include-paid --include-live # 28 callsInstead of passing VIEWDNS_API_KEY on the command line, you can put it in .env. --include-live runs port scan,
ping and traceroute against viewdns.info.
AppInspect:
.venv/bin/splunk-appinspect inspect dist/TA-viewdns-1.0.0.tar.gz --mode precert --included-tags cloud
.venv/bin/splunk-appinspect inspect dist/TA-viewdns-1.0.0.tar.gz --mode precert # full Splunkbase setBoth report 0 failures and 0 errors. The remaining warnings are informational or come from UCC-generated UI files (SplunkJS telemetry, the configuration page's Mako template) and bundled libraries (splunk-sdk version notice, solnlib internals, PySocks metadata).
- The API key is only ever stored in Splunk's credential store. In this repo it lives only in your git-ignored
.env. .gitignoreexcludes.env,local/directories,passwords.conf, build output and the virtualenv.- Never commit a
local/directory exported from a Splunk instance: it contains the encrypted key.
support@viewdns.info · issues: https://github.com/viewdns/splunk-addon/issues
Apache License 2.0. See package/LICENSES/Apache-2.0.txt.