Skip to content

Setup & Usage Guide

Requirements

Tool Version
Docker 24+
Docker Compose plugin 2.20+
Git any recent version
Go (local dev only) 1.22+
Node.js (local dev only) 20+

The recommended deployment path is Docker Compose. The worker image installs the configured scanner binaries from backend/configs/config.yaml, so you do not need to install ProjectDiscovery tools on the host for normal Docker usage.

Repository Directory

Clone the repository and enter the project directory:

git clone <repository-url>
cd hx0110-EASM

All commands below assume the current working directory is the repository root: hx0110-EASM/.

Quick Start With Docker Compose

  1. Create a local environment file:
cp .env.example .env
  1. Start the platform:
./scripts/up.sh

The script loads .env, validates the worker count, and runs:

docker compose up -d --build --scale worker=$WORKER_REPLICAS

If WORKER_REPLICAS is missing, empty, invalid, or less than 1, the script uses 1 worker.

  1. Open the UI:
http://localhost:3000

Services exposed by the default Compose stack:

Service URL / address
Frontend http://localhost:3000
API http://localhost:8080
PostgreSQL localhost:5432
Redis localhost:6379
MinIO S3 API http://localhost:9000
MinIO Console http://localhost:9001

Worker Count

Set worker replicas in .env:

WORKER_REPLICAS=3

Then start or restart with:

./scripts/up.sh

Operational notes:

  • More workers allow multiple scan jobs to run in parallel.
  • Each worker runs plugin jobs and needs access to PostgreSQL, Redis, MinIO, and configured scanner binaries.
  • Keep worker count conservative on small hosts because scanners such as nuclei, nmap, katana, and screenshot collection can be CPU, memory, and network intensive.
  • You can also scale manually with docker compose up -d --scale worker=3, but scripts/up.sh is the preferred project command.

Test Mode

For scanner mock output, set this in .env:

TEST_MODE=true

Then run:

./scripts/up.sh

Docker Compose maps TEST_MODE into EASM_TEST_MODE for API and worker containers. Test mode is useful for development or demos because plugins return deterministic mock data instead of executing external scanner binaries.

For real scans, use:

TEST_MODE=false

Configuration Files

Main backend configuration lives in:

backend/configs/config.yaml

Important sections:

  • app.version: displayed by the app and Update Center.
  • storage: S3/MinIO artifact storage.
  • updates: GitHub release checks.
  • research: hxresearch mount paths.
  • scan_profiles: config-driven scan profile definitions.
  • tools: scanner binary installation configuration for workers.

After changing backend/configs/config.yaml, restart API and workers:

./scripts/up.sh

See Configuration for the full config reference.

First-Time Setup Flow

  1. Open http://localhost:3000.
  2. Complete the First Administrator Setup flow.
  3. Create an organization.
  4. Add scope, for example domain = example.com.
  5. Approve the scope as an admin.
  6. Go to Scans, choose an approved scope and scan profile, then start a scan.
  7. Watch scan jobs, assets, vulnerabilities, files, and exposure changes populate.
  8. Use Asset Graph, Assets, Vulnerabilities, Files, Changes, and Reports to review results.

After the first admin exists, later registrations are created as pending users until an admin approves them.

API Authentication

Protected endpoints require a Bearer token:

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

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>"