Fieldguide integration

ScanNinja's Audit Hub delivers your compliance evidence to auditors who run their engagements on Fieldguide. Two delivery modes are supported:

1. Audit package export — a self-describing ZIP an auditor can import or work from directly.
2. Direct API push — evidence files land on the engagement's evidence requests in Fieldguide automatically, matched by control reference.

Both modes source the same data: the controls, evidence, and approved policies for an engagement in the Audit Hub.

What Fieldguide expects

Fieldguide organizes an engagement around requests — items the audit firm creates asking the client for evidence, each linked to one or more framework controls (for example CC6.1). Fieldguide's API does not allow integrations to create requests; ScanNinja therefore matches your evidence to the requests your auditor has already built, and uploads to them.

Audit package export

Exports are generated from the Audit Hub and produce a ZIP with a control-centric layout:

audit-map.json              control → evidence/policy file paths, per control reference
controls/{controlId}.json   full control detail (status, score, assessment notes)
evidence/{id}_{name.ext}    evidence files, original names and extensions preserved
policies/{id}_{name.ext}    approved policies only
metadata/
  engagement.json           engagement, framework, and period metadata
  export-manifest.json      SHA-256 hash of every file in the package
  audit-log-entry.json      who exported, when, and what was included

Key properties:

• Control-referenced. audit-map.json maps each control (e.g. CC6.1) to the exact files that evidence it, matching Fieldguide's control → request → files model.
• Integrity-verifiable. Every file is SHA-256 hashed into export-manifest.json, and the manifest hash is embedded in the audit log entry, so the package is tamper-evident.
• Approved content only. Draft policies and unreviewed evidence are never included.

Direct API push

The fieldguide-push tool takes an exported audit package and pushes it into a Fieldguide engagement over Fieldguide's REST API:

export FIELDGUIDE_API_TOKEN=...   # provided by your audit firm — see below

# 1. Find the engagement
node scripts/fieldguide-push.mjs --list-engagements

# 2. Preview the match plan — nothing is uploaded
node scripts/fieldguide-push.mjs --zip export.zip --engagement <uuid> --dry-run

# 3. Push
node scripts/fieldguide-push.mjs --zip export.zip --engagement <uuid> --ready-for-review

flowchart LR
  A[Audit Hub<br/>export ZIP] --> B[fieldguide-push]
  B -->|match by control reference| C[Fieldguide requests]
  B -->|no matching request| D[Fieldguide Documents tab]
  C --> E[Request status:<br/>Ready For Review]

How matching works

Each evidence file is routed to the Fieldguide request(s) that cover its control, using three signals in order of reliability:

1. Linked controls — the control keys the audit firm attached to each request.
2. Request identifier — the request's external-system identifier field.
3. Title references — control references detected in the request title.

Control references are recognized across frameworks: SOC 2 (CC6.1), CMMC 2.0 (AC.L2-3.1.1), NIST 800-53 (AC-2), NIST 800-171 (3.1.1), and ISO/IEC 27001 (A.8.24). Reference formatting differences (cc 6.1, CC-6.1) are normalized automatically.

Behavior

Behavior	Detail
Idempotent	Re-running skips files already present on a request — safe to run after every evidence update.
Dry run	--dry-run prints the full routing plan without uploading or changing anything.
Fallback	Files with no matching request upload to the engagement's Documents tab (disable with --no-fallback, target a folder with --folder).
Review flagging	--ready-for-review flips each request that received files to Ready For Review, notifying the auditor.
Rate-limit aware	Fieldguide API throttling (HTTP 429) is retried automatically with backoff.

Getting an API token

Fieldguide API tokens are provisioned inside the audit firm's Fieldguide workspace — ask your auditor to create one for the engagement. Request the minimum scopes:

Scope	Purpose	Required
engagements:read	Find the engagement	Yes
requests:read	List evidence requests	Yes
controls:read	Read control links for matching	Yes
requests.files:read	Detect already-uploaded files (idempotency)	Yes
requests.files:write	Upload evidence to requests	Yes
engagements.files:write	Documents-tab fallback uploads	Optional
requests:write	Flip requests to Ready For Review	Optional

Token handling

Treat the token as a secret. Supply it only via the FIELDGUIDE_API_TOKEN environment variable (or a secret store such as Azure Key Vault) — never on the command line, in scripts, or in source control. Verify it any time with the tool's startup check, which prints the token's scopes and expiry.