webvigil 1.0.0__py3-none-any.whl

webvigil/__init__.py

@@ -0,0 +1,10 @@
+"""WebVigil — a web application vulnerability scanner for developers."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("webvigil")
+except PackageNotFoundError:  # running from a source tree without an install
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["__version__"]

webvigil/api/__init__.py

@@ -0,0 +1,7 @@
+"""
+Web API: a FastAPI wrapper around the scan engine, with SQLite persistence.
+
+Only available with the ``web`` extra (``pip install "webvigil[web]"``). This
+package may import the engine and the reporters; the engine imports nothing from
+here — the boundary is enforced by import-linter.
+"""

webvigil/api/app.py

@@ -0,0 +1,85 @@
+"""
+The FastAPI application factory and its lifespan.
+
+The route-handler docstrings double as the OpenAPI endpoint descriptions, so
+they stay to a sentence or two; the private helpers carry the full
+Args/Returns sections.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from webvigil import __version__
+from webvigil.api.config import WebConfig
+from webvigil.api.db import make_engine, run_alembic_upgrade
+from webvigil.api.routes import auth, meta, reports, scans, setup
+from webvigil.api.runner import OrchestratorFactory, ScanRunner, recover_interrupted_scans
+from webvigil.api.security import resolve_session_secret
+from webvigil.api.throttle import LoginThrottle
+
+
+def create_app(
+    config: WebConfig | None = None,
+    *,
+    orchestrator_factory: OrchestratorFactory | None = None,
+) -> FastAPI:
+    """
+    Build the FastAPI app: wire the lifespan, optional CORS, and the routers.
+
+    Args:
+        config (WebConfig | None): The Web-API config; loaded from file / env
+            when ``None``.
+        orchestrator_factory (OrchestratorFactory | None): Test seam passed
+            through to the :class:`~webvigil.api.runner.ScanRunner`; ``None``
+            uses the real orchestrator.
+
+    Returns:
+        FastAPI: The configured application.
+    """
+    cfg = config or WebConfig.load()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        """Startup: migrate, open the engine, resolve the secret, recover, start the runner."""
+        if cfg.auto_migrate:
+            run_alembic_upgrade(cfg)
+        engine = make_engine(cfg)
+        app.state.config = cfg
+        app.state.engine = engine
+        app.state.session_secret = resolve_session_secret(engine, cfg)
+        recover_interrupted_scans(engine)
+        runner = (
+            ScanRunner(engine, orchestrator_factory=orchestrator_factory)
+            if orchestrator_factory is not None
+            else ScanRunner(engine)
+        )
+        app.state.runner = runner
+        await runner.start()
+        runner.wake()
+        try:
+            yield
+        finally:
+            await runner.stop()
+            engine.dispose()
+
+    app = FastAPI(title="WebVigil API", version=__version__, lifespan=lifespan)
+    app.state.login_throttle = LoginThrottle()
+    if cfg.cors_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=cfg.cors_origins,
+            allow_credentials=True,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+    for router in (meta.router, setup.router, auth.router, scans.router, reports.router):
+        app.include_router(router, prefix="/api")
+    return app
+
+
+app = create_app()

webvigil/api/cli.py

@@ -0,0 +1,88 @@
+"""
+The ``webvigil-web`` command: serve the API, run migrations, reset the password (RF-29).
+
+The command docstrings double as Typer ``--help`` text, so they stay terse.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from sqlmodel import Session, select
+
+from webvigil.api.config import WebConfig
+from webvigil.api.db import User, make_engine, run_alembic_upgrade, utcnow
+from webvigil.api.security import hash_password
+
+app = typer.Typer(
+    name="webvigil-web",
+    help="Run the WebVigil Web API and manage its database.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+_ConfigOpt = Annotated[Path | None, typer.Option("--config", help="Path to webvigil.toml.")]
+
+
+@app.command()
+def serve(
+    config: _ConfigOpt = None,
+    host: Annotated[str | None, typer.Option(help="Bind host.")] = None,
+    port: Annotated[int | None, typer.Option(help="Bind port.")] = None,
+    reload: Annotated[bool, typer.Option(help="Auto-reload on code changes (dev only).")] = False,
+) -> None:
+    """Serve the API with uvicorn."""
+    import uvicorn
+
+    if config is not None:
+        os.environ["WEBVIGIL_CONFIG"] = str(config)
+    cfg = WebConfig.load(config)
+    uvicorn.run(
+        "webvigil.api.app:app",
+        host=host or cfg.host,
+        port=port or cfg.port,
+        reload=reload,
+    )
+
+
+@app.command()
+def migrate(config: _ConfigOpt = None) -> None:
+    """Run ``alembic upgrade head`` against the configured database."""
+    cfg = WebConfig.load(config)
+    run_alembic_upgrade(cfg)
+    typer.echo(f"database migrated: {cfg.database_path}")
+
+
+@app.command(name="reset-password")
+def reset_password(
+    config: _ConfigOpt = None,
+    username: Annotated[
+        str | None, typer.Option(help="Which user (default: the only one).")
+    ] = None,
+) -> None:
+    """Set a new password for the single user."""
+    cfg = WebConfig.load(config)
+    run_alembic_upgrade(cfg)
+    engine = make_engine(cfg)
+    with Session(engine) as session:
+        statement = select(User)
+        if username is not None:
+            statement = statement.where(User.username == username)
+        user = session.exec(statement).first()
+        if user is None:
+            typer.echo("no user found — complete first-run setup in the browser first", err=True)
+            raise typer.Exit(1)
+        new_password = typer.prompt("New password", hide_input=True, confirmation_prompt=True)
+        user.password_hash = hash_password(new_password)
+        user.updated_at = utcnow()
+        session.add(user)
+        session.commit()
+        typer.echo(f"password updated for {user.username}")
+
+
+def main() -> None:
+    """Console-script entry point for ``webvigil-web`` (see ``project.scripts``)."""
+    app()

webvigil/api/config.py

@@ -0,0 +1,119 @@
+"""Web API configuration: the ``[web]`` table of ``webvigil.toml`` plus env overrides."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from webvigil.core.errors import ConfigError
+
+_ENV_PREFIX = "WEBVIGIL_"
+
+
+class WebConfig(BaseModel):
+    """
+    Everything the Web API needs to run. API-only — the engine never reads this.
+
+    Attributes:
+        database_path (Path): SQLite file path. Defaults to ``webvigil.db``.
+        host (str): Bind host. Defaults to ``127.0.0.1``.
+        port (int): Bind port. Defaults to 8000.
+        session_secret (str | None): Pinned JWT signing secret; when ``None`` a
+            secret is generated and stored in the database on first use.
+        session_ttl_hours (int): Session lifetime, in hours. Defaults to 12.
+        cookie_secure (bool): Set the ``Secure`` flag on the session cookie.
+            Defaults to ``False`` (development over HTTP).
+        auto_migrate (bool): Run ``alembic upgrade head`` on startup. Defaults
+            to ``True``.
+        cors_origins (list[str]): Allowed CORS origins. Defaults to empty (the
+            bundled UI is same-origin).
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    database_path: Path = Path("webvigil.db")
+    host: str = "127.0.0.1"
+    port: int = 8000
+    session_secret: str | None = None
+    session_ttl_hours: int = 12
+    cookie_secure: bool = False
+    auto_migrate: bool = True
+    cors_origins: list[str] = []
+
+    @classmethod
+    def load(cls, path: str | Path | None = None) -> WebConfig:
+        """
+        Build a config from the ``[web]`` table of ``path``, then env vars.
+
+        Args:
+            path (str | Path | None): Path to a ``webvigil.toml``. When omitted,
+                ``WEBVIGIL_CONFIG`` is used if set; when that is also unset, only
+                defaults and env vars apply.
+
+        Returns:
+            WebConfig: The validated configuration.
+
+        Raises:
+            ConfigError: If the file is missing, is not valid TOML, has a
+                non-table ``[web]``, or fails model validation.
+        """
+        path = path if path is not None else os.environ.get("WEBVIGIL_CONFIG")
+        data: dict[str, Any] = {}
+        if path is not None:
+            file = Path(path)
+            if not file.is_file():
+                raise ConfigError(f"config file not found: {file}")
+            try:
+                raw = tomllib.loads(file.read_text("utf-8"))
+            except tomllib.TOMLDecodeError as exc:
+                raise ConfigError(f"invalid TOML in {file}: {exc}") from exc
+            section = raw.get("web")
+            if section is not None:
+                if not isinstance(section, dict):
+                    raise ConfigError("[web] must be a table")
+                data.update(section)
+
+        data.update(_env_overrides())
+        try:
+            return cls.model_validate(data)
+        except ValidationError as exc:
+            raise ConfigError(str(exc)) from exc
+
+
+def _env_overrides() -> dict[str, Any]:
+    """
+    Read ``WEBVIGIL_*`` environment variables into a config-field mapping.
+
+    Returns:
+        dict[str, Any]: The overrides, with ``port`` / ``session_ttl_hours``
+            coerced to ``int``, the boolean flags parsed loosely, and
+            ``cors_origins`` split on commas.
+    """
+    out: dict[str, Any] = {}
+    mapping = {
+        "DATABASE_PATH": "database_path",
+        "WEB_HOST": "host",
+        "WEB_PORT": "port",
+        "SESSION_SECRET": "session_secret",
+        "SESSION_TTL_HOURS": "session_ttl_hours",
+        "COOKIE_SECURE": "cookie_secure",
+        "AUTO_MIGRATE": "auto_migrate",
+        "CORS_ORIGINS": "cors_origins",
+    }
+    for env_suffix, field in mapping.items():
+        value = os.environ.get(f"{_ENV_PREFIX}{env_suffix}")
+        if value is None:
+            continue
+        if field in ("port", "session_ttl_hours"):
+            out[field] = int(value)
+        elif field in ("cookie_secure", "auto_migrate"):
+            out[field] = value.strip().lower() in ("1", "true", "yes", "on")
+        elif field == "cors_origins":
+            out[field] = [origin.strip() for origin in value.split(",") if origin.strip()]
+        else:
+            out[field] = value
+    return out

webvigil/api/db.py

@@ -0,0 +1,258 @@
+"""
+SQLModel tables, the engine factory, and the Alembic upgrade wrapper (RF-23, RF-24, RF-25).
+
+This module is API-only. The engine never imports it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime
+from enum import StrEnum
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import JSON, Column, Engine, String, event
+from sqlmodel import Field, Session, SQLModel, create_engine
+
+from webvigil.api.config import WebConfig
+
+_MIGRATIONS_DIR = Path(__file__).parent / "migrations"
+
+
+def utcnow() -> datetime:
+    """
+    Returns:
+        datetime: The current time, timezone-aware in UTC.
+    """
+    return datetime.now(UTC)
+
+
+class ScanStatus(StrEnum):
+    """
+    Lifecycle state of a stored scan.
+
+    Attributes:
+        QUEUED (str): Waiting for the runner's execution slot.
+        RUNNING (str): Currently executing.
+        COMPLETED (str): Finished; findings are stored.
+        FAILED (str): Ended with a controlled engine error or a crash.
+        CANCELLED (str): Cancelled by the user.
+        INTERRUPTED (str): Left ``RUNNING`` by a process that died; recovered on
+            the next startup.
+    """
+
+    QUEUED = "queued"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+    INTERRUPTED = "interrupted"
+
+
+TERMINAL_STATUSES: frozenset[ScanStatus] = frozenset(
+    {
+        ScanStatus.COMPLETED,
+        ScanStatus.FAILED,
+        ScanStatus.CANCELLED,
+        ScanStatus.INTERRUPTED,
+    }
+)
+
+
+class User(SQLModel, table=True):
+    """
+    The single account (first-run setup creates it).
+
+    Attributes:
+        id (int | None): Primary key.
+        username (str): Unique, indexed login name.
+        password_hash (str): Argon2 hash.
+        created_at (datetime): When the account was created (UTC).
+        updated_at (datetime): When it was last changed, e.g. a password reset.
+    """
+
+    __tablename__ = "user"
+
+    id: int | None = Field(default=None, primary_key=True)
+    username: str = Field(unique=True, index=True)
+    password_hash: str
+    created_at: datetime = Field(default_factory=utcnow)
+    updated_at: datetime = Field(default_factory=utcnow)
+
+
+class Scan(SQLModel, table=True):
+    """
+    One scan request and its result metadata.
+
+    Attributes:
+        id (int | None): Primary key.
+        target (str): The requested target URL.
+        mode (str): ``"passive"`` or ``"active"``.
+        scope (str): ``"host"`` or ``"subdomains"``.
+        options (dict[str, Any]): The extra overrides from the request
+            (``max_pages``, ``delay_ms``, ``follow_robots``, ``fail_on``,
+            ``disabled_checks``).
+        status (ScanStatus): Lifecycle state; stored as its string value in a
+            plain, indexed ``String`` column.
+        authorized_by (str | None): Active-Mode attestation.
+        tool_version (str | None): WebVigil version that ran the scan.
+        error (str | None): Failure message, when ``status`` is ``FAILED`` /
+            ``INTERRUPTED``.
+        created_at (datetime): When the request was queued (indexed).
+        started_at (datetime | None): When execution began.
+        finished_at (datetime | None): When execution ended.
+        pages_scanned (int): Pages the crawler fetched.
+        counts (dict[str, int]): Finding count per severity name.
+        check_errors (list[dict[str, Any]]): Serialised
+            :class:`~webvigil.core.result.CheckError` entries.
+        warnings (list[str]): Scan warnings.
+        technologies (list[dict[str, Any]]): Detected-technology inventory
+            (spec 004, RF-17); empty for pre-004 scans.
+    """
+
+    __tablename__ = "scan"
+
+    id: int | None = Field(default=None, primary_key=True)
+    target: str
+    mode: str
+    scope: str
+    options: dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON))
+    status: ScanStatus = Field(
+        default=ScanStatus.QUEUED,
+        sa_column=Column("status", String, index=True, nullable=False),
+    )
+    authorized_by: str | None = None
+    tool_version: str | None = None
+    error: str | None = None
+    created_at: datetime = Field(default_factory=utcnow, index=True)
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    pages_scanned: int = 0
+    counts: dict[str, int] = Field(default_factory=dict, sa_column=Column(JSON))
+    check_errors: list[dict[str, Any]] = Field(default_factory=list, sa_column=Column(JSON))
+    warnings: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    technologies: list[dict[str, Any]] = Field(default_factory=list, sa_column=Column(JSON))
+
+
+class Finding(SQLModel, table=True):
+    """
+    One stored finding, belonging to a :class:`Scan`.
+
+    Attributes:
+        id (int | None): Primary key.
+        scan_id (int): Owning scan; ``ON DELETE CASCADE``.
+        check_id (str): The check that produced it.
+        severity (int): The :class:`~webvigil.core.findings.Severity` integer
+            value.
+        confidence (int): The :class:`~webvigil.core.findings.Confidence`
+            integer value.
+        title (str): One-line summary.
+        description (str): Full explanation.
+        location (dict[str, Any]): Serialised
+            :class:`~webvigil.core.findings.Location`.
+        remediation (str): How to fix it.
+        evidence (list[dict[str, Any]]): Serialised evidence items.
+        cwe (list[int]): CWE ids.
+        references (list[str]): Further-reading URLs.
+        fingerprint (str): Stable dedup identity.
+    """
+
+    __tablename__ = "finding"
+
+    id: int | None = Field(default=None, primary_key=True)
+    scan_id: int = Field(foreign_key="scan.id", index=True, ondelete="CASCADE")
+    check_id: str
+    severity: int
+    confidence: int
+    title: str
+    description: str
+    location: dict[str, Any] = Field(sa_column=Column(JSON))
+    remediation: str
+    evidence: list[dict[str, Any]] = Field(default_factory=list, sa_column=Column(JSON))
+    cwe: list[int] = Field(default_factory=list, sa_column=Column(JSON))
+    references: list[str] = Field(default_factory=list, sa_column=Column(JSON))
+    fingerprint: str
+
+
+class Setting(SQLModel, table=True):
+    """
+    A single key/value row for process-wide settings (currently just the session secret).
+
+    Attributes:
+        key (str): Setting name (primary key).
+        value (str): Its string value.
+    """
+
+    __tablename__ = "setting"
+
+    key: str = Field(primary_key=True)
+    value: str
+
+
+def make_engine(config: WebConfig) -> Engine:
+    """
+    Create the SQLite engine, enabling WAL and foreign-key enforcement per connection.
+
+    Args:
+        config (WebConfig): Supplies ``database_path``; the parent directory is
+            created if needed.
+
+    Returns:
+        Engine: The configured SQLAlchemy engine.
+    """
+    path = config.database_path
+    if path.parent and not path.parent.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+    engine = create_engine(
+        f"sqlite:///{path}",
+        connect_args={"check_same_thread": False},
+    )
+
+    @event.listens_for(engine, "connect")
+    def _set_pragmas(dbapi_connection: Any, _record: Any) -> None:
+        """Enable WAL journalling and foreign-key enforcement on every new connection."""
+        cursor = dbapi_connection.cursor()
+        cursor.execute("PRAGMA journal_mode=WAL")
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.close()
+
+    return engine
+
+
+@contextmanager
+def session_scope(engine: Engine) -> Iterator[Session]:
+    """
+    A transactional session context.
+
+    Args:
+        engine (Engine): The DB engine.
+
+    Yields:
+        Session: A session that commits on a clean exit and rolls back on any
+            exception.
+    """
+    with Session(engine) as session:
+        try:
+            yield session
+            session.commit()
+        except Exception:
+            session.rollback()
+            raise
+
+
+def run_alembic_upgrade(config: WebConfig) -> None:
+    """
+    Run ``alembic upgrade head`` against the configured database.
+
+    Args:
+        config (WebConfig): Supplies ``database_path``.
+    """
+    from alembic import command
+    from alembic.config import Config as AlembicConfig
+
+    alembic_cfg = AlembicConfig()
+    alembic_cfg.set_main_option("script_location", str(_MIGRATIONS_DIR))
+    alembic_cfg.set_main_option("sqlalchemy.url", f"sqlite:///{config.database_path}")
+    command.upgrade(alembic_cfg, "head")

webvigil/api/deps.py

@@ -0,0 +1,114 @@
+"""FastAPI dependencies: the DB engine, a request-scoped session, and the current user."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Annotated
+
+from fastapi import Depends, HTTPException, Request, status
+from sqlalchemy import Engine
+from sqlmodel import Session
+
+from webvigil.api.db import User
+from webvigil.api.runner import ScanRunner
+from webvigil.api.security import SESSION_COOKIE, credentials_changed_at, decode_token
+
+_UNAUTHENTICATED = HTTPException(status.HTTP_401_UNAUTHORIZED, "not authenticated")
+
+
+def get_engine(request: Request) -> Engine:
+    """
+    Args:
+        request (Request): The current request.
+
+    Returns:
+        Engine: The process-wide DB engine, stored on ``app.state`` by the
+            lifespan.
+    """
+    engine: Engine = request.app.state.engine
+    return engine
+
+
+def get_session(request: Request) -> Iterator[Session]:
+    """
+    Args:
+        request (Request): The current request.
+
+    Yields:
+        Session: A request-scoped session, closed when the request ends.
+    """
+    with Session(request.app.state.engine) as session:
+        yield session
+
+
+SessionDep = Annotated[Session, Depends(get_session)]
+
+
+def optional_user(request: Request, session: SessionDep) -> User | None:
+    """
+    Resolve the user from the session cookie, or ``None`` when there is none.
+
+    For the one endpoint that has to answer "am I signed in?" without turning
+    the answer into a 401 (a 401 shows up as a console error in the browser).
+
+    Args:
+        request (Request): The current request; the session cookie is read
+            here.
+        session (SessionDep): The request-scoped session.
+
+    Returns:
+        User | None: The authenticated user, or ``None`` when the cookie is
+            absent, invalid, expired, names a user that no longer exists, or was issued before
+            the user's credentials last changed (a password change signs the other sessions out).
+    """
+    token = request.cookies.get(SESSION_COOKIE)
+    if not token:
+        return None
+    claims = decode_token(token, request.app.state.session_secret)
+    if claims is None:
+        return None
+    user = session.get(User, claims.user_id)
+    if user is None or claims.issued_at < credentials_changed_at(user):
+        return None
+    return user
+
+
+OptionalUser = Annotated[User | None, Depends(optional_user)]
+
+
+def current_user(user: OptionalUser) -> User:
+    """
+    Require an authenticated user.
+
+    Args:
+        user (OptionalUser): The user resolved from the session cookie, if any.
+
+    Returns:
+        User: The authenticated user.
+
+    Raises:
+        HTTPException: 401 when there is no valid session (see
+            :func:`optional_user` for what counts as one).
+    """
+    if user is None:
+        raise _UNAUTHENTICATED
+    return user
+
+
+CurrentUser = Annotated[User, Depends(current_user)]
+
+
+def get_runner(request: Request) -> ScanRunner:
+    """
+    Args:
+        request (Request): The current request.
+
+    Returns:
+        ScanRunner: The process-wide scan runner, stored on ``app.state`` by
+            the lifespan.
+    """
+    runner: ScanRunner = request.app.state.runner
+    return runner
+
+
+RunnerDep = Annotated[ScanRunner, Depends(get_runner)]