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 owner, 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.
Scoping	The `--project-uuid` / `--project-name` flags and the `VIGOLIUM_PROJECT_UUID` env var scope CLI operations; the `X-Project-UUID` header scopes server API operations.

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

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 the mutating project commands (create, delete) 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.

Scoping and the Projects API

A project is a data boundary, not an authentication boundary — Vigolium does not gate project access per user. Authentication is the server’s own API key / bearer token (see Authentication); anyone holding it can address any project. Run separate servers, or separate databases, when engagements must not share an operator.

Selecting the active project

Surface	How
CLI (one command)	`--project-uuid <uuid>` or `--project-name <name>`
CLI (a session)	`eval $(vigolium project use <uuid>)`, which exports `VIGOLIUM_PROJECT_UUID`
REST API	the `X-Project-UUID` request header

Omit all three and operations land in the default project.

Managing via API

# List projects
curl -s http://localhost:9002/api/projects -H "Authorization: Bearer $VIGOLIUM_API_KEY"

# Create (admin scope) — name is required; uuid/description/owner_uuid are optional
curl -X POST http://localhost:9002/api/projects \
  -H "Authorization: Bearer $VIGOLIUM_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"client-engagement","description":"Q3 external assessment"}'

# Read one project, or its aggregate stats
curl -s http://localhost:9002/api/projects/a1b2c3d4-... -H "Authorization: Bearer $VIGOLIUM_API_KEY"
curl -s http://localhost:9002/api/projects/a1b2c3d4-.../stats -H "Authorization: Bearer $VIGOLIUM_API_KEY"

# Update (admin scope) — name, description, owner_uuid
curl -X PUT http://localhost:9002/api/projects/a1b2c3d4-... \
  -H "Authorization: Bearer $VIGOLIUM_API_KEY" -H "Content-Type: application/json" \
  -d '{"description":"handed over to the blue team"}'

# Delete (admin scope) — removes the project and everything tied to it
curl -X DELETE http://localhost:9002/api/projects/a1b2c3d4-... -H "Authorization: Bearer $VIGOLIUM_API_KEY"

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

Delete a project

Scoping Operations to a Project

CLI examples

Server API

Config Merge Strategy

Scoping and the Projects API

Selecting the active project

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

​Delete a project

​Scoping Operations to a Project

​CLI examples

​Server API

​Config Merge Strategy

​Scoping and the Projects API

​Selecting the active project

​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

Delete a project

Scoping Operations to a Project

CLI examples

Server API

Config Merge Strategy

Scoping and the Projects API

Selecting the active project

Managing via API

Database Isolation