Metadata-Version: 2.4
Name: soaphound-py
Version: 1.5.0
Summary: BloodHound ingestor using ADWS (Active Directory Web Services), with Kerberos support. Official PyPI package maintained by @j4s0nmo0n.
Author: @belettet1m0ree, @Sant0rryu
License: MIT
Project-URL: Homepage, https://github.com/j4s0nmo0n/Soaphound.py
Project-URL: Repository, https://github.com/j4s0nmo0n/Soaphound.py
Project-URL: Issues, https://github.com/j4s0nmo0n/Soaphound.py/issues
Project-URL: Documentation, https://j4s0nmo0n.github.io/belettetimoree.github.io/2025/07/26/Soaphound.py-Collecting-Active-Directory-Objects-over-ADWS-from-Linux.html
Keywords: bloodhound,active-directory,adws,pentest,red-team,kerberos
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
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: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: impacket>=0.11.0
Requires-Dist: dnspython>=2.0.0
Requires-Dist: pyasn1>=0.4.8
Requires-Dist: pycryptodomex>=3.10.0
Requires-Dist: cryptography>=3.4.0
Requires-Dist: ldap3>=2.9.0
Requires-Dist: setuptools>=65.0
Requires-Dist: requests>=2.32.0
Requires-Dist: requests-gssapi>=1.4.0
Dynamic: license-file

# Description

While reading [BloodHound.py](https://github.com/dirkjanm/BloodHound.py), a Linux alternative to [SharpHound](https://github.com/SpecterOps/SharpHound), we observed that object collection is performed on a case-by-case basis. Specific conditions are evaluated to determine the most relevant information for each collected object, and tailored actions are taken accordingly.

We sought to follow a similar logic while implementing Soaphound.py, aiming to collect the most valuable information during object enumeration through ADWS. In addition, since user sessions on machines are not collected through LDAP, we reused BloodHound.py's approach to perform this collection.

The tool is currently being improved to cover all specific data collection scenarios. At the time of writing, it is capable of collecting Active Directory objects via the ADWS service and retrieving remote session data similar to what BloodHound.py achieves.


## Documentation

Full documentation lives on the **[Soaphound.py Wiki](https://github.com/j4s0nmo0n/Soaphound.py/wiki)**.

### Getting started
- [Installation](https://github.com/j4s0nmo0n/Soaphound.py/wiki/Installation)
- [Quick Start](https://github.com/j4s0nmo0n/Soaphound.py/wiki/Quick-Start)

### Collection
- [BloodHound Ingestion](https://github.com/j4s0nmo0n/Soaphound.py/wiki/BloodHound-Ingestion) · [Collection Presets](https://github.com/j4s0nmo0n/Soaphound.py/wiki/Collection-Presets) · [Output Format](https://github.com/j4s0nmo0n/Soaphound.py/wiki/Output-Format)

### Primitives
- [AD CS Enumeration](https://github.com/j4s0nmo0n/Soaphound.py/wiki/AD-CS-Enumeration) · [AD CS Enrollment (MS-XCEP + MS-WSTEP)](https://github.com/j4s0nmo0n/Soaphound.py/wiki/AD-CS-Enrollment)
- [MS-ADCAP TopologyManagement](https://github.com/j4s0nmo0n/Soaphound.py/wiki/MS-ADCAP) · [BadSuccessor Orchestrator](https://github.com/j4s0nmo0n/Soaphound.py/wiki/BadSuccessor)
- [Trust Audit](https://github.com/j4s0nmo0n/Soaphound.py/wiki/Trust-Audit) · [Privilege Rights Audit](https://github.com/j4s0nmo0n/Soaphound.py/wiki/Privilege-Rights-Audit)

### Attack playbooks
- [ESC4 via Full SOAP](https://github.com/j4s0nmo0n/Soaphound.py/wiki/Playbook-ESC4)
- [BadSuccessor via ADWS Writes](https://github.com/j4s0nmo0n/Soaphound.py/wiki/Playbook-BadSuccessor)

### Defender's corner
- [Detection & Hunting Tips](https://github.com/j4s0nmo0n/Soaphound.py/wiki/Detection)


## Collection methods

| Preset | Network ports | AD coverage | Use case |
|---|---|---|---|
| `-c Default` (default) | TCP:9389 (ADWS, including cross-NC referral follow) + TCP:445 (SMB SYSVOL when GPOs are found, plus per-host sessions) | **Full** — all objects, GPO settings, local admins, GPP cpassword, trust risks | Standard pentest, AD audit |
| `-c Stealth` | TCP:9389 only (ADWS + referral follow stays on ADWS) | **Partial** — AD objects only; GPO settings, local admins, cpassword and computer sessions NOT collected | Red Team ops where SMB is blocked or monitored |
| `-c ADWSOnly` | (deprecated alias of Stealth) | Same as Stealth | Backward compatibility, will be removed in v1.5 |

**Note on referrals.** When a cross-naming-context query (for example a trust in another forest partition) returns an `ADWSReferralError`, Soaphound.py opens a new ADWS session on the referred DC. The target URL is formatted as `ldap://<fqdn>/...` by the server, but the client connection stays on TCP:9389 — no native LDAP (TCP:389) traffic is generated.

**Why two modes?** The richest offensive signals (local admins, user rights, GPP cpassword credentials) live in SYSVOL, not in the AD database. A proper reconnaissance requires reading both over ADWS AND over SMB SYSVOL. The Stealth mode exists for the specific case where SMB TCP:445 is unavailable or must stay silent, with the explicit trade-off of a partial output.

More information: [you may check out the short blog post](https://j4s0nmo0n.github.io/belettetimoree.github.io/Soaphound.py%20-%20Collecting%20Active%20Directory%20Objects%20over%20ADWS%20from%20Linux.html)

# Usage
```
 .oooooo..o                                oooo                                                .o8                             
d8P'    `Y8                                `888                                               "888                             
Y88bo.       .ooooo.   .oooo.   oo.ooooo.   888 .oo.    .ooooo.  oooo  oooo  ooo. .oo.    .oooo888      oo.ooooo.  oooo    ooo 
 `"Y8888o.  d88' `88b `P  )88b   888' `88b  888P"Y88b  d88' `88b `888  `888  `888P"Y88b  d88' `888       888' `88b  `88.  .8'  
     `"Y88b 888   888  .oP"888   888   888  888   888  888   888  888   888   888   888  888   888       888   888   `88..8'   
oo     .d8P 888   888 d8(  888   888   888  888   888  888   888  888   888   888   888  888   888  .o.  888   888    `888'    
8""88888P'  `Y8bod8P' `Y888""8o  888bod8P' o888o o888o `Y8bod8P'  `V88V"V8P' o888o o888o `Y8bod88P" Y8P  888bod8P'     .8'     
                                 888                                                                     888       .o..P'      
                                o888o                                                                   o888o      `Y8P'       
                                                                                                    (made by @belettet1m0ree)


usage: soaphound [-h] [-c COLLECTIONMETHOD] -d DOMAIN [-v] [--ts] -u USERNAME
                 [-p PASSWORD] [--hashes HASHES] [-k] [-aesKey HEXKEY]
                 [-dc-ip HOST] -dc HOST [--zip] [-op PREFIX_NAME]
                 [-wk NUM_WORKERS] [--output-dir OUTPUT_DIR]
                 [--cert-find] [--cert-find-force-epa {auto,enabled,disabled}]
                 [--cert-find-skip-web-probe] [--cert-find-ca-rpc]

Python based ingestor for BloodHound using ADWS

options:
  -h, --help            show this help message and exit
  -c, --collectionmethod {Default,Stealth,ADWSOnly}
                        Collection preset. Default: AD objects via ADWS +
                        GPO via SMB SYSVOL (full output). Stealth: ADWS
                        only, TCP:9389 only, no SMB. ADWSOnly: deprecated
                        alias of Stealth, will be removed in v1.5.
  -d, --domain DOMAIN   Domain to query.
  -v                    Enable verbose output.
  --ts                  Add timestamp to logs.

authentication options:
  NTLM authentication is supported using a username/password or NT hash.
  Kerberos authentication is supported through -k using the ccache pointed to
  by KRB5CCNAME.

  -u, --username USERNAME
                        Username. Format: username[@domain].
                        If the domain is unspecified, the current domain is used.
  -p, --password PASSWORD
                        Password.
  --hashes HASHES       LM:NTLM hashes.
  -k, --kerberos        Use Kerberos authentication through the ticket available
                        in the ccache pointed to by KRB5CCNAME.
  -aesKey, --aes-key HEXKEY
                        AES key, 128 or 256 bits, for Kerberos authentication.
                        Used for SMB collection in Default mode.
  -dc-ip, --kdc-ip HOST
                        KDC IP address or hostname. Useful when the ADWS DC and
                        the KDC differ. Defaults to the value provided with -dc.

collection options:
  -dc, --domain-controller HOST
                        DC to query, hostname or FQDN.
  --zip                 Compress the JSON output files into a zip archive.
  -op, --outputprefix PREFIX_NAME
                        String to prepend to output file names.
  -wk, --worker_num NUM_WORKERS
                        Number of workers, default 100.
  --output-dir OUTPUT_DIR
                        Output folder, default current directory.
  --cert-find           Enumerate AD CS certificate templates and CAs like certipy find.
  --cert-find-force-epa {auto,enabled,disabled}
                        Override HTTPS EPA detection for AD CS Web Enrollment: auto, enabled, or disabled.
  --cert-find-skip-web-probe
                        Do not probe HTTP/HTTPS /certsrv/ endpoints AD CS Web Enrollment and ESC8 will not be evaluated.
  --cert-find-ca-rpc    Enrich CA configuration through Remote Registry/RPC:
                        User Specified SAN, Request Disposition, Enforce
                        Encryption, Active Policy.

```

# Installation

## From PyPI (recommended)

```bash
pipx install soaphound-py
soaphound --help
```

> **Note on PyPI namespace** - The official PyPI distribution is **`soaphound-py`** (with the `-py` suffix). A separate package named `soaphound` was published on PyPI on 2026-03-29 by an unrelated third party; **that package is not maintained by this project**. Always install `soaphound-py`.

To upgrade later:
```bash
pipx upgrade soaphound-py
```

## From git (alternative)

```bash
pipx install git+https://github.com/j4s0nmo0n/Soaphound.py
soaphound --help
```

## With `poetry` (development)

```bash
git clone https://github.com/j4s0nmo0n/Soaphound.py
cd Soaphound.py
poetry install
poetry run soaphound --help
```

## With `pip` in a virtualenv

```bash
python3 -m venv ~/venvs/soaphound
source ~/venvs/soaphound/bin/activate
pip install git+https://github.com/j4s0nmo0n/Soaphound.py
```

# Example Usage

Perform ADWS collection with session enumeration

```
soaphound -d corp.local -u alice -p Password123! -dc dc01 --output-dir output
```

Perform Stealth collection (ADWS only, no SMB — skips SYSVOL, local admins, cpassword, computer sessions)

```
soaphound -d corp.local -u alice -p Password123! -dc dc01 --output-dir output -c Stealth
```

Perform ADCS information collection

```
soaphound -d corp.local -u alice -p Password123! -dc dc01 --cert-find --cert-find-force-epa auto
```

# Kerberos authentication (-k)

Soaphound supports Kerberos authentication through the `-k` option and the `KRB5CCNAME` environment variable.

The ccache may contain a valid TGT or a usable service ticket, depending on the collection mode and the operations being performed.

```bash
# Load a Kerberos ticket
export KRB5CCNAME=/tmp/alice.ccache

# Run Soaphound with Kerberos
soaphound -d corp.local -u alice -dc dc01.corp.local -k

# Run Stealth collection with Kerberos (ADWS only, no SMB)
soaphound -d corp.local -u alice -dc dc01.corp.local -k -c Stealth

# Let Soaphound extract the username and domain from the ccache
soaphound -dc dc01.corp.local -k -c Stealth

# Use a different KDC
soaphound -d corp.local -u alice -dc adws.corp.local -dc-ip kdc.corp.local -k
```

# References

- [Falcon Force Team](https://falconforce.nl/soaphound-tool-to-collect-active-directory-data-via-adws/) for the initial inspiration.
- [BloodHound.py](https://github.com/dirkjanm/BloodHound.py), for this amazing implementation of BloodHound ingestor.
- [SOAPy](https://github.com/logangoins/SOAPy) by @_logangoins, whose Kerberos NNS implementation is the basis of the `-k` support.
- [Microsoft](https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-addm/59205cf6-aa8e-4f7e-be57-8b63640bf9a4) for the official protocol documentation.
- [ERNW](https://insinuator.net/2016/08/pentesting-webservices-with-net-tcp-binding/) for the initial boost.
- [X-Force Red](https://www.ibm.com/think/x-force/stealthy-enumeration-of-active-directory-environments-through-adws) for their brilliant implementation of NBFX and research insights.
- [Rabobank Red Team](https://rabobank.jobs/en/techblog/adws-an-unconventional-path-into-active-directory-luc-kolen/) for sharing valuable resources and operational insights.
