Skip to content

Setup & Usage Guide

Requirements

Tool Version
Docker ≥ 24
Docker Compose ≥ 2.20
Go (local dev only) 1.22+
Node.js (local dev only) 20+

Quick start with Docker Compose

# 1. Clone / enter the repo
cd NIR-VKR-src

# 2. Start all services (uses mock scanner data)
TEST_MODE=true docker compose up --build

# Services:
#   http://localhost:3000  — React frontend
#   http://localhost:8080  — Go API
#   localhost:5432         — PostgreSQL
#   localhost:6379         — Redis

With real scanners

Install the scanner binaries on the worker host:

go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
go install -v github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest
sudo apt-get install -y nmap       # or brew install nmap

Then start without test mode:

docker compose up --build

Local development (no Docker)

Backend

cd backend
go mod download

# Needs running postgres + redis
export EASM_DATABASE_DSN="postgres://easm:easm@localhost:5432/easm?sslmode=disable"
export EASM_REDIS_ADDR="localhost:6379"
export EASM_TEST_MODE=true

# Start API server
go run ./cmd/api

# Start worker (separate terminal)
go run ./cmd/worker

Frontend

cd frontend
npm install
npm run dev     # starts on http://localhost:3000

The Vite dev server proxies /api/* to http://localhost:8080 automatically.

First-time setup flow

  1. Open http://localhost:3000
  2. Register an admin account at /register (select role Admin)
  3. Create an Organization
  4. Add a Scope (e.g. type=domain, value=example.com)
  5. As admin, Approve the scope (click the ✓ on the scope row)
  6. Go to Scans, select the approved scope, choose a profile, click Start Scan
  7. Watch scan jobs appear; assets and vulnerabilities populate automatically
  8. Visit Asset Graph to explore the topology
  9. Visit Vulnerabilities to triage findings

Environment variables

Variable Default Description
EASM_SERVER_PORT 8080 API listen port
EASM_DATABASE_DSN postgres://easm:easm@… PostgreSQL DSN
EASM_REDIS_ADDR localhost:6379 Redis address
EASM_JWT_SECRET change-me-in-production JWT signing key — change this
EASM_JWT_ACCESS_TOKEN_TTL 15 Access token TTL (minutes)
EASM_JWT_REFRESH_TOKEN_TTL 7 Refresh token TTL (days)
EASM_LOG_LEVEL info debug/info/warn/error
EASM_TEST_MODE false Use mock scanner output instead of real binaries

Database migrations

Migrations run automatically on API startup via goose. Migration files are in backend/migrations/. To run manually:

cd backend
goose -dir migrations postgres "$EASM_DATABASE_DSN" up

API authentication

All protected endpoints require a Bearer token:

# Login
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"admin@example.com","password":"password"}'

# Use the access_token in subsequent requests
curl http://localhost:8080/api/v1/organizations \
  -H "Authorization: Bearer <access_token>"

Or use an API key:

curl http://localhost:8080/api/v1/organizations \
  -H "Authorization: Bearer easm_<key>"