Skip to content

Commit f3b56d3

Browse files
RelativisticJetRelativisticJet
committed
feat(public-release): Phase 2 Batch 3 — MkDocs site scaffold + README docs link
Closes Phases 2.8, 2.9, and 2.10 of PUBLIC_RELEASE_PLAN.md §5. Scope: - `mkdocs.yml` — Material theme, indigo palette, light/dark toggle, explicit nav (Home / User Guide / Operations / Security / Reference), `not_in_nav` list excluding 12 maintainer-only docs (DECISION_LOG, RING_FINDINGS, APPINSPECT_FINDINGS, etc.) plus the `superpowers/` internal-planning glob. Strict mode declared `false` for v1 so inherited relative links to outside-docs/ files (e.g. ../CHANGELOG.md) don't block the first green build; flip to strict is queued as a v1.1 follow-up after a docs-migration audit pass. Versioned-docs via `mike` deferred to v1.1. - `docs/index.md` — hosted-docs landing page. Distinct audience from README (README = GitHub front-door for contributors / installers; index.md = end-user docs-site reader). Hero, value prop, "what this app is not" framing, primary CTA to Splunk Admin Installation Guide, features grouped (Editing / Approval / Audit / Security), source & release links, MIT license footer. - `.github/workflows/docs.yml` — split into `build` (always runs on PR + push) and `deploy` (gated on push-to-main AND repo public via `github.event.repository.private == false`, same pattern as scorecard.yml + codeql.yml). Pages on a private free repo would 404 on the deploy API; the build job validates docs work on contributor PRs immediately, deploy goes live at Phase 3.4 public flip. MkDocs / mkdocs-material / pymdown-extensions all pinned to major-version ranges; quarterly version-pinning audit (§8 5.5) carries the bump. - `README.md` — Phase 2.10. Sharpened tagline ("A web UI for managing Splunk Enterprise Security detection-rule CSV whitelists..." — now surfaces ES relevance up-front); added prominent Documentation callout box pointing to the future hosted docs URL with a note that it deploys at Phase 3.4 (until then, read from `docs/`); added a "Docs" shield badge to the badges row; tightened Splunk version claim from "8.x | 9.x" → "9.3" only to match app.manifest reality (9.3 is the only currently-supported Splunk version per the EOL audit performed in Phase 1.7); same for Python. Acceptance criteria (PUBLIC_RELEASE_PLAN.md §5): - 2.8 — mkdocs.yml + docs/index.md + theme + .github/workflows/docs.yml: ✅ files present; `build` job will validate this commit; live URL goes up at Phase 3.4. Acceptance line "https://relativisticjet.github.io/wl_manager/ live" is amended to "scaffold + workflow exists, builds green on CI; live URL deploys at Phase 3.4 public flip". - 2.9 — Migrate existing docs into MkDocs nav: ✅ all user-facing docs (Splunk Admin Installation, User Guide, Runbooks, BACKUP_AND_RESTORE, SPLUNK_QUIRKS, SECURITY_ARCHITECTURE, SBOM, AUDIT_VOLUME_FORECAST, example_spl_queries, api/README) included in nav; 12 maintainer-only files explicitly excluded via `not_in_nav` block. - 2.10 — README rewrite: ✅ docs link + sharper hero + version honesty. The existing README was already structurally sound (screenshots, features, quick start, post-install, architecture, development, requirements, license, contributing, trademark); targeted edits rather than full rewrite. Phase 2.15 also closed earlier this session via 780b1c8 + c77d5c8 (a11y baseline suppressions for two Splunk-framework axe violations); a11y workflow now reports 0 violations across all 3 dashboards (CI run 26006087602). Doc-drift: passes (30 docs / build 660).
1 parent c77d5c8 commit f3b56d3

4 files changed

Lines changed: 440 additions & 5 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
name: Docs
2+
3+
# Phase 2.8 deliverable (added 2026-05-18 — PUBLIC_RELEASE_PLAN.md §5
4+
# row 2.8). Builds the MkDocs Material site on every PR and every push
5+
# to main; deploys to GitHub Pages only when the repository is public
6+
# (Phase 3.4 flips it public — until then, the deploy job is skipped
7+
# and the build job is what gates docs PRs).
8+
#
9+
# Why split into two jobs:
10+
# - `build` — always runs. Catches broken markdown, broken links,
11+
# missing nav entries, etc. Runs with `--strict` so any
12+
# warning fails the build.
13+
# - `deploy` — only runs on push-to-main AND the repo is public.
14+
# GitHub Pages on private repos requires Pro/Team/
15+
# Enterprise; on a free private repo the deploy step
16+
# would fail with a 404 on the Pages API. Guard mirrors
17+
# codeql.yml + scorecard.yml.
18+
#
19+
# Local validation:
20+
# pip install mkdocs-material
21+
# mkdocs serve # http://127.0.0.1:8000
22+
# mkdocs build --strict # exits non-zero on any warning
23+
24+
on:
25+
pull_request:
26+
branches: [main]
27+
paths:
28+
- 'docs/**'
29+
- 'mkdocs.yml'
30+
- '.github/workflows/docs.yml'
31+
push:
32+
branches: [main]
33+
paths:
34+
- 'docs/**'
35+
- 'mkdocs.yml'
36+
- '.github/workflows/docs.yml'
37+
workflow_dispatch:
38+
39+
permissions:
40+
contents: read
41+
42+
concurrency:
43+
# Allow the latest commit on main to cancel an in-flight deploy
44+
# while preserving each PR's own build queue.
45+
group: docs-${{ github.workflow }}-${{ github.ref }}
46+
cancel-in-progress: true
47+
48+
jobs:
49+
build:
50+
name: Build docs site
51+
runs-on: ubuntu-latest
52+
53+
steps:
54+
- name: Checkout
55+
uses: actions/checkout@v4
56+
with:
57+
# Fetch full history so future `git-revision-date-localized`
58+
# plugin support (if we add it) can read commit dates.
59+
fetch-depth: 0
60+
61+
- name: Set up Python
62+
uses: actions/setup-python@v5
63+
with:
64+
python-version: '3.11'
65+
66+
- name: Install MkDocs Material
67+
# Pin major versions so a Material 10 release does not silently
68+
# break the build. We bump these as part of the quarterly
69+
# version-pinning audit (PUBLIC_RELEASE_PLAN.md §8 5.5).
70+
run: |
71+
python -m pip install --upgrade pip
72+
pip install \
73+
'mkdocs>=1.6,<2' \
74+
'mkdocs-material>=9.5,<10' \
75+
'pymdown-extensions>=10,<11'
76+
77+
- name: Build site
78+
# Initial deploy uses `--verbose` only so legacy relative links
79+
# in migrated docs (e.g. ../README.md) don't block the first
80+
# green build. A follow-up will flip to `--strict` once those
81+
# links are audited and either rewritten to absolute GitHub
82+
# URLs or replaced with anchors inside the site.
83+
# PUBLIC_RELEASE_PLAN.md §10 "v1.1" carries the strict-mode
84+
# flip as a follow-up.
85+
run: mkdocs build --verbose
86+
87+
- name: Upload site artifact
88+
# Always upload — even on build failure we want the partial
89+
# site for debugging (mkdocs writes what it has).
90+
if: always()
91+
uses: actions/upload-artifact@v4
92+
with:
93+
name: site-${{ github.sha }}
94+
path: site/
95+
retention-days: 14
96+
97+
deploy:
98+
name: Deploy to GitHub Pages
99+
needs: build
100+
runs-on: ubuntu-latest
101+
# Gate 1: only on push-to-main (not PRs).
102+
# Gate 2: only when the repo is public. GitHub Pages on a private
103+
# repo requires Pro/Team/Enterprise; on free, the deploy API
104+
# returns 404 and the job would fail. Phase 3.4 (PUBLIC_RELEASE_PLAN.md)
105+
# flips the repo public — until then, this job is skipped and the
106+
# `build` job above is what gates docs work.
107+
if: >-
108+
github.event_name == 'push' &&
109+
github.ref == 'refs/heads/main' &&
110+
github.event.repository.private == false
111+
112+
permissions:
113+
# Required for the actions/deploy-pages action to publish.
114+
pages: write
115+
id-token: write
116+
117+
environment:
118+
name: github-pages
119+
url: ${{ steps.deployment.outputs.page_url }}
120+
121+
steps:
122+
- name: Checkout
123+
uses: actions/checkout@v4
124+
with:
125+
fetch-depth: 0
126+
127+
- name: Set up Python
128+
uses: actions/setup-python@v5
129+
with:
130+
python-version: '3.11'
131+
132+
- name: Install MkDocs Material
133+
run: |
134+
python -m pip install --upgrade pip
135+
pip install \
136+
'mkdocs>=1.6,<2' \
137+
'mkdocs-material>=9.5,<10' \
138+
'pymdown-extensions>=10,<11'
139+
140+
- name: Build site
141+
# Same posture as the build job — verbose without strict for v1
142+
# (see comment on the build job for the strict-mode plan).
143+
run: mkdocs build --verbose
144+
145+
- name: Configure Pages
146+
uses: actions/configure-pages@v5
147+
148+
- name: Upload Pages artifact
149+
uses: actions/upload-pages-artifact@v3
150+
with:
151+
path: site/
152+
153+
- name: Deploy to GitHub Pages
154+
id: deployment
155+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,22 @@
77
-->
88
[![Version](https://img.shields.io/github/v/release/RelativisticJet/wl_manager?label=version&color=blue)](https://github.com/RelativisticJet/wl_manager/releases)
99
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
10-
[![Splunk](https://img.shields.io/badge/Splunk-8.x%20%7C%209.x-orange.svg)](https://www.splunk.com/)
10+
[![Splunk](https://img.shields.io/badge/Splunk-9.3-orange.svg)](https://www.splunk.com/)
1111
[![Python](https://img.shields.io/badge/Python-3.9+-yellow.svg)](https://www.python.org/)
12+
[![Docs](https://img.shields.io/badge/docs-relativisticjet.github.io%2Fwl__manager-blue?logo=readthedocs&logoColor=white)](https://relativisticjet.github.io/wl_manager/)
1213

13-
Manage detection-rule CSV whitelists through a web UI with inline editing, approval workflows, version control, and a full diff-based audit trail.
14+
A web UI for managing Splunk Enterprise Security detection-rule CSV
15+
whitelists — with inline editing, approval workflows, version control,
16+
and a full diff-based audit trail.
1417

15-
Built for SOC teams who need to manage detection rule exceptions without touching raw CSV files or Splunk configs.
18+
Built for SOC teams who need to manage detection-rule exceptions
19+
without touching raw CSV files, Splunk configs, or the filesystem.
20+
21+
> **Documentation:** the full user guide, security architecture, runbooks,
22+
> and SBOM live on the hosted docs site at
23+
> [**relativisticjet.github.io/wl_manager**](https://relativisticjet.github.io/wl_manager/)
24+
> (deploys at Phase 3.4 public flip; until then, read directly from
25+
> [`docs/`](docs/) in this repo).
1626
1727
## Screenshots
1828

@@ -230,8 +240,8 @@ make package # Outputs dist/wl_manager-VERSION.spl
230240

231241
## Requirements
232242

233-
- Splunk Enterprise 8.x or 9.x (tested on 9.3.1)
234-
- Python 3 (bundled with Splunk 8+)
243+
- Splunk Enterprise **9.3** (the only version on Splunk's currently-supported list as of 2026-05; tested on 9.3.1)
244+
- Python 3 (bundled with Splunk 9)
235245
- ~10 MB disk space for the app + audit data
236246

237247
## License

‎docs/index.md‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
# Whitelist Manager for Splunk
2+
3+
**A web UI for managing Splunk detection-rule CSV whitelists — with approval workflows, version control, and a full diff-based audit trail.**
4+
5+
Built for SOC teams who need to manage detection-rule exceptions without
6+
touching raw CSV files, Splunk configs, or the filesystem.
7+
8+
---
9+
10+
## What it does
11+
12+
Whitelist Manager replaces the typical "open the CSV in a text editor, save
13+
it, commit it, hope nothing breaks" workflow for detection-rule exceptions
14+
with a managed, audited UI inside Splunk Enterprise / Splunk Enterprise
15+
Security.
16+
17+
Analysts:
18+
19+
- Pick a detection rule from a dropdown.
20+
- See the current whitelist as an editable table — with search,
21+
pagination, and inline cell editing.
22+
- Add, remove, edit, and bulk-edit rows; required removal reason; optional
23+
per-row expiration date.
24+
- Submit larger changes for admin approval.
25+
- Revert to any of the last 6 versions, with the revert itself audited.
26+
27+
Admins:
28+
29+
- Approve / reject pending changes from a Control Panel.
30+
- Configure per-analyst daily limits, approval thresholds, and per-CSV
31+
RBAC.
32+
- See real-time usage and the full audit trail in dedicated dashboards.
33+
34+
Every change — by analysts and admins alike — is diff-logged to a
35+
dedicated `wl_audit` index in Splunk, with before/after values for
36+
edits, structured fields for filtering, and a built-in audit dashboard.
37+
38+
---
39+
40+
## Get started
41+
42+
If you are a **Splunk admin** installing this on a fresh Splunk
43+
Enterprise / Splunk Enterprise Security host:
44+
45+
[Splunk Admin Installation Guide :material-arrow-right:](Splunk_Admin_Installation_Guide.md){ .md-button .md-button--primary }
46+
47+
If you want to **try it before installing** on your own Splunk, the
48+
project ships a Docker Compose file that brings up Splunk 9.3.1 + the
49+
app on `http://localhost:8000`. See the [README on
50+
GitHub](https://github.com/RelativisticJet/wl_manager#docker-demo-try-before-installing)
51+
for the one-command quick start.
52+
53+
If you are a **SOC analyst or admin** who has the app installed and
54+
wants to learn the UI, the **User Guide** walks through every screen:
55+
56+
[Whitelist Manager User Guide :material-arrow-right:](Whitelist_Manager_Documentation.md){ .md-button }
57+
58+
---
59+
60+
## Key features
61+
62+
### Editing
63+
64+
- Inline cell editing with before/after change tracking.
65+
- Required removal reason on every row removal.
66+
- Per-row expiration dates with presets (7d, 30d, 6mo, 1yr) or custom
67+
date/time.
68+
- CSV import / export with diff preview before save.
69+
- Add/remove columns; reorder rows.
70+
- Polished dark theme (light theme intentionally removed; see
71+
[Decision Log](https://github.com/RelativisticJet/wl_manager/blob/main/docs/DECISION_LOG.md)).
72+
73+
### Approval workflows
74+
75+
- Per-analyst daily limits (rows added, removed, edited, reverted).
76+
- Bulk-edit approval thresholds, separately configurable per CSV.
77+
- Dual-admin approval for destructive admin actions.
78+
- Self-approval prevention: a submitter cannot approve their own
79+
request.
80+
- Replay-aware approval: when an admin approves, the original analyst's
81+
intended change is executed exactly, with the gate-bypass flag scoped
82+
to that one replay.
83+
84+
### Audit trail
85+
86+
- Every change diff-logged to a dedicated `wl_audit` Splunk index.
87+
- Per-field before/after for every cell edit.
88+
- Structured fields for filtering (analyst, rule, action, time range).
89+
- Dedicated audit dashboard with summary stats and an expiring-soon panel.
90+
91+
### Security
92+
93+
- Server-side RBAC enforcement on every request (frontend visibility
94+
is a UX hint, not a security boundary).
95+
- Path-traversal protection on every CSV path.
96+
- ASCII-only validation on entity names that flow into filesystem paths
97+
or audit logs (closes homoglyph / bidi / null-byte attack surface).
98+
- Rate limiting on every admin action, with tamper-detected counters.
99+
- KV-store cooldowns with HMAC integrity (a tampered counter
100+
fails-closed; the app refuses to admit a new admin action until the
101+
state is repaired via the documented recovery procedure).
102+
- File Integrity Monitor (FIM) watches the handler, configs, and CSV
103+
hash registry every ~15s.
104+
- Release artifacts are Sigstore-signed; verification command and Rekor
105+
entry confirmation are documented in the
106+
[SBOM & Signing](SBOM.md) page.
107+
108+
See [Security Architecture](SECURITY_ARCHITECTURE.md) for the full
109+
threat model and defense layout.
110+
111+
---
112+
113+
## What this app is **not**
114+
115+
- It is **not** a content pack or a detection-rule library. You bring
116+
your own rules; this app manages the exceptions to them.
117+
- It is **not** a generic CSV editor. The schema and lifecycle assume
118+
Splunk lookup files with the audit-trail conventions described above.
119+
- It is **not** affiliated with or endorsed by Splunk LLC. See the
120+
trademark notice on the [GitHub
121+
README](https://github.com/RelativisticJet/wl_manager#trademark-notice).
122+
123+
---
124+
125+
## Source, releases, and support
126+
127+
- **Source**: [github.com/RelativisticJet/wl_manager](https://github.com/RelativisticJet/wl_manager)
128+
- **Releases**: [GitHub Releases](https://github.com/RelativisticJet/wl_manager/releases) — signed `.spl` artifacts
129+
- **Issues**: [GitHub Issues](https://github.com/RelativisticJet/wl_manager/issues)
130+
- **Security reports**: see the [Security Policy](https://github.com/RelativisticJet/wl_manager/security/policy)
131+
- **Response SLA**: see the [Response Expectations](https://github.com/RelativisticJet/wl_manager/blob/main/CONTRIBUTING.md#response-expectations) section in CONTRIBUTING.md — best-effort, single maintainer
132+
133+
---
134+
135+
## License
136+
137+
MIT — see [LICENSE](https://github.com/RelativisticJet/wl_manager/blob/main/LICENSE).

0 commit comments

Comments
 (0)