Skip to content

Commit fa333df

Browse files
ADScanProADScanPro
committed
Merge remote-tracking branch 'origin/main' into dev
2 parents a6bc8c1 + 3532a24 commit fa333df

10 files changed

Lines changed: 22301 additions & 383 deletions

File tree

‎.github/workflows/bump.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Bump Version
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
bump:
10+
# No ejecutes este job si el commit message incluye 'Bump version:'
11+
if: "! contains(github.event.head_commit.message, 'Bump version:')"
12+
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- name: Checkout
17+
uses: actions/checkout@v2
18+
with:
19+
token: ${{ secrets.PAT_TOKEN }}
20+
21+
- name: Setup Python
22+
uses: actions/setup-python@v2
23+
with:
24+
python-version: '3.9'
25+
26+
- name: Install bump2version
27+
run: |
28+
pip install bump2version
29+
30+
- name: Configure Git
31+
run: |
32+
git config --global user.name "github-actions"
33+
git config --global user.email "actions@github.com"
34+
35+
- name: Bump version
36+
run: |
37+
# Importante que en tu .bumpversion.cfg tengas configurado "tag = True"
38+
# y "tag_name = v{new_version}" si quieres que el tag sea "v0.1.7"
39+
bump2version patch
40+
41+
- name: Push changes
42+
run: |
43+
# Empuja el commit y el tag generado
44+
git push origin HEAD --follow-tags

‎.github/workflows/release.yml‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
on:
2+
push:
3+
tags:
4+
- 'v*' # <--- Se activa cuando se hace push de un tag que empiece por 'v'
5+
6+
jobs:
7+
release:
8+
runs-on: ubuntu-latest
9+
10+
steps:
11+
- name: Checkout
12+
uses: actions/checkout@v2
13+
14+
- name: Setup Python
15+
uses: actions/setup-python@v2
16+
with:
17+
python-version: '3.9'
18+
19+
- name: Install build
20+
run: pip install build
21+
22+
- name: Build
23+
run: python -m build
24+
25+
- name: Publish to PyPI
26+
uses: pypa/gh-action-pypi-publish@v1.4.2
27+
with:
28+
user: __token__
29+
password: ${{ secrets.PYPI_API_TOKEN }}

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2025 ADScanPro
3+
Copyright (c) 2025 ADScan
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# bloodhound-cli
2+
3+
**bloodhound-cli** is a Python command-line tool designed to query and manage data from **BloodHound**.
4+
5+
- Legacy (Neo4j-backed) is fully supported.
6+
- Community Edition (CE) is introduced with a pluggable client skeleton so behavior can be incrementally implemented without breaking legacy users.
7+
8+
>CE support note: This CLI now includes an early CE client. Many CE features are placeholders. If you need the official SpecterOps CE installer CLI, see their project at `https://github.com/specterOps/bloodHound-cli`.
9+
10+
## Key Features
11+
12+
1. **Configuration Management**
13+
14+
- Save your Neo4j connection details (host, port, user, and password) to a local configuration file (`~/.bloodhound_config`) using the `set` subcommand.
15+
- The configuration file is stored with restricted permissions (`chmod 600`) to protect your sensitive credentials.
16+
2. **ACL Queries (`acl` subcommand)**
17+
18+
- Enumerate ACLs related to a single user by specifying `-u/--user`.
19+
- Enumerate cross-domain ACLs for a domain by specifying `-d/--domain`.
20+
- Optionally exclude multiple domains with `-bd/--blacklist-domains`.
21+
3. **Computer Queries (`computer` subcommand)**
22+
23+
- Enumerate computers within a specified domain (`-d`).
24+
- Optionally save results to a file (`-o`).
25+
- Filter by LAPS status (`--laps True/False`).
26+
4. **User Queries (`user` subcommand)**
27+
28+
- Enumerate users within a specified domain (`-d`).
29+
- Optionally save results to a file (`-o`).
30+
- Use mutually exclusive filters to target specific user attributes:
31+
- `--admin-count`: Show only privileged (admin) users.
32+
- `--high-value`: Show only high-value users.
33+
- `--password-not-required`: Show only users with `passwordnotreqd` enabled.
34+
- `--password-never-expires`: Show only users with `pwdneverexpires` enabled.
35+
5. **Session and Access Queries**
36+
37+
- Query sessions and access path relations in a domain (legacy).
38+
39+
6. **Debug and Verbose Output**
40+
41+
- Global flags `--debug` and `--verbose` enhance output. When available, output is formatted with `rich`.
42+
43+
7. **Secure Credential Storage**
44+
45+
- The `set` subcommand saves your Neo4j credentials in a local file (`~/.bloodhound_config`) which is excluded from source control and has strict file permissions.
46+
47+
## Installation
48+
49+
It is recommended to install **bloodhound-cli** using [pipx](https://github.com/pipxproject/pipx) to ensure it runs in an isolated environment. You can install it from PyPI:
50+
51+
```sh
52+
pipx install bloodhound-cli
53+
```
54+
55+
Alternatively, you can use pip:
56+
57+
```sh
58+
pip install bloodhound-cli
59+
```
60+
61+
## Usage
62+
63+
1. **Set Neo4j (Legacy) Configuration**
64+
65+
```sh
66+
bloodhound-cli set --host <neo4j_host> --port <neo4j_port> --db-user <neo4j_user> --db-password <neo4j_password>
67+
```
68+
69+
2. **Set CE Configuration (optional, early support)**
70+
71+
(Removed) Use the auth subcommand passing --base-url and credentials instead.
72+
73+
3. **Authenticate to CE (generate and store token)**
74+
75+
```sh
76+
bloodhound-cli --edition ce auth --url http://localhost:7474 --username <user>
77+
# It will prompt for the password securely
78+
# Optional flags:
79+
# --password <pass>
80+
# --login-path /api/v2/login
81+
# --insecure
82+
```
83+
84+
4. **Run in a chosen edition**
85+
86+
- The default edition can be persisted in `~/.bloodhound_config` under `[GENERAL] edition`.
87+
Running `set` will store `legacy`; running `auth` will store `ce`.
88+
89+
- To target CE explicitly:
90+
91+
```sh
92+
bloodhound-cli --edition ce user --domain mydomain.local
93+
```
94+
95+
- Or via env var:
96+
97+
```sh
98+
BLOODHOUND_EDITION=ce bloodhound-cli user --domain mydomain.local
99+
```
100+
101+
5. **Upload collector artifacts to CE (v2 file-upload flow)**
102+
103+
```sh
104+
bloodhound-cli --edition ce upload \
105+
-f data1.zip data2.json \
106+
--start-path /api/v2/file-upload/start \
107+
--upload-path /api/v2/file-upload/{job_id} \
108+
--end-path /api/v2/file-upload/{job_id}/end
109+
# Optional flags:
110+
# --content-type application/zip|application/json (auto-detected if omitted)
111+
# --insecure
112+
```
113+
114+
6. **Enumerate ACLs**
115+
116+
- **For a single user:**
117+
118+
```sh
119+
bloodhound-cli acl --user myuser
120+
```
121+
122+
- **For cross-domain:**
123+
124+
```sh
125+
bloodhound-cli acl --domain mydomain.local
126+
```
127+
128+
- **Exclude multiple domains:**
129+
130+
```sh
131+
bloodhound-cli acl --domain mydomain.local -bd EXCLUDED1 EXCLUDED2
132+
```
133+
134+
7. **Enumerate Computers**
135+
136+
- **All computers in a domain:**
137+
138+
```sh
139+
bloodhound-cli computer --domain mydomain.local
140+
```
141+
142+
- **Filter by LAPS and save results:**
143+
144+
```sh
145+
bloodhound-cli computer --domain mydomain.local --laps True -o computers_with_laps.txt
146+
```
147+
148+
8. **Enumerate Users**
149+
150+
- **List all users in a domain:**
151+
152+
```sh
153+
bloodhound-cli user --domain mydomain.local
154+
```
155+
156+
- **List privileged (admin) users:**
157+
158+
```sh
159+
bloodhound-cli user --domain mydomain.local --admin-count
160+
```
161+
162+
- **List high-value users:**
163+
164+
```sh
165+
bloodhound-cli user --domain mydomain.local --high-value
166+
```
167+
168+
- **List users with password not required:**
169+
170+
```sh
171+
bloodhound-cli user --domain mydomain.local --password-not-required
172+
```
173+
174+
- **List users with password never expires:**
175+
176+
```sh
177+
bloodhound-cli user --domain mydomain.local --password-never-expires
178+
```
179+
180+
- **Save user query results:**
181+
182+
```sh
183+
bloodhound-cli user --domain mydomain.local --admin-count -o admin_users.txt
184+
```
185+
186+
## Edition Support Details
187+
188+
- `--edition legacy` (default): full feature set (Neo4j backend).
189+
- `--edition ce`: CE client with support for `auth` (/api/v2/login) y `upload` (flow de file-upload v2). El resto de comandos imprimirán un mensaje hasta estar conectados a CE.
190+
191+
## Changelog
192+
193+
- 0.2.0
194+
- Add `--edition` and `--verbose` global flags
195+
- Add CE configuration `set-ce` and CE client skeleton
196+
- Add CE `auth` (JWT via `/api/v2/login`) and `upload` (file-upload `/start`, `/{job_id}`, `/{job_id}/end`)
197+
- Integrate `rich` for debug/verbose output
198+
- Dependencies: add `requests`, `rich`
199+
200+
## License
201+
202+
This project is licensed under the MIT License.

‎img/adscan_icon.png‎

410 KB
Loading

‎img/adscan_logo_horizontal_tagline.png‎

1.48 MB
Loading

0 commit comments

Comments
 (0)