The security toolkit: `prorm audit`

prorm audit looks at a project and records what it finds: patterns in the
code that weaken security, what a live database says about its own
configuration, and which checklist items people have attested to. It writes
that down as SARIF, as JSON, and as an evidence bundle that can be verified
later.

This report records technical evidence mapped to control references. It is
not an audit, attestation, or certification, and it does not determine
compliance.

Every report the toolkit writes opens with that sentence, and the toolkit is
held to it. A clean scan means the specific patterns it looks for were not seen
in the files it scanned. It does not mean a control operates, and it says
nothing about the people, paperwork and processes most frameworks are about.

src/compliance/audit/ holds the implementation. It is unrelated to
src/audit/, which is the ORM's change logger.

A first audit, end to end

The project below is two files: an Express route that builds SQL from
req.params, and a connection that switches off certificate checks. The output
is what the commands print for it.

Scan the code

$ prorm audit code .
rule     severity  confidence  location                    message
TLS-002  high      high        src/db/connection.ts:9:28   rejectUnauthorized: false accepts any server certificate.
SQL-001  critical  high        src/routes/reports.ts:7:34  SQL passed to query() is built from request input in the same function (1 interpolated value(s)). Bind the values as parameters instead.
2 file(s), 19 rule(s): 2 finding(s), 0 suppressed.
$ echo $?
6

SQL-001 is critical because the interpolated value is traced to
req.params in the same function. Exit code 6 means an unsuppressed finding at
or above --fail-on (default high).

Fix it, or suppress it with a reason

 reports.get('/reports/:id', async (req, res) => {
-  const rows = await prorm.query(`SELECT * FROM reports WHERE id = ${req.params.id}`);
+  const rows = await prorm.query('SELECT * FROM reports WHERE id = ?', {
+    replacements: [req.params.id],
+  });
   res.json(rows);
 });

A suppression without a reason does not suppress anything. It adds a finding:

$ prorm audit code .
rule     severity  confidence  location                    message
TLS-002  high      high        src/db/connection.ts:9:28   rejectUnauthorized: false accepts any server certificate.
AUD-001  medium    high        src/routes/reports.ts:7:1   prorm-audit-ignore SQL-001 has no reason, so it suppresses nothing. Add ": <reason>".
SQL-001  critical  high        src/routes/reports.ts:8:34  SQL passed to query() is built from request input in the same function (1 interpolated value(s)). Bind the values as parameters instead.
2 file(s), 19 rule(s): 3 finding(s), 0 suppressed.

Evaluate the checklists and write a bundle

$ prorm audit run . --framework soc2,hipaa --out evidence --sign-key ~/.prorm/evidence-ed25519.pem
This report records technical evidence mapped to control references. It is not an audit, attestation, or certification, and it does not determine compliance.
checklist       evidence-supports  evidence-contradicts  inconclusive  not-run  attested  attestation-missing  attestation-expired  not-applicable
soc2-tsc        6                  2                     5             4        0         16                   0                    0
hipaa-security  3                  2                     6             4        0         19                   0                    0
✓ Evidence bundle: evidence/prorm-evidence-shop-20260926T221349Z
Check it later with: prorm audit verify evidence/prorm-evidence-shop-20260926T221349Z

Most of each checklist is attestation-missing. That is expected. Those items
are about people and paperwork, and they move only when someone runs
prorm audit attest. The klock behaviour-monitoring items
are not-run here because the account probes need --account.

Verify it, and hand it over

$ prorm audit verify evidence/prorm-evidence-shop-20260926T221349Z --public-key evidence.pub.pem
✓ 7 file(s) match SHA256SUMS; signature valid.

See Evidence bundles for what is inside and how
tampering shows up.

How audit run fits together

flowchart TD
  A["prorm audit run [path]"] --> B["scanPath: 19 rules over TS/JS, .env / .klock files and production configs"]
  A --> C["--db: runDbProbes, a fixed list of read-only statements"]
  A --> CK["--account: runKlockAccountProbes, read-only GETs as the signed-in account"]
  B --> D["findings"]
  C --> E["probesToFindings"]
  E --> D
  CK --> EK["accountProbesToFindings"]
  EK --> D
  F[".prorm/checklists/*.yaml: not-applicable overrides"] --> G
  H[".prorm/attestations/item-id.yaml"] --> G
  D --> G["evaluateChecklist, one status per item, per framework"]
  G --> I["results.json, findings.sarif, evidence/*.json, report.md, report.html"]
  I --> J["writeBundle: manifest.json and SHA256SUMS"]
  J --> K{"--sign-key given?"}
  K -- yes --> L["SHA256SUMS.sig and signature.json, ed25519"]
  K -- no --> M["unsigned bundle"]
  L --> N["prorm audit verify, prorm audit export"]
  M --> N

The diagram follows runAudit() in src/compliance/audit/run.ts: the code
scan, the optional database probes and the optional klock account probes all
become findings, the findings,
overrides and attestations are evaluated against each chosen checklist, and
everything is written as one hashed, optionally signed, directory.

What it needs

The rules parse source with the TypeScript compiler API. typescript is an
optional peer dependency, loaded only when audit code or audit run
runs. A plain JavaScript project installs it as a dev dependency:

npm install --save-dev typescript

Nothing else is needed. The built-in checklists ship as compiled data, so
nothing parses YAML at runtime. Your own overrides and attestations under
.prorm/ are read with the yaml package if it is installed, and with a small
built-in reader otherwise.

The rules

Rules are syntax visitors with no type information, so each one looks at one
file, and within a function at most. Every rule has at least five fixtures
that must be flagged and five that must not
(tests/audit/fixtures/<RULE>/{bad,good}/).

The klock checks (KLOCK-001 to
KLOCK-008) have their own section below.

How many checks there are

Counted from ALL_RULES, KLOCK_LOCAL_RULE_IDS and CHECKS in
src/compliance/audit/ with a scratch script (ALL_RULES.length, grouped by
the id prefix; CHECKS grouped by kind; the scan's own rulesRun):

Each finding carries ruleId, severity, confidence, message,
location, controls (the common control keys in
regulations), checklistItems (every item whose checks
include the rule) and fingerprint. The fingerprint is built from the rule, the
file, the enclosing function and the finding's position among its siblings, so
it survives lines being added above it.

Suppressing a finding

Inline, on the line or the line above:

// prorm-audit-ignore SQL-001: `column` is checked against COLUMNS above
const rows = await prorm.query(`SELECT ${column} FROM reports`);

Or in a baseline, .prorm/audit-baseline.json, keyed by fingerprint. You can
write one for the current findings:

prorm audit code --write-baseline --reason "pre-existing; tracked in SEC-142"

A suppression needs a reason. Without one it suppresses nothing, and it becomes
an AUD-001 finding itself. Suppressed findings stay in the JSON, in SARIF (as
suppressions with the justification) and in the report.

SARIF

--format sarif writes SARIF 2.1.0. It includes rules[] with helpUri and
security-severity, per-result partialFingerprints, and levels mapped from
severity (critical/high → error, medium → warning, low/info → note).
Code-scanning dashboards read it as it is:

prorm audit code --format sarif --out prorm.sarif

In GitHub Actions, upload it with the code-scanning action. The if: always()
matters: the audit step exits 6 when it finds something, and that is exactly
when you want the upload to run.

name: prorm audit
on: [push, pull_request]
permissions:
  contents: read
  security-events: write
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx prorm audit code --format sarif --out prorm.sarif --fail-on critical
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: prorm.sarif

{
  "level": "error",
  "locations": [
    {
      "physicalLocation": {
        "artifactLocation": { "uri": "src/routes/reports.ts", "uriBaseId": "%SRCROOT%" },
        "region": { "startLine": 7, "startColumn": 34, "endLine": 7, "endColumn": 85 }
      }
    }
  ],
  "message": {
    "text": "SQL passed to query() is built from request input in the same function (1 interpolated value(s)). Bind the values as parameters instead."
  },
  "partialFingerprints": { "prormFingerprint/v1": "e0eb5a9bbfb4cb021cce639d01a93536" },
  "properties": {
    "checklistItems": [
      "gdpr.art25-secure-by-design",
      "hipaa.164-312-c-injection-integrity",
      "iso.a8-28-secure-coding",
      "pci.6-2-4-injection-prevention",
      "soc2.cc7-1-injection-prevention"
    ],
    "confidence": "high",
    "controls": [],
    "security-severity": "9.5",
    "severity": "critical"
  },
  "ruleId": "SQL-001",
  "ruleIndex": 15
}

Checklists

Five checklists, each with 25 to 40 items, live in
compliance/checklists/*.yaml and are compiled by
scripts/build-checklists.mjs:

• soc2-tsc
• iso27001-2022
• hipaa-security
• pci-dss-4.0.1
• gdpr

Counted from checklists() in src/compliance/checklists.ts with the same
scratch script (items.length, then grouped by automation and by
responsibility); every checklist is at checklistVersion 1.0.0:

No item has responsibility: library: every one is the project's to act on,
alone (customer) or with the library's controls as part of the answer
(shared).

xychart-beta
    title "Items a check can show on its own (automation: automated)"
    x-axis ["soc2-tsc", "iso27001-2022", "hipaa-security", "pci-dss-4.0.1", "gdpr"]
    y-axis "items" 0 --> 15
    bar [12, 9, 7, 12, 8]

The bars are the automated column of the table above; the rest of every
checklist, 123 of the 171 items, needs a person's attestation before it can
leave inconclusive or attestation-missing.

SOC 2, ISO and PCI control text is copyrighted. The checklists store only the
reference id and a title written for this project. HIPAA and GDPR are public
law. Read the published standard for the authoritative wording.

Each item says how much of it a tool can show:

• automated: a rule or probe covers it, such as TLS configuration, embedded
  credentials, dynamic SQL, grants or card-data columns.
• partial: a check covers part of it, but the item is about operation over
  a period, such as logging retained and reviewed, backups tested or keys
  rotated. Clean checks alone leave it inconclusive.
• manual: people and paperwork, such as policies, BAAs and DPAs,
  training, penetration tests, risk assessments and access reviews. Only an
  attestation moves it.

prorm audit checklist                 # the five, with counts
prorm audit checklist hipaa --automation manual
prorm audit checklist --item pci.3-3-1-no-sad

The automated half of GDPR, with the checks behind each item:

$ prorm audit checklist gdpr --automation automated
GDPR - technical evidence map — References only; titles are paraphrased in our own words. Read the published source for the authoritative text.
id                                   control        title                                                                    automation  checks
gdpr.art25-secure-by-design          Art. 25(1)     Data protection by design                                                automated   SQL-001 SQL-002 AUD-001
gdpr.art25-default-restriction       Art. 25(2)     Data protection by default                                               automated   GRANT-002 DB-GRANTS DB-RLS
gdpr.art32-encryption-transit        Art. 32(1)(a)  Encryption of personal data in transit                                   automated   TLS-001 DB-TLS RT-TLS
gdpr.art32-cert-verification         Art. 32(1)(b)  Confidentiality of connections                                           automated   TLS-002 DB-SECTRANSPORT
gdpr.art32-encryption-at-rest        Art. 32(1)(a)  Encryption of stored personal data                                       automated   PII-001 SEC-002
gdpr.art32-no-embedded-credentials   Art. 32(1)(b)  Credentials kept out of source                                           automated   SEC-001 SEC-003
gdpr.art32-access-restriction        Art. 32(4)     Access limited to those instructed                                       automated   GRANT-001 GRANT-003 DB-PRIV
gdpr.art32-klock-credential-custody  Art. 32(1)(b)  Machine credentials stay in the key store, readable only by their owner  automated   KLOCK-001 KLOCK-003 KLOCK-007

Statuses

The toolkit uses these statuses and nothing else. There is no score and no
pass mark.

flowchart TD
  S["checklist item"] --> NA{"marked not applicable?"}
  NA -- yes --> R1["not-applicable"]
  NA -- no --> C{"an active finding from one of its checks?"}
  C -- yes --> R2["evidence-contradicts"]
  C -- no --> AUT{"automation level"}
  AUT -- automated --> ALL{"how many of its checks ran?"}
  ALL -- all --> R3["evidence-supports"]
  ALL -- some --> R4["inconclusive"]
  ALL -- none --> R5["not-run"]
  AUT -- "partial or manual" --> ATT{"attestation on file?"}
  ATT -- "in date" --> R6["attested"]
  ATT -- "expired, or older than the freshness window" --> R7["attestation-expired"]
  ATT -- none --> P{"partial, and a check ran?"}
  P -- yes --> R4
  P -- "partial, none ran" --> R5
  P -- manual --> R8["attestation-missing"]

This is evaluateItem() in src/compliance/audit/evaluate.ts, in the order
it tests: an override wins over everything, a finding wins over an
attestation, and a partial item with clean checks is still inconclusive
until someone attests to how the control operates over time.

Not applicable

.prorm/checklists/*.yaml:

notApplicable:
  - item: soc2.cc6-6-query-firewall
    justification: Queries are restricted by database roles and network policy; no application query firewall is used.

An entry without a justification is reported and not applied.

Attestations

prorm audit attest <item-id> asks for each field, or takes them as flags:

prorm audit attest hipaa.164-308-b-baa \
  --by ana@example.com --role "Privacy officer" \
  --statement "BAAs signed with every processor on the register" \
  --evidence CONTRACT-2026-014,CONTRACT-2026-022

This writes .prorm/attestations/<item-id>.yaml:

item: hipaa.164-308-b-baa
attestedBy: ana@example.com
role: Privacy officer
date: 2026-09-25
expires: 2027-09-25
statement: BAAs signed with every processor on the register
evidenceRefs:
  - CONTRACT-2026-014
  - CONTRACT-2026-022

An attestation expires on its expires date, or when it is older than the
item's freshness window, whichever comes first.

Database probes

prorm audit db connects with the usual connection flags (--url,
$DATABASE_URL, --dialect and so on) and runs a fixed list of read-only
statements. The executor refuses anything not on that list. It keeps counts and
flags, never row values.

SQLite, D1 and DuckDB have no session or server role, so the probes report
not-applicable. TLSEnforcer.verifyRuntime(prorm) runs the same TLS query
from application code.

klock checks: prorm audit klock

The klock checks look at how klock credentials are kept.
They come in two kinds, like the rest of the toolkit:

• Local checks run inside every code scan (audit code, audit run,
  audit klock), with no network. They read every .klock file the scan
  finds, committed or not, and production deployment configs for the prorm
  API.
• Account probes are read-only GETs as the signed-in account:
  /me/capabilities, /security/devices, /security/behaviour (admins
  only) and /security/access-rules. They run only from prorm audit klock
  (when signed in and not --offline) and prorm audit run --account. A
  route the API does not offer (404, 405, 501 or 503) makes the probe
  unknown, never a pass.

KLOCK-002 (an admin without MFA) and KLOCK-004 (a service session without
rotateBy) are not implemented, because the API does not show either fact to
the account. The ids are kept free for them.

When E3 is set somewhere the scan cannot see, such as the Cloudflare
dashboard, suppress KLOCK-008 with the reason:

{
  // prorm-audit-ignore KLOCK-008: CAPABILITY_E3 is set in the dashboard
  "vars": { "CAPABILITY_ENFORCEMENT": "enforce" }
}

prorm audit klock [path] runs the klock subset of the scan over the project,
then your own klock files (~/.prorm/klock/*.klock and the configured klock,
unless --no-home), then the account probes. It asks the public
/.well-known/klock-configuration whether v2 is offered; a 404 there turns
KLOCK-003 off. A project with a v1 klock left readable, and an API config
without E3:

$ prorm audit klock --offline --no-home
check      severity  where               message
KLOCK-008  medium    api/wrangler.jsonc  This production config sets up klock v2 for the prorm API but does not set CAPABILITY_E3, so the E3 stage (admin step-up and MFA, no new v1 CLI tokens) is off unless it is set elsewhere.
KLOCK-003  medium    ops/.klock          A v1 .klock holds a bearer secret that works from any machine. v2 binds it to a device key: prorm klock upgrade <file> --drop-secret.
KLOCK-007  high      ops/.klock          The .klock is mode 0644: every user on this machine can read it. It must be 0600.
Account checks skipped (--offline).
$ echo $?
6

It exits 6 on a finding at or above --fail-on, and 7 when an account probe
could not run.

prorm audit run --account [--report-days N] adds the account probes to an
evidence bundle: evidence/klock-account.json, manifest.klockAccount
({ account, probes }), and findings located at account:<username>.
Without a signed-in CLI it is a usage error.

The klock checklist items

Thirteen items across the five checklists name the klock checks:

Without --account, the behaviour items are not-run, which claims nothing
either way, and the access-policy items rest on KLOCK-008 alone, so they stay
inconclusive.

From code

The same pieces are importable, without the CLI:

import { scanPath, toSarif, runAudit, verifyBundle } from 'ts-prorm-orm/compliance/audit';
import { checklist, itemsForCheck, crosswalk } from 'ts-prorm-orm/compliance/checklists';

const scan = scanPath('src', { rules: ['SQL-001', 'TLS-002'] });
const sarif = toSarif(scan.findings, { toolVersion: '1.0.0' });

A release gate that writes a signed bundle, checks it, and fails on anything
critical, as a script your CI can call:

import fs from 'node:fs';
import { runAudit, verifyBundle, activeFindings, summarize } from 'ts-prorm-orm/compliance/audit';

const run = runAudit({
  path: '.',
  frameworks: ['soc2', 'hipaa'],
  outDir: 'evidence',
  signKeyPem: fs.readFileSync(process.env.EVIDENCE_KEY_FILE ?? '', 'utf8'),
});

const check = verifyBundle(run.dir, {
  publicKeyPem: fs.readFileSync('evidence.pub.pem', 'utf8'),
});
if (!check.ok) throw new Error(check.problems.join('\n'));

console.log(summarize(run.results));
// for the project above: { 'evidence-supports': 9, 'evidence-contradicts': 4, inconclusive: 11,
//   'not-run': 8, attested: 0, 'attestation-missing': 35, … }
const critical = activeFindings(run.findings).filter((f) => f.severity === 'critical');
if (critical.length > 0 || run.incomplete) process.exit(6);

Neither subpath is re-exported from the main entry point, so importing the
ORM does not load them.

Exit codes

--fail-on none never exits 6.

prorm audit on its own

Before the toolkit, prorm audit showed the account audit log. That is now
prorm audit log (and still prorm security audit). Bare prorm audit keeps
working for one minor release and prints a note pointing to audit log and
audit run.

Next: Evidence bundles.