ARMOR

A full-stack cybersecurity platform for network asset discovery.

Documentation Map

• Backend setup and operations: Server/README.md
• Frontend setup and development: Client/README.md

---

Table of Contents

• Overview
• Architecture
• Tech Stack
• Features
• Project Structure
• Getting Started
  • Prerequisites
  • Running with Docker (recommended)
  • Running locally (development)
• API Reference
• Environment Variables
• Useful Commands

---

Overview

ARMOR automates network scanning using nmap, enriches discovered hosts with OS, device type, and vulnerability data, and presents results through a real-time dashboard. Scan progress is streamed live to the browser over WebSocket. PDF and email reports can be generated per scan.

---

Architecture

flowchart LR
    U[User Browser]
    C[Client App\nReact + Vite + Redux]

    API[Web Service\nDjango + DRF + Daphne]
    WS[WebSocket Consumer\nDjango Channels]

    DB[(PostgreSQL)]
    R[(Redis)]

    ORCH[Scan Orchestrator Task]
    W[Celery Worker Pool\nNmap Scans]
    FIN[Scan Finalizer Task]
    BEAT[Celery Beat]
    FLOWER[Flower]

    PDF[PDF Report Generator]
    EMAIL[Email Sender]

    U --> C
    C -->|REST + JWT| API
    C -->|ws://.../ws/scans/:scan_id/| WS

    API --> DB
    API -->|dispatch scan tasks| ORCH
    API -->|publish scan updates| WS

    ORCH -->|discover hosts| W
    ORCH -->|init progress/results| R
    W -->|store host results + progress| R
    W -->|scan metadata| DB

    R -->|aggregate results| FIN
    FIN -->|bulk create assets/ports| DB
    FIN -->|final completion event| WS

    BEAT -->|scheduled jobs| ORCH
    BEAT -->|scheduled reports| PDF
    PDF --> DB
    PDF --> EMAIL

    FLOWER -. monitors .- ORCH
    FLOWER -. monitors .- W
    FLOWER -. monitors .- FIN

Loading

• The web container serves the REST API and the Django Channels WebSocket endpoint.
• One or more celery_worker containers pick up scan tasks. Each worker can run multiple concurrent scans (CELERY_CONCURRENCY). The number of worker containers is controlled by CELERY_REPLICAS.
• Celery Beat handles periodic background jobs (e.g. scheduled scans).
• Scan progress events are pushed from the worker → Redis channel layer → WebSocket → Redux store in the browser in real time.

---

Tech Stack

Backend

Technology	Purpose
Django 5.2 + DRF	REST API
Daphne + Django Channels 4	ASGI server, WebSocket support
Celery 5 + Redis	Async task queue, parallel scanning
Celery Beat	Scheduled / periodic tasks
Flower	Celery worker monitoring UI
PostgreSQL 16	Primary database
Redis 7	Broker, result backend, channel layer cache
python-nmap	nmap wrapper for host/port discovery
ReportLab	PDF report generation
drf-yasg	Swagger / ReDoc API docs
SimpleJWT	JWT authentication

Frontend

Technology	Purpose
React 19 + TypeScript	UI framework
Vite	Build tool / dev server
Redux Toolkit + redux-persist	Global state, scan session persistence
React Router 7	Client-side routing
Radix UI + Tailwind CSS	Component primitives + styling
Chart.js + react-chartjs-2	Dashboard charts
Sonner	Toast notifications
CSS Modules	Scoped component styles

---

Features

• Network scanning — standard (quick) and comprehensive (deep) nmap scan modes
• Real-time progress — live WebSocket feed of scan status, current host, ports found, and asset counts
• Asset management — full CRUD on discovered hosts; editable ports, severity ratings, device classification
• Dashboard — severity timeline, doughnut distribution, ports analysis, device type charts
• Reports — download PDF or email a full scan report
• User management — registration, login, JWT refresh, password change/reset via email
• Parallel scanning — multiple Celery worker replicas each handling concurrent nmap processes
• Docker-first — single docker compose up -d brings up the entire stack; nmap raw-socket capabilities granted via cap_add

---

Project Structure

ARMOR-FYP/
├── Client/                         # React frontend (Vite)
│   ├── src/
│   │   ├── components/
│   │   │   ├── charts/             # Chart.js chart components
│   │   │   ├── custom/             # CyberGrid, Sidebar, Header, RadarScanner…
│   │   │   ├── models/             # Modal components (InitiateScan, etc.)
│   │   │   └── ui/                 # Radix-based primitives (button, dialog…)
│   │   ├── pages/                  # Dashboard, Assets, Scans, AssetDetails…
│   │   ├── routes/                 # AppRouter, ProtectedRoutes
│   │   ├── store/
│   │   │   ├── apis/               # RTK Query APIs + wsClient (WebSocket config)
│   │   │   └── slices/             # auth, scanSession Redux slices
│   │   └── types/                  # Shared TypeScript interfaces
│   └── .env                        # VITE_API_BASE_URL, VITE_WS_BASE_URL
│
└── Server/                         # Django backend
    ├── Armor/                      # Project settings, ASGI, Celery config
    ├── asset_management/
    │   ├── models.py               # Scan, Asset, Port models
    │   ├── views.py                # ScanViewSet, AssetViewSet, ReportViewSet
    │   ├── serializers.py
    │   ├── consumers.py            # WebSocket consumer (scan progress)
    │   ├── tasks/                  # Celery tasks: orchestrator, enrichment, finalizer
    │   └── services.py             # nmap execution, data processing
    ├── users/                      # Custom user model, auth views
    ├── Dockerfile
    ├── docker-compose.yml
    ├── entrypoint.sh
    ├── Makefile
    └── .env                        # Server environment variables

---

Getting Started

Prerequisites

• Docker Desktop (includes Compose v2) — install
• Node.js 20+ — only needed for local frontend development

Running with Docker (recommended)

cd Server

# 1. Copy environment template and fill in values
cp .env.example .env        # Linux/macOS
# copy .env.example .env    # Windows (PowerShell/CMD)

# 2. Build images and start all services
docker compose up -d --build

# 3. Check everything is healthy
docker compose ps

Services once up:

Service	URL
Django REST API	http://localhost:8000/api/v1/
Swagger docs	http://localhost:8000/swagger/
Flower (worker monitor)	http://localhost:5555
pgAdmin	http://localhost:5050

Scale workers for heavier scanning

# In Server/.env:
CELERY_REPLICAS=4      # number of worker containers
CELERY_CONCURRENCY=6   # concurrent nmap processes per worker

docker compose up -d --scale celery_worker=4

Running locally (development)

Backend

cd Server
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env            # Linux/macOS
# copy .env.example .env        # Windows

python manage.py migrate
python manage.py runserver      # or: daphne -b 0.0.0.0 -p 8000 Armor.asgi:application

# In separate terminals:
celery -A Armor worker -l info
celery -A Armor beat -l info

Frontend

cd Client
cp .env.example .env            # Linux/macOS
# copy .env.example .env        # Windows
npm install
npm run dev                     # http://localhost:5173

---

API Reference

Full interactive docs available at http://localhost:8000/swagger/ when the server is running.

Authentication — /api/v1/auth/

Method	Endpoint	Description
POST	/register/	Register a new user
POST	/login/	Login, returns JWT tokens
POST	/logout/	Invalidate refresh token
POST	/token/refresh/	Refresh access token
POST	/password/change/	Change password
POST	/password/reset/email/	Send password reset email
POST	/password/reset/{uid}/{token}/	Confirm password reset

Asset Management — /api/v1/asset-management/

Method	Endpoint	Description
GET	/scans/	List all scans
POST	/scans/	Start a new scan
GET	/scans/{id}/	Scan details
DELETE	/scans/{id}/	Delete scan
POST	/scans/{id}/cancel/	Cancel running scan
GET	/scans/{id}/assets/	Assets discovered in scan
GET	/scans/statistics/	Aggregate scan statistics
GET	/assets/{id}/	Asset details
PATCH	/assets/{id}/	Update asset
DELETE	/assets/{id}/	Delete asset
GET	/assets/{id}/ports/	Ports for an asset
GET	/reports/{scan_id}/pdf/	Download PDF report
POST	/reports/{scan_id}/email/	Email report

WebSocket

ws://localhost:8000/ws/scans/{scan_id}/

Messages received: { type: "scan_update", data: { status, progress, message, host, ports_found, ... } }

---

Environment Variables

Server (Server/.env)

Variable	Default	Description
SECRET_KEY	—	Django secret key (required)
DEBUG	True	Django debug mode
DB_NAME	armor_db	PostgreSQL database name
DB_USER	armor_user	PostgreSQL user
DB_PASSWORD	—	PostgreSQL password
DB_HOST	db	DB host (db in Docker, localhost locally)
REDIS_HOST	redis	Redis host
CELERY_BROKER_URL	redis://redis:6379/0	Celery broker
CELERY_CONCURRENCY	4	Concurrent tasks per worker
CELERY_REPLICAS	2	Worker container replicas
FRONTEND_URL	http://localhost:5173	CORS allowed origin
EMAIL_HOST_USER	—	Gmail address for email reports
EMAIL_HOST_PASSWORD	—	Gmail app password

Client (Client/.env)

Variable	Default	Description
VITE_API_BASE_URL	http://127.0.0.1:8000/api/v1/	REST API base URL
VITE_WS_BASE_URL	ws://127.0.0.1:8000	WebSocket base URL

---

Useful Commands

All Make targets run from the Server/ directory.

make up           # Start stack (detached)
make dev          # Start stack (foreground logs)
make down         # Stop stack
make logs         # Tail all logs
make logs-celery  # Tail worker logs only
make bash         # Shell into web container
make migrate      # Apply migrations inside container
make scale N=4    # Scale to 4 worker containers
make clean        # Destroy containers + volumes (DESTRUCTIVE)