evidentia-api 0.6.0__py3-none-any.whl

evidentia_api/__init__.py

@@ -0,0 +1,21 @@
+"""Evidentia API: FastAPI REST server + bundled React web UI.
+
+The FastAPI application is exposed as :data:`evidentia_api.app.app` and
+can be served directly with uvicorn:
+
+    uvicorn evidentia_api.app:app --host 127.0.0.1 --port 8000
+
+Typical users reach it via the CLI:
+
+    evidentia serve [--host HOST] [--port PORT] [--offline]
+
+which is a thin Typer wrapper around :func:`evidentia_api.cli.serve`.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("evidentia-api")
+except PackageNotFoundError:  # pragma: no cover — only hit in editable repos without install
+    __version__ = "0.0.0+unknown"

evidentia_api/app.py

@@ -0,0 +1,236 @@
+"""FastAPI application factory.
+
+The module-level ``app`` is the canonical instance that uvicorn references.
+For testing (TestClient), prefer :func:`create_app` which accepts overrides.
+
+All API routes live under ``/api/*``. Static assets (the bundled React SPA)
+are mounted at ``/`` and serve ``index.html`` for every non-``/api/*`` path
+to support client-side routing (React Router).
+
+In v0.4.0 the static directory is populated at wheel-build time by the
+frontend build hook in ``.github/workflows/release.yml`` (it runs
+``npm run build`` in ``packages/evidentia-ui`` and copies ``dist/*``
+into ``src/evidentia_api/static/``). When the directory is empty at
+runtime (e.g. fresh dev install without a build), a placeholder JSON
+response is returned instead of 404 so the error is self-explanatory.
+
+Offline mode: the ``evidentia serve --offline`` CLI entry point sets
+``EVIDENTIA_API_OFFLINE=1`` in the subprocess env. This module reads
+that at import time to flip the process-wide air-gap guard before any
+router handler runs.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from evidentia_api import __version__
+
+logger = logging.getLogger(__name__)
+
+STATIC_DIR = Path(__file__).parent / "static"
+"""Absolute path to the bundled SPA assets (populated at build time)."""
+
+
+def create_app(
+    *,
+    offline: bool = False,
+    dev_mode: bool = False,
+    cors_origins: list[str] | None = None,
+) -> FastAPI:
+    """Build and return a FastAPI application.
+
+    Parameters
+    ----------
+    offline
+        When True, flips the process-wide air-gap guard at app creation.
+        Every LLM/network call then refuses non-loopback targets.
+    dev_mode
+        When True, CORS is permissive to support the Vite dev server
+        (http://127.0.0.1:5173) without a proxy.
+    cors_origins
+        Explicit allow-list override. Default: restrictive localhost-only.
+    """
+    if offline:
+        from evidentia_core.network_guard import set_offline
+
+        set_offline(True)
+
+    app = FastAPI(
+        title="Evidentia API",
+        description=(
+            "REST API for the Evidentia GRC tool. All endpoints mirror "
+            "CLI capabilities. Binds to 127.0.0.1 by default for localhost "
+            "web-UI use."
+        ),
+        version=__version__,
+        docs_url="/api/docs",
+        redoc_url="/api/redoc",
+        openapi_url="/api/openapi.json",
+    )
+
+    # CORS: dev_mode is permissive for Vite HMR; prod is localhost-only.
+    if cors_origins is None:
+        cors_origins = (
+            [
+                "http://127.0.0.1:5173",
+                "http://localhost:5173",
+                "http://127.0.0.1:8000",
+                "http://localhost:8000",
+            ]
+            if dev_mode
+            else ["http://127.0.0.1:8000", "http://localhost:8000"]
+        )
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=cors_origins,
+        allow_credentials=True,
+        allow_methods=["GET", "POST", "PUT", "DELETE"],
+        allow_headers=["*"],
+    )
+
+    # Attach flags to app state so every router dep can consult them.
+    app.state.offline = offline
+    app.state.dev_mode = dev_mode
+
+    # Register routers. Each router is a focused module — see routers/*.py.
+    # Imports are deferred so module-load errors in one router don't take
+    # down the whole server.
+    from evidentia_api.routers import (
+        collectors as collectors_router,
+    )
+    from evidentia_api.routers import (
+        config as config_router,
+    )
+    from evidentia_api.routers import (
+        doctor as doctor_router,
+    )
+    from evidentia_api.routers import (
+        explain as explain_router,
+    )
+    from evidentia_api.routers import (
+        frameworks as frameworks_router,
+    )
+    from evidentia_api.routers import (
+        gaps as gaps_router,
+    )
+    from evidentia_api.routers import (
+        health as health_router,
+    )
+    from evidentia_api.routers import (
+        init_wizard as init_wizard_router,
+    )
+    from evidentia_api.routers import (
+        integrations as integrations_router,
+    )
+    from evidentia_api.routers import (
+        llm_status as llm_status_router,
+    )
+    from evidentia_api.routers import (
+        risks as risks_router,
+    )
+
+    app.include_router(health_router.router, prefix="/api", tags=["health"])
+    app.include_router(config_router.router, prefix="/api", tags=["config"])
+    app.include_router(doctor_router.router, prefix="/api", tags=["doctor"])
+    app.include_router(llm_status_router.router, prefix="/api", tags=["llm"])
+    app.include_router(
+        frameworks_router.router, prefix="/api", tags=["frameworks"]
+    )
+    app.include_router(gaps_router.router, prefix="/api", tags=["gaps"])
+    app.include_router(risks_router.router, prefix="/api", tags=["risks"])
+    app.include_router(explain_router.router, prefix="/api", tags=["explain"])
+    app.include_router(
+        init_wizard_router.router, prefix="/api", tags=["init"]
+    )
+    app.include_router(
+        integrations_router.router, prefix="/api", tags=["integrations"]
+    )
+    app.include_router(
+        collectors_router.router, prefix="/api", tags=["collectors"]
+    )
+
+    # Static SPA mount — everything that isn't /api/* falls through to index.html.
+    _mount_spa(app)
+
+    return app
+
+
+def _mount_spa(app: FastAPI) -> None:
+    """Mount the bundled React SPA at the root.
+
+    If the static directory is missing or empty (common in fresh dev checkouts
+    before ``npm run build`` has been executed), serve a helpful placeholder
+    instead of 404 so users can self-diagnose.
+    """
+    if STATIC_DIR.is_dir() and (STATIC_DIR / "index.html").is_file():
+        # Mount static/assets first for JS/CSS/fonts; then SPA fallback.
+        assets_dir = STATIC_DIR / "assets"
+        if assets_dir.is_dir():
+            app.mount(
+                "/assets",
+                StaticFiles(directory=assets_dir),
+                name="spa-assets",
+            )
+
+        @app.get("/{full_path:path}", include_in_schema=False)
+        async def _spa_fallback(full_path: str, request: Request) -> FileResponse:
+            """Serve index.html for every non-API path so React Router owns routing."""
+            if full_path.startswith("api/"):
+                # Defensive — FastAPI routing should have caught these already.
+                return FileResponse(STATIC_DIR / "index.html", status_code=404)
+            target = STATIC_DIR / full_path
+            if target.is_file():
+                return FileResponse(target)
+            return FileResponse(STATIC_DIR / "index.html")
+
+    else:
+        logger.info(
+            "Static SPA directory is empty at %s — serving dev placeholder. "
+            "Run `npm run build` in packages/evidentia-ui/ to populate.",
+            STATIC_DIR,
+        )
+
+        @app.get("/{full_path:path}", include_in_schema=False)
+        async def _dev_placeholder(full_path: str) -> JSONResponse:
+            if full_path.startswith("api/"):
+                return JSONResponse(status_code=404, content={"detail": "Not Found"})
+            return JSONResponse(
+                status_code=503,
+                content={
+                    "error": "spa_not_built",
+                    "message": (
+                        "The Evidentia web UI is not bundled in this install. "
+                        "If you are developing, run `npm install && npm run dev` "
+                        "in packages/evidentia-ui/ and use `evidentia "
+                        "serve --dev`. If you are an end user, please reinstall "
+                        "with `pip install --force-reinstall evidentia[gui]`."
+                    ),
+                    "api_docs": "/api/docs",
+                },
+            )
+
+
+# Read env-var flags set by ``evidentia serve`` subprocess launch.
+# EVIDENTIA_API_OFFLINE=1 -> offline mode
+# EVIDENTIA_API_DEV=1     -> permissive CORS for Vite dev server
+_env_offline = os.environ.get("EVIDENTIA_API_OFFLINE", "").strip().lower() in {
+    "1",
+    "true",
+    "yes",
+}
+_env_dev = os.environ.get("EVIDENTIA_API_DEV", "").strip().lower() in {
+    "1",
+    "true",
+    "yes",
+}
+
+# Default instance for `uvicorn evidentia_api.app:app` usage.
+app = create_app(offline=_env_offline, dev_mode=_env_dev)

evidentia_api/cli.py

@@ -0,0 +1,123 @@
+"""`evidentia serve` implementation.
+
+Invoked from :mod:`evidentia.cli.main` via the `serve` Typer command.
+Uses ``subprocess.Popen`` against ``sys.executable -m uvicorn`` for
+portability across Windows/macOS/Linux — per the Plan-agent pressure-test,
+this pattern survives Ctrl+C on Windows consoles more reliably than
+``uvicorn.run()`` in-process.
+
+Dev mode (``--dev``) leaves frontend serving to the Vite dev server
+(``npm run dev`` in ``packages/evidentia-ui/``) on port 5173; the
+FastAPI server at 8000 enables permissive CORS so the two co-exist.
+Production mode serves the bundled SPA from the wheel.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def serve(
+    *,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    offline: bool = False,
+    dev: bool = False,
+    open_browser: bool = True,
+    reload: bool = False,
+) -> int:
+    """Spawn uvicorn serving the Evidentia API + web UI.
+
+    Returns the child process exit code. Errors raised before spawn (e.g.
+    missing uvicorn install) surface as ``ImportError`` for the caller to
+    translate into a friendly message.
+    """
+    # Verify uvicorn is importable before spawning — otherwise the
+    # subprocess error message is opaque on Windows.
+    try:
+        import uvicorn  # noqa: F401
+    except ImportError as e:
+        raise ImportError(
+            "uvicorn is not installed. Install the [gui] extra: "
+            "`pip install 'evidentia[gui]'` or "
+            "`uv tool install 'evidentia[gui]'`."
+        ) from e
+
+    # Host-binding security: warn if binding to a non-loopback address.
+    if host not in ("127.0.0.1", "localhost", "::1"):
+        logger.warning(
+            "SECURITY: binding to %s exposes the web UI on your network. "
+            "Evidentia has no auth in v0.4.0 — anyone who can reach this "
+            "address can view and modify your gap reports. Bind to 127.0.0.1 "
+            "unless you know what you're doing.",
+            host,
+        )
+
+    # Environment plumbing: offline flag + dev mode are read by
+    # evidentia_api.app.create_app via module-level env vars so they
+    # survive the subprocess boundary.
+    env = os.environ.copy()
+    if offline:
+        env["EVIDENTIA_API_OFFLINE"] = "1"
+    if dev:
+        env["EVIDENTIA_API_DEV"] = "1"
+
+    cmd = [
+        sys.executable,
+        "-m",
+        "uvicorn",
+        "evidentia_api.app:app",
+        "--host",
+        host,
+        "--port",
+        str(port),
+    ]
+    if reload:
+        cmd.append("--reload")
+
+    if open_browser and not reload:
+        # Open browser slightly after spawn so the server has time to bind.
+        import threading
+        import webbrowser
+
+        def _open() -> None:
+            import time
+
+            time.sleep(1.5)
+            webbrowser.open(f"http://{host}:{port}")
+
+        threading.Thread(target=_open, daemon=True).start()
+
+    logger.info("Spawning: %s", " ".join(cmd))
+
+    # Windows: CREATE_NEW_PROCESS_GROUP lets Ctrl+C in the parent terminate
+    # the child cleanly without leaving a zombie on the port.
+    popen_kwargs: dict = {"env": env}
+    if sys.platform == "win32":
+        popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+
+    proc = subprocess.Popen(cmd, **popen_kwargs)
+    try:
+        return proc.wait()
+    except KeyboardInterrupt:
+        logger.info("Received Ctrl+C; shutting down uvicorn...")
+        if sys.platform == "win32":
+            import signal
+
+            proc.send_signal(signal.CTRL_BREAK_EVENT)
+        else:
+            proc.terminate()
+        return proc.wait()
+
+
+def resolve_static_dir() -> Path:
+    """Return the static-asset directory, for diagnostics."""
+    from evidentia_api.app import STATIC_DIR
+
+    return STATIC_DIR

evidentia_api/deps.py

@@ -0,0 +1,25 @@
+"""FastAPI dependency-injection helpers.
+
+Each router consumes these via ``Depends(...)`` so tests can override them
+via ``app.dependency_overrides`` for TestClient-based coverage.
+"""
+
+from __future__ import annotations
+
+from evidentia_core.catalogs.registry import FrameworkRegistry
+from fastapi import Request
+
+
+def get_registry() -> FrameworkRegistry:
+    """Return the shared FrameworkRegistry singleton."""
+    return FrameworkRegistry.get_instance()
+
+
+def get_offline_flag(request: Request) -> bool:
+    """True if the server was started with --offline."""
+    return bool(getattr(request.app.state, "offline", False))
+
+
+def get_dev_mode(request: Request) -> bool:
+    """True if the server was started with --dev (Vite proxy mode)."""
+    return bool(getattr(request.app.state, "dev_mode", False))

evidentia_api/routers/__init__.py

@@ -0,0 +1,5 @@
+"""FastAPI routers — one module per logical endpoint group.
+
+Routers are registered in :func:`evidentia_api.app.create_app`; each
+module exposes a ``router: APIRouter`` module-level attribute.
+"""

evidentia_api/routers/collectors.py

@@ -0,0 +1,151 @@
+"""Collectors router — AWS + GitHub evidence endpoints.
+
+All endpoints are POST-only — running a collector has non-trivial
+side-effects (AWS API calls, GitHub rate limits) so a GET shouldn't
+trigger them. Response is a list of :class:`SecurityFinding` objects.
+
+Credentials:
+- AWS: boto3's standard chain (env, ~/.aws/credentials, instance profile)
+- GitHub: $GITHUB_TOKEN environment variable on the server
+
+No credential values ever flow through request/response bodies.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from evidentia_core.models.finding import SecurityFinding
+from fastapi import APIRouter, HTTPException
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+@router.post("/collectors/aws/collect", response_model=list[SecurityFinding])
+async def aws_collect(payload: dict[str, Any] | None = None) -> list[SecurityFinding]:
+    """Run the AWS collector (Config + Security Hub).
+
+    Request body (optional):
+
+    - ``region``: override region
+    - ``profile``: optional AWS profile name
+    - ``include_config``: bool (default True)
+    - ``include_security_hub``: bool (default True)
+    """
+    try:
+        from evidentia_collectors.aws import AwsCollector, AwsCollectorError
+    except ImportError as e:
+        raise HTTPException(
+            status_code=503,
+            detail=(
+                "AWS collector not installed. Run "
+                "`pip install 'evidentia-collectors[aws]'`."
+            ),
+        ) from e
+
+    body = payload or {}
+    region = body.get("region") if isinstance(body.get("region"), str) else None
+    profile = body.get("profile") if isinstance(body.get("profile"), str) else None
+    include_config = bool(body.get("include_config", True))
+    include_security_hub = bool(body.get("include_security_hub", True))
+
+    try:
+        collector = AwsCollector(region=region, profile=profile)
+        collector.test_connection()
+    except AwsCollectorError as e:
+        raise HTTPException(status_code=503, detail=str(e)) from e
+
+    try:
+        findings = collector.collect_all(
+            include_config=include_config,
+            include_security_hub=include_security_hub,
+        )
+    except Exception as e:
+        logger.exception("AWS collector failed")
+        raise HTTPException(status_code=500, detail=f"AWS collector failed: {e}") from e
+
+    return findings
+
+
+@router.post("/collectors/github/collect", response_model=list[SecurityFinding])
+async def github_collect(payload: dict[str, Any]) -> list[SecurityFinding]:
+    """Run the GitHub collector.
+
+    Request body (required):
+
+    - ``repo``: repository in 'owner/repo' format
+
+    Credentials are sourced from the server's ``$GITHUB_TOKEN`` env var.
+    """
+    try:
+        from evidentia_collectors.github import (
+            GitHubApiError,
+            GitHubCollector,
+            GitHubCollectorError,
+        )
+    except ImportError as e:
+        raise HTTPException(
+            status_code=503,
+            detail=f"GitHub collector import failed: {e}",
+        ) from e
+
+    repo = str(payload.get("repo") or "").strip()
+    if "/" not in repo:
+        raise HTTPException(
+            status_code=422,
+            detail="Request body must include 'repo' in 'owner/repo' format.",
+        )
+    owner, repo_name = repo.split("/", 1)
+    token = os.environ.get("GITHUB_TOKEN")
+
+    try:
+        with GitHubCollector(
+            owner=owner, repo=repo_name, token=token
+        ) as collector:
+            findings = collector.collect()
+    except GitHubCollectorError as e:
+        raise HTTPException(status_code=404, detail=str(e)) from e
+    except GitHubApiError as e:
+        raise HTTPException(status_code=502, detail=str(e)) from e
+
+    return findings
+
+
+@router.get("/collectors/status")
+async def collectors_status() -> dict[str, Any]:
+    """Report which collectors are installed + which credentials are set.
+
+    Never returns token values — only ``configured: bool`` + the env var
+    name the token was sourced from.
+    """
+    aws_installed = False
+    github_installed = False
+    try:
+        import evidentia_collectors.aws
+
+        aws_installed = True
+    except ImportError:
+        pass
+    try:
+        import evidentia_collectors.github  # noqa: F401
+
+        github_installed = True
+    except ImportError:
+        pass
+
+    return {
+        "aws": {
+            "installed": aws_installed,
+            "credentials_hint": (
+                "boto3 standard chain (env / ~/.aws / instance profile)"
+            ),
+        },
+        "github": {
+            "installed": github_installed,
+            "token_configured": bool(os.environ.get("GITHUB_TOKEN")),
+            "token_source": "env:GITHUB_TOKEN" if os.environ.get("GITHUB_TOKEN") else None,
+        },
+    }

evidentia_api/routers/config.py

@@ -0,0 +1,74 @@
+"""Config router — read / write ``evidentia.yaml``.
+
+GET returns the current config (walking CWD -> parents for the file).
+PUT accepts a :class:`EvidentiaConfig` payload, validates it via
+Pydantic, and writes the YAML back to the same path.
+
+No secrets ever flow through this endpoint's request/response bodies —
+the ``llm`` subsection is model + temperature only (no API keys). Keys
+are handled separately via the ``/api/llm-status`` endpoint, which never
+returns key values, only booleans + source identifiers.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+from evidentia_core.config import (
+    CONFIG_FILENAME,
+    EvidentiaConfig,
+    find_config_file,
+    load_config,
+)
+from fastapi import APIRouter, HTTPException
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+@router.get("/config", response_model=EvidentiaConfig)
+async def get_config() -> EvidentiaConfig:
+    """Return the currently-loaded evidentia.yaml contents.
+
+    If no file exists in CWD or any parent, returns a default
+    (empty) :class:`EvidentiaConfig`.
+    """
+    return load_config()
+
+
+@router.put("/config", response_model=EvidentiaConfig)
+async def put_config(payload: EvidentiaConfig) -> EvidentiaConfig:
+    """Persist ``evidentia.yaml`` with the validated payload.
+
+    Writes to the discovered path (walking CWD -> parents), or to
+    ``./evidentia.yaml`` if none exists yet. Returns the persisted
+    config (with ``source_path`` populated so callers can confirm where
+    the write landed).
+    """
+    target = find_config_file() or (Path.cwd() / CONFIG_FILENAME)
+    try:
+        dumped: dict[str, Any] = payload.model_dump(
+            exclude={"source_path"}, exclude_defaults=False
+        )
+        yaml_text = yaml.safe_dump(
+            dumped, sort_keys=False, default_flow_style=False
+        )
+        target.write_text(yaml_text, encoding="utf-8")
+    except OSError as e:
+        logger.error("Failed to write %s: %s", target, e)
+        raise HTTPException(
+            status_code=500,
+            detail=f"Could not write config to {target}: {e}",
+        ) from e
+
+    # Clear the LRU cache so subsequent reads see the new contents.
+    from evidentia_core.config import _load_config_cached
+
+    _load_config_cached.cache_clear()
+
+    refreshed = load_config(target)
+    logger.info("Wrote %s (%d bytes)", target, len(yaml_text))
+    return refreshed