openhack-cli 0.1.0__py3-none-any.whl

openhack_cli/config.py

@@ -0,0 +1,137 @@
+"""Persistent CLI configuration: app URL, auth token, and active org/project context.
+
+Stored as JSON at ``$XDG_CONFIG_HOME/openhack/config.json`` (falling back to
+``~/.config/openhack/config.json``). The file is written with ``0600`` perms
+since it holds a long-lived API token.
+
+Every value can be overridden at runtime by an environment variable so the CLI
+stays scriptable for agents and CI:
+
+    OPENHACK_APP_URL   -> app_url
+    OPENHACK_TOKEN     -> token
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+DEFAULT_APP_URL = "https://app.openhack.com"
+LOCAL_APP_URL = "http://localhost:9080"
+
+# Environment overrides take precedence over the on-disk config.
+ENV_APP_URL = "OPENHACK_APP_URL"
+ENV_TOKEN = "OPENHACK_TOKEN"
+# Export OPENHACK_DEV=1 to target the local dev server without passing --local.
+ENV_DEV = "OPENHACK_DEV"
+
+_TRUTHY = {"1", "true", "yes", "on"}
+
+
+def _truthy(value: Optional[str]) -> bool:
+    return bool(value) and value.strip().lower() in _TRUTHY
+
+
+def config_dir() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or os.path.join(
+        os.path.expanduser("~"), ".config"
+    )
+    return Path(base) / "openhack"
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+class Config:
+    """Thin wrapper over the JSON config file with env-var overrides."""
+
+    def __init__(self, data: Optional[dict[str, Any]] = None):
+        self._data: dict[str, Any] = data or {}
+        # Set by CLI flags (--app-url/--local); wins over env and saved config.
+        self._override_app_url: Optional[str] = None
+
+    # ----- loading / saving -------------------------------------------------
+    @classmethod
+    def load(cls) -> "Config":
+        path = config_path()
+        if path.exists():
+            try:
+                data = json.loads(path.read_text())
+            except (json.JSONDecodeError, OSError):
+                data = {}
+        else:
+            data = {}
+        return cls(data)
+
+    def save(self) -> None:
+        path = config_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        # Write atomically-ish, then lock down perms (token lives here).
+        tmp = path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(self._data, indent=2) + "\n")
+        os.chmod(tmp, 0o600)
+        tmp.replace(path)
+        os.chmod(path, 0o600)
+
+    # ----- resolved accessors (env wins) -----------------------------------
+    def set_override_app_url(self, url: str) -> None:
+        """Force the app URL for this invocation (from a CLI flag)."""
+        self._override_app_url = url.rstrip("/")
+
+    @property
+    def app_url(self) -> str:
+        # Precedence (highest first):
+        #   1. CLI flag (--app-url / --local)
+        #   2. OPENHACK_APP_URL env
+        #   3. OPENHACK_DEV=1 -> local dev server
+        #   4. saved config (last login / `config set`)
+        #   5. built-in production default
+        if self._override_app_url:
+            return self._override_app_url
+        explicit = os.environ.get(ENV_APP_URL)
+        if explicit:
+            return explicit.rstrip("/")
+        if _truthy(os.environ.get(ENV_DEV)):
+            return LOCAL_APP_URL
+        return (self._data.get("app_url") or DEFAULT_APP_URL).rstrip("/")
+
+    @property
+    def token(self) -> Optional[str]:
+        return os.environ.get(ENV_TOKEN) or self._data.get("token")
+
+    @property
+    def user(self) -> Optional[dict[str, Any]]:
+        return self._data.get("user")
+
+    @property
+    def org(self) -> Optional[dict[str, Any]]:
+        return self._data.get("org")
+
+    @property
+    def project(self) -> Optional[dict[str, Any]]:
+        return self._data.get("project")
+
+    # ----- mutators ---------------------------------------------------------
+    def set(self, key: str, value: Any) -> None:
+        if value is None:
+            self._data.pop(key, None)
+        else:
+            self._data[key] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, default)
+
+    def as_dict(self) -> dict[str, Any]:
+        return dict(self._data)
+
+    def clear_auth(self) -> None:
+        """Remove credentials and bound context (logout)."""
+        for key in ("token", "user", "org", "project"):
+            self._data.pop(key, None)
+
+    @property
+    def is_authenticated(self) -> bool:
+        return bool(self.token)

openhack_cli/context.py

@@ -0,0 +1,76 @@
+"""Helpers that bridge Click context, config, and the API client."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import click
+
+from .client import Client
+from .config import Config
+
+
+def get_config(ctx: click.Context) -> Config:
+    return ctx.obj["config"]
+
+
+def get_client(ctx: click.Context, require_auth: bool = True) -> Client:
+    """Return a configured API client, optionally requiring a stored token."""
+    cfg: Config = ctx.obj["config"]
+    if require_auth and not cfg.token:
+        raise click.ClickException(
+            "Not logged in. Run `openhack-cli auth login` first."
+        )
+    if "client" not in ctx.obj:
+        ctx.obj["client"] = Client(cfg.app_url, token=cfg.token)
+    return ctx.obj["client"]
+
+
+def is_json(ctx: click.Context) -> bool:
+    return bool(ctx.obj.get("json"))
+
+
+def resolve_org_id(ctx: click.Context, org: Optional[str]) -> str:
+    """Resolve an org id from an explicit arg or the active context.
+
+    ``org`` may be an org id (passed through as-is). When omitted we fall back
+    to the org bound to the active context (set via `orgs use`, or the org the
+    login token is bound to).
+    """
+    cfg: Config = ctx.obj["config"]
+    if org:
+        return org
+    active = cfg.org
+    if active and active.get("id"):
+        return active["id"]
+    raise click.ClickException(
+        "No organization selected. Pass --org <id> or run `openhack-cli orgs use <id|slug>`."
+    )
+
+
+def resolve_project_id(ctx: click.Context, project: Optional[str]) -> str:
+    """Resolve a project id from an explicit arg or the active context."""
+    cfg: Config = ctx.obj["config"]
+    if project:
+        return project
+    active = cfg.project
+    if active and active.get("id"):
+        return active["id"]
+    raise click.ClickException(
+        "No project selected. Pass a project id or run `openhack-cli projects use <id|slug>`."
+    )
+
+
+def match_resource(items: list[dict], needle: str,
+                   keys: tuple[str, ...] = ("id", "slug", "name")) -> Optional[dict]:
+    """Find a resource by id/slug/name (case-insensitive for slug/name)."""
+    for item in items:
+        if item.get("id") == needle:
+            return item
+    low = needle.lower()
+    for item in items:
+        for key in keys:
+            val = item.get(key)
+            if val and str(val).lower() == low:
+                return item
+    return None

openhack_cli/output.py

@@ -0,0 +1,104 @@
+"""Rendering helpers shared by all commands.
+
+Every command supports two modes:
+  - human: Rich tables / panels (default, when stdout is a TTY or not --json)
+  - json:  raw machine-readable JSON for agents and scripts (--json)
+
+The active mode is carried on the Click context object (``ctx.obj``).
+"""
+
+from __future__ import annotations
+
+import json as _json
+import sys
+from typing import Any, Optional, Sequence
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+err_console = Console(stderr=True)
+
+# Severity ordering + colors reused across scans / findings / pentest output.
+SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "info": 4}
+SEVERITY_COLORS = {
+    "critical": "bright_red",
+    "high": "red",
+    "medium": "yellow",
+    "low": "cyan",
+    "info": "blue",
+}
+STATUS_COLORS = {
+    "completed": "green",
+    "approved": "green",
+    "in_progress": "yellow",
+    "pending": "yellow",
+    "draft": "dim",
+    "failed": "red",
+    "cancelled": "red",
+}
+
+
+def severity_label(sev: Optional[str]) -> str:
+    if not sev:
+        return "[dim]-[/dim]"
+    color = SEVERITY_COLORS.get(sev.lower(), "white")
+    return f"[{color}]{sev.upper()}[/{color}]"
+
+
+def status_label(status: Optional[str]) -> str:
+    if not status:
+        return "[dim]-[/dim]"
+    color = STATUS_COLORS.get(status.lower(), "white")
+    return f"[{color}]{status}[/{color}]"
+
+
+def print_json(data: Any) -> None:
+    """Emit raw JSON to stdout (machine mode)."""
+    click.echo(_json.dumps(data, indent=2, default=str))
+
+
+def emit(ctx_obj: dict, data: Any, render) -> None:
+    """Print JSON when --json is set, otherwise call ``render(data)``."""
+    if ctx_obj.get("json"):
+        print_json(data)
+    else:
+        render(data)
+
+
+def make_table(title: Optional[str], columns: Sequence[str]) -> Table:
+    table = Table(title=title, title_justify="left", header_style="bold",
+                  expand=False, pad_edge=False)
+    for col in columns:
+        table.add_column(col, overflow="fold")
+    return table
+
+
+def info(message: str) -> None:
+    err_console.print(message)
+
+
+def success(message: str) -> None:
+    err_console.print(f"[green]✓[/green] {message}")
+
+
+def warn(message: str) -> None:
+    err_console.print(f"[yellow]![/yellow] {message}")
+
+
+def error(message: str) -> None:
+    err_console.print(f"[red]✗[/red] {message}")
+
+
+def fail(message: str, code: int = 1) -> "click.ClickException":
+    """Print an error and exit with a non-zero code."""
+    error(message)
+    sys.exit(code)
+
+
+def short(value: Optional[str], length: int = 36) -> str:
+    if not value:
+        return "-"
+    value = str(value)
+    return value if len(value) <= length else value[: length - 1] + "…"

openhack_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: openhack-cli
+Version: 0.1.0
+Summary: Command-line interface for the OpenHack security platform.
+Author: OpenHack
+License: MIT
+Project-URL: Homepage, https://openhack.com
+Project-URL: Repository, https://github.com/openhackai/cli
+Project-URL: Issues, https://github.com/openhackai/cli/issues
+Keywords: openhack,security,pentest,cli,sast,vulnerability
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+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 :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: rich>=13.7
+Dynamic: license-file
+
+# OpenHack CLI
+
+`openhack-cli` is the command-line interface for the [OpenHack](https://openhack.com)
+security platform. It does one thing: talk to the OpenHack app in an
+authenticated way, so that **humans and agents** can drive the platform from a
+terminal or a script. No scanning happens in the CLI itself — it's a thin,
+authenticated client over the OpenHack API.
+
+## Install
+
+```bash
+pipx install openhack-cli        # recommended (isolated)
+# or
+pip install openhack-cli
+```
+
+From source:
+
+```bash
+git clone <this repo> && cd openhack-cli
+pip install -e .
+```
+
+Requires Python 3.9+.
+
+> **Driving the CLI from an automated agent?** See [`AGENT.md`](./AGENT.md) — an
+> exhaustive, copy-pasteable command + field reference covering every command
+> group, with allowed enum values and `--json` output for automation.
+
+## Quick start
+
+```bash
+openhack-cli auth login          # device-code login in your browser
+openhack-cli orgs list           # list your organizations
+openhack-cli orgs use acme       # pick the active org
+openhack-cli projects list       # list projects
+openhack-cli projects use web    # pick the active project
+openhack-cli scans list          # scans for the active project
+openhack-cli vulns list          # vulnerabilities across recent scans
+```
+
+## Authentication
+
+Login uses the same **device-code flow** as the OpenHack web app:
+
+1. `auth login` calls `POST /api/cli/auth` and prints a short code + URL.
+2. Your browser opens; you sign in, choose an organization, and approve.
+3. The CLI polls `POST /api/cli/auth/poll` until approval, then stores the
+   issued token.
+
+The token is a long-lived, **org-scoped** API key sent as
+`Authorization: Bearer openhack_…` on every request. It is stored at
+`$XDG_CONFIG_HOME/openhack/config.json` (default `~/.config/openhack/config.json`)
+with `0600` permissions.
+
+```bash
+openhack-cli auth status         # who am I / active context
+openhack-cli auth token          # print the raw token (scripting)
+openhack-cli auth logout         # remove local credentials
+```
+
+## Commands
+
+| Group | Command | Description |
+|-------|---------|-------------|
+| `auth` | `login`, `logout`, `status`/`whoami`, `token` | Manage credentials |
+| `orgs` | `list`, `use <id\|slug>` | List / select organizations |
+| `projects` | `list`, `get`, `use`, `create` | Manage projects |
+| `scans` | `list`, `get <scan_id>`, `trigger-full` | View / trigger scans |
+| `vulns` | `list`, `groups`, `report`, `get`, `edit` | View, report, and edit project vulnerabilities |
+| `pentest` | `list`, `get`, `create` | Pentesting engagements |
+| `pentest findings` | `[engagement]` | Findings in an engagement (defaults to latest) |
+| `pentest finding` | `get`, `create`, `update`, `delete`, `link`, `unlink` | Single finding: view / create / patch / delete / cross-reference |
+| `config` | `show`, `set`, `path` | CLI configuration |
+
+For an exhaustive, example-driven command reference (aimed at automation and
+agents), see [`AGENT.md`](./AGENT.md).
+
+## Scripting & agents
+
+Pass `--json` (global flag) to get machine-readable output from any command:
+
+```bash
+openhack-cli --json scans list
+openhack-cli --json vulns list --severity critical
+```
+
+Configuration can be driven entirely by environment variables (handy in CI):
+
+| Variable | Purpose |
+|----------|---------|
+| `OPENHACK_TOKEN` | API token (overrides stored credentials) |
+| `OPENHACK_APP_URL` | App base URL (default `https://app.openhack.com`) |
+| `OPENHACK_DEV` | Set to `1` to target the local dev server (`http://localhost:9080`) |
+| `XDG_CONFIG_HOME` | Where the config file lives |
+
+### Targeting an environment
+
+Production (`https://app.openhack.com`) is the default. For local dev work
+(`http://localhost:9080`), the easiest option is to export `OPENHACK_DEV` once —
+then every command targets localhost with no flags:
+
+```bash
+export OPENHACK_DEV=1        # add to your ~/.zshrc for permanent dev mode
+openhack-cli auth login      # now logs in against localhost:9080
+openhack-cli scans list
+```
+
+Or use the `--local` flag per-command (shorthand for `--app-url
+http://localhost:9080`):
+
+```bash
+openhack-cli --local auth login
+```
+
+The app URL is resolved with this precedence (highest first):
+
+1. `--app-url` / `--local` flag
+2. `OPENHACK_APP_URL` env var
+3. `OPENHACK_DEV=1` → `http://localhost:9080`
+4. saved config (last login, or `openhack-cli config set app_url <url>`)
+5. built-in default `https://app.openhack.com`
+
+Exit codes: `0` success, `1` API/usage error, `2` auth error, `130` interrupted.
+
+## Configuration
+
+```bash
+openhack-cli config show
+openhack-cli config set app_url https://your-openhack-host
+openhack-cli config path
+```

openhack_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+openhack_cli/__init__.py,sha256=6nfu9_udx4lsS141GD_R5QAtLAYXHcFhoWDWw63odBQ,107
+openhack_cli/cli.py,sha256=BDl-T3qbilOtPAxUT-8ohnA64EVewPqTs5FzZNRRpDU,2901
+openhack_cli/client.py,sha256=sJB_2IyI1Pym7c4vbC3Ka3wCa6PuEKFeZDeS9pLbG8Y,3980
+openhack_cli/config.py,sha256=nXHcsAlCFcE_WG9mDkop26Gxt9bnGvCqeUZXebEXRy0,4421
+openhack_cli/context.py,sha256=JcGn3riPW3I1Y9wNllihxNOJLLj0A5iYsxfjSSyaSk0,2396
+openhack_cli/output.py,sha256=99Rt9e9kE_2nW33Qob_Cy237NeorDJ0XJwEuDoR99M8,2745
+openhack_cli/commands/__init__.py,sha256=9NftJ5ZmxEB-ahGxqevwt2mWSvoIhYqWN1qNiafgl2Q,43
+openhack_cli/commands/auth.py,sha256=4XUOOLZexNjJkWwCbz-DoYGCbtU7nJRH9iP0Dw4Nu9k,6115
+openhack_cli/commands/config_cmd.py,sha256=EZLtRJXYLQkW-foGDgeBLTDQU-sYj7gfcZQ9b-WnzbM,1577
+openhack_cli/commands/orgs.py,sha256=Jt2EJA8dXdPNnZBdVwNpGRhenV-bn_RPiZAMU4k-hqE,2158
+openhack_cli/commands/pentest.py,sha256=5WeNRDvYzqWtgkb8B9o_cBEC0-IhbCfixGeiJ9F1-dM,24970
+openhack_cli/commands/projects.py,sha256=1N-EBtqA9dwzlwurkuC-FvuquSkLwyqpVGe8inPoPkk,4504
+openhack_cli/commands/scans.py,sha256=ExnYWOHzuIfGuBtSMtzNET1nCOWC-D7IZ0630Xibpe4,5993
+openhack_cli/commands/vulns.py,sha256=-6sx0Y8i5o_JBwrQatESua25T5UACY5Yf10bRtsg53o,13934
+openhack_cli-0.1.0.dist-info/licenses/LICENSE,sha256=0tVdhGTtdQjkkFnwg6Lpg6OBdMhd8wA-9Ml_lZrIAt0,1065
+openhack_cli-0.1.0.dist-info/METADATA,sha256=zHhMd_Vs5zYp-R6_m7JxWd3rhI0SVADaTkoAVcsblx8,5905
+openhack_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+openhack_cli-0.1.0.dist-info/entry_points.txt,sha256=Whtj5Zn_-rVj3hbrBRDWvqGEM0I2d9-xX2Zg29FTdpA,55
+openhack_cli-0.1.0.dist-info/top_level.txt,sha256=vV5GLcxelf8nE1-fcKcAawtKzfILLvrfmfr-bSt6Gc8,13
+openhack_cli-0.1.0.dist-info/RECORD,,

openhack_cli-0.1.0.dist-info/WHEEL

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

openhack_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+openhack-cli = openhack_cli.cli:main

openhack_cli-0.1.0.dist-info/licenses/LICENSE

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

openhack_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+openhack_cli