create-filegrc 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -2
- package/package.json +1 -1
- package/src/cli.js +2 -0
- package/src/defaults.js +1 -1
- package/src/index.js +22 -8
- package/template/AGENTS.md +54 -14
- package/template/README.md +39 -16
- package/template/WORKSPACE.md +41 -0
- package/template/data/AGENTS.md +7 -5
- package/template/data/action-items/AGENTS.md +2 -2
- package/template/data/audits/AGENTS.md +12 -1
- package/template/data/evidence/AGENTS.md +3 -1
- package/template/data/obligation-events/AGENTS.md +2 -2
- package/template/data/obligations/AGENTS.md +2 -1
- package/template/data/people/person-independent-approver.json +3 -4
- package/template/data/policies/AGENTS.md +3 -1
- package/template/data/policies/policy-information-security.md +3 -3
- package/template/data/renderer.json +2 -1
- package/template/data/risk-assessments/AGENTS.md +1 -1
- package/template/data/systems/system-filegrc-program-repository.md +1 -1
- package/template/docs/filegrc-audit.png +0 -0
- package/template/docs/filegrc-home.png +0 -0
- package/template/package.json +1 -1
- package/template-parameters.json +4 -0
package/README.md
CHANGED
|
@@ -9,10 +9,12 @@ npm run validate
|
|
|
9
9
|
npm run serve
|
|
10
10
|
```
|
|
11
11
|
|
|
12
|
-
Setup asks for the company name, the initial policy owner, and a security contact email. The generated private project includes a starter Security program, policy-driven
|
|
12
|
+
Setup asks for the company name, the initial policy owner, and a security contact email. The generated private project includes a starter Security program, Program Readiness, a policy-driven Work Queue, Policy Events that add linked tasks, later audit preparation, evidence packets, and one dependency: `filegrc`.
|
|
13
13
|
|
|
14
|
-
Generated workspaces also include layered `AGENTS.md` instructions and model-driven headless commands.
|
|
14
|
+
Generated workspaces also include layered `AGENTS.md` instructions and model-driven headless commands. `filegrc program-path` gives agents the same six steps, exact page guidance, current status, and next actions shown in the renderer. Agents can define program scope, approve policies, implement controls, test External Evidence, complete policy work, trigger event tasks, and prepare later audit packets through the same domain functions used by the renderer.
|
|
15
15
|
|
|
16
16
|
Git is initialized when needed. The browser can create local commits before a remote is configured.
|
|
17
17
|
|
|
18
|
+
Creation output reports the resolved FileGRC version, whether installation ran, and whether the target joined an existing Git worktree or received a new repository.
|
|
19
|
+
|
|
18
20
|
Use `npx create-filegrc@latest --help` for non-interactive options.
|
package/package.json
CHANGED
package/src/cli.js
CHANGED
|
@@ -7,6 +7,8 @@ export async function runCli(argv = process.argv.slice(2)) {
|
|
|
7
7
|
if (options.version) return printVersion();
|
|
8
8
|
const result = await createFileGRC({ target, ...options });
|
|
9
9
|
console.log(`Created ${result.target}`);
|
|
10
|
+
console.log(`FileGRC ${result.engineVersion}: ${result.install === "installed" ? "installed" : "installation skipped"}`);
|
|
11
|
+
console.log(`Git: ${result.gitMode === "existing-worktree" ? "joined existing worktree" : "initialized new repository"}`);
|
|
10
12
|
console.log("");
|
|
11
13
|
console.log(` cd ${result.target}`);
|
|
12
14
|
if (options.install === false) console.log(" npm install");
|
package/src/defaults.js
CHANGED
|
@@ -70,7 +70,7 @@ const controls = [
|
|
|
70
70
|
title: "Security governance",
|
|
71
71
|
statement: "Management assigns security responsibilities, and a reviewer who is separate from the policy owner and control operators independently reviews the program, risks, incidents, findings, policy approvals, and overdue work at least quarterly.",
|
|
72
72
|
requirements: ["CC1.1", "CC1.2", "CC1.3", "CC1.5"],
|
|
73
|
-
activity: "Assign an
|
|
73
|
+
activity: "Assign an independent reviewer who is separate from program ownership and record quarterly oversight decisions, approvals, and actions.",
|
|
74
74
|
controlType: "preventive",
|
|
75
75
|
operationMode: "manual",
|
|
76
76
|
frequency: "Quarterly",
|
package/src/index.js
CHANGED
|
@@ -22,6 +22,7 @@ export async function createFileGRC(options = {}) {
|
|
|
22
22
|
...prompted,
|
|
23
23
|
effective_date: options.effectiveDate ?? new Date().toISOString().slice(0, 10),
|
|
24
24
|
project_name: normalizePackageName(basename(target)),
|
|
25
|
+
filegrc_version: engineVersion,
|
|
25
26
|
filegrc_version_range: `^${engineVersion}`
|
|
26
27
|
};
|
|
27
28
|
|
|
@@ -30,13 +31,21 @@ export async function createFileGRC(options = {}) {
|
|
|
30
31
|
await renderTemplate(target, parameterConfig, values);
|
|
31
32
|
await writeBaselineRecords(target, values.effective_date);
|
|
32
33
|
|
|
33
|
-
|
|
34
|
+
const installed = options.install !== false;
|
|
35
|
+
if (installed) {
|
|
34
36
|
await run("npm", ["install", "--ignore-scripts"], target);
|
|
35
37
|
} else {
|
|
36
38
|
await writeMinimalLockfile(target, values.project_name, values.filegrc_version_range);
|
|
37
39
|
}
|
|
38
|
-
|
|
39
|
-
|
|
40
|
+
const joinedExistingWorktree = await isInsideGitWorktree(target);
|
|
41
|
+
if (!joinedExistingWorktree) await run("git", ["init"], target);
|
|
42
|
+
return {
|
|
43
|
+
target,
|
|
44
|
+
values,
|
|
45
|
+
engineVersion,
|
|
46
|
+
install: installed ? "installed" : "skipped",
|
|
47
|
+
gitMode: joinedExistingWorktree ? "existing-worktree" : "initialized"
|
|
48
|
+
};
|
|
40
49
|
}
|
|
41
50
|
|
|
42
51
|
export async function resolveFileGRCVersion(explicitVersion) {
|
|
@@ -167,9 +176,11 @@ async function renderTemplate(target, parameterConfig, values) {
|
|
|
167
176
|
|
|
168
177
|
async function templateDestinationPaths() {
|
|
169
178
|
const template = join(packageRoot, "template");
|
|
170
|
-
return (await collectFiles(template)).
|
|
179
|
+
return (await collectFiles(template)).flatMap((source) => {
|
|
171
180
|
const templatePath = relative(template, source);
|
|
172
|
-
|
|
181
|
+
if (templatePath === "README.md") return [];
|
|
182
|
+
if (templatePath === "WORKSPACE.md") return ["README.md"];
|
|
183
|
+
return [templatePath === "gitignore" ? ".gitignore" : templatePath];
|
|
173
184
|
});
|
|
174
185
|
}
|
|
175
186
|
|
|
@@ -177,7 +188,10 @@ async function copyTemplate(target) {
|
|
|
177
188
|
const template = join(packageRoot, "template");
|
|
178
189
|
for (const source of await collectFiles(template)) {
|
|
179
190
|
const templatePath = relative(template, source);
|
|
180
|
-
|
|
191
|
+
if (templatePath === "README.md") continue;
|
|
192
|
+
const destinationPath = templatePath === "WORKSPACE.md"
|
|
193
|
+
? "README.md"
|
|
194
|
+
: templatePath === "gitignore" ? ".gitignore" : templatePath;
|
|
181
195
|
const destination = join(target, destinationPath);
|
|
182
196
|
await assertNoSymlinkComponents(target, destinationPath);
|
|
183
197
|
await mkdir(dirname(destination), { recursive: true });
|
|
@@ -202,13 +216,13 @@ async function collectFiles(directory) {
|
|
|
202
216
|
async function writeMinimalLockfile(target, name, versionRange) {
|
|
203
217
|
const lock = {
|
|
204
218
|
name,
|
|
205
|
-
version: "0.
|
|
219
|
+
version: "0.2.0",
|
|
206
220
|
lockfileVersion: 3,
|
|
207
221
|
requires: true,
|
|
208
222
|
packages: {
|
|
209
223
|
"": {
|
|
210
224
|
name,
|
|
211
|
-
version: "0.
|
|
225
|
+
version: "0.2.0",
|
|
212
226
|
dependencies: { filegrc: versionRange }
|
|
213
227
|
}
|
|
214
228
|
}
|
package/template/AGENTS.md
CHANGED
|
@@ -12,11 +12,13 @@ Do not guess a resource type, field name, enum value, relationship, or file path
|
|
|
12
12
|
|
|
13
13
|
```sh
|
|
14
14
|
npx filegrc guide --json
|
|
15
|
+
npx filegrc program-path --json
|
|
15
16
|
npx filegrc guide risk-assessment --json
|
|
16
17
|
npx filegrc list person --json
|
|
18
|
+
npx filegrc program-readiness --json
|
|
17
19
|
```
|
|
18
20
|
|
|
19
|
-
The
|
|
21
|
+
`program-path` gives agents the same six-step order, exact page Instructions, Use, Policy Basis, commands, current state, and next actions shown in the renderer. The general guide lists every supported action and record type. A type guide repeats that page guidance and adds timing, required and conditional fields, current relationship candidates, JSON location, and Markdown slots.
|
|
20
22
|
|
|
21
23
|
For a new record, generate a mutation envelope:
|
|
22
24
|
|
|
@@ -93,7 +95,7 @@ Headless agents get the same protection by exporting an edit payload with `fileg
|
|
|
93
95
|
|
|
94
96
|
`data/renderer.json` stores committed renderer preferences. New workspaces set `showOnboarding` to `true`. Completing or skipping onboarding sets it to `false`; the app does not commit that change.
|
|
95
97
|
|
|
96
|
-
Onboarding explains the file and Git workflow,
|
|
98
|
+
Onboarding explains the file and Git workflow, the program path, policy obligations, and Policy Events before covering report types and the final audit stage. It then collects the initial service boundary, owner, business criticality, highest data classification, internet exposure, and optional program goal. It creates or updates a `system` record and stores the management goal and program scope on `workspace`. Selecting Type 1 or Type 2 does not create an audit engagement. Completing onboarding opens the Step 1 overview so the user can confirm the starter people and oversight team, criteria, commitments, vendors, and systems before approving policies.
|
|
97
99
|
|
|
98
100
|
The renderer is optional. Agents may set `showOnboarding` to `false` and maintain all records headlessly. Restart onboarding from Repository when useful. Read-only builds never run it.
|
|
99
101
|
|
|
@@ -105,15 +107,15 @@ The generated workspace starts with the SOC 2 Security category:
|
|
|
105
107
|
- The 33 Common Criteria reference IDs from CC1.1 through CC9.2, without the licensed criteria text
|
|
106
108
|
- The nine Description Criteria reference IDs from DC1 through DC9, without the licensed criteria text
|
|
107
109
|
- Planned controls mapped to those references and the included policies
|
|
108
|
-
- A security and risk oversight team chaired by an
|
|
110
|
+
- A security and risk oversight team chaired by an independent reviewer who may be internal or external
|
|
109
111
|
- Recurring obligations for the reviews, scans, tests, training, and meetings required by the included policies
|
|
110
112
|
- A default 5x5 risk method and Public, Internal, Confidential, and Restricted data classifications
|
|
111
113
|
|
|
112
|
-
Treat every planned control as a proposal until its owner, scope,
|
|
114
|
+
Treat every planned control as a proposal until its owner, actual procedure in Record Markdown, system scope, cadence, authoritative evidence sources, implementation date, and mappings match actual practice. For a control linked to FileGRC obligations, every non-retired Work Queue schedule must be enabled and its governing policies effective. Marking the control implemented starts eligible schedules. Do not mark a control implemented because a policy describes it. Add Availability, Processing Integrity, Confidentiality, or Privacy criteria only when they are in scope.
|
|
113
115
|
|
|
114
|
-
The recurring obligations mirror the fixed cadences in the starter policies. Update the policy, control, and obligation together when an approved cadence changes. Create separate completion records, such as meetings, reviews, scans, tests, exercises, and attestations, for each period.
|
|
116
|
+
The recurring obligations mirror the fixed cadences in the starter policies. They remain proposals until every governing policy is active and effective and, when they name controls, at least one linked control is implemented. Update the policy, control, and obligation together when an approved cadence changes. Create separate completion records, such as meetings, reviews, scans, tests, exercises, and attestations, for each period.
|
|
115
117
|
|
|
116
|
-
## Policy
|
|
118
|
+
## Work Queue and Policy Events
|
|
117
119
|
|
|
118
120
|
Run the same obligation planner used by the web app:
|
|
119
121
|
|
|
@@ -122,7 +124,9 @@ npx filegrc obligations --json
|
|
|
122
124
|
npx filegrc obligations --from 2026-01-01 --through 2026-12-31 --complete --json
|
|
123
125
|
```
|
|
124
126
|
|
|
125
|
-
|
|
127
|
+
Work Queue includes recurring obligations, Policy Event tasks, and every other open Action Item. Create an Action Item only when follow-up from a Finding, Risk, Incident, review, test, meeting, Exception, or request needs its own assignee, deadline, and completion proof. Point `sourceResourceId` to the record that produced the task. Use that source record’s Markdown for the report and observations.
|
|
128
|
+
|
|
129
|
+
A calendar obligation’s recurrence anchor starts its first allowed cycle. Unless `window` narrows that range, completion is allowed from the cycle start through the day before the next cycle, and the item becomes overdue on the next cycle’s first day. Use **Record work** in Work Queue, or create and link a completion atomically with:
|
|
126
130
|
|
|
127
131
|
```sh
|
|
128
132
|
npx filegrc complete obligation-id completion-record.json
|
|
@@ -130,14 +134,14 @@ npx filegrc complete obligation-id completion-record.json
|
|
|
130
134
|
|
|
131
135
|
Keep prior completion links because the planner matches each dated record to its own period.
|
|
132
136
|
|
|
133
|
-
Event obligations are templates. Do not mark a template complete or replace it for each occurrence.
|
|
137
|
+
Event obligations are templates. Do not mark a template complete or replace it for each occurrence. Use Trigger Work on Step 5 or run:
|
|
134
138
|
|
|
135
139
|
```sh
|
|
136
140
|
npx filegrc trigger person-started --occurred-on 2026-07-25 --subject person-new-worker --json
|
|
137
141
|
npx filegrc trigger person-ended --occurred-at 2026-07-25T16:30:00-05:00 --subject person-departing-worker --json
|
|
138
142
|
```
|
|
139
143
|
|
|
140
|
-
The command creates one `obligation-event` and its
|
|
144
|
+
Run `npx filegrc obligations` first to preview every task, owner, deadline, and requested proof for each available Policy Event. The trigger command creates one `obligation-event` and adds its full set of Action Items to the Work Queue in a single validated write. Its success output names the event, task count, task IDs, and deadlines. Hour-based deadlines require an RFC 3339 event timestamp so an immediate or 24-hour cutoff is exact. Day-based deadlines use the event’s calendar date. Link the requested completion resources and evidence to each action item, then mark the actions done and the event complete. Every generated action has a cutoff. FileGRC applies a 30-day deadline when a custom event obligation omits one.
|
|
141
145
|
|
|
142
146
|
Complete an event action and link its new proof in one validated write:
|
|
143
147
|
|
|
@@ -159,9 +163,34 @@ npx filegrc content risk-assessment risk-assessment-2026 --write updated-assessm
|
|
|
159
163
|
|
|
160
164
|
Run `filegrc guide <type>` to get slot names. Policies use `content`, meetings use `agenda` and `minutes`, and implicit long-form work uses `record`. FileGRC derives the path and rejects content that does not belong to the record.
|
|
161
165
|
|
|
166
|
+
## Program readiness and the candidate period
|
|
167
|
+
|
|
168
|
+
Prepare the management program before creating an audit engagement:
|
|
169
|
+
|
|
170
|
+
```sh
|
|
171
|
+
npx filegrc program-readiness
|
|
172
|
+
npx filegrc program-readiness --require-ready --json
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
The Evidence Ready gate requires:
|
|
176
|
+
|
|
177
|
+
1. A management goal, selected systems, criteria, and controls.
|
|
178
|
+
2. Active policies with completed text, separate management approval, real approval and effective dates, and linked controls.
|
|
179
|
+
3. Implemented controls with an owner, actual procedure, scope, cadence, evidence source, mappings, implementation date, and every eligible linked Work Queue schedule running.
|
|
180
|
+
4. Active authoritative systems with evidence source roles, access owners, and repeatable extraction instructions in Record Markdown.
|
|
181
|
+
5. A verified `test-export` or `test-capture` evidence record for each selected control family that relies on evidence from outside FileGRC.
|
|
182
|
+
|
|
183
|
+
Completing onboarding creates draft External Evidence records only for evidence that must come from other systems and does not already have a dedicated Step 5 record. FileGRC-managed records, such as risk assessments, meetings, vendor reviews, attestations, vulnerability scans, penetration tests, backup tests, exercises, exceptions, and findings, do not need a separate collection test. Put any fixed external artifact in an External Evidence record and link it from the operating record. For each generated draft, choose its authoritative source System, attach or reference the real result, record its collector and classification, then have another person verify it. Run `npx filegrc evidence-test-drafts` to create any drafts needed after the control set changes.
|
|
184
|
+
|
|
185
|
+
When the gate passes, set `workspace.candidatePeriodStart` to the date reliable evidence collection begins. Do not backdate it. `candidatePeriodStart` and `candidatePeriodEnd` express management’s target. They do not establish the final report period.
|
|
186
|
+
|
|
187
|
+
Maintain risk assessments and the risk register while the program operates. Complete assessments on schedule and after material changes, and add or update controls when the conclusions require a different response. Audit preparation still checks for a current, independently reviewed assessment.
|
|
188
|
+
|
|
189
|
+
Record complementary customer or subservice controls after the internal control set is defined. `complementary-control.relatedControlIds` is the source of truth for those links. FileGRC derives the reverse connections for Control pages and evidence packets.
|
|
190
|
+
|
|
162
191
|
## Audit preparation and evidence packets
|
|
163
192
|
|
|
164
|
-
After
|
|
193
|
+
After engaging a CPA firm, create one audit record and set the firm-agreed Type 1 date or Type 2 period. Then initialize the engagement-specific management work:
|
|
165
194
|
|
|
166
195
|
```sh
|
|
167
196
|
npx filegrc prepare-audit audit-2026-type-2
|
|
@@ -169,11 +198,20 @@ npx filegrc audit-readiness audit-2026-type-2
|
|
|
169
198
|
npx filegrc audit-readiness audit-2026-type-2 --require-ready --json
|
|
170
199
|
```
|
|
171
200
|
|
|
201
|
+
The audit record’s `typeOneAsOf`, `periodStart`, and `periodEnd` are the dates agreed with the CPA firm. Keep the workspace candidate dates even when the formal period differs.
|
|
202
|
+
|
|
172
203
|
Preparation creates a separate system description, management assertion, and management representation document for the engagement from the local starter templates. Type 2 preparation also creates a period completeness statement and one `audit-population` record for each standard population. It is safe to run again and does not approve documents, mark controls implemented, or create evidence. Do not reuse one completed management document across engagements.
|
|
173
204
|
|
|
205
|
+
Review both evidence paths against the exact firm-agreed date or period:
|
|
206
|
+
|
|
207
|
+
1. FileGRC Evidence consists of dated Step 5 operating records. Complete each applicable record, link it to the Controls it supports, record the result in structured fields or Markdown, and link any external artifact needed to support that result.
|
|
208
|
+
2. External Evidence consists of verified `evidence` records from authoritative Systems. Confirm the source System, audit date or period, Control links, collector, verifier, and fixed attachment or approved external reference.
|
|
209
|
+
|
|
210
|
+
Audit Readiness reports coverage for both paths. The packet includes the matching FileGRC records and Markdown with Git history, plus External Evidence records, retained attachments, delivery indexes, and checksums.
|
|
211
|
+
|
|
174
212
|
Near the end of fieldwork, link a verified fixed-format copy of the signed management representation letter to its engagement-specific document. Date it on or after the Type 1 date or Type 2 period end. A representation that is still marked for later blocks packet delivery.
|
|
175
213
|
|
|
176
|
-
Catalog each authoritative source under Systems and assign its `evidenceSourceKinds`. Name the people who can access
|
|
214
|
+
Catalog each authoritative source under Systems and assign its `evidenceSourceKinds`. A third-party application is still a System because it operates controls or produces evidence. Create a separate Vendor for its provider and connect the System through `vendorId`; keep contracts, due diligence, and supplier risk on the Vendor. Name the people who can access system reports and keep extraction instructions in the System's Record Markdown. For each Type 2 population, select one source system and export the exact audit period. Split a population when different systems or queries produce its items. Link a verified `population-export` evidence record that names the same source system and stores the query or report parameters, generation time, timezone, count, completeness check, and accuracy check. A zero count still requires the source export and query. A population linked to an in-scope control cannot be marked not applicable.
|
|
177
215
|
|
|
178
216
|
Every evidence record names its collector. Verified evidence also names its verifier and verification date. Use `sourceSystemId` for system exports, `sourceResourceIds` for FileGRC records, and `sourceCommit` to bind the evidence to repository state.
|
|
179
217
|
|
|
@@ -185,7 +223,7 @@ npx filegrc evidence-packet --audit audit-2026-type-2
|
|
|
185
223
|
npx filegrc evidence-packet --audit audit-2026-type-2 --preview --require-ready
|
|
186
224
|
```
|
|
187
225
|
|
|
188
|
-
The packet includes records explicitly related to the selected engagement, its systems, controls, criteria, policies, evidence, and dependencies. It does not include unrelated dated records from the workspace. A Type 2 packet adds
|
|
226
|
+
The packet includes records explicitly related to the selected engagement, its systems, controls, criteria, policies, evidence, and dependencies. It does not include unrelated dated records from the workspace. A Type 2 packet adds FileGRC Evidence, recurring obligation occurrences, event workflows, and management population reconciliations. Output includes a control matrix with separate FileGRC Evidence and External Evidence columns, source-system index, external-evidence delivery index, population index, evidence index, committed historical source versions, and SHA-256 checksums. Output under `.filegrc/evidence-packets/` is derived and must not be hand-edited or committed.
|
|
189
227
|
|
|
190
228
|
Treat a packet as ready for management delivery only when its status is `delivery-ready`, its review list is clear, and its manifest names a clean Git revision. This means FileGRC's management checks passed. It does not mean the engagement team found the evidence sufficient or appropriate. The generator copies raw records, Markdown, and local fixed attachments. It never fetches external references. Reconcile `external-evidence-index.csv` to the auditor portal or other approved delivery system before telling the engagement team that submission is complete.
|
|
191
229
|
|
|
@@ -195,11 +233,13 @@ Link a control test to its `audit-population` record when sampling applies. Link
|
|
|
195
233
|
|
|
196
234
|
The seed policy owner is {{policy_owner_name}} and the reporting address is {{security_contact_email}}. Replace ownership or contacts when responsibilities change.
|
|
197
235
|
|
|
198
|
-
|
|
236
|
+
Appoint an independent management reviewer during policy review, not as a condition of defining the service boundary. The reviewer must be separate from the policy owner and able to challenge the owner’s decisions. Most organizations assign another internal leader or manager. An external reviewer is also allowed, and a one-person company needs one because no second internal person is available. The reviewer chairs Security and Risk Oversight and approves policies and governed documents.
|
|
237
|
+
|
|
238
|
+
The management reviewer and CPA auditor are different roles. Do not assign the CPA firm management or approval work without first confirming the firm's independence requirements.
|
|
199
239
|
|
|
200
240
|
Policy and training attestations must identify the exact Git revision of the content that a person acknowledged. Store signatures as evidence attachments and link their evidence IDs from the attestation.
|
|
201
241
|
|
|
202
|
-
Committee and risk meeting minutes are `meeting` resources with a primary Markdown companion. An optional `-agenda.md` companion holds the agenda. Record attendees, decisions, risks discussed
|
|
242
|
+
Committee and risk meeting minutes are `meeting` resources with a primary Markdown companion. An optional `-agenda.md` companion holds the agenda. Record attendees, decisions, and risks discussed on the Meeting. When follow-up needs separate tracking, create an `action-item` whose `sourceResourceId` points to the Meeting.
|
|
203
243
|
|
|
204
244
|
## Audit evidence
|
|
205
245
|
|
package/template/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Run a SOC 2 program as files in Git.
|
|
4
4
|
|
|
5
|
-
FileGRC gives a founder-led engineering team one place to adopt policies,
|
|
5
|
+
FileGRC gives a founder-led engineering team one place to adopt policies, implement controls, test External Evidence collection, run recurring compliance work, and prepare an audit. JSON holds structured records, Markdown holds long-form work, and Git supplies the change history.
|
|
6
6
|
|
|
7
7
|
There is no separate application database. The repository is the program, so engineers and agents can use the same data through the web app, a text editor, or the CLI.
|
|
8
8
|
|
|
@@ -15,9 +15,10 @@ SOC 2 work tends to scatter across documents, calendars, tickets, screenshots, a
|
|
|
15
15
|
FileGRC keeps that work connected:
|
|
16
16
|
|
|
17
17
|
- A starter Security program links criteria references, policies, planned controls, owners, and schedules.
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
18
|
+
- Work Queue turns policy timing into upcoming, due, and overdue work.
|
|
19
|
+
- Policy Events add the required hiring, departure, vendor, incident, and change tasks to the Work Queue.
|
|
20
|
+
- Program Readiness says whether management can begin a candidate Type 2 evidence period without an audit record.
|
|
21
|
+
- Audit Readiness starts later with the CPA engagement, formal period, fieldwork documents, populations, and evidence delivery.
|
|
21
22
|
- The packet builder produces a scoped, indexed delivery with source files, attachments, history, and checksums.
|
|
22
23
|
|
|
23
24
|
The starter content is a proposal, not a claim of compliance. Review every policy and planned control against how your company actually operates before approving it.
|
|
@@ -33,35 +34,42 @@ npm run validate
|
|
|
33
34
|
npm run serve
|
|
34
35
|
```
|
|
35
36
|
|
|
36
|
-
Setup asks for the company name, the initial policy owner, and a security contact email. It initializes Git when needed. The first local run then
|
|
37
|
+
Setup asks for the company name, the initial policy owner, and a security contact email. It initializes Git when needed. The first local run then defines the initial service boundary and an optional program goal. A Type 2 choice records management intent, not an audit engagement. Completing onboarding opens Step 1 so you can confirm the starter people and oversight team, criteria, commitments, vendors, and systems before moving on.
|
|
37
38
|
|
|
38
39
|
Open the printed local URL. You can commit locally from Repository without configuring a remote. Add a remote when the team is ready to share the workspace, then the browser can pull with rebase and push reviewed commits.
|
|
39
40
|
|
|
41
|
+
The creation summary reports the resolved engine version, install result, and whether the target joined an existing Git worktree. Generated workspaces receive an organization-specific README with their engine version, validation commands, and remaining setup work.
|
|
42
|
+
|
|
40
43
|
## How it works
|
|
41
44
|
|
|
42
|
-
1.
|
|
43
|
-
2.
|
|
44
|
-
3.
|
|
45
|
-
4.
|
|
46
|
-
5.
|
|
45
|
+
1. Confirm the program’s people and oversight team, applicable criteria, commitments, material vendors, and in-scope systems.
|
|
46
|
+
2. Review and activate the policies with a separate management reviewer, who is usually internal and may be external.
|
|
47
|
+
3. Tailor the starter controls, add each owner, actual procedure, scope, cadence, evidence source, and implementation date, and confirm any linked Work Queue schedules are enabled. Marking a control implemented starts eligible schedules. Then record any complementary customer or subservice controls.
|
|
48
|
+
4. Open each generated External Evidence draft, choose its authoritative source System, collect the named artifact, and have another person verify it.
|
|
49
|
+
5. Start the management candidate period, maintain risk assessments and risks, update controls when needed, work the FileGRC queue, and preserve dated evidence.
|
|
50
|
+
6. Engage a CPA firm, record the separate firm-agreed period, review FileGRC Evidence and External Evidence, prepare fieldwork, and generate the evidence packet.
|
|
47
51
|
|
|
48
52
|
Long-form policies, procedures, plans, minutes, training, assertions, and audit responses are Markdown companions beside their JSON records. Screenshots, signed acknowledgements, reports, and fixed exports are attachments linked through evidence records.
|
|
49
53
|
|
|
54
|
+
Third-party software is usually both a System and a Vendor. The application is the System because it operates controls and produces evidence. The provider is the Vendor because contracts, due diligence, and supplier risk belong to that relationship. Link the System to the Vendor with `vendorId`, and link exported evidence to the System.
|
|
55
|
+
|
|
50
56
|
## Run the program
|
|
51
57
|
|
|
52
|
-
Use Overview to follow
|
|
58
|
+
Use Overview to follow one six-step path: define scope, approve policies, implement controls, test External Evidence, operate the program, then complete the audit. Steps 1 through 4 and Step 6 open an overview with instructions, record links, progress, and completion status. Step 5 opens Policy Events and the Work Queue because operation is ongoing rather than a one-time checklist. The progress tracker opens the first incomplete step.
|
|
53
59
|
|
|
54
|
-
Use
|
|
60
|
+
Use Work Queue for recurring work, Policy Event tasks, and other assigned follow-up. Trigger a Policy Event when the underlying change occurs, and FileGRC adds its required actions to the queue with their owners and deadlines. Create a separate Action Item only when follow-up needs its own assignee, deadline, and completion proof. Each queue item shows its due window or deadline. Link dated proof to close the work.
|
|
55
61
|
|
|
56
|
-
Use the resource pages to maintain systems, people, vendors, risks, controls, tests, incidents, training, meetings, and
|
|
62
|
+
Use the resource pages to maintain systems, people, vendors, risks, controls, tests, incidents, training, meetings, and External Evidence. The question-mark guide on each list explains what the record type is for, which policies call for it, and when to update it.
|
|
57
63
|
|
|
58
64
|
Agents use the same logic headlessly:
|
|
59
65
|
|
|
60
66
|
```sh
|
|
61
67
|
npx filegrc guide risk-assessment --json
|
|
68
|
+
npx filegrc program-path --json
|
|
62
69
|
npx filegrc scaffold risk-assessment --title "2026 Annual Risk Assessment"
|
|
63
70
|
npx filegrc list risk --json
|
|
64
71
|
npx filegrc obligations --json
|
|
72
|
+
npx filegrc program-readiness --json
|
|
65
73
|
npx filegrc complete obligation-id completion-record.json
|
|
66
74
|
npx filegrc trigger person-started --occurred-on 2026-07-25 --subject person-id
|
|
67
75
|
npx filegrc complete-action action-item-id completion-record.json --completed-on 2026-07-25
|
|
@@ -69,15 +77,28 @@ npx filegrc complete-event obligation-event-id --completed-on 2026-07-25
|
|
|
69
77
|
npx filegrc search "access review"
|
|
70
78
|
```
|
|
71
79
|
|
|
72
|
-
`
|
|
80
|
+
`program-path` reports the same six steps, current status, page order, exact Instructions, Use, Policy Basis, and next actions shown in the renderer. `guide` reports that same page guidance for one resource, plus timing, required fields, valid values, relationship candidates, and Markdown locations. `scaffold` produces the same JSON and Markdown mutation shape used by the browser. Read `AGENTS.md` and `data/AGENTS.md` for the full headless workflow.
|
|
81
|
+
|
|
82
|
+
## Start the evidence period
|
|
83
|
+
|
|
84
|
+
Program Readiness works without an audit ID or CPA firm:
|
|
85
|
+
|
|
86
|
+
```sh
|
|
87
|
+
npx filegrc program-readiness --json
|
|
88
|
+
npx filegrc program-readiness --require-ready
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The Evidence Ready gate requires defined scope, effective policies, implemented controls, configured authoritative systems, and verified collection for external evidence that does not already have a dedicated Step 5 record. Put scan reports, backup output, and other fixed artifacts in External Evidence records, then link them from the applicable Step 5 operating records. Starter obligations remain enabled proposals until their governing policies are effective and at least one linked control is implemented. A FileGRC-managed control cannot be implemented while one of its linked Work Queue schedules is paused or waiting for policy approval.
|
|
92
|
+
|
|
93
|
+
When the gate passes, record `candidatePeriodStart` on the workspace on the date reliable collection begins. This is management’s candidate Type 2 period. Do not backdate it. The later audit record keeps the separate period agreed with the CPA firm.
|
|
73
94
|
|
|
74
95
|
## Prepare the audit
|
|
75
96
|
|
|
76
|
-
|
|
97
|
+
After engaging a CPA firm, create the audit record with the firm, scope, and exact agreed date or period. Audit Readiness checks the program foundation, engagement, formal scope and dates, management documents, FileGRC Evidence, External Evidence, and Type 2 populations.
|
|
77
98
|
|
|
78
99
|

|
|
79
100
|
|
|
80
|
-
For a Type 2 audit, reconcile each complete period population to its authoritative system after the period closes. A zero-item population still needs its source export and query. FileGRC
|
|
101
|
+
For a Type 2 audit, reconcile each complete period population to its authoritative system after the period closes. A zero-item population still needs its source export and query. FileGRC Evidence consists of dated operating records and their Markdown and Git history. External Evidence consists of verified exports, reports, screenshots, signed files, and approved external references. The packet compiles both paths with the selected records, attachments, indexes, historical versions, and SHA-256 checksums.
|
|
81
102
|
|
|
82
103
|
```sh
|
|
83
104
|
npx filegrc prepare-audit audit-id
|
|
@@ -87,6 +108,8 @@ npx filegrc evidence-packet --audit audit-id
|
|
|
87
108
|
|
|
88
109
|
FileGRC checks management preparation and packet integrity. The independent CPA firm still selects samples, tests controls, evaluates exceptions, decides whether evidence is sufficient, and issues the SOC 2 report.
|
|
89
110
|
|
|
111
|
+
Early CPA engagement remains available when a customer deadline, unusual scope, or other timing risk needs input before the program reaches Evidence Ready. It is optional, not the default first action.
|
|
112
|
+
|
|
90
113
|
## What belongs elsewhere
|
|
91
114
|
|
|
92
115
|
FileGRC does not replace workforce, identity, source-control, deployment, infrastructure, monitoring, endpoint, backup, vulnerability, training, signature, procurement, contract, or vendor-risk systems.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# {{company_name}} SOC 2 Program
|
|
2
|
+
|
|
3
|
+
This private workspace holds {{company_name}}'s SOC 2 program records and audit evidence. JSON under `data/` stores structured records, Markdown stores long-form work, and Git records reviewed changes.
|
|
4
|
+
|
|
5
|
+
The workspace uses FileGRC {{filegrc_version}} through the dependency range `{{filegrc_version_range}}`.
|
|
6
|
+
|
|
7
|
+
## Work locally
|
|
8
|
+
|
|
9
|
+
You need Node.js 20 or newer and Git.
|
|
10
|
+
|
|
11
|
+
```sh
|
|
12
|
+
npm install
|
|
13
|
+
npm run validate
|
|
14
|
+
npm run serve
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
The editable server binds to loopback by default and has no authentication. Do not expose it to an untrusted network.
|
|
18
|
+
|
|
19
|
+
Agents and terminal users can inspect the workspace without the browser:
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
npx filegrc guide --json
|
|
23
|
+
npx filegrc program-path --json
|
|
24
|
+
npx filegrc obligations --json
|
|
25
|
+
npx filegrc validate --json
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Read `AGENTS.md` and `data/AGENTS.md` before broad changes.
|
|
29
|
+
|
|
30
|
+
## Finish initial setup
|
|
31
|
+
|
|
32
|
+
The starter policies, controls, and obligations are proposals. They do not state that {{company_name}} operates the described controls.
|
|
33
|
+
|
|
34
|
+
1. Use browser onboarding or `npx filegrc setup --help` to record the initial service and goal, then finish Step 1 by confirming the people and oversight team, applicable criteria, commitments, material vendors, and in-scope systems.
|
|
35
|
+
2. Review the starter policies, appoint a reviewer who is separate from the policy owner, and activate only the policies that match current practice. The reviewer will usually be another person in the organization, but may be external.
|
|
36
|
+
3. Review the starter control set, implement each applicable control with its actual procedure, scope, cadence, evidence sources, and implementation date, and confirm any linked Work Queue schedules are enabled. Marking a control implemented starts eligible schedules. Then record any complementary customer or subservice controls.
|
|
37
|
+
4. Open each generated External Evidence draft, choose its authoritative source System, collect the named artifact, and have another person verify it.
|
|
38
|
+
5. Run `npx filegrc program-readiness --require-ready`, record the management candidate period start when reliable evidence collection begins, maintain risk assessments and risks, update controls when needed, use Work Queue for scheduled work, and trigger Policy Events when changes create required actions. `npx filegrc obligations` previews every event task, owner, deadline, and requested proof before the trigger creates anything.
|
|
39
|
+
6. Engage a CPA firm, record the separate firm-agreed period in an audit record, review FileGRC Evidence and External Evidence, and prepare fieldwork.
|
|
40
|
+
|
|
41
|
+
FileGRC manages GRC records and audit evidence. It does not replace infrastructure logging, monitoring, identity, backup, endpoint, or incident-detection systems.
|
package/template/data/AGENTS.md
CHANGED
|
@@ -8,13 +8,14 @@ Treat the installed model as the authority. Do not infer a schema from a nearby
|
|
|
8
8
|
|
|
9
9
|
```sh
|
|
10
10
|
npx filegrc guide --json
|
|
11
|
+
npx filegrc program-path --json
|
|
11
12
|
npx filegrc types --json
|
|
12
13
|
npx filegrc guide RESOURCE_TYPE --json
|
|
13
14
|
npx filegrc list RESOURCE_TYPE --json
|
|
14
15
|
npx filegrc search "TERM" --json
|
|
15
16
|
```
|
|
16
17
|
|
|
17
|
-
Use `guide` before any unfamiliar create or status transition. It reports required fields, fields required by a status, enum values, relationship types and candidates, Markdown slots,
|
|
18
|
+
Use `program-path` to find the current lifecycle step and see the renderer’s exact page Instructions, Use, Policy Basis, commands, and next actions. Use `guide` before any unfamiliar create or status transition. It repeats the page guidance and reports required fields, fields required by a status, enum values, relationship types and candidates, Markdown slots, timing, and exact paths. Use `describe` only when you need the raw model definition.
|
|
18
19
|
|
|
19
20
|
## Choose the right record
|
|
20
21
|
|
|
@@ -23,7 +24,7 @@ Use `guide` before any unfamiliar create or status transition. It reports requir
|
|
|
23
24
|
- Work required on a schedule or event belongs in `obligation`.
|
|
24
25
|
- A dated instance of work belongs in its activity type, such as `meeting`, `risk-assessment`, `access-review`, `vulnerability-scan`, `backup-test`, or `exercise`.
|
|
25
26
|
- A fact that may change over time belongs in an inventory record, such as `person`, `system`, `asset`, `vendor`, or `access-grant`.
|
|
26
|
-
-
|
|
27
|
+
- A dated Step 5 operating record proves that FileGRC-managed work occurred. Put each fixed external artifact in an `evidence` record and link it from the operating record; never add an unexplained attachment.
|
|
27
28
|
- Follow-up work belongs in `action-item`. A gap belongs in `finding`, a known threat belongs in `risk`, and an approved temporary departure belongs in `exception`.
|
|
28
29
|
- An auditor request belongs in `audit-request`; the engagement itself belongs in `audit`.
|
|
29
30
|
|
|
@@ -90,7 +91,7 @@ Never replace a complete record with a partial JSON object. Never change `id` or
|
|
|
90
91
|
|
|
91
92
|
JSON is for stable metadata used by validation, relationships, filters, schedules, and audit checks. Markdown is for the actual work: inputs, method, observations, results, rationale, decisions, exceptions, and follow-up.
|
|
92
93
|
|
|
93
|
-
If `guide` marks a Markdown slot recommended, fill it before treating the deliverable as complete.
|
|
94
|
+
If `guide` marks a Markdown slot recommended, fill it before treating the deliverable as complete. Keep observations and report details in the source record’s Markdown. Create a Finding only for a confirmed gap that needs its own remediation lifecycle. Create an Action Item only when follow-up needs a separate assignee, deadline, and completion proof. Set each child record’s `sourceResourceId` to the record that produced it; do not maintain reverse Finding or Action Item arrays on the source. Do not put a report’s entire variable structure into new JSON fields.
|
|
94
95
|
|
|
95
96
|
Use explicit business dates. Git records when a file changed, but it does not replace `occurredOn`, `assessmentDate`, `reviewedOn`, `completedOn`, or similar fields.
|
|
96
97
|
|
|
@@ -161,17 +162,18 @@ npx filegrc complete-action ACTION_ITEM_ID completion-mutation.json --completed-
|
|
|
161
162
|
npx filegrc complete-event OBLIGATION_EVENT_ID --completed-on YYYY-MM-DD
|
|
162
163
|
```
|
|
163
164
|
|
|
164
|
-
`complete` and `complete-action` validate the expected completion type and link the new record atomically. `complete-event` refuses to close the workflow until every action has its requested proof. For hour-based deadlines use `--occurred-at` with an RFC 3339 timestamp and timezone.
|
|
165
|
+
Run `obligations` before `trigger` to preview every Policy Event task, owner, deadline, and requested proof. Triggering creates the event and adds all linked Action Items to the Work Queue atomically. `complete` and `complete-action` validate the expected completion type and link the new record atomically. `complete-event` refuses to close the workflow until every action has its requested proof. For hour-based deadlines use `--occurred-at` with an RFC 3339 timestamp and timezone.
|
|
165
166
|
|
|
166
167
|
## Audit work
|
|
167
168
|
|
|
168
169
|
```sh
|
|
170
|
+
npx filegrc program-readiness --json
|
|
169
171
|
npx filegrc prepare-audit AUDIT_ID
|
|
170
172
|
npx filegrc audit-readiness AUDIT_ID --json
|
|
171
173
|
npx filegrc evidence-packet --audit AUDIT_ID --preview --json
|
|
172
174
|
```
|
|
173
175
|
|
|
174
|
-
Fix readiness errors in source records. Do not edit packet output under `.filegrc/`. A delivery-ready FileGRC packet means the management checks passed; the engagement team still judges evidence and performs the examination.
|
|
176
|
+
Run Program Readiness before creating the normal audit engagement. It checks scope, effective policies, implemented controls, evidence sources, and test captures without an audit ID. Fix readiness errors in source records. Do not edit packet output under `.filegrc/`. A delivery-ready FileGRC packet means the management checks passed; the engagement team still judges evidence and performs the examination.
|
|
175
177
|
|
|
176
178
|
## Finish every change
|
|
177
179
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Action Item Instructions
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Create an Action Item only when follow-up needs its own assignee, deadline, and completion proof. Keep simpler remediation on the Finding or other source record. Set `sourceResourceId` to the record that created the work; FileGRC derives the backlink and adds every open Action Item to Work Queue. Keep the assignee, due date or policy window, blockers, completion records, and evidence explicit.
|
|
4
4
|
|
|
5
5
|
For an event-generated action, do not weaken or extend its policy deadline by hand. Create the requested completion resource and close the action atomically:
|
|
6
6
|
|
|
@@ -8,4 +8,4 @@ For an event-generated action, do not weaken or extend its policy deadline by ha
|
|
|
8
8
|
npx filegrc complete-action ACTION_ITEM_ID completion-mutation.json --completed-on YYYY-MM-DD
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
FileGRC rejects the wrong completion type. Mark ordinary
|
|
11
|
+
FileGRC rejects the wrong completion type. Mark ordinary Action Items `done` only after the work occurred, set `completedOn`, and link the completion record or evidence. Use `blocked` while a named dependency prevents work, and link that dependency with `blockingResourceIds`.
|
|
@@ -1,6 +1,10 @@
|
|
|
1
1
|
# Audit Instructions
|
|
2
2
|
|
|
3
|
-
Create one `audit` record for one engagement. Define the audit kind, framework, exact Type 1 date or Type 2 period, scope, owners, auditor, and report status from facts supplied by management or the engagement team.
|
|
3
|
+
Create one `audit` record for one real CPA engagement. Define the audit kind, framework, exact firm-agreed Type 1 date or Type 2 period, scope, owners, auditor, and report status from facts supplied by management or the engagement team.
|
|
4
|
+
|
|
5
|
+
Keep management’s candidate Type 2 dates on `workspace`. Do not copy them into the audit record until the CPA firm agrees to those dates. Preserve both sets when the formal period differs.
|
|
6
|
+
|
|
7
|
+
The normal path is to pass `npx filegrc program-readiness --require-ready` and start reliable evidence collection before engaging the firm. Early engagement is allowed when a customer deadline or unusual scope needs CPA input.
|
|
4
8
|
|
|
5
9
|
After the audit record has its dates:
|
|
6
10
|
|
|
@@ -11,6 +15,13 @@ npx filegrc audit-readiness AUDIT_ID --json
|
|
|
11
15
|
|
|
12
16
|
Preparation creates engagement-specific management documents and, for Type 2, population records. It does not approve documents, implement controls, reconcile populations, or create evidence.
|
|
13
17
|
|
|
18
|
+
Review both evidence paths for the exact formal date or period:
|
|
19
|
+
|
|
20
|
+
1. FileGRC Evidence consists of dated Step 5 operating records. Complete the record, link it to the applicable Controls, record the result in its fields or Markdown, and link any external artifact needed to support that result.
|
|
21
|
+
2. External Evidence consists of verified `evidence` records from other Systems. Confirm the source System, date or period, Control links, collector, verifier, and fixed attachment or approved external reference.
|
|
22
|
+
|
|
23
|
+
The packet compiles both paths. It includes FileGRC records and Markdown with Git history, plus External Evidence records, retained attachments, delivery indexes, and checksums.
|
|
24
|
+
|
|
14
25
|
Run readiness repeatedly and fix source records. Preview the packet before writing it:
|
|
15
26
|
|
|
16
27
|
```sh
|
|
@@ -1,7 +1,9 @@
|
|
|
1
|
-
# Evidence Instructions
|
|
1
|
+
# External Evidence Instructions
|
|
2
2
|
|
|
3
3
|
An evidence record explains what a proof item is, where it came from, what period it supports, who collected it, and which records or controls it supports. The attachment alone is not enough.
|
|
4
4
|
|
|
5
|
+
Completing onboarding creates draft collection tests only for evidence that must come from systems outside FileGRC and does not already have a dedicated Step 5 record. Risk assessments, meetings, vendor reviews, attestations, vulnerability scans, penetration tests, backup tests, exercises, exceptions, and findings do not need a separate test. When one of those operating records needs a fixed external artifact, create or update an External Evidence record for the artifact and link its ID from the operating record. Keep a generated collection test as `draft` until the artifact has actually been captured. Set it to `collected` only after selecting the source System, attaching or referencing the result, and recording the source, date, classification, and collector. Set it to `verified` only after another named person checks it.
|
|
6
|
+
|
|
5
7
|
## Create evidence
|
|
6
8
|
|
|
7
9
|
1. Run `npx filegrc guide evidence --json`.
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
# Policy Event Instructions
|
|
2
2
|
|
|
3
|
-
Do not create an `obligation-event` or its
|
|
3
|
+
Do not create an `obligation-event` or its Action Items by hand. Preview the configured Policy Event, then trigger its work:
|
|
4
4
|
|
|
5
5
|
```sh
|
|
6
6
|
npx filegrc obligations --json
|
|
7
7
|
npx filegrc trigger EVENT_TYPE --occurred-on YYYY-MM-DD --subject RESOURCE_ID --json
|
|
8
8
|
```
|
|
9
9
|
|
|
10
|
-
Use `--occurred-at` with an RFC 3339 timestamp when any action has an hour-based deadline. The
|
|
10
|
+
The obligations output lists every task the trigger will add, with its owner, deadline, and requested proof. Use `--occurred-at` with an RFC 3339 timestamp when any action has an hour-based deadline. The trigger creates the event and adds all Action Items to the Work Queue atomically, then reports the event, task count, task IDs, and deadlines.
|
|
11
11
|
|
|
12
12
|
Complete each action with the requested resource type and proof. Then close the workflow:
|
|
13
13
|
|
|
@@ -5,7 +5,8 @@ An obligation is a reusable policy schedule or event template. It is not the rec
|
|
|
5
5
|
- Calendar obligations need a valid recurrence anchor, owners, expected completion types, and policy or control links.
|
|
6
6
|
- Event obligations need a stable lowercase `eventType`, a prompt, owners, expected completion types, and an explicit deadline window.
|
|
7
7
|
- Keep completed occurrences in `completionResourceIds`. Do not replace prior links when a new period starts.
|
|
8
|
+
- Keep starter obligations as proposals until every governing policy is active and effective and, when the obligation names controls, at least one linked control is implemented.
|
|
8
9
|
- When an approved cadence changes, update the policy, control, and obligation together.
|
|
9
10
|
- Pause or retire a template only when the underlying policy work no longer applies. Do not delete historical templates that explain prior periods.
|
|
10
11
|
|
|
11
|
-
Use `npx filegrc obligations --json` to inspect calculated work. Use `npx filegrc complete OBLIGATION_ID completion-mutation.json` to create and link a dated occurrence in one validated write.
|
|
12
|
+
Use `npx filegrc obligations --json` to inspect calculated recurring work and preview every Policy Event task, owner, deadline, and requested proof. Use `npx filegrc complete OBLIGATION_ID completion-mutation.json` to create and link a dated occurrence in one validated write. Use `npx filegrc trigger EVENT_TYPE ...` only after the matching event occurs; it adds all configured Action Items to the Work Queue atomically.
|
|
@@ -2,9 +2,8 @@
|
|
|
2
2
|
"schemaVersion": 1,
|
|
3
3
|
"id": "person-independent-approver",
|
|
4
4
|
"type": "person",
|
|
5
|
-
"title": "Independent
|
|
6
|
-
"status": "
|
|
7
|
-
"role": "
|
|
8
|
-
"employmentType": "external-reviewer",
|
|
5
|
+
"title": "Independent Reviewer",
|
|
6
|
+
"status": "active",
|
|
7
|
+
"role": "Security and Risk Oversight Reviewer",
|
|
9
8
|
"teamIds": ["team-security-risk-oversight"]
|
|
10
9
|
}
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Policies state required behavior. Controls, obligations, training, attestations, and evidence show how the organization applies that behavior.
|
|
4
4
|
|
|
5
|
-
Use the `content` Markdown slot for the policy text. Keep ownership and approval metadata in JSON. The approver must be separate from the owner, including through team membership
|
|
5
|
+
Use the `content` Markdown slot for the policy text. Keep ownership and approval metadata in JSON. The approver must be separate from the owner, including through team membership. The reviewer will usually be another leader or manager in the organization, but may be external.
|
|
6
6
|
|
|
7
7
|
Keep a policy `draft` until its text, owner, scope, related requirements and controls, approval, effective date, review cadence, and acknowledgement requirement match actual practice. When activating it:
|
|
8
8
|
|
|
@@ -12,4 +12,6 @@ Keep a policy `draft` until its text, owner, scope, related requirements and con
|
|
|
12
12
|
4. Update or create its recurring and event obligations.
|
|
13
13
|
5. Assign training or attestations when the policy requires them.
|
|
14
14
|
|
|
15
|
+
The independent policy approver is a management reviewer, not the CPA auditor. Appoint the reviewer during policy adoption. Recurring and event obligations linked to the policy remain proposals until the policy is active and effective and, when they name controls, at least one linked control is implemented.
|
|
16
|
+
|
|
15
17
|
For a material revision, preserve Git history, obtain a new approval, and require a new acknowledgement when the audience’s responsibilities changed. Do not reuse the audit firm as a management approver without confirming independence.
|
|
@@ -26,9 +26,9 @@ The policy owner:
|
|
|
26
26
|
- Coordinates incidents, exercises, reviews, and audit work.
|
|
27
27
|
- Approves security exceptions or obtains the required approval.
|
|
28
28
|
|
|
29
|
-
An
|
|
29
|
+
An independent reviewer chairs the security and risk oversight group. This person must be separate from the policy owner and able to challenge the owner's decisions. The reviewer will usually be another leader or manager in the organization, but may be external. The reviewer approves policies and governed plans, challenges management's assessment of control operation, and records independent decisions.
|
|
30
30
|
|
|
31
|
-
The security and risk oversight group meets at least quarterly to review the risk register, material incidents, significant findings, vendor and access review results, policy changes, exercises, and overdue work. Each meeting has formal minutes, decisions, and assigned actions. A one-person company must appoint a qualified external person to fill the independent reviewer role
|
|
31
|
+
The security and risk oversight group meets at least quarterly to review the risk register, material incidents, significant findings, vendor and access review results, policy changes, exercises, and overdue work. Each meeting has formal minutes, decisions, and assigned actions. A one-person company must appoint a qualified external person to fill the independent reviewer role because no second internal person is available.
|
|
32
32
|
|
|
33
33
|
System and process owners classify their systems and data, approve access, maintain safeguards, respond to findings, and keep recovery information current.
|
|
34
34
|
|
|
@@ -230,4 +230,4 @@ Violations may result in access removal, corrective action, contract remedies, o
|
|
|
230
230
|
|
|
231
231
|
## Review
|
|
232
232
|
|
|
233
|
-
The policy owner reviews this policy at least annually and after a material change to systems, services, risks, or obligations.
|
|
233
|
+
The policy owner reviews this policy at least annually and after a material change to systems, services, risks, or obligations. An independent reviewer who is separate from the policy owner approves this policy and other governed policies and plans. The reviewer may be internal or external. The security and risk oversight group reviews material changes and records its decision in meeting minutes. Git history records approvals and changes.
|
|
@@ -9,7 +9,7 @@ Use a `risk-assessment` for the dated assessment process and one `risk` record f
|
|
|
9
9
|
3. Scaffold the assessment and keep it `planned` or `in-progress` while the work is underway.
|
|
10
10
|
4. Write the method, inputs reviewed, threats considered, observations, decisions, and conclusion in Record Markdown.
|
|
11
11
|
5. Create or update the individual `risk` records. Link all risks considered with `riskIds`, newly identified risks with `newRiskIds`, and materially changed risks with `changedRiskIds`.
|
|
12
|
-
6. Link evidence
|
|
12
|
+
6. Link evidence from the assessment. When a confirmed gap needs its own lifecycle, create a Finding whose `sourceResourceId` points to this assessment. Create an Action Item only for separately assigned follow-up. Do not hide an unresolved issue in the narrative.
|
|
13
13
|
7. Use a reviewer who is not one of the assessors. Set `methodology` and `approvedOn` before marking the assessment `complete`.
|
|
14
14
|
8. Run validation, review the full diff, and commit the assessment, risk changes, and evidence together when practical.
|
|
15
15
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# FileGRC Program Repository
|
|
2
2
|
|
|
3
|
-
This Git repository is the system of record for FileGRC governance records and their revision history. It can supply the training and acknowledgement catalog, exception and finding populations, policy and document approvals, obligation history,
|
|
3
|
+
This Git repository is the system of record for FileGRC governance records and their revision history. It can supply the training and acknowledgement catalog, exception and finding populations, policy and document approvals, obligation history, Policy Event workflows, and management evidence indexes.
|
|
4
4
|
|
|
5
5
|
## Evidence Extraction
|
|
6
6
|
|
|
Binary file
|
|
Binary file
|
package/template/package.json
CHANGED
package/template-parameters.json
CHANGED