@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.50

package/server-managed/repository-risk-assess.ts

@@ -0,0 +1,105 @@
+// A package's risk line, as a repository risk scan tells it
+// (repository-risk.ts): its version's document read and assessed, as risk
+// tells one npm removed where npm has none; and how a failure is told.
+import { setTimeout as delay } from 'node:timers/promises'
+import { NpmRiskError, SEVERITIES, type Severity } from '../risk/index.js'
+import { GithubApiError } from './github-errors.ts'
+import { NpmPackageError, type NpmVersionDocument } from './npm-packages.ts'
+import type { RepositoryRiskLine } from './repository-risk.ts'
+
+// An assessment refused as busy (`npm-busy`, by npm-risk.ts or the npm reads
+// beneath it), or that npm asked to ask later (risk's `upstream-busy`, as its
+// downloads API answers past a burst of requests), is asked again after a
+// wait, up to this many times.
+export const BUSY_RETRIES = 20
+export const BUSY_WAIT_MS = 1000
+
+// How long a package's risk line, or a lockfile's advisories, is told as it
+// is: after it, a risk line is told stale and assessed again, as risk tells
+// again what of a package changes in time, and advisories asked again, as npm
+// publishes them (repository-risk.ts).
+export const RISK_KEPT_MS = 60 * 60_000
+
+// The most severe of `findings`, or null for none.
+export function highestSeverity(findings: readonly { severity: Severity }[]): Severity | null {
+  return SEVERITIES.find(severity => findings.some(finding => finding.severity === severity)) ?? null
+}
+
+// Why a step failed, as a line says it: an error's code, and for a lockfile
+// refused, what of it its reader refused.
+export type RiskFailure = { error: string; detail?: string }
+type RiskLine = Extract<RepositoryRiskLine, { type: 'risk' }>
+
+// What an error is known by: a GitHub or npm failure's code, or `failed`;
+// GitHub not reached with what failed (githubUnreachable), while `doing` what
+// of a repository, and risk's with what it asked of npm and how that failed,
+// where they say.
+export function failureOf(error: unknown, doing?: string): RiskFailure {
+  if (error instanceof GithubApiError && error.detail) return { error: error.message, detail: doing ? `${doing}: ${error.detail}` : error.detail }
+  if (error instanceof GithubApiError || error instanceof NpmPackageError) return { error: error.message }
+  if (!(error instanceof NpmRiskError)) return { error: 'failed' }
+  return error.message === error.code ? { error: error.code } : { error: error.code, detail: error.message }
+}
+
+export const isBusy = (error: unknown) => (error instanceof NpmPackageError && error.status === 429) || (error instanceof NpmRiskError && error.code === 'upstream-busy')
+
+// A package to assess: npm's of its name and version, or, with an
+// `integrity`, a mirror's held to it.
+export interface AssessedPackage { name: string; version: string; integrity?: string }
+
+export type Assessment = { published: string | null; findings: { id: string; severity: Severity; takenDown?: unknown }[]; score: { score: number } }
+
+// What of a scan's source assessing a package asks (RepositoryRiskSource).
+export interface AssessingSource {
+  version(name: string, version: string, signal: AbortSignal): Promise<NpmVersionDocument>
+  assess(doc: NpmVersionDocument, teamScoped: boolean, signal: AbortSignal): Promise<Assessment>
+  removed(name: string, version: string, teamScoped: boolean, signal: AbortSignal): Promise<Assessment>
+}
+
+// A package's risk line, its version's document kept and the assessment asked
+// again after a wait while the server is busy; null once the scan stops. A
+// version npm has no document of is told as risk tells one npm removed
+// (removedOf), its malware keeping whether its package was taken down.
+export async function assessPackage(source: AssessingSource, signal: AbortSignal, pkg: AssessedPackage, teamScoped: boolean): Promise<RiskLine | null> {
+  const at = { type: 'risk', ...pkg } as const
+  let doc: NpmVersionDocument | NpmPackageError | undefined
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const read = doc ??= await documentOf(source, pkg, signal)
+      if (!(read instanceof NpmPackageError) && pkg.integrity !== undefined && !pkg.integrity.split(/\s+/u).includes(read.dist.integrity)) return { ...at, error: 'integrity-mismatch' }
+      const { published, findings, score } = read instanceof NpmPackageError ? await removedOf(source, pkg, teamScoped, signal, read) : await assessedOf(source, pkg, teamScoped, signal, read)
+      const told = findings.map(({ id, severity, takenDown }) => ({ id, severity, ...takenDown === true ? { takenDown: true as const } : {} }))
+      return { ...at, published, severity: highestSeverity(told), score: score.score, findings: told }
+    } catch (error) {
+      if (signal.aborted) return null
+      if (!isBusy(error) || attempt >= BUSY_RETRIES) return { ...at, ...failureOf(error) }
+      try { await delay(BUSY_WAIT_MS * Math.min(attempt + 1, 5), undefined, { signal }) } catch { return null }
+    }
+  }
+}
+
+// npm's document of a version, or its answer that it has none (a 404).
+async function documentOf(source: AssessingSource, pkg: AssessedPackage, signal: AbortSignal): Promise<NpmVersionDocument | NpmPackageError> {
+  try { return await source.version(pkg.name, pkg.version, signal) } catch (error) {
+    if (error instanceof NpmPackageError && error.status === 404) return error
+    throw error
+  }
+}
+
+// A version's assessment; where risk finds npm no longer has it, as a document
+// read from where versions' are kept doesn't tell, as one npm removed.
+async function assessedOf(source: AssessingSource, pkg: AssessedPackage, teamScoped: boolean, signal: AbortSignal, doc: NpmVersionDocument): Promise<Assessment> {
+  try { return await source.assess(doc, teamScoped, signal) } catch (error) {
+    if (!(error instanceof NpmRiskError && error.code === 'version-not-found')) throw error
+    return removedOf(source, pkg, teamScoped, signal, new NpmPackageError(404, 'package-not-found'))
+  }
+}
+
+// A version npm has no document of, as risk tells one npm removed, as it
+// removes every one it finds malware in (`removed`): `gone`, npm's answer of
+// none, thrown where nothing tells of it.
+async function removedOf(source: AssessingSource, pkg: AssessedPackage, teamScoped: boolean, signal: AbortSignal, gone: NpmPackageError): Promise<Assessment> {
+  try { return await source.removed(pkg.name, pkg.version, teamScoped, signal) } catch (error) {
+    throw error instanceof NpmRiskError && (error.code === 'version-not-found' || error.code === 'package-not-found') ? gone : error
+  }
+}

package/server-managed/repository-risk-audit.ts

@@ -0,0 +1,79 @@
+// A lockfile's advisories, as a repository risk scan asks them
+// (repository-risk.ts): npm's registry's of its packages of the registry or
+// a mirror, asked at once, as `npm audit` asks, each told with whether it is
+// of malware (risk's npmMalwareAdvisory); kept by the lockfile's blob, in the
+// instance's memory and the source's `audits`, for RISK_KEPT_MS, as npm
+// publishes advisories, or why they couldn't be had for AUDIT_FAILED_KEPT_MS.
+import type { Advisory } from '@preventive/upstream/advisories.js'
+import { isExactVersion } from '@preventive/upstream/semver.js'
+import { npmMalwareAdvisory } from '../risk/index.js'
+import { isNpmPackageName } from '../common/managed/npm-packages.js'
+import type { LockedPackage } from './locked-packages.ts'
+import type { Lru } from './lru.ts'
+import type { KeptStore } from './npm-kept.ts'
+import { RISK_KEPT_MS, type RiskFailure, failureOf } from './repository-risk-assess.ts'
+
+export type AdvisoryRow = Advisory & { malware: boolean }
+// A lockfile's advisories, or why they couldn't be had.
+export type Audit = AdvisoryRow[] | RiskFailure
+
+export interface AuditSource {
+  // npm's registry's advisories of these packages' versions, asked at once.
+  advisories(packages: { name: string; versions: string[] }[], signal: AbortSignal): Promise<Advisory[]>
+  // Where audits are kept beyond this instance, by the lockfile's blob.
+  audits?: KeptStore<Audit>
+}
+
+// How long a lockfile's advisories that couldn't be had are told so, rather
+// than asked again: a scan's next parts don't wait on an audit that failed,
+// as by timing out, again and again.
+const AUDIT_FAILED_KEPT_MS = 10 * 60_000
+
+// Whether an audit kept `at` is told as it is: its advisories within
+// RISK_KEPT_MS, why they couldn't be had within AUDIT_FAILED_KEPT_MS.
+const isFresh = ({ at, audit }: { at: number; audit: Audit }) => Date.now() - at < (Array.isArray(audit) ? RISK_KEPT_MS : AUDIT_FAILED_KEPT_MS)
+
+// The audits of lockfiles, each of its `packages` by its `key` (auditLockfile),
+// `inTurn` with others, asked at once: each null where it has none to ask
+// of, or once `signal` aborts. Each is the caller's to tell once it may.
+export function auditLockfiles(source: AuditSource, memory: Lru<{ at: number; audit: Audit }>, signal: AbortSignal,
+  lockfiles: { key: string; packages: readonly LockedPackage[] | null }[], inTurn: <T>(work: () => Promise<T>) => Promise<T>): Promise<Audit | null>[] {
+  return lockfiles.map(({ key, packages }) => {
+    const audit = packages ? inTurn(() => (signal.aborted ? Promise.resolve(null) : auditLockfile(source, memory, signal, key, packages))) : Promise.resolve(null)
+    // One no longer waited on, as the scan stopped, fails alone.
+    audit.catch(() => {})
+    return audit
+  })
+}
+
+// The audit of a lockfile's `packages`, by its `key` as kept (`memory`, then
+// the source's), else asked and kept; null where it locks none to ask of, or
+// once `signal` aborts.
+export async function auditLockfile(source: AuditSource, memory: Lru<{ at: number; audit: Audit }>, signal: AbortSignal, key: string,
+  packages: readonly LockedPackage[]): Promise<Audit | null> {
+  let kept = memory.get(key)
+  if (!kept || !isFresh(kept)) {
+    const stored = await source.audits?.read(key)
+    kept = stored ? { at: stored.at, audit: stored.value } : undefined
+  }
+  if (kept && isFresh(kept)) { memory.set(key, kept); return kept.audit }
+  const asked = new Map<string, Set<string>>()
+  for (const { name, version, source: from } of packages) {
+    if ((from !== 'registry' && from !== 'mirror') || !isNpmPackageName(name) || !isExactVersion(version)) continue
+    if (!asked.has(name)) asked.set(name, new Set())
+    asked.get(name)!.add(version)
+  }
+  if (asked.size === 0) return null
+  let audit: Audit
+  try {
+    audit = (await source.advisories([...asked].map(([name, versions]) => ({ name, versions: [...versions] })), signal))
+      .map(advisory => ({ ...advisory, malware: npmMalwareAdvisory(advisory) }))
+  } catch (error) {
+    if (signal.aborted) return null
+    audit = failureOf(error)
+  }
+  const now = Date.now()
+  memory.set(key, { at: now, audit })
+  await source.audits?.write(key, audit, now)
+  return audit
+}

package/server-managed/repository-risk-read.ts

@@ -0,0 +1,170 @@
+// A repository as a repository risk scan reads it of GitHub
+// (repository-risk.ts): opened at its default branch's head, its lockfiles
+// of npm's ecosystem listed (findRepoLockfiles), those of its `paths` alone,
+// each read for its packages (@preventive/lockfile), and access to it checked
+// again before they are told (`recheck`); and its Dependabot alerts, open or dismissed, of
+// npm's, where the source asks them (dependabot-alerts.ts), asked meanwhile
+// and never kept, a failure to have them its own, and its GitHub Actions
+// (repository-actions.ts). A listing is kept by the commit it was listed at,
+// its Actions' files too, and a lockfile's packages by its blob: in the
+// instance's memory, and the source's `listings`, `actionFiles` and
+// `lockfiles` for SCAN_READ_KEPT_MS, so that only opening a repository and
+// checking access to it again ask GitHub where all else is kept.
+import type { LockfileFormat, RepoLockfile } from '@preventive/upstream/github.js'
+import type { AlertsRead } from './dependabot-access.ts'
+import type { DependabotAlert } from './dependabot-alerts.ts'
+import { type LockedPackage, isTestFixture, lockedPackages } from './locked-packages.ts'
+import type { Lru } from './lru.ts'
+import type { KeptStore } from './npm-kept.ts'
+import { inTurns } from './queue.ts'
+import { type WorkflowsRead, lastingRead, readActions } from './repository-actions.ts'
+import { type RiskFailure, failureOf } from './repository-risk-assess.ts'
+import type { RepositoryRiskLine, RepositoryRiskRepo } from './repository-risk.ts'
+
+// The formats of npm's ecosystem, as findRepoLockfiles names them, and those
+// of them read here.
+const NPM_LOCKFILE_FORMATS: ReadonlySet<LockfileFormat> = new Set(['npm', 'pnpm', 'yarn', 'bun', 'deno'])
+const READ_FORMATS: ReadonlySet<LockfileFormat> = new Set(['npm', 'pnpm', 'yarn'])
+
+// How long the source's `listings` and `lockfiles` are read for: what
+// GitHub has at a commit or a blob doesn't change, how it is read here may.
+export const SCAN_READ_KEPT_MS = 24 * 60 * 60_000
+// How many of a repository's lockfiles are read at once: each one GitHub is
+// asked for where it isn't kept, then parsed.
+const LOCKFILES_AT_ONCE = 4
+
+export type ListedLockfile = Pick<RepoLockfile, 'path' | 'format' | 'sha'>
+export type LockfileRead = { packages: LockedPackage[] } | RiskFailure
+// A repository's Dependabot alerts, those of its `paths` alone, with access to
+// them to check again before they are told (`recheck`), or why they couldn't
+// be had.
+export type DependabotRead = { alerts: DependabotAlert[]; recheck?(): Promise<void> } | RiskFailure
+type LockfileLine = Extract<RepositoryRiskLine, { type: 'lockfile' }>
+export type RepositoryFailure = Extract<RepositoryRiskLine, { type: 'repo'; error: string }>
+
+// A repository opened at its default branch's head (`commit`): its lockfiles,
+// as findRepoLockfiles lists them, each with its blob's id, and a file's
+// text; `recheck` checks access to it again, throwing where it is gone; and
+// `dependabot`, where asked, its Dependabot alerts of npm's, open or dismissed, as GitHub
+// has them now, with access to them to check again before they are told.
+export interface OpenedRepository {
+  commit: string
+  lockfiles(): Promise<ListedLockfile[]>
+  file(path: string): Promise<string>
+  recheck(): Promise<void>
+  dependabot?(): Promise<AlertsRead>
+  // Its workflows' paths, none where it has none.
+  workflows?(): Promise<string[]>
+}
+
+// What a repository is read with: the scan's source and caches, and its
+// signal.
+export interface RepositoryReading<R extends RepositoryRiskRepo> {
+  source: { open(repo: R): Promise<OpenedRepository>; listings?: KeptStore<ListedLockfile[]>; lockfiles?: KeptStore<LockfileRead>; actionFiles?: KeptStore<WorkflowsRead> }
+  caches: { listings: Lru<ListedLockfile[]>; lockfiles: Lru<LockfileRead>; actionFiles: Lru<WorkflowsRead> }
+  signal: AbortSignal
+}
+
+// A repository read: its commit, its lockfiles' lines, each with its blob's
+// id, its Dependabot alerts where asked, and access to it to check again just
+// before they are told (OpenedRepository `recheck`), as GitHub may have
+// withdrawn it meanwhile.
+export interface RepositoryRead {
+  commit: string
+  lockfiles: { sha: string; line: LockfileLine }[]
+  dependabot: DependabotRead | null
+  // Its Actions' files, where it lists its workflows.
+  actions: WorkflowsRead | null
+  recheck(): Promise<void>
+}
+
+// Whether a lockfile at `path` is of `paths` (RepositoryRiskRepo).
+function lockfileOf(path: string, paths: readonly string[] | undefined) {
+  const dir = path.slice(0, Math.max(path.lastIndexOf('/'), 0))
+  return !paths || paths.some(scope => dir === '' || dir === scope || dir.startsWith(`${scope}/`) || scope.startsWith(`${dir}/`))
+}
+
+// What is kept by `key`: in this instance's memory, else in `store` within
+// SCAN_READ_KEPT_MS, else `read` and kept in both, where it is to be.
+async function keptRead<T>(memory: Lru<T>, store: KeptStore<T> | undefined, key: string, read: () => Promise<T>, keep = (_value: T) => true) {
+  const known = memory.get(key)
+  if (known !== undefined) return known
+  const kept = await store?.read(key)
+  if (kept && Date.now() - kept.at < SCAN_READ_KEPT_MS) { memory.set(key, kept.value); return kept.value }
+  const value = await read()
+  if (!keep(value)) return value
+  memory.set(key, value)
+  await store?.write(key, value, Date.now())
+  return value
+}
+
+// A lockfile's line, its packages or why they couldn't be had: as kept by its
+// blob, else read from GitHub and kept.
+async function readLockfile({ source, caches }: RepositoryReading<RepositoryRiskRepo>, repo: number, opened: OpenedRepository,
+  { path, format, sha }: ListedLockfile): Promise<LockfileLine> {
+  const at = { type: 'lockfile', repo, path, format } as const
+  if (!READ_FORMATS.has(format)) return { ...at, error: 'unsupported-format' }
+  try {
+    return { ...at, ...await keptRead(caches.lockfiles, source.lockfiles, `${format}\0${sha}`, async (): Promise<LockfileRead> => {
+      const text = await opened.file(path)
+      try { return { packages: lockedPackages(format, text) } } catch (error) {
+        return { error: 'lockfile-unreadable', ...error instanceof Error ? { detail: error.message.slice(0, 500) } : {} }
+      }
+    }) }
+  } catch (error) { return { ...at, ...failureOf(error) } }
+}
+
+// A repository opened and its lockfiles of npm's ecosystem listed, as kept
+// for its commit or else from GitHub, those of its `paths` alone; its line
+// telling why where either failed; null where the scan stopped.
+async function listLockfiles<R extends RepositoryRiskRepo>(reading: RepositoryReading<R>, repo: R) {
+  let doing = 'opening it'
+  try {
+    const opened = await reading.source.open(repo)
+    if (reading.signal.aborted) return null
+    doing = 'listing its lockfiles'
+    const listed = await keptRead(reading.caches.listings, reading.source.listings, `${repo.repoId}@${opened.commit}`, () => opened.lockfiles())
+    const lockfiles = listed.filter(({ path, format }) => NPM_LOCKFILE_FORMATS.has(format) && lockfileOf(path, repo.paths))
+    return { opened, lockfiles }
+  } catch (error) {
+    return reading.signal.aborted ? null : { type: 'repo', id: repo.repoId, ...failureOf(error, doing) } as const
+  }
+}
+
+// A repository's Dependabot alerts of its `paths` (RepositoryRiskRepo), as
+// its lockfiles are, or why they couldn't be had; null where they aren't
+// asked.
+async function readDependabot(opened: OpenedRepository, paths: readonly string[] | undefined): Promise<DependabotRead | null> {
+  if (!opened.dependabot) return null
+  try {
+    const { alerts, recheck } = await opened.dependabot()
+    return { alerts: alerts.filter(alert => lockfileOf(alert.manifest, paths)), recheck }
+  } catch (error) {
+    return failureOf(error, 'asking its Dependabot alerts')
+  }
+}
+
+// A repository read: its lockfiles listed and read, a few at once, its
+// Dependabot alerts asked and its Actions read meanwhile; its line telling why where listing
+// failed; null where the scan stopped. A test's
+// fixture or example its reader refuses (isTestFixture) is left out, as a
+// test may keep one so on purpose.
+export async function readRepository<R extends RepositoryRiskRepo>(reading: RepositoryReading<R>, repo: R): Promise<RepositoryRead | RepositoryFailure | null> {
+  const listed = await listLockfiles(reading, repo)
+  if (!listed || 'type' in listed) return listed
+  const alerting = readDependabot(listed.opened, repo.paths)
+  const { opened } = listed, { workflows } = opened
+  const acting = workflows ? keptRead(reading.caches.actionFiles, reading.source.actionFiles, `${repo.repoId}@${opened.commit}`,
+    () => readActions({ workflows, file: path => opened.file(path) }), lastingRead) : Promise.resolve(null)
+  acting.catch(() => {})
+  const inTurn = inTurns(LOCKFILES_AT_ONCE)
+  const lines = await Promise.all(listed.lockfiles.map(lockfile => inTurn(() => (reading.signal.aborted ? Promise.resolve(null) : readLockfile(reading, repo.repoId, opened, lockfile)))))
+  const lockfiles: RepositoryRead['lockfiles'] = []
+  for (const [at, line] of lines.entries()) {
+    if (!line) return null
+    if (!('error' in line && line.error === 'lockfile-unreadable' && isTestFixture(line.path))) lockfiles.push({ sha: listed.lockfiles[at]!.sha, line })
+  }
+  const dependabot = await alerting
+  const actions = await acting
+  return reading.signal.aborted ? null : { commit: listed.opened.commit, lockfiles, dependabot, actions, recheck: () => listed.opened.recheck() }
+}