nessus-export 0.1.0__py3-none-any.whl

nessus_export/__init__.py

@@ -0,0 +1,4 @@
+"""nessus-export: export Nessus scan results via the API, with a
+reconstruction fallback for trial-mode servers."""
+
+__version__ = "0.1.0"

nessus_export/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

nessus_export/cli.py

@@ -0,0 +1,242 @@
+"""Command-line interface for nessus-export."""
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+from typing import Dict, List, Optional
+
+from . import __version__
+from .client import NessusClient, NessusError, AuthError, TrialModeError
+from .exporter import (CHAPTERS, EXTENSIONS, NATIVE_FORMATS, export_scan)
+
+_STATUS_ORDER = ["running", "completed", "canceled", "aborted", "empty"]
+
+
+def _eprint(*a) -> None:
+    print(*a, file=sys.stderr)
+
+
+def _load_env_file(path: str) -> None:
+    """Populate os.environ from a simple KEY=VALUE .env file (no deps)."""
+    try:
+        with open(path) as fh:
+            for line in fh:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, _, val = line.partition("=")
+                key, val = key.strip(), val.strip().strip('"').strip("'")
+                os.environ.setdefault(key, val)
+    except FileNotFoundError:
+        pass
+
+
+def _make_client(args) -> NessusClient:
+    if args.env_file:
+        _load_env_file(args.env_file)
+    else:
+        # Convenience: auto-load ./.env if present and keys not already set.
+        if os.path.exists(".env"):
+            _load_env_file(".env")
+    access = args.access_key or os.environ.get("ACCESS_KEY") \
+        or os.environ.get("NESSUS_ACCESS_KEY", "")
+    secret = args.secret_key or os.environ.get("SECRET_KEY") \
+        or os.environ.get("NESSUS_SECRET_KEY", "")
+    url = args.url or os.environ.get("NESSUS_URL") or "https://localhost:8834"
+    if not access or not secret:
+        raise AuthError(
+            "missing API keys; set ACCESS_KEY/SECRET_KEY (env or .env) "
+            "or pass --access-key/--secret-key"
+        )
+    return NessusClient(
+        url=url, access_key=access, secret_key=secret,
+        verify_ssl=args.verify_ssl, ca_bundle=args.ca_bundle,
+        timeout=args.timeout,
+    )
+
+
+def _sanitize(name: str) -> str:
+    return re.sub(r"[^A-Za-z0-9._-]+", "_", name).strip("_") or "scan"
+
+
+# --------------------------------------------------------------------------
+# commands
+# --------------------------------------------------------------------------
+def cmd_list(client: NessusClient, args) -> int:
+    scans = client.list_scans()
+    if args.status:
+        scans = [s for s in scans if s.get("status") == args.status]
+    scans.sort(key=lambda s: (s.get("name") or "").lower())
+    if args.json:
+        import json
+        print(json.dumps(scans, indent=2))
+        return 0
+    if not scans:
+        _eprint("no scans found")
+        return 0
+    width = max(len(str(s.get("name", ""))) for s in scans)
+    print(f"{'ID':>5}  {'NAME':<{width}}  {'STATUS':<10}  FOLDER")
+    for s in scans:
+        print(f"{s.get('id'):>5}  {str(s.get('name','')):<{width}}  "
+              f"{str(s.get('status','')):<10}  {s.get('folder_id','')}")
+    return 0
+
+
+def _select_scan_ids(client: NessusClient, args) -> List[int]:
+    if args.all:
+        scans = client.list_scans()
+        if args.status:
+            scans = [s for s in scans if s.get("status") == args.status]
+        return [s["id"] for s in scans]
+    if not args.scans:
+        raise NessusError("no scans specified; pass names/ids, or use --all")
+    resolved = []
+    for ref in args.scans:
+        s = client.resolve_scan(ref)
+        resolved.append(s["id"])
+    return resolved
+
+
+def cmd_export(client: NessusClient, args) -> int:
+    scan_ids = _select_scan_ids(client, args)
+    if not scan_ids:
+        _eprint("no matching scans to export")
+        return 1
+
+    chapters = None
+    if args.chapters:
+        chapters = [c.strip() for c in args.chapters.split(",") if c.strip()]
+        bad = [c for c in chapters if c not in CHAPTERS]
+        if bad:
+            raise NessusError(f"invalid chapter(s): {bad}; choose from {CHAPTERS}")
+
+    out_dir = args.out_dir
+    single_out = args.output if len(scan_ids) == 1 else None
+    if out_dir:
+        os.makedirs(out_dir, exist_ok=True)
+
+    quiet = args.quiet
+    progress = (lambda m: None) if quiet else (lambda m: _eprint(f"  … {m}"))
+
+    rc = 0
+    used_paths: set = set()
+    for scan_id in scan_ids:
+        info = client.get_scan(scan_id).get("info", {})
+        name = info.get("name", f"scan-{scan_id}")
+        _eprint(f"[{name}] (id {scan_id}) → {args.format}")
+        try:
+            result = export_scan(
+                client, scan_id, fmt=args.format, mode=args.mode,
+                chapters=chapters, db_password=args.db_password,
+                poll_interval=args.poll_interval, max_wait=args.max_wait,
+                progress=progress,
+            )
+        except (TrialModeError, NessusError, ValueError) as e:
+            _eprint(f"  ✗ {e}")
+            rc = 1
+            continue
+
+        if single_out:
+            path = single_out
+        else:
+            base = os.path.join(out_dir or ".", _sanitize(name))
+            path = base + result.extension
+            # Disambiguate when several scans share a name (append the id).
+            if path in used_paths:
+                path = f"{base}_{scan_id}{result.extension}"
+            used_paths.add(path)
+        with open(path, "wb") as fh:
+            fh.write(result.content)
+        tag = "reconstructed (trial mode)" if result.mode == "reconstruct" else "native"
+        _eprint(f"  ✓ wrote {path} ({len(result.content)} bytes, {tag})")
+    return rc
+
+
+def cmd_status(client: NessusClient, args) -> int:
+    st = client.server_status()
+    print(f"server: {client.url}")
+    print(f"status: {st.get('status')}  progress: {st.get('progress')}")
+    return 0
+
+
+# --------------------------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="nessus-export",
+        description="Export Nessus scan results via the API, with an automatic "
+                    "reconstruction fallback for trial-mode servers.",
+    )
+    p.add_argument("--version", action="version",
+                   version=f"nessus-export {__version__}")
+    p.add_argument("--url", help="Nessus base URL (default env NESSUS_URL or "
+                                 "https://localhost:8834)")
+    p.add_argument("--access-key", help="API access key (default env ACCESS_KEY)")
+    p.add_argument("--secret-key", help="API secret key (default env SECRET_KEY)")
+    p.add_argument("--env-file", help="path to a .env file with the keys")
+    p.add_argument("--verify-ssl", action="store_true",
+                   help="verify the server TLS certificate (off by default; "
+                        "Nessus ships a self-signed cert)")
+    p.add_argument("--ca-bundle", help="CA bundle to verify against")
+    p.add_argument("--timeout", type=int, default=60, help="HTTP timeout seconds")
+
+    sub = p.add_subparsers(dest="command", required=True)
+
+    lp = sub.add_parser("list", help="list scans on the server")
+    lp.add_argument("--status", choices=_STATUS_ORDER, help="filter by status")
+    lp.add_argument("--json", action="store_true", help="raw JSON output")
+    lp.set_defaults(func=cmd_list)
+
+    sp = sub.add_parser("status", help="show server status")
+    sp.set_defaults(func=cmd_status)
+
+    ep = sub.add_parser("export", help="export one or more scans")
+    ep.add_argument("scans", nargs="*", metavar="SCAN",
+                    help="scan name(s) or id(s) to export")
+    ep.add_argument("--all", action="store_true", help="export every scan")
+    ep.add_argument("--status", choices=_STATUS_ORDER,
+                    help="with --all, only scans in this status")
+    ep.add_argument("-f", "--format", default="nessus", choices=NATIVE_FORMATS,
+                    help="export format (default: nessus)")
+    ep.add_argument("-m", "--mode", default="auto",
+                    choices=("auto", "native", "reconstruct"),
+                    help="auto: native then fallback; native: API only; "
+                         "reconstruct: rebuild locally (nessus/csv)")
+    ep.add_argument("-o", "--output", help="output file (single scan only)")
+    ep.add_argument("-d", "--out-dir", help="output directory (for multiple scans)")
+    ep.add_argument("--chapters",
+                    help="pdf/html sections, comma-separated: " + ",".join(CHAPTERS))
+    ep.add_argument("--db-password", help="password for the 'db' format")
+    ep.add_argument("--poll-interval", type=float, default=2.0,
+                    help="seconds between export status polls")
+    ep.add_argument("--max-wait", type=float, default=600.0,
+                    help="max seconds to wait for a native export")
+    ep.add_argument("-q", "--quiet", action="store_true",
+                    help="suppress per-step progress")
+    ep.set_defaults(func=cmd_export)
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        client = _make_client(args)
+        return args.func(client, args)
+    except AuthError as e:
+        _eprint(f"auth error: {e}")
+        return 2
+    except TrialModeError as e:
+        _eprint(f"trial mode: {e}")
+        return 3
+    except NessusError as e:
+        _eprint(f"error: {e}")
+        return 1
+    except KeyboardInterrupt:
+        _eprint("interrupted")
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nessus_export/client.py

@@ -0,0 +1,178 @@
+"""Minimal Nessus REST API client (standard library only).
+
+Covers the endpoints needed for listing scans and exporting results, both via
+the native export API and via the direct scan/host/plugin read endpoints used
+by the reconstruction fallback.
+"""
+from __future__ import annotations
+
+import json
+import ssl
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional
+
+
+class NessusError(Exception):
+    """Generic error returned by the Nessus API."""
+
+
+class TrialModeError(NessusError):
+    """Raised when an action is blocked because the server is in trial mode.
+
+    Nessus Essentials / trial installs return errors such as
+    "Export is not allowed in trial mode." for the native export endpoints.
+    """
+
+
+class AuthError(NessusError):
+    """Raised on 401/403 — bad or missing API keys."""
+
+
+def _looks_like_trial(message: str) -> bool:
+    m = message.lower()
+    return "trial mode" in m or "purchase a full nessus license" in m
+
+
+class NessusClient:
+    def __init__(
+        self,
+        url: str = "https://localhost:8834",
+        access_key: str = "",
+        secret_key: str = "",
+        verify_ssl: bool = False,
+        ca_bundle: Optional[str] = None,
+        timeout: int = 60,
+    ) -> None:
+        if not access_key or not secret_key:
+            raise AuthError("access_key and secret_key are required")
+        self.url = url.rstrip("/")
+        self.timeout = timeout
+        self._headers = {
+            "X-ApiKeys": f"accessKey={access_key}; secretKey={secret_key}",
+            "Content-Type": "application/json",
+        }
+        if ca_bundle:
+            self._ctx = ssl.create_default_context(cafile=ca_bundle)
+        elif verify_ssl:
+            self._ctx = ssl.create_default_context()
+        else:
+            self._ctx = ssl.create_default_context()
+            self._ctx.check_hostname = False
+            self._ctx.verify_mode = ssl.CERT_NONE
+
+    # -- low level ---------------------------------------------------------
+    def _request(self, method: str, path: str, body: Optional[dict] = None,
+                 raw: bool = False):
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(
+            self.url + path, data=data, headers=self._headers, method=method
+        )
+        try:
+            with urllib.request.urlopen(req, context=self._ctx,
+                                        timeout=self.timeout) as resp:
+                payload = resp.read()
+        except urllib.error.HTTPError as e:
+            payload = e.read()
+            message = self._extract_error(payload) or f"HTTP {e.code}"
+            # Trial-mode restrictions come back as 403, so check the message
+            # text before treating a 403 as an authentication failure.
+            if _looks_like_trial(message):
+                raise TrialModeError(message) from None
+            if e.code in (401, 403):
+                raise AuthError(message) from None
+            raise NessusError(message) from None
+        except urllib.error.URLError as e:
+            raise NessusError(f"could not reach {self.url}: {e.reason}") from None
+
+        if raw:
+            # Even on 200, an export download may actually be a JSON error body.
+            message = self._extract_error(payload)
+            if message and _looks_like_trial(message):
+                raise TrialModeError(message)
+            return payload
+
+        parsed = json.loads(payload) if payload else {}
+        if isinstance(parsed, dict) and parsed.get("error"):
+            message = parsed["error"]
+            if _looks_like_trial(message):
+                raise TrialModeError(message)
+            raise NessusError(message)
+        return parsed
+
+    @staticmethod
+    def _extract_error(payload: bytes) -> Optional[str]:
+        try:
+            obj = json.loads(payload)
+        except (ValueError, TypeError):
+            return None
+        if isinstance(obj, dict) and obj.get("error"):
+            return str(obj["error"])
+        return None
+
+    # -- high level --------------------------------------------------------
+    def server_status(self) -> Dict[str, Any]:
+        return self._request("GET", "/server/status")
+
+    def list_scans(self) -> List[Dict[str, Any]]:
+        data = self._request("GET", "/scans")
+        return data.get("scans") or []
+
+    def resolve_scan(self, ref: str) -> Dict[str, Any]:
+        """Resolve a scan by numeric id or by (case-insensitive) name."""
+        scans = self.list_scans()
+        if ref.isdigit():
+            for s in scans:
+                if str(s.get("id")) == ref:
+                    return s
+        matches = [s for s in scans if (s.get("name") or "").lower() == ref.lower()]
+        if len(matches) == 1:
+            return matches[0]
+        if len(matches) > 1:
+            ids = ", ".join(str(m["id"]) for m in matches)
+            raise NessusError(
+                f"scan name {ref!r} is ambiguous (ids: {ids}); use the id"
+            )
+        raise NessusError(f"no scan matching {ref!r}")
+
+    def get_scan(self, scan_id: int) -> Dict[str, Any]:
+        return self._request("GET", f"/scans/{scan_id}")
+
+    def get_host(self, scan_id: int, host_id: int) -> Dict[str, Any]:
+        return self._request("GET", f"/scans/{scan_id}/hosts/{host_id}")
+
+    def get_plugin(self, scan_id: int, host_id: int, plugin_id: int) -> Dict[str, Any]:
+        return self._request(
+            "GET", f"/scans/{scan_id}/hosts/{host_id}/plugins/{plugin_id}"
+        )
+
+    # -- native export -----------------------------------------------------
+    def export_request(self, scan_id: int, fmt: str,
+                       extra: Optional[dict] = None) -> Any:
+        body: Dict[str, Any] = {"format": fmt}
+        if extra:
+            body.update(extra)
+        data = self._request("POST", f"/scans/{scan_id}/export", body=body)
+        # Nessus returns {"file": <id>, "token": <token>} (token on newer builds)
+        return data.get("file"), data.get("token")
+
+    def export_status(self, scan_id: int, file_id: Any) -> str:
+        data = self._request("GET", f"/scans/{scan_id}/export/{file_id}/status")
+        return data.get("status", "")
+
+    def export_download(self, scan_id: int, file_id: Any) -> bytes:
+        return self._request(
+            "GET", f"/scans/{scan_id}/export/{file_id}/download", raw=True
+        )
+
+    def wait_and_download(self, scan_id: int, file_id: Any,
+                          poll_interval: float = 2.0,
+                          max_wait: float = 600.0) -> bytes:
+        waited = 0.0
+        while waited < max_wait:
+            if self.export_status(scan_id, file_id) == "ready":
+                return self.export_download(scan_id, file_id)
+            time.sleep(poll_interval)
+            waited += poll_interval
+        raise NessusError(f"export {file_id} not ready after {max_wait:.0f}s")

nessus_export/exporter.py

@@ -0,0 +1,110 @@
+"""Export orchestration: native API export with reconstruction fallback."""
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+from .client import NessusClient, TrialModeError
+from . import reconstruct
+
+ProgressFn = Optional[Callable[[str], None]]
+
+# Formats the native API can produce.
+NATIVE_FORMATS = ("nessus", "csv", "pdf", "html", "db")
+# Formats we can rebuild ourselves without a license.
+RECONSTRUCTABLE = ("nessus", "csv")
+
+EXTENSIONS = {
+    "nessus": ".nessus", "csv": ".csv", "pdf": ".pdf",
+    "html": ".html", "db": ".db",
+}
+
+# Chapter sections valid for pdf/html exports.
+CHAPTERS = (
+    "vuln_hosts_summary", "vuln_by_host", "vuln_by_plugin",
+    "remediations", "compliance_exec", "compliance",
+)
+
+
+def _noop(_: str) -> None:
+    pass
+
+
+class ExportResult:
+    def __init__(self, content: bytes, fmt: str, mode: str, trial: bool):
+        self.content = content      # bytes to write
+        self.fmt = fmt              # requested format
+        self.mode = mode           # "native" or "reconstruct"
+        self.trial = trial         # server reported trial-mode restriction
+        self.extension = EXTENSIONS.get(fmt, ".dat")
+
+
+def _native_export(client: NessusClient, scan_id: int, fmt: str,
+                   chapters: Optional[List[str]], db_password: Optional[str],
+                   poll_interval: float, max_wait: float,
+                   progress: Callable[[str], None]) -> bytes:
+    extra: Dict[str, Any] = {}
+    if fmt in ("pdf", "html"):
+        # Nessus rejects a pdf/html export request that lacks a chapter list,
+        # so default to a per-host vulnerability report when none is given.
+        extra["chapters"] = ";".join(chapters or ["vuln_by_host"])
+    if fmt == "db":
+        if not db_password:
+            raise ValueError("the 'db' format requires --db-password")
+        extra["password"] = db_password
+    progress(f"requesting native {fmt} export")
+    file_id, _token = client.export_request(scan_id, fmt, extra)
+    progress(f"export queued (file {file_id}); polling")
+    content = client.wait_and_download(scan_id, file_id,
+                                       poll_interval=poll_interval,
+                                       max_wait=max_wait)
+    progress(f"downloaded {len(content)} bytes")
+    return content
+
+
+def _reconstruct_export(client: NessusClient, scan_id: int, fmt: str,
+                        progress: Callable[[str], None]) -> bytes:
+    progress("reconstructing from read API (this walks every host/plugin)")
+    data = reconstruct.collect(client, scan_id, progress=progress)
+    if fmt == "nessus":
+        return reconstruct.build_nessus_xml(data).encode("utf-8")
+    if fmt == "csv":
+        return reconstruct.build_csv(data).encode("utf-8")
+    raise ValueError(f"format {fmt!r} cannot be reconstructed")
+
+
+def export_scan(client: NessusClient, scan_id: int, fmt: str = "nessus",
+                mode: str = "auto", chapters: Optional[List[str]] = None,
+                db_password: Optional[str] = None,
+                poll_interval: float = 2.0, max_wait: float = 600.0,
+                progress: ProgressFn = None) -> ExportResult:
+    """Export a single scan.
+
+    mode:
+      auto        try native; on trial-mode restriction, fall back to
+                  reconstruction if the format supports it.
+      native      native API only (errors out under trial mode).
+      reconstruct skip the API export and rebuild locally (nessus/csv only).
+    """
+    progress = progress or _noop
+    if fmt not in NATIVE_FORMATS:
+        raise ValueError(f"unknown format {fmt!r}; choose from {NATIVE_FORMATS}")
+
+    if mode == "reconstruct":
+        content = _reconstruct_export(client, scan_id, fmt, progress)
+        return ExportResult(content, fmt, "reconstruct", trial=False)
+
+    try:
+        content = _native_export(client, scan_id, fmt, chapters, db_password,
+                                 poll_interval, max_wait, progress)
+        return ExportResult(content, fmt, "native", trial=False)
+    except TrialModeError as e:
+        if mode == "native":
+            raise
+        if fmt not in RECONSTRUCTABLE:
+            raise TrialModeError(
+                f"{e} — reconstruction fallback only supports "
+                f"{RECONSTRUCTABLE}, not {fmt!r}."
+            ) from None
+        progress(f"native export blocked (trial mode); falling back: {e}")
+        content = _reconstruct_export(client, scan_id, fmt, progress)
+        return ExportResult(content, fmt, "reconstruct", trial=True)

nessus_export/reconstruct.py

@@ -0,0 +1,218 @@
+"""Reconstruct .nessus (NessusClientData_v2) and CSV output from the read API.
+
+Used as a fallback when the native export endpoint is unavailable (e.g. the
+server is in trial mode). The scan/host/plugin read endpoints are not
+license-gated, so the findings themselves are fully recoverable; the scan
+*policy* metadata is not exposed and is therefore emitted as a stub.
+"""
+from __future__ import annotations
+
+import csv
+import io
+from typing import Any, Callable, Dict, List, Optional
+from xml.sax.saxutils import escape, quoteattr
+
+from .client import NessusClient
+
+# Host-property tags surfaced from the host "info" block, in a stable order.
+_HOST_TAGS = [
+    "host-ip", "host-fqdn", "host-rdns", "netbios-name", "mac-address",
+    "operating-system", "os", "system-type", "host_start", "host_end",
+    "HOST_START", "HOST_END",
+]
+
+# risk_information keys emitted verbatim as ReportItem children.
+_RISK_KEYS = [
+    "cvss_base_score", "cvss_vector", "cvss_temporal_score", "cvss_temporal_vector",
+    "cvss3_base_score", "cvss3_vector", "cvss3_temporal_score",
+    "cvss3_temporal_vector", "cvss_score_source", "stig_severity",
+]
+
+ProgressFn = Optional[Callable[[str], None]]
+
+
+def _noop(_: str) -> None:
+    pass
+
+
+def collect(client: NessusClient, scan_id: int,
+            progress: ProgressFn = None) -> Dict[str, Any]:
+    """Fetch scan + per-host + per-plugin data into a normalised structure."""
+    progress = progress or _noop
+    scan = client.get_scan(scan_id)
+    info = scan.get("info", {}) or {}
+    hosts_out: List[Dict[str, Any]] = []
+
+    raw_hosts = scan.get("hosts") or []
+    for hi, h in enumerate(raw_hosts, 1):
+        hid = h["host_id"]
+        hd = client.get_host(scan_id, hid)
+        hinfo = hd.get("info", {}) or {}
+        vulns = hd.get("vulnerabilities") or []
+        progress(f"host {hi}/{len(raw_hosts)} "
+                 f"({hinfo.get('host-ip') or h.get('hostname')}): "
+                 f"{len(vulns)} plugins")
+        findings: List[Dict[str, Any]] = []
+        for v in vulns:
+            pid = v["plugin_id"]
+            det = client.get_plugin(scan_id, hid, pid)
+            pa = (((det.get("info") or {}).get("plugindescription") or {})
+                  .get("pluginattributes", {}) or {})
+            pinfo = pa.get("plugin_information", {}) or {}
+            risk = pa.get("risk_information", {}) or {}
+            vuln = pa.get("vuln_information", {}) or {}
+
+            instances = []  # one per (port, output)
+            for o in det.get("outputs") or []:
+                output = o.get("plugin_output") or ""
+                ports = o.get("ports") or {}
+                if not ports:
+                    instances.append(("0", "tcp", "", output))
+                for pk in ports:
+                    parts = [x.strip() for x in pk.split("/")]
+                    port = parts[0] if parts and parts[0] else "0"
+                    proto = parts[1] if len(parts) > 1 and parts[1] else "tcp"
+                    svc = parts[2] if len(parts) > 2 else ""
+                    instances.append((port, proto, svc, output))
+            if not instances:
+                instances.append(("0", "tcp", "", ""))
+
+            cves, bids, xrefs = [], [], []
+            for ref in (pa.get("ref_information") or {}).get("ref") or []:
+                name = (ref.get("name") or "").lower()
+                for val in (ref.get("values") or {}).get("value") or []:
+                    if name == "cve":
+                        cves.append(val)
+                    elif name == "bid":
+                        bids.append(val)
+                    else:
+                        xrefs.append(f"{name.upper()}:{val}")
+
+            findings.append({
+                "plugin_id": pid,
+                "plugin_name": pa.get("plugin_name") or v.get("plugin_name") or "",
+                "plugin_family": pinfo.get("plugin_family")
+                                 or v.get("plugin_family") or "",
+                "severity": v.get("severity", pa.get("severity", 0)),
+                "attrs": pa,
+                "risk": risk,
+                "vuln": vuln,
+                "pinfo": pinfo,
+                "cves": cves, "bids": bids, "xrefs": xrefs,
+                "instances": instances,
+            })
+        hosts_out.append({
+            "host_id": hid,
+            "name": hinfo.get("host-ip") or h.get("hostname") or str(hid),
+            "info": hinfo,
+            "findings": findings,
+        })
+    return {"info": info, "hosts": hosts_out}
+
+
+def _child(tag: str, text: Any) -> str:
+    if text is None or text == "":
+        return ""
+    return f"        <{tag}>{escape(str(text))}</{tag}>\n"
+
+
+def build_nessus_xml(data: Dict[str, Any]) -> str:
+    info = data["info"]
+    name = info.get("name", "scan")
+    buf = io.StringIO()
+    buf.write('<?xml version="1.0" encoding="UTF-8"?>\n<NessusClientData_v2>\n')
+    # Policy stub — trial mode does not expose real policy/preferences data.
+    buf.write("  <Policy>\n")
+    buf.write(f"    <policyName>{escape(name)}</policyName>\n")
+    buf.write("    <Preferences>\n"
+              "      <ServerPreferences></ServerPreferences>\n"
+              "      <PluginsPreferences></PluginsPreferences>\n"
+              "    </Preferences>\n")
+    buf.write("    <FamilySelection></FamilySelection>\n"
+              "    <IndividualPluginSelection></IndividualPluginSelection>\n")
+    buf.write("  </Policy>\n")
+    buf.write(f'  <Report name={quoteattr(name)} '
+              'xmlns:cm="http://www.nessus.org/cm">\n')
+
+    for host in data["hosts"]:
+        buf.write(f'    <ReportHost name={quoteattr(str(host["name"]))}>\n')
+        buf.write("      <HostProperties>\n")
+        hinfo = host["info"]
+        for t in _HOST_TAGS:
+            if hinfo.get(t) not in (None, ""):
+                buf.write(f'        <tag name={quoteattr(t)}>'
+                          f'{escape(str(hinfo[t]))}</tag>\n')
+        buf.write("      </HostProperties>\n")
+
+        for f in host["findings"]:
+            pa, risk, vuln, pinfo = f["attrs"], f["risk"], f["vuln"], f["pinfo"]
+            for port, proto, svc, output in f["instances"]:
+                attrs = (f'port="{escape(port)}" svc_name={quoteattr(svc)} '
+                         f'protocol="{escape(proto)}" severity="{f["severity"]}" '
+                         f'pluginID="{f["plugin_id"]}" '
+                         f'pluginName={quoteattr(str(f["plugin_name"]))} '
+                         f'pluginFamily={quoteattr(str(f["plugin_family"]))}')
+                buf.write(f"      <ReportItem {attrs}>\n")
+                buf.write(_child("synopsis", pa.get("synopsis")))
+                buf.write(_child("description", pa.get("description")))
+                buf.write(_child("solution", pa.get("solution")))
+                buf.write(_child("risk_factor", risk.get("risk_factor")))
+                for k in _RISK_KEYS:
+                    buf.write(_child(k, risk.get(k)))
+                buf.write(_child("vpr_score", pa.get("vpr_score")))
+                buf.write(_child("epss_score", pa.get("epss_score")))
+                buf.write(_child("exploit_available", vuln.get("exploit_available")))
+                buf.write(_child("exploitability_ease", vuln.get("exploitability_ease")))
+                buf.write(_child("cpe", vuln.get("cpe")))
+                buf.write(_child("plugin_type", pinfo.get("plugin_type")))
+                buf.write(_child("plugin_version", pinfo.get("plugin_version")))
+                buf.write(_child("plugin_publication_date",
+                                 pinfo.get("plugin_publication_date")))
+                buf.write(_child("plugin_modification_date",
+                                 pinfo.get("plugin_modification_date")))
+                buf.write(_child("fname", pa.get("fname")))
+                for sa in pa.get("see_also") or []:
+                    buf.write(_child("see_also", sa))
+                for cve in f["cves"]:
+                    buf.write(_child("cve", cve))
+                for bid in f["bids"]:
+                    buf.write(_child("bid", bid))
+                for xref in f["xrefs"]:
+                    buf.write(_child("xref", xref))
+                buf.write(_child("plugin_output", output))
+                buf.write("      </ReportItem>\n")
+        buf.write("    </ReportHost>\n")
+    buf.write("  </Report>\n</NessusClientData_v2>\n")
+    return buf.getvalue()
+
+
+_SEV = {0: "None", 1: "Low", 2: "Medium", 3: "High", 4: "Critical"}
+
+
+def build_csv(data: Dict[str, Any]) -> str:
+    """Approximate the native Nessus CSV export column set."""
+    buf = io.StringIO()
+    w = csv.writer(buf)
+    w.writerow(["Plugin ID", "CVE", "CVSS v2.0 Base Score", "Risk", "Host",
+                "Protocol", "Port", "Name", "Synopsis", "Description",
+                "Solution", "See Also", "Plugin Output"])
+    for host in data["hosts"]:
+        for f in host["findings"]:
+            pa, risk = f["attrs"], f["risk"]
+            for port, proto, svc, output in f["instances"]:
+                w.writerow([
+                    f["plugin_id"],
+                    ", ".join(f["cves"]),
+                    risk.get("cvss_base_score", ""),
+                    _SEV.get(f["severity"], f["severity"]),
+                    host["name"],
+                    proto,
+                    port,
+                    f["plugin_name"],
+                    pa.get("synopsis", ""),
+                    pa.get("description", ""),
+                    pa.get("solution", ""),
+                    "\n".join(pa.get("see_also") or []),
+                    output,
+                ])
+    return buf.getvalue()

nessus_export-0.1.0.dist-info/METADATA

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: nessus-export
+Version: 0.1.0
+Summary: Export Nessus scan results via the API, with a reconstruction fallback for trial-mode servers.
+Author-email: setuidloot <michael@mccord.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/setuidloot/nessus-export
+Project-URL: Issues, https://github.com/setuidloot/nessus-export/issues
+Keywords: nessus,tenable,security,vulnerability,export,scanner
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nessus-export
+
+[![CI](https://github.com/setuidloot/nessus-export/actions/workflows/ci.yml/badge.svg)](https://github.com/setuidloot/nessus-export/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/nessus-export.svg)](https://pypi.org/project/nessus-export/)
+[![Python](https://img.shields.io/pypi/pyversions/nessus-export.svg)](https://pypi.org/project/nessus-export/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Export [Nessus](https://www.tenable.com/products/nessus) scan results from the
+command line via the REST API — **with an automatic fallback that reconstructs a
+valid `.nessus` file even when the server's native export is locked** (as it is
+on Nessus Essentials / trial installations).
+
+Zero dependencies. Pure Python standard library.
+
+---
+
+## Why this exists
+
+Nessus has a perfectly good export API (`POST /scans/{id}/export`). But on
+**Nessus Essentials** and **trial** installations, every export format is
+license-gated. Ask for one and the server refuses:
+
+```json
+{ "error": "Export is not allowed in trial mode. Please purchase a full Nessus license to enable exports." }
+```
+
+That's frustrating, because **the scan data itself is not restricted** — the
+per-scan, per-host, and per-plugin *read* endpoints (`GET /scans/{id}`,
+`GET /scans/{id}/hosts/{host}`, `GET /scans/{id}/hosts/{host}/plugins/{plugin}`)
+return everything: findings, ports/services, severities, CVSS scores, CVEs,
+plugin output, remediation text. The export endpoint is gated; the data is not.
+
+**nessus-export** does the obvious thing:
+
+1. **Try the native export API first.** If your server is licensed, you get the
+   real, byte-for-byte Nessus export (`.nessus`, CSV, PDF, HTML, DB) — no
+   reconstruction, nothing lost.
+2. **If the server is in trial mode**, it transparently reads the scan data and
+   **reconstructs** a spec-compliant `NessusClientData_v2` (`.nessus`) or CSV
+   file itself.
+
+The reconstructed `.nessus` imports cleanly back into Nessus and into anything
+else that consumes the format (parsers, dashboards, DefectDojo, etc.).
+
+## Install
+
+```bash
+pip install nessus-export
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/setuidloot/nessus-export
+cd nessus-export
+pip install .
+# or run without installing:
+python -m nessus_export --help
+```
+
+Requires Python 3.8+. No third-party packages.
+
+## Authentication
+
+Generate API keys in Nessus: **Settings → My Account → API Keys → Generate**.
+
+Provide them any of these ways (checked in order):
+
+- CLI flags: `--access-key` / `--secret-key`
+- Environment: `ACCESS_KEY` / `SECRET_KEY` (or `NESSUS_ACCESS_KEY` / `NESSUS_SECRET_KEY`)
+- A `.env` file in the working directory (auto-loaded), or `--env-file PATH`
+
+```bash
+cp .env.example .env      # then edit in your keys
+```
+
+Nessus ships a self-signed TLS certificate, so certificate verification is
+**off by default**. Turn it on with `--verify-ssl` (optionally `--ca-bundle`).
+
+## Usage
+
+```bash
+# List scans on the server
+nessus-export list
+nessus-export list --status completed
+nessus-export list --json
+
+# Export one scan by name or id (defaults to .nessus, into the current dir)
+nessus-export export myscan
+nessus-export export 5 -o results.nessus
+
+# Pick a format
+nessus-export export myscan -f csv
+nessus-export export myscan -f pdf --chapters vuln_by_host,remediations
+
+# Export several scans into a directory
+nessus-export export web-scan db-scan -d ./exports
+nessus-export export --all --status completed -d ./exports
+
+# Force behavior
+nessus-export export myscan -m native       # native API only (fails under trial)
+nessus-export export myscan -m reconstruct   # skip the API, rebuild locally
+```
+
+### Commands
+
+| Command  | Purpose                                             |
+|----------|-----------------------------------------------------|
+| `list`   | List scans (`--status`, `--json`)                   |
+| `export` | Export one/several/all scans                        |
+| `status` | Show server status                                  |
+
+### Key `export` options
+
+| Option              | Description                                                        |
+|---------------------|-------------------------------------------------------------------|
+| `SCAN…`             | One or more scan names or ids                                     |
+| `--all`             | Export every scan (combine with `--status`)                       |
+| `-f, --format`      | `nessus` (default), `csv`, `pdf`, `html`, `db`                    |
+| `-m, --mode`        | `auto` (default), `native`, `reconstruct`                        |
+| `-o, --output`      | Output file (single scan)                                        |
+| `-d, --out-dir`     | Output directory (multiple scans; filenames from scan names)     |
+| `--chapters`        | `pdf`/`html` sections, comma-separated                           |
+| `--db-password`     | Required for `-f db`                                              |
+| `-q, --quiet`       | Suppress per-step progress                                       |
+
+### Export modes
+
+- **`auto`** *(default)* — try the native API; if the server reports a
+  trial-mode restriction, fall back to reconstruction (for `nessus`/`csv`).
+- **`native`** — only use the API. Exits non-zero under trial mode. Use this
+  when you specifically want the licensed, byte-exact export or nothing.
+- **`reconstruct`** — skip the API export entirely and rebuild locally. Handy
+  for consistent output across mixed licensed/trial servers.
+
+### Formats and modes at a glance
+
+| Format   | Native (licensed) | Reconstruction fallback (trial) |
+|----------|:-----------------:|:-------------------------------:|
+| `nessus` | ✅                | ✅                              |
+| `csv`    | ✅                | ✅                              |
+| `pdf`    | ✅                | ❌ (needs a licensed server)    |
+| `html`   | ✅                | ❌ (needs a licensed server)    |
+| `db`     | ✅                | ❌ (needs a licensed server)    |
+
+`pdf`, `html`, and `db` are report renderings Nessus builds server-side; there's
+no faithful way to reproduce them from the read API, so they require a licensed
+server. In `auto` mode, requesting one on a trial server yields a clear error
+rather than a degraded file.
+
+## Caveats when reconstructing (trial mode)
+
+When the tool falls back to reconstruction, the **findings are complete and
+faithful** — hosts, ports/services, severities, CVSS v2/v3 scores and vectors,
+CVEs/BIDs/xrefs, synopsis, description, solution, see-also, and plugin output
+are all carried through. But a reconstructed file is **not byte-identical** to a
+licensed export, in these specific ways:
+
+1. **The `<Policy>` block is a stub.** A licensed export embeds the full scan
+   policy — every server/plugin preference and the plugin-family selection.
+   Trial mode does not expose that data through the API, so the policy elements
+   are emitted empty. Your *findings* are intact; the scan *configuration*
+   metadata is not.
+2. **`HostProperties` is a subset.** It contains what the host-info endpoint
+   returns (IP, FQDN, OS, MAC, start/end time, …) — generally fewer tags than a
+   native export writes.
+3. **Plugin output honors the API's truncation.** Very large outputs flagged
+   `max_attachments_exceeded` by the API are carried through exactly as the API
+   returned them (i.e. possibly truncated).
+4. **No attachments.** Binary attachments some plugins produce are not
+   reassembled.
+5. **CSV columns approximate** the native Nessus CSV layout; exact column
+   ordering/quoting may differ slightly.
+
+If any of that matters for your use case, use a licensed server with
+`-m native`. For the common need — "get my findings out in a portable,
+importable format" — the reconstructed `.nessus` does the job.
+
+## Supported Nessus versions
+
+Developed and verified against **Nessus 10.12.1** (latest at time of writing);
+expected to work on the Nessus 10.x API generally. It uses only long-standing,
+stable REST endpoints, so older 8.x/9.x servers will likely work too but are
+untested. If you run it against another version, a PR updating this section is
+welcome.
+
+| Nessus version | Status              |
+|----------------|---------------------|
+| 10.12.1        | ✅ Verified         |
+| 10.x (other)   | 🟡 Expected to work |
+| 8.x – 9.x      | 🟡 Likely, untested |
+
+## How it works
+
+```
+export ──► native API export ──► ready? ──► download  (licensed servers)
+                │
+                └─ trial-mode 403 ──► read scan + hosts + plugins
+                                       └─► serialize NessusClientData_v2 / CSV
+```
+
+The reconstruction walks every host and every plugin finding, so it makes more
+API calls than a native export — expect it to take longer on large scans.
+
+## Library use
+
+```python
+from nessus_export.client import NessusClient
+from nessus_export.exporter import export_scan
+
+client = NessusClient(url="https://localhost:8834",
+                      access_key="…", secret_key="…")
+result = export_scan(client, scan_id=5, fmt="nessus", mode="auto")
+open("myscan.nessus", "wb").write(result.content)
+print(result.mode)   # "native" or "reconstruct"
+```
+
+## Security notes
+
+- Never commit your `.env` / API keys. `.gitignore` already excludes `.env` and
+  common export artifacts (`*.nessus`, `*.pdf`, `*.db`).
+- Exported scan results contain sensitive vulnerability data — handle and store
+  them accordingly.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Disclaimer
+
+Not affiliated with or endorsed by Tenable, Inc. "Nessus" is a trademark of
+Tenable, Inc. This tool uses only documented REST endpoints and does not
+circumvent licensing: it reads data the API already exposes and formats it
+locally.

nessus_export-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+nessus_export/__init__.py,sha256=pYp-aFj3TCJHTE6LuNkhJlwpIdvvuI-IFMe77LTIRy4,139
+nessus_export/__main__.py,sha256=4JMK66Wj4uLZTKbF-sT3LAxOsr6buig77PmOkJCRRxw,83
+nessus_export/cli.py,sha256=_zAECQgbtqWDKzDb-h8cPKi_DdCTJTIYZaLWn2SM19A,9366
+nessus_export/client.py,sha256=Vc5bKyk_6VImc0hHKAzPn36_dvHHEHTPGlvupL_UrIE,6898
+nessus_export/exporter.py,sha256=xnpKAZhBwwejG_5nFz682OQMK5cV9kdtOvnI0LjVpYk,4534
+nessus_export/reconstruct.py,sha256=5lZxDs0F48H6KZZb3OAeHmZSY7fLKTVinLLPZkAAFCg,9585
+nessus_export-0.1.0.dist-info/licenses/LICENSE,sha256=uqLgtzci92MJY4mZZnJtjQzfDJd0jElg04pnm1JIa3U,1067
+nessus_export-0.1.0.dist-info/METADATA,sha256=-gLyUOOLWT3NOtKtpFz9tZ6YFiVUzZTIOVXXJlnIJBw,10623
+nessus_export-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+nessus_export-0.1.0.dist-info/entry_points.txt,sha256=tcv5pGQaycggjeMyvufXmI-rEAvD2FVfFKWOMnX1Jho,57
+nessus_export-0.1.0.dist-info/top_level.txt,sha256=A1yBqJUC5nAUr0sCGmpfhJ8RKGGvlrkj2meJDL0pDr0,14
+nessus_export-0.1.0.dist-info/RECORD,,

nessus_export-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nessus_export-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nessus-export = nessus_export.cli:main

nessus_export-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 setuidloot
+
+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.

nessus_export-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nessus_export