Onboarding Guide

Welcome to ThreatWeaver — an Enterprise Exposure Management Platform that combines continuous vulnerability management with an integrated AppSec scanner. ThreatWeaver syncs with Tenable.io to surface, prioritize, and track vulnerabilities across your assets, while its built-in scanner actively probes APIs and web applications for security weaknesses.

This guide is your complete path from zero to productive in ThreatWeaver, whether you are a developer, security analyst, product manager, or platform admin.

---

Pre-Requisites: Before Day 1

Get these sorted before you sit down to set up your local environment. Opening a ticket at 9am is better than blocking yourself at 9pm.

Accounts You Need

Account	Who to ask	Notes
GitHub access to BluCypher1/ThreatWeaver	Project owner (Tilak)	Needs read+write access to the repo
Render Dashboard access	Project owner	UAT environment management
Supabase access (optional)	Project owner	Only needed if working on production DB
Tenable.io sandbox credentials	Project owner	Only needed for Tenable sync work
Anthropic API key	Project owner	Only needed for AI/scanner work

Software to Install

Tool	Version	Install
Node.js	20+ (LTS)	https://nodejs.org or nvm install 20
npm	9+ (bundled with Node)	Included with Node.js
Docker Desktop	Latest	https://www.docker.com/products/docker-desktop
Git	Any recent	https://git-scm.com
VS Code (recommended)	Latest	https://code.visualstudio.com

Recommended VS Code extensions:

• ESLint
• Prettier
• TypeScript Hero
• Docker
• GitLens

---

Day 1 Checklist

Work through these steps in order. Each step depends on the previous one completing successfully.

Access and Clone

• Confirm you have GitHub access: open https://github.com/BluCypher1/ThreatWeaver in your browser
• Clone the repository:

  git clone git@github.com:BluCypher1/ThreatWeaver.git
  cd ThreatWeaver

• Switch to the working branch:

  git checkout local

  Always work on local. Never commit directly to dev or main.
• Verify you are on the right branch:

  git branch --show-current
  # Should output: local

Install Git Hooks (Required — takes 5 seconds)

ThreatWeaver has a pre-commit hook that automatically regenerates KB documentation whenever you commit backend source changes. You must install it once after cloning, otherwise documentation will drift out of sync with the code.

Option A — with npm (recommended, also installs all project deps):

npm install
# Runs "prepare": "husky" which installs the hook automatically

Option B — without npm (fastest, just configures the hook):

git config --local core.hooksPath .husky
# That's it. No Node or npm required.

Or run the included setup script:

bash setup.sh

Why this matters

Every time you commit a file under backend/src/, the hook detects which files changed and runs only the relevant doc generators (API collections, DB schema, RBAC matrix, etc.). The generated docs are automatically staged into your commit — you never need to think about it. If you skip this step, docs won't update and other devs get stale documentation.

Works on all branches

The hook fires on every commit regardless of branch — local, dev, main, or any feature branch. It never blocks a commit; doc gen failures are warnings only.

Docker Setup

• Install Docker Desktop and start it (the whale icon should appear in your menu bar)
• Verify Docker is running:

  docker --version
  docker-compose --version

• Start only the PostgreSQL container (never run docker-compose up without the service name):

  docker-compose up -d postgres

• Verify the container is healthy:

  docker-compose ps
  # Should show: postgres   Up (healthy)

Backend Setup

• Open a terminal in the project root and move to the backend:

  cd backend

• Install dependencies:

  npm install

• Copy the environment template:

  cp .env.example .env

  The defaults in .env.example work for local development without changes.
• Run database migrations (creates schema + seeds initial data):

  npm run migrate:local

  Expected output: [Migration] Running X pending migrations... Done. with no errors.
• Start the backend development server:

  npm run dev

  Expected output: Server running on port 4005 and Database connected.

Frontend Setup

• Open a second terminal (leave the backend running) and move to the frontend:

  cd frontend
  npm install
  npm run dev

  Expected output: VITE ready in Xs and a localhost URL.

Verification

• Open http://localhost:3005 in your browser
• Log in with the local admin credentials:
  • Email: admin@company.com
  • Password: Admin123@same!
• Confirm the dashboard loads without errors
• Open the Knowledge Base site at http://localhost:3010 (start it with cd kb-site && npm run start if not running)
• Read the module overview for the module you will be working on first (linked from the KB sidebar)

Quick Sanity Check

# Verify backend is responding
curl -s http://localhost:4005/health
# Expected: {"status":"healthy","database":"connected"}

# Verify frontend is up
curl -s http://localhost:3005 | head -5
# Expected: HTML content

---

Understanding the Codebase

ThreatWeaver is a monorepo with two completely independent modules. Do not mix work across them in a single commit.

The Two Modules

Module	Purpose	Entry points
Vulnerability Management Dashboard	Syncs with Tenable.io, manages assets, tracks vulnerabilities	frontend/src/pages/workspace/
AppSec Scanner	Actively scans APIs and web apps for vulnerabilities	backend/src/services/appsec/, backend/src/services/appsec/agents/

Backend Structure (backend/src/)

backend/src/
  config/
    database.ts          # TypeORM data source (connects to Docker Postgres locally)
    environment.ts       # env var validation and typed access
  entities/              # 133 TypeORM database models
    Asset.ts             # Core asset entity
    Vulnerability.ts     # Vulnerability records synced from Tenable
    Finding.ts           # AppSec scanner findings
    User.ts              # User accounts (multi-tenant aware)
    Tenant.ts            # Tenant model for multi-tenant isolation
    ...                  # 128 more entities
  middleware/
    auth.middleware.ts   # JWT verification, role enforcement
    tenant.middleware.ts # Per-request tenant isolation
    rateLimit.middleware.ts # Rate limiting by IP and user
  routes/                # 41 Express route modules
    assets.routes.ts     # Asset CRUD and Tenable sync
    vulnerabilities.routes.ts
    auth.routes.ts       # Login, logout, refresh, SSO
    scan.routes.ts       # AppSec scanner control
    admin.routes.ts      # Admin-only operations
    ...
  services/
    aggregation.service.ts   # CRITICAL: all KPI/trend calculation (~2936 lines)
    tenable.service.ts       # Tenable.io API integration
    appsec/
      agents/            # 59 scanner agent files (one per vulnerability class)
      orchestrator.service.ts
      findingValidator.service.ts
      findingDeduplicator.service.ts
  multi-tenant/
    tenantRepository.ts  # Tenant-aware DB operations
    tenantStorage.ts     # Per-request tenant context
  utils/
    urlSecurity.ts       # URL validation, SSRF prevention

Frontend Structure (frontend/src/)

frontend/src/
  pages/
    workspace/           # Module-level page containers
      Dashboard.tsx      # Main KPI dashboard
      Assets.tsx         # Asset inventory
      Vulnerabilities.tsx # Vulnerability list and detail
      AppSec.tsx         # Scanner control panel
      Admin.tsx          # Admin panel (superadmin only)
  components/
    Sidebar.tsx          # Main navigation
    charts/              # Recharts wrappers
    tables/              # Reusable data tables with sorting/filtering
    modals/              # Modal dialogs
  services/
    api.ts               # Axios instance with auth interceptors
    assets.service.ts    # Asset API calls
    vulnerabilities.service.ts
    scan.service.ts      # Scanner API calls
  store/
    authStore.ts         # Zustand: JWT, user profile, tenant
    uiStore.ts           # Zustand: sidebar state, theme
  hooks/
    useVulnerabilities.ts  # React Query hooks for data fetching
    useAssets.ts
    useAuth.ts

KB Site Structure (kb-site/)

kb-site/
  docs/                  # All documentation (Docusaurus Markdown)
    getting-started/     # This document + dev-setup, coding standards, etc.
    modules/             # Per-module documentation
    operations/          # Deployment, disaster recovery, runbooks
    technical-reference/ # API reference, schema, architecture
  sidebars.ts            # Navigation configuration (autogenerated)
  docusaurus.config.ts   # Site configuration

---

First Week Tasks by Role

Developer

Day 1-2:

1. Complete the Day 1 Checklist above
2. Read Coding Standards end-to-end
3. Read Git Workflow
4. Read CLAUDE.md (agent rules, applies to AI-assisted work)
5. Find one small bug or documentation gap and fix it as your first commit

Day 3-4:

1. Read the architecture doc for your assigned module
2. Trace one API request end-to-end: from frontend component → API call → route → service → DB → response
3. Add or improve one test

Day 5:

1. Run the full AppSec scanner against a test target (dvws-node or crAPI) if working on the scanner module
2. Review docs/audits/ISSUE_TRACKER.md to understand current open issues
3. Pick up your first real task from the issue tracker

Security Analyst

Day 1:

1. Complete the Day 1 Checklist
2. Log in to the local instance and explore every menu item
3. Read the AppSec Scanner Overview and Exposure Management Overview

Day 2-3:

1. Run a scan against a known-vulnerable target (crAPI, DVAPI, or dvws-node)
2. Review scan findings — understand TP, FP, FN concepts in context
3. Read docs/audits/ISSUE_TRACKER.md to understand what detection gaps exist

Day 4-5:

1. Read the ground truth documents in memory/ (dvws_node_ground_truth.md, verified_ground_truth_mar30.md)
2. Reproduce one known false positive and document your findings
3. Propose one detection improvement (even a simple heuristic)

Product Manager

Day 1:

1. Log in to both local and UAT environments
2. Read the Executive Summary and all module overviews
3. Review the Competitive Analysis documents

Day 2-3:

1. Walk through the Roadmap with the engineering team
2. Understand the scan result terminology (TP, FP, FN, GT coverage %)
3. Review current scan benchmarks in memory/session_apr5_r22_results.md

Platform Admin

Day 1:

1. Complete the Day 1 Checklist
2. Log in and explore Admin → Tenants, Admin → Users, Admin → Security
3. Read Deployment Guide
4. Read Disaster Recovery end-to-end

Day 2:

1. Understand the three migration scripts:
   • npm run migrate:local — local Docker DB
   • npm run migrate:dev — UAT/dev cloud DB
   • npm run migrate:production — production DB (requires approval)
2. Verify you can access Render Dashboard for the UAT environment
3. Confirm you can query the UAT DB via Render's PostgreSQL console

---

Key Things to Know Before Making Changes

aggregation.service.ts is CRITICAL

The file backend/src/services/aggregation.service.ts is approximately 2,936 lines and contains all KPI calculations, trend logic, and risk score aggregations that power the entire dashboard. Changes here affect every number a user sees.

Before touching this file:

1. Read the full function you are modifying, not just the lines around your change
2. Understand all callers of the function
3. Add a comment explaining what changed and why
4. Run the full test suite
5. Manually verify the KPIs before and after

Always Work on local Branch

# Verify before every work session
git branch --show-current
# Must be: local

If you accidentally committed to dev, stop immediately and ask the project owner before pushing. Pushing to dev triggers immediate deployment to the production-facing UAT environment.

Run Tests Before Committing

# Backend
cd backend && npm test

# Frontend
cd frontend && npm test

# Build check (catches TypeScript errors)
cd backend && rm -rf dist && npm run build

If tests are failing before your change, document which tests were already failing — do not let your PR introduce new failures.

Read CLAUDE.md for Agent-Specific Rules

If you are using Claude Code or any AI agent to assist with development, read /CLAUDE.md in the repo root. It contains rules about parallel execution, commit standards, and critical files. All AI-assisted work follows the same rules as manual work.

Never Push to main

main is protected by a pre-push Git hook. Attempting to push will fail. If you think a release to main is needed, discuss it with the project owner first.

Three Migration Scripts Must Always Stay in Sync

When you change a TypeORM entity (add/remove/rename a column or table), you must update all three migration scripts:

• backend/src/migrations/migrate-local.ts
• backend/src/migrations/migrate-dev.ts
• backend/src/migrations/migrate-production.ts

Forgetting one causes production deploys to fail or data to be wrong in specific environments.

---

Who to Ask for What

Area	Go to	Where
Architecture decisions	Project owner (Tilak)	Direct message
Product scope / requirements	Project owner	Direct message
DevOps / Render / Vercel	Project owner	Direct message
Security review	Security analyst on the team	Code review
Scanner false positive logic	docs/audits/ISSUE_TRACKER.md first, then project owner
Historical context	memory/ files in repo root	Git / KB
API documentation	KB site → Technical Reference → API Reference	localhost:3010

When asking for help, always include:

• What you expected to happen
• What actually happened
• The relevant logs or error message
• What you already tried

---

Glossary Quick-Reference

Term	Definition
TP (True Positive)	A finding that is a real vulnerability in the target
FP (False Positive)	A finding the scanner flagged as a vulnerability, but is not one
FN (False Negative)	A real vulnerability that the scanner missed
GT (Ground Truth)	The authoritative list of known vulnerabilities in a target used for benchmarking
Assessment	A configured scan run: target URL + scan type + auth profile + result set
Finding	A single potential vulnerability identified by the scanner
Tenant	An isolated customer workspace in the multi-tenant architecture
VFP (Vulnerability Fingerprint)	A hash used to deduplicate identical vulnerabilities across syncs
AppSec	Application Security — the scanner module (distinct from the VM dashboard)
BOLA / IDOR	Broken Object Level Authorization / Insecure Direct Object Reference — the most common API vulnerability class ThreatWeaver detects

---

Common Day-1 Mistakes

Running docker-compose up without specifying postgres

# WRONG — starts ALL services including backend/frontend in Docker
docker-compose up -d

# CORRECT — starts only PostgreSQL
docker-compose up -d postgres

Backend and frontend run natively on your machine, not in Docker. Running everything in Docker causes port conflicts and hot reload issues.

Working on the dev branch

# Check your branch first every single day
git branch --show-current

If you have uncommitted changes on dev, stash them and switch to local:

git stash
git checkout local
git stash pop

Running npm run migrate:dev or migrate:production locally

These connect to cloud databases. Running them locally by accident can corrupt the UAT or production database. Always verify which migrate script you are running:

# Safe — local Docker DB only
npm run migrate:local

# CAUTION — connects to cloud UAT DB
# npm run migrate:dev

# DANGER — connects to production DB — requires explicit approval
# npm run migrate:production

Not reading a file before editing it

TypeScript type errors and context mismatches are the most common cause of broken builds from AI-assisted edits. Always read the full relevant section of a file before proposing changes, especially for large services.

Committing to main accidentally

The pre-push hook will catch this, but to avoid the mental overhead:

# Add this to your .gitconfig aliases to see your branch in the prompt
# Or use oh-my-zsh which shows branch names automatically

Mixing AppSec and Dashboard changes in one commit

These are separate modules. A commit that fixes a scanner FP and also changes the vulnerability dashboard's KPI display is doing two unrelated things. Split them. Reviewers will thank you.

Skipping the build check before pushing

# Always do this before pushing
cd backend && rm -rf dist && npm run build

TypeScript errors that only show at compile time will break the Render deploy and block the entire team.

---

Setup Flow Summary

---

Common Commands Reference

Task	Command
Install git hooks (first time)	bash setup.sh or npm install at repo root
Start local DB	docker-compose up -d postgres
Stop local DB	docker-compose stop postgres
Run backend	cd backend && npm run dev
Run frontend	cd frontend && npm run dev
Run KB site	cd kb-site && npm run start
Run local migrations	cd backend && npm run migrate:local
DB shell	docker-compose exec -T postgres psql -U tenable -d tenable_dashboard
Check build	cd backend && rm -rf dist && npm run build
Run backend tests	cd backend && npm test
Run frontend tests	cd frontend && npm test
Check current branch	git branch --show-current
Check health	curl -s http://localhost:4005/health

---

Next Steps

After completing your Day 1 setup:

1. Read the Coding Standards to understand the code quality expectations
2. Read the Git Workflow for branching and PR procedures
3. Explore the Architecture Diagrams for a system-wide view
4. Review the Database Schema to understand the data model
5. Read the AppSec Scanner Overview if you are on the scanner team
6. Read the Exposure Management Overview if you are on the dashboard team