malwar 0.2.1__py3-none-any.whl

malwar/__init__.py

@@ -0,0 +1,25 @@
+# Copyright (c) 2026 Veritas Aequitas Holdings LLC. All rights reserved.
+"""malwar - Malware detection engine for agentic skills."""
+
+__version__ = "0.1.0"
+
+from malwar.integrations.exceptions import MalwarBlockedError
+from malwar.integrations.langchain import (
+    MalwarCallbackHandler,
+    MalwarGuard,
+    MalwarScanTool,
+)
+from malwar.sdk import scan, scan_batch, scan_file, scan_file_sync, scan_sync
+
+__all__ = [
+    "MalwarBlockedError",
+    "MalwarCallbackHandler",
+    "MalwarGuard",
+    "MalwarScanTool",
+    "__version__",
+    "scan",
+    "scan_batch",
+    "scan_file",
+    "scan_file_sync",
+    "scan_sync",
+]

malwar/__main__.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2026 Veritas Aequitas Holdings LLC. All rights reserved.
+"""Allow running malwar as a module: python -m malwar."""
+
+from malwar.cli.app import app
+
+app()

malwar/api/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) 2026 Veritas Aequitas Holdings LLC. All rights reserved.

malwar/api/app.py

@@ -0,0 +1,90 @@
+# Copyright (c) 2026 Veritas Aequitas Holdings LLC. All rights reserved.
+"""FastAPI application factory."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from malwar.api.middleware import RateLimitMiddleware, RequestMiddleware, UsageLoggingMiddleware
+from malwar.api.routes import (
+    analytics,
+    campaigns,
+    export,
+    feed,
+    health,
+    ingest,
+    reports,
+    scan,
+    signatures,
+)
+
+_WEB_DIST = Path(__file__).resolve().parent.parent.parent.parent / "web" / "dist"
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None]:
+    from malwar.core.config import get_settings
+    from malwar.storage.database import close_db, init_db
+
+    settings = get_settings()
+    await init_db(settings.db_path, auto_migrate=settings.auto_migrate)
+    yield
+    await close_db()
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="malwar",
+        description="Malware detection engine for agentic skills",
+        version="0.1.0",
+        lifespan=lifespan,
+        docs_url="/api/docs",
+        redoc_url="/api/redoc",
+        openapi_url="/api/openapi.json",
+    )
+
+    # CORS for development (Vite dev server)
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["http://localhost:3000"],
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(health.router, prefix="/api/v1", tags=["health"])
+    app.include_router(scan.router, prefix="/api/v1", tags=["scan"])
+    app.include_router(campaigns.router, prefix="/api/v1", tags=["campaigns"])
+    app.include_router(signatures.router, prefix="/api/v1", tags=["signatures"])
+    app.include_router(reports.router, prefix="/api/v1", tags=["reports"])
+    app.include_router(feed.router, prefix="/api/v1", tags=["feed"])
+    app.include_router(analytics.router, prefix="/api/v1", tags=["analytics"])
+    app.include_router(export.router, prefix="/api/v1", tags=["export"])
+    app.include_router(ingest.router, prefix="/api/v1", tags=["ingest"])
+    app.add_middleware(UsageLoggingMiddleware)
+    app.add_middleware(RequestMiddleware)
+    app.add_middleware(RateLimitMiddleware)
+
+    # Serve frontend in production (when web/dist exists)
+    if _WEB_DIST.is_dir():
+        _index = str(_WEB_DIST / "index.html")
+
+        # Mount static files for assets
+        app.mount("/assets", StaticFiles(directory=str(_WEB_DIST / "assets")), name="assets")
+
+        # Catch-all for SPA client-side routes
+        @app.api_route("/{path:path}", methods=["GET"], include_in_schema=False)
+        async def _spa_fallback(request: Request, path: str) -> FileResponse:
+            # Serve actual static files if they exist (favicon, vite.svg, etc.)
+            static_file = _WEB_DIST / path
+            if path and static_file.is_file():
+                return FileResponse(str(static_file))
+            return FileResponse(_index)
+
+    return app

malwar/api/auth.py

@@ -0,0 +1,35 @@
+# Copyright (c) 2026 Veritas Aequitas Holdings LLC. All rights reserved.
+"""API key authentication dependency."""
+
+from __future__ import annotations
+
+from fastapi import HTTPException, Security
+from fastapi.security import APIKeyHeader
+
+from malwar.core.config import get_settings
+
+_api_key_header = APIKeyHeader(name="X-API-Key", auto_error=False)
+
+
+async def require_api_key(
+    api_key: str | None = Security(_api_key_header),
+) -> str:
+    """Validate the X-API-Key header.
+
+    If no API keys are configured in settings, authentication is disabled
+    (open access). Otherwise the provided key must match one of the
+    configured keys.
+    """
+    settings = get_settings()
+
+    # No keys configured = auth disabled
+    if not settings.api_keys:
+        return "anonymous"
+
+    if not api_key:
+        raise HTTPException(status_code=401, detail="Missing X-API-Key header")
+
+    if api_key not in settings.api_keys:
+        raise HTTPException(status_code=403, detail="Invalid API key")
+
+    return api_key

malwar/api/middleware.py

@@ -0,0 +1,181 @@
+# Copyright (c) 2026 Veritas Aequitas Holdings LLC. All rights reserved.
+"""Request middleware for logging, request ID tracking, rate limiting, and usage metering."""
+
+from __future__ import annotations
+
+import logging
+import time
+import uuid
+from collections import defaultdict
+from datetime import UTC, datetime
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+from malwar.core.config import get_settings
+
+logger = logging.getLogger("malwar.api.middleware")
+
+# ---------------------------------------------------------------------------
+# Rate-limit state (in-memory, per-process)
+# ---------------------------------------------------------------------------
+_request_log: dict[str, list[float]] = defaultdict(list)
+_CLEANUP_INTERVAL = 60.0  # seconds between full sweeps
+_last_cleanup: float = 0.0
+
+_RATE_LIMIT_SKIP_PATHS: set[str] = {"/api/v1/health"}
+
+
+def _cleanup_old_entries(now: float, window: float) -> None:
+    """Remove timestamps older than *window* seconds for every tracked key."""
+    global _last_cleanup
+    expired_keys: list[str] = []
+    for key, timestamps in _request_log.items():
+        _request_log[key] = [t for t in timestamps if now - t < window]
+        if not _request_log[key]:
+            expired_keys.append(key)
+    for key in expired_keys:
+        del _request_log[key]
+    _last_cleanup = now
+
+
+class RateLimitMiddleware(BaseHTTPMiddleware):
+    """In-memory rate limiter with per-API-key and per-IP support.
+
+    * Authenticated requests (with ``X-API-Key`` header): limited to
+      ``rate_limit_per_key`` requests per minute (default 600).
+    * Unauthenticated requests: limited to ``rate_limit_per_ip`` requests
+      per minute (default 60), keyed by client IP.
+    * Returns **429 Too Many Requests** with a ``Retry-After`` header.
+    * Adds ``X-RateLimit-Limit``, ``X-RateLimit-Remaining``, and
+      ``X-RateLimit-Reset`` headers on all responses.
+    * Skips the ``/api/v1/health`` endpoint.
+    """
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        if request.url.path in _RATE_LIMIT_SKIP_PATHS:
+            return await call_next(request)
+
+        settings = get_settings()
+        window = 60.0  # seconds
+
+        # Determine identity and limit: API key takes precedence over IP
+        api_key = request.headers.get("X-API-Key")
+        if api_key:
+            identity = f"key:{api_key}"
+            limit = settings.rate_limit_per_key
+        else:
+            client_ip = request.client.host if request.client else "unknown"
+            identity = f"ip:{client_ip}"
+            limit = settings.rate_limit_per_ip
+
+        now = time.monotonic()
+
+        # Periodic cleanup to avoid memory leaks
+        global _last_cleanup
+        if now - _last_cleanup > _CLEANUP_INTERVAL:
+            _cleanup_old_entries(now, window)
+
+        # Prune this identity's old timestamps
+        timestamps = _request_log[identity]
+        _request_log[identity] = [t for t in timestamps if now - t < window]
+        timestamps = _request_log[identity]
+
+        remaining = max(0, limit - len(timestamps))
+        # Compute seconds until the oldest request in the window expires
+        if timestamps:
+            oldest = min(timestamps)
+            reset_seconds = int(window - (now - oldest)) + 1
+        else:
+            reset_seconds = int(window)
+
+        if len(timestamps) >= limit:
+            return JSONResponse(
+                status_code=429,
+                content={"detail": "Rate limit exceeded"},
+                headers={
+                    "Retry-After": str(reset_seconds),
+                    "X-RateLimit-Limit": str(limit),
+                    "X-RateLimit-Remaining": "0",
+                    "X-RateLimit-Reset": str(reset_seconds),
+                },
+            )
+
+        timestamps.append(now)
+        remaining = max(0, limit - len(timestamps))
+
+        response = await call_next(request)
+
+        # Add rate-limit headers to every successful response
+        response.headers["X-RateLimit-Limit"] = str(limit)
+        response.headers["X-RateLimit-Remaining"] = str(remaining)
+        response.headers["X-RateLimit-Reset"] = str(reset_seconds)
+
+        return response
+
+
+class UsageLoggingMiddleware(BaseHTTPMiddleware):
+    """Logs API usage to the ``api_usage`` table after each request.
+
+    Gracefully degrades: if the table does not exist (migration not yet
+    applied), the error is silently swallowed so the request still succeeds.
+    """
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        response = await call_next(request)
+
+        # Fire-and-forget usage logging; never block the response
+        try:
+            api_key = request.headers.get("X-API-Key", "")
+            endpoint = request.url.path
+            method = request.method
+            status_code = response.status_code
+            timestamp = datetime.now(UTC).isoformat()
+
+            from malwar.storage.database import get_db
+
+            db = await get_db()
+            await db.execute(
+                """
+                INSERT INTO api_usage (api_key, endpoint, method, status_code, timestamp)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (api_key, endpoint, method, status_code, timestamp),
+            )
+            await db.commit()
+        except Exception:
+            # Graceful degradation: table may not exist yet, DB may not be
+            # initialized, etc.  Never let usage logging break the request.
+            pass
+
+        return response
+
+
+class RequestMiddleware(BaseHTTPMiddleware):
+    """Adds request logging and X-Request-ID header to every response."""
+
+    async def dispatch(
+        self, request: Request, call_next: RequestResponseEndpoint
+    ) -> Response:
+        request_id = uuid.uuid4().hex
+        start = time.monotonic()
+
+        response = await call_next(request)
+
+        duration_ms = round((time.monotonic() - start) * 1000, 1)
+        response.headers["X-Request-ID"] = request_id
+
+        logger.info(
+            "%s %s %s %.1fms",
+            request.method,
+            request.url.path,
+            response.status_code,
+            duration_ms,
+        )
+
+        return response

malwar/api/routes/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) 2026 Veritas Aequitas Holdings LLC. All rights reserved.

malwar/api/routes/analytics.py

@@ -0,0 +1,166 @@
+# Copyright (c) 2026 Veritas Aequitas Holdings LLC. All rights reserved.
+"""Analytics API endpoints for API usage metering."""
+
+from __future__ import annotations
+
+import logging
+from datetime import date
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+
+from malwar.api.auth import require_api_key
+
+logger = logging.getLogger("malwar.api.analytics")
+
+router = APIRouter()
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+
+class DailyBucket(BaseModel):
+    date: str
+    count: int
+
+
+class EndpointCount(BaseModel):
+    endpoint: str
+    count: int
+
+
+class VerdictCount(BaseModel):
+    verdict: str
+    count: int
+
+
+class AnalyticsResponse(BaseModel):
+    total_requests: int
+    requests_by_endpoint: list[EndpointCount]
+    requests_by_verdict: list[VerdictCount]
+    requests_over_time: list[DailyBucket]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+async def _table_exists(db: object, table_name: str) -> bool:
+    """Check whether *table_name* exists in the database."""
+    cursor = await db.execute(  # type: ignore[attr-defined]
+        "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+        (table_name,),
+    )
+    return await cursor.fetchone() is not None
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.get("/analytics", response_model=AnalyticsResponse)
+async def get_analytics(
+    start_date: date | None = Query(default=None, description="Start date (YYYY-MM-DD)"),  # noqa: B008
+    end_date: date | None = Query(default=None, description="End date (YYYY-MM-DD)"),  # noqa: B008
+    api_key: str | None = Query(default=None, description="Filter by API key"),
+    _auth_key: str = Depends(require_api_key),
+) -> AnalyticsResponse:
+    """Return API usage statistics.
+
+    Supports optional filtering by date range and API key.
+    Returns empty stats if the ``api_usage`` table has not been created yet.
+    """
+    from malwar.storage.database import get_db
+
+    db = await get_db()
+
+    # Graceful degradation: if table doesn't exist, return empty stats
+    if not await _table_exists(db, "api_usage"):
+        return AnalyticsResponse(
+            total_requests=0,
+            requests_by_endpoint=[],
+            requests_by_verdict=[],
+            requests_over_time=[],
+        )
+
+    # Build WHERE clause dynamically
+    conditions: list[str] = []
+    params: list[str] = []
+
+    if start_date is not None:
+        conditions.append("timestamp >= ?")
+        params.append(start_date.isoformat())
+    if end_date is not None:
+        conditions.append("timestamp < date(?, '+1 day')")
+        params.append(end_date.isoformat())
+    if api_key is not None:
+        conditions.append("api_key = ?")
+        params.append(api_key)
+
+    where = (" WHERE " + " AND ".join(conditions)) if conditions else ""
+
+    # Total requests
+    cursor = await db.execute(
+        f"SELECT COUNT(*) FROM api_usage{where}", params  # noqa: S608
+    )
+    row = await cursor.fetchone()
+    total_requests = row[0] if row else 0
+
+    # Requests by endpoint
+    cursor = await db.execute(
+        f"SELECT endpoint, COUNT(*) AS cnt FROM api_usage{where} GROUP BY endpoint ORDER BY cnt DESC",  # noqa: S608
+        params,
+    )
+    endpoint_rows = await cursor.fetchall()
+    requests_by_endpoint = [
+        EndpointCount(endpoint=r[0], count=r[1]) for r in endpoint_rows
+    ]
+
+    # Requests by verdict -- join with scans table via endpoint pattern
+    # We track the scan endpoint's status_code; for verdict we need to
+    # correlate with the scans table.  A simpler approach: count by status_code
+    # group in the usage table.  However, the issue specifies "by verdict".
+    # We join api_usage rows that hit /api/v1/scan (POST) with scans to get
+    # verdicts.  For simplicity, we count verdicts from the scans table
+    # directly, applying the same date/key filters where possible.
+    verdict_conditions: list[str] = []
+    verdict_params: list[str] = []
+    if start_date is not None:
+        verdict_conditions.append("created_at >= ?")
+        verdict_params.append(start_date.isoformat())
+    if end_date is not None:
+        verdict_conditions.append("created_at < date(?, '+1 day')")
+        verdict_params.append(end_date.isoformat())
+    verdict_where = (
+        (" WHERE " + " AND ".join(verdict_conditions)) if verdict_conditions else ""
+    )
+
+    cursor = await db.execute(
+        f"SELECT verdict, COUNT(*) AS cnt FROM scans{verdict_where} GROUP BY verdict ORDER BY cnt DESC",  # noqa: S608
+        verdict_params,
+    )
+    verdict_rows = await cursor.fetchall()
+    requests_by_verdict = [
+        VerdictCount(verdict=r[0], count=r[1]) for r in verdict_rows
+    ]
+
+    # Requests over time (daily buckets)
+    cursor = await db.execute(
+        f"SELECT date(timestamp) AS day, COUNT(*) AS cnt FROM api_usage{where} GROUP BY day ORDER BY day",  # noqa: S608
+        params,
+    )
+    time_rows = await cursor.fetchall()
+    requests_over_time = [
+        DailyBucket(date=r[0], count=r[1]) for r in time_rows
+    ]
+
+    return AnalyticsResponse(
+        total_requests=total_requests,
+        requests_by_endpoint=requests_by_endpoint,
+        requests_by_verdict=requests_by_verdict,
+        requests_over_time=requests_over_time,
+    )

malwar/api/routes/campaigns.py

@@ -0,0 +1,115 @@
+# Copyright (c) 2026 Veritas Aequitas Holdings LLC. All rights reserved.
+"""Campaign API endpoints."""
+
+from __future__ import annotations
+
+import json
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from malwar.api.auth import require_api_key
+
+router = APIRouter()
+
+
+# ---------------------------------------------------------------------------
+# Response models
+# ---------------------------------------------------------------------------
+
+
+class CampaignResponse(BaseModel):
+    id: str
+    name: str
+    description: str
+    first_seen: str
+    last_seen: str
+    attributed_to: str | None = None
+    iocs: list[str]
+    total_skills_affected: int
+    status: str
+
+
+class CampaignDetailResponse(CampaignResponse):
+    signature_count: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _row_to_response(row: dict) -> CampaignResponse:
+    iocs_raw = row.get("iocs", "[]")
+    iocs = json.loads(iocs_raw) if isinstance(iocs_raw, str) else iocs_raw
+    return CampaignResponse(
+        id=row["id"],
+        name=row["name"],
+        description=row["description"],
+        first_seen=row["first_seen"],
+        last_seen=row["last_seen"],
+        attributed_to=row.get("attributed_to"),
+        iocs=iocs,
+        total_skills_affected=row.get("total_skills_affected", 0),
+        status=row["status"],
+    )
+
+
+# ---------------------------------------------------------------------------
+# Endpoints
+# ---------------------------------------------------------------------------
+
+
+@router.get("/campaigns", response_model=list[CampaignResponse])
+async def list_campaigns(
+    _api_key: str = Depends(require_api_key),
+) -> list[CampaignResponse]:
+    """List all active campaigns."""
+    from malwar.storage.database import get_db
+    from malwar.storage.repositories.campaigns import CampaignRepository
+
+    db = await get_db()
+    repo = CampaignRepository(db)
+    rows = await repo.list_active()
+    return [_row_to_response(row) for row in rows]
+
+
+@router.get("/campaigns/{campaign_id}", response_model=CampaignDetailResponse)
+async def get_campaign(
+    campaign_id: str,
+    _api_key: str = Depends(require_api_key),
+) -> CampaignDetailResponse:
+    """Retrieve a single campaign with details."""
+    from malwar.storage.database import get_db
+    from malwar.storage.repositories.campaigns import CampaignRepository
+
+    db = await get_db()
+    repo = CampaignRepository(db)
+    row = await repo.get(campaign_id)
+    if row is None:
+        raise HTTPException(
+            status_code=404, detail=f"Campaign {campaign_id} not found"
+        )
+
+    iocs_raw = row.get("iocs", "[]")
+    iocs = json.loads(iocs_raw) if isinstance(iocs_raw, str) else iocs_raw
+
+    # Count associated signatures
+    cursor = await db.execute(
+        "SELECT COUNT(*) FROM signatures WHERE campaign_id = ?", (campaign_id,)
+    )
+    count_row = await cursor.fetchone()
+    signature_count = count_row[0] if count_row else 0
+
+    return CampaignDetailResponse(
+        id=row["id"],
+        name=row["name"],
+        description=row["description"],
+        first_seen=row["first_seen"],
+        last_seen=row["last_seen"],
+        attributed_to=row.get("attributed_to"),
+        iocs=iocs,
+        total_skills_affected=row.get("total_skills_affected", 0),
+        status=row["status"],
+        signature_count=signature_count,
+    )