Metadata-Version: 2.4
Name: grc-lake
Version: 0.3.3
Summary: Open-source, self-hosted GRC engineering on your evidence lake: read-only evidence collection, deterministic control tests, and reproducible assessment exports via console, API, CLI, and MCP.
Author: Mohamed Saad
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/msaad00/grc-lake
Project-URL: Documentation, https://github.com/msaad00/grc-lake/tree/main/docs
Project-URL: Repository, https://github.com/msaad00/grc-lake
Project-URL: Changelog, https://github.com/msaad00/grc-lake/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/msaad00/grc-lake/issues
Keywords: compliance,soc2,nist,fedramp,hipaa,pci-dss,iso27001,grc,devsecops,audit,security,evidence,controls,mcp,agents,data-lake
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: server
Requires-Dist: fastapi>=0.141.1; extra == "server"
Requires-Dist: uvicorn>=0.30; extra == "server"
Requires-Dist: sqlalchemy>=2.0; extra == "server"
Requires-Dist: alembic>=1.13; extra == "server"
Requires-Dist: mako>=1.4.3; extra == "server"
Requires-Dist: psycopg[binary]>=3.1; extra == "server"
Requires-Dist: authlib>=1.3; extra == "server"
Requires-Dist: itsdangerous>=2.2; extra == "server"
Requires-Dist: python3-saml>=1.16; extra == "server"
Requires-Dist: reportlab>=5.0.1; extra == "server"
Requires-Dist: redis>=8.1.0; extra == "server"
Provides-Extra: dev
Requires-Dist: jsonschema>=4.23; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=7.1; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Requires-Dist: mypy>=2.3; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: commitizen>=3.27; extra == "dev"
Requires-Dist: fastapi>=0.141.1; extra == "dev"
Requires-Dist: uvicorn>=0.30; extra == "dev"
Requires-Dist: httpx>=0.28.1; extra == "dev"
Requires-Dist: sqlalchemy>=2.0; extra == "dev"
Requires-Dist: alembic>=1.13; extra == "dev"
Requires-Dist: mako>=1.4.3; extra == "dev"
Requires-Dist: authlib>=1.3; extra == "dev"
Requires-Dist: itsdangerous>=2.2; extra == "dev"
Requires-Dist: python3-saml>=1.16; extra == "dev"
Requires-Dist: reportlab>=5.0.1; extra == "dev"
Requires-Dist: redis>=8.1.0; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Provides-Extra: parquet
Requires-Dist: pyarrow<26,>=23.0.1; extra == "parquet"
Provides-Extra: iceberg
Requires-Dist: pyiceberg[pyarrow]<0.13,>=0.12.0; extra == "iceberg"
Requires-Dist: pyarrow<26,>=23.0.1; extra == "iceberg"
Provides-Extra: analytics
Requires-Dist: duckdb>=1.0; extra == "analytics"
Provides-Extra: bigquery
Requires-Dist: google-cloud-bigquery<4,>=3.45; extra == "bigquery"
Provides-Extra: cloud
Requires-Dist: boto3>=1.34; extra == "cloud"
Requires-Dist: azure-identity>=1.17; extra == "cloud"
Requires-Dist: azure-mgmt-authorization>=4.0; extra == "cloud"
Requires-Dist: azure-mgmt-resource<24,>=23.0; extra == "cloud"
Requires-Dist: google-cloud-asset>=3.20; extra == "cloud"
Requires-Dist: google-cloud-resource-manager>=1.12; extra == "cloud"
Requires-Dist: google-cloud-org-policy>=1.11; extra == "cloud"
Requires-Dist: snowflake-connector-python[pandas]>=4.7.1; extra == "cloud"
Requires-Dist: clickhouse-connect>=0.7; extra == "cloud"
Provides-Extra: kubernetes
Requires-Dist: kubernetes>=36.0.3; extra == "kubernetes"
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.2.0; extra == "mcp"
Provides-Extra: sdk
Requires-Dist: httpx>=0.28.1; extra == "sdk"
Provides-Extra: agents
Requires-Dist: langgraph>=1.2.14; extra == "agents"
Dynamic: license-file

<p align="center">
  <img src="docs/images/grc-lake-capability-header.svg" alt="GRC Lake — collect, evaluate, resolve, and export: read-only evidence from cloud, identity, code, and data sources, evaluated through a common control framework and framework packs." width="100%">

</p>

<p align="center">
  <a href="https://pypi.org/project/grc-lake/"><img src="https://img.shields.io/pypi/v/grc-lake?color=2b7bba&label=PyPI" alt="PyPI version"></a>
  <a href="https://pypi.org/project/grc-lake/"><img src="https://img.shields.io/badge/python-3.11%2B-blue" alt="Python 3.11+"></a>
  <a href="https://github.com/koda-ai-studio/grc-lake/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/koda-ai-studio/grc-lake/ci.yml?branch=main&amp;label=CI" alt="CI status"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue" alt="License: Apache 2.0"></a>
  <a href="https://scorecard.dev/viewer/?uri=github.com/koda-ai-studio/grc-lake"><img src="https://api.scorecard.dev/projects/github.com/koda-ai-studio/grc-lake/badge" alt="OpenSSF Scorecard"></a>
</p>

**Open-source trust operations, on your evidence lake.** Self-hosted GRC
engineering: collect read-only evidence from cloud, identity, code, and existing
security lakes; evaluate it with deterministic, version-pinned control tests;
export snapshots, workpapers, and OSCAL.

<!-- BEGIN README AT A GLANCE -->

- **20 framework packs, 2,252 catalogued requirements (1,965 distinct; FedRAMP Moderate's 287 rows restate NIST SP 800-53 controls),** linked through 96 common safeguards. 1,417 requirements have safeguard mappings; 339 have reviewed mappings and the other 1,078 are proposed.
- **25 read-only source adapters (7 in preview)**, plus OCSF presets for existing security lakes.
- **Fails closed:** missing, stale, or partial evidence never produces a pass, and proposed mappings are not attestable.
- **One engine, four surfaces:** console, REST API, CLI, and MCP server. Agents propose; humans approve.

<!-- END README AT A GLANCE -->

[Quick start](#quick-start) · [Architecture](#architecture) · [Evidence modes](#evidence-modes) ·
[Product tour](#product-tour) · [Self-host](#self-host) · [Frameworks](#frameworks) · [Documentation](#documentation) · [Current coverage](docs/CURRENT_STATE.md) · [Roadmap](ROADMAP.md)

## Quick start

Python 3.11+ on macOS or Linux:

```bash
python -m venv .venv
source .venv/bin/activate
pip install "grc-lake[server]"
grc-lake fixtures load --company golden --out ./lake --rebase-times
grc-lake assessment status --lake ./lake
grc-lake serve --server --allow-insecure-no-auth --lake ./lake --host 127.0.0.1 --port 8787
```

Open [localhost:8787/console/dashboard/](http://127.0.0.1:8787/console/dashboard/).
This local demo uses synthetic data and disables authentication. Use the
[production setup](#self-host) before connecting real evidence. Follow the
[5-minute tutorial](docs/TUTORIAL_5_MIN.md) for the workflow.

<details>
<summary>Docker, source development, or an agent connection</summary>

With Docker Compose v2, use the published release templates:

```bash
git clone --branch v0.3.2 --depth 1 https://github.com/koda-ai-studio/grc-lake.git
cd grc-lake
docker compose up
```

The container is public; no registry login is required. Compose binds the
no-auth demo to loopback. Main currently references the unpublished 0.3.3 image;
use the source-development command below to try the candidate.

From source, with [uv](https://docs.astral.sh/uv/) and Node 22+:

```bash
git clone https://github.com/koda-ai-studio/grc-lake.git
cd grc-lake
uv sync --frozen --extra dev --extra server
make demo-local
```

For MCP over stdio:

```bash
pip install 'grc-lake[mcp]'
GRC_LAKE_LAKE=./lake grc-lake-mcp
```

Read [headless GRC](docs/HEADLESS_GRC.md) for agent credentials and authority.

</details>

> Renamed from TrustOps. See the [upgrade guide](docs/REBRANDING.md) for command aliases, existing volumes and release availability.

The PyPI package is `grc-lake`, the CLI is
`grc-lake`, and the MCP server is `grc-lake-mcp`.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/grc-lake-demo-dashboard-dark.png">
  <img src="docs/images/grc-lake-demo-dashboard.png" alt="GRC Lake overview with framework coverage, priority actions, and evidence freshness" width="100%">
</picture>

_Screens show the bundled synthetic company, captured from 0.3.3 candidate source `9e741ffb` on 2026-10-12, with evidence investigation, the AI model and agent worklist, and shared framework/control identities.
Main can include changes newer than the published package. These screens
demonstrate workflows, not a customer deployment or an audit opinion._

## Architecture

Deploy GRC Lake on your own infrastructure or in the cloud, using a VM,
containers, or Kubernetes. Hosting location, application storage, and evidence
sources are separate choices:

- **Application storage:** filesystem mode uses one writable replica; distributed
  mode uses PostgreSQL and S3-compatible object storage with multiple API replicas
  and workers. Both can run on-premises or in the cloud.
- **Evidence sources:** collect directly from supported systems or read existing
  self-managed and cloud lakes through supported connectors and mappings.

```mermaid
flowchart LR
  Sources["Sources<br/>cloud · identity · code · existing lakes"]
  Collect["Collect<br/>read-only · normalize · hash"]
  Evaluate["Evaluate<br/>deterministic, version-pinned control tests"]
  Generations["Assessment generations<br/>filesystem or PostgreSQL + S3<br/>hash-verified, published atomically"]
  Snapshots["Snapshots<br/>hash-chained ledger"]
  API["REST API"]
  Console["Console"]
  MCP["MCP server"]
  CLI["CLI"]
  Sources --> Collect --> Evaluate --> Generations --> Snapshots
  Generations --> API
  API --> Console
  API --> MCP
  Generations -. filesystem mode .-> CLI
  Generations -. filesystem mode .-> MCP
```

Connectors only read from source systems. Deterministic rules own every result;
agents can propose changes but do not decide them. Each run publishes a new
generation whose artifact hashes are verified before it becomes current, and
each snapshot records its predecessor's hash. CLI assessment commands use a
filesystem lake; `cluster` commands manage distributed operation. MCP reads a
filesystem lake or calls the authenticated API; distributed deployments require
API mode. See [architecture](docs/ARCHITECTURE.md) and
[distributed deployment](docs/DISTRIBUTED.md).

Queued evaluations and snapshots retain tenant-scoped result receipts, allowing
an authorized caller to inspect a committed result after a lost worker response.
Operation lists support cursor pagination; queue admission, response storage and
collector retries have explicit limits. See the
[assessment application contract](docs/ASSESSMENT_APPLICATION_CONTRACT.md) for
failure codes, retry guidance and the limits of local recovery.

Distributed operators can inspect committed objects without trusting replica
caches and follow the [backup and restore runbook](docs/runbooks/BACKUP_RESTORE.md).
The built-image qualification restores PostgreSQL and S3 objects into fresh stores
and checks evidence, snapshot chains, operation receipts and tenant isolation.
This synthetic single-host drill does not establish production recovery times
or storage failover.

## Evidence modes

Both modes feed the same evaluation engine, assessments, and review workflows.

| Mode              | Start with                                                                        | How it works                                                                                                                                                                                                                                                                                                 |
| ----------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Existing lake** | Logs, security events, and evidence already ingested into your lake or warehouse. | Read-only readers query existing tables; [lake mappings](docs/BRING_YOUR_OWN_LAKE.md) translate their fields into evidence. Snowflake, ClickHouse, Databricks, BigQuery, and Iceberg/Parquet readers include OCSF presets for Amazon Security Lake. S3 evidence and SIEM exports are also supported sources. |
| **Ingest**        | Cloud, identity, code, endpoint, and SaaS systems; no existing lake required.     | Read-only connectors collect evidence into storage you own. Sources include AWS, Azure, GCP, GitHub, GitLab, Okta, Google Workspace, Jira, Intune, and HR systems.                                                                                                                                           |

**Already have a lake?** Start with [bring your own lake](docs/BRING_YOUR_OWN_LAKE.md).
**Collecting new evidence?** Start with [connector setup](docs/CONNECTOR_CREDENTIALS.md).
Lake mappings are experimental; preview and live-provider qualification vary by
reader. See the [connector catalog](docs/CONNECTORS.md) for status. Compatibility
depends on the supported reader, schema mapping, and access configuration;
arbitrary lake backends are not automatically supported. Existing-lake readers
preserve the source system and materialize assessment evidence into GRC Lake's
configured application storage. A source warehouse does not replace that storage.

## Product tour

| Workflow     | What you get                                                                     |
| ------------ | -------------------------------------------------------------------------------- |
| **Collect**  | Source evidence with identity, timestamps, hashes, and collection status.        |
| **Evaluate** | Deterministic results pinned to a catalog and evidence generation.               |
| **Resolve**  | Assigned findings, follow-up verification, and independently reviewed decisions. |
| **Export**   | Snapshots, workpapers, OSCAL, and scoped, revocable auditor shares.              |

The console groups navigation by workflow, with category icons and a top-mounted
collapse control. The compact rail opens each category's pages on demand and remembers
your preference. Findings and framework drawers resize
and separate assessment, evidence, triage, and history into focused views.
Lists use pagination; source operations have a focused dashboard view with
clickable provider marks and source-specific evidence links. A compact vendor
review summary leads to the dedicated Vendor risk workspace. Audit room leads
with observed gaps and next actions; Trust center separates scoped sharing from
active-link management. Framework identities, control-family icons, and provider marks
appear inside the console as well as in this tour. The graph keeps selected-node
details beside large icon-led nodes. [Evidence investigation](docs/INVESTIGATION_GRAPH.md)
connects exact records to controls, CCF safeguards, environments, repository context,
findings, and explicitly linked vendor assessments. Depth and layer controls keep
local neighborhoods bounded. Expand the workspace for more room, drill into a selected
node, and roll up to the preceding view; mapping review stays separate from assessment.

Connector setup separates configuration, access testing, first sync, and result review.
Cloud authorization separates provider preparation from target configuration. Required
fields and permissions remain visible; advanced identity settings and schedules are
progressively disclosed. Access reviews open on pending decisions and explain the next
action without implying that recording a decision changes provider access.

### Know what is covered

Framework coverage separates assessed controls, missing evidence, and unreviewed
mappings. A passing sample does not establish full framework compliance.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/grc-lake-demo-frameworks-dark.png">
  <img src="docs/images/grc-lake-demo-frameworks.png" alt="Framework roster showing evidence coverage and assessment results" width="100%" loading="lazy">
</picture>

### Follow evidence to a decision

Inspect the source, freshness, and affected controls before assigning a finding.
Closing a task requires fresh verification; approval actions require an eligible
human session. Agents can collect, explain, and propose work.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/grc-lake-demo-evidence-dark.png">
  <img src="docs/images/grc-lake-demo-evidence.png" alt="Evidence workspace with freshness and source lineage" width="100%" loading="lazy">
</picture>

<details>
<summary>More screens: setup, graph, AI governance, sources, access reviews, remediation, audit room, and mobile</summary>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/grc-lake-demo-connector-setup-dark.png">
  <img src="docs/images/grc-lake-demo-connector-setup.png" alt="Provider setup with required fields, permissions, and bounded steps" width="100%" loading="lazy">
</picture>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/grc-lake-demo-graph-dark.png">
  <img src="docs/images/grc-lake-demo-graph.png" alt="Record-level evidence graph with large icons and a selected control inspector" width="100%" loading="lazy">
</picture>

AI governance lists recorded models and agents with owners, environments, signals,
and next actions. Inspect an asset to follow its exact control links or open its
filtered evidence. Observed controls and recorded lineage remain distinct from
freshly evaluated controls and complete lineage.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/grc-lake-demo-ai-governance-dark.png">
  <img src="docs/images/grc-lake-demo-ai-governance.png" alt="AI model and agent worklist with governance signals and next actions" width="100%" loading="lazy">
</picture>

![Source operations with provider marks and paginated evidence sources](docs/images/grc-lake-demo-sources.png)
![User access review workspace](docs/images/grc-lake-demo-access-reviews.png)

Access reviews scope and seed campaigns from collected identity evidence. Human
SSO reviewers record decisions and rationale; recording a revocation decision
does not change access at the provider. Vendor assessment status describes the
recorded review, not complete vendor coverage or certification.

![Remediation workspace](docs/images/grc-lake-demo-remediation.png)
![Audit room priorities and evaluated framework scope](docs/images/grc-lake-demo-audit-room.png)
<img src="docs/images/grc-lake-demo-ai-governance-mobile.png" alt="AI governance worklist on a narrow screen" width="390" loading="lazy">
<img src="docs/images/grc-lake-demo-overview-mobile.png" alt="GRC Lake overview on a narrow screen" width="390" loading="lazy">

</details>

## Self-host

Use [Docker or Helm](deploy/README.md), configure [SSO and scoped credentials](docs/SERVER_AUTH.md),
and choose the [storage and writer topology](docs/runbooks/HA_READ_REPLICAS.md).
See the [deployment and lake compatibility matrix](docs/DEPLOYMENT.md#deployment-and-lake-compatibility)
for hosting, storage, source-reader and export support.
Evidence stays in storage you operate; data leaves through the connectors, sinks,
and model integrations you configure.

- **Local mode:** one writable replica with a local JSONL lake and SQLite or PostgreSQL.
- **Distributed mode:** multiple API replicas and tenant workers share PostgreSQL
  and S3-compatible object storage, with private scratch space and fenced publication.
  Enable it explicitly using the [distributed deployment guide](docs/DISTRIBUTED.md).
  A single tenant evaluation still runs on one worker; production capacity and
  provider failover require deployment-specific qualification.
- **Warehouse exports** have separate setup and qualification requirements.
  See [data flow](docs/DATA_FLOW.md).
- **Authentication is required for production.** The loopback demo is a separate
  setup. Human approval, tenant isolation, and read-only auditor access are
  enforced at the API boundary.
- **Retain evidence deliberately.** Use the [operations guide](docs/OPERATIONS_CONTRACTS.md)
  for generation archival, history costs, and external integrity checkpoints.

See the [connector catalog](connectors/catalog.json) for implementation and preview
status, and [credential setup](docs/CONNECTOR_CREDENTIALS.md) for each source.

### Verify a release

Wheels and sdists carry SLSA build provenance, and each GitHub release attaches
a CycloneDX SBOM of the locked runtime dependencies:

```bash
gh release download v0.3.2 -R koda-ai-studio/grc-lake -p '*.whl'
gh attestation verify grc_lake-0.3.2-py3-none-any.whl -R koda-ai-studio/grc-lake
```

## Frameworks

Common safeguards connect source evidence to framework requirements. Proposed
crosswalks remain review work; reviewed mappings are version-pinned and still
need applicable evidence. The legacy `fedramp-moderate` pack represents the
NIST 800-53B Moderate foundation, not a complete FedRAMP authorization package.

<details>
<summary>Generated catalog coverage and control families</summary>

<!-- BEGIN README CCF SUMMARY -->

**20 framework packs · 96 reusable safeguards · 21 control families in 10 categories · 2,252 catalogued requirements (1,965 distinct; FedRAMP Moderate's 287 rows restate NIST SP 800-53 controls).** 2 more registry entries are planned or superseded and hold no requirements.

1,417 requirements have safeguard mappings; **339 have reviewed mappings**. Catalog coverage and evaluated customer posture are separate measures.

Control families by category:

- **Governance and risk:** Risk management · Governance
- **Identity and access:** Identity and access
- **Data protection and privacy:** Data protection · Privacy
- **Secure engineering:** Change management · Secure development · Secure architecture
- **Infrastructure security:** Configuration management · Vulnerability management · Network security
- **Detection and response:** Detection · Audit logging · Incident response
- **Resilience and integrity:** Availability and recovery · System maintenance · Processing integrity
- **Third-party and supply chain:** Third-party risk
- **People and physical:** People security · Physical security
- **AI governance:** AI governance

<!-- END README CCF SUMMARY -->

</details>

[Framework packs](docs/FRAMEWORK_PACKS.md) · [Coverage catalog](docs/FRAMEWORK_COVERAGE.md) ·
[Common controls](docs/COMMON_CONTROL_FRAMEWORK.md) ·
[Control families screen](docs/images/grc-lake-demo-control-families.png) ·
[Crosswalk screen](docs/images/grc-lake-demo-crosswalk.png)

## Evidence boundaries

Missing, stale, blocked, or partial evidence cannot establish a passing control.
Inventory observations establish presence, not the effectiveness of a control.
Exceptions and compensating measures are review records, not automatic passes.
Scoped risk decisions retain evidence, expiry and independent review; extensions
require a new approval. See [governance](docs/GOVERNED_REMEDIATION.md).

Local fixture tests, exported hashes, and screenshots do not establish live
provider qualification, production capacity, certification, or customer
adoption. An independently retained checkpoint is needed to detect a complete
local history replacement. See [evidence recovery](docs/EVIDENCE_RECOVERY.md) and
[audit readiness](docs/AUDIT_READINESS.md).

## Documentation

| Need                             | Start here                                                                                           |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Try a complete workflow          | [5-minute tutorial](docs/TUTORIAL_5_MIN.md)                                                          |
| Understand the design            | [Architecture](docs/ARCHITECTURE.md) · [Data model](docs/DATA_MODEL.md) · [All docs](docs/README.md) |
| Deploy and authenticate          | [Deployment](deploy/README.md) · [Server auth](docs/SERVER_AUTH.md)                                  |
| Understand storage and retention | [Data flow](docs/DATA_FLOW.md) · [Operations](docs/OPERATIONS_CONTRACTS.md)                          |
| Integrate an agent               | [Headless GRC](docs/HEADLESS_GRC.md) · [Agent skills](docs/api/AGENT_SKILLS.md)                      |
| Evaluate audit evidence          | [Audit readiness](docs/AUDIT_READINESS.md) · [Evidence recovery](docs/EVIDENCE_RECOVERY.md)          |
| Contribute                       | [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Trust boundaries](docs/THREAT_MODEL.md) |

## Develop

```bash
uv sync --frozen --extra dev --extra server --extra mcp
uv run pytest -q
uv run pre-commit run --all-files
npm --prefix app/web ci
npm --prefix app/web run build
```

Regenerate the header and catalog counts with `make readme-header`. Rebuild the
synthetic demo and recapture its light, dark, and mobile screens with
`make demo-screenshots-full` (requires Playwright Chromium). License: [Apache 2.0](LICENSE).
