Metadata-Version: 2.4
Name: bofhound
Version: 0.5.0
Summary: Parse output from common sources and transform it into BloodHound-ingestible data
License-File: LICENSE
Author: Adam Brown
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.14
Requires-Dist: Flask (>=2.0,<3.0)
Requires-Dist: Jinja2 (>=3.0.3,<4.0.0)
Requires-Dist: MarkupSafe (>=2.0.1,<3.0.0)
Requires-Dist: Werkzeug (>=2.0.2,<3.0.0)
Requires-Dist: adidnsdump (>=1.4.0,<2.0.0)
Requires-Dist: asn1crypto (>=1.5.1,<2.0.0)
Requires-Dist: bloodhound (>=1.6,<2.0)
Requires-Dist: cffi (>=1.17.1,<2.0.0)
Requires-Dist: chardet (>=4.0,<5.0)
Requires-Dist: click (==8.1.8)
Requires-Dist: cryptography (>=36.0,<37.0)
Requires-Dist: dnspython (>=2.2,<3.0)
Requires-Dist: future (>=0.18.2,<0.19.0)
Requires-Dist: impacket (>=0.10.0,<0.11.0)
Requires-Dist: itsdangerous (>=2.0.1,<3.0.0)
Requires-Dist: ldap3 (>=2.9.1,<3.0.0)
Requires-Dist: ldapdomaindump (>=0.9.3,<0.10.0)
Requires-Dist: mythic (>=0.2.5,<0.3.0)
Requires-Dist: pyOpenSSL (>=22.0.0,<23.0.0)
Requires-Dist: pyasn1 (>=0.4.8,<0.5.0)
Requires-Dist: pycparser (>=2.21,<3.0)
Requires-Dist: pycryptodomex (>=3.14.0,<4.0.0)
Requires-Dist: requests (>=2.32.3,<3.0.0)
Requires-Dist: rich (>=12.5,<13.0)
Requires-Dist: six (>=1.16.0,<2.0.0)
Requires-Dist: typer (>=0.9,<0.10)
Project-URL: Homepage, https://github.com/coffeegist/bofhound
Project-URL: Repository, https://github.com/coffeegist/bofhound
Description-Content-Type: text/markdown

```
              _____________________________ __    __    ______    __    __   __   __   _______
             |   _   /  /  __   / |   ____/|  |  |  |  /  __  \  |  |  |  | |  \ |  | |       \
             |  |_)  | |  |  |  | |  |__   |  |__|  | |  |  |  | |  |  |  | |   \|  | |  .--.  |
             |   _  <  |  |  |  | |   __|  |   __   | |  |  |  | |  |  |  | |  . `  | |  |  |  |
             |  |_)  | |  `--'  | |  |     |  |  |  | |  `--'  | |  `--'  | |  |\   | |  '--'  |
             |______/   \______/  |__|     |__|  |___\_\________\_\________\|__| \___\|_________\

                                         << @coffeegist | @Tw1sm >>
```

<h1 align="center">

![Python](https://img.shields.io/badge/python-3670A0?style=for-the-badge&logo=python&logoColor=ffdd54)
![PyPi](https://img.shields.io/pypi/v/bofhound?style=for-the-badge)
</h1>

BOFHound is an offline BloodHound ingestor and LDAP result parser compatible with TrustedSec's [ldapsearch BOF](https://github.com/trustedsec/CS-Situational-Awareness-BOF), the Python adaptation, [pyldapsearch](https://github.com/fortalice/pyldapsearch) and Brute Ratel's [LDAP Sentinel](https://bruteratel.com/tabs/commander/badgers/#ldapsentinel). ldapsearch BOF output can also be parsed from [Havoc](https://github.com/HavocFramework/Havoc) logs, OutflankC2 logs, and [Mythic](https://github.com/its-a-feature/Mythic) callbacks.

By parsing log files generated by the aforementioned tools, BOFHound allows operators to utilize BloodHound's beloved interface while maintaining full control over the LDAP queries being run and the spped at which they are executed. This leaves room for operator discretion to account for potential honeypot accounts, expensive LDAP query thresholds and other detection mechanisms designed with the traditional, automated BloodHound collectors in mind.

Check this [PR](https://github.com/trustedsec/CS-Situational-Awareness-BOF/pull/114) to the SA BOF repo for BOFs that collect session and local group membership data and can be parsed by BOFHound.

### References

Blog Posts:

| Title| Date|
|------|-----|
| [*BOFHound: AD CS Integration*](https://medium.com/specter-ops-posts/bofhound-ad-cs-integration-91b706bc7958) | Oct 30, 2024 |
| [*BOFHound: Session Integration*](https://posts.specterops.io/bofhound-session-integration-7b88b6f18423) | Jan 30, 2024 |
| [*Granularize Your AD Recon Game Part 2*](https://web.archive.org/web/20221205144115/https://www.fortalicesolutions.com/posts/granularize-your-active-directory-reconnaissance-game-part-2) | Jun 15, 2022 |
| [*Granularize Your AD Recon Game*](https://web.archive.org/web/20220813221840/https://www.fortalicesolutions.com/posts/bofhound-granularize-your-active-directory-reconnaissance-game) | May 10, 2022  |

Presentations:

| Conference| Materials| Date|
|-----------|----------|-----|
| *SO-CON 2024*| [Slides](https://github.com/SpecterOps/presentations/blob/main/SO-CON%202024/Matt%20Creel%20%26%20Adam%20Brown%20-%20Manually%20Enumerating%20AD%20Attack%20Paths%20with%20BOFHound/Matt%20Creel%20and%20Adam%20Brown%20-%20Manually%20Enumerating%20AD%20Attack%20Paths%20With%20BOFHound%20-%20SO-CON%202024.pdf) & [Recording](https://www.youtube.com/watch?v=Xxm4YktSKVY)| Mar 11, 2024|

# Installation
BOFHound can be installed with `pip3 install bofhound` or by cloning this repository and running `pip3 install .`

# Usage
```
 Usage: bofhound [OPTIONS]

 Generate BloodHound compatible JSON from logs written by the ldapsearch BOF, pyldapsearch and
 specific C2 frameworks

╭─ Options ─────────────────────────────────────────────────────────────────────────────────────╮
│ --input             -i      TEXT                             Directory or file containing     │
│                                                              logs of ldapsearch results       │
│                                                              [default:                        │
│                                                              /opt/cobaltstrike/logs]          │
│ --output            -o      TEXT                             Location to export bloodhound    │
│                                                              files                            │
│                                                              [default: .]                     │
│ --properties-level  -p      [Standard|Member|All]            Change the verbosity of          │
│                                                              properties exported to JSON:     │
│                                                              Standard - Common BH properties  │
│                                                              | Member - Includes MemberOf and │
│                                                              Member | All - Includes all      │
│                                                              properties                       │
│                                                              [default: Member]                │
│ --parser                    [ldapsearch|BRC4|Havoc|Outflank  Parser to use for log files.     │
│                             C2|Mythic]                       ldapsearch parser (default)      │
│                                                              supports ldapsearch BOF logs     │
│                                                              from Cobalt Strike and           │
│                                                              pyldapsearch logs                │
│                                                              [default: ldapsearch]            │
│ --debug                                                      Enable debug output              │
│ --zip               -z                                       Compress the JSON output files   │
│                                                              into a zip archive               │
│ --quiet             -q                                       Suppress banner                  │
│ --help              -h                                       Show this message and exit.      │
╰───────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Mythic Options ──────────────────────────────────────────────────────────────────────────────╮
│ --mythic-server        TEXT  IP or hostname of Mythic server to connect to                    │
│                              [default: 127.0.0.1]                                             │
│  --mythic-token         TEXT  Mythic API token [default: None]                                │
╰───────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ BloodHound CE Options ───────────────────────────────────────────────────────────────────────╮
│ --bh-token-id         TEXT  BloodHound API token ID [default: None]                           │
│ --bh-token-key        TEXT  BloodHound API token key [default: None]                          │
│ --bh-server           TEXT  BloodHound CE URL [default: http://127.0.0.1:8080]                │
╰───────────────────────────────────────────────────────────────────────────────────────────────╯
```

## Example Usage
Parse ldapseach BOF results from Cobalt Strike logs (`/opt/cobaltstrike/logs` by default) to /data/
```
bofhound -o /data/
```

Parse pyldapsearch logs and only include all properties (vs other property levels)
```
bofhound -i ~/.pyldapsearch/logs/ --properties-level all
```

Parse LDAP Sentinel data from BRc4 logs (will change default input path to `/opt/bruteratel/logs`)
```
bofhound --parser brc4
```

Parse Havoc loot logs (will change default input path to `/opt/havoc/data/loot`) and zip the resulting JSON files
```
bofhound --parser havoc --zip
```

## Uploading to BloodHound CE

Supply `--bh-server`, `--bh-token-id`, and `--bh-token-key` to upload after parsing.
BOFHound checks connectivity and credentials before parsing, then creates an upload
job after generating the files. Upload permissions are checked when that job starts.
Requests use a 10-second connect timeout and a 300-second read timeout.

Retry an upload without parsing the logs again:

```sh
bofhound --upload-only --output ./output --bh-server http://127.0.0.1:8080 --bh-token-id TOKEN_ID --bh-token-key TOKEN_KEY
```

This uploads all regular `*.json` files directly inside `--output` (default: current
directory). To upload existing `*.zip` archives instead, add `--zip`. In upload-only
mode, `--zip` selects archives; it does not create them. Use a directory containing
only the exports you intend to upload. Both token options are required; the server
defaults to `http://127.0.0.1:8080`.

An unsuccessful upload or job completion returns a nonzero exit status. Generated
files remain available for retrying; retrying a folder resends all selected files,
including any that were accepted in an earlier attempt. A successful exit confirms
upload acceptance and job completion, not the outcome of server-side ingestion.


## Performance & Cache

`--workers N` controls parallel file and ACL processing. Use `--workers 1` for
sequential processing. The default uses about 90% of available CPU cores. Actual pools are limited to the
number of tasks and the platform limit (61 processes on Windows). Files with
incomplete records and custom stateful parsers use sequential parsing to preserve
records spanning files. Pending tasks
are bounded; input or ACL worker failures abort before output/cache updates.

Caching is enabled by default at `--output/bofhound_cache.db`; override it with
`--cache-file PATH`, disable it with `--no-cache`, or inspect it with `--cache-stats`.
The cache stores data-only raw LDAP snapshots. Each run combines cached and current
LDAP data and rebuilds relationships against that complete snapshot. It does not
skip ACL processing or reuse computed relationships, because newly collected
objects can change existing relationships.

Present attributes replace earlier values, including empty strings. Cached group
membership links follow known identities through renames and are removed when the
known target is displaced; explicitly supplied membership attributes use current DNs. Objects and
attributes absent from a partial collection remain cached; absence does not prove
deletion. Use a new cache file to start a fresh snapshot. Local sessions and local
group records are processed from the current logs and are not retained in the cache.
`--context-from PATH` loads SID/domain/schema mappings and CA-host identities from
a prior cache (or a directory containing `bofhound_cache.db`) without exporting its
objects. Current collected computers take precedence over cached host identities.
Legacy or incompatible cache versions are rejected without being loaded or changed;
choose a new cache path or remove the old database and rebuild from the original logs.

```sh
bofhound -i ./logs --output ./out --workers 4
bofhound -i ./logs --output ./out --no-cache
bofhound --output ./out --cache-stats
```

# ldapsearch
Specify `*,ntsecuritydescriptor` as the attributes to return to be able to parse ACL edges. You are missing a ton of data if you don't include this in your `ldapsearch` queries!

#### Required Data
The following attributes are required for proper functionality:
```
samaccounttype
distinguishedname
objectsid
```

Some object classes rely on domain objects being populated within BOFHound. Domains can be queried with either of the following commands
```
ldapsearch (objectclass=domain) --attributes *,ntsecuritydescriptor
ldapsearch (distinguishedname=DC=windomain,DC=local) --attributes *,ntsecuritydescriptor
```

## Example ldapsearch Queries
```
# Get All the Data (Maybe Run BloodHound Instead?)
ldapsearch (objectclass=*) --attributes *,ntsecuritydescriptor

# Retrieve All Schema Info
ldapsearch (schemaIDGUID=*) --attributes name,schemaidguid --dn CN=Schema,CN=Configuration,DC=windomain,DC=local

# Retrieve Only the ms-Mcs-AdmPwd schemaIDGUID
ldapsearch (name=ms-mcs-admpwd) --attributes name,schemaidguid --count 1 --dn CN=Schema,CN=Configuration,DC=windomain,DC=local

# Retrieve Domain NetBIOS Names (useful if collecting data via `netsession2/netloggedon2` BOFs)
ldapsearch (netbiosname=*) --dn "CN=Partitions,CN=Configuration,DC=windomain,DC=local"

# Unroll a group's nested members
ldapsearch (memberOf:1.2.840.113556.1.4.1941:=CN=TargetGroup,CN=Users,DC=windomain,DC=local) --attributes *,ntsecuritydescriptor

# Query domain trusts
ldapsearch (objectclass=trusteddomain) --attributes *,ntsecuritydescriptor

# Query across a trust
ldapsearch (objectclass=domain) --attributes *,ntsecuritydescriptor --hostname dc1.trusted.windomain.local --dn "DC=TRUSTED,DC=WINDOMAIN,DC=LOCAL"

#####
# Queries below populate objects for AD CS parsing

# Query the domain object
ldapsearch (objectclass=domain) --attributes *,ntsecuritydescriptor

# Query Enterprise CAs
ldapsearch (objectclass=pKIEnrollmentService) --attributes *,ntsecuritydescriptor --dn "CN=Configuration,DC=domain,DC=local"

# Query AIACAs, Root CAs and NTAuth Stores
ldapsearch (objectclass=certificationAuthority) --attributes *,ntsecuritydescriptor --dn "CN=Configuration,DC=domain,DC=local"

# Query Certificate Templates
ldapsearch (objectclass=pKICertificateTemplate) --attributes *,ntsecuritydescriptor --dn "CN=Configuration,DC=domain,DC=local"

# Query Issuance Policies
ldapsearch (objectclass=msPKI-Enterprise-Oid) --attributes *,ntsecuritydescriptor --dn "CN=Configuration,DC=domain,DC=local"
```

# Versions
Check the tagged releases to download a specific version
- v0.4.0 and onward support parsing AD CS objects and edges
- v0.3.0 and onward support session/local group data
- v0.2.1 and onward are compatible with BloodHound CE
- v0.2.0 is the last release supporting BloodHound Legacy

# Development
bofhound uses Poetry to manage dependencies. Install from source and setup for development with:

```shell
git clone https://github.com/fortalice/bofhound
cd bofhound
poetry install
poetry run bofhound --help
```

Release maintainers: see [the release guide](docs/RELEASING.md) for the manual GitHub Actions publishing process.

# References and Credits
- [@_dirkjan](https://twitter.com/_dirkjan) (and other contributors) for [BloodHound.py](https://github.com/fox-it/BloodHound.py)
- TrustedSec for [CS-Situational-Awareness-BOF](https://github.com/trustedsec/CS-Situational-Awareness-BOF)
- [P-aLu](https://github.com/P-aLu) for collaboration on bofhoud's [AD CS support](https://github.com/coffeegist/bofhound/pull/8)

