racfhound 0.1.0__tar.gz

racfhound-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Claude Code
+.claude/
+
+# Collection output (local run artifacts — not part of the package)
+collect_output/
+racf_opengraph.json
+racfdump.txt
+apflist.txt
+parmlist.txt
+proclist.txt
+
+# macOS
+.DS_Store

racfhound-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jonathan Prince
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

racfhound-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: racfhound
+Version: 0.1.0
+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
+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.

racfhound-0.1.0/README.md

@@ -0,0 +1,141 @@
+# 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.

racfhound-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "racfhound"
+version = "0.1.0"
+description = "RACF security analysis for z/OS — collect, transform, and upload to BloodHound CE"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Jonathan Prince", email = "jonathan.prince@gmail.com" },
+]
+keywords = [
+    "racf", "mainframe", "zos", "z/os", "ibm",
+    "bloodhound", "security", "attack-path", "graph",
+    "irrdbu00", "penetration-testing", "red-team",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "click>=8.0",
+    "requests>=2.28",
+    "paramiko>=3.0",
+    "mfpandas-racfhound",
+]
+
+[project.urls]
+Repository    = "https://github.com/JonathanPrince/racfhound"
+Documentation = "https://github.com/JonathanPrince/racfhound/tree/main/docs"
+"Bug Tracker" = "https://github.com/JonathanPrince/racfhound/issues"
+
+[project.scripts]
+racfhound = "racfhound.cli:cli"
+
+# ---------------------------------------------------------------------------
+# Build
+# ---------------------------------------------------------------------------
+
+[tool.hatch.build.targets.wheel]
+packages = ["racfhound"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "racfhound/",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

racfhound-0.1.0/racfhound/__init__.py

@@ -0,0 +1,3 @@
+"""RACFHound — RACF collection and BloodHound export pipeline."""
+
+__version__ = "0.1.0"