FileGRC

FileGRC is a zero-dependency Node.js engine for Git-native GRC workspaces. It validates structured JSON records and their Markdown companions, renders a local web app, provides safe CRUD operations, and builds a read-only audit view.

Program Readiness checks management-owned scope, policy adoption, control implementation, and authoritative evidence mapping without requiring an audit record. Audit Readiness starts after CPA engagement and checks the firm-agreed date or period, engagement-specific management documents, operating evidence, and Type 2 population completeness.

The Controls list focuses on implementation and its next action. The Obligations list shows schedule state separately, including proposals, approved schedules, and Policies awaiting activation or their effective date. Enabled work starts when its governing content is effective and a linked Control is implemented.

Most users should create a complete workspace:

npx create-filegrc@latest company-grc

Inside a workspace:

npx filegrc validate
npx filegrc serve
npx filegrc setup --help
npx filegrc build
npx filegrc guide risk-assessment
npx filegrc program-path --next --json
npx filegrc scaffold risk-assessment --title "2026 Annual Risk Assessment"
npx filegrc list risk --json
npx filegrc references risk-example --json
npx filegrc describe risk
npx filegrc search "access review"
npx filegrc evidence-map --json
npx filegrc program-readiness --summary --json
npx filegrc program-readiness --require-ready
npx filegrc audit-readiness audit-id
npx filegrc prepare-audit audit-id
npx filegrc evidence-packet --start 2026-01-01 --end 2026-06-30 --audit audit-id

Upgrade an existing workspace

Package updates may include optional starter Policy and Control revisions. Review them without writing:

npx filegrc policy-library

The command shows an exact diff only when the current text still matches the prior starter default. It skips customized, approved, active, superseded, and retired Policy content. Accept one named proposal revision only with the command printed by the review, which includes --accept, --proposal-revision, and --yes. Acceptance fails if the proposal changed after review. It changes only the listed defaults and does not approve a Policy, activate it, or mark a Control implemented.

The normal runtime uses data model v11. Existing model v10 workspaces start with a read-only preview:

npx filegrc migrate --to-model 11 --preview --json

Review every automatic, review-required, and unsupported item. Model v11 removes the old per-Control implementation approval fields. Owners can record implementation directly, while periodic Control oversight uses one Collection Review at the end of Step 3. Policy, Document, and Training approvals stay independent. Resolve unsupported items before applying the same migration with --yes. The model v11 upgrade guide documents the review.

A model v2 workspace must migrate to v3 first:

npx filegrc migrate --to-model 3 --preview --json

The migration writes one atomic batch, validates model v3, changes no Git history, and is safe to rerun. The model v3 upgrade guide explains every migration class and the review that follows. Apply it before previewing models v4, v5, and v6 in order.

A model v1 workspace must migrate to v2 first:

npx filegrc migrate --to-model 2 --preview --json

Follow the model v2 upgrade guide, then migrate one model version at a time through model v11.

filegrc serve --help prints bind, port, environment, and safety options without starting the server. The editable server prefers 127.0.0.1:8787 and chooses another available port when that port is occupied. Set FILEGRC_HOST, FILEGRC_PORT, or the matching flags when needed. In trunk mode, browser saves synchronize, commit, and push from the authoritative branch. Use --allow-non-authoritative-writes for local development in a task checkout; the override never commits or pushes.

filegrc setup provides the headless equivalent of browser onboarding. Run it without arguments for guided terminal setup, or pass all initial service-boundary fields and a management program goal as flags or a JSON payload. Add --preview to validate and inspect the planned System and Program writes without saving. Add --summary --json for compact agent output. Selecting Type 1 or Type 2 updates the Program goal and selected Systems. Setup does not select Framework records, link Controls, create Evidence Artifacts, or create an Audit record.

filegrc program-path --next --json gives an agent the current step and first action without loading the full lifecycle. Use --summary for compact status across all five steps, --current for the full current-step guide, or no compact flag for every step. filegrc guide <type> repeats the matching page guidance and adds fields, relationship candidates, Markdown slots, and timing for that record type.

filegrc program-readiness reports whether management can start a candidate Type 2 period. Add --summary --json for compact stage counts and next actions, or omit --summary for every readiness item. Use --require-ready in automation. Pass --program PROGRAM_ID when more than one active Program exists. The command does not require an Audit ID or CPA firm.

Step 2 uses one Policies page to review Policies, program Documents, and Training, while keeping their record types separate. Step 3 implements linked requirements, defines schedules as Obligations, and uses filegrc activate-content --scaffold to record the active Person, separate activation date, and revision for approved Documents and Training. Control implementation also checks expected evidence, authoritative source Components, and source readiness. During Step 4, create Evidence only when operation produces a real record or artifact. Keep engagement-scoped terms, management assertions, representation letters, and other Audit Documents in Step 5. Link each one to one Audit and use filegrc activate-documents --audit AUDIT_ID --scaffold after approval.

filegrc obligations shows recurring work and a task-level preview for each Policy Event, including owners, deadlines, and requested proof. filegrc trigger adds the event and all of its Action Items to the Work Queue atomically, then prints the created task IDs and deadlines.

Long-form Markdown lives beside its JSON record. FileGRC derives the Markdown path, so records do not store it.

Headless creates and updates require the { "record": {...}, "content": {...}, "revision": "...", "contentRevisions": {...} } mutation envelope used by the web app. Run filegrc scaffold for a new mutation or filegrc get <id> --mutation before an update; stale record and Markdown writes are rejected. Use filegrc content <type> <id> to read a companion and --write <file|-> to replace it. filegrc guide --json is the compact action and resource index for agents.

Use filegrc attach <evidence-id> <source-file> to copy a fixed evidence file under its record and update filePaths without overwriting an existing attachment.

Use filegrc detach <evidence-id> <attachment-name> --yes for explicit removal. Evidence records with linked local attachments cannot be deleted.

The package requires Node.js 20 or newer. It uses Git for authors, commit timestamps, messages, diffs, and revisions. New workspaces use trunk mode, which fetches and fast-forwards before each browser mutation, validates and commits the saved change, then pushes. Agents and terminal users use Git directly; the FileGRC CLI does not wrap pull, commit, or push.

The editable server has no authentication and binds to loopback by default. Put it behind trusted authentication before exposing it on a network, or publish the read-only static build.

The authoritative data model ships in this package. Import the public Node.js API from filegrc and the model loader from filegrc/model.

Workflow notification contacts

getWorkItems(root, options) returns the same work items as assessWorkflow(root, options).workItems, including stable ownerIds and notificationContacts. Each contact contains personId and optional email from the Person record. notificationContacts(ownerIds, resources) resolves active Team members and chairs and active Appointment holders to active People, deduplicated and sorted by Person ID. Inactive People receive no contact entry. People without email still have a Person ID contact.

Core calculates work and exposes repository contacts. Autopilot manages notification settings and Person-to-Slack links in its database, using Core contact Person IDs to look up destinations.

FileGRC Autopilot

Run your SOC 2 program automatically. FileGRC Autopilot is the optional hosted service for owner reminders and policy-driven escalation.

filegrc automation reports local FileGRC Autopilot configuration. Add --json for the stable contract or --open to open the dashboard, or the setup guide when configuration is unavailable. These commands do not check live service status.

After connecting a repository, the Autopilot webapp offers a reviewable PR adding .filegrc/hosted-automation.json:

{ "version": 1, "connectionId": "opaque-non-secret-id" }

Version 1 accepts exactly these fields. The ID contains 1–128 ASCII letters, digits, underscores, or hyphens and grants no access. A valid marker means configured locally. Billing, access, and delivery health remain authoritative in the webapp. Removing the marker does not disconnect service.

Core builds dashboard links as https://app.filegrc.com/connections/<encoded connectionId>?repository=<encoded owner/repo>. It derives the optional repository hint from one supported GitHub origin URL without contacting GitHub, omitting it when unavailable or ambiguous. The hint grants no authorization. Invalid or unsupported markers produce warnings and leave local workflows available; Core never rewrites the marker.

Track this file in Git. Existing repositories that ignore .filegrc/ should use .filegrc/* and add !.filegrc/hosted-automation.json. Person mappings and delivery policy remain separate files.