vulnotes 0.1.0__py3-none-any.whl

vulnotes/resources/attachments.py

@@ -0,0 +1,75 @@
+"""File attachments. Permissions: ``ro:reports`` / ``rw:reports``."""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any
+
+from .._utils import FileTypes, omit_none, prepare_file
+from ._base import JSON, Resource
+
+
+class Attachments(Resource):
+    def list(
+        self,
+        *,
+        template_id: str | None = None,
+        company_id: str | None = None,
+        report_id: str | None = None,
+        vulnerability_id: str | None = None,
+        note_id: str | None = None,
+    ) -> builtins.list[dict[str, Any]]:
+        """List attachments, optionally filtered by associated entity."""
+        params = omit_none(
+            {
+                "templateId": template_id,
+                "companyId": company_id,
+                "reportId": report_id,
+                "vulnerabilityId": vulnerability_id,
+                "noteId": note_id,
+            }
+        )
+        return self._client.get("/attachments", params=params)
+
+    def upload(
+        self,
+        file: FileTypes,
+        *,
+        template_id: str | None = None,
+        company_id: str | None = None,
+        report_id: str | None = None,
+        vulnerability_id: str | None = None,
+        note_id: str | None = None,
+        user_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Upload a file attachment. Requires ``rw:reports``.
+
+        Args:
+            file: A filesystem path, raw bytes, an open binary file object,
+                or a ``(filename, fileobj_or_bytes)`` tuple.
+        """
+        data = omit_none(
+            {
+                "templateId": template_id,
+                "companyId": company_id,
+                "reportId": report_id,
+                "vulnerabilityId": vulnerability_id,
+                "noteId": note_id,
+                "userId": user_id,
+            }
+        )
+        prepared = prepare_file(file, default_name="attachment.bin")
+        try:
+            return self._client.post(
+                "/attachments/upload", data=data, files={"file": prepared}
+            )
+        finally:
+            fh = prepared[1]
+            if hasattr(fh, "close"):
+                fh.close()
+
+    def list_for_report(self, report_id: str) -> builtins.list[dict[str, Any]]:
+        return self._client.get(f"/attachments/report/{report_id}")
+
+    def delete(self, attachment_id: str) -> JSON:
+        return self._client.delete(f"/attachments/{attachment_id}")

vulnotes/resources/comments.py

@@ -0,0 +1,98 @@
+"""Review comment threads on report snapshots.
+
+Permissions: ``ro:reports`` / ``rw:reports``.
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any
+
+from .._utils import omit_none
+from ._base import JSON, Resource
+
+
+class Comments(Resource):
+    def list(
+        self,
+        report_id: str,
+        snapshot_id: str,
+        *,
+        resolved: bool | None = None,
+        type: str | None = None,
+        ref: str | None = None,
+    ) -> builtins.list[dict[str, Any]]:
+        """List comments on a snapshot, optionally filtered by resolved state,
+        attachment type, or attachment ref.
+
+        Returns the comment list; use :meth:`counts` for the aggregate counts.
+        """
+        params = omit_none(
+            {
+                "resolved": str(resolved).lower() if resolved is not None else None,
+                "type": type,
+                "ref": ref,
+            }
+        )
+        resp = self._client.get(
+            f"/reports/{report_id}/snapshots/{snapshot_id}/comments", params=params
+        )
+        if isinstance(resp, dict):
+            return resp.get("comments", [])
+        return resp
+
+    def create(
+        self,
+        report_id: str,
+        snapshot_id: str,
+        content: str,
+        *,
+        attachment_type: str | None = None,
+        attachment_ref: str | None = None,
+        finding_field: str | None = None,
+        parent_comment: str | None = None,
+        page_number: int | None = None,
+        bounding_box: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Create a review comment (or a reply, via ``parent_comment``)."""
+        body = omit_none(
+            {
+                "content": content,
+                "attachmentType": attachment_type,
+                "attachmentRef": attachment_ref,
+                "findingField": finding_field,
+                "parentComment": parent_comment,
+                "pageNumber": page_number,
+                "boundingBox": bounding_box,
+            }
+        )
+        return self._client.post(
+            f"/reports/{report_id}/snapshots/{snapshot_id}/comments", json=body
+        )
+
+    def counts(self, report_id: str, snapshot_id: str) -> dict[str, Any]:
+        """Get comment counts for a snapshot
+        (``total`` / ``unresolved`` / ``resolved`` / ``byType``)."""
+        return self._client.get(
+            f"/reports/{report_id}/snapshots/{snapshot_id}/comments/counts"
+        )
+
+    def annotations(self, report_id: str, snapshot_id: str) -> JSON:
+        """Get PDF annotations for a snapshot, as ``{"annotations": [...],
+        "byPage": {...}}``."""
+        return self._client.get(
+            f"/reports/{report_id}/snapshots/{snapshot_id}/annotations"
+        )
+
+    def update(self, report_id: str, comment_id: str, content: str) -> dict[str, Any]:
+        """Edit a comment's content."""
+        return self._client.put(
+            f"/reports/{report_id}/comments/{comment_id}", json={"content": content}
+        )
+
+    def delete(self, report_id: str, comment_id: str) -> JSON:
+        return self._client.delete(f"/reports/{report_id}/comments/{comment_id}")
+
+    def toggle_resolved(self, report_id: str, comment_id: str) -> dict[str, Any]:
+        """Toggle a comment's resolved status."""
+        return self._client.patch(f"/reports/{report_id}/comments/{comment_id}/resolve")

vulnotes/resources/companies.py

@@ -0,0 +1,77 @@
+"""Client companies. Permissions: ``ro:clients`` / ``rw:clients``."""
+
+from __future__ import annotations
+
+import builtins
+from collections.abc import Iterator
+from typing import Any
+
+from .._utils import omit_none
+from ._base import JSON, Resource, page_params, paginate
+
+
+class Companies(Resource):
+    def list(self, *, page: int | None = None, limit: int | None = None) -> JSON:
+        """List companies, sorted by creation date descending.
+
+        Returns a plain list when called without arguments, or a paginated
+        envelope (``data`` plus a ``pagination`` object with ``page``,
+        ``limit``, ``total``, ``totalPages``, ``hasNextPage``) when ``page``
+        or ``limit`` is given.
+        """
+        return self._client.get("/companies", params=page_params(page, limit))
+
+    def iter(self, *, limit: int = 100) -> Iterator[dict[str, Any]]:
+        """Iterate over every company, fetching pages lazily."""
+        return paginate(lambda page, limit: self.list(page=page, limit=limit), limit=limit)
+
+    def search(self, query: str) -> builtins.list[dict[str, Any]]:
+        """Search companies by name (accent-insensitive)."""
+        return self._client.get("/companies/search", params={"query": query})
+
+    def get(self, company_id: str) -> dict[str, Any]:
+        return self._client.get(f"/companies/{company_id}")
+
+    def create(
+        self,
+        name: str,
+        *,
+        logo: str | None = None,
+        contacts: builtins.list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        """Create a company. Requires ``rw:clients``."""
+        body = omit_none({"name": name, "logo": logo, "contacts": contacts})
+        return self._client.post("/companies", json=body)
+
+    def update(
+        self,
+        company_id: str,
+        *,
+        name: str | None = None,
+        logo: str | None = None,
+        contacts: builtins.list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        """Update a company. Only the supplied fields are changed."""
+        body = omit_none({"name": name, "logo": logo, "contacts": contacts})
+        return self._client.put(f"/companies/{company_id}", json=body)
+
+    def delete(self, company_id: str) -> JSON:
+        return self._client.delete(f"/companies/{company_id}")
+
+    def portal_access(self, company_id: str) -> dict[str, Any]:
+        """Get the company's client-portal access configuration and users."""
+        return self._client.get(f"/companies/{company_id}/portal-access")
+
+    def update_client_user(
+        self,
+        company_id: str,
+        user_id: str,
+        *,
+        client_role: str | None = None,
+        active: bool | None = None,
+    ) -> dict[str, Any]:
+        """Update a company's client-portal user (role and/or active status)."""
+        body = omit_none({"clientRole": client_role, "active": active})
+        return self._client.patch(
+            f"/companies/{company_id}/client-users/{user_id}", json=body
+        )

vulnotes/resources/findings.py

@@ -0,0 +1,62 @@
+"""Findings embedded in a report. Permissions: ``ro:reports`` / ``rw:reports``."""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any
+
+from ._base import JSON, Resource
+
+
+class Findings(Resource):
+    def list(self, report_id: str) -> builtins.list[dict[str, Any]]:
+        """Get all findings for a report."""
+        return self._client.get(f"/reports/{report_id}/findings")
+
+    def add(self, report_id: str, finding: dict[str, Any]) -> dict[str, Any]:
+        """Append a finding to a report. Requires ``rw:reports``.
+
+        A unique ``id`` is generated automatically. If the report has a
+        vulnerability template and ``fields`` is not provided, the field
+        definitions are copied from it, and multilingual ``data`` entries are
+        initialized for all supported languages.
+
+        Example:
+            >>> client.findings.add(report_id, {
+            ...     "title": "SQL Injection in /login",
+            ...     "severity": "Critical",
+            ...     "cvss": {"vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H"},
+            ...     "data": {"EN": {"title": "SQL Injection in /login",
+            ...                     "description": "..."}},
+            ... })
+        """
+        return self._client.post(f"/reports/{report_id}/findings", json=finding)
+
+    def replace_all(
+        self, report_id: str, findings: builtins.list[dict[str, Any]]
+    ) -> builtins.list[dict[str, Any]]:
+        """Replace the report's entire findings array (also used for reordering)."""
+        return self._client.put(f"/reports/{report_id}/findings", json=findings)
+
+    def update(
+        self, report_id: str, finding_id: str, changes: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Partially update a finding.
+
+        Accepted fields: ``title``, ``severity``, ``status``, ``description``,
+        ``impact``, ``remediation``, ``references``, ``cvss``, ``cwe``,
+        ``affectedSystems``, ``evidence``, ``data``, ``order``, ``fields``,
+        ``isComplete``. Other fields are ignored.
+
+        Args:
+            report_id: The report's ObjectId.
+            finding_id: The finding's ``id`` field (a generated string, not an ObjectId).
+            changes: The fields to change.
+        """
+        return self._client.put(
+            f"/reports/{report_id}/findings/{finding_id}", json=changes
+        )
+
+    def delete(self, report_id: str, finding_id: str) -> JSON:
+        """Remove a finding from the report."""
+        return self._client.delete(f"/reports/{report_id}/findings/{finding_id}")

vulnotes/resources/images.py

@@ -0,0 +1,85 @@
+"""Image upload and management. Permissions: ``ro:reports`` / ``rw:reports``."""
+
+from __future__ import annotations
+
+import builtins
+from typing import Any
+
+from .._utils import FileTypes, omit_none, prepare_file
+from ._base import JSON, Resource
+
+
+class Images(Resource):
+    def list(
+        self,
+        *,
+        template_id: str | None = None,
+        client_id: str | None = None,
+        report_id: str | None = None,
+    ) -> builtins.list[dict[str, Any]]:
+        """List images, optionally filtered by template, client, or report."""
+        params = omit_none(
+            {"templateId": template_id, "clientId": client_id, "reportId": report_id}
+        )
+        return self._client.get("/images", params=params)
+
+    def upload(
+        self,
+        image: FileTypes,
+        *,
+        template_id: str | None = None,
+        client_id: str | None = None,
+        report_id: str | None = None,
+        note_id: str | None = None,
+        vulnerability_id: str | None = None,
+        company_id: str | None = None,
+        user_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Upload an image and associate it with an entity. Requires ``rw:reports``.
+
+        Args:
+            image: A filesystem path, raw bytes, an open binary file object,
+                or a ``(filename, fileobj_or_bytes)`` tuple.
+            template_id / client_id / report_id / note_id / vulnerability_id /
+                company_id / user_id: Entity to associate the image with.
+        """
+        data = omit_none(
+            {
+                "templateId": template_id,
+                "clientId": client_id,
+                "reportId": report_id,
+                "noteId": note_id,
+                "vulnerabilityId": vulnerability_id,
+                "companyId": company_id,
+                "userId": user_id,
+            }
+        )
+        prepared = prepare_file(image, default_name="image.png")
+        try:
+            return self._client.post(
+                "/images/upload", data=data, files={"image": prepared}
+            )
+        finally:
+            fh = prepared[1]
+            if hasattr(fh, "close"):
+                fh.close()
+
+    def list_for_note(self, note_id: str) -> builtins.list[dict[str, Any]]:
+        return self._client.get(f"/images/note/{note_id}")
+
+    def list_for_template(self, template_id: str) -> builtins.list[dict[str, Any]]:
+        return self._client.get(f"/images/template/{template_id}")
+
+    def list_for_user(self, user_id: str) -> builtins.list[dict[str, Any]]:
+        return self._client.get(f"/images/user/{user_id}")
+
+    def associate_with_template(
+        self, template_id: str, image_ids: builtins.list[str]
+    ) -> JSON:
+        """Associate previously uploaded images with a template."""
+        return self._client.post(
+            f"/images/template/{template_id}/associate", json={"imageIds": image_ids}
+        )
+
+    def delete(self, image_id: str) -> JSON:
+        return self._client.delete(f"/images/{image_id}")

vulnotes/resources/notes.py

@@ -0,0 +1,71 @@
+"""Notes attached to reports. Permissions: ``ro:reports`` / ``rw:reports``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .._utils import omit_none
+from ._base import JSON, Resource
+
+
+class Notes(Resource):
+    def list_for_report(self, report_id: str) -> list[dict[str, Any]]:
+        """Get all notes attached to a report."""
+        return self._client.get(f"/notes/report/{report_id}")
+
+    def create(
+        self,
+        report_id: str,
+        title: str,
+        *,
+        content: str | None = None,
+        is_pinned: bool | None = None,
+        tags: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Create a note on a report. Requires ``rw:reports``."""
+        body = omit_none(
+            {"title": title, "content": content, "isPinned": is_pinned, "tags": tags}
+        )
+        return self._client.post(f"/notes/report/{report_id}", json=body)
+
+    def get(self, note_id: str) -> dict[str, Any]:
+        return self._client.get(f"/notes/{note_id}")
+
+    def update(
+        self,
+        note_id: str,
+        *,
+        title: str | None = None,
+        content: str | None = None,
+        is_pinned: bool | None = None,
+        tags: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Update a note. Only the supplied fields are changed."""
+        body = omit_none(
+            {"title": title, "content": content, "isPinned": is_pinned, "tags": tags}
+        )
+        return self._client.put(f"/notes/{note_id}", json=body)
+
+    def delete(self, note_id: str) -> JSON:
+        return self._client.delete(f"/notes/{note_id}")
+
+    def save(
+        self,
+        note_id: str,
+        *,
+        content: str | None = None,
+        title: str | None = None,
+    ) -> dict[str, Any]:
+        """Autosave-style update of a note's content and title.
+
+        Warning: this endpoint always rewrites the title. When ``title`` is
+        omitted it is re-extracted from the first ``# heading`` line of the
+        content, falling back to ``"Untitled Note"``. Pass ``title``
+        explicitly (or use :meth:`update`) to keep the existing one.
+        """
+        body = omit_none({"content": content, "title": title})
+        return self._client.patch(f"/notes/{note_id}/save", json=body)
+
+    def toggle_pin(self, note_id: str) -> dict[str, Any]:
+        """Toggle the note's pinned status."""
+        return self._client.patch(f"/notes/{note_id}/toggle-pin")

vulnotes/resources/planning.py

@@ -0,0 +1,210 @@
+"""The resource-planning calendar: engagements and availability.
+
+Permissions: ``ro:planning`` to read, ``rw:planning`` to write,
+``manage:planning`` to delete events or assign users outside your own team.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from collections.abc import Iterator
+from typing import Any, Union
+
+from .._utils import iso, omit_none
+from ._base import JSON, Resource, page_params, paginate
+
+DateLike = Union[str, _dt.date, _dt.datetime]
+
+
+class Planning(Resource):
+    # ── calendar ─────────────────────────────────────────────────────────
+
+    def calendar(self, start: DateLike, end: DateLike) -> dict[str, Any]:
+        """Get the combined planning calendar (events + availability) for a date range."""
+        return self._client.get(
+            "/planning/calendar", params={"start": iso(start), "end": iso(end)}
+        )
+
+    def users(self, *, skills: str | None = None) -> list[dict[str, Any]]:
+        """List calendar users, optionally filtered by skills."""
+        return self._client.get("/planning/users", params=omit_none({"skills": skills}))
+
+    # ── events ───────────────────────────────────────────────────────────
+
+    def list_events(
+        self, *, page: int | None = None, limit: int | None = None
+    ) -> JSON:
+        """List planning events (plain list, or paginated envelope with ``page``/``limit``)."""
+        return self._client.get("/planning/events", params=page_params(page, limit))
+
+    def iter_events(self, *, limit: int = 100) -> Iterator[dict[str, Any]]:
+        """Iterate over every visible planning event, fetching pages lazily."""
+        return paginate(
+            lambda page, limit: self.list_events(page=page, limit=limit), limit=limit
+        )
+
+    def events_in_range(self, start: DateLike, end: DateLike) -> list[dict[str, Any]]:
+        """List planning events overlapping a date range."""
+        return self._client.get(
+            "/planning/events/range", params={"start": iso(start), "end": iso(end)}
+        )
+
+    def check_conflicts(
+        self,
+        user_id: str,
+        start: DateLike,
+        end: DateLike,
+        *,
+        exclude_event_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Check whether a user is already booked during a date range."""
+        params = omit_none(
+            {"start": iso(start), "end": iso(end), "excludeEventId": exclude_event_id}
+        )
+        return self._client.get(f"/planning/events/conflicts/{user_id}", params=params)
+
+    def get_event(self, event_id: str) -> dict[str, Any]:
+        return self._client.get(f"/planning/events/{event_id}")
+
+    def create_event(
+        self,
+        title: str,
+        start_date: DateLike,
+        end_date: DateLike,
+        assignees: list[str],
+        event_type: str,
+        *,
+        description: str | None = None,
+        client: str | None = None,
+        status: str | None = None,
+        color: str | None = None,
+        notes: str | None = None,
+    ) -> dict[str, Any]:
+        """Book an engagement on the calendar. Requires ``rw:planning``.
+
+        Args:
+            title: Event title (max 200 chars).
+            start_date / end_date: ``end_date`` must be strictly after ``start_date``.
+            assignees: User ObjectIds (at least one). Non-admin callers may only
+                assign members of their own team.
+            event_type: One of ``pentest``, ``training``, ``conference``,
+                ``research``, ``other``.
+            client: Company ObjectId.
+            status: One of ``planned``, ``requirements``, ``in-progress``,
+                ``completed``, ``cancelled``.
+            color: Hex color, e.g. ``"#3B82F6"``.
+        """
+        body = omit_none(
+            {
+                "title": title,
+                "startDate": iso(start_date),
+                "endDate": iso(end_date),
+                "assignees": assignees,
+                "eventType": event_type,
+                "description": description,
+                "client": client,
+                "status": status,
+                "color": color,
+                "notes": notes,
+            }
+        )
+        return self._client.post("/planning/events", json=body)
+
+    def update_event(
+        self,
+        event_id: str,
+        *,
+        title: str | None = None,
+        start_date: DateLike | None = None,
+        end_date: DateLike | None = None,
+        assignees: list[str] | None = None,
+        event_type: str | None = None,
+        description: str | None = None,
+        client: str | None = None,
+        status: str | None = None,
+        color: str | None = None,
+        notes: str | None = None,
+    ) -> dict[str, Any]:
+        """Update a planning event. Only the supplied fields are changed."""
+        body = omit_none(
+            {
+                "title": title,
+                "startDate": iso(start_date),
+                "endDate": iso(end_date),
+                "assignees": assignees,
+                "eventType": event_type,
+                "description": description,
+                "client": client,
+                "status": status,
+                "color": color,
+                "notes": notes,
+            }
+        )
+        return self._client.put(f"/planning/events/{event_id}", json=body)
+
+    def delete_event(self, event_id: str) -> JSON:
+        """Delete a planning event. Requires ``manage:planning``."""
+        return self._client.delete(f"/planning/events/{event_id}")
+
+    # ── availability ─────────────────────────────────────────────────────
+
+    def list_availability(
+        self, *, page: int | None = None, limit: int | None = None
+    ) -> JSON:
+        """List availability entries (plain list, or paginated envelope)."""
+        return self._client.get("/planning/availability", params=page_params(page, limit))
+
+    def availability_in_range(
+        self, start: DateLike, end: DateLike
+    ) -> list[dict[str, Any]]:
+        """List availability entries overlapping a date range."""
+        return self._client.get(
+            "/planning/availability/range", params={"start": iso(start), "end": iso(end)}
+        )
+
+    def create_availability(
+        self,
+        type: str,
+        start_date: DateLike,
+        end_date: DateLike,
+        *,
+        description: str | None = None,
+    ) -> dict[str, Any]:
+        """Mark availability for the API key's owner. Requires ``rw:planning``.
+
+        Args:
+            type: One of ``vacation``, ``conference``, ``sick``, ``training``, ``other``.
+            start_date / end_date: ``end_date`` must be strictly after ``start_date``.
+        """
+        body = omit_none(
+            {
+                "type": type,
+                "startDate": iso(start_date),
+                "endDate": iso(end_date),
+                "description": description,
+            }
+        )
+        return self._client.post("/planning/availability", json=body)
+
+    def update_availability(
+        self,
+        availability_id: str,
+        *,
+        type: str | None = None,
+        start_date: DateLike | None = None,
+        end_date: DateLike | None = None,
+        description: str | None = None,
+    ) -> dict[str, Any]:
+        """Update an availability entry. Only the supplied fields are changed."""
+        body = omit_none(
+            {
+                "type": type,
+                "startDate": iso(start_date),
+                "endDate": iso(end_date),
+                "description": description,
+            }
+        )
+        return self._client.put(f"/planning/availability/{availability_id}", json=body)
+
+    def delete_availability(self, availability_id: str) -> JSON:
+        return self._client.delete(f"/planning/availability/{availability_id}")