# Splunk

Splunk in Docker with index and HEC configured. The deploy script handles **Docker create/destroy** the same way as [deploy_misp.sh](../misp_config/deploy_misp.sh): idempotent deploy, optional destroy for a clean re-deploy.

## Quick start

```bash
cd splunk_config
./deploy_splunk.sh
```

- **First run:** Pulls the image, starts the container, waits for Splunk to be ready, then configures index and HEC.
- **Later runs:** If the Splunk container already exists, the script starts it (if stopped), recreates to apply config, then re-runs post-deploy config and exits.

## Destroy (clean re-deploy)

To remove the Splunk container and all volumes (data, etc.):

```bash
./deploy_splunk.sh destroy
```

Also accepted: `--destroy` or `-d`. After destroy, run `./deploy_splunk.sh` again for a fresh deploy. The script directory and `docker-compose.yml` are left in place; only containers and volumes are removed.

## What the deploy script does

- **Preflight:** Checks Docker, Docker Compose, and ports 8000, 8088, 8089.
- **Existing install:** If the `splunk` container exists, starts/recreates it, waits for healthy, runs post-deploy config, prints access info, exits.
- **Fresh deploy:** Pulls image, starts container, waits for healthy, then:
  - **Creates** the `threat_intel` index.
  - **Enables HEC** using the token from `docker-compose.yml` (`SPLUNK_HEC_TOKEN`); writes it to `splunk_hec_token.txt` in this directory.
- Splunk is attached to the **security-lab** Docker network (for integrations with n8n and other lab services).

## License (Splunk Developer)

The `splunk.lic` in this folder is a **Splunk Developer license** associated with the me (Buddy) that will expire on August 17, 2026 11:59 PM. This setup expects that file (or your own) at `splunk.lic` in this directory (mounted into the container via the Dockerfile as a default). The **Splunk Developer Program** offers a free developer license that is valid for **6 months**; anyone can apply and request a new license when it expires.

**How to get a developer license:**

1. Go to the [Splunk Developer Portal](https://dev.splunk.com/) and **Sign up** or **Log in**.
2. Open **Documentation & Tooling** → **Request Developer License** (or [Request License](https://dev.splunk.com/enterprise/dev_license/) directly).
3. Submit the form and download your `splunk.lic` file.
4. Place `splunk.lic` in the `splunk_config` directory (next to `docker-compose.yml`).

**Application tip:** The Splunk Developer Program **manually reviews** each application. They will **likely not approve** a distro or throwaway email address. Use a **personal or work email** you can receive mail at when applying.

For more detail (manual HEC setup, sample SPL, n8n workflow examples, and script snippets), see [Splunk Developer.md](Splunk Developer.md) in this folder.

## Environment variables (optional)

Set before running to override defaults:

| Variable | Default | Description |
|----------|---------|-------------|
| `SPLUNK_PASS` | `YourSecurePassword123!` | Admin password for Splunk Web and API |
| `SPLUNK_HEC_TOKEN` | *(in docker-compose.yml)* | HEC token; must match value in compose and ingestion scripts |

## MISP42Splunk (optional)

[MISP42Splunk](https://github.com/remg427/misp42splunk) is a Splunk app that integrates Splunk with MISP: it can pull IOCs from MISP (e.g. for retrosearch) and push data from Splunk to MISP. The MISP stack in this lab is already set up for it: [deploy_misp.sh](../misp_config/deploy_misp.sh) publishes all events so MISP42Splunk’s `last/publish_timestamp`–based queries work.

A copy of the app package is in this folder: **`misp42splunk-5.0.0.tar.gz`**. Installation is **manual** only. When we tried to automate installing and configuring the app (e.g. via deploy script or container startup), we ran into several issues (app state, permissions, and Splunk’s app lifecycle), so we do not automate it. Install and configure the app yourself as follows.

**Install (manual):**

1. Ensure Splunk is running (`./deploy_splunk.sh` or `docker compose up -d`).
2. In Splunk Web (**http://localhost:8000**), go to **Apps** → **Manage Apps** → **Install app from file**.
3. Upload **`misp42splunk-5.0.0.tar.gz`** from this directory (or browse to it). Restart Splunk if prompted.
4. Go to **Apps** → **MISP42** (or the app name as shown). Configure the MISP connection:
   - **MISP URL:** Use the URL reachable from the Splunk container. If Splunk runs in Docker on the same host as MISP, try `https://host.docker.internal:8443` or the host’s IP and port (e.g. `https://localhost:8443` only works if Splunk is not in Docker or shares the host network).
   - **MISP API key:** Use the key from **`../misp_config/misp_api_key.txt`** (generated by `deploy_misp.sh`).
   - **SSL:** For a lab with self-signed certs, disable certificate verification if the app offers that option.

After configuration, you can use the app’s custom commands and alert actions to query MISP and run retrosearch with MISP IOCs.

## Files

| File | Purpose |
|------|--------|
| `docker-compose.yml` | Splunk container; HEC token set via `SPLUNK_HEC_TOKEN`. |
| `deploy_splunk.sh` | Idempotent deploy/destroy: Docker create or destroy, then index and HEC. |
| `splunk_hec_token.txt` | Written by deploy script; use in n8n or other HEC clients. |
| `splunk.lic` | Splunk license file (mounted into container). |
| *(Optional)* `misp42splunk-5.0.0.tar.gz` | MISP42Splunk Splunk app package; install manually via Splunk Web (see [MISP42Splunk (optional)](#misp42splunk-optional)). |
| `simulate_firewall_alert.py` | Simulates a firewall alert with a URL IOC, sends it to Splunk via HEC. Optionally triggers an n8n webhook for enrichment (e.g. VirusTotal, URLScan). Reads HEC token from `splunk_hec_token.txt` or `SPLUNK_HEC_TOKEN`. Run from `splunk_config`: `python3 simulate_firewall_alert.py [--url URL] [--n8n-webhook URL]`. |
| *(Optional)* `ingest_iocs/insert_iocs.py` | Inserts sample IOCs (ThreatFox, MalwareBazaar, URLhaus, and email indicators) into Splunk via HEC. Run manually from `ingest_iocs/`. Ensure HEC URL/token in script match your deploy (or use env/file). |
| *(Optional)* `ingest_iocs/ingest_tweetfeed_to_splunk.py` | Fetches the TweetFeed RSS feed and ingests IOCs into Splunk via HEC. Run manually from `ingest_iocs/`. |
| *(Optional)* `ingest_iocs/malwarebazaar_to_splunk.sh` | Fetches the MalwareBazaar recent CSV, parses SHA-256 hashes and metadata, and sends them to Splunk via HEC. Run manually from `ingest_iocs/` (e.g. `python3 malwarebazaar_to_splunk.sh`). |

## Management

From the script directory:

| Action | Command |
|--------|---------|
| Start | `docker compose up -d` |
| Stop | `docker compose down` |
| Destroy (containers + volumes) | `./deploy_splunk.sh destroy` |
| Logs | `docker logs -f splunk` |

## Ports

- **8000** — Web UI  
- **8088** — HEC  
- **8089** — Management API
