GrantPath

What it does · Collection modes · Quick start · Support matrix · Installation · Roadmap

Who has access? Why does it exist? What changes if you remove it?

GrantPath is a graph-powered, self-hosted Access Path Intelligence Platform for IAM, Active Directory and file server permissions. It reconstructs effective access through identities, nested groups, ACLs and inheritance, then turns that graph into explainable investigations, what-if simulations and access reviews.

GrantPath is an early public preview. Filesystem analysis and the main investigation flows are usable today; broader enterprise connector coverage is still evolving and is labeled conservatively in the support matrix.

What GrantPath Does

Investigate	Explain	Simulate	Govern
Find who can reach a resource	Reconstruct the groups, ACLs and inheritance behind access	Preview the effect of removing a grant, group or ACE	Run access reviews, remediation plans and scheduled reports

Typical questions:

• Why does mario.rossi still have write access to Finance?
• Which nested groups and ACLs make a share reachable?
• Who loses access if an ACE or group membership is removed?
• Which resources are overexposed or changed since the previous scan?
• Which review decisions can be exported for audit or remediation?

Beyond a raw ACL export

Traditional permission report	GrantPath
Lists isolated ACL entries	Reconstructs effective access paths
Leaves nested groups and inheritance to the operator	Explains how each principal reaches a resource
Makes cleanup a production experiment	Previews removals with scoped what-if analysis
Produces a point-in-time spreadsheet	Connects investigation, review, remediation and reporting

How It Works

flowchart TD
    A["Filesystem and identity sources"] --> B["Live or VSS collection"]
    B --> C["Raw versioned snapshot"]
    C --> D["Normalization pipeline"]
    D --> E["Access graph and materialized index"]
    E --> F["Investigate · Govern · Report"]

Loading

The collected source data is normalized into principals, groups, resources and access relationships. GrantPath then evaluates inherited grants and denies, ranks explainable paths and exposes the result through the API and task-oriented web interface.

Collection Modes

Mode	Best for	Behaviour	Availability
Live	Labs, test systems, Linux and remote SSH targets	Reads the configured target directly. This remains the default for existing targets.	Supported
Windows VSS snapshot	Safer point-in-time collection on a local Windows server or VM	Creates a temporary VSS shadow copy, scans it while preserving the original paths in results, then removes it in a finally cleanup step.	Pilot

VSS mode requires GrantPath to run locally on Windows with elevated privileges and the target must be an absolute local drive path such as D:\Shares. It does not support UNC or SSH targets. VSS reduces exposure to changing files but is not zero-impact: pilot it on a disposable VM and monitor shadow-storage use before production adoption.

See Windows VSS scan mode for requirements, lifecycle and diagnostics.

Current Capabilities

• local admin bootstrap, RBAC and MFA
• LDAP and OIDC authentication paths
• Windows and Linux filesystem collection, plus Linux over SSH
• opt-in Windows VSS snapshot collection for local elevated targets (pilot)
• versioned raw snapshots and normalization pipeline
• effective access, exposure and change queries
• deterministic why paths and scoped what-if simulations
• graph explorer and task-oriented investigation workspace
• access review campaigns and remediation plans
• HTML, PDF and XLSX reports with scheduling
• API/worker runtime split and operational job visibility
• Docker, Windows package and Linux installer paths

Enterprise integrations such as Microsoft Graph, Azure, Okta, AWS, Google and CyberArk have different maturity levels. Do not infer production support from the presence of a connector: check Supported vs partial first.

Quick Start

Local evaluation appliance

git clone https://github.com/OS3RVNO/GrantPath.git
cd GrantPath
docker compose -f docker-compose.appliance.yml up -d --build

Open http://127.0.0.1:8000. The appliance binds only to localhost and is intended for local evaluation, not direct exposure to an untrusted network.

Production Docker stack

cp .env.production.example .env
# Replace every required secret and hostname in .env
docker compose -f docker-compose.production.yml up -d

Production sessions require HTTPS. Terminate TLS through the examples in deploy/ or another trusted reverse proxy. Full instructions are in INSTALL.md.

Development

Backend

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r .\backend\requirements-dev.txt
.\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload --app-dir .\backend

Frontend

cd frontend
npm ci
npm run dev

The development UI is served at http://127.0.0.1:5173.

Quality gates

.\.venv\Scripts\python.exe -m pytest backend/tests
.\.venv\Scripts\python.exe -m bandit -r backend/app -ll
.\.venv\Scripts\python.exe -m pip_audit -r backend/requirements.txt
cd frontend
npm run lint
npm run build
npm audit --omit=dev

Architecture

Layer	Responsibility
Collectors	Filesystem, identity and integration acquisition
Raw snapshot store	Versioned source evidence and retention
Normalization	Canonical entities and relationships
Graph engine	Inheritance, access paths and what-if reasoning
Materialized index	Fast effective-access and exposure queries
API and UI	Investigation, governance, operations and reporting

Core stack: FastAPI, React + TypeScript, PostgreSQL and OpenTelemetry. Optional enterprise services include Neo4j, OpenSearch, ClickHouse and Valkey. Internal environment variables retain the EIP_* prefix for backward compatibility.

Documentation

• Installation guide
• Support matrix
• Windows VSS scan mode
• Official integration notes
• Enterprise readiness review
• Roadmap
• Changelog

Repository Layout

• backend/ — FastAPI services, collectors, graph engine and tests
• frontend/ — React/TypeScript web interface
• docs/ — support, integration and operational documentation
• deploy/ — reverse-proxy examples
• scripts/ — Windows/Linux build, install, backup and restore tooling

Security and Contributions

Please use the private reporting flow in SECURITY.md for vulnerabilities. Contribution setup and quality requirements are in CONTRIBUTING.md.

GrantPath is available under the Apache-2.0 License.