Skip to content

PROJECT_OVERVIEW.md

Latest commit

 

History

History
311 lines (249 loc) · 8.84 KB

PROJECT_OVERVIEW.md

File metadata and controls

311 lines (249 loc) · 8.84 KB

SentinelPrime - Project Overview

🎯 What We Built

A complete, production-ready proof-of-concept for an AI-driven Security Control Plane that unifies:

  • ZTNA (Zero Trust Network Access)
  • EDR (Endpoint Detection & Response)
  • NDR (Network Detection & Response)

Into a single, intelligent enforcement system.

📁 Project Structure

SentinelPrime/
├── control-plane/          # Core AI control plane (FastAPI)
│   ├── main.py            # API entry point
│   ├── config.py          # Configuration management
│   ├── requirements.txt   # Python dependencies
│   ├── Dockerfile         # Container build
│   ├── api/               # REST API endpoints
│   │   └── routes/        # Telemetry, decisions, policies
│   ├── core/              # Core business logic
│   │   ├── correlation_engine.py  # Event correlation
│   │   └── risk_scorer.py         # Risk assessment
│   ├── ml/                # Machine learning models
│   │   ├── anomaly_detection.py   # Isolation Forest
│   │   └── graph_analyzer.py      # Neo4j attack graphs
│   └── ingestion/         # Event ingestion
│       └── kafka_consumer.py      # Kafka consumer
│
├── ztna/                   # Zero Trust integrations
│   ├── openziti/          # OpenZiti adapter
│   │   ├── adapter.py
│   │   └── policy-templates.yaml
│   └── pomerium/          # Pomerium adapter
│       └── adapter.py
│
├── edr/                    # Endpoint Detection integrations
│   ├── wazuh/             # Wazuh configuration
│   │   ├── config.yaml
│   │   └── adapter.py
│   └── osquery/           # osquery queries
│       └── queries.sql
│
├── ndr/                    # Network Detection integrations
│   ├── zeek/              # Zeek configuration
│   │   ├── local.zeek
│   │   ├── adapter.py
│   │   └── scripts/
│   └── suricata/          # Suricata rules
│       ├── suricata.yaml
│       └── custom-sentinel.rules
│
├── orchestration/          # Enforcement orchestration
│   ├── enforcement_engine.py     # Action coordinator
│   └── README.md
│
├── experiments/            # Attack scenarios
│   ├── lateral_movement.py       # Simulation script
│   └── README.md
│
├── docs/                   # Documentation
│   ├── ARCHITECTURE.md    # System design
│   └── INSTALLATION.md    # Setup guide
│
├── docker-compose.yml      # Full stack deployment
├── deploy.sh              # Automated deployment
├── .env.example           # Configuration template
├── readme.md              # Project overview
├── CONTRIBUTING.md        # Contribution guide
├── LICENSE                # MIT License
└── .gitignore            # Git ignore rules

🚀 Quick Start

# 1. Deploy the stack
chmod +x deploy.sh
./deploy.sh

# 2. Access services
# Control Plane: http://localhost:8000
# API Docs: http://localhost:8000/docs
# Grafana: http://localhost:3000
# Neo4j: http://localhost:7474

# 3. Run attack simulation
python experiments/lateral_movement.py

🧠 Key Features

1. Intelligent Event Correlation

  • Cross-layer event analysis (EDR + NDR + ZTNA)
  • Temporal correlation within time windows
  • Attack chain reconstruction using graph database

2. ML-Powered Anomaly Detection

  • Isolation Forest for outlier detection
  • Behavior profiling per entity
  • Real-time risk scoring

3. Graph-Based Attack Analysis

  • Neo4j for relationship mapping
  • Multi-hop attack chain detection
  • Lateral movement identification
  • Risk score propagation

4. Automated Enforcement

  • Coordinated response across all layers
  • Graduated enforcement based on confidence
  • Dry-run mode for safety
  • Audit logging of all actions

5. Vendor-Agnostic Design

  • Pluggable EDR systems (Wazuh, osquery, etc.)
  • Pluggable NDR systems (Zeek, Suricata, etc.)
  • Pluggable ZTNA systems (OpenZiti, Pomerium, etc.)

🏗️ Architecture Highlights

Control Plane

  • FastAPI for high-performance REST API
  • Kafka/Redpanda for event streaming
  • Neo4j for graph-based analysis
  • Redis for caching and state
  • Prometheus + Grafana for monitoring

ML Engine

  • Scikit-learn Isolation Forest
  • Custom behavior analysis
  • Graph correlation algorithms

Orchestration

  • Async enforcement across layers
  • Playbook-based responses
  • Manual override capability

📊 What Makes This Different

Traditional XDR systems focus on detection and alerting.

SentinelPrime focuses on decision-making and enforcement.

Traditional XDR SentinelPrime
Alert sprawl Automated decisions
Separate tools Unified control plane
Detection-focused Intent-aware
Manual response Closed-loop enforcement
Vendor lock-in Vendor-agnostic

🧪 Research Questions Addressed

  1. Can AI determine attacker intent from telemetry?

    • Graph-based correlation reconstructs attack chains
    • ML identifies deviations from baseline behavior

  2. What is optimal detection-to-enforcement latency?

    • Real-time event processing via Kafka
    • Async orchestration minimizes delay

  3. How much can blast radius be reduced?

    • Automated isolation at first detection
    • Coordinated blocking across all layers

  4. What false positive rate is acceptable?

    • Confidence scoring guides enforcement
    • Dry-run mode for validation

🔐 Security Considerations

  • Fail-safe defaults: Dry-run enabled by default
  • Audit trail: All actions logged
  • Manual override: Human operators can intervene
  • Graduated response: Actions escalate with confidence
  • Role-based access: Control plane API authentication

📈 Metrics Tracked

  • Detection → Enforcement latency
  • Blast radius before containment
  • Alert count vs. real incidents
  • False positive/negative rates
  • Action success/failure rates

🛠️ Technology Stack

Backend:

  • Python 3.11+
  • FastAPI
  • Kafka/Redpanda
  • Neo4j
  • Redis

ML:

  • Scikit-learn
  • NumPy
  • Pandas

Infrastructure:

  • Docker & Docker Compose
  • Prometheus & Grafana
  • Elasticsearch & Kibana

Security Tools:

  • Wazuh (EDR)
  • osquery (EDR)
  • Zeek (NDR)
  • Suricata (NDR)
  • OpenZiti (ZTNA)
  • Pomerium (ZTNA)

🎓 Use Cases

1. Lateral Movement Detection

EDR detects suspicious process → NDR sees SMB connections → ZTNA access revoked → Host isolated

2. Data Exfiltration Prevention

EDR sees sensitive file access → NDR detects large upload → Network blocked → User session terminated

3. Compromised Identity Response

ZTNA sees failed auth + success → Risk score elevated → MFA required → All sessions reviewed

📚 Documentation

🔬 Research Status

Phase 1: Reference Implementation ✅ COMPLETE

  • ✅ Core control plane
  • ✅ Telemetry ingestion pipeline
  • ✅ ML-based correlation
  • ✅ Graph analysis
  • ✅ Enforcement orchestration
  • ✅ ZTNA/EDR/NDR adapters
  • ✅ Attack simulations
  • ✅ Docker deployment

Phase 2: Evaluation (Next)

  • Measure detection accuracy
  • Benchmark latency
  • Test enforcement effectiveness
  • Gather false positive rates

Phase 3: Optimization (Future)

  • Model tuning
  • Performance optimization
  • Scalability testing
  • Real-world validation

🌟 What You Can Do Now

  1. Deploy and Test:

    ./deploy.sh
python experiments/lateral_movement.py

  2. Integrate Real Systems:

    • Connect actual Wazuh deployment
    • Deploy Zeek on network tap
    • Configure OpenZiti/Pomerium

  3. Customize Detection:

    • Add correlation rules
    • Tune ML thresholds
    • Create custom playbooks

  4. Extend Capabilities:

    • Add new adapters
    • Implement custom ML models
    • Create new attack scenarios

  5. Measure Effectiveness:

    • Run attack simulations
    • Track metrics in Grafana
    • Analyze enforcement logs

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Areas of interest:

  • New detection algorithms
  • Additional EDR/NDR/ZTNA integrations
  • Attack scenario development
  • Performance optimization
  • Documentation improvements

📄 License

MIT License - See LICENSE for details.

🙏 Acknowledgments

Built on the shoulders of giants:

  • MITRE ATT&CK Framework
  • NIST Zero Trust Architecture
  • Open source security tools
  • Research community

SentinelPrime - Where security decisions matter more than dashboards.