Feature/jitter tool

go.mod

@@ -22,6 +22,7 @@ require (
 	github.com/stretchr/testify v1.10.0
 	github.com/yuin/gopher-lua v1.1.1
 	golang.org/x/oauth2 v0.26.0
+	gonum.org/v1/gonum v0.14.0
 	gopkg.in/urfave/cli.v1 v1.20.0
 	gopkg.in/yaml.v2 v2.4.0
 	layeh.com/gopher-luar v1.0.11

go.sum

@@ -109,6 +109,8 @@ github.com/yuin/gopher-lua v1.1.1/go.mod h1:GBR0iDaNXjAgGg9zfCvksxSRnQx76gclCIb7
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
 golang.org/x/crypto v0.14.0/go.mod h1:MVFd36DqK4CsrnJYDkBA3VC4m2GkXAM0PvzMCn4JQf4=
+golang.org/x/exp v0.0.0-20230321023759-10a507213a29 h1:ooxPy7fPvB4kwsA2h+iBNHkAbp/4JxTSwCmvdjEYmug=
+golang.org/x/exp v0.0.0-20230321023759-10a507213a29/go.mod h1:CxIveKay+FTh1D0yPZemJVgC/95VzuuOLq5Qi4xnoYc=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
 golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
@@ -161,6 +163,8 @@ golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+gonum.org/v1/gonum v0.14.0 h1:2NiG67LD1tEH0D7kM+ps2V+fXmsAnpUeec7n8tcr4S0=
+gonum.org/v1/gonum v0.14.0/go.mod h1:AoWeoz0becf9QMWtE8iWXNXc27fK4fNeHNf/oMejGfU=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=

jitter/README.md

@@ -0,0 +1,131 @@
+# Jitter Analysis Package
+
+This package provides statistical analysis of inter-arrival time jitter for event timing validation. It's designed to detect whether event timing has appropriate randomness characteristics or if it exhibits unwanted patterns like periodicity or insufficient variance.
+
+## Usage
+
+### CLI Command
+
+```bash
+# Analyze intervals from stdin
+cat intervals.txt | gogen jitter
+
+# With custom thresholds
+cat intervals.txt | gogen jitter --cv-threshold 0.6 --burst-threshold -0.4
+
+# JSON output
+cat intervals.txt | gogen jitter --json
+
+# Quiet mode (only pass/fail)
+cat intervals.txt | gogen jitter --quiet
+```
+
+### As a Library
+
+```go
+import "github.com/coccyx/gogen/jitter"
+
+intervals := []float64{1.5, 2.1, 0.8, 1.2, 3.4, 1.9, 2.5, 1.1, 0.9, 2.8}
+
+opts := jitter.Options{
+    CVThreshold:    0.5,
+    BurstThreshold: -0.5,
+    SCRThreshold:   0.3,
+}
+
+result, err := jitter.AnalyzeIntervals(intervals, opts)
+if err != nil {
+    // Handle error
+}
+
+if result.OverallPass {
+    // Intervals have good variance characteristics
+}
+```
+
+## Metrics
+
+The analysis computes several statistical measures:
+
+### Coefficient of Variation (CV)
+- **Formula**: σ/μ (standard deviation / mean)
+- **Interpretation**: Measures relative variability
+- **Target**: > 0.5 (for exponential-like distribution, CV ≈ 1.0)
+
+### Burstiness
+- **Formula**: (σ - μ) / (σ + μ)
+- **Interpretation**: Characterizes temporal pattern
+  - B > 0: Bursty (events clustered)
+  - B ≈ 0: Random (exponential-like)
+  - B < 0: Regular (periodic-like)
+- **Target**: > -0.5 (avoid overly regular patterns)
+
+### Kolmogorov-Smirnov (KS) Test
+- **Purpose**: Tests if intervals follow exponential distribution
+- **Interpretation**: Informational only (reported but not pass/fail)
+
+### Spectral Concentration Ratio (SCR)
+- **Method**: FFT-based periodicity detection
+- **Formula**: peak_power / total_power
+- **Interpretation**:
+  - High SCR: Energy concentrated at one frequency (periodic)
+  - Low SCR: Energy spread across frequencies (random)
+- **Target**: < 0.3 (avoid strong periodicity)
+
+## Input Format
+
+The tool reads inter-arrival times (in seconds) from stdin, one value per line:
+
+```
+1.5
+2.1
+0.8
+1.2
+...
+```
+
+Minimum 5 intervals required; 16+ recommended for FFT analysis.
+
+## Exit Codes
+
+- 0: All tests passed
+- 1: One or more tests failed
+- 2: Insufficient data or parsing error
+
+## Flags
+
+- `--cv-threshold`: Minimum CV threshold (default: 0.5)
+- `--burst-threshold`: Minimum burstiness threshold (default: -0.5)
+- `--scr-threshold`: Maximum SCR threshold (default: 0.3)
+- `--json`: Output results as JSON
+- `--quiet`, `-q`: Only output PASS/FAIL
+
+## Example Output
+
+```
+==========================================
+Jitter Analysis
+==========================================
+
+Samples analyzed:      100
+Mean interval:         0.9775 s
+Std deviation:         0.9642 s
+Lambda (MLE):          1.0230 events/s
+
+CV (target > 0.5):     0.9864 ✓
+Burstiness (target > -0.5): -0.0069 ✓
+
+KS Statistic (D):      0.089234 (informational)
+KS Critical (95%):     0.136000 ✓
+
+Periodicity Analysis (FFT):
+  SCR (target < 0.3):  0.0123 ✓
+  Peak frequency:      0.0204 Hz
+  Dominant period:     49.0123 s
+
+RESULT: PASS - Event timing has good variance characteristics
+```
+
+## Background
+
+This tool is useful for validating that generated events have realistic timing patterns, especially for security testing scenarios where detection systems might flag perfectly periodic or deterministic event timing as suspicious.