vulnotes 0.1.0__tar.gz

vulnotes-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest -q

vulnotes-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

vulnotes-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store

vulnotes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vulnotes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vulnotes-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: vulnotes
+Version: 0.1.0
+Summary: Official Python SDK for the Vulnotes API
+Project-URL: Homepage, https://vulnotes.com
+Project-URL: Documentation, https://docs.vulnotes.com
+Project-URL: Repository, https://github.com/vulnotes/vulnotes-python-sdk
+Author: Vulnotes
+License: MIT License
+        
+        Copyright (c) 2026 Vulnotes
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api,pentest,reporting,sdk,vulnerability,vulnotes
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vulnotes-python-sdk
+
+Python client for the [Vulnotes](https://vulnotes.com) REST API.
+
+```bash
+pip install vulnotes
+```
+
+Needs Python 3.9 or later. The only dependency is `requests`.
+
+## Getting started
+
+Create an API key in Vulnotes under Settings > API Keys, then:
+
+```python
+from vulnotes import VulnotesClient
+
+client = VulnotesClient("https://acme.vulnotes.app", api_key="vuln_sk_...")
+
+report = client.reports.create("External pentest Q3", language="EN")
+
+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": "..."}},
+})
+```
+
+If `VULNOTES_URL` and `VULNOTES_API_KEY` are set in the environment you can just do `VulnotesClient()`.
+
+Methods return plain dicts and lists matching the API's JSON. File exports return bytes. If you're wondering what a key is allowed to do, `client.api_keys.me()` tells you.
+
+## What's covered
+
+Everything reachable with an API key: reports and findings, companies, the vulnerability library, vulnerability templates, report templates, snapshots and review comments, notes, image/attachment uploads, exports (PDF, DOCX, XLSX, ZIP, JSON), the planning calendar, and the AI endpoints. Full endpoint reference: [docs.vulnotes.com](https://docs.vulnotes.com).
+
+Anything not wrapped yet can still be called directly:
+
+```python
+client.request("GET", f"/reports/{report_id}/snapshots")
+```
+
+## A few common tasks
+
+Iterating without dealing with pages:
+
+```python
+for report in client.reports.iter():
+    print(report["title"])
+```
+
+Feeding scanner results into a report:
+
+```python
+for issue in results:
+    client.findings.add(report_id, {
+        "title": issue["name"],
+        "severity": issue["severity"],
+        "affectedSystems": issue["hosts"],
+        "data": {"EN": {"title": issue["name"], "description": issue["detail"]}},
+    })
+```
+
+Downloading exports:
+
+```python
+client.reports.export_xlsx(report_id, finding_fields=["title", "severity"], path="findings.xlsx")
+client.reports.archived_pdf(report_id, path="final.pdf")  # PDF stored when the report was completed
+```
+
+Uploading evidence:
+
+```python
+client.images.upload("screenshot.png", report_id=report_id)
+client.attachments.upload("nmap-scan.xml", report_id=report_id)
+```
+
+Dates can be passed as ISO strings or as `datetime.date`/`datetime.datetime`.
+
+## Errors
+
+Everything raised by the SDK inherits from `vulnotes.VulnotesError`. HTTP errors map to subclasses (`NotFoundError`, `PermissionDeniedError`, `RateLimitError`, ...) with `status_code`, `message` and the parsed body attached.
+
+```python
+from vulnotes import NotFoundError
+
+try:
+    client.reports.get(report_id)
+except NotFoundError:
+    # doesn't exist, or the key's owner can't see it
+    ...
+```
+
+A key that lacks the permission an endpoint needs gets a `PermissionDeniedError` naming it. Reports outside the owner's visibility raise `NotFoundError`, not 403; that's intentional on the server side.
+
+Idempotent requests are retried automatically on connection errors and 429/502/503/504. Tune with `max_retries`, `timeout` and `verify_ssl` on the client.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest          # offline, no instance needed
+ruff check .
+```
+
+There's also an integration suite that runs against a real instance. It creates its own fixtures and removes them, but point it at a disposable instance anyway:
+
+```bash
+VULNOTES_TEST_URL=https://dev.example VULNOTES_TEST_API_KEY=vuln_sk_... pytest tests/integration
+```
+
+## License
+
+MIT

vulnotes-0.1.0/README.md

@@ -0,0 +1,115 @@
+# vulnotes-python-sdk
+
+Python client for the [Vulnotes](https://vulnotes.com) REST API.
+
+```bash
+pip install vulnotes
+```
+
+Needs Python 3.9 or later. The only dependency is `requests`.
+
+## Getting started
+
+Create an API key in Vulnotes under Settings > API Keys, then:
+
+```python
+from vulnotes import VulnotesClient
+
+client = VulnotesClient("https://acme.vulnotes.app", api_key="vuln_sk_...")
+
+report = client.reports.create("External pentest Q3", language="EN")
+
+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": "..."}},
+})
+```
+
+If `VULNOTES_URL` and `VULNOTES_API_KEY` are set in the environment you can just do `VulnotesClient()`.
+
+Methods return plain dicts and lists matching the API's JSON. File exports return bytes. If you're wondering what a key is allowed to do, `client.api_keys.me()` tells you.
+
+## What's covered
+
+Everything reachable with an API key: reports and findings, companies, the vulnerability library, vulnerability templates, report templates, snapshots and review comments, notes, image/attachment uploads, exports (PDF, DOCX, XLSX, ZIP, JSON), the planning calendar, and the AI endpoints. Full endpoint reference: [docs.vulnotes.com](https://docs.vulnotes.com).
+
+Anything not wrapped yet can still be called directly:
+
+```python
+client.request("GET", f"/reports/{report_id}/snapshots")
+```
+
+## A few common tasks
+
+Iterating without dealing with pages:
+
+```python
+for report in client.reports.iter():
+    print(report["title"])
+```
+
+Feeding scanner results into a report:
+
+```python
+for issue in results:
+    client.findings.add(report_id, {
+        "title": issue["name"],
+        "severity": issue["severity"],
+        "affectedSystems": issue["hosts"],
+        "data": {"EN": {"title": issue["name"], "description": issue["detail"]}},
+    })
+```
+
+Downloading exports:
+
+```python
+client.reports.export_xlsx(report_id, finding_fields=["title", "severity"], path="findings.xlsx")
+client.reports.archived_pdf(report_id, path="final.pdf")  # PDF stored when the report was completed
+```
+
+Uploading evidence:
+
+```python
+client.images.upload("screenshot.png", report_id=report_id)
+client.attachments.upload("nmap-scan.xml", report_id=report_id)
+```
+
+Dates can be passed as ISO strings or as `datetime.date`/`datetime.datetime`.
+
+## Errors
+
+Everything raised by the SDK inherits from `vulnotes.VulnotesError`. HTTP errors map to subclasses (`NotFoundError`, `PermissionDeniedError`, `RateLimitError`, ...) with `status_code`, `message` and the parsed body attached.
+
+```python
+from vulnotes import NotFoundError
+
+try:
+    client.reports.get(report_id)
+except NotFoundError:
+    # doesn't exist, or the key's owner can't see it
+    ...
+```
+
+A key that lacks the permission an endpoint needs gets a `PermissionDeniedError` naming it. Reports outside the owner's visibility raise `NotFoundError`, not 403; that's intentional on the server side.
+
+Idempotent requests are retried automatically on connection errors and 429/502/503/504. Tune with `max_retries`, `timeout` and `verify_ssl` on the client.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest          # offline, no instance needed
+ruff check .
+```
+
+There's also an integration suite that runs against a real instance. It creates its own fixtures and removes them, but point it at a disposable instance anyway:
+
+```bash
+VULNOTES_TEST_URL=https://dev.example VULNOTES_TEST_API_KEY=vuln_sk_... pytest tests/integration
+```
+
+## License
+
+MIT

vulnotes-0.1.0/examples/export_report.py

@@ -0,0 +1,33 @@
+"""Export a report as JSON and PDF.
+
+Usage: python export_report.py <report_id>
+Set VULNOTES_URL and VULNOTES_API_KEY first (the key needs ro:reports).
+"""
+
+import json
+import sys
+
+from vulnotes import NotFoundError, VulnotesClient
+
+
+def main(report_id: str) -> None:
+    client = VulnotesClient()
+
+    export = client.reports.export_json(report_id)
+    with open(f"report-{report_id}.json", "w") as fh:
+        json.dump(export, fh, indent=2)
+    print(f"Wrote report-{report_id}.json")
+
+    try:
+        # PDF archived when the report was marked completed (pixel-perfect)
+        client.reports.archived_pdf(report_id, path=f"report-{report_id}.pdf")
+    except NotFoundError:
+        # Not completed yet: fall back to server-side rendering
+        client.reports.export_pdf(report_id, path=f"report-{report_id}.pdf")
+    print(f"Wrote report-{report_id}.pdf")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        sys.exit(__doc__)
+    main(sys.argv[1])

vulnotes-0.1.0/examples/import_scanner_findings.py

@@ -0,0 +1,46 @@
+"""Create a report and push scanner findings into it.
+
+Set VULNOTES_URL and VULNOTES_API_KEY before running (the key needs
+rw:reports and, to link a company, ro:clients).
+"""
+
+from vulnotes import VulnotesClient
+
+# Pretend output of a scanner
+SCANNER_RESULTS = [
+    {
+        "name": "Outdated OpenSSH (9.0p1)",
+        "severity": "Medium",
+        "hosts": ["203.0.113.10"],
+        "detail": "The SSH service reports an outdated version with known CVEs.",
+    },
+    {
+        "name": "TLS certificate expired",
+        "severity": "Low",
+        "hosts": ["203.0.113.12"],
+        "detail": "The certificate served on port 443 expired 42 days ago.",
+    },
+]
+
+
+def main() -> None:
+    client = VulnotesClient()
+
+    report = client.reports.create("Perimeter scan import", language="EN")
+    print(f"Created report {report['_id']}")
+
+    for issue in SCANNER_RESULTS:
+        finding = client.findings.add(
+            report["_id"],
+            {
+                "title": issue["name"],
+                "severity": issue["severity"],
+                "affectedSystems": issue["hosts"],
+                "data": {"EN": {"title": issue["name"], "description": issue["detail"]}},
+            },
+        )
+        print(f"  added finding {finding['id']}: {issue['name']}")
+
+
+if __name__ == "__main__":
+    main()

vulnotes-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vulnotes"
+description = "Official Python SDK for the Vulnotes API"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "Vulnotes" }]
+requires-python = ">=3.9"
+dependencies = ["requests>=2.28"]
+dynamic = ["version"]
+keywords = ["vulnotes", "pentest", "vulnerability", "reporting", "api", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://vulnotes.com"
+Documentation = "https://docs.vulnotes.com"
+Repository = "https://github.com/vulnotes/vulnotes-python-sdk"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "ruff>=0.4"]
+
+[tool.hatch.version]
+path = "src/vulnotes/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vulnotes"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]

vulnotes-0.1.0/src/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-0.1.0/src/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-0.1.0/src/vulnotes/_version.py

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