human-risk-graph 0.1.8

A quantitative model for measuring organizational security risk caused by human dependencies

Human Risk Graph (HRG)

Human Risk Graph (HRG) is a quantitative model for measuring organizational security risk caused by human dependencies, decision concentration, and bus-factor effects.

Unlike traditional security models that focus only on technical assets, HRG treats people as part of the attack surface and models how organizational decisions and emergency processes introduce systemic risk.

Core Idea

Organizations often depend on a small number of individuals for:

• critical decisions,
• emergency bypasses,
• access approvals.

HRG represents these dependencies as a directed graph and computes risk metrics that highlight human single points of failure.

What HRG Measures

• Bus Factor Risk — how fragile the organization is to the loss of key people
• Decision Concentration — how much authority is centralized
• Bypass Risk — how often normal controls are overridden by humans

Repository Structure

• src/ — core implementation (HRG class, metrics, graph algorithms)
• tests/ — comprehensive unit tests
• experiments/ — synthetic data generation and benchmarking
• examples/ — usage demonstrations
• paper/ — LaTeX source for academic paper (arXiv-ready)
• docs/ — formal model with mathematical definitions
• data/ — example organization datasets

Quick Start

Installation

# Install from PyPI (recommended)
pip install human-risk-graph

# Or install from source
git clone https://github.com/LF3551/human-risk-graph.git
cd human-risk-graph
pip install -e .

# With development tools
pip install -e ".[dev]"

Data Format

Create a JSON file describing your organization structure:

{
  "people": [
    { "id": "A", "role": "SRE", "criticality": 0.9 },
    { "id": "B", "role": "Security Engineer", "criticality": 0.8 },
    { "id": "C", "role": "Manager", "criticality": 0.7 },
    { "id": "D", "role": "Developer", "criticality": 0.4 }
  ],
  "dependencies": [
    { "from": "A", "to": "B", "type": "approval", "weight": 0.8 },
    { "from": "C", "to": "A", "type": "bypass", "weight": 0.9 }
  ]
}

Fields:

• people.id — unique identifier
• people.role — job title (optional)
• people.criticality — importance level (0.0-1.0)
• dependencies.from/to — person IDs
• dependencies.type — relationship type (approval, bypass, etc.)
• dependencies.weight — dependency strength (0.0-1.0)

CLI Usage

The easiest way to use HRG is through the command-line interface:

# Analyze an organization (generates JSON, Markdown, and HTML reports)
hrg analyze data/example_organization.json

# Generate only HTML report
hrg analyze data/example_organization.json --format html

# Specify output file
hrg analyze data/example_organization.json --format html --output my_report.html

# Generate interactive graph visualization only
hrg visualize data/example_organization.json

Example Output

🔍 Analyzing: data/example_organization.json
⚙️  Running Human Risk Graph analysis...
✅ Generated: example_organization_report.json
✅ Generated: example_organization_graph.html

============================================================
📊 ANALYSIS SUMMARY
============================================================
Composite HRG Score: 0.090
  • Bus Factor Score: 0.225
  • Decision Concentration: 0.000
  • Bypass Risk Score: 0.000

⚠️  Critical People (Articulation Points): 1
   - A

✅ Analysis complete! Generated 2 file(s).

Generated files:

• JSON report with detailed metrics
• Interactive HTML graph visualization
• Optional Markdown and HTML reports

Python API Usage

from src.hrg import HumanRiskGraph

# Load your organization data
people = [...]
dependencies = [...]

# Create and analyze
hrg = HumanRiskGraph(people, dependencies)
results = hrg.calculate()

print(f"Composite Risk Score: {results['composite_score']:.3f}")
print(f"Critical People: {results['critical_people']}")

Development

# Run tests
pytest tests/ -v

# Run tests with coverage
pytest tests/ --cov=src --cov-report=html

# Code formatting
black src/ tests/ --line-length 100

# Linting
flake8 src/ tests/

# Run experiments
python experiments/generate_data.py
python experiments/run_experiments.py
python experiments/visualize.py

Key Features

• Graph-based analysis using NetworkX
• Three core metrics: Bus Factor, Decision Concentration, Bypass Risk
• Polynomial-time algorithms with proven complexity bounds
• Comprehensive test coverage
• Research paper ready for arXiv submission
• CISSP portfolio demonstration project

Use Cases

Best suited for: Organizations with 50+ employees, formal security processes, or compliance requirements.

• Security architecture analysis
• Business continuity planning (SOC2, ISO27001 audits)
• Insider threat assessment
• M&A due diligence (key person risk)
• Organizational risk modeling

Note: For small teams (<20 people), managers typically have direct visibility into dependencies. HRG provides the most value when organizational complexity exceeds intuitive understanding.

Status

This repository provides a reference implementation of the HRG model. It is intended for research, architecture analysis, and discussion — not as a production-ready security tool.

Citation

If you use this software in your research or work, please cite:

@software{aleinikov_2026_hrg,
  author       = {Aleinikov, Aleksei},
  title        = {Human Risk Graph: A Quantitative Model for Organizational Security Risk},
  year         = 2026,
  publisher    = {Zenodo},
  version      = {v0.1.8},
  doi          = {10.5281/zenodo.18316882},
  url          = {https://doi.org/10.5281/zenodo.18316882}
}

Or use this text citation:

Aleinikov, A. (2026). Human Risk Graph: A Quantitative Model for Organizational Security Risk (v0.1.8). Zenodo. https://doi.org/10.5281/zenodo.18316882

License

Licensed under the Apache License, Version 2.0. See the LICENSE file for details.