@erclx/aitk 2.1.0 → 2.2.0

package/src/commands/audits.ts

@@ -244,7 +244,11 @@ function countLine(counts: Record<string, number>): string {
  * against an absent baseline says the same as a corpus that did not move.
  */
 function deltaLine(delta: Delta): string | undefined {
-  if (delta.kind === 'per-machine' || delta.kind === 'unmeasured') {
+  if (
+    delta.kind === 'per-machine' ||
+    delta.kind === 'upstream' ||
+    delta.kind === 'unmeasured'
+  ) {
     return undefined
   }
   if (delta.kind === 'unrecorded') return 'No recorded baseline to compare'
@@ -301,7 +305,11 @@ function report(
     }
 
     if (!result.tracked) {
-      logInfo('Per-machine corpus, so no baseline is kept')
+      logInfo(
+        result.corpus === 'upstream'
+          ? 'Upstream index, so no baseline is kept and growth is not this tree'
+          : 'Per-machine corpus, so no baseline is kept',
+      )
       continue
     }
 
@@ -335,7 +343,7 @@ function report(
   // Stated on every run, including a clean one. A count of what passed reads as
   // a verdict on the whole set unless the run also says what it never reached.
   logInfo(
-    `${summary.audited} of ${results.length} corpora measured, ${summary.absent} absent on this machine`,
+    `${summary.audited} of ${results.length} corpora measured, ${summary.absent} absent or unreachable from this machine`,
   )
 
   outro()

package/src/commands/deps.ts

@@ -0,0 +1,173 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import {
+  type Advisory,
+  auditDependencies,
+  type AuditRefusal,
+  countBySeverity,
+  SEVERITIES,
+} from '@/deps/audit'
+import {
+  intro,
+  logInfo,
+  logStep,
+  logWarn,
+  outro,
+  pipeOutput,
+  plural,
+} from '@/ui'
+
+interface AuditCommandOptions {
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the advisory list fails to arrive. */
+const REFUSALS: Record<AuditRefusal, string> = {
+  'no-manifest': 'No package.json here, so there is no dependency set to read.',
+  'no-lockfile':
+    'No lockfile beside the manifest, so no dependency set is resolved yet. Install first.',
+  'no-record':
+    'The advisory lookup returned no record. Check the network, then re-run.',
+}
+
+export function register(program: Command): void {
+  const deps = program
+    .command('deps')
+    .description('Read the installed dependency set for published advisories')
+    .helpOption('-h, --help', 'Show this help message')
+
+  deps
+    .command('audit')
+    .description('Report advisories against the dependencies already resolved')
+    .argument('[path]', 'Project to audit, defaulting to the current directory')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scope:',
+        "  The resolved dependency set, read through the runtime's own",
+        '  advisory command. This reaches a network, so a lookup that fails',
+        '  refuses rather than reporting a clean tree.',
+        '',
+        'Exit codes:',
+        '  0  no advisory against the resolved set',
+        '  1  refused, with the reason on stderr',
+        '  2  at least one advisory was published',
+        '',
+        'Examples:',
+        '  aitk deps audit',
+        '  aitk deps audit --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: AuditCommandOptions) => {
+      process.exitCode = await runAudit(path, opts)
+    })
+}
+
+function severityLine(counts: Record<string, number>): string {
+  return SEVERITIES.filter((severity) => counts[severity] !== 0)
+    .map((severity) => `${counts[severity]} ${severity}`)
+    .join(', ')
+}
+
+/**
+ * Groups by package, since one dependency commonly carries several advisories
+ * and a flat list reads as more distinct upgrades than the tree actually owes.
+ */
+function byPackage(advisories: readonly Advisory[]): Map<string, Advisory[]> {
+  const grouped = new Map<string, Advisory[]>()
+
+  for (const advisory of advisories) {
+    const held = grouped.get(advisory.package) ?? []
+    held.push(advisory)
+    grouped.set(advisory.package, held)
+  }
+
+  return grouped
+}
+
+async function runAudit(
+  path: string | undefined,
+  opts: AuditCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('aitk deps audit')
+
+  const audit = await auditDependencies(root)
+
+  if (audit.kind === 'refused') {
+    logStep('Refused')
+    logWarn(REFUSALS[audit.reason])
+    if (audit.message !== undefined) logWarn(audit.message)
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: audit.reason,
+          message: audit.message ?? REFUSALS[audit.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  const counts = countBySeverity(audit.advisories)
+
+  logStep('Advisories')
+  if (audit.advisories.length === 0) {
+    logInfo('No advisory against the resolved dependency set.')
+  } else {
+    const grouped = byPackage(audit.advisories)
+    const total = audit.advisories.length
+
+    logWarn(
+      `${total} ${total === 1 ? 'advisory' : 'advisories'} across ${plural(grouped.size, 'package')}: ${severityLine(counts)}`,
+    )
+
+    // Piped rather than logged line by line, since every one of these is a
+    // finding and the timeline's own tick would mark each as something that
+    // passed. The frame stays, and the list inside it stays unmarked.
+    pipeOutput(
+      [...grouped]
+        .map(([name, held]) =>
+          [
+            `${name}: ${severityLine(countBySeverity(held))}`,
+            ...held.flatMap((advisory) => [
+              `  ${advisory.severity.padEnd(8)} ${advisory.title}`,
+              `  ${' '.repeat(8)} ${advisory.url}`,
+            ]),
+          ].join('\n'),
+        )
+        .join('\n'),
+    )
+  }
+
+  // Stated whichever way the count went. An advisory arrives when someone
+  // publishes one, so this number moves with no edit here, and a report that
+  // does not date itself reads as a fact about the tree rather than about a day.
+  logStep('Reading')
+  logInfo(
+    'Measured against the advisory index at run time, not at commit time.',
+  )
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        severities: counts,
+        advisories: audit.advisories,
+      })}\n`,
+    )
+  }
+
+  return audit.advisories.length === 0 ? 0 : 2
+}

package/src/commands/secrets.ts

@@ -0,0 +1,132 @@
+import { resolve } from 'node:path'
+import type { Command } from 'commander'
+import { type ScanRefusal, scanShippedTree } from '@/secrets/scan'
+import { intro, logError, logInfo, logStep, logWarn, outro, plural } from '@/ui'
+
+interface ScanCommandOptions {
+  readonly json?: boolean
+}
+
+/** What a reader does about each way the corpus fails to build. */
+const REFUSALS: Record<ScanRefusal, string> = {
+  'no-manifest':
+    'No package.json here, so nothing is published from this tree.',
+  'no-publish':
+    'The manifest declares private, so this project publishes nothing.',
+  // Stated as an unread corpus rather than an absent one. A publish with no
+  // files field packs the whole tree, so this is the package that ships the
+  // most, and calling it nothing to read is the denial the reasoning in
+  // src/secrets/shipped.ts warns against.
+  'no-files-field':
+    'package.json declares no files field, so a publish would pack the whole tree. This check reads a declared corpus and left that one unread.',
+  'no-git': 'git could not list this tree, so the corpus is unknown.',
+  'no-shipped-files':
+    'The files field matched nothing git lists, so nothing would be scanned.',
+}
+
+export function register(program: Command): void {
+  const secrets = program
+    .command('secrets')
+    .description('Read committed state for credentials that ship to a target')
+    .helpOption('-h, --help', 'Show this help message')
+
+  secrets
+    .command('scan')
+    .description('Report credential-shaped values in the tree this repo ships')
+    .argument(
+      '[path]',
+      'Repository to scan, defaulting to the current directory',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Scope:',
+        "  The package's own files field, so the corpus is what npm packs",
+        '  and what the plugin ships. Nothing outside it is read.',
+        '',
+        'Exit codes:',
+        '  0  the shipped tree carries no credential-shaped value',
+        '  1  refused, with the reason on stderr',
+        '  2  at least one value was found',
+        '',
+        'Examples:',
+        '  aitk secrets scan',
+        '  aitk secrets scan --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (path: string | undefined, opts: ScanCommandOptions) => {
+      process.exitCode = await runScan(path, opts)
+    })
+}
+
+async function runScan(
+  path: string | undefined,
+  opts: ScanCommandOptions,
+): Promise<number> {
+  const root = resolve(path ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('aitk secrets scan')
+
+  const scan = await scanShippedTree(root)
+
+  if (scan.kind === 'refused') {
+    logStep('Refused')
+    logWarn(REFUSALS[scan.reason])
+    outro()
+
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          reason: scan.reason,
+          message: REFUSALS[scan.reason],
+        })}\n`,
+      )
+    }
+    return 1
+  }
+
+  logStep('Corpus')
+  logInfo(
+    `${plural(scan.files, 'file')} read, ${scan.skipped} skipped as binary or unreadable`,
+  )
+  // Stated on every run, including a clean one. The corpus answers what the
+  // package publishes, and a reader who sees only the passing count reads the
+  // verdict as covering the repository.
+  logInfo(
+    `${scan.listed - scan.files - scan.skipped} of ${scan.listed} listed files sit outside the published corpus and were not read`,
+  )
+
+  logStep('Findings')
+  if (scan.findings.length === 0) {
+    logInfo('No credential-shaped value in the shipped tree.')
+  } else {
+    logError(plural(scan.findings.length, 'value'))
+    for (const finding of scan.findings) {
+      logWarn(
+        `${finding.file}:${finding.line}:${finding.column}  ${finding.label}  ${finding.preview}`,
+      )
+    }
+  }
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        files: scan.files,
+        skipped: scan.skipped,
+        listed: scan.listed,
+        findings: scan.findings,
+      })}\n`,
+    )
+  }
+
+  return scan.findings.length === 0 ? 0 : 2
+}

package/src/deps/audit.ts

@@ -0,0 +1,153 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { execa } from 'execa'
+
+/**
+ * The severities the advisory index publishes, worst first.
+ *
+ * `info` is this module's own floor rather than one of theirs. An advisory
+ * arriving under a severity nothing here recognizes still exists, and dropping
+ * it would shrink the count on the day the vocabulary changed.
+ */
+export const SEVERITIES = [
+  'critical',
+  'high',
+  'moderate',
+  'low',
+  'info',
+] as const
+
+export type Severity = (typeof SEVERITIES)[number]
+
+export interface Advisory {
+  readonly package: string
+  readonly id: number
+  readonly title: string
+  readonly url: string
+  readonly severity: Severity
+  readonly vulnerableVersions?: string
+}
+
+/**
+ * Why no advisory list was produced, which is never the same as a clean one.
+ *
+ * `no-lockfile` is split out from `no-record` because the two take different
+ * remedies. An unreachable index is retried, and a project whose dependencies
+ * were never resolved is installed first, so one message naming the network
+ * would send half the readers at the wrong cause.
+ */
+export type AuditRefusal = 'no-manifest' | 'no-lockfile' | 'no-record'
+
+/** The lockfiles a resolved dependency set leaves behind, in any manager. */
+const LOCKFILES = [
+  'bun.lock',
+  'bun.lockb',
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+]
+
+export type DepsAudit =
+  | { readonly kind: 'audited'; readonly advisories: readonly Advisory[] }
+  | {
+      readonly kind: 'refused'
+      readonly reason: AuditRefusal
+      readonly message?: string
+    }
+
+function severityOf(value: unknown): Severity {
+  return SEVERITIES.includes(value as Severity) ? (value as Severity) : 'info'
+}
+
+/**
+ * Reads the record `bun audit --json` writes to stdout.
+ *
+ * The shape is an object keyed by package name, each holding that package's
+ * advisories, which this flattens into one list carrying the name on every
+ * entry. Returning nothing on unreadable output is what keeps an unreachable
+ * index from reporting as a clean tree, and the caller turns it into a stated
+ * refusal rather than a zero.
+ */
+export function parseAdvisories(stdout: string): Advisory[] | undefined {
+  let record: unknown
+  try {
+    record = JSON.parse(stdout)
+  } catch {
+    return undefined
+  }
+
+  if (typeof record !== 'object' || record === null || Array.isArray(record)) {
+    return undefined
+  }
+
+  const advisories: Advisory[] = []
+  for (const [name, entries] of Object.entries(record)) {
+    if (!Array.isArray(entries)) return undefined
+
+    for (const raw of entries) {
+      if (typeof raw !== 'object' || raw === null) return undefined
+      const entry = raw as Record<string, unknown>
+
+      advisories.push({
+        package: name,
+        id: typeof entry.id === 'number' ? entry.id : 0,
+        title: typeof entry.title === 'string' ? entry.title : '',
+        url: typeof entry.url === 'string' ? entry.url : '',
+        severity: severityOf(entry.severity),
+        ...(typeof entry.vulnerable_versions === 'string' && {
+          vulnerableVersions: entry.vulnerable_versions,
+        }),
+      })
+    }
+  }
+
+  return advisories
+}
+
+export function countBySeverity(
+  advisories: readonly Advisory[],
+): Record<Severity, number> {
+  const counts = Object.fromEntries(
+    SEVERITIES.map((severity) => [severity, 0]),
+  ) as Record<Severity, number>
+
+  for (const advisory of advisories) counts[advisory.severity] += 1
+  return counts
+}
+
+/**
+ * Shells the runtime's own advisory command rather than carrying an index.
+ *
+ * A vendored advisory database is a second corpus to keep current, and what
+ * this check is worth is the report rather than the data. The cost is the one
+ * failure mode no other audit here carries: the command reaches a network, so
+ * an unreachable index has to be told from a tree with nothing against it.
+ * That split is the return value, and the exit code is deliberately not read.
+ * `bun audit` exits non-zero on advisories found and on a lookup that failed,
+ * so the record on stdout is the only thing that separates them.
+ */
+export async function auditDependencies(root: string): Promise<DepsAudit> {
+  if (!existsSync(join(root, 'package.json'))) {
+    return { kind: 'refused', reason: 'no-manifest' }
+  }
+
+  if (!LOCKFILES.some((name) => existsSync(join(root, name)))) {
+    return { kind: 'refused', reason: 'no-lockfile' }
+  }
+
+  const result = await execa('bun', ['audit', '--json'], {
+    cwd: root,
+    reject: false,
+  })
+
+  const advisories = parseAdvisories(result.stdout)
+  if (advisories === undefined) {
+    return {
+      kind: 'refused',
+      reason: 'no-record',
+      message: result.stderr.trim().split('\n').pop() ?? 'no output on stdout',
+    }
+  }
+
+  return { kind: 'audited', advisories }
+}

package/src/secrets/marker.ts

@@ -0,0 +1,44 @@
+/**
+ * The inline token exempting one line from the secret scan.
+ *
+ * Shaped on the `stub: true` precedent in `src/seed-marker.ts`, which answers
+ * a check whose own comment records a false-positive class. The exemption
+ * travels with the line it exempts rather than sitting in a path list away
+ * from it, so a reader meeting a muted match finds the reason on the spot.
+ *
+ * The set of files carrying one is empty today. What empties it is the keying
+ * rather than this mechanism: `patterns.ts` matches issued values and never
+ * the words around them, so nothing in the shipped tree matches on purpose.
+ * A path allow-list was declined for the same reason, since the noise it would
+ * target is word-keyed and spread past the fixture trees, so it would hide
+ * part of the noise and none of the risk.
+ */
+export const SECRET_MARKER = 'aitk-allow-secret'
+
+/**
+ * Only a marker naming a reason counts.
+ *
+ * A bare token is read as a line that meant to say something and did not,
+ * which is the rule `isStubSeed` already applies to a field set to anything
+ * but `true`. Honoring it would let a typo mute a finding, and the reason is
+ * the whole value of an exemption a later reader has to weigh.
+ */
+const MARKER_LINE = new RegExp(`${SECRET_MARKER}:[ \\t]*\\S`)
+
+/**
+ * Whether the line at `index` is exempt, reading itself and the line above it.
+ *
+ * Two lines rather than one, because a credential-shaped literal is as often
+ * introduced by a preceding comment as annotated inline, and a format that
+ * takes no trailing comment at all has nowhere else to put the marker. Nothing
+ * further up counts, so a marker cannot silence a block it does not sit on.
+ */
+export function isExempt(lines: readonly string[], index: number): boolean {
+  const own = lines[index]
+  const above = index > 0 ? lines[index - 1] : undefined
+
+  return (
+    (own !== undefined && MARKER_LINE.test(own)) ||
+    (above !== undefined && MARKER_LINE.test(above))
+  )
+}

package/src/secrets/patterns.ts

@@ -0,0 +1,142 @@
+/**
+ * The rule set the secret scan keys on.
+ *
+ * Every pattern matches an issued value and none of them matches a word. That
+ * split is what lets the exclusion set start empty: a scan keyed on `password`,
+ * `secret`, or `token` fires on the environment reads, the workflow inputs, and
+ * the prose that name those things, and this repository ships all three. The
+ * cost is a credential no issuer stamps with a recognizable prefix, which this
+ * set does not reach and no exclusion would have helped with either.
+ *
+ * None of these sources matches itself, so this file is in scope like any
+ * other. Each literal prefix is followed here by a character class rather than
+ * by the class's own members, and `src/secrets/scan.test.ts` holds the check.
+ */
+export interface SecretPattern {
+  readonly id: string
+  readonly label: string
+  /** Carries the global flag, since a line may hold more than one value. */
+  readonly match: RegExp
+  /**
+   * Whether the matched text is the credential itself.
+   *
+   * A private key header names a block without carrying its bytes, so echoing
+   * it whole tells the reader what was found. Every other pattern matches the
+   * value, and reporting one in full would copy a live credential into a log.
+   */
+  readonly redact: boolean
+}
+
+export const PATTERNS: readonly SecretPattern[] = [
+  {
+    id: 'aws-access-key-id',
+    label: 'AWS access key id',
+    match: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+    redact: true,
+  },
+  {
+    id: 'github-token',
+    label: 'GitHub token',
+    // Spelled as alternation rather than a character class, so the source
+    // carries the issued prefixes as themselves. A class reads as one
+    // pronounceable token to a spell checker and puts a nonsense word in a
+    // dictionary that is supposed to hold real terms.
+    match: /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36,}\b/g,
+    redact: true,
+  },
+  {
+    id: 'github-fine-grained-token',
+    label: 'GitHub fine-grained token',
+    match: /\bgithub_pat_[A-Za-z0-9_]{50,}\b/g,
+    redact: true,
+  },
+  {
+    id: 'google-api-key',
+    label: 'Google API key',
+    match: /\bAIza[0-9A-Za-z_-]{35}\b/g,
+    redact: true,
+  },
+  {
+    id: 'slack-token',
+    label: 'Slack token',
+    match: /\b(?:xoxa|xoxb|xoxp|xoxr|xoxs)-[0-9A-Za-z-]{12,}\b/g,
+    redact: true,
+  },
+  {
+    id: 'slack-webhook',
+    label: 'Slack webhook',
+    match: /https:\/\/hooks\.slack\.com\/services\/T[0-9A-Za-z_/-]{20,}/g,
+    redact: true,
+  },
+  {
+    id: 'stripe-secret-key',
+    label: 'Stripe live key',
+    match: /\b(?:sk|rk)_live_[0-9A-Za-z]{20,}\b/g,
+    redact: true,
+  },
+  {
+    id: 'anthropic-api-key',
+    label: 'Anthropic API key',
+    match: /\bsk-ant-[0-9A-Za-z_-]{24,}\b/g,
+    redact: true,
+  },
+  {
+    id: 'openai-api-key',
+    label: 'OpenAI project key',
+    match: /\bsk-proj-[0-9A-Za-z_-]{24,}\b/g,
+    redact: true,
+  },
+  {
+    id: 'npm-token',
+    label: 'npm token',
+    match: /\bnpm_[0-9A-Za-z]{36}\b/g,
+    redact: true,
+  },
+  {
+    id: 'private-key-block',
+    label: 'Private key block',
+    match: /-----BEGIN(?: [A-Z0-9]+)* PRIVATE KEY-----/g,
+    redact: false,
+  },
+]
+
+export interface PatternHit {
+  readonly pattern: string
+  readonly label: string
+  /** One-based, so the report reads like every other file reference here. */
+  readonly column: number
+  /** What the report prints, redacted unless the pattern says otherwise. */
+  readonly preview: string
+}
+
+/**
+ * Shortens a matched value to its two ends.
+ *
+ * The ends are what a reader needs to find the credential in the file and to
+ * tell one match from another, and the middle is the part no report should
+ * carry. A value too short to have a middle is reported as its shape alone.
+ */
+function redact(value: string): string {
+  if (value.length <= 8) return '…'
+  return `${value.slice(0, 4)}…${value.slice(-4)}`
+}
+
+/** Every value on one line, ordered by where each starts. */
+export function matchLine(line: string): PatternHit[] {
+  const hits: PatternHit[] = []
+
+  for (const pattern of PATTERNS) {
+    for (const found of line.matchAll(pattern.match)) {
+      if (found.index === undefined) continue
+
+      hits.push({
+        pattern: pattern.id,
+        label: pattern.label,
+        column: found.index + 1,
+        preview: pattern.redact ? redact(found[0]) : found[0],
+      })
+    }
+  }
+
+  return hits.sort((left, right) => left.column - right.column)
+}