Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ The active authoritative model registry is the standalone `packages/filegrc/mode
- Export auditor control, population, and evidence indexes, committed historical source versions, and per-file checksums with every packet. External references remain warnings because the packet is not self-contained.
- Use one `audit-population` record for each complete management population and link its fixed `population-export` evidence. Record the evidence generation time, exact query or report parameters, timezone, count, and completeness and accuracy checks, including when the count is zero. Link the population and sampled-item evidence from the related control test.
- Catalog every authoritative evidence source as a `component`, assign its `evidenceSourceKinds`, name the people who can obtain evidence, and keep extraction instructions in Record Markdown. A reconciled population and its Evidence Artifact must name the same source Component. Split a population when its items require different source Components or queries.
- Every Evidence Artifact names its collector. Verified Evidence Artifacts also name their verifier and verification date. A source export links the cataloged source Component.
- Every Evidence Artifact names its collector. Reviewed Evidence Artifacts retain the technical `verified` status and actual review metadata. The authorized collector may review; require a separate reviewer only when a governing requirement specifically requires independence. A source export links the cataloged source Component.
- Define fields, types, enums, relationships, conditional requirements, and default UI metadata once in the model registry. Validators, CRUD forms, filters, search indexing, CLI help, and generated model documentation must consume that registry.
- Do not hand-copy model definitions into validators, templates, generated repositories, or documentation.
- Generate `docs/data-model.md` from the registry. Do not edit generated model documentation by hand.
Expand Down
4 changes: 4 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -904,3 +904,7 @@ Evidence packets retain current source proposals in the normal record and conten
A content revision does not restart an unchanged adopted schedule. Its Obligation Rule keeps its anchor, recorded completions and still-open earlier windows. Shared planning and occurrence validation use the first actual relevant governing operation together with the rule's own cutover. Initial content activation and real rule amendments retain their boundaries; this does not waive gaps in period authorization or evidence.

Owner retention applicability uses the same operating schedule edition. Source Coverage, existing applications and new application previews use its exact rule and procedure, while present service and source fingerprints remain current. A proposed period or disposal change does not stale an application before cutover. The browser displays the approved values being applied; actual activation of a changed rule requires reassessing an old application when its binding no longer matches.

### Evidence review and independence

Evidence collection and substantive review are distinct. The existing `verified` status and verification metadata record a real review, which an authorized collector may perform. The browser labels this state Reviewed. A separate reviewer is required only by a governing approved policy, Control, Commitment or legal requirement; scoped reporting-configuration proof checks continue to enforce their own independence conditions. Policy and risk-assessment approvals and CPA independence are unchanged. Completed Vendor Reviews may retain collected supporting proof without reopening vendor work. Packet delivery still checks actual review, source, scope, chronology, integrity and retained artifacts. Existing JSON fields, statuses, diagnostic codes and CSV column names stay compatible; historical verification facts are never rewritten by an upgrade.
14 changes: 8 additions & 6 deletions docs/data-model.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,7 @@ Operating record guides:
- **Risks** (`risk`): Name the threat and impact, assign an owner, rate the risk, and record its response.
- **Policy Events** (`obligation-event`): Record the actual event date and subject, then complete its linked Work Queue actions.
- **Data requests** (`data-request`): Record the request scope, decision, response, and supporting evidence.
- **Evidence Artifacts** (`evidence`): Record a real artifact or approved reference, link its source and supported work, then have another person verify it.
- **Evidence Artifacts** (`evidence`): Record a real artifact or approved reference, link its source and supported work, then record its actual substantive review. The authorized collector may review it unless a governing requirement specifically requires independence.
- **Policy reviews** (`policy-review`): Record the review date, reviewer, decision, and any required follow-up.
- **Meetings** (`meeting`): Record attendees, decisions, minutes, and assigned follow-up for the meeting.
- **Exceptions** (`exception`): Record the scope, owner, approval, and expiry before the departure begins.
Expand Down Expand Up @@ -2434,14 +2434,16 @@ Record Markdown: shown by default as an implicit companion file.

A retained export, report, screenshot, signed record, fixed file, or approved external reference. FileGRC operating records may support an audit directly without wrappers.

Instructions: Record a real artifact or approved reference, link its source and supported work, then have another person verify it.
Instructions: Record a real artifact or approved reference, link its source and supported work, then record its actual substantive review. The authorized collector may review it unless a governing requirement specifically requires independence.

Policy basis: The information security policy requires retained proof from authoritative Components when FileGRC operating records do not contain the full result.

Timing: Create an Evidence Artifact only for a real retained artifact or approved reference. Identify its source Component or source records, Controls, collection and verification facts, coverage, revision, and classification.
Timing: Collect real retained proof, then substantively review its source, scope, dates, completeness, accuracy and integrity before audit use. The authorized collector may also review and finalize it. A separate reviewer is required only by an applicable approved policy, Control, Commitment or legal requirement.

When reviewing:

- Collected means the artifact exists; Reviewed (stored as status verified) means a named Person actually checked it. Record that Person in verifierIds and the real review date in verifiedOn. The reviewer may be the collector. Do not infer review or independence from collection or fabricate review metadata.
- Preserve any specifically required independent review, including configuration proof supporting Reporting Channel Set approval. Keep independent policy and risk-assessment approvals and the CPA firm’s examination separate from routine evidence review.
- For a signed management representation, choose "Signed Record" for "Artifact Kind" and enter "signed-management-representation" for "Artifact Subtype".
- Enter when the representation was signed in "Business event time". Use "Collected On" for the date you received it.
- For a final CPA report, choose "Third Party Report" for "Artifact Kind", enter "soc2-report" for "Artifact Subtype", and enter when the CPA firm issued it in "Source generation time".
Expand Down Expand Up @@ -2472,8 +2474,8 @@ Markdown companions:
| `controlIds` | array of id | No | References: `control` |
| `auditIds` | array of id | No | References: `audit` |
| `collectorIds` | array of id | Conditional | References: `person` Required when `status` is one of `collected`, `verified`, `withdrawn`. |
| `verifierIds` | array of id | Conditional | References: `person` Required when `status` is `verified`. |
| `verifiedOn` | date | Conditional | Required when `status` is `verified`. |
| `verifierIds` | array of id | Conditional | Reviewed by References: `person` Required when `status` is `verified`. |
| `verifiedOn` | date | Conditional | Reviewed on Required when `status` is `verified`. |
| `expiresOn` | date | No | |
| `sourceResourceIds` | array of id | No | Relation group: `evidence-source-record`. References: `appointment`, `document`, `obligation`, `obligation-event`, `requirement`, `commitment`, `complementary-control`, `control`, `control-test`, `finding`, `exception`, `action-item`, `policy`, `policy-review`, `attestation`, `meeting`, `training`, `risk`, `risk-assessment`, `vendor`, `vendor-review`, `access-grant`, `access-review`, `vulnerability`, `vulnerability-scan`, `incident`, `exercise`, `backup-test`, `penetration-test`, `data-request`, `audit`, `audit-population`, `audit-request`, `source-coverage`, `control-activity`, `retention-schedule-item`, `requirement-mapping`, `obligation-rule`, `obligation-occurrence`, `reporting-route`, `reporting-route-set` |
| `filePaths` | array of data-path | Conditional | Required when `sourceKind` is `file` and `status` is one of `collected`, `verified`, `withdrawn`. Allowed when `sourceKind` is one of `file`, `system`, `rendered-page`, `authored-record`, `component`. |
Expand All @@ -2486,7 +2488,7 @@ Markdown companions:
| `businessEventAt` | timestamp | No | Business event time |
| `sourceGeneratedAt` | timestamp | No | Source generation time |
| `collectedAt` | timestamp | No | Collection time |
| `verifiedAt` | timestamp | No | Verification time |
| `verifiedAt` | timestamp | No | Review time |
| `readinessTest` | boolean | No | Pre-period readiness test |
| `coveredSourceFamilyIds` | array of string | No | Covered source families |
| `retrievalMethodKey` | string (id) | No | Retrieval method key |
Expand Down
8 changes: 4 additions & 4 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "filegrc-monorepo",
"version": "0.21.10",
"version": "0.21.11",
"private": true,
"workspaces": [
"packages/filegrc",
Expand Down
2 changes: 1 addition & 1 deletion packages/create-filegrc/package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "create-filegrc",
"version": "0.21.10",
"version": "0.21.11",
"description": "Create a filegrc workspace for a SOC 2 program",
"license": "MIT",
"repository": {
Expand Down
4 changes: 2 additions & 2 deletions packages/create-filegrc/src/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -524,13 +524,13 @@ async function runCombinedSetup(target, input) {
async function writeMinimalLockfile(target, name, versionRange) {
const lock = {
name,
version: "0.21.10",
version: "0.21.11",
lockfileVersion: 3,
requires: true,
packages: {
"": {
name,
version: "0.21.10",
version: "0.21.11",
dependencies: { filegrc: versionRange }
}
}
Expand Down
2 changes: 1 addition & 1 deletion packages/create-filegrc/template/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,7 @@ Model v13 checks completed full-program risk assessment, current workforce train

Use `npx filegrc amend-nonmaterial RESOURCE_ID --scaffold` for a model-supported administrative label correction or verified equivalent reporting email alias. Fill the actual owner, scoped authority, rationale, time and supporting fixed evidence; preview with `--preview`, then save with `--yes` and commit. The source record, Markdown and independent approval remain unchanged. `get RESOURCE_ID --workflow --json` includes the current administrative view and amendment IDs. The browser exposes the same action on supported record pages.

Email aliases require the owner to confirm the same underlying destination, recipients, access boundaries, availability and dependencies. This decision does not independently verify its Evidence or create a new independent approval. A matching proposed alias successor may be withdrawn atomically. Never use an amendment for changed commitments, recipients, access, scope, retention periods, cadence, deadlines, governed prose or evidence conclusions. Keep those normal reviews. Preserve committed amendments and the observations and captures supporting them; correct them through a subsequent amendment. Later independent verification may add verification metadata without rewriting those observations.
Email aliases require the owner to confirm the same underlying destination, recipients, access boundaries, availability and dependencies. This decision does not independently verify its Evidence or create a new independent approval. A matching proposed alias successor may be withdrawn atomically. Never use an amendment for changed commitments, recipients, access, scope, retention periods, cadence, deadlines, governed prose or evidence conclusions. Keep those normal reviews. Preserve committed amendments and the observations and captures supporting them; correct them through a subsequent amendment. Later substantive review, including review by the authorized collector, may add actual review metadata without rewriting those observations. A specific independence requirement still applies where relevant.

## Applying approved retention rules to services

Expand Down
4 changes: 3 additions & 1 deletion packages/create-filegrc/template/data/audits/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ Select a framework containing every CC1.1 through CC9.2 Security Common Criterio
Review both evidence paths for the exact formal date or period:

1. FileGRC Evidence consists of dated Step 4 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.
2. Evidence Artifacts are verified `evidence` records from source Components. Read each artifact and its linked records to check the source Component, date or period, Control links, collector, verifier, and fixed attachment or approved external reference. Ask only for a missing source fact or independent verification.
2. Evidence Artifacts are substantively reviewed (`status: "verified"`) `evidence` records from source Components. Read each artifact and its linked records to check the source Component, date or period, Control links, collector, actual reviewer, and fixed attachment or approved external reference. Ask only for a missing source fact or substantive review. The collector may also review unless a governing requirement specifically requires independence. A completed Vendor Review is not unfinished solely because supporting Evidence has no separate verifier; audit packet review remains a distinct check.

The packet compiles both paths. It includes FileGRC records and Markdown with Git history, plus Evidence Artifacts, retained attachments, delivery indexes, and checksums.

Expand All @@ -40,3 +40,5 @@ The signed representation requires verified `signed-record` Evidence with `artif
At report draft and again before closure, record the subsequent-events review through the CPA report date. Name the actual reviewers, review on or after the through date, state management's conclusion, and link relevant incidents, findings, and Evidence.

For each packet delivery, name the people who performed the least-disclosure review and approved delivery. Record the redaction decision, recipient, approved delivery System, exact packet Git revision, SHA-256 manifest checksum, chronological review, approval, and delivery dates, and the receipt reference. Final assertion and representation signers must have active authority Appointments linked from the Audit.

Evidence review does not require a second person by default. The authorized collector may review and finalize proof. Preserve any specific independence requirement, prior verification metadata and approvals. Collection alone is not review, and a completed supplier assessment does not become unfinished solely because supporting proof lacks a separate verifier.
6 changes: 4 additions & 2 deletions packages/create-filegrc/template/data/evidence/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

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.

Do not create placeholder or collection-test Evidence. Control implementation maps Controls to complete authoritative source Components; `npx filegrc evidence-map --json` remains available as a focused diagnostic. Create an Evidence Artifact during Step 4 only when a real export, report, screenshot, signed file, or approved external reference exists. When an operating record needs fixed supporting proof, create or update an Evidence Artifact and link its ID from that record. Keep it as `draft` until the artifact exists. Set it to `collected` only after selecting the source Component, attaching or referencing the result, and recording the source, date, Classification, and collector. Set it to `verified` only after another named person checks it.
Do not create placeholder or collection-test Evidence. Control implementation maps Controls to complete authoritative source Components; `npx filegrc evidence-map --json` remains available as a focused diagnostic. Create an Evidence Artifact during Step 4 only when a real export, report, screenshot, signed file, or approved external reference exists. When an operating record needs fixed supporting proof, create or update an Evidence Artifact and link its ID from that record. Keep it as `draft` until the artifact exists. Set it to `collected` only after selecting the source Component, attaching or referencing the result, and recording the source, date, Classification, and collector. Set it to `verified` (shown as Reviewed) only after a named authorized person substantively checks the source, dates, scope, completeness, accuracy, and integrity. That person may be the collector unless an applicable approved Policy, Control, Commitment, or legal requirement specifically requires independence. Collection alone is not review; never fabricate reviewer identities or dates.

## Create evidence

Expand All @@ -11,7 +11,7 @@ Do not create placeholder or collection-test Evidence. Control implementation ma
3. Put local attachments under `data/evidence/EVIDENCE_ID/` and list their data-relative paths in `filePaths`.
4. Use `externalReference` only when the file must remain in an approved external system. FileGRC never fetches it.
5. Link `sourceResourceIds`, `controlIds`, and `auditIds` as applicable. Use `sourceCommit` when the evidence represents repository state.
6. Name the actual collector. A `verified` record also needs the actual verifier and verification date.
6. Name the actual collector. A `verified` record also needs the actual reviewer in `verifierIds` and the actual review date in `verifiedOn`; these legacy field names do not require a separate person. Preserve historical review and verification records.

Copy a local fixed file and update the record atomically:

Expand All @@ -30,3 +30,5 @@ For a signed acknowledgement, bind the attestation to the exact content Git revi
For a `population-export`, also record the authoritative `sourceComponentId`, exact period, generation timestamp, timezone, query or report parameters, item count, completeness check, and accuracy check. A zero-item population still needs its source export and query.

Do not commit plaintext credentials, private keys, tokens, recovery codes, session data, regulated data, or personal data that may need erasure. Source-controlled ciphertext is allowed only under the Information Security Policy's approved encryption, separate-key, access, and rotation conditions. Use an approved external reference when Git is not an appropriate store.

A completed Vendor Review can rely on valid collected supporting proof without a separate Evidence verifier. For audit packet delivery, retain the distinct substantive review step and record actual review metadata, including an owner’s self-review when permitted. Policy approval, independent risk-assessment review, and the auditor’s independent examination remain separate requirements.
Loading
Loading