openhack-cli 0.1.0__py3-none-any.whl

openhack_cli/__init__.py

@@ -0,0 +1,3 @@
+"""OpenHack CLI — programmatic, authenticated access to the OpenHack platform."""
+
+__version__ = "0.1.0"

openhack_cli/cli.py

@@ -0,0 +1,88 @@
+"""OpenHack CLI entrypoint.
+
+Wires the command groups together, sets up the shared Click context (config +
+output mode), and provides uniform error handling for API/auth failures.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from . import __version__, output
+from .client import APIError, AuthError
+from .commands.auth import auth
+from .commands.config_cmd import config
+from .commands.orgs import orgs
+from .commands.pentest import pentest
+from .commands.projects import projects
+from .commands.scans import scans
+from .commands.vulns import vulns
+from .config import Config, LOCAL_APP_URL
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(context_settings=CONTEXT_SETTINGS)
+@click.version_option(__version__, "-v", "--version", prog_name="openhack-cli")
+@click.option("--json", "json_output", is_flag=True,
+              help="Output raw JSON (for scripts and agents).")
+@click.option("--app-url", default=None, help="Override the OpenHack app URL.")
+@click.option("--local", "use_local", is_flag=True,
+              help=f"Target the local dev server ({LOCAL_APP_URL}).")
+@click.option("--token", default=None,
+              help="Override the API token (else uses stored credentials).")
+@click.pass_context
+def cli(ctx: click.Context, json_output: bool, app_url: str | None,
+        use_local: bool, token: str | None) -> None:
+    """OpenHack CLI — authenticated, programmatic access to OpenHack.
+
+    Start with `openhack-cli auth login`, then explore `orgs`, `projects`,
+    `scans`, `vulns`, and `pentest`.
+    """
+    cfg = Config.load()
+    # --local is a shorthand for the dev server; --app-url wins if both given.
+    # These are runtime overrides (beat OPENHACK_DEV / OPENHACK_APP_URL / config).
+    if use_local:
+        cfg.set_override_app_url(LOCAL_APP_URL)
+    if app_url:
+        cfg.set_override_app_url(app_url.rstrip("/"))
+    if token:
+        cfg.set("token", token)
+    ctx.obj = {"config": cfg, "json": json_output}
+
+
+cli.add_command(auth)
+cli.add_command(orgs)
+cli.add_command(projects)
+cli.add_command(scans)
+cli.add_command(vulns)
+cli.add_command(pentest)
+cli.add_command(config)
+
+
+def main() -> None:
+    try:
+        cli(standalone_mode=False)
+    except AuthError as exc:
+        output.error(f"Authentication failed ({exc.status}): {exc.message}")
+        output.info("Run `openhack-cli auth login` to (re)authorize, or check "
+                    "that this endpoint accepts CLI tokens.")
+        sys.exit(2)
+    except APIError as exc:
+        output.error(exc.message if exc.status else str(exc))
+        sys.exit(1)
+    except click.ClickException as exc:
+        exc.show()
+        sys.exit(exc.exit_code)
+    except click.Abort:
+        output.error("Aborted.")
+        sys.exit(130)
+    except KeyboardInterrupt:
+        output.error("Interrupted.")
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

openhack_cli/client.py

@@ -0,0 +1,124 @@
+"""HTTP client for the OpenHack API.
+
+Wraps ``requests`` with the CLI's Bearer-token auth and uniform error
+handling. Every authenticated endpoint expects::
+
+    Authorization: Bearer openhack_<hex>
+
+which is the token issued by the device-code login flow.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import requests
+
+from . import __version__
+
+# Endpoints that the CLI talks to are JSON unless noted (e.g. PDF reports).
+USER_AGENT = f"openhack-cli/{__version__}"
+DEFAULT_TIMEOUT = 30
+
+
+class APIError(Exception):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(self, status: int, message: str, body: Any = None):
+        self.status = status
+        self.message = message
+        self.body = body
+        super().__init__(f"[{status}] {message}")
+
+
+class AuthError(APIError):
+    """Raised on 401/403 so the CLI can prompt the user to re-login."""
+
+
+class Client:
+    def __init__(self, app_url: str, token: Optional[str] = None,
+                 timeout: int = DEFAULT_TIMEOUT):
+        self.app_url = app_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self._session = requests.Session()
+
+    # ----- low-level --------------------------------------------------------
+    def _headers(self, extra: Optional[dict] = None, auth: bool = True) -> dict:
+        headers = {"User-Agent": USER_AGENT, "Accept": "application/json"}
+        if auth and self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[dict] = None,
+        auth: bool = True,
+        raw: bool = False,
+    ) -> Any:
+        """Perform a request and return parsed JSON (or the raw Response).
+
+        ``raw=True`` returns the underlying ``requests.Response`` so callers can
+        stream binary payloads (e.g. PDF reports).
+        """
+        url = path if path.startswith("http") else f"{self.app_url}{path}"
+        try:
+            resp = self._session.request(
+                method,
+                url,
+                json=json,
+                params=params,
+                headers=self._headers(auth=auth),
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise APIError(0, f"Network error: {exc}") from exc
+
+        if resp.status_code >= 400:
+            self._raise_for_status(resp)
+
+        if raw:
+            return resp
+        if not resp.content:
+            return None
+        ctype = resp.headers.get("Content-Type", "")
+        if "application/json" in ctype:
+            return resp.json()
+        return resp.content
+
+    @staticmethod
+    def _raise_for_status(resp: requests.Response) -> None:
+        message = resp.reason or "Request failed"
+        body: Any = None
+        try:
+            body = resp.json()
+            if isinstance(body, dict):
+                message = body.get("error") or body.get("message") or message
+                if body.get("message") and body.get("error"):
+                    message = f"{body['error']}: {body['message']}"
+        except ValueError:
+            text = resp.text.strip()
+            if text:
+                message = text[:300]
+        if resp.status_code in (401, 403):
+            raise AuthError(resp.status_code, message, body)
+        raise APIError(resp.status_code, message, body)
+
+    # ----- verb helpers -----------------------------------------------------
+    def get(self, path: str, **kw) -> Any:
+        return self.request("GET", path, **kw)
+
+    def post(self, path: str, **kw) -> Any:
+        return self.request("POST", path, **kw)
+
+    def patch(self, path: str, **kw) -> Any:
+        return self.request("PATCH", path, **kw)
+
+    def delete(self, path: str, **kw) -> Any:
+        return self.request("DELETE", path, **kw)

openhack_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command groups for the OpenHack CLI."""

openhack_cli/commands/auth.py

@@ -0,0 +1,185 @@
+"""`openhack-cli auth` — device-code login, logout, and status.
+
+Implements the same device-code flow the app exposes for the CLI:
+
+  1. POST /api/cli/auth            -> { device_code, user_code, verification_url }
+  2. open verification_url in the browser; user signs in + picks an org + approves
+  3. POST /api/cli/auth/poll       -> { status: "pending" } ... until
+                                      { status: "approved", token, org, user }
+
+The returned ``token`` (``openhack_<hex>``) is a long-lived, org-scoped API key
+sent as ``Authorization: Bearer`` on every later request.
+"""
+
+from __future__ import annotations
+
+import time
+import webbrowser
+
+import click
+
+from .. import output
+from ..client import APIError, Client
+from ..config import Config
+from ..context import get_config
+
+POLL_INTERVAL = 2.0  # seconds between poll attempts
+
+
+@click.group()
+def auth() -> None:
+    """Log in to OpenHack and manage CLI credentials."""
+
+
+@auth.command()
+@click.option("--no-browser", is_flag=True,
+              help="Don't auto-open the browser; just print the URL.")
+@click.option("--app-url", default=None,
+              help="Override the OpenHack app URL for this login.")
+@click.pass_context
+def login(ctx: click.Context, no_browser: bool, app_url: str | None) -> None:
+    """Authorize this CLI against your OpenHack account."""
+    cfg: Config = get_config(ctx)
+    base_url = (app_url or cfg.app_url).rstrip("/")
+    # The auth-start + poll endpoints are public (no token needed).
+    client = Client(base_url, token=None)
+
+    if cfg.is_authenticated:
+        output.warn("Already logged in. Re-authorizing will replace the current token.")
+
+    try:
+        start = client.post("/api/cli/auth", auth=False)
+    except APIError as exc:
+        raise click.ClickException(f"Failed to start login: {exc.message}")
+
+    device_code = start["device_code"]
+    user_code = start["user_code"]
+    verification_url = start["verification_url"]
+    expires_in = int(start.get("expires_in", 900))
+
+    output.console.print()
+    output.console.print("To authorize the OpenHack CLI, visit:\n")
+    output.console.print(f"  [bold cyan]{verification_url}[/bold cyan]\n")
+    output.console.print("and confirm this code:\n")
+    output.console.print(f"  [bold]{user_code}[/bold]\n")
+
+    if not no_browser:
+        try:
+            webbrowser.open(verification_url)
+        except Exception:
+            pass
+
+    output.info("Waiting for approval in the browser… (Ctrl-C to cancel)")
+
+    deadline = time.time() + expires_in
+    result = None
+    while time.time() < deadline:
+        time.sleep(POLL_INTERVAL)
+        try:
+            poll = client.post(
+                "/api/cli/auth/poll", json={"device_code": device_code}, auth=False
+            )
+        except APIError as exc:
+            if exc.status == 410:
+                raise click.ClickException(
+                    "Login session expired. Run `openhack-cli auth login` again."
+                )
+            raise click.ClickException(f"Login failed: {exc.message}")
+        if poll.get("status") == "approved":
+            result = poll
+            break
+
+    if not result:
+        raise click.ClickException("Login timed out before approval.")
+
+    # Persist the token + bound org/user context.
+    cfg.set("app_url", base_url)
+    cfg.set("token", result["token"])
+    cfg.set("user", result.get("user"))
+    cfg.set("org", result.get("org"))
+    cfg.save()
+
+    org = result.get("org") or {}
+    user = result.get("user") or {}
+    name = _display_name(user)
+    output.console.print()
+    output.success(
+        f"Logged in as [bold]{name}[/bold]"
+        + (f" — org [bold]{org.get('name')}[/bold]" if org.get("name") else "")
+    )
+
+
+@auth.command()
+@click.pass_context
+def logout(ctx: click.Context) -> None:
+    """Remove stored credentials from this machine."""
+    cfg: Config = get_config(ctx)
+    if not cfg.is_authenticated:
+        output.warn("Not logged in.")
+        return
+    cfg.clear_auth()
+    cfg.save()
+    output.success("Logged out. Token removed from this machine.")
+    output.info("(The API key still exists server-side; revoke it in org settings.)")
+
+
+@auth.command()
+@click.pass_context
+def status(ctx: click.Context) -> None:
+    """Show the current login status and active context."""
+    cfg: Config = get_config(ctx)
+    payload = {
+        "authenticated": cfg.is_authenticated,
+        "app_url": cfg.app_url,
+        "user": cfg.user,
+        "org": cfg.org,
+        "project": cfg.project,
+    }
+
+    def render(_data):
+        if not cfg.is_authenticated:
+            output.warn("Not logged in. Run `openhack-cli auth login`.")
+            output.console.print(f"App URL: [dim]{cfg.app_url}[/dim]")
+            return
+        user = cfg.user or {}
+        output.success(f"Logged in as [bold]{_display_name(user)}[/bold]")
+        if user.get("email"):
+            output.console.print(f"  Email:   {user['email']}")
+        output.console.print(f"  App URL: {cfg.app_url}")
+        if cfg.org:
+            output.console.print(
+                f"  Org:     {cfg.org.get('name')} "
+                f"[dim]({cfg.org.get('slug') or cfg.org.get('id')})[/dim]"
+            )
+        if cfg.project:
+            output.console.print(
+                f"  Project: {cfg.project.get('name')} "
+                f"[dim]({cfg.project.get('slug') or cfg.project.get('id')})[/dim]"
+            )
+
+    output.emit(ctx.obj, payload, render)
+
+
+@auth.command(name="whoami")
+@click.pass_context
+def whoami(ctx: click.Context) -> None:
+    """Alias for `auth status`."""
+    ctx.invoke(status)
+
+
+@auth.command()
+@click.pass_context
+def token(ctx: click.Context) -> None:
+    """Print the raw API token (for scripting). Keep it secret."""
+    cfg: Config = get_config(ctx)
+    if not cfg.token:
+        raise click.ClickException("Not logged in.")
+    click.echo(cfg.token)
+
+
+def _display_name(user: dict) -> str:
+    if not user:
+        return "unknown"
+    parts = [user.get("firstName"), user.get("lastName")]
+    name = " ".join(p for p in parts if p).strip()
+    return name or user.get("email") or "unknown"

openhack_cli/commands/config_cmd.py

@@ -0,0 +1,56 @@
+"""`openhack-cli config` — inspect and set CLI configuration."""
+
+from __future__ import annotations
+
+import click
+
+from .. import output
+from ..config import config_path
+from ..context import get_config
+
+# Keys the user is allowed to set directly. `token` is managed by auth login.
+SETTABLE = {"app_url"}
+
+
+@click.group()
+def config() -> None:
+    """View and change CLI configuration."""
+
+
+@config.command(name="path")
+def show_path() -> None:
+    """Print the path to the config file."""
+    click.echo(str(config_path()))
+
+
+@config.command(name="show")
+@click.pass_context
+def show(ctx: click.Context) -> None:
+    """Show the current configuration (token redacted)."""
+    cfg = get_config(ctx)
+    data = cfg.as_dict()
+    if data.get("token"):
+        data["token"] = data["token"][:14] + "…"
+    data["app_url"] = cfg.app_url  # resolved value (env may override)
+
+    def render(d):
+        for key, value in d.items():
+            output.console.print(f"  [bold]{key}[/bold]: {value}")
+
+    output.emit(ctx.obj, data, render)
+
+
+@config.command(name="set")
+@click.argument("key")
+@click.argument("value")
+@click.pass_context
+def set_value(ctx: click.Context, key: str, value: str) -> None:
+    """Set a config value (e.g. `config set app_url https://...`)."""
+    if key not in SETTABLE:
+        raise click.ClickException(
+            f"'{key}' is not settable. Allowed: {', '.join(sorted(SETTABLE))}."
+        )
+    cfg = get_config(ctx)
+    cfg.set(key, value.rstrip("/") if key == "app_url" else value)
+    cfg.save()
+    output.success(f"Set {key} = {value}")

openhack_cli/commands/orgs.py

@@ -0,0 +1,71 @@
+"""`openhack-cli orgs` — list organizations and pick the active one."""
+
+from __future__ import annotations
+
+import click
+
+from .. import output
+from ..context import get_client, get_config, match_resource
+
+
+@click.group()
+def orgs() -> None:
+    """List and select organizations."""
+
+
+def _fetch_orgs(ctx: click.Context) -> list[dict]:
+    client = get_client(ctx)
+    data = client.get("/api/orgs")
+    return data.get("orgs", []) if isinstance(data, dict) else (data or [])
+
+
+@orgs.command(name="list")
+@click.pass_context
+def list_orgs(ctx: click.Context) -> None:
+    """List organizations you belong to."""
+    items = _fetch_orgs(ctx)
+    cfg = get_config(ctx)
+    active_id = (cfg.org or {}).get("id")
+
+    def render(rows):
+        if not rows:
+            output.warn("No organizations found.")
+            return
+        table = output.make_table("Organizations",
+                                  ["", "Name", "Slug", "Type", "Plan", "ID"])
+        for o in rows:
+            marker = "[green]●[/green]" if o.get("id") == active_id else ""
+            table.add_row(
+                marker,
+                o.get("name", "-"),
+                o.get("slug") or "-",
+                o.get("orgType") or "-",
+                o.get("subscriptionPlan") or "-",
+                output.short(o.get("id"), 38),
+            )
+        output.console.print(table)
+
+    output.emit(ctx.obj, items, render)
+
+
+@orgs.command()
+@click.argument("identifier")
+@click.pass_context
+def use(ctx: click.Context, identifier: str) -> None:
+    """Set the active organization (by id, slug, or name)."""
+    items = _fetch_orgs(ctx)
+    match = match_resource(items, identifier)
+    if not match:
+        raise click.ClickException(
+            f"No organization matching '{identifier}'. Try `openhack-cli orgs list`."
+        )
+    cfg = get_config(ctx)
+    cfg.set("org", {
+        "id": match.get("id"),
+        "slug": match.get("slug"),
+        "name": match.get("name"),
+    })
+    # Switching orgs invalidates the previously-selected project.
+    cfg.set("project", None)
+    cfg.save()
+    output.success(f"Active org set to [bold]{match.get('name')}[/bold]")