Metadata-Version: 2.4
Name: granary-harness
Version: 1.0.1
Summary: Granary agent-security, governance, and privilege containment harness.
Author-email: Max <klasickars@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Tunatroll/granary-harness
Project-URL: Repository, https://github.com/Tunatroll/granary-harness
Project-URL: Documentation, https://github.com/Tunatroll/granary-harness#readme
Keywords: agents,security,mcp,governance,zero-trust
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: requests
Provides-Extra: mcp
Requires-Dist: mcp>=1.27; extra == "mcp"
Provides-Extra: ml
Requires-Dist: torch; extra == "ml"
Requires-Dist: scipy; extra == "ml"

# Granary Harness — Secure GitOps Orchestration & Containment

A secure, GitOps-native multi-agent orchestration loop and zero-trust containment framework. Grounded in the academic **CAID (Centralized Asynchronous Isolated Delegation)** paradigm, Granary coordinates multi-agent fleets asynchronously using private GitHub PRs as an immutable blackboard communications bus—fully isolated by local sandboxing boundaries, credential filters, and an MCP gateway.

---

## 🚀 Day-0 Quickstart (Run the MVP Demo)

Granary is packaged to be extremely lightweight (<5MB) and runs in any terminal in under 30 seconds.

### 1. Installation & Environment Setup
Clone the repository and install dependencies in editable development mode:
```bash
make setup
```

### 2. View Security & Governance Status Dashboard
Run bare `granary` (or `granary status`) to view a beautifully formatted terminal dashboard showing active directory sandboxes, registered agent capabilities, loaded self-healing hooks, and MCP gateway policies:
```bash
.venv/bin/granary
```

### 3. Run the Secure Blackboard Loop Demo (CAID)
Execute our E2E GitOps loop simulation to see how agents coordinate asynchronously, how file containment jails block unauthorized traversal attempts, how **Helix-style self-healing auto-hooks** are dynamically compiled on exceptions, and how **SEDM/TierMem memory evolution** consolidates records on success:
```bash
.venv/bin/python bin/granary-loop-demo.py
```

---

## Key Features

- **Asynchronous GitOps Coordination (CAID)**: Standardizes multi-agent software engineering workflows over Git branches and PRs (as in arXiv:2603.21489), sequentially merging worker commits and resolving workspace conflicts natively.
- **Helix-style "Gene Map" Auto-Hooks**: Intercepts, trace-fingerprints, and registers dynamic recovery hooks on sandbox failures, shielding future loops in under 1ms without LLM overhead.
- **SEDM/TierMem Memory Evolution**: Promotes probation records to active memory via "Verified Write-Back" upon successful PR merges, or quarantines them on task exceptions.
- **Operating Constitution**: Enforces a strict, declarative, five-tier (T0-T4) blast-radius boundary limit for filesystem, LOC edits, token budgets, and path overrides via `agent-constitution.yaml`.
- **Dynamic JIT Privilege Elevation**: Implements `AgentAssertionToken` (AAT) with `agent_owner` and `agent_trust_score` claims, alongside RFC 8693 token exchange payloads and RFC 9449 DPoP sender-constraining validation.
- **Egress & Tunneling Control (ShieldNet)**: Shannon entropy monitoring and rate limiting over DNS queries to identify exfiltration channels and active tunneling attempts.
- **MCP Trust Gateway**: High-fidelity Model Context Protocol tool interceptors, risk-based gating, and human-in-the-loop approvals.

## Project Structure

```
granary-harness/
├── granary/                # Core security modules
│   ├── __init__.py         # Public API (39 fully exported modules)
│   ├── identity.py         # AAT Claims, signatures, and DPoP validation
│   ├── constitution.py     # Operating Constitution and YAML parser
│   ├── readiness.py        # Pre-launch checklists & cold rollbacks
│   ├── adversa.py          # Adversa offline red-teaming
│   ├── mcp_security.py     # MCP tool risk gateways
│   ├── shieldnet.py        # DNS entropy network egress
│   ├── attestation.py      # Nitro enclave attestation
│   └── ...                 # Sandboxing, rollups, self-healing, otel
├── tests/                  # Standalone unittest suites
│   └── test_granary_*.py   # 158 verified unit tests
├── docs/                   # Governance & policy contracts
│   ├── gtm/                # Competitive positioning & matrices
│   ├── agent-constitution.yaml
│   ├── governance-cadence.md
│   └── planning_merge_verification.md
├── pyproject.toml          # Package configuration
├── CLAUDE.md               # Code standards & run commands
└── AGENTS.md               # Autonomous onboarding reference
```

## Setup & Task Automation

Granary includes a standardized local task runner using the project `Makefile`:

-   **Set up standalone environment**: Create `.venv` and install the package in editable development mode:
    ```bash
    make setup
    ```
-   **Run the unit test suite**: Run all 158 tests with verbose reporting:
    ```bash
    make test
    ```
-   **Package compiling**: Compile the project into distributable wheel (`.whl`) and sdist (`.tar.gz`) archives:
    ```bash
    make build
    ```
-   **Pristine cleaning**: Recursively clean caches, bytecode, and packaging/environment folders:
    ```bash
    make clean
    ```

---

## Command-Line Interface (CLI)

The administrative utility is registered natively upon installation as the executable `granary`.

### 1. Constitution Validation
Validate the syntax and autonomy tiers of a declarative agent constitution YAML file:
```bash
granary validate-constitution --path docs/agent-constitution.yaml
```

### 2. Merkle Audit Ledger Management
-   **Export Chain**: Export a mock, cryptographically chained, and redacted compliance ledger:
    ```bash
    granary admin ledger export --work-unit-id "wu_92e8a10f-3a21" --output "./forensics_export.json"
    ```
-   **Verify Chain Integrity**: Scan, recalculate Merkle roots, and verify HSM-signatures over an exported ledger file:
    ```bash
    granary admin ledger verify-chain --input "./forensics_export.json"
    ```

---

## Running Unit Tests

Unit tests are written using Python's built-in, zero-dependency `unittest` module.

To run the complete test suite (158 tests) with no regressions:

```bash
python -m unittest discover -s tests -p "test_granary_*.py" -v
```

---

## MCP Gateway (Cursor / Claude)

Granary exposes a **stdio MCP server** that wraps `McpTrustGateway` for live agent sessions.

### Setup

```bash
make setup   # installs granary-harness[mcp]
```

### Cursor configuration

This repo ships [`.cursor/mcp.json`](.cursor/mcp.json). After setup, restart Cursor or reload MCP servers. You should see **`granary-gateway`** with four tools:

| Tool | Purpose |
|------|---------|
| `granary_authorize_tool` | Risk-tier + scope + JTI replay check before tool execution |
| `granary_approve_pending` | Human approval for T2/T3 actions |
| `granary_validate_redirect` | OAuth redirect URI allowlist check |
| `granary_list_pending` | List queued approval requests |

Run manually:

```bash
granary-mcp
```

Optional custom policy JSON via `GRANARY_MCP_POLICY=/path/to/policy.json`.

---

## Publishing to PyPI

See [`docs/PYPI_RELEASE.md`](docs/PYPI_RELEASE.md) for build, `twine check`, TestPyPI, and production upload steps.

```bash
make build
make publish-check
```
