vardrrunner 0.28.0__py3-none-any.whl

vardrrunner/__init__.py

@@ -0,0 +1,8 @@
+"""VardrRunner — local automation runner for the VardrSec product family.
+
+The version literal below is the single source of truth: `pyproject.toml` reads
+it via setuptools' dynamic-version mechanism, and the heartbeat reports it to the
+backend. Bump it here (and add a CHANGELOG entry) on every release.
+"""
+
+__version__ = "0.28.0"

vardrrunner/api.py

@@ -0,0 +1,173 @@
+"""
+Thin wrapper around requests for authenticated calls to the VardrMap API.
+All methods raise requests.HTTPError on non-2xx responses.
+
+The session retries transient failures (connection errors and 429/5xx) with
+exponential backoff so a long-running daemon survives network blips and brief
+backend restarts. Retries are limited to idempotent methods (urllib3's default:
+GET/HEAD/PUT/DELETE/OPTIONS/TRACE) — POST and PATCH are never auto-retried, so a
+dropped response can't cause a double-claim, double-import, or duplicate event.
+"""
+
+import platform
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from vardrrunner import __version__
+
+# Statuses worth retrying: rate-limit + transient server/proxy errors.
+_RETRY_STATUSES = (429, 500, 502, 503, 504)
+
+
+class VardrMapClient:
+    def __init__(
+        self,
+        api_url: str,
+        api_key: str,
+        *,
+        retries: int = 3,
+        backoff_factor: float = 0.5,
+    ):
+        self.base = api_url.rstrip("/")
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "Authorization": f"Bearer {api_key}",
+                # Identify the runner + version in backend logs.
+                "User-Agent": f"vardrrunner/{__version__} ({platform.system()})",
+            }
+        )
+
+        # Mount a retry-with-backoff adapter for transient failures. allowed_methods
+        # is left at urllib3's idempotent-only default so POST/PATCH are not retried.
+        retry = Retry(
+            total=retries,
+            connect=retries,
+            read=retries,
+            status=retries,
+            backoff_factor=backoff_factor,
+            status_forcelist=_RETRY_STATUSES,
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self.session.mount("https://", adapter)
+        self.session.mount("http://", adapter)
+
+    def _url(self, path: str) -> str:
+        return f"{self.base}/{path.lstrip('/')}"
+
+    def get(self, path: str, params: dict | None = None) -> Any:
+        r = self.session.get(self._url(path), params=params, timeout=30)
+        r.raise_for_status()
+        return r.json()
+
+    def post(
+        self,
+        path: str,
+        json: dict | None = None,
+        files: dict | None = None,
+        data: dict | None = None,
+    ) -> Any:
+        r = self.session.post(self._url(path), json=json, files=files, data=data, timeout=60)
+        r.raise_for_status()
+        return r.json()
+
+    def whoami(self) -> dict:
+        return self.get("/me")
+
+    def engagements(self) -> list[dict]:
+        data = self.get("/engagements")
+        # VardrMap returns both keys during the engagements → engagements
+        # transition; prefer the new name and fall back to the old one.
+        return data.get("engagements") or data.get("engagements", [])
+
+    def engagement(self, engagement_id: str) -> dict:
+        return self.get(f"/engagements/{engagement_id}")
+
+    def scope(self, engagement_id: str) -> dict:
+        """Returns {"in": [...], "out": [...]} scope lists."""
+        return self.engagement(engagement_id).get("scope", {"in": [], "out": []})
+
+    # Backend rejects limit values above this with 422.
+    RECON_PAGE_SIZE = 500
+
+    def recon(
+        self, engagement_id: str, limit: int = 100, status_code: int | None = None
+    ) -> list[dict]:
+        """Fetch recon items, paginating in RECON_PAGE_SIZE chunks to avoid backend 422s."""
+        results: list[dict] = []
+        offset = 0
+        page_size = min(limit, self.RECON_PAGE_SIZE)
+
+        while len(results) < limit:
+            remaining = limit - len(results)
+            fetch = min(remaining, page_size)
+            params: dict = {"limit": fetch, "offset": offset}
+            if status_code is not None:
+                params["status_code"] = status_code
+            page = self.get(f"/engagements/{engagement_id}/recon", params=params).get("recon", [])
+            results.extend(page)
+            if len(page) < fetch:
+                break
+            offset += fetch
+
+        return results
+
+    def import_file(self, engagement_id: str, tool_type: str, file_path: str) -> dict:
+        with open(file_path, "rb") as fh:
+            return self.post(
+                f"/engagements/{engagement_id}/imports",
+                files={"file": (file_path, fh, "application/json")},
+                data={"tool_type": tool_type},
+            )
+
+    # ------------------------------------------------------------------
+    # Scan jobs (job queue for UI-initiated scans)
+    # ------------------------------------------------------------------
+
+    def pending_jobs(self) -> list[dict]:
+        """Return all pending jobs owned by the authenticated user."""
+        return self.get("/jobs/pending").get("jobs", [])
+
+    def claim_job(self, job_id: str) -> dict:
+        """Atomically claim a pending job. Raises HTTPError 409 if already claimed."""
+        return self.post(f"/jobs/{job_id}/claim")
+
+    def complete_job(self, job_id: str, status: str, error: str = "") -> dict:
+        """Mark a job done or failed."""
+        payload: dict = {"status": status}
+        if error:
+            payload["error_message"] = error
+        return self.patch(f"/jobs/{job_id}", json=payload)
+
+    def patch(self, path: str, json: dict | None = None) -> Any:
+        r = self.session.patch(self._url(path), json=json, timeout=30)
+        r.raise_for_status()
+        return r.json()
+
+    # ------------------------------------------------------------------
+    # Runner heartbeat
+    # ------------------------------------------------------------------
+
+    def send_heartbeat(self, payload: dict) -> dict:
+        """Post runner status (hostname, version, os, tools) to the backend."""
+        return self.post("/runner/heartbeat", json=payload)
+
+    # ------------------------------------------------------------------
+    # Job events
+    # ------------------------------------------------------------------
+
+    def post_event(self, job_id: str, kind: str, text: str = "") -> dict:
+        """Post a lifecycle event for a job (started, running, done, failed, …)."""
+        return self.post(f"/jobs/{job_id}/events", json={"kind": kind, "text": text})
+
+    # ------------------------------------------------------------------
+    # Services
+    # ------------------------------------------------------------------
+
+    def create_services(self, engagement_id: str, services: list[dict]) -> dict:
+        """Bulk-upsert nmap service results for an engagement."""
+        return self.post(f"/engagements/{engagement_id}/services", json={"services": services})

vardrrunner/cli.py

@@ -0,0 +1,440 @@
+"""
+vardrrunner — local automation runner for the VardrSec product family.
+
+Runs security tooling on the operator's machine and syncs results to a VardrSec
+backend (today: VardrMap) over HTTP. See https://github.com/VardrSec/VardrRunner.
+"""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+
+from vardrrunner.commands import auth, engagements, imports, jobs, run
+from vardrrunner.commands import daemon as daemon_cmd
+from vardrrunner.commands import doctor as doctor_cmd
+from vardrrunner.commands import heartbeat as heartbeat_cmd
+from vardrrunner.commands import pipeline as pipeline_cmd
+from vardrrunner.commands import status as status_cmd
+
+console = Console()
+
+# Shared across every command that resolves targets, so the cap is described
+# identically in `run --help` and `pipeline run --help`.
+_MAX_TARGETS_HELP = "Abort if resolved targets exceed this count (0 disables the cap)"
+
+app = typer.Typer(
+    name="vardrrunner",
+    help="Local runner for VardrMap. Runs tools locally, uploads results to your VardrMap instance.",
+    no_args_is_help=True,
+)
+
+# --------------------------------------------------------------------------- #
+# Auth
+# --------------------------------------------------------------------------- #
+
+login_app = typer.Typer(help="Log in to a Vardr product.", no_args_is_help=True)
+app.add_typer(login_app, name="login")
+login_app.command("vardrmap")(auth.login_vardrmap)
+
+
+@app.command()
+def status():
+    """Show config, API connectivity, and local tool availability."""
+    status_cmd.run_status()
+
+
+@app.command()
+def doctor(
+    as_json: bool = typer.Option(False, "--json", help="Emit a machine-readable JSON report"),
+):
+    """Deep preflight before unattended use — exits non-zero on actionable failures."""
+    doctor_cmd.run_doctor(as_json=as_json)
+
+
+@app.command()
+def heartbeat():
+    """Send a heartbeat to VardrMap — reports hostname, version, and tool status."""
+    heartbeat_cmd.send_heartbeat(quiet=False)
+
+
+@app.command()
+def logout():
+    """Remove stored credentials (keychain + config file); keep the API URL."""
+    auth.logout()
+
+
+@app.command()
+def whoami():
+    """Show the identity tied to the configured API key."""
+    auth.whoami()
+
+
+# --------------------------------------------------------------------------- #
+# Programs
+# --------------------------------------------------------------------------- #
+
+
+@app.command()
+def engagement_list():
+    """List all engagements in VardrMap."""
+    engagements.list_engagements()
+
+
+# Alias `engagements` → `engagement-list` for a more natural UX
+app.command(name="engagements")(engagement_list)
+# Retired name, kept so existing habits and scripts do not break. Hidden from
+# --help so only the current name is advertised.
+app.command(name="programs", hidden=True)(engagement_list)
+
+
+@app.command()
+def scope(engagement_id: str = typer.Argument(..., help="Engagement UUID")):
+    """Show in-scope and out-of-scope items for an engagement."""
+    engagements.show_scope(engagement_id)
+
+
+# --------------------------------------------------------------------------- #
+# Import
+# --------------------------------------------------------------------------- #
+
+import_app = typer.Typer(help="Import tool output files into VardrMap.", no_args_is_help=True)
+app.add_typer(import_app, name="import")
+
+
+@import_app.command("nuclei")
+def import_nuclei(
+    engagement_id: str = typer.Option(
+        ..., "--engagement", "--program", "-p", help="Engagement UUID"
+    ),
+    file: Path = typer.Option(..., "--file", "-f", help="Path to nuclei JSONL output"),
+):
+    """Import a nuclei output file."""
+    imports.import_file("nuclei", engagement_id, file)
+
+
+@import_app.command("httpx")
+def import_httpx(
+    engagement_id: str = typer.Option(
+        ..., "--engagement", "--program", "-p", help="Engagement UUID"
+    ),
+    file: Path = typer.Option(..., "--file", "-f", help="Path to httpx JSON/JSONL output"),
+):
+    """Import an httpx output file."""
+    imports.import_file("httpx", engagement_id, file)
+
+
+# --------------------------------------------------------------------------- #
+# Run
+# --------------------------------------------------------------------------- #
+
+# --------------------------------------------------------------------------- #
+# Jobs
+# --------------------------------------------------------------------------- #
+
+# --------------------------------------------------------------------------- #
+# Daemon
+# --------------------------------------------------------------------------- #
+
+daemon_app = typer.Typer(
+    help="Long-running background worker: polls jobs and sends heartbeats.", no_args_is_help=True
+)
+app.add_typer(daemon_app, name="daemon")
+
+
+@daemon_app.command("start")
+def daemon_start(
+    detach: bool = typer.Option(False, "--detach", "-d", help="Run in background"),
+    poll_interval: int = typer.Option(5, "--poll-interval", help="Seconds between job polls"),
+    heartbeat_interval: int = typer.Option(
+        60, "--heartbeat-interval", help="Seconds between heartbeats"
+    ),
+    log_file: Path | None = typer.Option(None, "--log-file", help="Append output to file"),
+):
+    """Start the daemon (foreground by default, use --detach for background)."""
+    daemon_cmd.start(
+        detach=detach,
+        poll_interval=poll_interval,
+        heartbeat_interval=heartbeat_interval,
+        log_file=log_file,
+    )
+
+
+@daemon_app.command("stop")
+def daemon_stop():
+    """Stop a running daemon."""
+    daemon_cmd.stop()
+
+
+@daemon_app.command("status")
+def daemon_status():
+    """Show whether the daemon is running."""
+    daemon_cmd.status()
+
+
+# --------------------------------------------------------------------------- #
+# Jobs
+# --------------------------------------------------------------------------- #
+
+jobs_app = typer.Typer(help="Manage and execute scan job queue.", no_args_is_help=True)
+app.add_typer(jobs_app, name="jobs")
+
+
+@jobs_app.command("list")
+def jobs_list():
+    """List pending scan jobs."""
+    jobs.list_jobs()
+
+
+@jobs_app.command("run")
+def jobs_run(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompts"),
+):
+    """Claim and execute all pending scan jobs."""
+    jobs.run_jobs(yes=yes)
+
+
+# --------------------------------------------------------------------------- #
+# Run
+# --------------------------------------------------------------------------- #
+
+run_app = typer.Typer(
+    help="Run a tool locally and upload results to VardrMap.", no_args_is_help=True
+)
+app.add_typer(run_app, name="run")
+
+
+@run_app.command("httpx")
+def run_httpx(
+    engagement_id: str = typer.Option(
+        ..., "--engagement", "--program", "-p", help="Engagement UUID"
+    ),
+    scope: bool = typer.Option(False, "--scope", help="Use in-scope assets from VardrMap"),
+    from_recon: bool = typer.Option(
+        False, "--from-recon", help="Use live recon items from VardrMap"
+    ),
+    target: str | None = typer.Option(None, "--target", help="Single inline target"),
+    targets_file: Path | None = typer.Option(None, "--targets", help="Path to a targets .txt file"),
+    limit: int = typer.Option(100, "--limit", help="Max recon items to use (--from-recon only)"),
+    status_code: int | None = typer.Option(
+        None, "--status-code", help="Filter recon by HTTP status code"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    max_targets: int = typer.Option(
+        run.MAX_TARGETS_DEFAULT, "--max-targets", help=_MAX_TARGETS_HELP
+    ),
+):
+    """Run httpx locally and upload results to VardrMap."""
+    run.run_httpx(
+        engagement_id=engagement_id,
+        scope=scope,
+        from_recon=from_recon,
+        target=target,
+        targets_file=targets_file,
+        limit=limit,
+        status_code=status_code,
+        yes=yes,
+        max_targets=max_targets,
+    )
+
+
+@run_app.command("subfinder")
+def run_subfinder(
+    engagement_id: str = typer.Option(
+        ..., "--engagement", "--program", "-p", help="Engagement UUID"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    max_targets: int = typer.Option(
+        run.MAX_TARGETS_DEFAULT, "--max-targets", help=_MAX_TARGETS_HELP
+    ),
+):
+    """Run subfinder against wildcard scope entries and import discovered hosts."""
+    run.run_subfinder(engagement_id=engagement_id, yes=yes, max_targets=max_targets)
+
+
+@run_app.command("nuclei")
+def run_nuclei(
+    engagement_id: str = typer.Option(
+        ..., "--engagement", "--program", "-p", help="Engagement UUID"
+    ),
+    scope: bool = typer.Option(False, "--scope", help="Use in-scope assets from VardrMap"),
+    from_recon: bool = typer.Option(
+        False, "--from-recon", help="Use live recon items from VardrMap"
+    ),
+    target: str | None = typer.Option(None, "--target", help="Single inline target"),
+    targets_file: Path | None = typer.Option(None, "--targets", help="Path to a targets .txt file"),
+    limit: int = typer.Option(100, "--limit", help="Max recon items to use (--from-recon only)"),
+    status_code: int | None = typer.Option(
+        None, "--status-code", help="Filter recon by HTTP status code"
+    ),
+    severity: str | None = typer.Option(
+        None, "--severity", help="Comma-separated severities, e.g. high,critical"
+    ),
+    templates: str | None = typer.Option(
+        None, "--templates", "-t", help="Nuclei template path or tag"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    max_targets: int = typer.Option(
+        run.MAX_TARGETS_DEFAULT, "--max-targets", help=_MAX_TARGETS_HELP
+    ),
+):
+    """Run nuclei locally and upload results to VardrMap."""
+    run.run_nuclei(
+        engagement_id=engagement_id,
+        scope=scope,
+        from_recon=from_recon,
+        target=target,
+        targets_file=targets_file,
+        limit=limit,
+        status_code=status_code,
+        severity=severity,
+        templates=templates,
+        yes=yes,
+        max_targets=max_targets,
+    )
+
+
+@run_app.command("nmap")
+def run_nmap(
+    engagement_id: str = typer.Option(
+        ..., "--engagement", "--program", "-p", help="Engagement UUID"
+    ),
+    scope: bool = typer.Option(False, "--scope", help="Use in-scope assets from VardrMap"),
+    from_recon: bool = typer.Option(
+        False, "--from-recon", help="Use live recon items from VardrMap"
+    ),
+    target: str | None = typer.Option(None, "--target", help="Single inline target"),
+    targets_file: Path | None = typer.Option(None, "--targets", help="Path to a targets .txt file"),
+    limit: int = typer.Option(500, "--limit", help="Max recon items to use (--from-recon only)"),
+    top_ports: int = typer.Option(100, "--top-ports", help="Number of most-common ports to scan"),
+    timing: int = typer.Option(
+        3, "--timing", help="nmap timing template (0-4; 5 is never allowed)"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    max_targets: int = typer.Option(
+        run.MAX_TARGETS_DEFAULT, "--max-targets", help=_MAX_TARGETS_HELP
+    ),
+):
+    """Run nmap service discovery locally and upload open ports to VardrMap."""
+    run.run_nmap(
+        engagement_id=engagement_id,
+        scope=scope,
+        from_recon=from_recon,
+        target=target,
+        targets_file=targets_file,
+        limit=limit,
+        top_ports=top_ports,
+        timing=timing,
+        yes=yes,
+        max_targets=max_targets,
+    )
+
+
+@run_app.command("dnsx")
+def run_dnsx(
+    engagement_id: str = typer.Option(
+        ..., "--engagement", "--program", "-p", help="Engagement UUID"
+    ),
+    scope: bool = typer.Option(False, "--scope", help="Use in-scope assets from VardrMap"),
+    from_recon: bool = typer.Option(
+        False, "--from-recon", help="Use live recon items from VardrMap"
+    ),
+    target: str | None = typer.Option(None, "--target", help="Single inline target"),
+    targets_file: Path | None = typer.Option(None, "--targets", help="Path to a targets .txt file"),
+    limit: int = typer.Option(500, "--limit", help="Max recon items to use (--from-recon only)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    max_targets: int = typer.Option(
+        run.MAX_TARGETS_DEFAULT, "--max-targets", help=_MAX_TARGETS_HELP
+    ),
+):
+    """Resolve hosts with dnsx and upload the resolvable ones as recon targets."""
+    run.run_dnsx(
+        engagement_id=engagement_id,
+        scope=scope,
+        from_recon=from_recon,
+        target=target,
+        targets_file=targets_file,
+        limit=limit,
+        yes=yes,
+        max_targets=max_targets,
+    )
+
+
+@run_app.command("naabu")
+def run_naabu(
+    engagement_id: str = typer.Option(
+        ..., "--engagement", "--program", "-p", help="Engagement UUID"
+    ),
+    scope: bool = typer.Option(False, "--scope", help="Use in-scope assets from VardrMap"),
+    from_recon: bool = typer.Option(
+        False, "--from-recon", help="Use live recon items from VardrMap"
+    ),
+    target: str | None = typer.Option(None, "--target", help="Single inline target"),
+    targets_file: Path | None = typer.Option(None, "--targets", help="Path to a targets .txt file"),
+    limit: int = typer.Option(500, "--limit", help="Max recon items to use (--from-recon only)"),
+    top_ports: int = typer.Option(100, "--top-ports", help="Number of most-common ports to scan"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    max_targets: int = typer.Option(
+        run.MAX_TARGETS_DEFAULT, "--max-targets", help=_MAX_TARGETS_HELP
+    ),
+):
+    """Port-scan hosts with naabu locally and upload open ports to VardrMap."""
+    run.run_naabu(
+        engagement_id=engagement_id,
+        scope=scope,
+        from_recon=from_recon,
+        target=target,
+        targets_file=targets_file,
+        limit=limit,
+        top_ports=top_ports,
+        yes=yes,
+        max_targets=max_targets,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Pipeline
+# --------------------------------------------------------------------------- #
+
+pipeline_app = typer.Typer(help="Run a chain of tools as one recon pipeline.", no_args_is_help=True)
+app.add_typer(pipeline_app, name="pipeline")
+
+
+@pipeline_app.command("list")
+def pipeline_list():
+    """List the available pipelines and their tool chains."""
+    pipeline_cmd.list_pipelines()
+
+
+@pipeline_app.command("run")
+def pipeline_run(
+    name: str = typer.Argument(..., help="Pipeline name (see `pipeline list`)"),
+    engagement_id: str = typer.Option(
+        ..., "--engagement", "--program", "-p", help="Engagement UUID"
+    ),
+    severity: str | None = typer.Option(
+        None, "--severity", help="nuclei severity filter for the scan stage"
+    ),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+    continue_on_error: bool = typer.Option(
+        False, "--continue-on-error", help="Keep going if a stage fails"
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="Resolve first-stage targets and print the plan without executing"
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Emit a machine-readable JSON result"),
+    max_targets: int = typer.Option(
+        run.MAX_TARGETS_DEFAULT, "--max-targets", help=_MAX_TARGETS_HELP
+    ),
+):
+    """Run every stage of a pipeline in order against an engagement."""
+    pipeline_cmd.run_pipeline(
+        name,
+        engagement_id,
+        severity=severity,
+        yes=yes,
+        continue_on_error=continue_on_error,
+        dry_run=dry_run,
+        as_json=as_json,
+        max_targets=max_targets,
+    )