Skip to content

QUICKSTART.md

Latest commit

 

History

History
297 lines (241 loc) · 6.36 KB

QUICKSTART.md

File metadata and controls

297 lines (241 loc) · 6.36 KB
Raw

API Security Monitoring System - Quick Start Guide

Get the system up and running in 5 minutes.

1. Initialize Models (One-time setup)

# Initialize project and create demo models
python3 scripts/init.py

Expected output:

✓ Created models directory: public/models
✓ Demo models created successfully
✓ Created .env.local template
✓ Project initialization complete!

2. Install Dependencies

# Frontend dependencies
npm install

# Backend dependencies
pip install -r scripts/requirements.txt

3. Start the System

Option A: Manual Startup (Recommended for Development)

Terminal 1 - Backend:

python3 scripts/run_backend.py

Wait for:

INFO:     Application startup complete

Terminal 2 - Frontend:

npm run dev

Wait for:

▲ Next.js 16.x.x
- Local:        http://localhost:3000

Option B: Single Command (Using Concurrently)

First, install concurrently:

npm install --save-dev concurrently

Then add to package.json scripts:

"dev-full": "concurrently \"python3 scripts/run_backend.py\" \"npm run dev\""

Run:

npm run dev-full

4. Access the Dashboard

Open your browser and go to:

5. Test the System

Generate Sample Threat

curl -X POST http://localhost:3000/api/proxy/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "path": "/api/admin/users",
    "headers": {"User-Agent": "Suspicious-Bot/1.0"},
    "body": "'; DROP TABLE users; --",
    "source_ip": "192.168.1.100",
    "response": {
      "status_code": 403,
      "response_time_ms": 150
    }
  }'

Expected response:

{
  "request_id": 1,
  "analysis": {
    "cnn_score": 0.65,
    "bilstm_score": 0.45,
    "combined_score": 0.59,
    "threat_level": "HIGH",
    "classification": "Request Anomaly (Injection/Malformed)",
    "recommendation": "FLAG for review and monitor closely"
  },
  "processing_time_ms": 12.5
}

View Live Dashboard

The dashboard will show:

  1. Updated threat count
  2. New alert in "Recent Security Alerts"
  3. Threat metrics updated in cards
  4. New entry in Security Logs

Demo Scenarios

Low Threat (Normal Traffic)

curl -X POST http://localhost:3000/api/proxy/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "path": "/api/public/data",
    "headers": {"User-Agent": "Chrome/120.0"},
    "source_ip": "8.8.8.8",
    "response": {"status_code": 200, "response_time_ms": 45}
  }'

Medium Threat (Suspicious Pattern)

curl -X POST http://localhost:3000/api/proxy/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "path": "/api/users/search?email=admin@example.com",
    "headers": {"User-Agent": "Mozilla/5.0"},
    "source_ip": "10.0.0.50",
    "response": {"status_code": 200, "response_time_ms": 120}
  }'

High Threat (Attack Pattern)

curl -X POST http://localhost:3000/api/proxy/api/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "method": "POST",
    "path": "/api/admin/config",
    "headers": {"Authorization": "Bearer invalid", "X-Forwarded-For": "multiple-ips"},
    "body": "<script>alert(\"xss\")</script>",
    "source_ip": "203.0.113.45",
    "response": {"status_code": 401, "response_time_ms": 500}
  }'

Common Issues

Backend won't connect

Problem: "Failed to connect to backend service" Solution:

  1. Verify backend is running: curl http://localhost:8000/api/health
  2. Check FASTAPI_URL in .env.local
  3. Ensure port 8000 is not in use

Port already in use

Problem: "Address already in use" Solution:

# Find process using port
lsof -i :8000  # For backend
lsof -i :3000  # For frontend

# Kill process (replace PID with actual process ID)
kill -9 <PID>

Python module not found

Problem: ModuleNotFoundError: No module named 'fastapi' Solution:

pip install -r scripts/requirements.txt
# Or install manually:
pip install fastapi uvicorn pydantic numpy scikit-learn

Models not found

Problem: Models don't load on startup Solution:

python3 scripts/create_models.py
# Or reinitialize:
python3 scripts/init.py

Dashboard Features

Main Dashboard

  • Real-time threat statistics
  • Threat distribution chart
  • CNN vs BiLSTM score comparison
  • Recent security alerts

Analytics Page

  • 24-hour threat trends
  • Detection rate per hour
  • Model performance metrics
  • Historical statistics

Logs Page

  • All analyzed requests
  • Filtering by threat level, IP, path
  • Export to CSV
  • Pagination

Alerts Page

  • Unacknowledged threats only
  • Detailed threat information
  • Recommended actions
  • One-click acknowledgement

API Endpoints Reference

Analyze Requests

# Single request
POST /api/proxy/api/analyze
Body: JSON with method, path, headers, body, response

# Batch analysis
POST /api/proxy/api/analyze-batch
Body: { "requests": [...] }

Get Data

# Security logs (with optional filters)
GET /api/proxy/api/logs?threat_level=HIGH&limit=50

# Statistics
GET /api/proxy/api/stats

# Active alerts
GET /api/proxy/api/alerts

Manage Alerts

# Acknowledge alert
POST /api/proxy/api/alerts/{alert_id}/acknowledge

Next Steps

  1. Integrate with Your API: Modify your API to send requests to the analysis endpoint
  2. Train Custom Models: Replace demo models with real trained models
  3. Set Up Database: Configure PostgreSQL for persistent storage
  4. Deploy: Use Vercel for frontend, cloud provider for backend
  5. Customize Alerts: Add custom alert rules and thresholds

Performance Tips

  • For high volume: Use batch analysis endpoint
  • Cache analysis results if same requests repeat
  • Use appropriate pagination when fetching logs
  • Monitor backend resource usage
  • Consider async processing for production

Support & Debugging

Enable debug logging in FastAPI:

# In api_backend.py
logging.basicConfig(level=logging.DEBUG)

Check all logs:

  • Frontend: Browser console (F12 → Console)
  • Backend: Terminal running uvicorn
  • Security logs: Dashboard Logs page

Production Deployment

See README.md for:

  • Database configuration
  • HTTPS setup
  • Authentication
  • Scaling considerations
  • Security best practices