Projects & Multi-Tenancy

Overview

Vigolium supports project-based data isolation. Every scan record, finding, scope rule, source repo, and OAST interaction is tagged with a project_uuid, so multiple engagements can share the same database without data leaking across boundaries.

Concept	Meaning
Project	A named container for all scan data. Has a UUID, name, description, optional access-control lists, and an optional per-project config overlay.
Default project	A built-in project (`00000000-0000-0000-0000-000000000001`) created during `vigolium init`. All data belongs to it unless you specify otherwise.
Project config	An optional YAML overlay at `~/.vigolium/projects/<uuid>/config.yaml` that merges on top of the global config.
Access control	`allowed_domains` (email-domain patterns like `@acme.com`) and `allowed_emails` (exact addresses) that gate who can access the project. See Access Control.

Managing Projects from the CLI

The vigolium project subcommand creates and manages projects.

Create a project

vigolium project create my-engagement
# Created project my-engagement
#   UUID: a1b2c3d4-...
#   Config: ~/.vigolium/projects/a1b2c3d4-.../config.yaml

# With a description
vigolium project create client-app --description "Q1 2026 pentest for client-app"

List projects

vigolium project list
# or
vigolium project ls

The active project is marked with *.

Set the active project

eval $(vigolium project use a1b2c3d4-...)
# Active project: my-engagement (a1b2c3d4-...)

This exports the VIGOLIUM_PROJECT_UUID environment variable into your shell, so every subsequent command in that shell uses this project.

View the project config path

vigolium project config
# or for a specific project
vigolium project config a1b2c3d4-...

Manage project access

# Add allowed domains and emails (auto-detected by format)
vigolium project allow a1b2c3d4-... @acme.com @partner.io [email protected]
# ✓ Added 2 domain(s) and 1 email(s) to project my-engagement

# @-prefixed values go to domains, the rest to emails
vigolium project allow a1b2c3d4-... @newdomain.io [email protected]

# Remove entries from both lists
vigolium project remove-access a1b2c3d4-... @partner.io [email protected]

Delete a project

# Delete a project and everything tied to it (prompts for confirmation)
vigolium project delete a1b2c3d4-...
# 'rm' and 'remove' are aliases
vigolium project rm a1b2c3d4-...

# Skip the confirmation prompt
vigolium project delete a1b2c3d4-... -F

# Delete the project's data but keep its config directory on disk
vigolium project delete a1b2c3d4-... --keep-config -F

Deletion removes all scan data scoped to the project (scans, HTTP records, findings, scopes, OAST interactions). By default the project’s config directory (~/.vigolium/projects/<uuid>/) is removed too; --keep-config leaves it in place.

Set VIGOLIUM_PROJECT_READONLY=true to disable all mutating project commands (create, allow, remove-access) from the CLI. Read-only commands (list, use, config) still work. Useful in production or shared environments where projects should only be managed through the REST API.

Scoping Operations to a Project

Several mechanisms select the active project, listed by precedence (highest first):

Method	Example
`--project-uuid` flag	`vigolium scan -t https://example.com --project-uuid a1b2c3d4-...`
`--project-name` flag	`vigolium scan -t https://example.com --project-name my-engagement`
`VIGOLIUM_PROJECT_UUID` env var	`export VIGOLIUM_PROJECT_UUID=a1b2c3d4-...`
`VIGOLIUM_PROJECT` env var (legacy)	`export VIGOLIUM_PROJECT=a1b2c3d4-...`
Default project	Used when no flag or env var is set

--project-uuid and --project-name are mutually exclusive (--project-name must match exactly one project).

CLI examples

# Scan within a project (by UUID or by name)
vigolium scan -t https://example.com --project-uuid a1b2c3d4-...
vigolium scan -t https://example.com --project-name my-engagement

# Ingest into a project
vigolium ingest --input urls.txt --project-uuid a1b2c3d4-...

# Query and export project data
vigolium finding list --project-name my-engagement
vigolium db export --project-uuid a1b2c3d4-... -o findings.jsonl

Server API

When using the REST API, set the X-Project-UUID header to scope all operations to a project:

curl -X POST http://localhost:9002/api/ingest-http \
  -H "Authorization: Bearer my-secret-key" \
  -H "X-Project-UUID: a1b2c3d4-..." \
  -H "Content-Type: application/json" \
  -d '{"input_mode": "url", "content": "https://example.com"}'

If the header is omitted, the default project is used. All queries (findings, HTTP records, stats, scans) return data scoped to that project.

Config Merge Strategy

Configuration is resolved in layers (later layers override earlier ones):

Built-in defaults
  → ~/.vigolium/vigolium-configs.yaml          (global config)
    → ~/.vigolium/projects/<uuid>/config.yaml  (project config overlay)
      → --scanning-profile flag                (scanning profile)
        → CLI flags                            (highest precedence)

The project config file uses the same partial-YAML format as scanning profiles — only the fields you specify are overridden:

# ~/.vigolium/projects/a1b2c3d4-.../config.yaml
scope:
  hosts:
    - "*.example.com"

scanning_pace:
  concurrency: 30
  rate_limit: 50

dynamic-assessment:
  extensions:
    enabled: true
    variables:
      auth_token: "Bearer project-specific-token"

See Configuration for the full set of config sections.

Access Control

Projects can restrict access by email domain or exact email address using the allowed_domains and allowed_emails fields.

How it works

When a request includes both X-Project-UUID and X-User-Email headers, the server checks access in this order:

If allowed_emails is non-empty → the user’s email must match exactly (case-insensitive).
Otherwise, if allowed_domains is non-empty → the user’s email domain (e.g. @acme.com) must match.
If both lists are empty → the project is open to anyone.
If X-User-Email is not sent → the check is skipped entirely.

Denied requests receive a 403 Forbidden response.

Managing via API

# Set access lists on create
curl -X POST http://localhost:9002/api/projects \
  -H "Content-Type: application/json" \
  -d '{"name":"restricted","allowed_domains":["@acme.com"],"allowed_emails":["[email protected]"]}'

# Update access lists
curl -X PUT http://localhost:9002/api/projects/a1b2c3d4-... \
  -H "Content-Type: application/json" \
  -d '{"allowed_domains":["@acme.com","@partner.io"]}'

# Clear restrictions (project becomes open)
curl -X PUT http://localhost:9002/api/projects/a1b2c3d4-... \
  -H "Content-Type: application/json" \
  -d '{"allowed_domains":[],"allowed_emails":[]}'

# Domain-to-project mapping (for frontend middleware)
curl http://localhost:9002/api/projects/domain-map

See the Projects API for the full endpoint reference.

Database Isolation

All major data tables carry a project_uuid column and are filtered by the active project across the CLI, server API, and internal pipeline: scans · http_records · findings · scopes · source_repos · oast_interactions · scan_logs Existing databases are migrated automatically — the project_uuid column is added with the default project UUID as its default value, so pre-project data stays accessible under the default project.

Getting Started

Native Scan

Agentic Scan

Architecture

Native Scanning Phases

Server Mode

Customization

Others

Overview

Managing Projects from the CLI

Create a project

List projects

Set the active project

View the project config path

Manage project access

Delete a project

Scoping Operations to a Project

CLI examples

Server API

Config Merge Strategy

Access Control

How it works

Managing via API

Database Isolation

​Overview

​Managing Projects from the CLI

​Create a project

​List projects

​Set the active project

​View the project config path

​Manage project access

​Delete a project

​Scoping Operations to a Project

​CLI examples

​Server API

​Config Merge Strategy

​Access Control

​How it works

​Managing via API

​Database Isolation

Overview

Managing Projects from the CLI

Create a project

List projects

Set the active project

View the project config path

Manage project access

Delete a project

Scoping Operations to a Project

CLI examples

Server API

Config Merge Strategy

Access Control

How it works

Managing via API

Database Isolation