Metadata-Version: 2.4
Name: splunkctl
Version: 0.3.0
Summary: CLI tool for Splunk Enterprise SIEM operations.
Author: dannyota
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/dannyota/splunkctl
Project-URL: Repository, https://github.com/dannyota/splunkctl
Project-URL: Issues, https://github.com/dannyota/splunkctl/issues
Keywords: splunk,siem,security,cli,detection,spl
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: splunk-sdk>=2.0
Requires-Dist: click>=8.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: tabulate>=0.9
Requires-Dist: requests>=2.32
Requires-Dist: defusedxml>=0.7
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: types-tabulate; extra == "dev"
Requires-Dist: types-defusedxml; extra == "dev"
Dynamic: license-file

# splunkctl

CLI tool for Splunk Enterprise SIEM operations.

Query, inspect, and manage a remote Splunk Enterprise instance from your
laptop. Built on the [splunk-sdk-python](https://github.com/dannyota/splunk-sdk-python/tree/splunkctl)
fork with [Click](https://click.palletsprojects.com/).

## Install

```bash
pip install splunkctl
pip install git+https://github.com/dannyota/splunk-sdk-python@splunkctl
```

Requires Python 3.13+. The second line installs the
[forked SDK](https://github.com/dannyota/splunk-sdk-python/tree/splunkctl)
which adds dashboard, lookup, and HEC token support. Without it, core
commands (search, rules, alerts, indexes, inputs, apps, users) still work.

### Development

```bash
git clone https://github.com/dannyota/splunkctl
cd splunkctl
pip install -e .
splunkctl --version
```

## Quick start

```bash
splunkctl config init                         # interactive setup
splunkctl doctor                              # check connection, auth, permissions
splunkctl search run 'index=main | head 10'   # run a search
splunkctl rules list                          # list detection rules
```

## Commands

| Group | Description |
|---|---|
| `doctor` | Connection, auth, health, and permissions check |
| `config` | Setup, show config, test connectivity |
| `info` | Server info (version, OS, license) |
| `search` | Run, export, oneshot, upload, job management |
| `rules` | Detection rules — CRUD, import/export (YAML) |
| `alerts` | Fired alerts, alert actions, suppression |
| `dashboards` | Dashboard CRUD (XML) |
| `indexes` | Index management |
| `inputs` | Data inputs (monitor, tcp, udp, script, http) |
| `lookups` | Lookup table CRUD (CSV, mmdb) |
| `hec` | HEC token management |
| `parsers` | Source types and field extractions |
| `apps` | App install (.spl/.tar.gz), uninstall, update |
| `users` | User and role management |
| `commands` | Machine-readable command tree (JSON) |
| `skill` | Embedded agent operating guide |

## Key features

### Detection-as-code

Export existing rules to YAML, version control them, deploy across
instances:

```bash
splunkctl rules export --path detections.yml
splunkctl rules import --path detections.yml        # dry-run preview
splunkctl --yes rules import --path detections.yml  # apply
```

### Remote file operations

Upload files from your laptop without SSH access to the server:

```bash
# Upload threat intel, logs, or sample data for indexing
splunkctl --yes search upload --path threats.csv --index threat_intel --sourcetype csv

# Upload lookup tables (CSV or GeoIP mmdb)
splunkctl --yes lookups upload --name threats.csv --path threats.csv

# Install apps from local .spl/.tar.gz packages
splunkctl --yes apps install --path TA_windows.spl
```

### Diagnostics

```bash
splunkctl doctor             # check everything: connection, auth, health, permissions
splunkctl doctor --json      # machine-readable output
```

## Global flags

```
--json              Force JSON output
--format FMT        Output format: table, json, csv, jsonl
--fields f1,f2      Project specific fields
--out FILE          Write output to file
--yes / -y          Apply mutations (skip dry-run preview)
--timeout N         Request timeout in seconds (default 30)
--config FILE       Config file path
--debug             HTTP request/response logging
```

## Dry-run by default

All write operations preview what would change. Pass `--yes` to apply.

```bash
splunkctl rules delete 'My Rule'          # shows preview only
splunkctl rules delete 'My Rule' --yes    # actually deletes
```

## Output formats

```bash
splunkctl rules list                      # table (TTY) or JSON (pipe)
splunkctl rules list --json               # force JSON
splunkctl rules list --format csv         # CSV
splunkctl rules list --fields name,cron   # project fields
splunkctl rules list --out rules.json     # write to file
```

## SDK fork

splunkctl depends on a [fork of splunk-sdk-python](https://github.com/dannyota/splunk-sdk-python/tree/splunkctl)
that adds entity classes missing from the upstream SDK:

| Entity | Service property | Purpose |
|---|---|---|
| `Dashboard` | `service.dashboards` | Dashboard CRUD |
| `LookupTableFile` | `service.lookup_table_files` | Lookup table metadata + download |
| `HECToken` | `service.hec_tokens` | HEC token management |

Install the fork directly:

```bash
pip install git+https://github.com/dannyota/splunk-sdk-python@splunkctl
```

## Agent integration

splunkctl ships with an embedded operating guide for AI agents
(Claude Code, etc.):

```bash
splunkctl skill                           # print the guide
splunkctl skill install                   # install to ~/.claude/skills/
splunkctl commands                        # JSON command tree for discovery
```

## License

Apache-2.0
