[pull] master from kevoreilly:master

.github/workflows/python-package.yml

@@ -48,6 +48,14 @@ jobs:
       - name: Run unit tests
         run: poetry run python -m pytest --import-mode=append
 
+      # The web/ Django suites (tenant-isolation, apiv2, guac, submission, ...) live
+      # outside testpaths=["tests","agent"], so the arg-less run above never collects
+      # them. They require importlib (append raises ImportPathMismatchError under
+      # pythonpath=web); DJANGO_SETTINGS_MODULE + pythonpath come from pyproject's
+      # [tool.pytest.ini_options] and still apply with an explicit path arg.
+      - name: Run web unit tests
+        run: poetry run python -m pytest web/ --import-mode=importlib
+
       - name: Run Linux analyzer unit tests
         run: poetry --project . --directory "analyzer/linux" run python -m pytest -v
 

conf/default/api.conf.default

@@ -14,6 +14,16 @@ url = http://example.tld
 token_auth_enabled = no
 mcp = no
 
+# Central-mode interactive live-VM (Guacamole) machine-to-machine auth. The central node
+# (lib/cuckoo/common/central_guac) presents this shared secret as "Authorization: Token <v>"
+# to the worker's apiv2 tasks/machine endpoint; that endpoint authorizes its (non-tenant-scoped,
+# VM-label-ONLY) read via a constant-time compare against this value, so interactive attach works
+# even when token_auth_enabled=no (DRF AllowAny leaves the request anonymous). EMPTY (the default)
+# = DISABLED: the endpoint then authorizes only via the viewer_for().is_local_admin gate. This is
+# a bearer secret -- keep apiv2 SG-locked to the control plane and the conf file non-world-readable;
+# rotate on suspicion. Leak scope is a pool VM label, never tenant/analysis data.
+control_plane_token =
+
 [list_exitnodes]
 enabled = no
 mcp = no

conf/default/cuckoo.conf.default

@@ -251,6 +251,13 @@ unused_files_in_mongodb = no
 # Central control-plane mode (off = current single-node behavior; analyses stay on the local
 # storage/analyses tree). When on, analysis artifacts are pushed to a shared object store and
 # interactive Guac routing resolves job->worker via a directory backend.
+#
+# TENANT ISOLATION: when central mode AND multitenancy are BOTH enabled, tenant-isolated access
+# requires the submit-bridge -- only a bridged task (job_id "ui-<central_id>", globally unique and
+# reconcile-mapped to a tenant) is a tenant-scoped own doc. A direct worker submission (keyed
+# "local-<id>", worker-local info.id, no tenancy by construction) is SINGLE-TENANT only: it is not
+# addressable through the tenant-scoped own-doc read/write/delete paths. See
+# lib.cuckoo.common.central_mode.central_bridge_required.
 enabled = no
 # Artifact storage backend when central mode is ON: "s3" (any S3-compatible store — AWS S3, MinIO,
 # Ceph RGW — via boto3, which is an optional/lazy import: pip install boto3 to use it) or "local"
@@ -276,10 +283,56 @@ broker_api_token =
 broker_table =
 # Interactive-Guac worker access: how the central node reaches the worker that hosts a live task's
 # VM. Defaults match the standard CAPE deb layout; override for other topologies.
-# File holding the worker apiv2 Token (blank/absent => requests go unauthenticated).
+# File holding the token the central node presents to the worker's apiv2 for the interactive
+# live-VM lookup (apiv2 tasks/machine). The worker authorizes that call by matching this value
+# (constant-time) against its own [api] control_plane_token, so this MUST equal the worker's
+# control_plane_token (in the AWS deploy: the same Secrets Manager value on both tiers). That
+# shared-secret path works on the shipped token_auth_enabled=no worker, where DRF leaves the
+# request anonymous. (On a token_auth_enabled=yes worker the endpoint ALSO accepts an
+# is_local_admin principal's token — but do NOT flip local_admins_manage_all_tenants=yes just
+# for this: that widens cross-tenant break-glass fleet-wide. Use an IdP-linked superuser
+# instead if you go that route.) Blank/absent => requests go unauthenticated.
 worker_api_token_file = /etc/cape/api-token
 # The worker's apiv2/web port.
 worker_api_port = 8000
 # The central node's libvirt-over-SSH identity onto workers (must be authorized on the workers).
 worker_ssh_user = cape
 worker_ssh_keyfile = /home/cape/.ssh/id_ed25519
+# SQLAlchemy URL of the CENTRAL control-plane RDS, used by WORKERS only to resolve a central task's
+# tenancy (tenant_id/user_id/visibility) when stamping the shared DocumentDB analysis doc under
+# multitenancy. A worker's own [database] is its LOCAL per-worker task DB (different id space) and
+# centralstore rewrites info.id to the central task id, so the stamp must be resolved here. Blank
+# (default) => central-mode analyses stamp fail-closed (private/unowned) rather than leak.
+# IMPORTANT: point this at the WRITER/PRIMARY endpoint (the same Postgres the central node uses as
+# its [database]), NOT a read replica/standby. Read-only credentials on the primary are fine, but a
+# reader endpoint breaks the reconcile's cross-node advisory-lock serialization (pg_advisory_lock on
+# a standby doesn't exclude the primary) and the under-lock re-read would be replication-lag-stale;
+# the worker detects pg_is_in_recovery() and warns + runs unserialized-but-fail-closed in that case.
+# Set on workers in a central + multitenancy deployment. Single-node and non-MT installs ignore this.
+central_database_url =
+# Management/UI node opt-in. A central UI node advertises the fleet's route options on the submission
+# form but runs NO rooter (only workers route traffic). When yes, init_rooter/init_routing tolerate an
+# unreachable rooter (warn + skip route verification/NAT while still populating the VPN list for the
+# form) instead of raising CuckooStartupError at web import. Default no, so single-node AND workers
+# keep failing fast on a missing rooter. Set yes ONLY on the central UI node, never on a worker.
+tolerate_missing_rooter = no
+
+[multitenancy]
+# Multi-tenant identity & job-visibility (off = current single-tenant behavior).
+# IMPORTANT: enabling this on an EXISTING populated install stamps NEW analyses only.
+# Pre-existing mongo reports have no tenant/visibility stamp and stay invisible to
+# every tenant (fail-closed) on the search/statistics/compare surfaces until you run
+# the one-shot backfill: `python utils/db_migration/mongo_backfill_tenant.py`
+# (stamps tenant_id/user_id/visibility from each report's Postgres task). See
+# docs/MULTITENANCY-SUPPORT.md.
+enabled = no
+# shared = tenant-less collaborative pool (submit default public);
+# locked = per-tenant isolation (submit default tenant).
+mode = shared
+# Blank = per-mode default (shared->public, locked->tenant). Override with one
+# of: public | tenant | private.
+default_visibility =
+# Operator break-glass: local Django superusers manage ALL tenants (cross-tenant
+# read + management) when yes. Set no to force admin access through the IdP.
+# Server-side only — a tenant/user cannot grant themselves this.
+local_admins_manage_all_tenants = yes

conf/default/reporting.conf.default

@@ -236,3 +236,12 @@ enabled = no
 # MUST be done in conf/gcp.conf. This section only controls the enabled state.
 enabled = no
 
+# Central mode: ship the analysis tree to shared object storage (S3/compatible or a
+# shared mount) and stamp the central job_id onto the report. This module is a
+# PREREQUISITE for central mode -- with it disabled, [central_mode] is non-functional
+# (no artifacts uploaded, info.job_id never stamped, info.id never rewritten to the
+# central task id, and the visibility reconcile has no job_id to key on). Storage
+# targets are configured under [central_mode] in conf/cuckoo.conf. Leave disabled on a
+# standard single-node install.
+[centralstore]
+enabled = no

docs/MULTITENANCY-SUPPORT.md

@@ -0,0 +1,108 @@
+# Multitenancy — Supported Configurations & Boundaries
+
+Multitenancy (the `[multitenancy]` section of `cuckoo.conf`) scopes every read
+surface so a user of one tenant cannot see or act on another tenant's tasks,
+samples, reports, artifacts, statistics, search results, or live-VM (Guacamole)
+sessions. This document states exactly which deployment modes that guarantee
+covers today, and what is intentionally **fail-closed** (safe but limited) until
+support is added.
+
+## Enabling on an existing (populated) install — run the backfill
+
+Turning `enabled = yes` stamps tenant/visibility onto **new** analyses only. Reports
+already in MongoDB have no `info.tenant_id` / `info.user_id` / `info.visibility`
+stamp, so the scoped search / statistics / compare surfaces treat them as
+**fail-closed / invisible** to every tenant (no leak, but the history disappears
+from those views) until they are stamped. Run the one-shot backfill once, after
+flipping the flag:
+
+```
+python utils/db_migration/mongo_backfill_tenant.py
+```
+
+It reads each selected `analysis` doc's Postgres task and writes
+`info.tenant_id` / `info.user_id` / `info.visibility` (orphans whose task was pruned
+fail closed to `private`), and creates the `tenant_scope_idx` index. It touches only
+(a) un-stamped docs (missing `info.visibility`, first-enable) and (b) crash-orphans in
+the exact reporter fail-closed shape (`visibility=private` + null `tenant_id` AND
+`user_id`) — never a stamped permissive doc — so it stays idempotent and safe to re-run.
+In a **central** deployment run it on the CENTRAL node **while quiesced**: it only
+restamps docs whose id space matches the node (broker `ui-*` ids ⇔ central RDS;
+worker-local ids ⇔ single-node), and it is not lock-serialized against a live toggle.
+The Alembic migration backfills the **SQL** columns only — the mongo stamp is this
+separate step. A fresh install needs no backfill (every report is stamped at
+creation).
+
+## Supported (isolation enforced end-to-end)
+
+- **Report store: MongoDB.** MT scoping of the aggregate/search/statistics/
+  compare surfaces reads the tenant stamp (`info.tenant_id` / `info.user_id` /
+  `info.visibility`) written into the mongo analysis document. **MongoDB is
+  required for multitenancy.**
+- **Single-node CAPE** (one host running web + processing + analysis).
+- **Central control plane + broker workers** (the "central mode" path): the
+  central UI serves artifacts staged from workers, keyed by the broker `job_id`.
+  Tenant stamping works across this path **only when workers can resolve the
+  submitter's tenancy from the central control-plane DB**: a worker's own
+  `[database]` is its LOCAL per-worker task DB (a different id space), and
+  `centralstore` rewrites `info.id` to the CENTRAL task id, so the worker resolves
+  and stamps tenancy against the central RDS via `[central_mode] central_database_url`.
+  If that URL is unset, central-mode analyses stamp **fail-closed** (private / unowned
+  — invisible to everyone but break-glass), never leaked. Point `central_database_url`
+  at the **writer/primary** endpoint (the same Postgres the central node uses as its
+  `[database]`), NOT a read replica: the worker's post-write reconcile takes its
+  per-task advisory lock there to serialize with the central node's visibility toggle
+  (advisory locks are cluster-wide, so same-key locks on the same primary mutually
+  exclude). If it points at a standby, `pg_advisory_lock` wouldn't exclude the primary
+  and the re-read would be replication-lag stale — the worker detects
+  `pg_is_in_recovery()`, warns, and runs unserialized-but-fail-closed, leaving a narrow
+  reprocess-during-toggle re-widen window (still no persistent leak: the fail-closed
+  insert + backfill keep it safe).
+- **Guacamole interactive sessions** for task-backed analyses: minting a live-VM
+  session (and the WebSocket tunnel re-check) is gated by `can_manage_task`
+  (owner / tenant-admin / break-glass), NOT mere read visibility — live keyboard/
+  mouse/framebuffer control is a task action, so a read-only viewer of a public/
+  tenant task cannot tunnel into another user's or tenant's VM.
+
+## Not yet supported (fail-closed — safe, but limited)
+
+These modes do **not** carry tenant context correctly. Rather than leak, MT
+**fails closed** on them (data is stamped private / invisible, or the surface is
+admin-only), so enabling MT on these modes is safe but the affected analyses
+will simply not be visible. Adding real support is tracked as future work.
+
+- **Elasticsearch report store.** The visibility toggle syncs the tenant stamp
+  only to MongoDB; an ES-backed install would not update the ES stamp, and the ES
+  statistics aggregates cannot be per-record gated. **Run MT with MongoDB.** (An
+  ES bool-filter analogue of the scope predicate exists but is unexercised.)
+- **Legacy distributed (`utils/dist.py`).** The main→worker submission does not
+  forward tenant/user/visibility, so a distributed worker cannot stamp the shared
+  mongo document correctly. When a worker processes a distributed task
+  (`options.main_task_id` set), the report is stamped **private/invisible**
+  (fail-closed) instead of world-visible. Use the broker/central path for
+  distributed multitenant analysis. (Our central path keys by `job_id` and never
+  sets `main_task_id`, so it is unaffected.)
+
+## Behavior notes
+
+- **Statistics API shape (shared mode).** With MT enabled in `shared` mode, the
+  `apiv2` statistics endpoint returns **per-scope** results
+  (`data['public']`, `data['tenant']`, `data['mine']`) instead of the legacy flat
+  `data['signatures']`. This is the correct scoped behavior; it is a breaking
+  change for API clients that assumed the flat shape on an MT-shared install.
+  Multitenancy-disabled installs and break-glass local-admins still receive the
+  flat dict.
+- **Direct VNC / VM operator console.** The task-less direct-console endpoints
+  (`task_id=0`: raw host:port VNC, plus VM console/start/shutdown/route/snapshot
+  by name) have no tenant scoping and mint sessions the per-task tunnel gate does
+  not cover, so **all** of them are restricted to break-glass admins
+  (`viewer_for(user).is_local_admin`) in addition to the existing config gate —
+  never a tenant user. (On an MT-disabled / no-auth install every principal is a
+  local-admin, so the operator console stays usable.)
+- **Threat-hunt facets.** `hunt()` scopes its aggregation by the viewer's entitled
+  scopes (`viewer_scope` `$match`); its facet `task_ids` rely on that stamp-based
+  `$match` with no per-id SQL backstop (a `$facet` count can't be post-filtered
+  per task). This is safe because the report tenant stamp is written fail-closed
+  on every path, so a doc can't carry a spoofed cross-tenant stamp.
+- **Modes:** `shared` (public pool + own tenant + own tasks) and `locked`
+  (tenant-isolated). An unknown/typo `mode` fails closed to `locked`.