mcp-botnex 0.1.0__tar.gz

mcp_botnex-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: mcp-botnex
+Version: 0.1.0
+Summary: MCP Server for BotNEX - VAPT scans, reports and CVE intelligence for AI clients
+Author: BotNEX Team
+License: MIT
+Project-URL: Homepage, https://github.com/ivedha-tech/botnex-mcp-server
+Project-URL: Repository, https://github.com/ivedha-tech/botnex-mcp-server
+Project-URL: Documentation, https://github.com/ivedha-tech/botnex-mcp-server#readme
+Keywords: mcp,botnex,vapt,security,cve,vulnerability,model-context-protocol
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: uvicorn[standard]>=0.27.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
+
+# mcp-botnex
+
+MCP (Model Context Protocol) server for **BotNEX** — exposes VAPT scans,
+reports, and CVE intelligence to AI clients such as Cursor and the NEXA
+platform. It is a thin, secure bridge to the existing `botnex-backend` REST
+API and authenticates with a **user-scoped API token** (no JWT).
+
+## Features
+
+- **10 tools** for scan lifecycle, reports, and CVE lookup
+- **6 resources** (`botnex://…`) for `@`-mentionable context in Cursor
+- **Dual transport**: stdio (Cursor / Claude Desktop) and HTTP (NEXA / Docker)
+- **API-token auth** mapped per-user on the backend — RBAC enforced server-side
+- AI-friendly formatters (severity-first findings, normalized CVE output)
+
+## Installation
+
+```bash
+pip install mcp-botnex
+```
+
+## Authentication
+
+1. Log in to the BotNEX UI.
+2. Create an API token: **API Tokens → Create** (calls `POST /api/v1/users/api-tokens/`).
+3. Copy the raw token once and provide it to the MCP server via `BOTNEX_API_KEY`.
+
+The token is sent as `Authorization: Bearer <token>` on every backend request.
+The backend resolves it to your user account and enforces all authorization
+and per-user data scoping.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BOTNEX_BACKEND_URL` | Yes | – | Backend origin, e.g. `https://botnex.example.com` (no `/api/v1`) |
+| `BOTNEX_API_KEY` | Yes | – | User API token |
+| `BOTNEX_MCP_SERVER_PORT` | No | `8001` | HTTP mode port |
+| `BOTNEX_LOG_LEVEL` | No | `INFO` | Log level |
+| `BOTNEX_BACKEND_TIMEOUT` | No | `60.0` | Backend HTTP timeout (s) |
+| `BOTNEX_FINDINGS_PAGE_SIZE` | No | `50` | Default findings page size |
+
+See `.env.example` for the full list.
+
+## Usage — Cursor (stdio)
+
+Add to your Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "botnex": {
+      "command": "mcp-botnex",
+      "env": {
+        "BOTNEX_BACKEND_URL": "https://botnex.example.com",
+        "BOTNEX_API_KEY": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Usage — HTTP (NEXA / Docker)
+
+```bash
+mcp-botnex-http
+# or
+uvicorn app.http_server:app --host 0.0.0.0 --port 8001
+```
+
+Endpoints: `GET /mcp/tools`, `POST /mcp/tools/call`, `GET /mcp/resources`,
+`POST /mcp/resources/read`, `GET /health`.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_scans` | List the user's scans and statuses |
+| `trigger_scan` | Start a security or asset-discovery scan |
+| `get_scan_findings` | Paginated, severity-ordered findings for a scan |
+| `get_scan_summary` | Aggregated dashboard summary |
+| `list_scheduled_scans` | Upcoming scheduled scans |
+| `generate_report` | Generate a PDF/CSV/DOCX report |
+| `get_report` | Report metadata by id |
+| `search_cves` | Full-text CVE search |
+| `get_cve_by_id` | CVE detail by id |
+| `search_cves_by_vendor` | CVEs by vendor + version |
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `botnex://scans/all` | All scans |
+| `botnex://scans/summary` | Scan dashboard summary |
+| `botnex://scans/scheduled` | Scheduled scans |
+| `botnex://scan/{scan_id}/findings` | Findings for a scan |
+| `botnex://cve/{cve_id}` | CVE detail |
+| `botnex://cve/latest` | Latest CVEs |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

mcp_botnex-0.1.0/README.md

@@ -0,0 +1,109 @@
+# mcp-botnex
+
+MCP (Model Context Protocol) server for **BotNEX** — exposes VAPT scans,
+reports, and CVE intelligence to AI clients such as Cursor and the NEXA
+platform. It is a thin, secure bridge to the existing `botnex-backend` REST
+API and authenticates with a **user-scoped API token** (no JWT).
+
+## Features
+
+- **10 tools** for scan lifecycle, reports, and CVE lookup
+- **6 resources** (`botnex://…`) for `@`-mentionable context in Cursor
+- **Dual transport**: stdio (Cursor / Claude Desktop) and HTTP (NEXA / Docker)
+- **API-token auth** mapped per-user on the backend — RBAC enforced server-side
+- AI-friendly formatters (severity-first findings, normalized CVE output)
+
+## Installation
+
+```bash
+pip install mcp-botnex
+```
+
+## Authentication
+
+1. Log in to the BotNEX UI.
+2. Create an API token: **API Tokens → Create** (calls `POST /api/v1/users/api-tokens/`).
+3. Copy the raw token once and provide it to the MCP server via `BOTNEX_API_KEY`.
+
+The token is sent as `Authorization: Bearer <token>` on every backend request.
+The backend resolves it to your user account and enforces all authorization
+and per-user data scoping.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `BOTNEX_BACKEND_URL` | Yes | – | Backend origin, e.g. `https://botnex.example.com` (no `/api/v1`) |
+| `BOTNEX_API_KEY` | Yes | – | User API token |
+| `BOTNEX_MCP_SERVER_PORT` | No | `8001` | HTTP mode port |
+| `BOTNEX_LOG_LEVEL` | No | `INFO` | Log level |
+| `BOTNEX_BACKEND_TIMEOUT` | No | `60.0` | Backend HTTP timeout (s) |
+| `BOTNEX_FINDINGS_PAGE_SIZE` | No | `50` | Default findings page size |
+
+See `.env.example` for the full list.
+
+## Usage — Cursor (stdio)
+
+Add to your Cursor MCP config:
+
+```json
+{
+  "mcpServers": {
+    "botnex": {
+      "command": "mcp-botnex",
+      "env": {
+        "BOTNEX_BACKEND_URL": "https://botnex.example.com",
+        "BOTNEX_API_KEY": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Usage — HTTP (NEXA / Docker)
+
+```bash
+mcp-botnex-http
+# or
+uvicorn app.http_server:app --host 0.0.0.0 --port 8001
+```
+
+Endpoints: `GET /mcp/tools`, `POST /mcp/tools/call`, `GET /mcp/resources`,
+`POST /mcp/resources/read`, `GET /health`.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_scans` | List the user's scans and statuses |
+| `trigger_scan` | Start a security or asset-discovery scan |
+| `get_scan_findings` | Paginated, severity-ordered findings for a scan |
+| `get_scan_summary` | Aggregated dashboard summary |
+| `list_scheduled_scans` | Upcoming scheduled scans |
+| `generate_report` | Generate a PDF/CSV/DOCX report |
+| `get_report` | Report metadata by id |
+| `search_cves` | Full-text CVE search |
+| `get_cve_by_id` | CVE detail by id |
+| `search_cves_by_vendor` | CVEs by vendor + version |
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `botnex://scans/all` | All scans |
+| `botnex://scans/summary` | Scan dashboard summary |
+| `botnex://scans/scheduled` | Scheduled scans |
+| `botnex://scan/{scan_id}/findings` | Findings for a scan |
+| `botnex://cve/{cve_id}` | CVE detail |
+| `botnex://cve/latest` | Latest CVEs |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

mcp_botnex-0.1.0/app/__init__.py

@@ -0,0 +1,15 @@
+"""BotNEX MCP Server package.
+
+A Model Context Protocol bridge between AI clients (Cursor, NEXA) and the
+BotNEX backend. Exposes VAPT scans, reports and CVE intelligence as MCP tools
+and resources, authenticating to the backend with a user-scoped API token.
+"""
+
+from importlib import metadata
+
+try:
+    __version__ = metadata.version("mcp-botnex")
+except metadata.PackageNotFoundError:  # running from source without install
+    __version__ = "0.0.0+local"
+
+__all__ = ["__version__"]

mcp_botnex-0.1.0/app/client/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP client for the BotNEX backend."""
+
+from app.client.backend_client import BackendClient
+
+__all__ = ["BackendClient"]

mcp_botnex-0.1.0/app/client/backend_client.py

@@ -0,0 +1,270 @@
+"""Async HTTP client for the BotNEX backend.
+
+Authentication
+--------------
+Every request carries the user-scoped API token::
+
+    Authorization: Bearer <BOTNEX_API_KEY>
+
+The backend resolves the token to a user (``request.user``) and enforces both
+the API-token endpoint allowlist and per-user data scoping. The MCP server is
+therefore a thin proxy - it never makes authorization decisions itself.
+
+Error mapping
+-------------
+HTTP status codes are translated into the domain exception hierarchy so tools
+and resources can render safe, useful messages.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from app import __version__
+from app.core.config import Settings, get_settings
+from app.core.exceptions import (
+    AccessForbiddenError,
+    AuthenticationError,
+    BackendConnectionError,
+    CveNotFoundError,
+    MCPServerError,
+    ReportNotFoundError,
+    ScanNotFoundError,
+)
+from app.core.logging import get_logger, mask_token
+
+logger = get_logger(__name__)
+
+
+class BackendClient:
+    """Thin async wrapper over the BotNEX ``/api/v1`` REST API."""
+
+    def __init__(self, settings: Settings | None = None):
+        self.settings = settings or get_settings()
+        self._client: httpx.AsyncClient | None = None
+
+    # -- lifecycle ---------------------------------------------------------
+
+    async def _get_client(self) -> httpx.AsyncClient:
+        """Lazily build the shared httpx client after validating config."""
+        self.settings.require_backend_config()
+        if self._client is None:
+            self._client = httpx.AsyncClient(
+                base_url=self.settings.api_base_url,
+                timeout=self.settings.botnex_backend_timeout,
+                verify=self.settings.botnex_verify_ssl,
+                headers=self._default_headers(),
+            )
+            logger.info(
+                "Backend client initialised: %s (token=%s)",
+                self.settings.api_base_url,
+                mask_token(self.settings.botnex_api_key),
+            )
+        return self._client
+
+    def _default_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.settings.botnex_api_key.strip()}",
+            "Accept": "application/json",
+            "User-Agent": f"{self.settings.botnex_mcp_server_name}/{__version__}",
+        }
+
+    async def aclose(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+
+    async def __aenter__(self) -> "BackendClient":
+        await self._get_client()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    # -- request core ------------------------------------------------------
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: dict[str, Any] | None = None,
+        extra_headers: dict[str, str] | None = None,
+        not_found: type[MCPServerError] = ScanNotFoundError,
+        expect_binary: bool = False,
+    ) -> Any:
+        """Perform an HTTP request with retries and error mapping.
+
+        ``path`` is relative to ``/api/v1`` (e.g. ``"/scans/list"``).
+        Returns parsed JSON, or raw bytes when ``expect_binary`` is True.
+        """
+        client = await self._get_client()
+        attempts = max(1, self.settings.botnex_backend_retry_attempts)
+        last_exc: Exception | None = None
+
+        for attempt in range(1, attempts + 1):
+            try:
+                response = await client.request(
+                    method,
+                    path,
+                    params=params,
+                    json=json,
+                    headers=extra_headers,
+                )
+                return self._handle_response(
+                    response, not_found=not_found, expect_binary=expect_binary
+                )
+            except (httpx.ConnectError, httpx.ConnectTimeout, httpx.ReadTimeout) as exc:
+                last_exc = exc
+                logger.warning(
+                    "Backend %s %s failed (attempt %d/%d): %s",
+                    method,
+                    path,
+                    attempt,
+                    attempts,
+                    exc,
+                )
+                if attempt < attempts:
+                    await asyncio.sleep(self.settings.botnex_backend_retry_delay * attempt)
+                    continue
+                raise BackendConnectionError(
+                    "Could not reach the BotNEX backend. Verify BOTNEX_BACKEND_URL "
+                    "and that the service is reachable."
+                ) from exc
+            except httpx.HTTPError as exc:
+                # Non-retryable transport error.
+                raise BackendConnectionError(f"HTTP transport error: {exc}") from exc
+
+        # Should be unreachable, but keep the type checker happy.
+        raise BackendConnectionError(str(last_exc) if last_exc else "Unknown error")
+
+    def _handle_response(
+        self,
+        response: httpx.Response,
+        *,
+        not_found: type[MCPServerError],
+        expect_binary: bool,
+    ) -> Any:
+        status = response.status_code
+
+        if status == 401:
+            raise AuthenticationError(
+                "The API token is invalid, expired, or revoked. Create a new "
+                "token in the BotNEX UI."
+            )
+        if status == 403:
+            raise AccessForbiddenError(
+                "This API token is not permitted to access the requested "
+                "resource."
+            )
+        if status == 404:
+            raise not_found("The requested item does not exist or is not "
+                            "accessible with this token.")
+        if status == 429:
+            raise BackendConnectionError(
+                "Rate limit exceeded on the BotNEX backend. Try again later."
+            )
+        if status >= 500:
+            raise BackendConnectionError(
+                f"BotNEX backend returned a server error ({status})."
+            )
+        if status >= 400:
+            raise MCPServerError(self._extract_error_message(response, status))
+
+        if expect_binary:
+            return response.content
+        if not response.content:
+            return {}
+        try:
+            return response.json()
+        except ValueError:
+            return {"raw": response.text}
+
+    @staticmethod
+    def _extract_error_message(response: httpx.Response, status: int) -> str:
+        try:
+            body = response.json()
+            if isinstance(body, dict):
+                for key in ("message", "error", "detail"):
+                    if body.get(key):
+                        return str(body[key])
+        except ValueError:
+            pass
+        return f"Request failed with status {status}."
+
+    # -- convenience verbs -------------------------------------------------
+
+    async def get(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs: Any) -> Any:
+        return await self.request("POST", path, **kwargs)
+
+    # ======================================================================
+    # Domain methods (one per backend endpoint used by the MCP surface)
+    # ======================================================================
+
+    # --- scans ---
+    async def list_scans(self) -> Any:
+        return await self.get("/scans/list")
+
+    async def trigger_scan(
+        self, payload: dict[str, Any], *, idempotency_key: str | None = None
+    ) -> Any:
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        return await self.post("/scans/scan", json=payload, extra_headers=headers)
+
+    async def get_scan_report(self, payload: dict[str, Any]) -> Any:
+        return await self.post("/scans/report", json=payload)
+
+    async def get_scan_summary(self) -> Any:
+        return await self.get("/scans/summary/")
+
+    async def list_scheduled_scans(self) -> Any:
+        return await self.get("/scans/scheduled/")
+
+    # --- reports ---
+    async def generate_report(self, payload: dict[str, Any]) -> bytes:
+        return await self.post(
+            "/reports/report",
+            json=payload,
+            not_found=ReportNotFoundError,
+            expect_binary=True,
+        )
+
+    async def get_report_metadata(self, report_id: str) -> Any:
+        return await self.get(
+            f"/reports/{report_id}", not_found=ReportNotFoundError
+        )
+
+    # --- cve ---
+    async def search_cves(self, search_term: str) -> Any:
+        return await self.get(
+            "/cve/search/all_fields/",
+            params={"search_term": search_term},
+            not_found=CveNotFoundError,
+        )
+
+    async def get_cve_by_id(self, cve_id: str) -> Any:
+        return await self.get(
+            f"/cve/searchid/{cve_id}/", not_found=CveNotFoundError
+        )
+
+    async def search_cves_by_vendor(self, vendor: str, version: str) -> Any:
+        return await self.get(
+            "/cve/search/",
+            params={"vendor": vendor, "version": version},
+            not_found=CveNotFoundError,
+        )
+
+    async def get_latest_cves(self) -> Any:
+        return await self.get("/cve/search/latest/", not_found=CveNotFoundError)
+
+    # --- identity ---
+    async def verify_token(self) -> Any:
+        """Return the authenticated user's identity (verify connection)."""
+        return await self.get("/users/token/verification")

mcp_botnex-0.1.0/app/core/__init__.py

@@ -0,0 +1 @@
+"""Core configuration, exceptions and registry for the BotNEX MCP server."""

mcp_botnex-0.1.0/app/core/config.py

@@ -0,0 +1,83 @@
+"""Application settings.
+
+Settings load from environment variables (and a local ``.env`` file when
+present). Validation of required values is *lazy*: the server must start even
+when ``BOTNEX_BACKEND_URL`` / ``BOTNEX_API_KEY`` are missing, because host
+platforms (NEXA, K8s) may inject configuration late or spawn the process just
+to list tools. The first backend call raises a clear, actionable error
+instead.
+
+``extra="ignore"`` ensures unrelated platform environment variables never
+crash the server.
+"""
+
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from app.core.exceptions import ConfigurationError
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # Required for backend access (lazy-validated).
+    botnex_backend_url: str = ""
+    botnex_api_key: str = ""
+
+    # Server identity.
+    botnex_mcp_server_name: str = "botnex-mcp-server"
+    botnex_mcp_server_port: int = 8001
+
+    # Logging.
+    botnex_log_level: str = "INFO"
+
+    # Backend HTTP behaviour. Report generation can be slow, default generous.
+    botnex_backend_timeout: float = 60.0
+    botnex_backend_retry_attempts: int = 3
+    botnex_backend_retry_delay: float = 1.0
+    botnex_verify_ssl: bool = True
+
+    # Output caps (keep LLM context manageable).
+    botnex_findings_page_size: int = 50
+    botnex_cve_result_limit: int = 25
+
+    @property
+    def backend_origin(self) -> str:
+        """Backend origin without trailing slash."""
+        return self.botnex_backend_url.strip().rstrip("/")
+
+    @property
+    def api_base_url(self) -> str:
+        """Full ``/api/v1`` base used by the backend client."""
+        return f"{self.backend_origin}/api/v1"
+
+    def require_backend_config(self) -> None:
+        """Raise ConfigurationError when backend credentials are missing.
+
+        Called by the backend client before the first request, never at
+        process start.
+        """
+        missing = []
+        if not self.botnex_backend_url.strip():
+            missing.append("BOTNEX_BACKEND_URL")
+        if not self.botnex_api_key.strip():
+            missing.append("BOTNEX_API_KEY")
+        if missing:
+            raise ConfigurationError(
+                "Missing required environment variable(s): "
+                + ", ".join(missing)
+                + ". Set the BotNEX backend URL and a user API token "
+                "(create one in the BotNEX UI under API Tokens)."
+            )
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Return a cached Settings instance."""
+    return Settings()