hardn-cli 0.1.0__py3-none-any.whl

hardn_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Hardn CLI — drive read-only scans of sites you own from the terminal or CI, via the /v1 API."""
+
+__version__ = "0.1.0"

hardn_cli/__main__.py

@@ -0,0 +1,4 @@
+from .main import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hardn_cli/client.py

@@ -0,0 +1,66 @@
+"""A tiny stdlib-only HTTP client for the Hardn /v1 API, so the CLI needs no third-party packages in CI."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+DEFAULT_API_URL = "https://api.hardn.si"
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.status = status
+        self.code = code
+        self.message = message
+
+
+class Client:
+    def __init__(self, api_key: str, api_url: str = DEFAULT_API_URL, *, timeout: float = 30.0) -> None:
+        self._key = api_key
+        self._base = api_url.rstrip("/")
+        self._timeout = timeout
+
+    def _request(self, method: str, path: str, body: dict | None = None) -> Any:
+        url = f"{self._base}{path}"
+        data = json.dumps(body).encode() if body is not None else None
+        req = urllib.request.Request(url, data=data, method=method)
+        req.add_header("Authorization", f"Bearer {self._key}")
+        req.add_header("Accept", "application/json")
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read()
+                return json.loads(raw) if raw else None
+        except urllib.error.HTTPError as exc:
+            raw = exc.read()
+            detail = {}
+            try:
+                detail = (json.loads(raw) or {}).get("detail", {})
+            except ValueError:
+                pass
+            if isinstance(detail, dict):
+                raise ApiError(exc.code, detail.get("code", "error"),
+                               detail.get("message", exc.reason or "Request failed.")) from exc
+            raise ApiError(exc.code, "error", str(detail) or (exc.reason or "Request failed.")) from exc
+        except urllib.error.URLError as exc:
+            raise ApiError(0, "network", f"Could not reach {self._base}: {exc.reason}") from exc
+
+    def start_scan(self, target_id: str, scan_type: str) -> dict:
+        return self._request("POST", "/v1/scans", {"target_id": target_id, "scan_type": scan_type})
+
+    def get_scan(self, scan_id: str) -> dict:
+        return self._request("GET", f"/v1/scans/{scan_id}")
+
+    def report(self, scan_id: str, fmt: str = "json") -> Any:
+        return self._request("GET", f"/v1/scans/{scan_id}/report?format={fmt}")
+
+    def verify(self, target_id: str) -> dict:
+        return self._request("POST", f"/v1/targets/{target_id}/verify")
+
+    def list_targets(self) -> list:
+        return self._request("GET", "/v1/targets")

hardn_cli/main.py

@@ -0,0 +1,185 @@
+"""`hardn` — start a read-only scan of a site you own, wait for it, write the report, and (for CI) fail the
+build when confirmed issues reach a severity threshold.
+
+Auth: set HARDN_API_KEY (an hk_live_… key from Settings → API keys). HARDN_API_URL overrides the endpoint.
+Everything the CLI triggers is the same read-only scan the dashboard runs; it never changes the target.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from typing import Any
+
+from . import __version__
+from .client import ApiError, Client, DEFAULT_API_URL
+
+SEVERITIES = ["critical", "high", "medium", "low", "info"]
+_RANK = {s: i for i, s in enumerate(SEVERITIES)}  # 0 = most severe
+TERMINAL = {"completed", "failed", "stopped"}
+
+
+def _err(msg: str) -> int:
+    print(f"hardn: {msg}", file=sys.stderr)
+    return 2
+
+
+def _client(args: argparse.Namespace) -> Client:
+    key = args.api_key or os.environ.get("HARDN_API_KEY", "")
+    if not key:
+        raise SystemExit(_err("no API key. Set HARDN_API_KEY or pass --api-key."))
+    return Client(key, args.api_url or os.environ.get("HARDN_API_URL", DEFAULT_API_URL))
+
+
+def _counts(findings: list[dict]) -> dict[str, int]:
+    out = {s: 0 for s in SEVERITIES}
+    for f in findings:
+        if f.get("validation_status") == "rejected":
+            continue
+        out[f.get("severity", "info")] = out.get(f.get("severity", "info"), 0) + 1
+    return out
+
+
+def _poll(client: Client, scan_id: str, timeout: float, quiet: bool) -> dict:
+    deadline = time.monotonic() + timeout
+    last = None
+    while time.monotonic() < deadline:
+        scan = client.get_scan(scan_id)
+        status = scan.get("status")
+        if status != last and not quiet:
+            print(f"  … {status} ({scan.get('progress', 0)}%)", file=sys.stderr)
+            last = status
+        if status in TERMINAL:
+            return scan
+        time.sleep(3.0)
+    raise SystemExit(_err(f"scan {scan_id} did not finish within {int(timeout)}s."))
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    client = _client(args)
+    try:
+        scan = client.start_scan(args.target, args.type)
+    except ApiError as exc:
+        return _err(exc.message)
+    scan_id = scan["id"]
+    if not args.quiet:
+        print(f"Started {args.type} scan {scan_id} for target {args.target}.", file=sys.stderr)
+    scan = _poll(client, scan_id, args.timeout, args.quiet)
+
+    try:
+        report = client.report(scan_id, "json")
+    except ApiError as exc:
+        return _err(f"scan finished but the report could not be fetched: {exc.message}")
+    findings = report.get("findings", [])
+    counts = _counts(findings)
+
+    if args.sarif:
+        try:
+            sarif = client.report(scan_id, "sarif")
+            with open(args.sarif, "w", encoding="utf-8") as fh:
+                json.dump(sarif, fh)
+            if not args.quiet:
+                print(f"Wrote SARIF to {args.sarif}.", file=sys.stderr)
+        except (ApiError, OSError) as exc:
+            print(f"hardn: could not write SARIF: {exc}", file=sys.stderr)
+
+    if args.format == "json":
+        json.dump({"scan": scan, "counts": counts, "findings": findings}, sys.stdout, indent=2)
+        print()
+    else:
+        _print_summary(scan, counts, findings)
+
+    if scan.get("status") != "completed":
+        return _err(f"scan did not complete (status: {scan.get('status')}).")
+
+    threshold = args.fail_on.lower()
+    if threshold == "none":
+        return 0
+    if threshold not in _RANK:
+        return _err(f"--fail-on must be one of none, {', '.join(SEVERITIES)}.")
+    gating = sum(n for sev, n in counts.items() if _RANK[sev] <= _RANK[threshold])
+    if gating:
+        if not args.quiet:
+            print(f"\nFAIL: {gating} issue(s) at or above '{threshold}'.", file=sys.stderr)
+        return 1
+    if not args.quiet:
+        print(f"\nPASS: no issues at or above '{threshold}'.", file=sys.stderr)
+    return 0
+
+
+def _print_summary(scan: dict, counts: dict[str, int], findings: list[dict]) -> None:
+    grade = scan.get("grade") or "–"
+    score = scan.get("score")
+    print(f"Grade {grade} ({score if score is not None else '–'}/100) · " +
+          " ".join(f"{counts[s]} {s}" for s in SEVERITIES if counts[s]))
+    for f in sorted(findings, key=lambda x: _RANK.get(x.get("severity", "info"), 9)):
+        if f.get("validation_status") == "rejected":
+            continue
+        owasp = f" [{f['owasp']}]" if f.get("owasp") else ""
+        where = f.get("location") or f.get("affected_asset") or ""
+        print(f"  {f.get('severity', '').upper():8} {f.get('title', '')}{owasp}  {where}")
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    client = _client(args)
+    try:
+        result = client.verify(args.target)
+    except ApiError as exc:
+        return _err(exc.message)
+    print(json.dumps(result) if args.format == "json" else
+          f"{'verified' if result.get('verified') else 'not verified'}: {result.get('detail', '')}")
+    return 0 if result.get("verified") else 1
+
+
+def cmd_targets(args: argparse.Namespace) -> int:
+    client = _client(args)
+    try:
+        targets = client.list_targets()
+    except ApiError as exc:
+        return _err(exc.message)
+    if args.format == "json":
+        json.dump(targets, sys.stdout, indent=2)
+        print()
+    else:
+        for t in targets:
+            print(f"{t['id']}  {t.get('status', ''):10} {t.get('host', '')}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="hardn", description="Scan sites you own with Hardn (read-only).")
+    p.add_argument("--version", action="version", version=f"hardn {__version__}")
+    p.add_argument("--api-key", help="API key (or set HARDN_API_KEY).")
+    p.add_argument("--api-url", help=f"API base URL (default {DEFAULT_API_URL}, or HARDN_API_URL).")
+    p.add_argument("--format", choices=["text", "json"], default="text")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("scan", help="Start a scan, wait for it, and gate on severity.")
+    s.add_argument("--target", required=True, help="A verified target id (tgt_…).")
+    s.add_argument("--type", choices=["public", "deep"], default="public")
+    s.add_argument("--fail-on", default="high",
+                   help="Exit non-zero if any confirmed issue is at or above this severity (or 'none').")
+    s.add_argument("--sarif", help="Write the SARIF report to this file.")
+    s.add_argument("--timeout", type=float, default=900.0, help="Seconds to wait for the scan (default 900).")
+    s.add_argument("--quiet", action="store_true", help="Only print the summary/report.")
+    s.set_defaults(func=cmd_scan)
+
+    v = sub.add_parser("verify", help="Re-run ownership verification for a target.")
+    v.add_argument("--target", required=True)
+    v.set_defaults(func=cmd_verify)
+
+    t = sub.add_parser("targets", help="List the organisation's targets.")
+    t.set_defaults(func=cmd_targets)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hardn_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: hardn-cli
+Version: 0.1.0
+Summary: Command-line client for Hardn (hardn.si): run read-only security scans of sites you own from the terminal or CI.
+Project-URL: Homepage, https://hardn.si
+Project-URL: Documentation, https://hardn.si/developers#cli
+Author: Infonex Pty Ltd
+License: Proprietary
+Keywords: ci,devsecops,hardn,scanner,security
+Classifier: Environment :: Console
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# hardn-cli
+
+Run Hardn's read-only security scans of sites you own from your terminal or CI, and fail the build when a scan
+finds problems at or above the severity you choose. Python 3.9+, no dependencies.
+
+## Install
+
+```bash
+pip install hardn-cli        # or: pipx install hardn-cli
+hardn --version
+```
+
+## Use
+
+Create an API key in Hardn (API keys → New key) and keep it as a secret.
+
+```bash
+export HARDN_API_KEY=hk_live_…
+hardn targets                                   # your sites and their ids (tgt_…)
+hardn scan --target tgt_… --fail-on high        # start a scan, wait, exit 1 on high or critical issues
+hardn scan --target tgt_… --sarif hardn.sarif   # also write a SARIF report (GitHub code scanning)
+hardn verify --target tgt_…                     # re-check ownership verification
+```
+
+Options: `--fail-on none|critical|high|medium|low|info` (default `high`), `--type public|deep`,
+`--timeout <seconds>` (default 900), `--format text|json`, `--quiet`, `--api-url` (or `HARDN_API_URL`; default
+`https://api.hardn.si`).
+
+Exit codes: `0` passed, `1` issues at or above `--fail-on` (for `verify`: not verified), `2` the scan didn't
+complete or timed out, or a usage or API error.
+
+## In GitHub Actions
+
+```yaml
+- name: Hardn scan
+  env:
+    HARDN_API_KEY: ${{ secrets.HARDN_API_KEY }}
+  run: |
+    pip install hardn-cli
+    hardn scan --target tgt_… --fail-on high --sarif hardn.sarif
+```
+
+Hardn only scans sites whose ownership you have verified. Docs: https://hardn.si/developers

hardn_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+hardn_cli/__init__.py,sha256=jaDNSMqSx8-HNHZzVHwSXwvEHc58ds0kOfnJLBURXeo,124
+hardn_cli/__main__.py,sha256=fdA1QWBe5LNX0fbtaJXa1-dwEhrg_4sS_5UnjaajcMo,80
+hardn_cli/client.py,sha256=3pyN-ufJZkTZNVdU8i48orgufg9p_hlfpPbFNMB5124,2674
+hardn_cli/main.py,sha256=xOwswJ_JVDAVjtsye4Kr387L0xCClgf9BYuWiPbzTi8,7152
+hardn_cli-0.1.0.dist-info/METADATA,sha256=sfjjNQ-03u5IT3h1pmg9LCB2Ie7KiPrXwNzp8RlS678,2145
+hardn_cli-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+hardn_cli-0.1.0.dist-info/entry_points.txt,sha256=DDj65hueR4z44wyFeDnxTwms2s9FhHW8Nwi06ADbrwA,46
+hardn_cli-0.1.0.dist-info/RECORD,,

hardn_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

hardn_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hardn = hardn_cli.main:main