vehlo-code-scanner 0.1.1rc1__tar.gz

vehlo_code_scanner-0.1.1rc1/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environment
+.venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+.env.*
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Docker
+docker-compose.override.yml
+
+# Alembic
+alembic/versions/__pycache__/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Office documents (working files + Word lock files)
+*.docx
+~$*
+
+# MinIO data
+minio_data/
+
+# Dashboard
+dashboard/node_modules/
+dashboard/dist/
+
+# Local tooling caches
+.ash/
+.claude-fuel/
+
+# Local Claude context (deployment/operational notes — not public)
+CLAUDE.local.md

vehlo_code_scanner-0.1.1rc1/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: vehlo-code-scanner
+Version: 0.1.1rc1
+Summary: Multi-tenant security scanning platform wrapping Amazon Security Helper
+Project-URL: Homepage, https://github.com/Vehlo-CyberSec/vehlo-code-scanner
+Project-URL: Repository, https://github.com/Vehlo-CyberSec/vehlo-code-scanner
+Requires-Python: >=3.12
+Requires-Dist: alembic<2.0,>=1.13
+Requires-Dist: authlib<2.0,>=1.3
+Requires-Dist: boto3>=1.34
+Requires-Dist: celery<6.0,>=5.3
+Requires-Dist: fastapi<1.0,>=0.115
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: itsdangerous<3.0,>=2.1
+Requires-Dist: psycopg[binary]<4.0,>=3.1
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: redis<6.0,>=5.0
+Requires-Dist: rich<14.0,>=13.5
+Requires-Dist: sqlalchemy<3.0,>=2.0
+Requires-Dist: typer<1.0,>=0.16
+Requires-Dist: uvicorn[standard]<1.0,>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest-cov<6.0,>=5.0; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
+Provides-Extra: scan
+Requires-Dist: vehlo-ash<4,>=3.2.5; extra == 'scan'
+Description-Content-Type: text/markdown
+
+# Vehlo Code Scanner
+
+Multi-tenant security scanning platform wrapping [Amazon Security Helper (ASH)](https://github.com/awslabs/automated-security-helper). Runs ASH across Vehlo's 500+ repos, centralizes findings in PostgreSQL, and surfaces them through a React dashboard with triage workflows and analytics.
+
+## Architecture
+
+```
+CI/CD pipeline → ASH scan → vcs CLI (--push) → POST /api/v1/scans → FastAPI + PostgreSQL → React Dashboard
+```
+
+Three components:
+
+- **CLI / scanner** — Python package (`vcs`) that wraps ASH. Supports container, local, and pre-commit modes. Outputs rich terminal tables, optionally pushes results to the central API, and can fail the build on a severity threshold.
+- **API service** — FastAPI monolith handling ingest, findings lifecycle, and analytics. Backed by PostgreSQL. Auto-resolves findings when they disappear from subsequent scans.
+- **Dashboard** — React + Vite SPA. Overview, findings browser, per-repo drill-down, scan history, and analytics.
+
+## Quick Start
+
+```bash
+# Start all services
+docker compose up
+
+# API → http://localhost:8002
+# Dashboard → http://localhost:5175
+```
+
+### Installation
+
+Distribution is **dual-mode**: a public path (PyPI + ECR Public, no AWS
+account needed) and an AWS-gated path (CodeArtifact + private ECR) for
+internal users. The tool itself is open to install — the **API token** gates
+pushing results and **SSO** gates viewing them. The `[scan]` extra adds the
+ASH engine (`vehlo-ash`, a rename-only repackaging of AWS's Apache-2.0
+automated-security-helper — see `packaging/vehlo-ash/`); without it you still
+get the CLI, `--push`, and the client.
+
+**Public (no AWS):**
+
+```bash
+# pip from PyPI
+pip install 'vehlo-code-scanner[scan]'
+
+# Docker from ECR Public (ASH bundled, nothing else to install)
+docker run --rm -v "$PWD:/src" \
+  public.ecr.aws/<alias>/vehlo-code-scanner:latest scan /src
+```
+
+**AWS-gated (internal):** authenticate once with `aws sso login`, then:
+
+```bash
+# pip via CodeArtifact (configures the index, then installs)
+aws codeartifact login --tool pip \
+  --domain "$VCS_CA_DOMAIN" --repository "$VCS_CA_REPO"
+pip install 'vehlo-code-scanner[scan]'
+
+# Docker via ECR
+aws ecr get-login-password --region "$AWS_REGION" \
+  | docker login --username AWS --password-stdin "$ECR_REGISTRY"
+docker run --rm -v "$PWD:/src" \
+  "$ECR_REGISTRY/vehlo-code-scanner:latest" scan /src
+```
+
+**GitHub Actions** (the calling job needs `permissions: id-token: write`):
+
+```yaml
+- uses: Vehlo-CyberSec/vehlo-code-scanner@v1
+  with:
+    api-url: ${{ vars.VCS_API_URL }}
+    api-token: ${{ secrets.VCS_API_TOKEN }}
+    image: ${{ vars.VCS_ECR_IMAGE }}      # full ECR URI
+    aws-role: ${{ secrets.VCS_AWS_ROLE }} # OIDC role with ECR pull
+    aws-region: ${{ vars.AWS_REGION }}
+    fail-on: high
+```
+
+> ASH is git-only upstream (and its PyPI name is squatted), so `vcs scan`
+> without the engine prints install guidance. The container images bundle ASH;
+> pip users get it via the `[scan]` extra (`vehlo-ash` from PyPI or
+> CodeArtifact, depending on the index you install from).
+
+For local development from a checkout:
+
+```bash
+uv tool install '.[scan]'   # or: uv sync --group local-scan  (ASH from git)
+```
+
+After installation, `vcs` (and `vcs-admin`) are available on your PATH.
+
+### Local development
+
+```bash
+# Install Python deps
+uv sync
+
+# Apply migrations
+VCS_DATABASE_URL=postgresql+psycopg://vcs:<password>@localhost:5433/vcs alembic upgrade head
+# (dev password: see docker-compose.yml)
+
+# Run API
+VCS_DATABASE_URL=... uvicorn vcs.api.app:create_app --factory --reload
+
+# Run dashboard (in ./dashboard)
+npm run dev
+```
+
+### Running a scan
+
+```bash
+# Scan current directory and print results
+vcs scan .
+
+# Scan and push results to central API
+VCS_API_URL=http://localhost:8002 VCS_API_TOKEN=<token> vcs scan . --push
+
+# Fail CI if critical or high findings exist
+vcs scan . --push --fail-on high
+```
+
+## Project Structure
+
+```
+src/vcs/
+├── api/
+│   ├── routes/         # health, ingest, findings, repos, scans, overview, analytics
+│   ├── services/       # ingest logic, auto-resolve
+│   ├── app.py          # FastAPI factory
+│   ├── deps.py         # DB session injection
+│   └── schemas.py      # Pydantic request/response models
+├── models/             # SQLAlchemy ORM: org, group, user, repo, scan, finding, api_token
+├── scanner/            # ASH wrapper: runner, parser, result models
+├── cli/                # Typer CLI: scan command, rich output
+├── client/             # HTTP client for pushing results to API
+├── db.py               # Database connection factory
+├── enums.py            # Severity, FindingStatus, etc.
+└── config.py           # Settings from environment
+
+dashboard/src/
+├── pages/              # Overview, Findings, FindingDetail, Repos, RepoDetail, Scans, Analytics
+├── components/         # Layout, SeverityBadge, StatusBadge, Pagination, Panel, etc.
+├── api/                # TanStack Query hooks
+└── types.ts            # TypeScript types
+
+alembic/versions/       # Database migrations
+tests/                  # Unit + integration tests
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `VCS_DATABASE_URL` | PostgreSQL connection string | required |
+| `VCS_API_URL` | Central API base URL (CLI push) | required for `--push` |
+| `VCS_API_TOKEN` | Bearer token for API auth (CLI push) | required for `--push` |
+| `VCS_REDIS_URL` | Celery broker/result backend | `redis://localhost:6380/0` |
+| `VCS_S3_ENDPOINT` | S3/MinIO endpoint for raw-result archiving | `http://localhost:9002` |
+| `VCS_SESSION_SECRET` | Secret for signing dashboard session cookies | dev default (**required** once OIDC is configured — startup fails without it) |
+| `VCS_CORS_ORIGINS` | Comma-separated allowed CORS origins; empty value = deny cross-origin (prod) | unset → any localhost port (dev) |
+| `VCS_OIDC_ISSUER` | OIDC issuer URL (enables dashboard SSO) | unset → SSO disabled |
+| `VCS_OIDC_CLIENT_ID` / `VCS_OIDC_CLIENT_SECRET` | OIDC client credentials | unset |
+| `VCS_OIDC_REDIRECT_URI` | OIDC callback URL | `.../api/v1/auth/callback` |
+| `VCS_OIDC_GROUPS_CLAIM` | Claim holding the user's group names | `groups` |
+| `VCS_DASHBOARD_URL` | Post-login redirect target | `http://localhost:5175` |
+| `VCS_DEV_LOGIN` | **Dev only** — enables `/api/v1/auth/dev-login` (one-click local session, no IdP). Never set in prod. | unset → disabled |
+
+## Running Tests
+
+```bash
+pytest
+pytest --cov=vcs --cov-report=term-missing
+```

vehlo_code_scanner-0.1.1rc1/README.md

@@ -0,0 +1,170 @@
+# Vehlo Code Scanner
+
+Multi-tenant security scanning platform wrapping [Amazon Security Helper (ASH)](https://github.com/awslabs/automated-security-helper). Runs ASH across Vehlo's 500+ repos, centralizes findings in PostgreSQL, and surfaces them through a React dashboard with triage workflows and analytics.
+
+## Architecture
+
+```
+CI/CD pipeline → ASH scan → vcs CLI (--push) → POST /api/v1/scans → FastAPI + PostgreSQL → React Dashboard
+```
+
+Three components:
+
+- **CLI / scanner** — Python package (`vcs`) that wraps ASH. Supports container, local, and pre-commit modes. Outputs rich terminal tables, optionally pushes results to the central API, and can fail the build on a severity threshold.
+- **API service** — FastAPI monolith handling ingest, findings lifecycle, and analytics. Backed by PostgreSQL. Auto-resolves findings when they disappear from subsequent scans.
+- **Dashboard** — React + Vite SPA. Overview, findings browser, per-repo drill-down, scan history, and analytics.
+
+## Quick Start
+
+```bash
+# Start all services
+docker compose up
+
+# API → http://localhost:8002
+# Dashboard → http://localhost:5175
+```
+
+### Installation
+
+Distribution is **dual-mode**: a public path (PyPI + ECR Public, no AWS
+account needed) and an AWS-gated path (CodeArtifact + private ECR) for
+internal users. The tool itself is open to install — the **API token** gates
+pushing results and **SSO** gates viewing them. The `[scan]` extra adds the
+ASH engine (`vehlo-ash`, a rename-only repackaging of AWS's Apache-2.0
+automated-security-helper — see `packaging/vehlo-ash/`); without it you still
+get the CLI, `--push`, and the client.
+
+**Public (no AWS):**
+
+```bash
+# pip from PyPI
+pip install 'vehlo-code-scanner[scan]'
+
+# Docker from ECR Public (ASH bundled, nothing else to install)
+docker run --rm -v "$PWD:/src" \
+  public.ecr.aws/<alias>/vehlo-code-scanner:latest scan /src
+```
+
+**AWS-gated (internal):** authenticate once with `aws sso login`, then:
+
+```bash
+# pip via CodeArtifact (configures the index, then installs)
+aws codeartifact login --tool pip \
+  --domain "$VCS_CA_DOMAIN" --repository "$VCS_CA_REPO"
+pip install 'vehlo-code-scanner[scan]'
+
+# Docker via ECR
+aws ecr get-login-password --region "$AWS_REGION" \
+  | docker login --username AWS --password-stdin "$ECR_REGISTRY"
+docker run --rm -v "$PWD:/src" \
+  "$ECR_REGISTRY/vehlo-code-scanner:latest" scan /src
+```
+
+**GitHub Actions** (the calling job needs `permissions: id-token: write`):
+
+```yaml
+- uses: Vehlo-CyberSec/vehlo-code-scanner@v1
+  with:
+    api-url: ${{ vars.VCS_API_URL }}
+    api-token: ${{ secrets.VCS_API_TOKEN }}
+    image: ${{ vars.VCS_ECR_IMAGE }}      # full ECR URI
+    aws-role: ${{ secrets.VCS_AWS_ROLE }} # OIDC role with ECR pull
+    aws-region: ${{ vars.AWS_REGION }}
+    fail-on: high
+```
+
+> ASH is git-only upstream (and its PyPI name is squatted), so `vcs scan`
+> without the engine prints install guidance. The container images bundle ASH;
+> pip users get it via the `[scan]` extra (`vehlo-ash` from PyPI or
+> CodeArtifact, depending on the index you install from).
+
+For local development from a checkout:
+
+```bash
+uv tool install '.[scan]'   # or: uv sync --group local-scan  (ASH from git)
+```
+
+After installation, `vcs` (and `vcs-admin`) are available on your PATH.
+
+### Local development
+
+```bash
+# Install Python deps
+uv sync
+
+# Apply migrations
+VCS_DATABASE_URL=postgresql+psycopg://vcs:<password>@localhost:5433/vcs alembic upgrade head
+# (dev password: see docker-compose.yml)
+
+# Run API
+VCS_DATABASE_URL=... uvicorn vcs.api.app:create_app --factory --reload
+
+# Run dashboard (in ./dashboard)
+npm run dev
+```
+
+### Running a scan
+
+```bash
+# Scan current directory and print results
+vcs scan .
+
+# Scan and push results to central API
+VCS_API_URL=http://localhost:8002 VCS_API_TOKEN=<token> vcs scan . --push
+
+# Fail CI if critical or high findings exist
+vcs scan . --push --fail-on high
+```
+
+## Project Structure
+
+```
+src/vcs/
+├── api/
+│   ├── routes/         # health, ingest, findings, repos, scans, overview, analytics
+│   ├── services/       # ingest logic, auto-resolve
+│   ├── app.py          # FastAPI factory
+│   ├── deps.py         # DB session injection
+│   └── schemas.py      # Pydantic request/response models
+├── models/             # SQLAlchemy ORM: org, group, user, repo, scan, finding, api_token
+├── scanner/            # ASH wrapper: runner, parser, result models
+├── cli/                # Typer CLI: scan command, rich output
+├── client/             # HTTP client for pushing results to API
+├── db.py               # Database connection factory
+├── enums.py            # Severity, FindingStatus, etc.
+└── config.py           # Settings from environment
+
+dashboard/src/
+├── pages/              # Overview, Findings, FindingDetail, Repos, RepoDetail, Scans, Analytics
+├── components/         # Layout, SeverityBadge, StatusBadge, Pagination, Panel, etc.
+├── api/                # TanStack Query hooks
+└── types.ts            # TypeScript types
+
+alembic/versions/       # Database migrations
+tests/                  # Unit + integration tests
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `VCS_DATABASE_URL` | PostgreSQL connection string | required |
+| `VCS_API_URL` | Central API base URL (CLI push) | required for `--push` |
+| `VCS_API_TOKEN` | Bearer token for API auth (CLI push) | required for `--push` |
+| `VCS_REDIS_URL` | Celery broker/result backend | `redis://localhost:6380/0` |
+| `VCS_S3_ENDPOINT` | S3/MinIO endpoint for raw-result archiving | `http://localhost:9002` |
+| `VCS_SESSION_SECRET` | Secret for signing dashboard session cookies | dev default (**required** once OIDC is configured — startup fails without it) |
+| `VCS_CORS_ORIGINS` | Comma-separated allowed CORS origins; empty value = deny cross-origin (prod) | unset → any localhost port (dev) |
+| `VCS_OIDC_ISSUER` | OIDC issuer URL (enables dashboard SSO) | unset → SSO disabled |
+| `VCS_OIDC_CLIENT_ID` / `VCS_OIDC_CLIENT_SECRET` | OIDC client credentials | unset |
+| `VCS_OIDC_REDIRECT_URI` | OIDC callback URL | `.../api/v1/auth/callback` |
+| `VCS_OIDC_GROUPS_CLAIM` | Claim holding the user's group names | `groups` |
+| `VCS_DASHBOARD_URL` | Post-login redirect target | `http://localhost:5175` |
+| `VCS_DEV_LOGIN` | **Dev only** — enables `/api/v1/auth/dev-login` (one-click local session, no IdP). Never set in prod. | unset → disabled |
+
+## Running Tests
+
+```bash
+pytest
+pytest --cov=vcs --cov-report=term-missing
+```

vehlo_code_scanner-0.1.1rc1/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "vehlo-code-scanner"
+version = "0.1.1rc1"
+description = "Multi-tenant security scanning platform wrapping Amazon Security Helper"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "sqlalchemy>=2.0,<3.0",
+    "psycopg[binary]>=3.1,<4.0",
+    "alembic>=1.13,<2.0",
+    "typer>=0.16,<1.0",
+    "rich>=13.5,<14.0",
+    "httpx>=0.27,<1.0",
+    "fastapi>=0.115,<1.0",
+    "uvicorn[standard]>=0.30,<1.0",
+    "pydantic>=2.0,<3.0",
+    "celery>=5.3,<6.0",
+    "redis>=5.0,<6.0",
+    "boto3>=1.34",
+    "authlib>=1.3,<2.0",
+    "itsdangerous>=2.1,<3.0",
+]
+
+[project.optional-dependencies]
+scan = [
+    "vehlo-ash>=3.2.5,<4",
+]
+# NOTE: the published wheel also gets a `scan` extra (`vehlo-ash>=3.2.5,<4`),
+# injected by the release workflow at build time — see
+# .github/workflows/release.yml and packaging/vehlo-ash/README.md. It is not
+# declared here because vehlo-ash is published by that same release run, so
+# declaring it would make `uv lock` unsatisfiable in dev. Dev installs ASH via
+# the `local-scan` dependency-group below instead.
+dev = [
+    "pytest>=8.0,<9.0",
+    "pytest-cov>=5.0,<6.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Vehlo-CyberSec/vehlo-code-scanner"
+Repository = "https://github.com/Vehlo-CyberSec/vehlo-code-scanner"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vcs"]
+
+# Hatchling's sdist default is "everything not gitignored", which would
+# publish the whole repo (internal docs, CI config, dashboard sources, any
+# stray local files) to PyPI. Ship only what the package needs.
+[tool.hatch.build.targets.sdist]
+only-include = ["src/vcs", "README.md"]
+
+[project.scripts]
+vcs = "vcs.cli.app:app"
+vcs-admin = "vcs.cli.admin:app"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 80
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+# Dev-only ASH install, straight from AWS's git at a pinned commit. This group
+# is NOT part of published wheel metadata and is not installed by a plain
+# `pip install`, so the squatted PyPI name never reaches end users. The Docker
+# image bakes ASH via this group; published pip users get vehlo-ash instead.
+[dependency-groups]
+local-scan = [
+    "automated-security-helper>=3.0",
+]
+
+[tool.uv.sources]
+automated-security-helper = { git = "https://github.com/awslabs/automated-security-helper.git", rev = "968c5f8ce337499577f97e62afcf66c0a2bb9a84" }

vehlo_code_scanner-0.1.1rc1/src/vcs/__init__.py

@@ -0,0 +1 @@
+"""Vehlo Code Scanner — multi-tenant security scanning platform."""

vehlo_code_scanner-0.1.1rc1/src/vcs/api/__init__.py

@@ -0,0 +1 @@
+"""API module — FastAPI application and routes."""

vehlo_code_scanner-0.1.1rc1/src/vcs/api/app.py

@@ -0,0 +1,92 @@
+"""FastAPI application factory."""
+
+import os
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.middleware.sessions import SessionMiddleware
+
+from vcs.api.routes import (
+    analytics,
+    auth,
+    findings,
+    groups,
+    health,
+    ingest,
+    overview,
+    repos,
+    scans,
+    tokens,
+)
+from vcs.config import get_cors_origins, get_session_secret
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    app = FastAPI(
+        title="Vehlo Code Scanner API",
+        description="Central API for security scan result ingestion and findings management.",
+        version="0.1.0",
+    )
+    # SessionMiddleware holds transient OIDC state (CSRF/nonce) during the
+    # login handshake. The authenticated session is a separate signed cookie.
+    app.add_middleware(SessionMiddleware, secret_key=get_session_secret())
+    # CORS: explicit origins from VCS_CORS_ORIGINS when set (empty = deny all
+    # cross-origin — right for prod, where the SPA is same-origin). The
+    # any-localhost-port regex is a dev-only default; with credentials
+    # allowed it must not reach a real deployment.
+    origins = get_cors_origins()
+    cors_scope = (
+        {"allow_origins": origins}
+        if origins is not None
+        else {"allow_origin_regex": r"http://localhost:\d+"}
+    )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+        **cors_scope,
+    )
+    app.include_router(health.router)
+    app.include_router(auth.router)
+    app.include_router(tokens.router)
+    app.include_router(groups.router)
+    app.include_router(ingest.router)
+    app.include_router(findings.router)
+    app.include_router(overview.router)
+    app.include_router(repos.router)
+    app.include_router(scans.router)
+    app.include_router(analytics.router)
+    _mount_dashboard(app)
+    return app
+
+
+def _mount_dashboard(app: FastAPI) -> None:
+    """Serve the built dashboard SPA from the API when bundled.
+
+    Active only when VCS_DASHBOARD_DIR points at a build (so tests/local
+    are unaffected). API routes are registered first and take precedence;
+    the catch-all serves real files, else index.html for client-side routes.
+    """
+    dist = os.environ.get("VCS_DASHBOARD_DIR")
+    if not dist:
+        return
+    root = Path(dist)
+    index = root / "index.html"
+    if not index.is_file():
+        return
+    if (root / "assets").is_dir():
+        app.mount(
+            "/assets", StaticFiles(directory=root / "assets"), name="assets"
+        )
+
+    @app.get("/{full_path:path}", include_in_schema=False)
+    def spa(full_path: str) -> FileResponse:
+        candidate = root / full_path
+        if full_path and candidate.is_file():
+            return FileResponse(candidate)
+        return FileResponse(index)

vehlo_code_scanner-0.1.1rc1/src/vcs/api/auth.py

@@ -0,0 +1,95 @@
+"""Authentication principal and the global tenant-isolation safety net.
+
+A single ``AuthPrincipal`` represents whoever is making a request — a machine
+token (exactly one group) or, later, a human SSO session (their group
+memberships). Every isolation rule is expressed once against
+``accessible_group_ids`` so both auth modes share the same enforcement.
+
+The isolation itself is a SQLAlchemy ``do_orm_execute`` listener: any session
+whose ``info`` carries ``accessible_group_ids`` automatically has a
+group-scoped predicate injected into every SELECT of ``Repo``/``Finding``/
+``Scan``. This is a safety net — a forgotten ``.filter()`` in a route cannot
+leak another group's data, because the predicate is applied at the session
+layer, not by the route.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass
+
+from sqlalchemy import event, select
+from sqlalchemy.orm import Session, with_loader_criteria
+
+SCOPE_KEY = "accessible_group_ids"
+
+
+@dataclass(frozen=True)
+class AuthPrincipal:
+    """The authenticated caller and the groups they may access."""
+
+    kind: str  # "token" | "user"
+    org_id: uuid.UUID
+    group_ids: frozenset[uuid.UUID]
+    token_id: uuid.UUID | None = None
+    user_id: uuid.UUID | None = None
+
+    @property
+    def accessible_group_ids(self) -> frozenset[uuid.UUID]:
+        return self.group_ids
+
+    @property
+    def primary_group_id(self) -> uuid.UUID:
+        """The single group a write (ingest) is attributed to.
+
+        Tokens are scoped to exactly one group. Raising here surfaces a
+        misuse (e.g. attributing a write to a multi-group user session)
+        rather than silently picking one.
+        """
+        if len(self.group_ids) != 1:
+            raise ValueError(
+                "primary_group_id requires exactly one accessible group"
+            )
+        return next(iter(self.group_ids))
+
+
+def scope_session(session: Session, group_ids: frozenset[uuid.UUID]) -> None:
+    """Bind a session to a principal's accessible groups for the request."""
+    session.info[SCOPE_KEY] = group_ids
+
+
+@event.listens_for(Session, "do_orm_execute")
+def _apply_group_scope(execute_state) -> None:
+    """Inject a group-scoped predicate on every scoped SELECT.
+
+    Skips relationship/column loads so navigating ``finding.repo`` and
+    similar lazy loads still work; only top-level entity SELECTs are filtered.
+    """
+    if (
+        not execute_state.is_select
+        or execute_state.is_column_load
+        or execute_state.is_relationship_load
+    ):
+        return
+
+    group_ids = execute_state.session.info.get(SCOPE_KEY)
+    if group_ids is None:
+        return
+
+    # Local imports avoid a circular import at module load time.
+    from vcs.models.finding import Finding
+    from vcs.models.repo import Repo
+    from vcs.models.scan import Scan
+
+    repo_ids = select(Repo.id).where(Repo.group_id.in_(group_ids))
+    execute_state.statement = execute_state.statement.options(
+        with_loader_criteria(
+            Repo, Repo.group_id.in_(group_ids), include_aliases=True
+        ),
+        with_loader_criteria(
+            Finding, Finding.repo_id.in_(repo_ids), include_aliases=True
+        ),
+        with_loader_criteria(
+            Scan, Scan.repo_id.in_(repo_ids), include_aliases=True
+        ),
+    )