SOC 2 evidence the auditor actually accepts.

TL;DR — what this does for SOC 2

NSAuditor AI EE generates a Type-I-friendly pre-audit gap report with institutional-level evidence controls. It maps cloud and network scan findings to specific Trust Services Criteria, produces signed evidence artifacts (cover-page Scope Attestation, SHA-256 chain-of-custody sidecars, RFC 3161 trusted-timestamps, cryptographic suppression signing), and ships in machine-readable form suitable for GRC platform ingestion (native Vanta push connector shipped; Drata / Secureframe on roadmap).

The market split: GRC platforms (Vanta, Drata, Secureframe) automate workflow but lack native vulnerability scanning; legacy scanners (Tenable, Qualys, Rapid7) produce voluminous CVE reports but don't map findings to TSC controls. NSAuditor's wedge is the bridge — deep scanning + auditor-mapped output + GRC API push.

Coverage matrix — AICPA TSC 2017

Source of truth is data/compliance/soc2.json; this matrix mirrors it. A test asserts the two stay in sync.

Supported compliance frameworks (EE 0.9.0):

Read this: "Covered" means the engine produces direct evidence the auditor can attach to the control. "Partial" means we evidence one dimension of the control (e.g., a point-in-time snapshot) but not the cadence / multi-period dimension. "Out of scope" means the control is fundamentally not addressable by network scanning — a different evidence source is required.

How to run a SOC 2 scan

Once the EE package is installed and your license is activated, every scan can emit SOC 2 evidence by passing --compliance soc2. There are four common configurations — pick the one that matches the audit-readiness you need.

1. Install & activate (3 lines, no shell-rc edits)

   CE 0.1.30+ ships license install <KEY> which verifies the JWT signature before persisting and stores the key in the platform-appropriate location (macOS Keychain, or ~/.nsauditor/.env mode 0600 on Linux/Windows). No env var setup required.

   # Install CE platform + EE package (EE needs npm read-token from your purchase email) $ npm install -g nsauditor-ai @nsasoft/nsauditor-ai-ee # Activate — verifies JWT signature, stores in Keychain / ~/.nsauditor/.env $ nsauditor-ai license install enterprise_eyJhbGciOiJFUzI1NiIs... ✓ Enterprise license installed Stored at: macOS Keychain (service=nsauditor-ai) Org: you@example.com Seats: 5 Expires: 2027-04-04 # Verify $ nsauditor-ai license --status ✓ Enterprise license active

   Backward-compatible: existing setups using NSAUDITOR_LICENSE_KEY env var or ~/.nsauditor/.env continue to work — the multi-source license loader (CE 0.1.30+) resolves keys in this order: env var (CI/CD wins) → macOS Keychain → file.

2. Run a basic SOC 2 scan

   Single-scan, point-in-time. Produces the 10-file evidence bundle (gap report + scope attestation + chain-of-custody + integrity sidecars). Suitable for internal review and Type I gap analysis. Pick the recipe that matches your scope — on-prem network, AWS, Azure, or GCP (multi-cloud all map to the same soc2.json evidence ledger).

   # On-prem network — full SOC 2 audit $ nsauditor-ai scan --host 10.0.0.0/24 --plugins all --compliance soc2 # AWS — S3 + IAM SOC 2 audit (plugins 020 + 030) $ CLOUD_PROVIDER=aws AWS_REGION=us-east-1 \ nsauditor-ai scan --host aws --plugins 020,030 --compliance soc2 --out tasks/aws-scan-out # Baseline: findingCount=31, byStatus pass=4 fail=5 # Optional: AWS_S3_AUDIT_CONFIDENTIAL_BUCKETS=payroll,hr,backups (raises LOW→MEDIUM) # Azure — RBAC + NSG + Storage SOC 2 audit (plugin 022, service-principal auth) $ CLOUD_PROVIDER=azure \ AZURE_TENANT_ID=<your-tenant-id> \ AZURE_CLIENT_ID=<sp-app-id> \ AZURE_CLIENT_SECRET=<sp-secret> \ AZURE_SUBSCRIPTION_ID=<subscription-id> \ nsauditor-ai scan --host azure --plugins 022 --compliance soc2 --out tasks/azure-scan-out # Baseline: findingCount=2, byStatus pass=6 fail=2 # GCP — firewall + IAM enumeration (canonical-shape ready; SOC 2 mapping rules pending v0.4.0) $ CLOUD_PROVIDER=gcp GCP_PROJECT_ID=my-project \ nsauditor-ai scan --host gcp --plugins 021 --out tasks/gcp-scan-out

3. Add trusted timestamps + SLA tracking

   Adds RFC 3161 trusted-timestamp sidecars (third-party non-repudiation) and per-severity SLA / MTTR tracking. This is the configuration most enterprise customers run for ongoing audit-readiness.

   $ COMPLIANCE_TSA_URL=https://freetsa.org/tsr \ COMPLIANCE_TRACK_SLA=true \ COMPLIANCE_IDENTITY_REGISTRY=data/compliance/identity_registry.json \ nsauditor-ai scan --host 10.0.0.0/24 --plugins all --compliance soc2

4. Push results to your GRC platform

   Ships the gap report straight into Vanta as TestResult objects with TSC outcome mapping. Drata / Secureframe on roadmap.

   $ COMPLIANCE_GRC_PROVIDER=vanta \ COMPLIANCE_GRC_TOKEN=vanta_api_xxxx \ COMPLIANCE_TSA_URL=https://freetsa.org/tsr \ COMPLIANCE_TRACK_SLA=true \ nsauditor-ai scan --host 10.0.0.0/24 --plugins all --compliance soc2

5. Run on a recurring schedule (Type II)

   For Type II operating-effectiveness, run the same compliance scan on a fixed cadence (typically weekly or monthly). The recurring-attestation module automatically discovers prior scans, builds a chronological matrix across your assessment window, detects cadence gaps and scope drift, and emits the Type II evidence pack.

   # Example: weekly SOC 2 scan via cron, 6-month assessment window $ crontab -e # 0 3 * * 0 cd /opt/nsauditor && nsauditor-ai scan --host 10.0.0.0/24 \ # --plugins all --compliance soc2 \ # --output-dir ./scans/$(date +\%Y-\%m-\%d) >> scan.log 2>&1 # Generate Type II recurring attestation across the last 6 months $ nsauditor-ai compliance recurring-attestation \ --root ./scans \ --framework soc2 \ --window 6m

Environment variables reference

All SOC 2-related environment variables (Enterprise license required):

What you get — output artifacts

Each --compliance soc2 run writes the evidence bundle to out/<scan-id>/. The base bundle is 10 files (14+ when recurring-attestation is configured), and every artifact ships with a .sha256 integrity sidecar.

The cover-page Scope Attestation

Every artifact opens with the same attestation block — this is the auditor's single source of truth for what was assessed:

• Report ID + generation timestamp (NTP-synced when available; honest "local clock" note otherwise)
• Assessment type — explicit Type-I disclaimer
• Scanner version (EE + CE, both pinned across all artifacts in the scan)
• Scan window (start / end) and parallelism
• Targets in scope — explicit CIDR / domains / cloud account IDs
• Targets explicitly excluded with one-line business justification each (missing justification flagged ⚠ NO JUSTIFICATION PROVIDED)
• Framework + version — SOC 2 (AICPA TSC 2017, with 2022 points of focus) version 2017
• Report integrity — SHA-256 in companion sidecar
• Clock advisory — NTP drift status + probe staleness classification
• TSA policy OID (when timestamps are configured)
• Version delta verdict — stable / changed / unknown across scan comparisons

Report appendices

• Appendix A — Full finding details with TSC control mappings and stable rationale text
• Appendix B — Accepted Risks & False Positives (every suppression with rationale + approver + renewal cadence)
• Appendix C — Per-Target SLA Override Trace (override definitions + matched findings)
• MTTR section — Mean Time To Remediate by severity with SLA compliance status
• Identity verification section — Approver verification band with per-reason breakdown

How to view & verify the results

1. Open the HTML report (the auditor-friendly view)

The HTML report is fully self-contained — inline CSS, dark theme, no external assets, "Print to PDF" button at the top. Open it in any browser and you have the same view your auditor will see.

2. Verify the chain-of-custody hashes

Every artifact ships with a .sha256 sidecar. All four MUST return OK. If any FAIL, the artifact has been tampered with since generation — reject the report and rerun the scan.

3. Verify the RFC 3161 trusted timestamp (when configured)

The TSA's signature attests "this hash existed at <TSA timestamp>" — a third-party time floor that an internal actor cannot backdate.

4. Push to your GRC platform (optional)

If COMPLIANCE_GRC_PROVIDER=vanta was set on the scan, the connector already pushed; you'll find the TestResult objects in your Vanta workspace under the matching control IDs. If not, you can push retroactively:

5. Inspect the JSON for custom tooling

The JSON envelope is the canonical machine-readable form — use it for GRC ingestion, dashboards, custom reports, etc.

✓ Covered controls — direct evidence

For each control below, the engine produces a finding the auditor can attach to the control with stable rationale text.

CC6.1 — Logical access security software, infrastructure, and architectures

"The entity implements logical access security software, infrastructure, and architectures over protected information assets to protect them from security events to meet the entity's objectives."

CC6.2 — User identification and authentication

CC6.6 — Logical access boundaries and network segmentation

CC6.7 — Data in transit protection

CC6.8 — Prevention and detection of unauthorized or malicious software

CC7.1 — Detection of changes to system configurations / vulnerabilities

This is the vulnerability-management control. Major audit firms typically interpret CC7.1 as requiring automated scanning, even though SOC 2 itself never uses the phrase "vulnerability scanning."

CC7.2 — Monitoring of system components and operation for anomalies Covered in EE 0.3.7 · hardened in 0.3.8

"The entity monitors system components and the operation of those components for anomalies that are indicative of malicious acts, natural disasters, and errors affecting the entity's ability to meet its objectives."

EE 0.3.7's new aws-cloudtrail-auditor (plugin 040) closes the previously-partial CC7.2 coverage by auditing the AWS-native monitoring substrate end-to-end: CloudTrail trail health, CIS AWS Foundations Benchmark v1.5 §3.1–3.14 alarm coverage, and AWS Config recorder state. EE 0.3.8's v2 metric-filter audit replaces the v1 alarm-name-substring heuristic with the auditor-canonical logs:DescribeMetricFilters evidence stream, and the multi-region trail enumeration is now ON by default (36 canonical AWS regions; region-list version stamp 2026-05).

CC7.3 — Evaluation of security events to determine response Covered in EE 0.3.7

"The entity evaluates security events to determine whether they could or have resulted in a failure of the entity to meet its objectives (security incidents) and, if so, takes actions to prevent or address such failures."

EE 0.3.7 closes the previously-partial CC7.3 coverage by evidencing the AWS-canonical event-evaluation primitive: CloudWatch alarm coverage tied to the CIS §3.1–3.14 baseline. CloudWatch alarms convert raw CloudTrail events into actionable signals routed to SNS topics, PagerDuty, etc. — an alarm class with no alarm = no automated evaluation path = security events accumulate without triggering response.

Auditor evidence pack: the per-scan summary.cisAlarmCoverage shape carries evidenceMethod: "metric-filter-correlation-v2" (default; v2 auditor-canonical evidence stream) or "alarm-name-substring-heuristic-v1" + v2FallbackReason (transparency layer when v2 unavailable). summary.scanScope carries {regionsScanned[], regionsWithAccessDenied[], regionsWithCredentialFailure[], regionListVersion: "2026-05", callerIdentity, configAggregators, s3DestinationAudit, throttleRetriesByApi, throttleBudgetExhaustedByApi} — every multi-region / cross-account / split-IAM evidence gap surfaces honestly.

C1.1 — Identification and disposition of confidential information

(Only assessed if Confidentiality is in your audit scope — this is one of the optional categories.)

C1.2 — Disposal of confidential information New in EE 0.3.2 · Substantially deepened in EE 0.4.0 (plugin 1130)

"The entity disposes of confidential information to meet the entity's objectives related to confidentiality."

(Only assessed if Confidentiality is in your audit scope — same as C1.1.)

NSAuditor evidences the disposal control by detecting buckets that lack the institutional WORM and tamper-resistance primitives. SEC Rule 17a-4 and FINRA 4511 require S3 Object Lock in COMPLIANCE mode — auditors specifically reject GOVERNANCE-mode buckets as evidence stores because the override permission (s3:BypassGovernanceRetention) is by design, not an emergency break.

Severity classifier: AWS_S3_AUDIT_CONFIDENTIAL_BUCKETS=name1,name2 (comma-separated, case-insensitive substring match) escalates the C1.2 + KMS-CMK findings from LOW to MEDIUM for matched buckets. Tag-based classification is planned for v0.4.0.

⚠ Partial controls — single-dimension evidence

NSAuditor evidences one dimension of these controls (typically the configuration-state-at-this-moment dimension). The CADENCE / multi-period / process dimension requires additional evidence sources. The renderer surfaces a ⚠ Coverage caveat: line on every partial control.

⚪ Out of scope — what network scanning fundamentally cannot evidence

A SOC 2 audit covers technical, administrative, and physical controls. NSAuditor evidences the technical-network-and-cloud slice. Everything else is genuinely not our job — pretending otherwise would create what auditors call "scope illusion": the false belief that buying a scanner replaces governance work.

The renderer emits all of these as out_of_scope controls in every gap report — auditors immediately see the engine's known boundaries and don't have to guess what wasn't evaluated.

Type I vs Type II support

Recurring-scan attestation

The recurring-attestation module discovers prior scans, filters by your assessment window, detects cadence gaps and scope drift, and emits a chronological matrix. Compliance status taxonomy:

• pass — scans within cadence, no scope drift
• pass_with_drift_review — within cadence; scope-drift events surfaced for CC8.1 change-management review
• cadence_breach — any inter-scan gap exceeds threshold (CC7.1 finding)
• no_evidence — zero scans in the window (distinguishes "scans on disk but outside window" from "truly empty rootDir" via discoveredCount)

SLA & MTTR tracking

Per-severity SLA thresholds from sla.json. Three statuses per finding: compliant, approaching (default 75% of threshold), breached. The renderer separates breachedTotal (raw count of all overdue findings) from breachedEffective (post-compensating-control). Auditors read both — breachedEffective > 0 is a hard CC7.1 finding.

Suppressions with status: accepted_risk + non-empty compensating_control flip a finding's effective SLA status from breached → breached_with_compensating_control. The renderer surfaces an inline disclaimer requiring auditor verification of each compensating-control text.

Suppression workflow — the "what about false positives?" answer

Every real scan produces findings the security team has triaged out — false positives, accepted risks with compensating controls, etc. SOC 2 auditors reject silent deletion of findings (looks like under-reporting) but accept documented exclusions when each one carries a specific match, a non-empty rationale, and an approver.

The compliance engine reads out/<scan-id>/suppressions.json if present and enforces all three fields. Suppressions missing any of them are rejected and the underlying finding stays in fail status — the engine refuses to silently absorb undocumented suppressions.

CLI

Per-status default expiry

• accepted_risk — 90 days (compensating controls decay; quarterly review is institutional norm)
• false_positive — 365 days (scanner-error classifications don't go stale)
• Caller can override via explicit expiresInDays

Cryptographic signing & identity verification

Each suppression can be Ed25519-signed with signSuppression(). The signature payload is NFC-normalized per RFC 5198 and capped at 64KiB. Verification via verifySuppression() or verifyAgainstRegistry() cross-references identity-registry public keys.

Approvers are validated against a corporate identity registry binding names to Ed25519 public keys and authorization scopes (which frameworks an approver may authorize suppressions for). The suppression-audit module detects governance gaps — late renewals, per-approver patterns, quarterly cadence trends — surfaced as governance bands (HEALTHY / ACCEPTABLE / DEFICIENT / CRITICAL).

Where suppressions show up in the report

Every suppression appears in Appendix B — Accepted Risks & False Positives with control ID, finding text, status (accepted_risk vs false_positive), approver, rationale, and renewal chain. Expired suppressions surface as report.expiredSuppressions[] with a "REVIEW REQUIRED" callout when non-empty.

GRC platform integration — Vanta

The Vanta connector maps NSAuditor findings to Vanta TestResult objects and pushes them via API. Drata and Secureframe are on the roadmap.

Outcome mapping

Reliability features

• Pre-flight — single-shot GET to vendor identity endpoint with AbortController timeout
• Streaming response cap — MAX_RESPONSE_BYTES=1MiB (CC7.1 input validation at vendor API boundary)
• Duration cap — maxTotalDurationMs=180s per push (A1.2 availability bound under Retry-After saturation)
• Foreign-token detection — 18 well-known non-GRC token format patterns (GitHub, Slack, AWS, OpenAI, Stripe, GCP, npm) prevent misconfigured tokens reaching Vanta
• Idempotency — idempotencyKey() with scanId collision disambiguation (~<sha16> suffix)
• Description truncation — control descriptions truncate at 8KB with explicit count + scan reference

WORM evidence storage — S3 Object Lock

Write-Once-Read-Many archival for SEC Rule 17a-4 / FINRA 4511 audit compliance. The module ships with strict fail-CLOSED Object Lock validation:

• GOVERNANCE mode explicitly rejected — citing s3:BypassGovernanceRetention as the override permission auditors reject. GOVERNANCE-mode allows bucket owners to override retention, making it functionally equivalent to /tmp from the auditor's perspective. This is the #1 institutional rejection cause for "WORM" claims.
• COMPLIANCE mode required; minimum retention validation (default 7 years / 2555 days)
• Integer-only Years/Days — fractional values rejected (prevents silent threshold bypass)
• Resource redaction — three modes: off · hash (canonical-JSON SHA-256 fingerprints, key-order-independent) · remove (target/resource fields stripped)
• Path-traversal defense in archive manifest (rejects entries containing /, \, .., .)

Tabletop simulation — CC4.1 / CC7.3 monitoring evidence

Structured probe-event manifest + SIEM detection correlation proving the organization tests its monitoring controls. You define probe events (what you tested), import SIEM detection events (what was detected), and the correlator produces auditor-grade evidence: detection coverage percentage, per-category breakdown, undetected-probe list, unmatched-SIEM-event list.

Coverage bands (configurable)

• Liberal baseline — 50% / 80% (Type I / first-year)
• Type II — 75% / 90% (practitioner heuristic for Type II annual)
• High assurance — 85% / 95% (PCI-DSS L1 / FedRAMP)

Correlation guarantees

• Strict UTC timestamp enforcement (naive timestamps rejected per CC7.1 / CC7.2)
• IPv6 case-insensitive normalization (RFC 5952) + /128 CIDR strip
• Hostname normalization (case-insensitive + trailing-dot strip)
• SIEM event deduplication (structural identity)
• O(P×S) safeguard with CORRELATION_SIZE_WARNING_THRESHOLD=1M + onWarn callback

Comparison vs the market

Caveat: competitor capability lists evolve quickly; this table reflects publicly-available 2026-Q1 product documentation. Verify against your actual contract before relying on these comparisons.

Auditor FAQ — questions your CPA firm asks, answered up front

How do I verify the scope of this report wasn't manipulated post-scan?

Three layered guarantees:

• Integrity (against bit-rot, accidental edits, unsophisticated tampering): the cover page is part of the report bytes; .sha256 sidecars verify the report bytes. If the cover-page scope is wrong, the hashes won't match. Always written.
• Non-repudiation (against an insider who can regenerate both the report AND the matching sidecar): opt-in via complianceTsaUrl. When configured, each artifact ships a .tsr sidecar containing a Time-Stamp Response from the configured RFC 3161 Time-Stamp Authority. The TSA's signature attests "this hash existed at <TSA timestamp>" — a third-party time floor that an internal actor cannot backdate. Recommended TSAs: FreeTSA.org (free, testing), DigiCert / Sectigo / GlobalSign (paid commercial), or your internal corporate TSA.
• Suppression non-repudiation: each suppression can be Ed25519-signed. Signatures are verified against a corporate identity registry binding approver names to public keys.

What if the security team marked a real finding as "false positive" to make the report look clean?

Multiple controls prevent this:

1. Suppressions are visible — every one is logged in Appendix B with rationale + approver.
2. Cryptographic signing (optional) — suppressions carry Ed25519 signatures the auditor can independently verify.
3. Identity verification — approvers are cross-referenced against a corporate identity registry with authorization-scope checks.
4. Late-renewal flagging — suppressions renewed after expiration are flagged LATE or VERY_LATE with governance-band classification.
5. Quarterly trend analysis — rising late-renewal rates across quarters surface as governance degradation.

How does the scanner handle clock drift?

The NTP probe measures local-clock drift against configurable NTP servers. Drift above threshold triggers a WARN or CRITICAL clock advisory on the cover page. In strict mode (complianceNtpStrict: true), critical drift aborts the compliance run entirely. Probe staleness detection classifies the gap between probedAt and generatedAt to catch backdated or stale reports.

This is a single-point-in-time scan. How does Type-II operating-effectiveness apply?

NSAuditor supports Type II evidence through several mechanisms:

• Recurring-scan attestation — multi-scan chronological matrix across 6–12 month windows
• SLA / MTTR tracking — mean-time-to-remediate by severity with configurable thresholds
• Version delta detection — identifies scanner-version changes to distinguish genuine findings from lifecycle artifacts
• Suppression renewal cadence — quarterly trend analysis with governance bands

Why is CC1 (control environment) marked out of scope?

CC1 is about board oversight and organizational ethics — these are inherently human / process artifacts, not network state. We could pretend, but pretending creates more audit risk than admitting the boundary. Pair NSAuditor with a GRC platform (Vanta / Drata / Secureframe) for the governance layer.

What about tabletop exercises for CC4.1 / CC7.3?

The tabletop simulation framework (EE-SOC2.14) provides probe-event manifests + SIEM detection correlation. You define what you tested, import what was detected, and the correlator produces auditor-grade evidence: detection coverage percentage, per-category breakdown, undetected-probe list, unmatched-SIEM-event list. Configurable coverage bands (50/80 liberal, 75/90 Type II, 85/95 high-assurance) classify the result as critical / acceptable / healthy.

Where can I see the canonical mapping?

The source of truth is data/compliance/soc2.json in the EE package. The full SOC 2 coverage matrix in the EE repo mirrors that file, and a test asserts the two stay in sync.