_ _ _____ __
/ \ _ __ ___ (_) / ____| / _|
/ _ \ | '_ ` _ \| | \___ \ __ _| |_ ___
/ ___ \| | | | | | | ___) / _` | _/ _ \
/_/ \_\_| |_| |_|_| |____/ \__,_|_| \___/
Automated network scanning and vulnerability assessment platform.
Project & target management · Real-time scan monitoring · Professional reporting
AmISafe is a self-hosted security assessment platform designed for security professionals and penetration testers. It provides a structured environment for managing assessments across multiple projects and targets, integrating Nmap for scanning, and surfacing results through a clean, real-time dashboard.
The system is split into a stateless FastAPI backend (async, WebSocket-enabled) and a Next.js frontend, with MongoDB as the document store. The architecture is intentionally simple enough to self-host on a single machine, while remaining extensible enough to plug in additional scanning tools.
- Overview
- Contents
- Features
- Architecture
- Tech Stack
- Project Structure
- Getting Started
- Environment Variables
- API Reference
- Configuration
- License
Project & Target Management
- Hierarchical organization: projects contain multiple targets
- Color-coded projects with tags and custom metadata
- Per-target tracking of IP addresses and hostnames
Scanning
- Port scanning, service detection, and OS fingerprinting via Nmap
- Configurable scan types, timing templates, and advanced flags
- Extensible scanner interface designed for Nikto, Nuclei, and others
Real-Time Monitoring
- Live scan progress via a dedicated WebSocket channel per client
- Automatic polling fallback when WebSocket connections are unavailable
- Robust error handling and connection lifecycle management
Reporting & Analytics
- Dashboard with vulnerability counts and port statistics
- Automated risk classification by severity level
- Full scan logs with structured JSON result storage
┌─────────────────────────────────┐
│ Next.js Frontend │
│ (App Router · shadcn/ui · WS) │
└────────────┬──────────┬──────────┘
│ REST │ WebSocket
┌────────────▼──────────▼──────────┐
│ FastAPI Backend │
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ Router │ │ WS Handler │ │
│ └────┬─────┘ └──────┬───────┘ │
│ │ │ │
│ ┌────▼───────────────▼───────┐ │
│ │ Service Layer │ │
│ │ projects · scans · targets │ │
│ └────────────┬───────────────┘ │
│ │ │
│ ┌────────────▼──────────────┐ │
│ │ Scanner Layer │ │
│ │ nmap_scanner.py │ │
│ └───────────────────────────┘ │
└──────────────┬────────────────────┘
│ Motor (async)
┌──────────────▼────────────────────┐
│ MongoDB │
│ projects · targets · scans │
│ scan_results │
└───────────────────────────────────┘
REST endpoints handle CRUD for projects, targets, and scans. A persistent WebSocket connection per client receives live scan events. The scanner layer invokes Nmap asynchronously and normalizes output into structured JSON stored in MongoDB.
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 14 (App Router) | UI framework with server components |
| UI Components | shadcn/ui + TailwindCSS | Design system and styling |
| Backend | FastAPI (Python) | Async REST API and WebSocket server |
| Data validation | Pydantic v2 | Schema enforcement and serialization |
| Database | MongoDB + Motor | Async document storage |
| Scanner | Nmap | Port scanning and OS detection |
| Real-time | WebSocket (native) | Live scan progress streaming |
AmISafe/
├── BackEnd/
│ ├── main.py # Application entry point
│ ├── config/
│ │ └── database.py # MongoDB connection and retry logic
│ ├── models/
│ │ ├── schemas.py # Pydantic request/response models
│ │ └── mongodb_models.py # Database-layer operations
│ ├── api/
│ │ ├── projects.py # Project CRUD routes
│ │ ├── scans.py # Scan management routes
│ │ └── websocket.py # WebSocket endpoint and event dispatch
│ ├── services/
│ │ ├── project_service.py # Project business logic
│ │ ├── scan_service.py # Scan orchestration and state tracking
│ │ └── target_service.py # Target management
│ ├── scanner/
│ │ └── nmap_scanner.py # Nmap invocation and output parsing
│ └── utils/
│
├── Frontend/
│ ├── app/
│ │ ├── page.tsx # Main dashboard
│ │ ├── layout.tsx # Root layout and providers
│ │ └── globals.css # Global styles
│ ├── components/
│ │ ├── ui/ # Base shadcn/ui components
│ │ ├── project-overview.tsx
│ │ ├── scan-configuration.tsx
│ │ └── project-creation-dialog.tsx
│ ├── hooks/
│ │ └── use-api.ts # Data fetching hooks
│ └── lib/
│ ├── api.ts # Typed API client
│ └── utils.ts # Shared utilities
│
└── scripts/
├── dev.py # Development server bootstrap
└── start_with_mongodb.sh # Service startup convenience script
- Python 3.8+ (3.10 or 3.11 recommended)
- Node.js 18+
- MongoDB Community Server (local, port
27017) - Nmap installed and accessible in
PATH - Git
1. Create a virtual environment and install dependencies
cd BackEnd
python -m venv venv
# Windows
venv\Scripts\activate
# Linux / macOS
source venv/bin/activate
pip install -r requirements.txt2. Configure environment variables
Create BackEnd/.env:
MONGODB_URL=mongodb://localhost:27017
DATABASE_NAME=amisafe
HOST=0.0.0.0
PORT=80003. Start the backend
python dev.pyThe API will be available at http://localhost:8000.
Interactive docs: http://localhost:8000/api/docs
1. Install dependencies
cd Frontend
npm install2. Configure environment variables
Create Frontend/.env.local:
NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_WS_URL=ws://localhost:8000/ws3. Start the dev server
npm run devFrontend available at http://localhost:3000.
| Variable | Default | Description |
|---|---|---|
MONGODB_URL |
mongodb://localhost:27017 |
MongoDB connection string |
DATABASE_NAME |
amisafe |
Database name |
HOST |
0.0.0.0 |
Server bind address |
PORT |
8000 |
Server port |
| Variable | Description |
|---|---|
NEXT_PUBLIC_API_URL |
Base URL of the FastAPI backend |
NEXT_PUBLIC_WS_URL |
WebSocket base URL for real-time scan events |
GET /api/v1/projects/ List all projects
POST /api/v1/projects/ Create a project
GET /api/v1/projects/{id} Get project details
PUT /api/v1/projects/{id} Update a project
DELETE /api/v1/projects/{id} Delete a project
GET /api/v1/scans/ List scans
POST /api/v1/scans/ Start a new scan
GET /api/v1/scans/{id} Get scan details and results
ws://<HOST>:<PORT>/ws/{client_id}
Connect with a unique client_id. The server pushes JSON events for scan progress, status changes, and completed results. If the connection drops, the frontend falls back to HTTP polling automatically.
Database initialization
To set up indexes or seed sample data:
cd BackEnd
python setup_mongodb.pyRunning all services at once
bash scripts/start_with_mongodb.shThis checks that MongoDB is running, then starts the backend and frontend in sequence.
Released under the MIT License.