bhshell

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).

pipx install bhshell     # recommended
# or
pip install bhshell

Quick Start

$ 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] > ou corp.local -t

[bh: shell] > computer WEB01 -G

[bh: shell] > path --owned -g

The same commands run non-interactively for scripting: bhshell -c "hunt --json" > hunt.json.

What it does

To add your own query, save it as a .cyp file in ~/.bhshell/queries/ and run it by name:

$ 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 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. Inside the shell, run help or help <command>.

Contributing

Bug reports and pull requests are welcome at github.com/kr0no/bloodhound-shell/issues.

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 for details.

BloodHound is a trademark of SpecterOps. bhshell is an independent project and is not affiliated with or endorsed by SpecterOps.