AssetMapper

Network asset discovery and port scanner module for CyberOps Suite. Built on Nmap with a FastAPI backend, PostgreSQL storage, Redis caching, and a React dashboard.

Installation

Prerequisites

• Docker and Docker Compose (for PostgreSQL and Redis)
• Python 3.12+
• nmap (installed automatically by the installer on supported systems)

Linux / macOS

git clone https://github.com/user/assetmapper.git
cd assetmapper
./install.sh

Windows

git clone https://github.com/user/assetmapper.git
cd assetmapper
powershell -ExecutionPolicy Bypass -File install.ps1

The installer checks for Docker, installs nmap if missing, creates a Python virtual environment, installs dependencies, and sets up the assetmapper CLI command.

Usage

Start

assetmapper start

This starts PostgreSQL and Redis containers, runs database migrations, launches the backend with elevated privileges (for full scan capabilities), and opens the dashboard in your default browser at http://localhost:5003.

Options:

• --port PORT -- Use a custom port (default: 5003)
• --no-browser -- Do not open the browser automatically
• --no-sudo -- Start without elevated privileges (basic TCP scans only, no OS detection)

Stop

assetmapper stop

Stops the backend and Docker containers. Scan data is preserved in Docker volumes and will be available on next start.

Status

assetmapper status

Scan from CLI

assetmapper scan 192.168.1.0/24
assetmapper scan 10.0.0.1 --type full
assetmapper scan 172.16.0.0/16 --type discovery

Database Migrations

assetmapper db migrate

Development

Local Backend Development

source .venv/bin/activate
docker compose -f docker-compose.prod.yml up -d
alembic upgrade head
uvicorn app.main:app --host 0.0.0.0 --port 5003 --reload

Frontend Development

Requires Bun 1.0+ (not needed for production use).

cd frontend
bun install
bun run dev    # Dev server with hot reload (proxies /api to port 5003)
bun run build  # Production build (output: frontend/dist/)

Running Tests

source .venv/bin/activate
pytest tests/ -v

Configuration

Application settings are loaded from config.yml and can be overridden with environment variables using the ASSETMAPPER__ prefix with __ as the nested delimiter.

Example: ASSETMAPPER__APP__DEBUG=true overrides app.debug in config.yml.

API Endpoints

Health

• GET /api/health -- Service health check (name, version, status)

Scan Management

• POST /api/scan/network -- Start a network scan (returns 202 with scan_id)
• GET /api/scan/{scan_id}/status -- Get scan status, timing, and host count
• GET /api/scan/history -- Paginated scan history with scan_type and limit filters

Scan Profiles

• GET /api/scan/profiles -- List all scan profiles
• POST /api/scan/profiles -- Create a scan profile
• GET /api/scan/profiles/{profile_id} -- Get a profile by ID
• PUT /api/scan/profiles/{profile_id} -- Update a profile
• DELETE /api/scan/profiles/{profile_id} -- Delete a profile

Asset Management

• GET /api/assets -- List assets with filters (status, type, criticality, search), pagination
• GET /api/assets/{asset_id} -- Full asset detail with nested services
• PUT /api/assets/{asset_id} -- Update hostname, criticality, tags, custom_metadata, type
• DELETE /api/assets/{asset_id} -- Soft-delete (sets status to "archived")
• GET /api/assets/{asset_id}/history -- Historical snapshots for an asset

Scan Schedules

• POST /api/scan/schedule -- Create a recurring scan schedule (cron expression)
• GET /api/scan/schedules -- List all scan schedules
• PUT /api/scan/schedule/{schedule_id} -- Update a schedule (name, target, cron, enabled)
• DELETE /api/scan/schedule/{schedule_id} -- Delete a schedule and remove from scheduler

Reports and Analytics

• GET /api/reports/summary -- Aggregate counts: total/active/inactive/archived assets, by type, by OS, critical count, changes in last 24h
• GET /api/reports/compliance?standard=pci-dss -- Compliance evaluation against PCI-DSS or HIPAA standards with issues list
• GET /api/reports/topology -- Network topology graph (nodes and edges) for visualization
• GET /api/reports/export/csv -- Export assets as CSV file
• GET /api/reports/export/json -- Export assets as JSON array with services

Configuration and Exclusions

• GET /api/config/scan-profiles -- List all scan profiles
• POST /api/config/scan-profiles -- Create a custom scan profile
• POST /api/config/exclusions -- Add IPs to exclusion list with reason
• GET /api/config/exclusions -- List all exclusions
• DELETE /api/config/exclusions/{exclusion_id} -- Remove an exclusion

Alerting and Webhooks

• POST /api/config/webhooks -- Register a webhook URL for change notifications
• GET /api/config/webhooks -- List all registered webhooks
• DELETE /api/config/webhooks/{webhook_id} -- Remove a registered webhook

Audit Logging

• GET /api/audit/logs -- List audit logs with filters (action, entity_type, since, until), pagination

Change Detection

• GET /api/assets/changes -- List changes with filters (type, severity, asset_id, since), pagination

Scanner Engine

The scanner wraps Nmap via python-nmap and supports:

• Scan types: quick (top ports), full (all 65535 ports), discovery (ping sweep), custom
• OS detection (-O) and service version detection (-sV)
• Timing templates: paranoid, sneaky, polite, normal, aggressive, insane
• Error handling: descriptive exceptions for missing binary, permission denied, unreachable targets
• Asset persistence: discovered hosts and services are upserted into the database after scan completion
• Change detection: automatic post-scan comparison detects new devices, offline devices, new/closed services, and OS changes
• Scheduled scanning: recurring scans via cron expressions using APScheduler with automatic next_run computation
• Compliance engine: PCI-DSS and HIPAA rule evaluation against asset inventory with issue reporting
• Reports and export: summary statistics, network topology, CSV and JSON export
• Exclusion filtering: excluded IPs are automatically removed from scan results before asset persistence
• Webhook alerting: change events delivered to registered webhooks with HMAC-SHA256 signatures and configurable retry logic
• Audit logging: all API operations (scans, asset updates, schedule changes, config changes) recorded with before/after state
• Concurrent scan limit: configurable max_concurrent_scans enforced at the API level (429 when exceeded)
• Rate limiting: token-bucket middleware (120 req/min per IP, configurable)
• Input validation: Pydantic schemas enforce field constraints, lengths, and allowed values across all endpoints
• Frontend dashboard: React-based UI with asset management, scan controls, network topology, compliance reports, and audit log viewer

Database Models

• Asset -- IP, MAC, hostname, OS info, status, criticality, tags
• Service -- Port, protocol, state, product, version (linked to Asset)
• Scan -- Target, type, status, timing, host/change counts
• ScanProfile -- Named scan configurations (port range, timing, duration)
• ScanSchedule -- Cron-based scan scheduling
• AssetSnapshot -- Point-in-time asset state captures
• Change -- Detected changes between scans
• Exclusion -- IPs excluded from scanning
• Webhook -- Registered webhook endpoints for alert delivery
• AuditLog -- Timestamped records of API operations and entity changes

Migrations are managed with Alembic (async PostgreSQL via asyncpg).

Project Structure

app/
  api/           Route handlers (health, scans, schedules, config, reports, audit, assets, changes)
  core/          Configuration (Pydantic Settings + YAML)
  db/            Async engine, session factory, seed data
  models/        SQLAlchemy ORM models
  schemas/       Pydantic request/response schemas
  services/      Scanner engine, scan executor, scheduler, compliance, asset manager, change detector, alerter, audit
  main.py        FastAPI application entry point (serves API + frontend)
cli/
  __main__.py    CLI entry point (assetmapper command)
  commands.py    start, stop, status, scan, db commands
  platform.py    OS detection, privilege escalation utilities
frontend/
  dist/          Pre-built production frontend (committed to repo)
  src/           React source (Bun + Vite + TailwindCSS)
alembic/         Database migration scripts
tests/           Test suite (281 tests)
config.yml       Default configuration
docker-compose.prod.yml   Production compose (PostgreSQL + Redis only)
docker-compose.yml        Full stack compose (includes app container)
install.sh       Linux/macOS installer
install.ps1      Windows installer