Workspace Trust Auditor

Read-only ChatGPT App and MCP server for auditing developer workspaces.

Turns local project inventory, dependency posture, secret-risk signals, provenance metadata, and next-app recommendations into a reviewable report. The dashboard renders an inspectable workspace map and a transparent audit-run ledger that can be published to ORI when an endpoint is configured.

Documentation

• Plain-English Overview
• CLI Reference
• API Reference
• MCP Setup Guide
• Visual Diffs
• CI/CD Agent Instructions

What It Does

• Detects local repositories, stacks, manifests, git status, and registry entries.
• Summarizes security posture without exposing raw secrets.
• Maps projects to evidence paths, attribution, and provenance completeness.
• Recommends next app opportunities by evaluating repo viability, health, marketability, safety, uniqueness, and readiness.
• Serves a local dashboard with map inspection and provides MCP tools for ChatGPT.
• Synthesizes workspace data into metaphoric narratives (city, ecosystem, factory) using the Storyteller lens.
• Publishes structured audit-run observations and canvas interactions to ORI when ORI_BASE_URL is set.
• Supports simulation mode (--simulate) for testing decision layers without scanning real files.

Quick Start (Terminal)

# Install dependencies
npm install

# Run a workspace inventory scan
npm run cli -- inventory --root /path/to/workspace --format summary

# Run a full audit report (inventory + security + provenance + recommendation)
npm run cli -- report --root /path/to/workspace --format summary

# Run the web dashboard (http://127.0.0.1:8787)
npm start

# Run the MCP server over stdio
npm run mcp

# Run full test coverage (Node built-in coverage report)
npm run coverage

Common flags:

| Flag | What it does | |------|-------------| | --root <path> | Workspace root to scan (default: WTA_ROOT env or /home/irfankabir) | | --format json\|summary | Output format — structured JSON or human-readable summary | | --max-depth <n> | How deep to walk looking for git repos | | --max-files <n> | Cap on files scanned for security patterns | | --simulate <scenario> | Return synthetic data instead of scanning; output is tagged simulated: true |

See CLI Reference for the full flag list and all commands.

Available Commands

| Command | Description | |---------|-------------| | inventory | Repository, stack, manifest, git status, and registry coverage | | security | Redacted dangerous-code and secret-risk posture | | provenance | Registry completeness and attribution output | | recommend | Ranked next-app candidates | | storyteller | Metaphoric workspace narrative (city, ecosystem, factory) | | report | Combined inventory + security + provenance + recommendation | | map | Full report plus spatial map, audit ledger, and ORI delivery status | | model | Structured command and output schemas | | overview | Themed operation groups (server, CLI, MCP, UI surfaces) | | simulate | Interactive scenario catalog | | dependencies | Lockfile scan and dependency posture |

Server Endpoints

| Endpoint | Description | |----------|-------------| | GET /health | Health check | | GET /api/model | Command input/output schemas | | GET /api/overview | Operation groups by theme | | GET /api/simulator | Simulator scenario catalog | | GET /api/report | Combined audit report | | GET /api/map | Full workspace map with ledger | | GET /api/dependencies | Dependency posture | | POST /api/ori/interaction | Forward a canvas interaction to ORI |

MCP Tools

scan_inventory · security_summary · provenance_report · recommend_next_app · diff_inventory · summarize_workspace_map · storyteller_synthesize · publish_ori_interaction · dependency_review · narrate_workspace · operator_role · renderer_query

Core audit tools do not mutate scanned repositories. publish_ori_interaction is the only write path.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | WTA_ROOT | /home/irfankabir | Default workspace root for all scans | | WTA_REGISTRY | $WTA_ROOT/PROJECT_REGISTRY.yaml | Path to the project registry | | WTA_ALLOWED_ROOTS | Value of WTA_ROOT | Colon-separated list of allowed scan roots. Requests for paths outside this list are rejected (403). | | ORI_BASE_URL | (unset) | ORI endpoint base URL. ORI delivery is disabled when unset. | | ORI_INGEST_PATH | /observations | ORI ingest path. Must be a clean absolute path with no .. or query strings. | | WTA_ATTRIBUTION_AUTHOR | Irfan Kabir | Canonical author name used in provenance checks | | WTA_ATTRIBUTION_KNOWN_AS | Prince | Canonical alias used in provenance checks | | WTA_ATTRIBUTION_SIGNATURE | Built by Prince (Irfan Kabir) | Canonical attribution signature | | PORT | 8787 | Web server port |

Security Posture

• No shell interpolation anywhere in the scan pipeline.
• Repository mutation is not exposed — policy.repositoryMutationAllowed: false on every report.
• Secret findings are redacted before output; raw values are never returned.
• Scan root is validated against WTA_ALLOWED_ROOTS before any filesystem traversal.
• Simulated responses are tagged simulated: true at the top level so callers can detect them.
• External dependency audits are flagged as a coverage gap unless explicitly supplied by the caller.

Attribution

Built by Prince (Irfan Kabir) Canonical identity source: /home/irfankabir/IDENTITY.md