Skip to content

vadhh/ritapi-v-sentinel

BranchesTags

Repository files navigation

RITAPI V-Sentinel

Network security enforcement platform combining a Django operations dashboard with a real-time AI-powered firewall engine. Designed for regulatory compliance environments (gambling domain blocking), the system performs DNS-based domain analysis, network flow tracking, and automated IP blocking using nftables.

Table of Contents

Architecture Overview

The platform consists of two main components that run as separate systemd services:

                           +---------------------+
                           |      Nginx          |
                           |  (Reverse Proxy)    |
                           +-----+--------+------+
                                 |        |
                    Port 8000    |        |   Port 8080
                  (Gunicorn)     |        |   (Uvicorn)
                                 v        v
              +------------------+--+  +--+------------------+
              |  RITAPI V-Sentinel  |  |  MiniFW-AI Service  |
              |  (Django Dashboard) |  |  (FastAPI + Engine)  |
              +---------------------+  +----------------------+
              | - Ops Dashboards    |  | - DNS Event Stream   |
              | - ASN Lookup        |  | - Flow Tracking      |
              | - IP Reputation     |  | - MLP Inference      |
              | - Alert Management  |  | - YARA Scanning      |
              | - JSON Schema Valid.|  | - nftables Enforce.  |
              | - Geo-Blocking      |  | - Policy Engine      |
              | - MiniFW CRUD UI    |  | - Sector Lock        |
              | - Request Logging   |  | - Audit Logging      |
              +--------+------------+  +----------+-----------+
                       |                          |
                       v                          v
                  PostgreSQL              SQLite + JSONL Logs
                  + Redis                 + nftables/ipset

RITAPI V-Sentinel (Django) provides the web-based operations dashboard for configuration management, monitoring, and reporting. It connects to PostgreSQL for persistent storage and Redis for rate limiting and caching.

MiniFW-AI Service (FastAPI + daemon) is the real-time security engine. It runs a continuous event loop that consumes DNS queries (from dnsmasq logs, journald, or none/degraded), tracks network flows via conntrack, scores threats using a multi-layer decision pipeline, and enforces blocking via nftables sets. It also exposes a FastAPI admin interface for managing allow/deny lists, policies, events, users, and audit logs.

Key Features

Threat Detection and Enforcement

  • Multi-layer scoring: DNS domain feeds, TLS SNI inspection, burst detection, flow analysis
  • Hard threat gates: PPS saturation, burst flood, bot-like small packet patterns, regular timing detection
  • MLP neural network inference for flow-level anomaly detection (scikit-learn)
  • YARA rule scanning on domain and SNI payloads
  • Automated IP blocking via nftables named sets with configurable timeouts
  • Conntrack-based flow tracking with LRU eviction

Sector Lock System

  • Factory-set, immutable sector configuration (school, hospital, government, finance, legal, establishment)
  • Sector-specific threshold adjustments, feed lists, and policy overrides
  • Hospital mode with IoMT (Internet of Medical Things) high-priority alerting

Operations Dashboard (Django)

  • ASN lookup and configuration
  • IP reputation checking
  • Alert management with Telegram integration
  • Geo-blocking configuration
  • JSON schema validation
  • Request logging and analytics
  • MiniFW policy management (CRUD for allow/deny lists)
  • Blocked IP map visualization

Unified Dashboard Features (Django)

  • Security event viewer with DataTables server-side processing and Excel export
  • User management with 5-tier RBAC (Super Admin, Admin, Operator, Auditor, Viewer)
  • Full audit logging with filtering, statistics, and JSON export
  • Sector lock status display

Resilience

  • Graceful degradation: service continues without DNS telemetry (fail-open telemetry, fail-closed security)
  • Pluggable DNS backends: file, journald, or none
  • Restart storm prevention via systemd StartLimitBurst
  • Deployment state tracking in /var/log/ritapi/deployment_state.json

Tech Stack

RITAPI V-Sentinel (Django)

Component Technology
Framework Django 4.2 with Django REST Framework
WSGI Server Gunicorn 22
Database PostgreSQL 15 (SQLite in-memory for tests)
Cache / Rate Limiter Redis 7
Template Engine Django Templates
Network Tools ipwhois, httpx, geoip2
Data / ML pandas, scikit-learn
TLS / Crypto cryptography, pyOpenSSL
Validation jsonschema
Task Queue Celery (optional)

MiniFW-AI Service

Component Technology
Web Framework FastAPI 0.120 with Uvicorn
AI/ML scikit-learn (MLP), NumPy 1.26.4 (pinned for legacy CPU compat), pandas, SciPy
Security Scanning yara-python
Authentication python-jose (JWT), passlib + bcrypt, pyotp (TOTP)
Database SQLAlchemy with SQLite
Firewall nftables, ipset (via subprocess)
UI AdminLTE 3 (Jinja2 templates)

Infrastructure

Component Technology
Reverse Proxy Nginx
Process Manager systemd
DNS Telemetry dnsmasq or systemd-resolved (optional)
Flow Tracking Linux conntrack (/proc/net/nf_conntrack)
CI/CD GitHub Actions
Log Rotation logrotate

Project Structure

ritapi-v-sentinel/
|-- docker-compose.yml                  # Docker demo stack (postgres, redis, django, minifw)
|-- docker/
|   |-- Dockerfile.django              # Django image (python:3.11-slim, deps only)
|   |-- Dockerfile.minifw             # MiniFW image (python:3.11-slim, deps only)
|   `-- demo.env                       # Pre-filled demo credentials (do not use in prod)
|
|-- install.sh                          # Main all-in-one installer (interactive menu)
|-- install_fixed.sh                    # Alternative installer variant
|-- vsentinel-audit.sh                  # Integration audit script (read-only diagnostics)
|-- vm_guide.md                         # VM installation walkthrough
|
|-- .github/
|   `-- workflows/
|       `-- pre-flight-check.yml        # CI: security audit, linting, tests
|
|-- docs/
|   |-- CARA_PAKAI.md                   # Usage guide (Indonesian)
|   |-- DEGRADED_MODE_IMPLEMENTATION.md # Resilience architecture documentation
|   |-- PANDUAN_INSTALASI_LENGKAP.md    # Full installation guide (Indonesian)
|   |-- README_INSTALLER.md             # Installer reference
|   |-- ROLLBACK_SOP.md                 # Rollback standard operating procedure
|   |-- TEST_PROCEDURES_STAGING.md      # Staging test procedures
|   `-- VERSION_PINNING.md              # Dependency version pinning policy
|
|-- scripts/
|   |-- logrotate.d/                    # Logrotate configuration files
|   |-- minifw_fixed/                   # CRUD fix and permission scripts
|   |-- vsentinel.env.template          # Environment variable template
|   |-- vsentinel.env.example           # Environment variable example
|   |-- vsentinel_selftest.sh           # Post-installation self-test with proof pack
|   |-- vsentinel_runtime_guard.sh      # Runtime guard (ExecStartPre)
|   |-- vsentinel_scope_gate.sh         # Scope gate script
|   |-- vsentinel_backup.sh             # Pre-upgrade backup script
|   `-- vsentinel_rollback.sh           # Rollback script
|
|-- projects/
|   |-- ritapi_django/                  # Django Operations Dashboard
|   |   |-- manage.py
|   |   |-- requirements.txt
|   |   |-- ritapi_v_sentinel/          # Django project settings, URLs, WSGI/ASGI
|   |   |-- authentication/             # Login, logout, password change, OpsAuth middleware
|   |   |-- asn/                        # ASN lookup and management
|   |   |-- ip_reputation/              # IP reputation checking
|   |   |-- alert/                      # Alert management and services
|   |   |-- blocking/                   # IP blocking module
|   |   |-- json_schema/                # JSON schema validation
|   |   |-- log_channel/                # Request logging
|   |   |-- minifw/                     # MiniFW CRUD integration for Django
|   |   |-- ml/                         # Machine learning module
|   |   |-- ops/                        # Ops dashboard views
|   |   |   |-- ops_asn/
|   |   |   |-- ops_iprep/
|   |   |   |-- ops_json/
|   |   |   |-- ops_alert/
|   |   |   |-- ops_blocking/
|   |   |   `-- ops_geoblock/
|   |   |-- middlewares/                # Rate limiting, security enforcement
|   |   |-- templates/                  # HTML templates (base, sidebar, dashboards)
|   |   `-- .env                        # Local development environment
|   |
|   `-- minifw_ai_service/             # MiniFW-AI Security Engine
|       |-- requirements.txt
|       |-- app/
|       |   |-- web/                    # FastAPI application
|       |   |   |-- app.py              # FastAPI entrypoint
|       |   |   |-- routers/            # admin, auth, health, status routes
|       |   |   |-- static/             # AdminLTE assets
|       |   |   `-- templates/          # Jinja2 admin templates
|       |   |-- minifw_ai/             # Core security engine
|       |   |   |-- main.py            # Main event loop and scoring logic
|       |   |   |-- policy.py          # Policy configuration loader
|       |   |   |-- enforce.py         # nftables/ipset enforcement
|       |   |   |-- feeds.py           # Domain feed matcher
|       |   |   |-- events.py          # Event model and writer
|       |   |   |-- burst.py           # Burst/rate tracker
|       |   |   |-- collector_dnsmasq.py  # DNS event stream (file/journald)
|       |   |   |-- collector_zeek.py  # Zeek TLS SNI collector
|       |   |   |-- collector_flow.py  # Conntrack flow tracker
|       |   |   |-- sector_lock.py     # Factory-set sector configuration
|       |   |   |-- sector_config.py   # Sector threshold adjustments
|       |   |   |-- netutil.py         # IP/subnet utilities
|       |   |   `-- utils/
|       |   |       |-- mlp_engine.py  # MLP neural network detector
|       |   |       `-- yara_scanner.py # YARA rule scanner
|       |   |-- controllers/           # Admin and auth controllers
|       |   |-- services/              # Business logic services
|       |   |-- models/                # SQLAlchemy models (User, Audit)
|       |   |-- schemas/               # Pydantic schemas
|       |   |-- middleware/            # Auth middleware (JWT)
|       |   `-- database.py            # SQLAlchemy database initialization
|       |-- config/                     # Policy JSON, feeds, dnsmasq config
|       |-- systemd/                   # minifw-ai.service unit file
|       |-- testing/                   # Integration and unit tests
|       |-- yara_rules/                # YARA rule files
|       |-- models/                    # Trained ML model files
|       `-- scripts/                   # Helper scripts

System Requirements

Requirement Minimum Recommended
OS Ubuntu 20.04 / Debian 11 Ubuntu 22.04 / Debian 12
RAM 2 GB 4 GB
Disk 5 GB free 10 GB free
CPU 1 vCPU 2 vCPUs
Python 3.10+ 3.11+
Network Internet for package downloads -
Access Root / sudo -

Additional runtime dependencies (installed by the installer):

  • PostgreSQL
  • Redis
  • Nginx
  • nftables
  • ipset
  • dnsmasq (optional -- system operates in BASELINE_PROTECTION without it)

Installation

Automated Installation (Recommended)

The project includes an all-in-one interactive installer:

chmod +x install.sh
sudo ./install.sh

The installer presents an interactive menu:

1. Install (Full Installation)
2. Status (Check Services)
3. Uninstall (Remove Everything)
4. Exit

You can also pass a subcommand directly:

sudo ./install.sh install   # Direct install (skip menu)
sudo ./install.sh status    # Check service status

The installer will:

  1. Detect the web server user (www-data, nginx, or apache)
  2. Install all system dependencies (Python, PostgreSQL, Redis, Nginx, nftables, ipset)
  3. Set up PostgreSQL (start service, create database user and database from env credentials)
  4. Create Python virtual environments for both services
  5. Install Python dependencies from requirements files
  6. Configure Nginx as a reverse proxy
  7. Set up systemd service units (ritapi-gunicorn.service, minifw-ai.service)
  8. Auto-detect server IP and configure DJANGO_ALLOWED_HOSTS in /etc/ritapi/vsentinel.env
  9. Run Django migrations and optionally create a superuser
  10. Detect DNS telemetry availability and configure BASELINE_PROTECTION if needed
  11. Write a deployment state file to /var/log/ritapi/deployment_state.json

Installation paths:

  • Django application: /opt/ritapi_v_sentinel
  • MiniFW-AI service: /opt/minifw_ai
  • Unified configuration: /etc/ritapi/vsentinel.env
  • Logs: /var/log/ritapi/

Local Development

Docker Demo Stack (Recommended for UI/UX Development)

The fastest way to run the full stack locally without kernel dependencies (nftables, dnsmasq):

docker compose up --build
URL Service
http://localhost:8000 Django dashboard
http://localhost:8080 MiniFW web admin

Django templates and MiniFW app code hot-reload on save — no rebuild needed.

Seed demo data:

docker compose exec django python ../../demos/demo_ritapi_dashboard.py

Reset demo data:

docker compose exec django python ../../demos/demo_ritapi_dashboard.py --reset

The demo stack runs with DEGRADED_MODE=1, MINIFW_DNS_SOURCE=none, and MINIFW_ENFORCE=0 (observe-only, no nftables). Credentials and paths are pre-filled in docker/demo.env — do not use those values in production.

Django Dashboard (manual venv)

cd projects/ritapi_django
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

The Django dev server starts on http://127.0.0.1:8000. In production, Gunicorn serves the application:

gunicorn --workers 3 --bind 127.0.0.1:8000 ritapi_v_sentinel.wsgi:application

MiniFW-AI Service

cd projects/minifw_ai_service
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# Required environment variables
export MINIFW_SECRET_KEY=test-secret
export MINIFW_ADMIN_PASSWORD=test-pass

# Run the daemon (event loop + scoring pipeline)
python -m minifw_ai

# Or run the web admin only
uvicorn app.web.app:app --host 0.0.0.0 --port 8000

Note: The daemon requires PYTHONPATH to include the app/ directory. In production, the systemd unit sets PYTHONPATH=/opt/minifw_ai/app.

Configuration

Environment Variables

All configuration is managed through a unified environment file at /etc/ritapi/vsentinel.env. A template is provided at scripts/vsentinel.env.template.

For local development, the Django project reads from projects/ritapi_django/.env. In production, /etc/ritapi/vsentinel.env takes priority and the local .env is ignored.

Shared Secrets

Variable Description Default
DJANGO_SECRET_KEY Django cryptographic signing key (auto-generated by installer)
MINIFW_SECRET_KEY MiniFW JWT signing secret (auto-generated by installer)
MINIFW_ADMIN_PASSWORD Admin bootstrap password for MiniFW (auto-generated by installer)
DB_PASSWORD PostgreSQL password (auto-generated by installer)
TELEGRAM_TOKEN Telegram bot token for alerts (empty)
TELEGRAM_CHAT_ID Telegram chat ID for alerts (empty)

Django Web

Variable Description Default
DJANGO_DEBUG Enable debug mode False
DJANGO_ALLOWED_HOSTS Comma-separated allowed hosts localhost,127.0.0.1
PG_MODE PostgreSQL install mode: auto, abort, reuse, external auto
DATABASE_URL Full DB URL for external mode (overrides individual DB_* vars) (empty)
DB_NAME PostgreSQL database name ritapi_v_sentinel
DB_USER PostgreSQL user ritapi
DB_HOST PostgreSQL host 127.0.0.1
DB_PORT PostgreSQL port 5432
REDIS_URL Redis connection URL redis://127.0.0.1:6379/0
APP_VERSION Application version label 0.1.0

MiniFW Core

Variable Description Default
MINIFW_POLICY Path to policy.json /opt/minifw_ai/config/policy.json
MINIFW_FEEDS Path to feeds directory /opt/minifw_ai/config/feeds
MINIFW_LOG Path to events log /opt/minifw_ai/logs/events.jsonl
MINIFW_FLOW_RECORDS Path to flow records log /opt/minifw_ai/logs/flow_records.jsonl
MINIFW_DNS_SOURCE DNS telemetry source: file, journald, none none
DEGRADED_MODE Telemetry mode flag (0=AI_ENHANCED_PROTECTION, 1=BASELINE_PROTECTION) 0
MINIFW_DNS_LOG_PATH DNS log path (when source=file) (empty)
MINIFW_YARA_RULES YARA rules directory /opt/minifw_ai/yara_rules
MINIFW_MLP_MODEL MLP model file path /opt/minifw_ai/models/mlp_v2.joblib
MODEL_NAME Policy engine model name v_sentinel_mlp
MODEL_VERSION Policy engine model version mlp_v2
POLICY_ID Regulatory policy identifier V-SENTINEL-GOV-01
POLICY_VERSION Regulatory policy version 1.0
GAMBLING_ONLY Regulatory enforcement mode (must be 1) 1
ALLOWED_DETECTION_TYPES Allowed detection type categories gambling
MLP_ENABLED Enable MLP engine 1
MINIFW_ENFORCE Enable nftables enforcement (0 = observe-only, for Docker/demo use) 1

The following variables are read from the environment at runtime but are not included in the template (they have sensible defaults):

Variable Description Default
AI_ENABLED Enable/disable AI modules true
MINIFW_MAX_FLOWS Maximum tracked flows (LRU) 20000
MINIFW_FLOW_FREQ_THRESHOLD Flow frequency threshold for hard gate 200

Policy Configuration

The MiniFW engine reads its policy from a JSON file (default: /opt/minifw_ai/config/policy.json). The policy defines:

  • Segments: Network segments with block and monitor score thresholds
  • Segment Subnets: CIDR-to-segment mapping
  • Features: Scoring weights for DNS, SNI, ASN, burst, MLP, and YARA
  • Enforcement: nftables set name, IP timeout, table, and chain
  • Collectors: dnsmasq log path, Zeek SSL log path, Zeek SNI toggle
  • Burst: DNS queries-per-minute thresholds for monitor and block actions

Usage

Accessing the Dashboard

After installation, access the Django dashboard at:

http://<SERVER_IP>/

Authenticated superusers are redirected to the ops dashboard. The dashboard provides navigation to all operational modules via a sidebar.

Creating an Admin User

cd /opt/ritapi_v_sentinel
sudo -u www-data ./venv/bin/python manage.py createsuperuser

Service Management

# Check status of all services
sudo systemctl status postgresql ritapi-gunicorn minifw-ai nginx

# Restart individual services
sudo systemctl restart postgresql
sudo systemctl restart ritapi-gunicorn
sudo systemctl restart minifw-ai
sudo systemctl restart nginx

# View real-time logs
sudo journalctl -u ritapi-gunicorn -f
sudo journalctl -u minifw-ai -f

Using the Installer Status Check

sudo ./install.sh status

API Endpoints

Django Application

Method Path Description
GET / Redirect to dashboard or login
GET /healthz Health check endpoint
GET /admin/ Django admin interface
- /auth/login/, /auth/logout/ Authentication
- /asn/ ASN lookup and management
- /ip-reputation/ IP reputation checking
- /alerts/ Alert management
- /blocking/ IP blocking management
- /json/ JSON schema validation
- /ops/requestlogs/ Request log viewer
- /ops/ Operations dashboard
- /ops/minifw/ MiniFW configuration UI

MiniFW-AI Service (FastAPI)

Method Path Description
GET / Service status
GET /health/ Health check
GET /status/ Service status details
GET /auth/login Login page
POST /auth/login Authenticate (returns JWT)
GET /admin/ Dashboard
GET/POST/PUT/DELETE /admin/allow-domain Allowed domains CRUD
GET/POST/PUT/DELETE /admin/deny-ip Denied IPs CRUD
GET/POST/PUT/DELETE /admin/deny-asn Denied ASNs CRUD
GET/POST/PUT/DELETE /admin/deny-domain Denied domains CRUD
GET /admin/events Events viewer page
GET /admin/api/events Events DataTables API
GET /admin/api/events/download Events Excel export
GET/POST /admin/policy Policy configuration
POST /admin/policy/segment Add segment
DELETE /admin/policy/segment/{name} Delete segment
POST /admin/policy/segment/subnets Update segment subnets
POST /admin/policy/features Update feature weights
POST /admin/policy/enforcement Update enforcement config
POST /admin/policy/collectors Update collectors config
POST /admin/policy/burst Update burst thresholds
GET /admin/users User management page
GET/POST /admin/api/users List / create users
PUT /admin/api/users/{id} Update user
PUT /admin/api/users/{id}/password Change password
DELETE /admin/api/users/{id} Delete user
GET /admin/audit-logs Audit logs page
GET /admin/api/audit/logs Audit logs API (filterable)
GET /admin/api/audit/statistics Audit statistics
GET /admin/api/audit/export Export audit logs
GET /admin/api/sector-lock Sector lock status

Testing

Django Tests

cd projects/ritapi_django
source venv/bin/activate
python manage.py test              # All tests
python manage.py test alert        # Single app
python manage.py test asn
python manage.py test ip_reputation

Tests use an in-memory SQLite database (configured in settings.py when test is in sys.argv).

MiniFW-AI Tests

cd projects/minifw_ai_service
source venv/bin/activate

# Set required environment variables
export MINIFW_SECRET_KEY=test-secret-key
export MINIFW_ADMIN_PASSWORD=test-admin-pass

# PYTHONPATH must include app/ since minifw_ai lives under app/
PYTHONPATH=app pytest testing/ -v

# With coverage
PYTHONPATH=app pytest testing/ -v --cov=app --cov-report=term

Note: GAMBLING_ONLY=1 is set automatically by testing/conftest.py -- no need to export it manually.

Test files include:

  • test_baseline_hard_gates.py -- Hard threat gate logic
  • test_flow_collector_simulated.py -- Flow tracking simulation
  • test_full_integration.py -- End-to-end integration
  • test_mlp_inference.py / test_mlp_integration.py -- MLP model tests
  • test_yara_scanner.py -- YARA rule scanning
  • test_sector_lock.py -- Sector lock system
  • test_standalone_integration.py -- Standalone integration

CI Pipeline

The GitHub Actions workflow (.github/workflows/pre-flight-check.yml) runs on pushes to main, master, and develop, and on pull requests to main/master. It executes:

  1. Security Audit -- detect-secrets, pip-audit, Bandit linter, .env file detection
  2. Code Quality -- flake8, black formatting check, TODO/FIXME scanning
  3. MiniFW-AI Tests -- pytest with coverage
  4. Django Tests -- Django migrations and test runner (with PostgreSQL and Redis services)
  5. Pre-Flight Report -- Consolidated go/no-go verdict

Deployment

Production Deployment

The installer handles production deployment. Key production considerations:

  1. Generate strong secrets:

    openssl rand -hex 32  # Use for DJANGO_SECRET_KEY and MINIFW_SECRET_KEY

  2. Set DJANGO_DEBUG=False in /etc/ritapi/vsentinel.env

  3. Configure DJANGO_ALLOWED_HOSTS with your domain/IP

  4. Set up HTTPS with Let's Encrypt:

    sudo certbot --nginx -d yourdomain.com

  5. Configure firewall:

    sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Systemd Services

After installation, two primary services run:

  • ritapi-gunicorn.service -- Django application via Gunicorn
  • minifw-ai.service -- MiniFW-AI security engine

The MiniFW-AI service unit includes:

  • Pre-start configuration validation (config_check.py)
  • Pre-start runtime guard (vsentinel_runtime_guard.sh)
  • Restart storm prevention (StartLimitBurst=5, StartLimitIntervalSec=300)
  • Automatic restart on failure (RestartSec=10)

Backup and Rollback

A backup is automatically created during upgrades via install.sh. You can also run backups manually:

sudo scripts/vsentinel_backup.sh

To roll back to a previous backup:

sudo scripts/vsentinel_rollback.sh

See docs/ROLLBACK_SOP.md for the full rollback standard operating procedure.

Post-Installation Verification

Run the self-test script to verify the installation and generate a regulatory proof pack:

sudo /opt/ritapi-v-sentinel/scripts/vsentinel_selftest.sh

This checks:

  • Service status and enablement (ritapi-gunicorn, minifw-ai, nginx)
  • Configuration file presence
  • GAMBLING_ONLY enforcement flag
  • Deployment state and operational mode (AI_ENHANCED_PROTECTION or BASELINE_PROTECTION)
  • IPset existence

The proof pack is written to /var/log/ritapi/proof_packs/ as a JSON file.

Integration Audit

Run the integration audit to detect known mismatches between the Django dashboard and MiniFW-AI:

sudo ./vsentinel-audit.sh

This performs read-only checks on:

  • Filesystem layout and expected files
  • Systemd unit configuration correctness
  • Firewall dependency availability (nft, ipset)
  • Policy schema drift
  • Dashboard-to-engine privilege boundaries
  • DNS/resolver conflicts
  • Python dependency compatibility (NumPy, pandas, scikit-learn, SciPy)

Security Features

Django Middleware Stack

The Django application applies security middleware in this order:

  1. RateLimiterMiddleware -- Per-IP rate limiting backed by Redis (default: 20 requests per 60 seconds). Returns HTTP 429 on excess. Skips health checks, admin, static assets, and ops paths.

  2. SecurityEnforcementMiddleware -- Validates JSON request bodies (max 2 MB, content-type enforcement) and inspects file uploads. Configurable path exclusions.

  3. OpsAuthMiddleware -- Enforces authentication on /ops/ paths.

MiniFW-AI Security

  • JWT Authentication -- All admin endpoints require a valid JWT token
  • TOTP 2FA -- Optional TOTP-based two-factor authentication via pyotp
  • RBAC -- Role-based access control for user management (Super Admin required for user CRUD)
  • Password Hashing -- bcrypt via passlib
  • Input Validation -- nftables object names validated with strict regex (alphanumeric + underscore, max 32 chars)
  • Audit Logging -- All administrative actions recorded with timestamps, user, action, severity, and resource type

Regulatory Compliance

  • GAMBLING_ONLY=1 hard guard: the MiniFW-AI engine refuses to start if this flag is not set
  • Sector lock system prevents runtime modification of the deployment sector
  • Proof pack generation for regulatory auditing
  • Deployment state file tracks telemetry availability

Operational Tooling

Script Location Purpose
install.sh Root All-in-one installer with install/status/uninstall menu
vsentinel-audit.sh Root Read-only integration audit (detect mismatches)
vsentinel_selftest.sh scripts/ Post-install self-test with proof pack generation
vsentinel_runtime_guard.sh scripts/ ExecStartPre runtime guard for MiniFW-AI
vsentinel_scope_gate.sh scripts/ Scope gate enforcement
vsentinel_backup.sh scripts/ Pre-upgrade backup
vsentinel_rollback.sh scripts/ Rollback to previous backup
fix_permissions.sh scripts/minifw_fixed/ Fix CRUD permissions for MiniFW

Log Locations

Log Path
Django (Gunicorn) journalctl -u ritapi-gunicorn
MiniFW-AI journalctl -u minifw-ai
Nginx errors /var/log/nginx/error.log
MiniFW events /opt/minifw_ai/logs/events.jsonl
MiniFW flow records /opt/minifw_ai/logs/flow_records.jsonl
Deployment state /var/log/ritapi/deployment_state.json
Self-test proof packs /var/log/ritapi/proof_packs/

Troubleshooting

Services not starting

# Check detailed service status
sudo systemctl status ritapi-gunicorn
sudo systemctl status minifw-ai

# View recent logs
sudo journalctl -u ritapi-gunicorn -n 100
sudo journalctl -u minifw-ai -n 100

# Check Nginx configuration
sudo nginx -t

MiniFW-AI restart storms

The service unit includes StartLimitBurst=5 and StartLimitIntervalSec=300 to prevent restart storms. If the service is flapping:

# Check restart limits
systemctl show minifw-ai | grep -i limit

# Check for DNS-related failures
journalctl -u minifw-ai --since "1 hour ago" | grep -i "degraded\|error\|fatal"

Permission errors on MiniFW CRUD

cd scripts/minifw_fixed
sudo ./fix_permissions.sh

PostgreSQL connection refused (400/500 errors on login)

If you see connection to server at "127.0.0.1", port 5432 failed: Connection refused, PostgreSQL is not running:

sudo systemctl start postgresql
sudo systemctl enable postgresql

ALLOWED_HOSTS / 400 Bad Request

If the dashboard returns 400 when accessed by server IP, the IP is not in DJANGO_ALLOWED_HOSTS:

# Add your server IP to the unified config
sudo sed -i "s/^DJANGO_ALLOWED_HOSTS=\(.*\)$/DJANGO_ALLOWED_HOSTS=\1,YOUR_SERVER_IP/" /etc/ritapi/vsentinel.env
sudo systemctl restart ritapi-gunicorn

Redis connection issues (rate limiter)

The rate limiter middleware fails open -- if Redis is unavailable, requests are allowed through. Check Redis status:

sudo systemctl status redis
redis-cli ping

Web dashboard not accessible

sudo systemctl restart ritapi-gunicorn nginx
sudo journalctl -u ritapi-gunicorn -n 50

Additional Documentation

Document Path Description
Quick Start QUICKSTART.md Fast-track installation guide
Resilience Reference RESILIENCE_QUICKSTART.md BASELINE_PROTECTION implementation details
VM Guide vm_guide.md Full VM installation walkthrough
Rollback SOP docs/ROLLBACK_SOP.md Backup and rollback procedures
Test Procedures docs/TEST_PROCEDURES_STAGING.md Staging environment test procedures
Version Pinning docs/VERSION_PINNING.md Dependency version pinning policy
Baseline Protection docs/DEGRADED_MODE_IMPLEMENTATION.md Resilience architecture deep dive
Installer Reference docs/README_INSTALLER.md Installer quick reference
Usage Guide docs/CARA_PAKAI.md Step-by-step usage guide (Indonesian)
Full Install Guide docs/PANDUAN_INSTALASI_LENGKAP.md Detailed installation documentation (Indonesian)

License

As per original projects.

Version: 2.0 (All-in-One Complete Package)

About

Network security enforcement platform combining a Django operations dashboard with a real-time AI-powered firewall engine. Designed for regulatory compliance environments (gambling domain blocking), the system performs DNS-based domain analysis, network flow tracking.

Topics

django ai dashboard dnsmasq enforcement network-security

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages