openhack-cli 0.1.0__tar.gz

openhack_cli-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,132 @@
+# 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/openhack_cli/__init__.py

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

openhack_cli-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-0.1.0/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-0.1.0/openhack_cli/commands/__init__.py

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