Metadata-Version: 2.4
Name: racfhound
Version: 0.1.1
Summary: RACF security analysis for z/OS — collect, transform, and upload to BloodHound CE
Project-URL: Repository, https://github.com/JonathanPrince/racfhound
Project-URL: Documentation, https://github.com/JonathanPrince/racfhound/tree/main/docs
Project-URL: Bug Tracker, https://github.com/JonathanPrince/racfhound/issues
Author-email: Jonathan Prince <jonathan.prince@gmail.com>
License: MIT
License-File: LICENSE
Keywords: attack-path,bloodhound,graph,ibm,irrdbu00,mainframe,penetration-testing,racf,red-team,security,z/os,zos
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: mfpandas-racfhound>=0.1.1
Requires-Dist: paramiko>=3.0
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

# RACFHound

Automated RACF security analysis for z/OS. Collects the RACF database via SSH, transforms it into a BloodHound-compatible graph, and uploads it to BloodHound CE for attack path analysis.

```
z/OS (SSH + FTP)          Linux                    BloodHound CE
┌──────────────┐          ┌─────────────────┐       ┌────────────────┐
│  RACF DB     │─IRRDBU00→│  racfdump.txt   │       │  Graph DB      │
│  SYS1.RACFDS │          │  apflist.txt    │─────→ │  RACF nodes    │
│  APF/PARMLIB │          │  opengraph.json │       │  Attack paths  │
└──────────────┘          └─────────────────┘       └────────────────┘
```

## Quick start — collect from z/OS

```bash
pip install racfhound

# 1. Collect from z/OS
racfhound collect \
  --host zos.example.com --user IBMUSER --key ~/.ssh/id_rsa

# 2. Transform to BloodHound graph
racfhound export --dump collect_output/racfdump.txt \
  --apf collect_output/apflist.txt \
  --parmlib collect_output/parmlist.txt \
  --proclib collect_output/proclist.txt

# 3. Authenticate to BloodHound
export BH_URL=http://bloodhound:8080
export BH_TOKEN=$(racfhound login --user admin@example.com --password 's3cr3t')

# 4. Provision BloodHound (once per instance)
racfhound provision
racfhound queries

# 5. Upload graph
racfhound upload racf_opengraph.json
```

## Quick start — local IRRDBU00 unload

If you already have an IRRDBU00 unload (from manual FTP, a previous run, or a third-party extraction), skip straight to transform:

```bash
# Transform an existing unload — no z/OS connection required
racfhound export --dump /path/to/racfdump.txt

# With optional context lists for APF/PARMLIB/PROCLIB marking
racfhound export --dump /path/to/racfdump.txt \
  --apf apflist.txt --parmlib parmlist.txt --proclib proclist.txt

# Then authenticate and upload as normal
export BH_TOKEN=$(racfhound login --user admin@example.com --password 's3cr3t')
racfhound upload racf_opengraph.json
```

## Prerequisites

| Requirement | Notes |
|-------------|-------|
| Python ≥ 3.10 | |
| BloodHound CE | For graph analysis |
| z/OS OpenSSH | SSH + SFTP access — only needed for remote collection |
| z/OS FTP server | For retrieving the RACF dump — only needed for remote collection |
| IRRDBU00 authority | RACF READ on the database dataset — only needed for remote collection |

The collecting user needs:
- SSH login to z/OS UNIX System Services
- READ access to the RACF database dataset (`SYS1.RACFDS` or equivalent)
- TSO access (for `RVARY LIST` and job submission)
- FTP access to the z/OS system

## Architecture

RACFHound is built from two cooperating packages:

```
mfpandas-racfhound          (transforms IRRDBU00 output → BloodHound OpenGraph)
    ↑  imported by                github.com/JonathanPrince/mfpandas-racfhound
racfhound                   (collect → transform → export pipeline + CLI)
    collect/                SSH collection, JCL submission, FTP retrieval
    data/                   Bundled custom-types.json + 40 Cypher queries
```

Both packages depend on [`mfpandas`](https://github.com/wizardofzos/mfpandas) (upstream IRRDBU00 parser by [@wizardofzos](https://github.com/wizardofzos)).

The transformation is done by [`mfpandas-racfhound`](https://github.com/JonathanPrince/mfpandas-racfhound) which maps RACF profiles, ACLs, group structure, and system attributes into BloodHound graph nodes and edges.

## Commands

| Command | Description |
|---------|-------------|
| `collect` | Collect from z/OS via SSH/FTP — RVARY LIST, IRRDBU00, PARMLIB |
| `export` | Transform a RACF unload file into BloodHound OpenGraph JSON |
| `login` | Authenticate to BloodHound CE and print a session token |
| `provision` | Register RACF node type icons and colours (once per instance) |
| `queries` | Load 40 bundled RACF Cypher queries (once per instance) |
| `upload` | Upload an OpenGraph JSON file to BloodHound CE |

## What gets collected

| Artifact | Source | Purpose |
|----------|--------|---------|
| `racfdump.txt` | IRRDBU00 unload | All RACF profiles (users, groups, datasets, resources) |
| `apflist.txt` | PARMLIB PROGxx | Marks APF-authorised libraries in the graph |
| `parmlist.txt` | PARMLIB member | Marks PARMLIB datasets in the graph |
| `proclist.txt` | PARMLIB member | Marks PROCLIB datasets in the graph |

## Environment variables

| Variable | Command | Description |
|----------|---------|-------------|
| `MF_HOST` | collect | z/OS SSH hostname |
| `MF_PORT` | collect | SSH port (default 22) |
| `MF_FTP_PORT` | collect | FTP port (default 21) |
| `MF_USER` | collect | TSO/USS username |
| `MF_KEY` | collect | SSH private key path |
| `MF_PASSWORD` | collect | SSH/FTP password |
| `MF_RACF_DSN` | collect | RACF database DSN (overrides RVARY LIST) |
| `MF_JOB_CLASS` | collect | JES job class |
| `MF_MSG_CLASS` | collect | JES message class |
| `BH_URL` | login / provision / queries / upload | BloodHound base URL |
| `BH_USER` | login | BloodHound username / email |
| `BH_PASSWORD` | login | BloodHound password |
| `BH_TOKEN` | provision / queries / upload | BloodHound JWT session token |

## Documentation

- [Getting started](docs/getting-started.md)
- [Collection](docs/collect.md)
- [BloodHound setup](docs/bloodhound.md)
- [Query reference](docs/queries.md)

## Graph model

**Nodes:** `RACFUser` · `RACFGroup` · `RACFDataset` · `RACFResource` · `RACFPrivilege` · `RACFStartedTask` · `RACFClass` · `RACFCertificate` · `RACFMFAFactor` · `RACFUndefined`

**Edges:** `RACFMemberOf` · `RACFHasSubgroup` · `RACFGroupAuth_{USE|CREATE|CONNECT|JOIN}` · `RACFOwns` · `RACFCanRead` · `RACFCanWrite` · `RACFCanExecute` · `RACFHasPrivilege` · `RACFSurrogateFor` · `RACFStartedTaskRunsAs` · `RACFCertificateFor` · `RACFPassticketFor` · `RACFCanAccessKey`

See the [query reference](docs/queries.md) and [BloodHound setup](docs/bloodhound.md) for more detail.
