SETUP_GUIDE.md

SentinelPrime Complete Setup Guide

Unified ZTNA + EDR + NDR Deployment

🎯 Overview

This guide will set up the complete SentinelPrime stack with all three security layers:

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

📋 Prerequisites

Hardware Requirements

• Minimum: 8GB RAM, 4 CPU cores, 50GB disk
• Recommended: 16GB RAM, 8 CPU cores, 100GB disk

Software Requirements

• Docker 20.10+ and Docker Compose 2.0+
• Network access for external repositories
• (Optional) Root/admin access to endpoints for agents

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    Docker Environment                   │
│  ┌──────────────┐  ┌──────────┐  ┌────────────────┐  │
│  │Control Plane │  │  Kafka   │  │  Neo4j/Redis   │  │
│  │   (FastAPI)  │  │(Redpanda)│  │  Elastic/Kibana│  │
│  └──────┬───────┘  └────┬─────┘  └────────────────┘  │
└─────────┼────────────────┼─────────────────────────────┘
          │                │
          │  Events via Kafka
          │                │
┌─────────▼────────────────▼─────────────────────────────┐
│               Native Agents (on hosts)                  │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐           │
│  │  Wazuh   │  │ osquery  │  │   Zeek    │  (ZTNA)  │
│  │  Agent   │  │          │  │  Sensor   │  Optional │
│  └──────────┘  └──────────┘  └───────────┘           │
└─────────────────────────────────────────────────────────┘

🚀 Quick Start (All-in-One)

Step 1: Deploy Core Infrastructure

cd SentinelPrime

# Start the complete stack
./deploy.sh

# This will start:
# - Control Plane API (port 8000)
# - Kafka/Redpanda (port 9092)
# - Neo4j (ports 7474, 7687)
# - Redis (port 6379)
# - Elasticsearch (port 9200)
# - Kibana (port 5601)
# - Prometheus (port 9090)
# - Grafana (port 3000)

Step 2: Choose Your Deployment Mode

You have 3 options:

Option A: Quick Test with Simulated Data ⚡ (5 minutes)

Best for: Testing, demos, development

# Run attack simulation
python3 experiments/lateral_movement.py

# View results immediately
curl http://localhost:8000/api/v1/telemetry/stats

Pros: Instant setup, no additional software Cons: Simulated data only, not real security monitoring

---

Option B: Partial Real Integration 🔧 (30 minutes)

Best for: Testing with real data, proof of concept

Install one or more real components on your laptop/VM:

# Install osquery on this machine
./scripts/install-osquery.sh

# Configure to send to SentinelPrime
./scripts/configure-osquery.sh --kafka localhost:9092

# Start monitoring
sudo systemctl start osqueryd

Pros: Real endpoint data, easy to set up Cons: Limited to endpoints you control

---

Option C: Full Production Setup 🏢 (2-4 hours)

Best for: Production deployment, complete testing

Deploy all components across infrastructure:

1. Wazuh agents on servers
2. osquery on workstations
3. Zeek on network tap
4. (Optional) OpenZiti/Pomerium for ZTNA

Pros: Complete real-world deployment Cons: Requires infrastructure access

---

📦 Detailed Setup: Option C (Full Deployment)

Phase 1: Core Infrastructure (Docker)

1. Clone and configure:

git clone <repo-url> SentinelPrime
cd SentinelPrime

# Create configuration
cp .env.example .env

# Edit configuration (optional)
nano .env

2. Deploy infrastructure:

# Make deployment script executable
chmod +x deploy.sh

# Deploy everything
./deploy.sh

# Wait for services to be ready (2-3 minutes)

3. Verify core services:

# Check all services are running
docker-compose ps

# Test Control Plane
curl http://localhost:8000/health

# Should return: {"status": "healthy"}

Phase 2: EDR Layer Setup

A. Wazuh Deployment

On Wazuh Manager (can be Docker or separate VM):

# Option 1: Add to existing docker-compose.yml
nano docker-compose.yml
# Add wazuh-manager service (see deployment/wazuh-docker.yml)

docker-compose up -d wazuh-manager

# Option 2: Separate VM installation
# See: edr/wazuh/INSTALLATION.md

On Each Endpoint to Monitor:

# Download and run agent installer
curl -o install-wazuh-agent.sh \
  https://raw.githubusercontent.com/wazuh/wazuh/master/extensions/elasticsearch/7.x/wazuh-app/install-wazuh-agent.sh

# Install and configure
sudo WAZUH_MANAGER='<MANAGER_IP>' \
     bash install-wazuh-agent.sh

Configure Kafka Integration:

# On Wazuh Manager
./scripts/configure-wazuh-kafka.sh \
  --kafka-host kafka:9092 \
  --topic sentinel-edr-events

B. osquery Deployment

On Each Endpoint:

# Use provided installer script
./scripts/install-osquery.sh

# Configure for SentinelPrime
./scripts/configure-osquery.sh \
  --kafka localhost:9092 \
  --topic sentinel-edr-events

# Start service
sudo systemctl start osqueryd
sudo systemctl enable osqueryd

Verify EDR Layer:

# Check events are flowing
docker-compose exec kafka kafka-console-consumer \
  --bootstrap-server localhost:9092 \
  --topic sentinel-edr-events \
  --max-messages 5

Phase 3: NDR Layer Setup

A. Zeek Deployment

On Network Tap/SPAN Port or Gateway Server:

# Install Zeek
curl -o install-zeek.sh https://zeek.org/get-zeek
sudo bash install-zeek.sh

# Deploy SentinelPrime Zeek configs
sudo cp ndr/zeek/local.zeek /usr/local/zeek/share/zeek/site/
sudo cp -r ndr/zeek/scripts /usr/local/zeek/share/zeek/site/

# Configure interface
sudo nano /usr/local/zeek/etc/node.cfg
# Set interface=eth0 (or your monitoring interface)

# Configure Kafka output
./scripts/configure-zeek-kafka.sh \
  --kafka-host kafka:9092 \
  --topic sentinel-ndr-events

# Start Zeek
sudo zeekctl deploy

B. Suricata Deployment

On Same Network Monitoring Point:

# Install Suricata
sudo apt-get install suricata

# Deploy SentinelPrime rules
sudo cp ndr/suricata/custom-sentinel.rules \
  /etc/suricata/rules/

# Configure
sudo cp ndr/suricata/suricata.yaml \
  /etc/suricata/suricata.yaml

# Start Suricata
sudo systemctl start suricata
sudo systemctl enable suricata

Verify NDR Layer:

# Check Zeek is running
sudo zeekctl status

# Check Suricata is running
sudo systemctl status suricata

# Verify events
docker-compose exec kafka kafka-console-consumer \
  --bootstrap-server localhost:9092 \
  --topic sentinel-ndr-events \
  --max-messages 5

Phase 4: ZTNA Layer (Optional)

Option A: OpenZiti

# Install OpenZiti controller
curl -sSLf https://get.openziti.io/quick/ziti-controller-quickstart.sh | bash

# Configure SentinelPrime integration
./scripts/configure-openziti.sh \
  --controller https://localhost:1280 \
  --username admin \
  --password <password>

Option B: Pomerium

# Deploy Pomerium
docker-compose -f deployment/pomerium-docker.yml up -d

# Configure routes
cp ztna/pomerium/config.yaml /etc/pomerium/config.yaml

# Restart
docker-compose restart pomerium

Verify ZTNA Layer:

# Test authentication event
curl -X POST http://localhost:8000/api/v1/telemetry/ztna \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "auth_success",
    "user_id": "test@company.com",
    "resource": "app.internal.com"
  }'

🧪 Testing the Complete Setup

1. Generate Test Events

# Run comprehensive test
./scripts/test-all-layers.sh

# Or test individually
./edr/test-edr.sh       # Test EDR
./ndr/test-ndr.sh       # Test NDR  
./ztna/test-ztna.sh     # Test ZTNA

2. Run Attack Simulation

# Simulate lateral movement
python3 experiments/lateral_movement.py

# Check detection
curl http://localhost:8000/api/v1/decisions/assess \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "192.168.1.100",
    "entity_type": "host"
  }'

3. Verify Correlation

# Check if events are being correlated
curl http://localhost:8000/api/v1/telemetry/stats

# Should show events from all sources:
{
  "events_by_source": {
    "edr": 150,
    "ndr": 89,
    "ztna": 45
  }
}

4. View in Dashboards

• Kibana: http://localhost:5601 - View all events
• Grafana: http://localhost:3000 - Metrics and alerts
• Neo4j: http://localhost:7474 - Attack graph visualization
• API Docs: http://localhost:8000/docs - Interactive API

📊 Monitoring & Validation

Check System Health

# All services status
docker-compose ps

# Control Plane health
curl http://localhost:8000/health

# Check logs
docker-compose logs -f control-plane

Monitor Event Flow

# Real-time event monitoring
docker-compose exec kafka kafka-console-consumer \
  --bootstrap-server localhost:9092 \
  --topic sentinel-edr-events

# Control Plane event stats
watch -n 5 'curl -s http://localhost:8000/api/v1/telemetry/stats'

View Enforcement Actions

# Get recent decisions
curl http://localhost:8000/api/v1/decisions?limit=10

# View enforcement history
docker-compose exec control-plane cat /var/log/enforcement.log

🔧 Troubleshooting

Services Won't Start

# Check Docker resources
docker system df

# Check logs
docker-compose logs <service-name>

# Restart specific service
docker-compose restart <service-name>

No Events Appearing

# Check Kafka topics exist
docker-compose exec kafka kafka-topics --list \
  --bootstrap-server localhost:9092

# Create missing topics
docker-compose exec kafka kafka-topics --create \
  --bootstrap-server localhost:9092 \
  --topic sentinel-edr-events \
  --partitions 3 \
  --replication-factor 1

Agents Not Connecting

# Check network connectivity
ping <control-plane-host>
telnet <control-plane-host> 9092

# Check firewall rules
sudo ufw status

# Check agent logs
# Wazuh: tail -f /var/ossec/logs/ossec.log
# osquery: journalctl -u osqueryd -f
# Zeek: tail -f /usr/local/zeek/logs/current/reporter.log

📝 Configuration Files

All configuration files are in:

SentinelPrime/
├── .env                    # Main configuration
├── docker-compose.yml      # Infrastructure
├── edr/
│   ├── wazuh/config.yaml
│   └── osquery/osquery.conf
├── ndr/
│   ├── zeek/local.zeek
│   └── suricata/suricata.yaml
└── ztna/
    ├── openziti/
    └── pomerium/

🎓 Deployment Scenarios

Scenario 1: Local Testing (Laptop)

# Core + Simulations
./deploy.sh
python3 experiments/lateral_movement.py

Scenario 2: Small Office

# Core in Docker on one server
# osquery on all workstations
# Zeek on gateway/router
# Wazuh on critical servers

Scenario 3: Enterprise

# Core in Kubernetes cluster
# Wazuh with clustered managers
# Zeek on multiple network taps
# Full ZTNA deployment

📚 Next Steps

1. ✅ Infrastructure deployed → Test with simulations
2. ✅ Agents installed → Monitor real activity
3. ✅ Events flowing → Tune correlation rules
4. ✅ Tested detection → Configure enforcement
5. ✅ Enforcement working → Enable auto-response

🔐 Security Considerations

Before production:

• Change all default passwords
• Enable TLS/SSL on all services
• Configure firewall rules
• Set up backup procedures
• Enable audit logging
• Configure alerting
• Test disaster recovery

📞 Getting Help

• Documentation: See docs/ directory
• Installation Issues: Check TROUBLESHOOTING.md
• API Reference: http://localhost:8000/docs
• Examples: See experiments/ directory

---

🎯 Recommended Setup Path

For most users, we recommend this order:

1. Week 1: Deploy core infrastructure + simulations
2. Week 2: Add osquery to your own machines
3. Week 3: Deploy Wazuh on test servers
4. Week 4: Add Zeek on network monitoring point
5. Week 5: Tune detection and correlation
6. Week 6: Enable automated enforcement

This gradual approach lets you learn each component before adding complexity!