🛡️ OBSIDIAN Sentinel WAF v2.2.4 Enterprise Edition

Enterprise-Grade Web Application Firewall with Advanced Security Features
Built on Coraza v3 Engine | Real-Time Protection | Zero-Trust Architecture | GeoIP Blocking | Advanced Analytics

Features • Quick Start • Architecture • API • Deployment • Security

📋 Overview

Obsidian Sentinel is an enterprise-ready Web Application Firewall that provides comprehensive protection against advanced cyber threats. It combines the battle-tested Coraza WAF engine with cutting-edge enterprise features including GeoIP blocking, advanced rate limiting, threat intelligence, webhook alerting, and sophisticated analytics.

Why Obsidian?

• 🔒 Zero-Trust Security: HMAC-SHA256 JWT authentication, RBAC, CSRF protection, and cryptographic token validation
• ⚡ High Performance: Concurrent-safe design with minimal allocation on hot paths (256-shard rate limiter)
• 📊 Real-Time Monitoring: WebSocket-based live dashboard with Chart.js visualizations and instant threat visibility
• 🌐 Advanced Threat Intelligence: Integrates with Spamhaus, Emerging Threats, Firehol, and custom feeds (2000+ threats)
• 🗺️ GeoIP Protection: Country-based blocking with MaxMind database support and risk assessment
• 🚨 Smart Alerting: Webhook integrations for Slack, Teams, Discord, PagerDuty with severity filtering
• 📈 Enterprise Analytics: PostgreSQL integration, comprehensive audit logging, and executive reporting
• 📱 Modern UI: Responsive Bootstrap 5 dark theme dashboard with mobile support
• 📦 Single Binary: All assets embedded - Redis/PostgreSQL optional for enterprise features

✨ Features

Core Security Features

Enterprise Features

Attack Categories Protected

• Cross-Site Scripting (XSS)
• SQL Injection (SQLi)
• Remote Code Execution (RCE)
• Local File Inclusion (LFI)
• Remote File Inclusion (RFI)
• Server-Side Request Forgery (SSRF)
• XML External Entity (XXE)
• Template Injection (SSTI)
• LDAP Injection
• Session Fixation
• Java/Deserialization Attacks

🚀 Quick Start

Prerequisites

• Go 1.23+ (or TinyGo for WASM builds)
• Windows, Linux, or macOS
• Optional for Enterprise Features:
  • PostgreSQL 12+ (for advanced analytics and audit logging)
  • Redis 6+ (for distributed rate limiting and clustering)
  • MaxMind GeoIP2 database (for country-based blocking)

Build and Run

# Clone the repository
git clone https://github.com/Abhishek-yadav04/Obsidian.git
cd obsidian

# Install dependencies
go mod tidy

# Option 1: Run directly with Go (recommended for development)
go run ./cmd/obsidian

# Option 2: Build and run executable
cd cmd/obsidian
go build -o obsidian.exe .
./obsidian.exe

# Run with custom port
go run ./cmd/obsidian -port 8082

# Run in development mode with debug logging
go run ./cmd/obsidian -port 8082 -dev

# Run with PostgreSQL and Redis (Enterprise mode)
export DATABASE_URL="postgres://user:pass@localhost/obsidian"
export REDIS_URL="redis://localhost:6379"
export OBSIDIAN_JWT_SECRET="your-very-secure-jwt-secret-here-at-least-32-chars"
go run ./cmd/obsidian -port 8082

Access the Dashboard

Open your browser and navigate to: http://localhost:8082

Default Credentials (CHANGE IMMEDIATELY IN PRODUCTION):

Role Permissions:

• Admin: Full access (rules, threats, users, audit logs, settings)
• Analyst: Read-only security data + report export
• Viewer: Read-only dashboard and logs

🔐 SECURITY NOTICE:

• Default passwords are documented and MUST be changed before production
• Set OBSIDIAN_JWT_SECRET environment variable (min 32 characters)
• Do NOT commit .env files to version control

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Client Request                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Security Headers Middleware                    │
│         (CSP, X-Frame-Options, X-Content-Type-Options)          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Rate Limiter Middleware                      │
│              (Sliding Window, Per-IP Tracking)                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Threat Intelligence Check                     │
│         (Spamhaus DROP, Emerging Threats, Custom Lists)         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Coraza WAF Engine                           │
│                  (55+ ModSecurity Rules)                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Application Router                           │
│               (API Handlers, Static Files)                       │
└─────────────────────────────────────────────────────────────────┘

Project Structure

obsidian/
├── cmd/obsidian/               # Main application entry point
│   ├── main.go                 # Server initialization and routing
│   └── ui/                     # Embedded frontend assets
│       ├── index.html          # Main dashboard (dark theme)
│       ├── login.html          # Authentication page
│       ├── js/app.js           # Frontend application logic
│       ├── css/styles.css      # Enterprise dark theme styling
│       └── assets/             # Static assets (logo, icons)
├── internal/app/               # Core application packages
│   ├── alerts/                 # Webhook alert management
│   ├── auth/                   # JWT authentication & RBAC
│   ├── geoip/                  # Geographic IP blocking service
│   ├── logging/                # Structured logging (Zap)
│   ├── metrics/                # Prometheus-compatible metrics
│   ├── ratelimit/              # 256-shard rate limiter
│   ├── report/                 # PDF/Excel report generation
│   ├── security/               # Security middleware & headers
│   ├── store/                  # Data persistence (PostgreSQL/memory)
│   ├── threatintel/            # Threat intelligence feeds
│   └── tracing/                # Request ID tracing
├── migrations/                 # Database migration scripts
│   ├── 000001_initial_schema.up.sql
│   └── 000001_initial_schema.down.sql
├── configs/                    # Configuration files
│   └── config.yaml             # Default configuration
└── testing/                    # Test suites and benchmarks
    ├── e2e/                    # End-to-end integration tests
    ├── performance/            # Load testing scenarios
    └── testdata/               # Test fixtures and data

🔧 Configuration

Environment Variables

OWASP CRS (External Ruleset)

Obsidian loads OWASP CRS as an external ruleset at runtime. CRS files are not vendored in this repository. To enable CRS, place the official CRS files on disk and point OBSIDIAN_CRS_PATH to the CRS root that contains crs-setup.conf and the rules/ directory.

Command Line Flags

./obsidian.exe [options]

Options:
  -port int        Port to run the server on (default 8082)
  -dev             Run in development mode (relaxed security)
  -log-level       Override LOG_LEVEL env var
  -log-format      Override LOG_FORMAT env var

Sample .env File

# ⚠️ NEVER COMMIT THIS FILE TO VERSION CONTROL
# Copy to .env and customize for your environment

# JWT Authentication (REQUIRED in production - min 32 chars)
OBSIDIAN_JWT_SECRET=your-super-secure-random-secret-minimum-32-chars

# Environment
OBSIDIAN_ENV=production

# PostgreSQL Database (REQUIRED)
DATABASE_URL=postgresql://obsidian:secure_password@localhost:5432/obsidian?sslmode=require

# Redis Cache (OPTIONAL - enables distributed rate limiting)
REDIS_URL=redis://localhost:6379/0
# For TLS: REDIS_URL=rediss://user:pass@host:port/0

# OAuth via Supabase (OPTIONAL - enables Google/GitHub login)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-anon-public-key

# WebSocket Origins (customize for your domain)
OBSIDIAN_ALLOWED_ORIGINS=https://your-domain.com

# GeoIP Database (OPTIONAL)
GEOIP_DATABASE_PATH=/opt/maxmind/GeoLite2-Country.mmdb

# Logging
LOG_LEVEL=info
LOG_FORMAT=json

# OWASP CRS (external ruleset)
OBSIDIAN_CRS_ENABLED=false
OBSIDIAN_CRS_PATH=/opt/owasp-crs
OBSIDIAN_CRS_MODE=DetectionOnly
OBSIDIAN_CRS_FAIL_OPEN=false
OBSIDIAN_WAF_CUSTOM_RULES=rules/obsidian-custom.conf

Production Deployment Checklist

• Set OBSIDIAN_JWT_SECRET (32+ random characters)
• Set OBSIDIAN_ENV=production
• Configure PostgreSQL with SSL (sslmode=require)
• Change all default user passwords immediately
• Configure proper OBSIDIAN_ALLOWED_ORIGINS
• Set up Redis for distributed rate limiting
• Enable GeoIP blocking if needed
• Configure reverse proxy (nginx/Caddy) with TLS
• Set up log aggregation
• Configure alerting webhooks

📡 API Reference

Authentication

POST /api/login

Authenticate and receive JWT token.

Request:

{
  "username": "admin",
  "password": "password"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "...",
  "user": {
    "id": 1,
    "username": "admin",
    "role": "Admin"
  },
  "expires_in": 900
}

Protected Endpoints (Require Bearer Token)

Core Security APIs

Enterprise Analytics APIs

Alert and Integration APIs

Health Check

GET /api/health

Returns comprehensive system health status.

"note": "See CI / Release section in this README for how releases are built and how to pull the official Docker image from GHCR."

---

## 🧩 CI / Release

Releases are performed by the repository GitHub Actions workflows. Key points:

- The CI pipeline builds and tests the project, runs linting, security scans, and produces artifacts (platform binaries).
- A separate Docker job builds multi-arch images and pushes them to GitHub Container Registry (GHCR) under `ghcr.io/<owner>/<repo>:<tag>`.
- The release job packages artifacts and creates a GitHub Release. The workflow also verifies the pushed Docker image by attempting to `docker pull` the released image during the release job.
- An SBOM (CycloneDX JSON) is generated and attached to the release artifacts.

How to pull the official release image from GHCR:

```bash
# Authenticate to GHCR (use a personal access token with appropriate scopes)
echo "${GHCR_TOKEN}" | docker login ghcr.io -u <USERNAME> --password-stdin

# Pull the image for a given tag (example: v2.2.4)
docker pull ghcr.io/<owner>/<repo>:v2.2.4

If you run into problems with releases or CI, check .github/workflows/ci.yml and .github/workflows/release.yml for the exact steps executed during builds.

{
"status": "healthy",
"uptime": "2h30m15s",
"version": "2.1.0",
"edition": "Enterprise",
"name": "Obsidian Sentinel WAF",
"features": {
"waf_engine": true,
"threat_intelligence": true,
"rate_limiting": true,
"geoip_blocking": true,
"webhook_alerts": true,
"postgresql": true,
"redis": true,
"advanced_analytics": true
},
"stats": {
"total_requests": 15432,
"blocked_requests": 127,
"active_threats": 2041,
"blocked_countries": 3
}
}

---

## 🔐 Security

### JWT Token Security
- Tokens signed with HMAC-SHA256
- Configurable expiration (default: 15 minutes)
- Refresh token rotation
- Secrets stored in environment variables
- Constant-time signature comparison
- Role-based claims validation

### Advanced Rate Limiting
- 256-shard sliding window algorithm
- Redis-backed distributed limiting
- Per-IP and per-endpoint tracking
- Configurable limits:
  - 200 requests/minute general
  - 5 login attempts/minute
  - Custom thresholds per endpoint
- Whitelist/blacklist IP management
- Geographic rate limiting

### Threat Intelligence Sources
- **Spamhaus DROP/EDROP** - 800+ malicious networks
- **Emerging Threats** - 1000+ compromised IPs
- **Firehol Level 1** - 200+ high-confidence threats
- **Custom feeds** - User-defined blocklists
- **GeoIP risk scoring** - Country-based threat assessment
- **Real-time updates** - Feeds refreshed every 4 hours

### GeoIP Security
- MaxMind GeoIP2 database integration
- Country-based blocking/allowing
- Risk score calculation
- VPN/Proxy/Tor detection
- Threat score based on geography
- Custom country rules with reasons

### Security Headers

X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Content-Security-Policy: default-src 'self'; ...

---

## 📦 Deployment

### Docker (Recommended)

#### Simple Deployment
```dockerfile
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN cd cmd/obsidian && go build -o obsidian .

FROM alpine:latest
RUN apk --no-cache add ca-certificates tzdata
WORKDIR /app
COPY --from=builder /app/cmd/obsidian/obsidian .
EXPOSE 8082
CMD ["./obsidian", "-port", "8082"]

Docker Compose (Repository Standard)

Use the checked-in docker-compose.yml and one of these env templates:

• .env.docker.example for local postgres + redis containers
• .env.external.example for managed/external DB + Redis

# Internal postgres + redis
cp .env.docker.example .env.docker
docker compose --env-file .env.docker up -d --build

# External managed services
cp .env.external.example .env.external
docker compose --env-file .env.external up -d --build

Notes:

• For Compose networking, use service names (postgres, redis) in URLs, not localhost.
• .env is for local go run workflows; prefer dedicated env files for Docker publish/deploy.
• OBSIDIAN_JWT_SECRET is required and must be set per environment.

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: obsidian-waf
  namespace: security
spec:
  replicas: 3
  selector:
    matchLabels:
      app: obsidian-waf
  template:
    metadata:
      labels:
        app: obsidian-waf
    spec:
      containers:
      - name: obsidian
        image: obsidian:2.1.0
        ports:
        - containerPort: 8082
        env:
        - name: OBSIDIAN_JWT_SECRET
          valueFrom:
            secretKeyRef:
              name: obsidian-secrets
              key: jwt-secret
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: obsidian-secrets
              key: database-url
        - name: REDIS_URL
          value: "redis://obsidian-redis:6379/0"
        - name: GEOIP_DATABASE_PATH
          value: "/data/GeoLite2-Country.mmdb"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /api/health
            port: 8082
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /api/health
            port: 8082
          initialDelaySeconds: 5
          periodSeconds: 10
        volumeMounts:
        - name: geoip-data
          mountPath: /data
      volumes:
      - name: geoip-data
        configMap:
          name: geoip-database
---
apiVersion: v1
kind: Service
metadata:
  name: obsidian-waf-service
spec:
  selector:
    app: obsidian-waf
  ports:
  - protocol: TCP
    port: 80
    targetPort: 8082
  type: LoadBalancer

Systemd Service

[Unit]
Description=Obsidian Sentinel WAF
After=network.target

[Service]
Type=simple
User=obsidian
WorkingDirectory=/opt/obsidian
Environment=OBSIDIAN_JWT_SECRET=your-secret-here
ExecStart=/opt/obsidian/obsidian -port 8082
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

📊 Documentation

🧪 Testing

Run Tests

go test ./... -v

Run with Coverage

go test ./... -cover -coverprofile=coverage.out
go tool cover -html=coverage.out

Test WAF Rules

# Test XSS blocking
curl -X GET "http://localhost:8082/api/test?input=<script>alert(1)</script>"

# Test SQL injection blocking
curl -X GET "http://localhost:8082/api/test?id=1' OR '1'='1"

📊 Monitoring

Metrics Endpoint

GET /api/metrics returns comprehensive system metrics:

{
  "total_requests": 25432,
  "blocked_requests": 327,
  "uptime_seconds": 172800,
  "memory_alloc_mb": 65,
  "memory_sys_mb": 128,
  "goroutines": 23,
  "rate_limiter": {
    "active_visitors": 15,
    "blacklist_count": 5,
    "whitelist_count": 10,
    "rate_limited_ips": 3,
    "requests_per_minute": 200,
    "shards": 256,
    "total_allowed": 25105,
    "total_blocked": 327
  },
  "threat_intel": {
    "total_threats": 2041,
    "feeds_active": 4,
    "last_update": "2026-02-01T14:30:00Z",
    "blocked_today": 127,
    "high_risk_count": 1205
  },
  "geoip": {
    "blocked_countries": 3,
    "total_lookups": 15432,
    "cache_hits": 12890,
    "cache_misses": 2542
  },
  "webhooks": {
    "active_webhooks": 2,
    "alerts_sent_today": 15,
    "alerts_failed": 1
  }
}

WebSocket Real-Time Updates

Connect to ws://localhost:8082/api/ws?token=<jwt> for live stats updates.

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📜 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

🙏 Acknowledgments

• Coraza WAF - The core WAF engine
• OWASP CRS - Core Rule Set inspiration
• ModSecurity - SecLang rule language

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Security: See SECURITY.md for reporting vulnerabilities

👨‍💻 Author

Abhishek Yadav
Computer Science Student

⭐ Star this repo if you find it helpful!

Made with ❤️ for the cybersecurity community

First and foremost, huge thanks to Juan Pablo Tosso for starting this project, and building an amazing community around Coraza!

Today we have lots of amazing contributors, we could not have done this without you!

Made with contrib.rocks.