RBAC (Role-Based Access Control)

RBAC adds role-based access control to Hugin’s API for multi-user serve mode. When you run hugin serve for a team, RBAC controls who can do what — view flows, run scans, modify scope, manage users, export data.

Single-user hugin start doesn’t need RBAC; the API has no auth (or a single static token) and you have full control.

🔗Architecture

HTTP request
  ├── Bearer token (hgn_*)
  │     └── lookup in token table → user_id
  │           └── user.role
  │                 └── role.permissions
  │                       └── allow / deny endpoint
  └── Audit log entry (always, success or denial)

Every authenticated API request resolves to a user, looks up their role, checks the role’s permissions against the endpoint’s required permission, and writes an audit log entry.

🔗Built-in Roles

Three default roles cover the common cases:

🔗admin

All permissions. The first user created on a serve instance is automatically admin.

🔗analyst

Day-to-day testing role:

  • view_flows — read captured flows
  • modify_flows — flag, annotate, tag
  • run_scans — trigger scanner / intruder / ratrace
  • manage_scope — edit scope
  • export_data — export flows / findings
  • run_intruder — start Intruder attacks
  • use_repeater — send through Repeater
  • view_findings / create / update findings
  • manage_projects — create / update projects
  • access_mcp — invoke MCP tools

🔗readonly

View-only role for stakeholders:

  • view_flows
  • view_findings
  • export_data

🔗Permissions

The permission set:

  • view_flows
  • modify_flows
  • run_scans
  • manage_scope
  • manage_users — admin-only by default; controls user/role CRUD
  • export_data
  • run_intruder
  • use_repeater
  • view_findings
  • manage_projects
  • configure_proxy — change proxy settings
  • access_mcp — invoke MCP tools (some tools have their own per-tool requirements)

🔗Custom Roles

rbac action:"create_role" name:"junior-analyst" permissions:["view_flows","view_findings","use_repeater"]

Custom roles can mix any subset of permissions. Built-in roles can’t be modified or deleted; custom roles can.

🔗User Management

rbac action:"list_users"           # all users
rbac action:"create_user" username:"alice" email:"alice@example.com" role:"analyst"
                                   # → returns API key (only shown once)
rbac action:"update_user" id:"<uuid>" role:"admin"
rbac action:"delete_user" id:"<uuid>"
rbac action:"get_user" id:"<uuid>"

API keys (hgn_* tokens) are bound to users — when a user is created, an API key is generated and shown once. The user is then expected to use that key as a Bearer token for all API requests.

To rotate: delete and re-create the user (or create a new user and migrate).

🔗Audit Log

Every authenticated API call (and every denial) is logged:

  • timestamp
  • user_id + username
  • action — e.g., scope.update, findings.delete, mcp.invoke:scanner
  • resource — what the action targeted (flow ID, scope pattern, etc.)
  • details — request params (sanitised, no payloads)
  • ip_address
  • outcome — success / denied (with reason)
rbac action:"audit_log" limit:100 user_id:"<uuid>" action_filter:"scope.*"

Audit log retention defaults to 90 days. Configurable via [rbac].audit_retention_days in config.toml.

🔗Manual Action Logging

log_action lets you push custom audit entries — useful when scripts perform multi-step operations and you want them attributed:

rbac action:"log_action" log_action:"bulk-delete" resource:"old findings" details:'{"count":42}'

🔗Setup Workflow

  1. Start serve mode: hugin serve --port 8080 --api-port 8081
  2. First user is auto-created as admin; the API key is printed to stdout (capture it!)
  3. Use the admin key to create per-team-member users with appropriate roles
  4. Distribute keys via secure channels (Signal, password manager)
  5. Review audit log regularly via rbac action:"audit_log"

🔗Permission Check Helper

rbac action:"check_permission" user_id:"<uuid>" permission:"run_scans" returns whether that user has the permission. Useful for tooling that needs to gate UI before making the API call.

🔗Combined with Token Auth

RBAC sits on top of the existing token auth (see Authentication):

  • The token resolves to a user
  • The user’s role’s permissions gate access

Static auth_token from [api] config bypasses RBAC entirely (treated as admin). This is intentional for backwards compatibility but should be disabled in multi-user deployments — set auth_token = "" and force everyone through hgn_* keys.

🔗MCP

The rbac MCP tool exposes the full surface:

  • Users: list_users, get_user, create_user, update_user, delete_user
  • Roles: list_roles, create_role, delete_role
  • Permissions: check_permission
  • Audit: audit_log, log_action

Pro license required for multi-user / RBAC features.