vulnotes 0.1.0__py3-none-any.whl

vulnotes/__init__.py

@@ -0,0 +1,42 @@
+"""Official Python SDK for the Vulnotes API.
+
+Usage:
+    >>> from vulnotes import VulnotesClient
+    >>> client = VulnotesClient("https://acme.vulnotes.app", api_key="...")
+    >>> report = client.reports.create("External pentest Q3")
+    >>> client.findings.add(report["_id"], {"title": "Open SSH port"})
+"""
+
+from ._version import __version__
+from .client import VulnotesClient
+from .exceptions import (
+    APIConnectionError,
+    APIStatusError,
+    APITimeoutError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    UnprocessableEntityError,
+    VulnotesError,
+)
+
+__all__ = [
+    "__version__",
+    "VulnotesClient",
+    "VulnotesError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "ServerError",
+]

vulnotes/_utils.py

@@ -0,0 +1,65 @@
+"""Internal helpers shared by the resource modules."""
+
+from __future__ import annotations
+
+import datetime as _dt
+import io
+import mimetypes
+import os
+from typing import Any, Union
+
+# A file argument may be a filesystem path, raw bytes, an open file object,
+# or a (filename, fileobj_or_bytes) / (filename, fileobj_or_bytes, content_type) tuple.
+FileTypes = Union[str, "os.PathLike[str]", bytes, io.IOBase, tuple]
+
+
+def omit_none(mapping: dict[str, Any]) -> dict[str, Any]:
+    """Drop keys whose value is ``None`` (the API treats absent fields as unchanged)."""
+    return {k: v for k, v in mapping.items() if v is not None}
+
+
+def iso(value: str | _dt.date | _dt.datetime | None) -> str | None:
+    """Convert a date/datetime to an ISO-8601 string; pass strings and None through."""
+    if value is None or isinstance(value, str):
+        return value
+    if isinstance(value, _dt.datetime):
+        return value.isoformat()
+    if isinstance(value, _dt.date):
+        return value.isoformat()
+    raise TypeError(f"expected str, date or datetime, got {type(value).__name__}")
+
+
+def _with_content_type(filename: str, payload: Any) -> tuple:
+    """Attach a guessed Content-Type so server-side upload filters (which
+    check the part's MIME type, not the filename) accept the file."""
+    content_type = mimetypes.guess_type(filename)[0]
+    if content_type:
+        return (filename, payload, content_type)
+    return (filename, payload)
+
+
+def prepare_file(file: FileTypes, default_name: str = "upload") -> tuple:
+    """Normalize a user-supplied file argument into a (filename, payload[, type]) tuple
+    suitable for the ``files=`` parameter of requests."""
+    if isinstance(file, tuple):
+        if len(file) == 2:
+            return _with_content_type(file[0], file[1])
+        return file  # already (filename, fileobj, content_type)
+    if isinstance(file, bytes):
+        return _with_content_type(default_name, file)
+    if isinstance(file, (str, os.PathLike)):
+        path = os.fspath(file)
+        return _with_content_type(os.path.basename(path), open(path, "rb"))
+    # file-like object
+    name = getattr(file, "name", None)
+    if isinstance(name, str) and name and not name.startswith("<"):
+        return _with_content_type(os.path.basename(name), file)
+    return _with_content_type(default_name, file)
+
+
+def write_bytes(content: bytes, path: str | os.PathLike[str]) -> str:
+    """Write binary content to *path* and return the path as a string."""
+    path = os.fspath(path)
+    with open(path, "wb") as fh:
+        fh.write(content)
+    return path

vulnotes/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

vulnotes/client.py

@@ -0,0 +1,228 @@
+"""The Vulnotes API client."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from ._version import __version__
+from .exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    VulnotesError,
+    error_for_status,
+)
+from .resources.ai import AI
+from .resources.api_keys import APIKeys
+from .resources.attachments import Attachments
+from .resources.comments import Comments
+from .resources.companies import Companies
+from .resources.findings import Findings
+from .resources.images import Images
+from .resources.notes import Notes
+from .resources.planning import Planning
+from .resources.report_templates import ReportTemplates
+from .resources.reports import Reports
+from .resources.snapshots import Snapshots
+from .resources.vulnerabilities import Vulnerabilities
+from .resources.vulnerability_templates import VulnerabilityTemplates
+
+__all__ = ["VulnotesClient"]
+
+_RETRYABLE_METHODS = frozenset(["GET", "HEAD", "OPTIONS", "PUT", "DELETE"])
+
+
+class VulnotesClient:
+    """Client for the Vulnotes REST API.
+
+    Authentication uses an API key (created in **Settings → API Keys** inside
+    Vulnotes) sent via the ``X-API-Key`` header. The key carries an explicit
+    set of permissions and can never exceed what its owner may do.
+
+    Args:
+        base_url: Root URL of your Vulnotes instance, e.g.
+            ``https://acme.vulnotes.app``. A trailing ``/api`` is added
+            automatically if not present. Falls back to the ``VULNOTES_URL``
+            environment variable.
+        api_key: Your API key. Falls back to the ``VULNOTES_API_KEY``
+            environment variable.
+        timeout: Default per-request timeout in seconds (connect + read).
+        verify_ssl: Set to ``False`` to skip TLS certificate verification
+            (only for lab instances with self-signed certificates).
+        max_retries: Automatic retries for idempotent requests that fail with
+            a connection error or a 429/502/503/504 status.
+        session: Optionally supply a pre-configured ``requests.Session``.
+
+    Example:
+        >>> from vulnotes import VulnotesClient
+        >>> client = VulnotesClient("https://acme.vulnotes.app", api_key="...")
+        >>> for report in client.reports.iter():
+        ...     print(report["title"])
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        *,
+        timeout: float = 30.0,
+        verify_ssl: bool = True,
+        max_retries: int = 3,
+        session: requests.Session | None = None,
+    ) -> None:
+        base_url = base_url or os.environ.get("VULNOTES_URL")
+        api_key = api_key or os.environ.get("VULNOTES_API_KEY")
+        if not base_url:
+            raise VulnotesError(
+                "No base_url provided. Pass it to VulnotesClient(...) or set the "
+                "VULNOTES_URL environment variable."
+            )
+        if not api_key:
+            raise VulnotesError(
+                "No api_key provided. Create one in Settings → API Keys, then pass "
+                "it to VulnotesClient(...) or set the VULNOTES_API_KEY environment variable."
+            )
+
+        base_url = base_url.rstrip("/")
+        if not base_url.endswith("/api"):
+            base_url += "/api"
+        self.base_url = base_url
+        self.timeout = timeout
+
+        self._session = session or requests.Session()
+        self._session.verify = verify_ssl
+        self._session.headers["X-API-Key"] = api_key
+        self._session.headers["User-Agent"] = f"vulnotes-python/{__version__}"
+        if max_retries:
+            retry = Retry(
+                total=max_retries,
+                connect=max_retries,
+                read=max_retries,
+                status=max_retries,
+                backoff_factor=0.5,
+                status_forcelist=(429, 502, 503, 504),
+                allowed_methods=_RETRYABLE_METHODS,
+                raise_on_status=False,
+            )
+            adapter = HTTPAdapter(max_retries=retry)
+            self._session.mount("https://", adapter)
+            self._session.mount("http://", adapter)
+
+        # Resource namespaces
+        self.companies = Companies(self)
+        self.templates = ReportTemplates(self)
+        self.vulnerability_templates = VulnerabilityTemplates(self)
+        self.vulnerabilities = Vulnerabilities(self)
+        self.reports = Reports(self)
+        self.findings = Findings(self)
+        self.snapshots = Snapshots(self)
+        self.comments = Comments(self)
+        self.notes = Notes(self)
+        self.images = Images(self)
+        self.attachments = Attachments(self)
+        self.ai = AI(self)
+        self.planning = Planning(self)
+        self.api_keys = APIKeys(self)
+
+    # ── low-level request machinery ──────────────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: dict[str, Any] | None = None,
+        files: dict[str, Any] | None = None,
+        raw: bool = False,
+        timeout: float | None = None,
+    ) -> Any:
+        """Perform an HTTP request against the API.
+
+        This is the escape hatch for endpoints not (yet) wrapped by a resource
+        method: ``client.request("GET", "/reports")``.
+
+        Returns the parsed JSON body, raw ``bytes`` when ``raw=True``, or
+        ``None`` for empty responses. Some endpoints wrap their payload in a
+        ``{"success": true, "data": ...}`` envelope; those are transparently
+        unwrapped so every method returns the entity itself. Raises a subclass
+        of :class:`~vulnotes.exceptions.VulnotesError` on failure.
+        """
+        url = self.base_url + (path if path.startswith("/") else "/" + path)
+        try:
+            resp = self._session.request(
+                method,
+                url,
+                params=params,
+                json=json,
+                data=data,
+                files=files,
+                timeout=timeout if timeout is not None else self.timeout,
+            )
+        except requests.Timeout as exc:
+            raise APITimeoutError(f"Request to {url} timed out") from exc
+        except requests.RequestException as exc:
+            raise APIConnectionError(f"Could not reach {url}: {exc}") from exc
+
+        if not resp.ok:
+            body: Any = None
+            try:
+                body = resp.json()
+            except ValueError:
+                pass
+            if isinstance(body, dict):
+                message = body.get("message") or body.get("error") or resp.text
+            else:
+                message = resp.text or resp.reason
+            raise error_for_status(resp.status_code, str(message), body=body, response=resp)
+
+        if raw:
+            return resp.content
+        if resp.status_code == 204 or not resp.content:
+            return None
+        content_type = resp.headers.get("Content-Type", "")
+        if "application/json" in content_type:
+            payload = resp.json()
+            # Normalize the {"success": true, "data": ...} envelope some
+            # endpoints use, so callers always get the entity itself.
+            # Paginated envelopes carry a "pagination" key and stay intact.
+            if (
+                isinstance(payload, dict)
+                and "data" in payload
+                and set(payload) <= {"success", "data", "message"}
+            ):
+                return payload["data"]
+            return payload
+        return resp.content
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        return self.request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> Any:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        return self.request("DELETE", path, **kwargs)
+
+    # ── lifecycle ────────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        """Release the underlying HTTP connection pool."""
+        self._session.close()
+
+    def __enter__(self) -> VulnotesClient:
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()

vulnotes/exceptions.py

@@ -0,0 +1,122 @@
+"""Exception hierarchy for the Vulnotes SDK.
+
+All exceptions raised by the SDK inherit from :class:`VulnotesError`, so a
+single ``except vulnotes.VulnotesError`` catches everything.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = [
+    "VulnotesError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "APIStatusError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "ServerError",
+]
+
+
+class VulnotesError(Exception):
+    """Base class for every error raised by this SDK."""
+
+
+class APIConnectionError(VulnotesError):
+    """The API could not be reached (DNS failure, refused connection, TLS error...)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The request timed out."""
+
+
+class APIStatusError(VulnotesError):
+    """The API returned a non-2xx HTTP status.
+
+    Attributes:
+        status_code: The HTTP status code.
+        message: Human-readable error message extracted from the response body.
+        body: The parsed JSON error body when available, otherwise ``None``.
+        response: The underlying ``requests.Response`` object.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        *,
+        body: Any | None = None,
+        response: Any = None,
+    ) -> None:
+        self.status_code = status_code
+        self.message = message
+        self.body = body
+        self.response = response
+        super().__init__(f"[{status_code}] {message}")
+
+
+class BadRequestError(APIStatusError):
+    """400 - the request was malformed or failed validation."""
+
+
+class AuthenticationError(APIStatusError):
+    """401 - the API key is missing, invalid, revoked, or its owner is disabled."""
+
+
+class PermissionDeniedError(APIStatusError):
+    """403 - the API key lacks the permission required by this endpoint."""
+
+
+class NotFoundError(APIStatusError):
+    """404 - the resource does not exist or is not visible to the key's owner.
+
+    Note: Vulnotes intentionally returns 404 (not 403) for reports outside the
+    owner's visibility, so their existence is not disclosed.
+    """
+
+
+class ConflictError(APIStatusError):
+    """409 - the request conflicts with the current state of the resource."""
+
+
+class UnprocessableEntityError(APIStatusError):
+    """422 - the request was well-formed but semantically invalid."""
+
+
+class RateLimitError(APIStatusError):
+    """429 - too many requests."""
+
+
+class ServerError(APIStatusError):
+    """5xx - the server failed to process the request."""
+
+
+_STATUS_MAP = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+}
+
+
+def error_for_status(
+    status_code: int,
+    message: str,
+    *,
+    body: Any | None = None,
+    response: Any = None,
+) -> APIStatusError:
+    """Build the most specific :class:`APIStatusError` subclass for a status code."""
+    cls = _STATUS_MAP.get(status_code)
+    if cls is None:
+        cls = ServerError if status_code >= 500 else APIStatusError
+    return cls(status_code, message, body=body, response=response)

vulnotes/resources/__init__.py

@@ -0,0 +1,31 @@
+from .ai import AI
+from .api_keys import APIKeys
+from .attachments import Attachments
+from .comments import Comments
+from .companies import Companies
+from .findings import Findings
+from .images import Images
+from .notes import Notes
+from .planning import Planning
+from .report_templates import ReportTemplates
+from .reports import Reports
+from .snapshots import Snapshots
+from .vulnerabilities import Vulnerabilities
+from .vulnerability_templates import VulnerabilityTemplates
+
+__all__ = [
+    "AI",
+    "APIKeys",
+    "Attachments",
+    "Comments",
+    "Companies",
+    "Findings",
+    "Images",
+    "Notes",
+    "Planning",
+    "ReportTemplates",
+    "Reports",
+    "Snapshots",
+    "Vulnerabilities",
+    "VulnerabilityTemplates",
+]

vulnotes/resources/_base.py

@@ -0,0 +1,67 @@
+"""Shared plumbing for resource namespaces."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from ..client import VulnotesClient
+
+# The API returns list endpoints in two shapes: a plain JSON array when no
+# pagination parameters are supplied, or a paginated envelope
+# {"success": true, "data": [...], "pagination": {"page", "limit", "total",
+# "totalPages", "hasNextPage", ...}} when `page` or `limit` is present.
+JSON = Any
+
+
+class Resource:
+    def __init__(self, client: VulnotesClient) -> None:
+        self._client = client
+
+
+def paginate(
+    fetch: Callable[..., JSON],
+    *,
+    limit: int = 100,
+    **kwargs: Any,
+) -> Iterator[dict[str, Any]]:
+    """Iterate every item of a paginated list endpoint, fetching pages lazily.
+
+    ``fetch`` must accept ``page`` and ``limit`` keyword arguments and return
+    either a plain list or a paginated envelope.
+    """
+    page = 1
+    while True:
+        result = fetch(page=page, limit=limit, **kwargs)
+        if isinstance(result, list):
+            # Server ignored pagination and returned everything at once.
+            yield from result
+            return
+        items: list[dict[str, Any]] = result.get("data") or []
+        yield from items
+        if not items:
+            return
+        # Pagination metadata lives under "pagination"; fall back to
+        # top-level keys for endpoints using the older flat envelope.
+        meta = result.get("pagination")
+        if not isinstance(meta, dict):
+            meta = result
+        has_next = meta.get("hasNextPage")
+        if has_next is not None:
+            if not has_next:
+                return
+        else:
+            total_pages: int | None = meta.get("totalPages")
+            if total_pages is None or page >= total_pages:
+                return
+        page += 1
+
+
+def page_params(page: int | None, limit: int | None) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    if page is not None:
+        params["page"] = page
+    if limit is not None:
+        params["limit"] = limit
+    return params

vulnotes/resources/ai.py

@@ -0,0 +1,110 @@
+"""AI-assisted features. Permissions: ``rw:vulnerabilities`` or ``rw:reports``
+depending on the endpoint (noted per method)."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from .._utils import FileTypes, omit_none, prepare_file
+from ._base import Resource
+
+
+class AI(Resource):
+    def generate_vulnerability(
+        self,
+        request_description: str,
+        category: str,
+        language: str,
+        fields: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """Generate vulnerability content from a description. Requires ``rw:vulnerabilities``."""
+        return self._client.post(
+            "/ai/vulnerability/new",
+            json={
+                "request_description": request_description,
+                "category": category,
+                "language": language,
+                "fields": fields,
+            },
+        )
+
+    def translate_vulnerability(self, message: dict[str, Any]) -> dict[str, Any]:
+        """Translate vulnerability content. Requires ``rw:vulnerabilities``."""
+        return self._client.post("/ai/vulnerability/translate", json={"message": message})
+
+    def generate_report_content(
+        self,
+        report_id: str,
+        variable_key: str,
+        *,
+        user_prompt: str | None = None,
+        vuln_template_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Generate content for a report variable. Requires ``rw:reports``."""
+        body = omit_none(
+            {
+                "variableKey": variable_key,
+                "userPrompt": user_prompt,
+                "vulnTemplateId": vuln_template_id,
+            }
+        )
+        return self._client.post(f"/ai/report/{report_id}/generate-content", json=body)
+
+    def improve_report_content(
+        self,
+        report_id: str,
+        existing_content: str,
+        *,
+        variable_key: str | None = None,
+        improvement_type: str | None = None,
+    ) -> dict[str, Any]:
+        """Improve existing report content. Requires ``rw:reports``."""
+        body = omit_none(
+            {
+                "existingContent": existing_content,
+                "variableKey": variable_key,
+                "improvementType": improvement_type,
+            }
+        )
+        return self._client.post(f"/ai/report/{report_id}/improve-content", json=body)
+
+    def generate_finding_from_images(
+        self,
+        report_id: str,
+        images: Sequence[FileTypes],
+        *,
+        description: str | None = None,
+        redacted_images: str | None = None,
+        vuln_template_id: str | None = None,
+        timeout: float | None = 300.0,
+    ) -> dict[str, Any]:
+        """Generate a finding from screenshot evidence. Requires ``rw:reports``.
+
+        Args:
+            images: Screenshots (paths, bytes, file objects, or
+                ``(filename, fileobj)`` tuples).
+            description: Extra context for the generation.
+            redacted_images: Redaction metadata as expected by the API.
+            vuln_template_id: Vulnerability template guiding the output fields.
+        """
+        data = omit_none(
+            {
+                "description": description,
+                "redactedImages": redacted_images,
+                "vulnTemplateId": vuln_template_id,
+            }
+        )
+        prepared = [prepare_file(img, default_name="image.png") for img in images]
+        try:
+            files = [("images", p) for p in prepared]
+            return self._client.post(
+                f"/ai/report/{report_id}/generate-finding",
+                data=data,
+                files=files,
+                timeout=timeout,
+            )
+        finally:
+            for p in prepared:
+                if hasattr(p[1], "close"):
+                    p[1].close()

vulnotes/resources/api_keys.py

@@ -0,0 +1,17 @@
+"""Introspection of the API key making the request."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._base import Resource
+
+
+class APIKeys(Resource):
+    def me(self) -> dict[str, Any]:
+        """Describe the API key making the request: its name, owner, and the
+        effective permissions it currently holds.
+
+        Useful to discover at runtime which endpoints the key may call.
+        """
+        return self._client.get("/api-keys/me")