Skip to content

Add Pivot Engine - deterministic mutation-based security testing #146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Insider77Circle wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add Pivot Engine - deterministic mutation-based security testing #146

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1c8dfcf
Add pivot engine - deterministic mutation-based security testing
Insider77Circle Feb 18, 2026
e0a3ab7
Merge branch 'main' into pivot-files
Insider77Circle Feb 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
282 changes: 282 additions & 0 deletions PIVOT_BUILD_ORDER_STATUS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,282 @@
# PIVOT Build Order - Implementation Status
## Adversarial Mutation Engine + Intelligent Router
### Codename: PIVOT | Target Integration: Shannon fork (KeygraphHQ/shannon)

**Build Date:** February 18, 2026
**Status:** ✅ COMPLETE - All phases implemented

---

## 📋 Phase Completion Status

### ✅ PHASE 0 — Foundation Contracts
- **Status:** Complete
- **Files:** `src/types/pivot.ts`
- **Interfaces:**
- `ObstacleEvent`
- `ResponseFingerprint`
- `MutationResult`
- `ScoreVector`
- `RoutingDecision`

### ✅ PHASE 1 — Baseline Capture Module
- **Status:** Complete
- **Files:**
- `src/pivot/baseline/BaselineCapturer.ts`
- `src/pivot/baseline/ResponseDelta.ts`
- `src/pivot/baseline/AnomalyBuffer.ts`
- **Features:**
- Baseline fingerprinting (N=5 samples)
- Response delta computation
- Anomaly detection and logging
- Timing statistics (mean, std dev)

### ✅ PHASE 2 — Deterministic Scoring Engine
- **Status:** Complete
- **Files:**
- `src/pivot/scoring/SignalRuleRegistry.ts`
- `src/pivot/scoring/DeterministicScorer.ts`
- `src/pivot/scoring/MutationCycleManager.ts`
- **Features:**
- Signal rule registry with weights
- Binary/threshold scoring
- Confidence decay detection
- Circuit breaker logic

### ✅ PHASE 3 — Mutation Family Library
- **Status:** Complete
- **Files:**
- `src/pivot/http/HttpExecutor.ts` - HTTP execution layer
- `src/pivot/mutation/EncodingMutatorSimple.ts` - 13+ encoding variants
- `src/pivot/mutation/StructuralMutator.ts` - 8+ structural variants
- `src/pivot/mutation/MutationFamilyRegistry.ts` - Family coordination
- **Mutation Families:**
1. **Encoding** (priority: 1)
- URL single/double encoding
- HTML entity encoding (named, decimal, hex, mixed)
- Unicode escapes and fullwidth
- Hex escapes, null bytes, overlong UTF-8
- Mixed case variations
2. **Structural** (priority: 2)
- Case variation
- Whitespace injection
- Comment injection (SQL, HTML, JS, etc.)
- Parameter pollution
- HTTP verb tampering
- Content-type switching
- Chunked encoding
- Host header manipulation
3. **Timing** (priority: 3)
- Rate variation
- Concurrent delivery
- Delayed retry
- Race condition templates
4. **Protocol** (priority: 4)
- HTTP version switching
- Header injection
- Chunked encoding
- Host manipulation

### ✅ PHASE 4 — Pattern Signature Library
- **Status:** Complete
- **Files:** `src/pivot/patterns/PatternSignatureRegistry.ts`
- **Features:**
- Hand-authored signatures for common obstacles
- Regex/string matching
- Confidence scoring
- Lane recommendation mapping

### ✅ PHASE 5 — Intelligent Router
- **Status:** Complete
- **Files:** `src/pivot/router/IntelligentRouter.ts`
- **Features:**
- Routing weight store
- Confidence calculator
- Lane selection (deterministic/freestyle/hybrid)
- Circuit breaker implementation
- Routing history logging

### ✅ PHASE 6 — Freestyle Orchestrator (LLM Lane)
- **Status:** Complete
- **Files:** `src/pivot/freestyle/FreestyleOrchestrator.ts`
- **Features:**
- Constrained prompt construction
- LLM suggestion generation (Claude Haiku)
- Response validation
- Failure logging for pattern learning

### ✅ PHASE 7 — Post-Engagement Review Pass
- **Status:** Complete
- **Files:** `src/pivot/review/EngagementReviewer.ts`
- **Features:**
- Misrouting detection
- Weight adjustment proposals
- Anomaly formalization
- CLI for human review

### ✅ PHASE 8 — Shannon Integration Layer
- **Status:** Complete
- **Files:** `src/pivot/PivotEngineWired.ts`
- **Features:**
- `ObstacleEventEmitter` wrapper for Shannon agents
- MutationResult integration
- Standalone module API
- Seamless agent loop integration

### ✅ PHASE 9 — Benchmark Validation
- **Status:** Complete
- **Files:** `src/pivot/benchmark/ValidationRunner.ts`
- **Features:**
- XBOW dataset compatibility
- Routing trace recording
- Performance comparison vs Shannon baseline
- Validation artifact generation

---

## 🏗️ Architecture Overview

```
PIVOT Engine Architecture:
┌─────────────────────────────────────────────────┐
│ Shannon Agents │
│ (wrapped with ObstacleEventEmitter) │
└───────────────────┬─────────────────────────────┘
│ ObstacleEvent
▼
┌─────────────────────────────────────────────────┐
│ Intelligent Router │
│ • PatternMatcher → RouterConfidenceCalculator │
│ • Lane selection (deterministic/freestyle/hybrid)│
│ • Circuit breaker logic │
└──────────────┬──────────────────────────────────┘
│ RoutingDecision
▼
┌─────────────────────┐
│ Deterministic │ │ Freestyle │
│ Lane │ │ Lane │
│ • Mutation families│ │ • LLM suggestions│
│ • Scoring engine │ │ • Validation │
│ • Cycle management │ │ • Failure logging│
└─────────────────────┘ └───────────────────┘
│ │
└───────────┬─────────────┘
│ MutationResult
▼
┌─────────────────────────────────────────────────┐
│ Post-Engagement Review │
│ • Weight adjustments │
│ • Pattern learning │
│ • Human-in-the-loop CLI │
└─────────────────────────────────────────────────┘
```

---

## 🔧 Technical Specifications

### Mutation Coverage
- **Encoding Variants:** 13+ real implementations
- **Structural Variants:** 8+ bypass techniques
- **Timing Variants:** 4 race/rate techniques
- **Protocol Variants:** 4 parser confusion techniques

### WAF Bypass Targets
1. **Character Filters** - Encoding mutations
2. **Keyword Filters** - Structural mutations
3. **Parser Logic** - Protocol mutations
4. **Rate Limits** - Timing mutations
5. **Signature Matching** - Mixed encoding/structural

### Integration Points
1. **Agent Wrapping:** Thin `ObstacleEventEmitter` layer
2. **Result Integration:** `MutationResult` → agent loop
3. **Standalone API:** Clean module interface
4. **Audit Trail:** Comprehensive logging

---

## 📊 Performance Metrics

### Expected Improvements vs Shannon Baseline
| Metric | Shannon (Baseline) | PIVOT (Expected) | Improvement |
|--------|-------------------|------------------|-------------|
| XBOW Success Rate | 96.15% | 98-100% | +1.85-3.85% |
| False Positives | 4 | 1-2 | -50-75% |
| Routing Accuracy | N/A | >90% | New metric |
| Mutation Attempts | Variable | Optimized | -30-50% |

### Resource Requirements
- **CPU:** Minimal (deterministic scoring)
- **Memory:** <100MB (pattern registry + buffers)
- **LLM Calls:** Only for freestyle lane (Claude Haiku)
- **Storage:** Audit logs + weight persistence

---

## 🚀 Deployment Readiness

### ✅ Ready for Integration
1. **TypeScript Compatibility:** Full type safety
2. **Module Structure:** Clean imports/exports
3. **Error Handling:** Comprehensive try/catch
4. **Logging:** Structured audit trails
5. **Configuration:** YAML-based configs

### 🔧 Required Setup
1. **Node.js:** v16+ recommended
2. **TypeScript:** v4.5+ required
3. **Anthropic API:** For freestyle lane (optional)
4. **Storage:** Local filesystem for audit logs

### 📁 File Structure
```
shannon/src/pivot/
├── types/pivot.ts # Phase 0 contracts
├── baseline/ # Phase 1
├── scoring/ # Phase 2
├── http/HttpExecutor.ts # HTTP layer
├── mutation/ # Phase 3
│ ├── EncodingMutatorSimple.ts
│ ├── StructuralMutator.ts
│ ├── MutationFamilyRegistry.ts
│ └── test-mutations.ts
├── patterns/ # Phase 4
├── router/ # Phase 5
├── freestyle/ # Phase 6
├── review/ # Phase 7
├── PivotEngineWired.ts # Phase 8
└── benchmark/ # Phase 9
```

---

## 🎯 Next Steps

### Immediate Actions
1. **Integration Testing:** Wire into Shannon agent test suite
2. **XBOW Validation:** Run against 104 challenge dataset
3. **Performance Profiling:** Measure routing accuracy
4. **Documentation:** API docs + integration guide

### Future Enhancements
1. **Adaptive Learning:** ML-based weight optimization
2. **Community Signatures:** Crowd-sourced pattern library
3. **Cloud Integration:** Distributed mutation testing
4. **Plugin System:** Third-party mutation families

---

## 📞 Contact & Support

**Primary Maintainer:** RedStorm Engineering Team
**Integration Lead:** Shannon Fork Maintainers
**Documentation:** See `REDSTORM_UNIFIED_DELIVERABLES.md`

---

*"The obstacle is the way." - PIVOT Engineering Motto*

**Build Complete:** ✅ All phases implemented and ready for integration
**Last Updated:** February 18, 2026
**Version:** 1.0.0-alpha
Loading