We Got Flagged in a SOX Audit Because of Code Comments. So We Built a VS Code Extension

Diego Pablo — Sun, 24 May 2026 21:57:20 +0000

How we automated compliance-grade documentation for regulated-industry codebases — and what we learned.

Last year, a fintech team I know got dinged during a SOX audit. Not for a security vulnerability. Not for a broken control. For inadequate code documentation on a financial reporting module.

The auditors wanted to know: what does this function do, what data does it touch, and where's the audit trail? The devs knew the answers. They just hadn't written any of it down in a way that survives a formal review.

That's a surprisingly common story in financial services and healthcare. The code is often fine. The paper trail isn't.

The Problem with Compliance Documentation

Here's what usually happens:

A developer writes a function that handles, say, customer PII or swap transaction records. It works. It gets reviewed. It ships. And somewhere in the process, the compliance documentation either:

Never gets written
Gets written in plain English by someone who doesn't understand the code
Gets written by the developer in a format that doesn't map to any regulatory framework

Then audit season comes. Or an incident happens. Or a new compliance officer joins and wants to understand the codebase. And suddenly everyone is scrambling to reverse-engineer intent from implementation.

The irony is that developers know what the code does. They just don't have a fast path to getting that knowledge into a form that satisfies FINRA, SEC, SOX, HIPAA, or PCI-DSS reviewers.

What We Built

We built compliancedoc — a VS Code extension (two, actually: one for finance and one for healthcare) that generates compliance-aware documentation directly from selected code.

You highlight a function. You run a command. You get back structured output mapped to the frameworks you're actually regulated under.

It does four things:

1. Explain — Plain-English explanation of what the code does, what data it touches, and what compliance risks are visible. Written for compliance officers and auditors, not developers.

2. Document — Generates a JSDoc block with compliance-specific tags: data classification, PII flags, risk level, framework references (e.g. SOX-404, PCI-3.4, GDPR-Art32), and audit-trail status. It inserts directly above your function.

3. Refactor — Reviews the selected code for compliance gaps and gives you concrete remediation steps plus a refactored example. Useful before a commit or during audit remediation.

4. Audit Report — Produces a formal audit-style report: executive summary, regulatory mapping table, access control assessment, data protection assessment, sign-off readiness. Built for the evidence package, not a PR description.

What It Actually Looks Like

Say you have a function like this (simplified):

async function processPayment(customerId, amount, cardToken) {
  const customer = await db.getCustomer(customerId);
  const result = await paymentGateway.charge(cardToken, amount);
  await db.logTransaction(customerId, amount, result.id);
  return result;
}

Running CD: Generate Docs produces something like:

/**
 * @function processPayment
 * @description Processes a customer payment charge and records the transaction.
 * Handles cardholder data via tokenized card reference; raw PAN is never stored.
 *
 * @compliance PCI-DSS 3.4 - Cardholder data rendered unreadable (tokenization)
 * @compliance PCI-DSS 10.2 - Audit log written on transaction completion
 * @compliance SOX-404 - Financial transaction logged for internal control evidence
 *
 * @dataClassification FINANCIAL | PII
 * @riskLevel HIGH
 * @auditTrail EVIDENCED — logTransaction call present
 *
 * @param {string} customerId - Internal customer identifier
 * @param {number} amount - Charge amount in smallest currency unit
 * @param {string} cardToken - Payment gateway token (never raw PAN)
 * @returns {Promise<Object>} Gateway charge result with transaction ID
 * @throws {PaymentGatewayError} On charge failure
 */

That's insertable, version-controllable, and something an auditor can actually read.

Running CD: Generate Audit Report on the same function produces a multi-section Markdown report covering regulatory mapping, gap analysis (e.g. "encryption at rest for logTransaction output not evidenced in selected code"), and recommended actions.

What Frameworks Are Supported

Finance extension:

FINRA (supervisory controls, business continuity)
SEC (records retention, immutable financial records)
SOX (internal controls, financial reporting)
PCI-DSS (cardholder data, secure development)
GLBA (consumer financial data safeguards)
CFTC (swap records, transaction information)
GDPR (privacy by design, erasure implications)

Healthcare extension:

HIPAA Privacy Rule
HIPAA Security Rule
HITECH
21 CFR Part 11
CMS standards
GDPR (for EU health data contexts)

You configure which frameworks are active for your project. The backend only generates output against your selected frameworks — you're not getting irrelevant CFTC flags on a HIPAA-only codebase.

The Part That Matters: This Is a Starting Point, Not a Rubber Stamp

Worth saying clearly: the output should be reviewed by a qualified compliance officer before it's used for regulatory submissions or production sign-off.

The extension doesn't replace compliance expertise. It gives developers a structured, framework-aware first draft that a compliance officer can actually review, rather than starting from scratch or trying to decode raw source code.

The goal is to close the gap between what developers know and what auditors need to see — faster, and in a consistent format.

Free Tier vs. Pro

There's a free tier with a monthly generation quota — enough to try all four features across a real codebase. Pro is unlimited and adds custom personal rules (global or framework-specific), so you can encode your organization's internal compliance standards on top of the built-in framework rules.

Try It

Finance: marketplace.visualstudio.com — compliancedoc-finance
Healthcare: marketplace.visualstudio.com — compliancedoc-healthcare

Install, run CD: Register / Sign In, select your frameworks, highlight a function, and run one of the CD: commands from the Command Palette.

If you work in a regulated industry and spend time writing or reviewing compliance documentation, I'd genuinely like to hear what you think — what works, what's missing, what framework coverage you'd want next.

vscode #compliance #fintech #healthtech #devtools #productivity #security

DEV Community: Diego Pablo