Skip to content

README.md

Latest commit

 

History

History
346 lines (266 loc) · 9.68 KB

README.md

File metadata and controls

346 lines (266 loc) · 9.68 KB

AIris Security — Backend

FastAPI service powering scan orchestration, ML inference, and PDF report generation.

For complete file-by-file backend coverage, see BACKEND_MODULE_DOCUMENTATION.md.

📌 Overview

The backend is a FastAPI + Motor (async MongoDB) application that serves as the core engine of AIris Security.

Responsibilities:

  • Auto-detect and orchestrate four security scanners (Nmap, Nikto, SSLScan, DirSearch)
  • Parse and aggregate scanner output into structured findings
  • Run an ML risk engine (XGBoost attack predictor + NLP payload classifier)
  • Generate professional PDF reports with severity charts and remediation guidance
  • Handle JWT authentication and user management
  • Stream real-time scan logs to the frontend via status polling

🗂️ Structure

backend/
├── server.py                     # FastAPI app + Windows event-loop policy
├── requirements.txt
├── .env.example
├── setup_backend.ps1             # One-shot setup script
│
├── app/
│   ├── core/
│   │   ├── config.py             # Pydantic Settings (reads .env)
│   │   └── security.py           # JWT + bcrypt helpers
│   ├── db/
│   │   └── mongodb.py            # Motor client + collection accessors
│   ├── models/
│   │   ├── user.py
│   │   ├── scan.py
│   │   └── report.py
│   ├── schemas/                  # Pydantic request/response schemas
│   ├── api/
│   │   ├── auth.py               # POST /api/auth/register|login, GET /api/auth/me
│   │   └── report.py             # GET /api/report/{id}
│   ├── routes/
│   │   └── scan.py               # POST /api/scan/start
│   │                             # GET  /api/scan/status|results|health|scanners
│   ├── scanners/
│   │   ├── __init__.py           # Auto-detection registry (AVAILABLE_SCANNERS)
│   │   ├── base.py               # Abstract BaseScanner
│   │   ├── nmap_scanner.py       # Nmap XML parser
│   │   ├── nikto_scanner.py      # Nikto text parser
│   │   ├── sslscan_scanner.py    # SSLScan TLS/cipher/certificate parser
│   │   └── dirsearch_scanner.py  # DirSearch plain-format output parser
│   └── services/
│       ├── scan_service.py       # Scan lifecycle (create/update/retrieve)
│       ├── scanner_orchestrator.py  # Runs all scanners, feeds ML
│       ├── ml_service.py         # Hybrid ML risk scoring
│       ├── pdf_report.py         # ReportLab PDF builder
│       ├── aggregator_service.py # Finding aggregation
│       ├── vulnerability_aggregator.py  # Deduplication
│       └── auth_service.py       # User CRUD
│
├── ml_models/                    # Runtime ML models (legacy path, active models in ml/models/)
│   ├── payload_classifier.joblib
│   ├── attack_predictor.joblib
│   └── attack_label_encoder.joblib
│
└── security_tools/               # Scanner binaries
    ├── tool_paths.txt            # Explicit path overrides
    ├── nikto/
    ├── sslscan/
    └── dirsearch/

⚙️ Installation

Prerequisites

  • Python 3.10+
  • MongoDB 4.4+ (local or Atlas)
  • Security scanners — see Scanner Setup below

1. Virtual environment

# From the repo root
python -m venv .venv
.venv\Scripts\Activate.ps1        # Windows
# source .venv/bin/activate       # Linux / Mac

2. Install dependencies

pip install -r backend/requirements.txt

3. Configure environment

cd backend
Copy-Item .env.example .env

Edit backend/.env:

# MongoDB
MONGODB_URI=mongodb://localhost:27017
DATABASE_NAME=airis_security

# JWT
SECRET_KEY=change-this-to-a-long-random-string
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=10080   # 7 days

# CORS
CORS_ORIGINS=http://localhost:3000

# Logging
LOG_LEVEL=INFO

4. Scanner paths (optional)

If your tools are not on PATH, add their locations to security_tools/tool_paths.txt:

NMAP_PATH=C:\Program Files (x86)\Nmap\nmap.exe
NIKTO_PATH=F:\...\nikto\program\nikto.pl
PERL_PATH=C:\Strawberry\perl\bin\perl.exe
DIRSEARCH_PATH=F:\...\dirsearch\dirsearch.py
SSLSCAN_PATH=F:\...\sslscan\sslscan.exe

5. Run

cd backend
uvicorn server:app --reload --host 127.0.0.1 --port 8000

API docs: http://localhost:8000/api/docs

🔍 Scanner Setup

Nmap

# Windows (Chocolatey)
choco install nmap

# Ubuntu / Debian
sudo apt install nmap

Nikto + Perl

# Windows — install Strawberry Perl, then bundled nikto is in security_tools/nikto/
# Linux
sudo apt install nikto

SSLScan / testssl.sh

# Windows binary: https://github.com/rbsec/sslscan/releases
# Or use testssl.sh (requires bash): https://testssl.sh/
# Linux
sudo apt install sslscan

DirSearch

pip install dirsearch
# Or clone: git clone https://github.com/maurosoria/dirsearch
# Bundled copy also lives at security_tools/dirsearch/

Scanner availability is checked automatically at startup. The /api/scan/health endpoint lists which scanners were detected.

🧰 Developer workflow

Run the backend

cd backend
uvicorn server:app --reload --host 127.0.0.1 --port 8000

Run the frontend (in a separate terminal)

cd frontend
npm install
npm run dev

Run the full test suite

cd backend
pytest

Run lint/formatting (if configured)

# Python formatting (if used)
cd backend
black .
ruff .

🧩 Environment variables (backend)

Create backend/.env from backend/.env.example and configure the values below.

Name Purpose Example/Default
MONGODB_URI MongoDB connection string mongodb://localhost:27017
DATABASE_NAME MongoDB database name airis_security
SECRET_KEY JWT signing secret (must be strong/unique in prod) change-this-to-a-long-random-string
ALGORITHM JWT signing algorithm HS256
ACCESS_TOKEN_EXPIRE_MINUTES Token lifetime in minutes 10080 (7 days)
CORS_ORIGINS Allowed browser origins (comma-separated) http://localhost:3000

📄 API Reference

Authentication

Method Path Body Response
POST /api/auth/register {email, password} {message}
POST /api/auth/login {email, password} {access_token, user}
GET /api/auth/me — {user_id, email, username, ...}

Scanning

Method Path Auth Description
GET /api/scan/health No System status + available scanners
GET /api/scan/scanners No List of detected scanner names
POST /api/scan/start JWT Start scan: {target: "example.com"}
GET /api/scan/status/{id} JWT {status, progress, logs, ...}
GET /api/scan/results/{id} JWT Full findings + ML analysis
GET /api/scan/report/{id}/pdf JWT Download PDF (binary)
GET /api/report/{id} JWT Return report payload from reports collection

Status values

initializing → scanning → analyzing → completed | error

Scan result shape

{
  "scan_id": "scan_20260303_120000_all",
  "target": "example.com",
  "status": "completed",
  "progress": 100,
  "scanners": ["nmap", "nikto", "sslscan", "dirsearch"],
  "findings": [
    {
      "type": "open_port",
      "severity": "high",
      "title": "SSH on port 22",
      "description": "...",
      "port": 22,
      "service": "ssh",
      "recommendation": "..."
    }
  ],
  "ml_analysis": {
    "risk_score": 62,
    "attack_type": "XSS",
    "confidence": 0.87,
    "payload_prediction": "XSS",
    "ml_powered": true
  },
  "raw_output": "..."
}

🤖 ML Service

app/services/ml_service.py — analyze_scan(findings, scanner_results)

  1. Build scan input — payload text + scanner blocks (nmap, nikto, sslscan, dirsearch)
  2. Run advanced inference — ml/src/inference.py::predict_attack(scan_input)
  3. Use trained artifacts — payload classifier + XGBoost attack predictor
  4. Map result for API — risk_score, attack_type, confidence, payload_prediction, ml_powered

📋 PDF Report

app/services/pdf_report.py — PDFReportGenerator.generate_scan_report(scan_data) → bytes

Sections:

  1. Scan Info — target, timestamps, scanner list
  2. ML Analysis — risk gauge chart, expanded ML table, attack vectors, CVE context, green remediation callout
  3. Findings — severity pie chart, per-severity grouped tables with highlighted Mitigation: rows
  4. Raw Output — full scanner stdout

Charts are generated with matplotlib (Agg backend) and embedded as in-memory PNG images — no temp files written.

The REMEDIATION_MAP constant contains 48 entries covering ML attack types, SSL/TLS findings, network port findings, and web/directory findings.

🧪 Testing

cd backend
pytest

🐛 Troubleshooting

Problem Fix
ModuleNotFoundError Activate venv and re-run pip install -r requirements.txt
MongoDB connection refused Start MongoDB service (mongod)
Scanner shows as unavailable Add path to security_tools/tool_paths.txt
NotImplementedError on Windows Ensure server.py sets WindowsProactorEventLoopPolicy
PDF generation fails Install matplotlib: pip install matplotlib
DirSearch output empty Check target has HTTP prefix; dirsearch needs http://

Last updated: March 2026 · v2.1.0