skillgate 1.1.0__py3-none-any.whl

skillgate/__init__.py

@@ -0,0 +1,5 @@
+"""SkillGate — CLI-first CI/CD policy enforcement for agent skills."""
+
+from skillgate.version import __version__
+
+__all__ = ["__version__"]

skillgate/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running skillgate as `python -m skillgate`."""
+
+from skillgate.cli.app import main
+
+main()

skillgate/api/__init__.py

@@ -0,0 +1 @@
+"""SkillGate hosted API — optional FastAPI backend."""

skillgate/api/app.py

@@ -0,0 +1,249 @@
+"""FastAPI application factory and configuration."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+import time
+import uuid
+from collections.abc import AsyncGenerator, Awaitable, Callable
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.exceptions import HTTPException as StarletteHTTPException
+from starlette.responses import Response
+
+from skillgate.api.db import init_db, should_auto_init_db, verify_database_connectivity
+from skillgate.api.errors import error_code_for_status, error_response
+from skillgate.api.middleware import BotMitigationMiddleware
+from skillgate.api.redis_circuit_breaker import RedisCircuitBreaker
+from skillgate.api.routes.alerts import router as alerts_router
+from skillgate.api.routes.api_keys import router as api_keys_router
+from skillgate.api.routes.audit import router as audit_router
+from skillgate.api.routes.auth import router as auth_router
+from skillgate.api.routes.entitlements import router as entitlements_router
+from skillgate.api.routes.health import router as health_router
+from skillgate.api.routes.hunt import router as hunt_router
+from skillgate.api.routes.license import router as license_router
+from skillgate.api.routes.payments import router as payments_router
+from skillgate.api.routes.pricing import router as pricing_router
+from skillgate.api.routes.retroscan import router as retroscan_router
+from skillgate.api.routes.roadmap import router as roadmap_router
+from skillgate.api.routes.scans import router as scans_router
+from skillgate.api.routes.teams import router as teams_router
+from skillgate.api.routes.usage import router as usage_router
+from skillgate.api.routes.verify import router as verify_router
+from skillgate.api.settings import get_settings
+from skillgate.api.telemetry import instrument_app
+from skillgate.version import __version__
+
+Redis: Any | None = None
+try:
+    from redis.asyncio import Redis as _Redis
+except ImportError:  # pragma: no cover
+    pass
+else:
+    Redis = _Redis
+
+API_VERSION = "v1"
+logger = logging.getLogger(__name__)
+
+# Global circuit breaker for Stripe API calls (shared across routes)
+stripe_circuit_breaker: RedisCircuitBreaker | None = None
+
+
+def get_stripe_circuit_breaker() -> RedisCircuitBreaker | None:
+    """Get global Stripe circuit breaker instance (None if Redis unavailable)."""
+    return stripe_circuit_breaker
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    """Application lifespan — startup and shutdown hooks."""
+    global stripe_circuit_breaker
+    settings = get_settings()
+
+    # Suppress verbose library logging in production
+    if settings.environment in {"production", "staging"}:
+        logging.getLogger("sqlalchemy").setLevel(logging.WARNING)
+        logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
+        logging.getLogger("asyncpg").setLevel(logging.WARNING)
+        logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+
+    settings.validate_startup()
+    await verify_database_connectivity()
+    if should_auto_init_db():
+        logger.warning(
+            "SKILLGATE_AUTO_INIT_DB enabled; using SQLAlchemy create_all for local/dev startup."
+        )
+        await init_db()
+
+    # Initialize Redis circuit breaker for Stripe calls
+    if Redis is not None:
+        try:
+            redis_client = Redis.from_url(settings.redis_url, decode_responses=False)
+            ping_result = redis_client.ping()
+            if inspect.isawaitable(ping_result):
+                await ping_result
+            stripe_circuit_breaker = RedisCircuitBreaker(
+                redis=redis_client,
+                name="stripe",
+                failure_threshold=5,
+                recovery_seconds=45,
+            )
+            logger.info("Redis circuit breaker initialized for Stripe API calls")
+        except Exception as e:
+            logger.warning(f"Redis init failed, circuit breaker disabled: {e}")
+            stripe_circuit_breaker = None
+
+    yield
+
+    # Shutdown: cleanup redis connection
+    if stripe_circuit_breaker is not None and hasattr(stripe_circuit_breaker._redis, "close"):
+        await stripe_circuit_breaker._redis.close()
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application.
+
+    Returns:
+        Configured FastAPI instance.
+    """
+    app = FastAPI(
+        title="SkillGate API",
+        description="Hosted API for SkillGate — agent skill security governance.",
+        version=__version__,
+        docs_url=f"/api/{API_VERSION}/docs",
+        openapi_url=f"/api/{API_VERSION}/openapi.json",
+        lifespan=lifespan,
+    )
+
+    settings = get_settings()
+
+    # CORS — configured origins only (no permissive wildcard defaults)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins,
+        allow_credentials=settings.cors_allow_credentials,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Bot mitigation — block suspicious User-Agent patterns
+    app.add_middleware(BotMitigationMiddleware)
+
+    @app.middleware("http")
+    async def request_context_middleware(
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Response]],
+    ) -> Response:
+        request_id = request.headers.get("X-Request-ID") or str(uuid.uuid4())
+        request.state.request_id = request_id
+        start = time.perf_counter()
+        try:
+            response = await call_next(request)
+        except Exception:  # noqa: BLE001
+            duration_ms = (time.perf_counter() - start) * 1000
+            logger.exception(
+                "request.failed method=%s path=%s duration_ms=%.2f request_id=%s",
+                request.method,
+                request.url.path,
+                duration_ms,
+                request_id,
+            )
+            error = error_response(
+                status_code=500,
+                message="Internal server error",
+                request_id=request_id,
+                code="INTERNAL_ERROR",
+            )
+            error.headers["X-Request-ID"] = request_id
+            return error
+
+        duration_ms = (time.perf_counter() - start) * 1000
+        response.headers["X-Request-ID"] = request_id
+
+        # Security headers (OWASP recommended)
+        response.headers["X-Content-Type-Options"] = "nosniff"
+        response.headers["X-Frame-Options"] = "DENY"
+        response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+        response.headers["Permissions-Policy"] = (
+            "camera=(), microphone=(), geolocation=(), payment=()"
+        )
+        response.headers["X-XSS-Protection"] = "0"  # Disabled; CSP preferred
+        response.headers["Content-Security-Policy"] = "default-src 'none'; frame-ancestors 'none'"
+        if settings.enable_hsts:
+            response.headers["Strict-Transport-Security"] = (
+                "max-age=63072000; includeSubDomains; preload"
+            )
+
+        logger.info(
+            "request.completed method=%s path=%s status=%s duration_ms=%.2f request_id=%s",
+            request.method,
+            request.url.path,
+            response.status_code,
+            duration_ms,
+            request_id,
+        )
+        return response
+
+    @app.exception_handler(StarletteHTTPException)
+    async def http_exception_handler(
+        request: Request,
+        exc: StarletteHTTPException,
+    ) -> Response:
+        request_id = getattr(request.state, "request_id", str(uuid.uuid4()))
+        message = str(exc.detail) if exc.detail else "Request failed"
+        return error_response(
+            status_code=exc.status_code,
+            message=message,
+            request_id=request_id,
+            code=error_code_for_status(exc.status_code),
+            headers=exc.headers,
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(
+        request: Request,
+        exc: RequestValidationError,
+    ) -> Response:
+        request_id = getattr(request.state, "request_id", str(uuid.uuid4()))
+        message = "Validation failed"
+        logger.warning(
+            "request.validation_failed errors=%s request_id=%s",
+            exc.errors(),
+            request_id,
+        )
+        return error_response(
+            status_code=422,
+            message=message,
+            request_id=request_id,
+            code="VALIDATION_ERROR",
+            retryable=False,
+        )
+
+    # Optional OpenTelemetry instrumentation
+    instrument_app(app)
+
+    # Register route groups
+    app.include_router(audit_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(alerts_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(auth_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(entitlements_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(api_keys_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(health_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(hunt_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(license_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(retroscan_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(roadmap_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(payments_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(pricing_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(scans_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(teams_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(usage_router, prefix=f"/api/{API_VERSION}")
+    app.include_router(verify_router, prefix=f"/api/{API_VERSION}")
+
+    return app

skillgate/api/auth_observability.py

@@ -0,0 +1,141 @@
+"""Auth-provider observability helpers for Section 17.187.
+
+Provides provider-path metrics and structured failure triage logging while
+ensuring token/secrets are never emitted.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+from fastapi import HTTPException
+
+from skillgate.api.errors import AuthError
+from skillgate.api.telemetry import get_meter
+
+logger = logging.getLogger(__name__)
+meter = get_meter("skillgate.api.auth_observability")
+provider_decisions_counter = meter.create_counter("auth_provider_decisions_total")
+provider_failures_counter = meter.create_counter("auth_provider_failures_total")
+
+_SENSITIVE_KEYS = frozenset(
+    {
+        "token",
+        "access_token",
+        "refresh_token",
+        "authorization",
+        "password",
+        "secret",
+        "api_key",
+        "service_role_key",
+        "anon_key",
+        "jwt_secret",
+    }
+)
+
+
+def sanitize_context(payload: dict[str, Any] | None) -> dict[str, Any]:
+    """Return log-safe context by redacting sensitive keys recursively."""
+
+    if payload is None:
+        return {}
+
+    safe: dict[str, Any] = {}
+    for key, value in payload.items():
+        key_norm = key.lower()
+        if any(secret_key in key_norm for secret_key in _SENSITIVE_KEYS):
+            safe[key] = "[REDACTED]"
+            continue
+
+        if isinstance(value, dict):
+            safe[key] = sanitize_context(value)
+            continue
+
+        safe[key] = value
+    return safe
+
+
+def failure_class_from_exception(exc: Exception) -> str:
+    """Map exception classes to stable triage buckets."""
+
+    if isinstance(exc, HTTPException):
+        status_code = exc.status_code
+        if status_code == 400:
+            return "bad_request"
+        if status_code == 401:
+            return "unauthorized"
+        if status_code == 403:
+            return "forbidden"
+        if status_code == 404:
+            return "not_found"
+        if status_code == 409:
+            return "conflict"
+        if status_code == 423:
+            return "locked"
+        if status_code == 429:
+            return "rate_limited"
+        if status_code >= 500:
+            return "upstream_or_internal"
+        return f"http_{status_code}"
+
+    if isinstance(exc, AuthError):
+        return "auth_error"
+    if isinstance(exc, httpx.HTTPError):
+        return "http_transport_error"
+    if isinstance(exc, ValueError):
+        return "validation_error"
+    return "internal_error"
+
+
+def record_auth_decision(
+    *,
+    endpoint: str,
+    provider: str,
+    outcome: str,
+    failure_class: str | None = None,
+    status_code: int | None = None,
+    context: dict[str, Any] | None = None,
+) -> None:
+    """Emit counters and a structured log line for auth provider decisions."""
+
+    attributes = {
+        "endpoint": endpoint,
+        "provider": provider,
+        "outcome": outcome,
+    }
+    provider_decisions_counter.add(1, attributes)
+
+    safe_context = sanitize_context(context)
+    if outcome == "success":
+        logger.info(
+            "auth_provider.decision endpoint=%s provider=%s outcome=%s context=%s",
+            endpoint,
+            provider,
+            outcome,
+            safe_context,
+        )
+        return
+
+    failure_bucket = failure_class or "unknown_failure"
+    provider_failures_counter.add(
+        1,
+        {
+            "endpoint": endpoint,
+            "provider": provider,
+            "failure_class": failure_bucket,
+        },
+    )
+    logger.warning(
+        (
+            "auth_provider.failure endpoint=%s provider=%s outcome=%s "
+            "failure_class=%s status=%s context=%s"
+        ),
+        endpoint,
+        provider,
+        outcome,
+        failure_bucket,
+        status_code,
+        safe_context,
+    )

skillgate/api/db.py

@@ -0,0 +1,127 @@
+"""Database engine and session management for hosted API routes."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncGenerator
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.pool import NullPool
+
+from skillgate.api.models import Base
+
+
+def _database_url() -> str:
+    """Resolve database URL from environment."""
+    value = os.environ.get("SKILLGATE_DATABASE_URL")
+    if value is None or not value.strip():
+        raise RuntimeError("SKILLGATE_DATABASE_URL must be set.")
+    return value
+
+
+def _read_replica_url() -> str | None:
+    """Optional read-replica URL for SELECT-heavy routes."""
+    return os.environ.get("SKILLGATE_READ_REPLICA_URL")
+
+
+def _parse_bool(value: str | None, default: bool) -> bool:
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _pool_size() -> int:
+    return int(os.environ.get("SKILLGATE_DB_POOL_SIZE", "20"))
+
+
+def _max_overflow() -> int:
+    return int(os.environ.get("SKILLGATE_DB_MAX_OVERFLOW", "10"))
+
+
+def _is_postgres(url: str) -> bool:
+    return url.startswith("postgresql")
+
+
+def database_url() -> str:
+    """Expose the configured runtime database URL."""
+    return _database_url()
+
+
+def alembic_database_url() -> str:
+    """Return sync-driver database URL for Alembic migration engine."""
+    url = _database_url()
+    if url.startswith("postgresql+asyncpg://"):
+        return url.replace("postgresql+asyncpg://", "postgresql+psycopg://", 1)
+    if url.startswith("sqlite+aiosqlite:///"):
+        return url.replace("sqlite+aiosqlite:///", "sqlite:///", 1)
+    return url
+
+
+def _engine_kwargs(url: str) -> dict[str, object]:
+    """Build engine kwargs with connection pooling for PostgreSQL."""
+    kwargs: dict[str, object] = {"future": True, "pool_pre_ping": True}
+    if _parse_bool(os.environ.get("SKILLGATE_DISABLE_DB_POOL"), False):
+        kwargs["poolclass"] = NullPool
+        return kwargs
+    if _is_postgres(url):
+        kwargs["pool_size"] = _pool_size()
+        kwargs["max_overflow"] = _max_overflow()
+        kwargs["pool_recycle"] = 300
+        kwargs["pool_timeout"] = 30
+    return kwargs
+
+
+_primary_url = _database_url()
+engine = create_async_engine(_primary_url, **_engine_kwargs(_primary_url))
+
+# Read-replica engine (falls back to primary if not configured)
+_replica_url = _read_replica_url()
+read_engine = (
+    create_async_engine(_replica_url, **_engine_kwargs(_replica_url)) if _replica_url else engine
+)
+
+SessionLocal = async_sessionmaker(
+    bind=engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+ReadOnlySession = async_sessionmaker(
+    bind=read_engine,
+    class_=AsyncSession,
+    expire_on_commit=False,
+)
+
+
+async def init_db() -> None:
+    """Create database tables for local/dev workflows only.
+
+    Production deployments must use Alembic migrations.
+    """
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+
+def should_auto_init_db() -> bool:
+    """Control schema auto-initialize behavior for local SQLite-only startup."""
+    default = _database_url().startswith("sqlite+")
+    return _parse_bool(os.environ.get("SKILLGATE_AUTO_INIT_DB"), default)
+
+
+async def verify_database_connectivity() -> None:
+    """Fail fast if the configured database is unreachable."""
+    async with engine.connect() as conn:
+        await conn.execute(text("SELECT 1"))
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    """Yield a transaction-capable async database session."""
+    async with SessionLocal() as session:
+        yield session
+
+
+async def get_read_session() -> AsyncGenerator[AsyncSession, None]:
+    """Yield a read-only session routed to the replica (or primary fallback)."""
+    async with ReadOnlySession() as session:
+        yield session