bhshell 0.1.0__tar.gz

bhshell-0.1.0/LICENSE

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

bhshell-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+graft tests
+graft docs
+global-exclude __pycache__ *.py[cod]

bhshell-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: bhshell
+Version: 0.1.0
+Summary: Interactive shell for BloodHound
+Author-email: kr0no <kr0no@ka0labs.net>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kr0no/bloodhound-shell
+Project-URL: Issues, https://github.com/kr0no/bloodhound-shell/issues
+Project-URL: Author, https://kr0no.me
+Keywords: bloodhound,bloodhound-ce,active-directory,attack-paths,cypher,pentest,red-team,security,cli,shell
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cmd2<5,>=4.3
+Requires-Dist: rich>=13.0
+Requires-Dist: requests>=2.31
+Requires-Dist: resvg-py>=0.5
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Dynamic: license-file
+
+# bhshell
+
+[![PyPI version](https://img.shields.io/pypi/v/bhshell.svg)](https://pypi.org/project/bhshell/)
+[![Python versions](https://img.shields.io/pypi/pyversions/bhshell.svg)](https://pypi.org/project/bhshell/)
+[![CI](https://github.com/kr0no/bloodhound-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/kr0no/bloodhound-shell/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kr0no/bloodhound-shell/blob/main/LICENSE)
+
+An interactive command-line shell for BloodHound. Look up Active Directory objects,
+hunt for weaknesses and find attack paths from the terminal, without opening the web UI.
+
+## Installation
+
+Requires Python 3.11+ and a BloodHound CE v9 server (tested on v9.7.1).
+
+```bash
+pipx install bhshell     # recommended
+# or
+pip install bhshell
+```
+
+## Quick Start
+
+```console
+$ bhshell --url http://127.0.0.1:8080
+
+[bh: shell] > login -u admin
+[+] Logged in as admin on 127.0.0.1:8080
+
+[bh: shell] > hunt
+  Severity   Check            Count   Example              Description
+  critical   dcsync           2       SVC_SQL@CORP.LOCAL   Non-Tier-Zero principals with replication rights
+  high       kerberoastable   2       JDOE@CORP.LOCAL      Kerberoastable users
+  ...
+[*] Details: 'hunt CHECK' (e.g. 'hunt kerberoastable'), or 'hunt --all'.
+
+[bh: shell] > user CORP\svc_sql --all -o svc_sql.csv
+
+[bh: shell] > path --owned -g
+```
+
+The same commands run non-interactively for scripting: `bhshell -c "hunt --json" > hunt.json`.
+
+## What it does
+
+| Command | Shows |
+|---|---|
+| `user`, `computer`, `group`, `lookup` | Kerberoastable / AS-REP roastable, delegation, password age, Tier Zero and owned flags, plus group nesting, inbound/outbound ACL control, sessions and local admin rights |
+| `search` | Objects matching property filters (`search -t user hasspn enabled`), with dates, ages (`90d`) and wildcards |
+| `path` | Shortest paths to a target or to Tier Zero, from everything owned, or through `--via` steps; printed as hop chains, a terminal graph, or SVG/PNG for reports |
+| `hunt` | Domain-wide checks by severity: DCSync, control of Tier Zero, AD CS (ESC*), Kerberoasting, privileged sessions, LAPS/gMSA readers, passwords in attributes, takeover primitives (Shadow Credentials, RBCD), GPO control, NTLM relay, trusts, possible honeytokens...; `hunt --owned` limits them to what your owned objects can do |
+| `cypher`, `query` | Raw Cypher, and a library of saved queries: bundled, your own `.cyp` files (`~/.bhshell/queries/` or any folder set with `config query_dirs`) and those saved on the server |
+| `owned`, `hvt` | Mark or unmark owned and Tier Zero objects |
+| `domains`, `trusts` | Per-domain counts, and the trust map with SID filtering status |
+
+To add your own query, save it as a `.cyp` file in `~/.bhshell/queries/` and run it by name:
+
+```console
+$ cat ~/.bhshell/queries/stale-admins.cyp
+// description: Enabled adminCount users who have not logged on for a year
+MATCH (u:User) WHERE u.admincount = true AND u.enabled = true
+  AND u.lastlogontimestamp < (datetime().epochseconds - 31536000) RETURN u
+
+[bh: shell] > query run stale-admins -o stale-admins.csv
+```
+
+See [Query library](https://github.com/kr0no/bloodhound-shell/blob/main/docs/USAGE.md#query-library) for the format and for
+keeping queries in other folders (a team repository, one folder per engagement).
+
+Most commands take `--json` and `-o FILE` (JSON or CSV). Login works with a password (plus MFA) or
+an API token; secrets are prompted for or read from the environment, never passed as arguments.
+
+## Documentation
+
+The full usage guide (every command, view flag, search filter, path option, hunt check and
+configuration setting) is in [docs/USAGE.md](https://github.com/kr0no/bloodhound-shell/blob/main/docs/USAGE.md).
+Inside the shell, run `help` or `help <command>`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+[github.com/kr0no/bloodhound-shell/issues](https://github.com/kr0no/bloodhound-shell/issues).
+
+```bash
+git clone https://github.com/kr0no/bloodhound-shell.git
+cd bloodhound-shell
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+python -m pytest
+```
+
+The tests mock the BloodHound API with `responses`, so no BloodHound server is needed.
+
+## License
+
+Distributed under the MIT License. See
+[LICENSE](https://github.com/kr0no/bloodhound-shell/blob/main/LICENSE) for details.
+
+BloodHound is a trademark of SpecterOps. bhshell is an independent project and is not affiliated
+with or endorsed by SpecterOps.

bhshell-0.1.0/README.md

@@ -0,0 +1,99 @@
+# bhshell
+
+[![PyPI version](https://img.shields.io/pypi/v/bhshell.svg)](https://pypi.org/project/bhshell/)
+[![Python versions](https://img.shields.io/pypi/pyversions/bhshell.svg)](https://pypi.org/project/bhshell/)
+[![CI](https://github.com/kr0no/bloodhound-shell/actions/workflows/ci.yml/badge.svg)](https://github.com/kr0no/bloodhound-shell/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kr0no/bloodhound-shell/blob/main/LICENSE)
+
+An interactive command-line shell for BloodHound. Look up Active Directory objects,
+hunt for weaknesses and find attack paths from the terminal, without opening the web UI.
+
+## Installation
+
+Requires Python 3.11+ and a BloodHound CE v9 server (tested on v9.7.1).
+
+```bash
+pipx install bhshell     # recommended
+# or
+pip install bhshell
+```
+
+## Quick Start
+
+```console
+$ bhshell --url http://127.0.0.1:8080
+
+[bh: shell] > login -u admin
+[+] Logged in as admin on 127.0.0.1:8080
+
+[bh: shell] > hunt
+  Severity   Check            Count   Example              Description
+  critical   dcsync           2       SVC_SQL@CORP.LOCAL   Non-Tier-Zero principals with replication rights
+  high       kerberoastable   2       JDOE@CORP.LOCAL      Kerberoastable users
+  ...
+[*] Details: 'hunt CHECK' (e.g. 'hunt kerberoastable'), or 'hunt --all'.
+
+[bh: shell] > user CORP\svc_sql --all -o svc_sql.csv
+
+[bh: shell] > path --owned -g
+```
+
+The same commands run non-interactively for scripting: `bhshell -c "hunt --json" > hunt.json`.
+
+## What it does
+
+| Command | Shows |
+|---|---|
+| `user`, `computer`, `group`, `lookup` | Kerberoastable / AS-REP roastable, delegation, password age, Tier Zero and owned flags, plus group nesting, inbound/outbound ACL control, sessions and local admin rights |
+| `search` | Objects matching property filters (`search -t user hasspn enabled`), with dates, ages (`90d`) and wildcards |
+| `path` | Shortest paths to a target or to Tier Zero, from everything owned, or through `--via` steps; printed as hop chains, a terminal graph, or SVG/PNG for reports |
+| `hunt` | Domain-wide checks by severity: DCSync, control of Tier Zero, AD CS (ESC*), Kerberoasting, privileged sessions, LAPS/gMSA readers, passwords in attributes, takeover primitives (Shadow Credentials, RBCD), GPO control, NTLM relay, trusts, possible honeytokens...; `hunt --owned` limits them to what your owned objects can do |
+| `cypher`, `query` | Raw Cypher, and a library of saved queries: bundled, your own `.cyp` files (`~/.bhshell/queries/` or any folder set with `config query_dirs`) and those saved on the server |
+| `owned`, `hvt` | Mark or unmark owned and Tier Zero objects |
+| `domains`, `trusts` | Per-domain counts, and the trust map with SID filtering status |
+
+To add your own query, save it as a `.cyp` file in `~/.bhshell/queries/` and run it by name:
+
+```console
+$ cat ~/.bhshell/queries/stale-admins.cyp
+// description: Enabled adminCount users who have not logged on for a year
+MATCH (u:User) WHERE u.admincount = true AND u.enabled = true
+  AND u.lastlogontimestamp < (datetime().epochseconds - 31536000) RETURN u
+
+[bh: shell] > query run stale-admins -o stale-admins.csv
+```
+
+See [Query library](https://github.com/kr0no/bloodhound-shell/blob/main/docs/USAGE.md#query-library) for the format and for
+keeping queries in other folders (a team repository, one folder per engagement).
+
+Most commands take `--json` and `-o FILE` (JSON or CSV). Login works with a password (plus MFA) or
+an API token; secrets are prompted for or read from the environment, never passed as arguments.
+
+## Documentation
+
+The full usage guide (every command, view flag, search filter, path option, hunt check and
+configuration setting) is in [docs/USAGE.md](https://github.com/kr0no/bloodhound-shell/blob/main/docs/USAGE.md).
+Inside the shell, run `help` or `help <command>`.
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+[github.com/kr0no/bloodhound-shell/issues](https://github.com/kr0no/bloodhound-shell/issues).
+
+```bash
+git clone https://github.com/kr0no/bloodhound-shell.git
+cd bloodhound-shell
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e '.[dev]'
+python -m pytest
+```
+
+The tests mock the BloodHound API with `responses`, so no BloodHound server is needed.
+
+## License
+
+Distributed under the MIT License. See
+[LICENSE](https://github.com/kr0no/bloodhound-shell/blob/main/LICENSE) for details.
+
+BloodHound is a trademark of SpecterOps. bhshell is an independent project and is not affiliated
+with or endorsed by SpecterOps.

bhshell-0.1.0/bhshell/__init__.py

@@ -0,0 +1,3 @@
+"""bhshell - an interactive shell for BloodHound."""
+
+__version__ = "0.1.0"

bhshell-0.1.0/bhshell/__main__.py

@@ -0,0 +1,3 @@
+from bhshell.cli import main
+
+raise SystemExit(main())

bhshell-0.1.0/bhshell/cli.py

@@ -0,0 +1,55 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from cmd2.string_utils import quote_if_needed
+
+from bhshell import __version__
+from bhshell.client.client import normalize_url
+from bhshell.config import Config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="bhshell", description="Interactive shell for BloodHound.")
+    p.add_argument("--url", help="BH backend URL (persisted; default http://127.0.0.1:8080/)")
+    p.add_argument("-k", "--insecure", action="store_true", help="disable TLS certificate verification (persisted; 'tls on' re-enables it)")
+    p.add_argument("--no-resume", action="store_true", help="do not resume the cached session")
+    p.add_argument("-c", "--command", action="append", default=[], metavar="CMD",
+                   help="run CMD and exit (repeatable)")
+    p.add_argument("-s", "--script", metavar="FILE", help="run commands from FILE and exit")
+    p.add_argument("--debug", action="store_true", help="show tracebacks for errors")
+    p.add_argument("--version", action="version", version=f"bhshell {__version__}")
+    return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    config = Config.load()
+    changed = False
+    if args.url:
+        try:
+            config.url = normalize_url(args.url)
+        except ValueError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        changed = True
+    if args.insecure:
+        config.verify_tls = False
+        changed = True
+    if changed:
+        config.save()
+
+    from bhshell.shell.app import BHShell  # imported late so '--help' stays fast
+
+    app = BHShell(config, debug=args.debug, resume=not args.no_resume)
+    if args.command or args.script:
+        commands = list(args.command)
+        if args.script:
+            commands.append(f"run_script {quote_if_needed(args.script)}")
+        app.runcmds_plus_hooks(commands)
+        return app.exit_code or (1 if app.command_failures else 0)
+    return app.cmdloop() or 0

bhshell-0.1.0/bhshell/client/auth.py

@@ -0,0 +1,74 @@
+"""Request authenticators for the BH API.
+
+Two schemes are supported:
+
+* `JWTAuth` - `Authorization: Bearer <session_token>` obtained from
+  `POST /api/v2/login`.
+* `HMACAuth` - BH API tokens (Token ID + Token Key). Each request is
+  signed with a chained HMAC-SHA256 as documented by SpecterOps:
+
+  1. `k1 = HMAC(token_key, METHOD + URI)`
+  2. `k2 = HMAC(k1, RequestDate[:13])`  (RFC3339 date truncated to the hour)
+  3. `signature = HMAC(k2, body)`
+
+  Headers: `Authorization: bhesignature <token_id>`, `RequestDate` and
+  `Signature` (base64).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+from collections.abc import Callable
+from datetime import datetime
+from urllib.parse import urlsplit
+
+from requests import PreparedRequest
+from requests.auth import AuthBase
+
+
+class JWTAuth(AuthBase):
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    def __call__(self, r: PreparedRequest) -> PreparedRequest:
+        r.headers["Authorization"] = f"Bearer {self.token}"
+        return r
+
+
+class HMACAuth(AuthBase):
+    def __init__(
+        self,
+        token_id: str,
+        token_key: str,
+        *,
+        clock: Callable[[], datetime] | None = None,
+    ) -> None:
+        self.token_id = token_id
+        self._key = token_key.encode()
+        self._clock = clock or (lambda: datetime.now().astimezone())
+
+    @staticmethod
+    def _request_uri(url: str) -> str:
+        parts = urlsplit(url)
+        return parts.path + (f"?{parts.query}" if parts.query else "")
+
+    def sign(self, method: str, uri: str, body: bytes | None, request_date: str) -> str:
+        digester = hmac.new(self._key, None, hashlib.sha256)
+        digester.update(f"{method.upper()}{uri}".encode())
+        digester = hmac.new(digester.digest(), None, hashlib.sha256)
+        digester.update(request_date[:13].encode())
+        digester = hmac.new(digester.digest(), None, hashlib.sha256)
+        if body:
+            digester.update(body)
+        return base64.b64encode(digester.digest()).decode()
+
+    def __call__(self, r: PreparedRequest) -> PreparedRequest:
+        request_date = self._clock().isoformat("T")
+        body = r.body.encode() if isinstance(r.body, str) else r.body
+        signature = self.sign(r.method or "GET", self._request_uri(r.url or ""), body, request_date)
+        r.headers["Authorization"] = f"bhesignature {self.token_id}"
+        r.headers["RequestDate"] = request_date
+        r.headers["Signature"] = signature
+        return r