vehlo-code-scanner 0.1.1rc1__py3-none-any.whl

vcs/__init__.py

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

vcs/api/__init__.py

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

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)

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
+        ),
+    )

vcs/api/deps.py

@@ -0,0 +1,161 @@
+"""Dependency injection for FastAPI routes."""
+
+import uuid
+from collections.abc import Generator
+
+from fastapi import Depends, HTTPException, Query, Request, status
+from sqlalchemy.orm import Session
+
+from vcs.api.auth import AuthPrincipal, scope_session
+from vcs.api.session import read_session
+from vcs.config import get_session_cookie_name
+from vcs.db import create_session_factory
+from vcs.enums import UserRole
+from vcs.models.group import Group
+from vcs.models.user import User
+from vcs.services.tokens import resolve_token
+
+_UNAUTHORIZED = HTTPException(
+    status_code=status.HTTP_401_UNAUTHORIZED,
+    detail="Authentication required",
+    headers={"WWW-Authenticate": "Bearer"},
+)
+
+_session_factory = None
+
+
+def _get_session_factory():
+    global _session_factory
+    if _session_factory is None:
+        _session_factory = create_session_factory()
+    return _session_factory
+
+
+def get_db() -> Generator[Session, None, None]:
+    """Yield an unscoped DB session, closing it after the request.
+
+    Used for the token lookup itself (which must not be group-scoped) and
+    for the ingest write path (which scopes explicitly via the principal).
+    """
+    session = _get_session_factory()()
+    try:
+        yield session
+    finally:
+        session.close()
+
+
+def get_principal(
+    request: Request,
+    db: Session = Depends(get_db),
+) -> AuthPrincipal:
+    """Resolve a bearer token OR a session cookie into an AuthPrincipal.
+
+    Machines send ``Authorization: Bearer <token>`` (one group); humans send
+    the dashboard session cookie (their group memberships). Both raise 401
+    when absent or invalid.
+    """
+    authorization = request.headers.get("authorization")
+    if authorization and authorization.startswith("Bearer "):
+        token = resolve_token(db, authorization[len("Bearer ") :].strip())
+        if token is None:
+            raise _UNAUTHORIZED
+        return AuthPrincipal(
+            kind="token",
+            org_id=token.group.org_id,
+            group_ids=frozenset({token.group_id}),
+            token_id=token.id,
+        )
+
+    cookie = request.cookies.get(get_session_cookie_name())
+    if cookie:
+        user_id = read_session(cookie)
+        if user_id:
+            user = db.query(User).filter_by(id=user_id).first()
+            if user is not None:
+                return AuthPrincipal(
+                    kind="user",
+                    org_id=user.org_id,
+                    group_ids=_visible_group_ids(db, user),
+                    user_id=user.id,
+                )
+
+    raise _UNAUTHORIZED
+
+
+def _visible_group_ids(db: Session, user: User) -> frozenset[uuid.UUID]:
+    """Groups a user may read.
+
+    Org admins see every group in their org; everyone else sees only their
+    memberships. This is the single rule that distinguishes the admin view —
+    routes and the isolation net are unchanged.
+    """
+    if user.role == UserRole.ORG_ADMIN:
+        rows = db.query(Group.id).filter_by(org_id=user.org_id).all()
+        return frozenset(gid for (gid,) in rows)
+    return frozenset(g.id for g in user.groups)
+
+
+def get_current_user(
+    principal: AuthPrincipal = Depends(get_principal),
+    db: Session = Depends(get_db),
+) -> User:
+    """Require a human (session) principal and return the User.
+
+    Machine tokens get 403 — token management and identity endpoints are
+    human-only.
+    """
+    if principal.kind != "user" or principal.user_id is None:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="This endpoint requires a logged-in user session",
+        )
+    user = db.query(User).filter_by(id=principal.user_id).first()
+    if user is None:
+        raise _UNAUTHORIZED
+    return user
+
+
+def resolve_accessible_group(
+    db: Session, principal: AuthPrincipal, group: str
+) -> uuid.UUID:
+    """Resolve a group slug/id to an id within the principal's reach, or 404.
+
+    404 (not 403) so we never reveal that a group exists outside the
+    principal's access.
+    """
+    query = db.query(Group.id).filter(
+        Group.id.in_(principal.accessible_group_ids)
+    )
+    try:
+        query = query.filter(Group.id == uuid.UUID(group))
+    except ValueError:
+        query = query.filter(Group.slug == group)
+    row = query.first()
+    if row is None:
+        raise HTTPException(status_code=404, detail="Group not found")
+    return row[0]
+
+
+def get_scoped_db(
+    principal: AuthPrincipal = Depends(get_principal),
+    group: str | None = Query(
+        default=None,
+        description="Narrow to one accessible group (slug or id).",
+    ),
+) -> Generator[Session, None, None]:
+    """Yield a session scoped to the principal's accessible groups.
+
+    The session carries the groups in ``info`` so the ``do_orm_execute`` net
+    filters every read to them. An optional ``group`` query param narrows the
+    scope to one accessible group — so the same filter applies uniformly to
+    every read endpoint without per-route plumbing.
+    """
+    session = _get_session_factory()()
+    scope = principal.accessible_group_ids
+    if group:
+        scope = frozenset({resolve_accessible_group(session, principal, group)})
+    scope_session(session, scope)
+    try:
+        yield session
+    finally:
+        session.close()

vcs/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API route modules."""

vcs/api/routes/analytics.py

@@ -0,0 +1,79 @@
+"""Analytics endpoints — trends and scanner breakdowns."""
+
+from datetime import datetime, timedelta, timezone
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import Date, cast, func
+from sqlalchemy.orm import Session
+
+from vcs.api.deps import get_scoped_db
+from vcs.api.schemas import (
+    AnalyticsScannersResponse,
+    AnalyticsTrendsResponse,
+    ScannerBreakdown,
+    TrendPoint,
+)
+from vcs.enums import FindingStatus
+from vcs.models.finding import Finding
+
+router = APIRouter(prefix="/api/v1/analytics")
+
+
+@router.get("/trends", response_model=AnalyticsTrendsResponse)
+def get_trends(
+    days: int = 30, db: Session = Depends(get_scoped_db)
+) -> AnalyticsTrendsResponse:
+    """Return daily open/resolved finding counts over the given window."""
+    cutoff = datetime.now(timezone.utc) - timedelta(days=days)
+    rows = (
+        db.query(
+            cast(Finding.first_seen_at, Date).label("date"),
+            Finding.status,
+            func.count(Finding.id).label("count"),
+        )
+        .filter(Finding.first_seen_at >= cutoff)
+        .group_by("date", Finding.status)
+        .order_by("date")
+        .all()
+    )
+    date_map: dict[str, dict[str, int]] = {}
+    for row in rows:
+        d = str(row.date)
+        if d not in date_map:
+            date_map[d] = {"open": 0, "resolved": 0}
+        status_val = (
+            row.status.value
+            if hasattr(row.status, "value")
+            else str(row.status)
+        )
+        if status_val == "open":
+            date_map[d]["open"] += row.count
+        elif status_val == "resolved":
+            date_map[d]["resolved"] += row.count
+    data = [
+        TrendPoint(date=d, open=v["open"], resolved=v["resolved"])
+        for d, v in sorted(date_map.items())
+    ]
+    return AnalyticsTrendsResponse(data=data)
+
+
+@router.get("/scanners", response_model=AnalyticsScannersResponse)
+def get_scanner_breakdown(
+    db: Session = Depends(get_scoped_db),
+) -> AnalyticsScannersResponse:
+    """Return open finding counts grouped by scanner."""
+    rows = (
+        db.query(
+            Finding.scanner,
+            func.count(Finding.id).label("count"),
+        )
+        .filter(Finding.status == FindingStatus.OPEN)
+        .group_by(Finding.scanner)
+        .order_by(func.count(Finding.id).desc())
+        .all()
+    )
+    data = [
+        ScannerBreakdown(scanner=row.scanner, count=row.count)
+        for row in rows
+    ]
+    return AnalyticsScannersResponse(data=data)

vcs/api/routes/auth.py

@@ -0,0 +1,169 @@
+"""Authentication routes — OIDC SSO login and session identity.
+
+Login flow (browser):
+  GET /api/v1/auth/login    -> redirect to the IdP
+  GET /api/v1/auth/callback -> exchange code, provision user, set session
+  POST /api/v1/auth/logout  -> clear session
+  GET /api/v1/auth/me       -> current user (session principal)
+
+The OIDC handshake needs a configured IdP (VCS_OIDC_* env). The session,
+provisioning, and /me/logout paths work independently and are unit-tested.
+"""
+
+from __future__ import annotations
+
+from authlib.integrations.base_client.errors import OAuthError
+from authlib.integrations.starlette_client import OAuth
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi.responses import JSONResponse, RedirectResponse
+from sqlalchemy.orm import Session
+
+from vcs.api.deps import get_current_user, get_db
+from vcs.api.session import issue_session
+from vcs.config import (
+    dev_login_enabled,
+    get_dashboard_url,
+    get_oidc_config,
+    get_session_cookie_name,
+    get_session_ttl_seconds,
+)
+from vcs.models.user import User
+from vcs.services.provisioning import provision_user_from_claims
+
+router = APIRouter(prefix="/api/v1")
+
+oauth = OAuth()
+_OIDC_NAME = "oidc"
+_registered = False
+
+
+def _ensure_oidc_registered() -> bool:
+    """Register the OIDC client once if configured. Returns availability."""
+    global _registered
+    cfg = get_oidc_config()
+    if not cfg["issuer"] or not cfg["client_id"]:
+        return False
+    if not _registered:
+        issuer = cfg["issuer"].rstrip("/")
+        oauth.register(
+            name=_OIDC_NAME,
+            client_id=cfg["client_id"],
+            client_secret=cfg["client_secret"],
+            server_metadata_url=(
+                f"{issuer}/.well-known/openid-configuration"
+            ),
+            # No "groups" scope — Entra delivers group membership via the
+            # `groups` claim (groupMembershipClaims), not an OAuth scope.
+            client_kwargs={"scope": "openid email profile"},
+        )
+        _registered = True
+    return True
+
+
+def _set_session_cookie(response, user_id: str) -> None:
+    response.set_cookie(
+        key=get_session_cookie_name(),
+        value=issue_session(user_id),
+        httponly=True,
+        samesite="lax",
+        max_age=get_session_ttl_seconds(),
+        path="/",
+    )
+
+
+@router.get("/auth/login")
+async def login(request: Request):
+    """Begin OIDC login by redirecting to the IdP."""
+    if not _ensure_oidc_registered():
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="SSO is not configured",
+        )
+    cfg = get_oidc_config()
+    client = getattr(oauth, _OIDC_NAME)
+    return await client.authorize_redirect(request, cfg["redirect_uri"])
+
+
+@router.get("/auth/callback")
+async def callback(request: Request, db: Session = Depends(get_db)):
+    """Handle the IdP redirect: provision the user and set the session."""
+    if not _ensure_oidc_registered():
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="SSO is not configured",
+        )
+    cfg = get_oidc_config()
+    client = getattr(oauth, _OIDC_NAME)
+    try:
+        token = await client.authorize_access_token(request)
+    except OAuthError as exc:
+        # Surface IdP errors cleanly instead of a 500.
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"SSO login failed: {exc.description or exc.error}",
+        ) from exc
+    claims = token.get("userinfo") or token.get("id_token_claims") or {}
+
+    user = provision_user_from_claims(
+        db,
+        dict(claims),
+        org_slug=cfg["default_org_slug"],
+        groups_claim=cfg["groups_claim"],
+    )
+    db.commit()
+
+    response = RedirectResponse(url=get_dashboard_url())
+    _set_session_cookie(response, str(user.id))
+    return response
+
+
+@router.get("/auth/dev-login")
+def dev_login(db: Session = Depends(get_db)):
+    """Dev-only: issue a session for a seeded admin user (no IdP needed).
+
+    Guarded by VCS_DEV_LOGIN; returns 404 when disabled so it is inert in
+    production. Useful for local dashboard preview before SSO is configured.
+    """
+    if not dev_login_enabled():
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND)
+    cfg = get_oidc_config()
+    user = provision_user_from_claims(
+        db,
+        {
+            "sub": "dev-login",
+            "email": "dev@localhost",
+            "name": "Dev User",
+            "role": "org_admin",
+            "groups": ["platform"],
+        },
+        org_slug=cfg["default_org_slug"],
+        groups_claim="groups",
+    )
+    db.commit()
+    response = RedirectResponse(url=get_dashboard_url())
+    _set_session_cookie(response, str(user.id))
+    return response
+
+
+@router.post("/auth/logout")
+def logout() -> JSONResponse:
+    """Clear the session cookie."""
+    response = JSONResponse({"status": "logged_out"})
+    response.delete_cookie(get_session_cookie_name(), path="/")
+    return response
+
+
+@router.get("/auth/me")
+def me(user: User = Depends(get_current_user)) -> dict:
+    """Return the current logged-in user."""
+    return {
+        "id": str(user.id),
+        "email": user.email,
+        "display_name": user.display_name,
+        "role": user.role.value,
+        "org_id": str(user.org_id),
+        "groups": [
+            {"id": str(g.id), "slug": g.slug, "name": g.name}
+            for g in user.groups
+        ],
+    }