Skip to main content

Frequently Asked Questions

Common questions about ThreatWeaver organized by category. Click any question to expand the answer.

Setup & Installation​

What are the system requirements for local development?
  • Node.js 20+ (LTS recommended)
  • Docker with Docker Compose (for PostgreSQL)
  • Git for version control
  • macOS, Linux, or WSL (native Windows not officially supported)

RAM: 8GB minimum, 16GB recommended. The backend, frontend, and PostgreSQL container run simultaneously during local development.

How do I set up the local development environment?
  1. Clone the repository
  2. Start PostgreSQL: docker-compose up -d postgres
  3. Backend: cd backend && npm install && npm run dev (runs on port 4005)
  4. Frontend: cd frontend && npm install && npm run dev (runs on port 3005)

Important: Never run the frontend or backend inside Docker locally. Only PostgreSQL runs in a container. Redis is not required locally -- the cache degrades gracefully.

What are the default local credentials?
  • Email: admin@company.com
  • Password: Admin123@same!

These credentials are seeded during the local migration process (npm run migrate:local).

How do I reset the local database?
docker-compose down -v
docker-compose up -d postgres
cd backend && npm run migrate:local

The -v flag removes the Docker volume, wiping all data. The migration will recreate the schema and seed default data.

Scanning​

What types of scanning does ThreatWeaver support?

ThreatWeaver supports three scanning modes:

  • Black Box: No prior knowledge of the application. Scanner discovers endpoints, authentication, and vulnerabilities from scratch.
  • Gray Box: Scanner is provided with API documentation (OpenAPI/Swagger), authenticated credentials, and optionally test data hints.
  • White Box: Full information including source code context, known test data UUIDs, and internal documentation. Maximum detection accuracy.
How many scanner agents are there?

ThreatWeaver has 56+ specialized scanner agents organized across the 6-phase pipeline. These cover OWASP Top 10, business logic flaws (BOLA, BFLA, IDOR), injection attacks (SQL, NoSQL, Command, LDAP), authentication issues (JWT, OAuth, session), and more.

How do I scan targets on private networks?

Deploy a Docker Scan Agent (scan sensor) inside your private network. The agent connects to the ThreatWeaver backend via a secure WebSocket tunnel. All scan traffic flows through the agent, so the backend never needs direct access to your internal targets.

docker run -e SENSOR_TOKEN=<token> -e BACKEND_URL=<url> threatweaver/scan-sensor:latest
How long does a typical scan take?

Scan duration depends on the target size and scanning mode:

  • Small API (10-20 endpoints): 5-15 minutes
  • Medium Application (50-100 endpoints): 15-45 minutes
  • Large Application (200+ endpoints): 1-3 hours

White box scans with full test data tend to be faster because the scanner skips the discovery phase.

Authentication & Authorization​

Does ThreatWeaver support SSO/SAML?

Yes. ThreatWeaver supports SAML 2.0 for enterprise single sign-on. Configure your Identity Provider (IdP) with the ThreatWeaver SP metadata URL. Supported IdPs include Okta, Azure AD (Entra ID), OneLogin, and any SAML 2.0 compliant provider.

How does multi-tenancy work?

ThreatWeaver uses a schema-per-tenant isolation model. Each tenant gets a dedicated PostgreSQL schema. Every API request goes through JWT authentication followed by tenant middleware that sets the search_path to the correct schema. This ensures complete data isolation between tenants.

What RBAC roles are available?
  • Admin: Full access to all modules, user management, and system settings
  • Manager: Read/write access to modules, can create scans and manage findings
  • Analyst: Read access to findings and dashboards, can add comments and tags
  • Viewer: Read-only access to dashboards and reports

Custom roles can be configured through the Admin module.

Deployment​

Where is ThreatWeaver deployed?

The production deployment uses:

  • Vercel: React frontend (SPA) with global CDN
  • Render: Node.js backend API (Singapore region)
  • Supabase: Managed PostgreSQL database
  • Upstash: Managed Redis cache

The dev branch auto-deploys to production on every push.

Can I self-host ThreatWeaver?

ThreatWeaver is designed as a SaaS platform, but the Docker Scan Agent component can be deployed on-premises for scanning private networks. Full self-hosted deployments are available as part of the enterprise licensing model. Contact the team for details.

How do I test changes before deploying?
  1. Always work on the local branch
  2. Test your build: cd backend && rm -rf dist && npm run build && npm start
  3. Run tests: cd backend && npm test
  4. Get explicit approval before pushing to dev (triggers immediate deployment)
  5. Never push directly to main -- it is protected

Troubleshooting​

The frontend shows a blank page after login

This is usually caused by an authentication token issue. Try:

  1. Clear browser localStorage (localStorage.clear())
  2. Hard refresh (Cmd+Shift+R or Ctrl+Shift+R)
  3. Verify the backend is running and accessible
  4. Check the browser console for CORS or network errors
Database migrations fail with schema errors

Ensure you are running the correct migration script for your environment:

  • Local: npm run migrate:local
  • Dev: npm run migrate:dev
  • Production: npm run migrate:production

If migrations are out of sync, check npm run migrate:status to see which migrations have been applied. Never mix migration scripts across environments.

Scans are stuck in "Running" state

Check the following:

  1. Backend logs for scan orchestrator errors
  2. Database connectivity (is PostgreSQL reachable?)
  3. AI provider API keys (are they valid and have quota?)
  4. For Docker scan agents: verify the WebSocket connection is established

You can manually transition a stuck scan via the admin API or by updating the assessment status in the database.

Redis connection errors in local development

Redis is not required for local development. The application is designed to degrade gracefully without Redis. If you see Redis connection warnings in the logs, they are informational only and do not affect functionality. To suppress them, ensure REDIS_URL is not set in your local .env file.