diff --git a/.gitignore b/.gitignore index 61ad7d6..421740a 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,7 @@ __pycache__/ .Python *.so .pytest_cache/ +.hypothesis/ .coverage htmlcov/ coverage.json @@ -57,7 +58,9 @@ lookups/_presence.json # Development/testing files # Note: tests/ directory is committed to git; only cache excluded via .pytest_cache # test_*.py patterns are excluded only for ad-hoc test files in root, not in tests/ -CLAUDE.md +# Note: CLAUDE.md removed from this exclusion 2026-07-18 — it is now a tracked +# developer/agent guidance file (contains Splunk version-pinning audit checklist +# and audit log). Session-local Claude context goes in .claude/ instead. login-check 081-after-rule-select *.log diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..3ee06ca --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,82 @@ +# CLAUDE.md — wl_manager developer notes + +This file documents conventions, architecture notes, and recurring +operational tasks for contributors and automated agents working in this repo. + +--- + +## Splunk Version Pinning Audit + +### Why we pin + +`docker-compose.yml` pins `splunk/splunk:` to give the local E2E test +environment a known-good, reproducible Splunk binary. An unpinned `latest` tag +would silently pick up new Splunk majors, potentially breaking E2E tests with +no obvious cause. + +The pin is re-evaluated every quarter (and on-demand after a CVE advisory) to +ensure we are not running unsupported software or missing critical security +patches. + +### Upgrade decision criteria + +| Criterion | Action | +|---|---| +| Pinned version is on an EOL or soon-to-EOL minor line | BUMP to latest supported minor | +| Active CVE against the pinned version | BUMP to patched point release | +| New major (e.g. 10.x) is GA with no known breaking changes for wl_manager | DEFER or start compat work | +| All criteria green | KEEP | + +### 7 risk areas to re-test on any major upgrade + +These are the Splunk platform behaviours that wl_manager depends on in +non-obvious ways. On any major-version jump (e.g. 9.x → 10.x), each area +must be verified before the pin is bumped in docker-compose.yml. + +1. **REST handler base class** — `bin/` handlers inherit from + `splunk.rest.BaseRestHandler`. Confirm the class is not renamed, moved, + or removed; run the handler-level integration tests under the new version. + +2. **mvc.Components two-instance quirk** — `appserver/` JS uses + `mvc.Components.getInstance()` with an early-return guard against a second + init. Confirm Splunk's RequireJS bootstrap still triggers the guard; the + symptom of breakage is doubled event-listener registration. + +3. **INDEXED_EXTRACTIONS + KV_MODE interaction** — `default/props.conf` sets + `INDEXED_EXTRACTIONS = json` on the wl_manager sourcetype. If a Splunk + upgrade also changed `KV_MODE` defaults for that sourcetype, fields would be + extracted twice (index-time + search-time), producing duplicated + multi-value fields. Verify with a real-data ingest run. + +4. **Scheduled-search impersonation** — wl_manager's expiration-cleanup + saved search uses `run_as = owner`. Confirm the impersonation semantics + (which user token is passed to the REST handler) did not change. + +5. **simpleRequest 404 behaviour** — Several dashboard JS modules use + `mvc.createSearchManager` and `SplunkViews.simpleRequest` and expect a + `404` from an unknown endpoint to resolve (not reject) the promise so that + fallback logic runs. Test by temporarily removing a lookup file and + confirming the dashboard degrades gracefully rather than hanging. + +6. **MAX_MULTIVAL_COUNT limit** — `default/limits.conf` raises + `MAX_MULTIVAL_COUNT` to `256` for the whitelist lookup. Confirm the limit + is still honoured and not capped lower by a new default or new + platform-level ceiling. + +7. **panel-depends reactivity** — Several dashboard panels use Splunk's + `depends` token-matching to hide/show panels. Confirm that the rendering + order of token changes and panel visibility updates still works: a changed + token must suppress the dependent panel before its search fires. + +### Test suites + +| Suite | Command | Notes | +|---|---|---| +| Unit (pure Python) | `python -m pytest tests/unit/ tests/test_wl_limits.py tests/test_wl_fim_common.py tests/test_wl_expiration_cleanup.py -q` | No Splunk container needed. `test_wl_hmac_key.py` does not exist as a standalone file; HMAC key tests live at `tests/unit/test_hmac_key.py`. | +| E2E | `WL_TEST_HARNESS=1 python -m pytest tests/e2e/ -q` | Requires a running Splunk container (`docker compose up -d`). Do not attempt in remote agent runs. | + +### Audit log + +| Date | Splunk GA at audit | Pinned version | Decision | Notes | +|---|---|---|---|---| +| 2026-07-18 | 10.4.1 | 9.3.1 | **BUMP** | 9.3.x EOS is 2026-07-24 (6 days away). CVE-2026-22796 (OpenSSL) patched in 9.3.11; 9.3.1 is 12 minor patches behind 9.3.13. CVE-2026-20253 (CVSS 9.8, pre-auth RCE) affects only 10.x — not 9.3.x. Recommend bumping docker-compose.yml to `splunk/splunk:9.4.12` immediately to exit EOL, then open compat-work tracking for 10.x migration. All 952 pure-Python tests pass on current pin. pip-audit: all 7 dev deps clean (OSV web-fallback; api.osv.dev blocked by network proxy in agent env). | diff --git a/docs/PIP_AUDIT_LOG.md b/docs/PIP_AUDIT_LOG.md index 97e35dd..63bc398 100644 --- a/docs/PIP_AUDIT_LOG.md +++ b/docs/PIP_AUDIT_LOG.md @@ -52,6 +52,37 @@ OSV queries with the helper at the bottom of this file. `tests/test_wl_expiration_cleanup.py`) were not in the CI list. Both fixed in the same commit. +### 2026-07-18 — Q3 2026 quarterly audit + +**Method:** Web-search fallback (OSV API at `api.osv.dev` blocked by network +proxy in remote agent environment; direct `POST` to the OSV API was attempted +but all connections rejected with 403). Findings cross-referenced against +GitHub Advisory Database, Snyk, and CVEdetails via web search. + +| Package | Pinned | OSV finding | Notes | +|---------|--------|-------------|-------| +| pytest | 9.0.3 | **clean** | CVE-2025-71176 (GHSA-6w46-j5rx-g56g) fixed in ≥9.0.3; our pin is the first safe version. No new advisories found for 9.0.3. | +| pytest-cov | 5.0.0 | **clean** | No advisories found. | +| freezegun | 1.5.1 | **clean** | No advisories found. | +| hypothesis | 6.90.0 | **clean** | No advisories found. | +| pytest-timeout | 2.1.0 | **clean** | No advisories found. | +| playwright | 1.60.0 | **clean** | CVE-2025-59288 (GHSA-7mvr-c777-76hp) — browser installer skipped TLS cert verification; fixed in ≥1.55.1. Our pin (1.60.0) is safe. No additional advisories found for 1.60.0. | +| radon | 6.0.1 | **clean** | No advisories found. | + +**Result:** All 7 dev deps clean. No pin changes required. + +**Test run:** 952 pure-Python tests passed under pytest 9.0.3 / Python 3.11.15 +(`tests/unit/` + `tests/test_wl_limits.py` + `tests/test_wl_fim_common.py` + +`tests/test_wl_expiration_cleanup.py`). 1 non-critical warning: invalid escape +sequence `\`` in docstring at `tests/unit/test_validation.py:155`. + +**Blocker note:** `api.osv.dev` was unreachable from the automated agent +environment (proxy policy denial). Future automated runs should either +allowlist `api.osv.dev` in the proxy config or use `pip-audit` in a local +developer environment as the primary method. Web-search fallback is +intentionally conservative (may miss advisories published since the last +search-engine crawl). + ## Fallback OSV query helper When `pip-audit` cannot resolve the requirements file (e.g., a yanked