ai-install-guard 0.1.0 → 0.2.0

package/hooks/scan/checks/structure.ts

@@ -20,6 +20,7 @@ export function structureChecks(ctx: ScanContext, validator: ValidatorReport | u
     linksCheck(ctx),
     imagesCheck(ctx),
     settingsCheck(ctx),
+    filledInCheck(ctx),
   ]
 }
 
@@ -355,3 +356,94 @@ function settingsCheck(ctx: ScanContext): CheckResult {
 }
 
 export type { InventoryFile }
+
+/**
+ * Files whose real content is not in the folder: Git LFS pointers, whose file
+ * is downloaded at install, and paths a git filter rewrites on checkout. The
+ * scan reads what is stored, so the code that runs could be anything.
+ */
+function filledInCheck(ctx: ScanContext): CheckResult {
+  const evidence: Evidence[] = []
+  for (const file of ctx.files) {
+    const name = basename(file.path)
+    if (name === '.gitattributes') {
+      // A line covers the files its pattern names under its own folder:
+      // rewriting only tests or docs is noted, live code is a warning.
+      const folder = dirname(file.path)
+      const lines = (ctx.text(file.path) ?? '').split('\n')
+      for (let index = 0; index < lines.length && index < 1000; index += 1) {
+        const line = (lines[index] as string).trim()
+        if (line.startsWith('#') || line.startsWith('[attr]')) continue
+        const driver = /(?:^|\s)filter=([^\s]{1,100})/.exec(line)?.[1]
+        if (driver === undefined) continue
+        const pattern = line.split(/\s/)[0] as string
+        const coversLive = ctx.files.some(other => {
+          const rel = folder === '' ? other.path : other.path.startsWith(`${folder}/`) ? other.path.slice(folder.length + 1) : undefined
+          return rel !== undefined && attributeMatches(pattern, rel) && isLive(ctx.roleOf(other.path))
+        })
+        evidence.push({ file: file.path, line: index + 1, excerpt: `git rewrites these files with the "${driver}" filter on checkout: ${line.slice(0, 200)}`, status: coversLive ? 'warn' : 'info' })
+      }
+      continue
+    }
+    if (file.size > 1024) continue
+    const text = ctx.text(file.path)
+    if (text === undefined || !text.startsWith('version https://git-lfs.github.com/spec/')) continue
+    evidence.push({
+      file: file.path,
+      excerpt: 'a Git LFS pointer: the real file is downloaded when it is installed, and this scan could not read it',
+      // Images and docs often live in LFS; code that runs must not.
+      status: isLive(ctx.roleOf(file.path)) ? 'fail' : 'info',
+    })
+    if (evidence.length >= 20) break
+  }
+  return row(
+    {
+      id: 'structure.fetched',
+      group: GROUP,
+      title: 'Files filled in at install',
+      advice: 'The scan reads what the repository stores. A file that Git LFS downloads or a filter rewrites at install can hold different code, which was not checked.',
+    },
+    evidence,
+  )
+}
+
+/**
+ * Whether a .gitattributes pattern names `path` (relative to the attributes
+ * file's folder): no slash matches the name at any depth, a slash anchors it,
+ * `*` and `?` stay within a folder and `**` crosses them. A pattern too
+ * elaborate to match cheaply counts as matching, which can only warn more.
+ */
+export function attributeMatches(pattern: string, path: string): boolean {
+  if (pattern.endsWith('/')) return false
+  if (pattern.length > 200 || path.length > 1000 || (pattern.match(/[*?[]/g) ?? []).length > 8) return true
+  const anchored = pattern.includes('/')
+  const body = pattern.startsWith('/') ? pattern.slice(1) : pattern
+  let source = ''
+  for (let index = 0; index < body.length; index += 1) {
+    const char = body[index] as string
+    if (char === '*' && body[index + 1] === '*') {
+      if (body[index + 2] === '/') {
+        source += '(?:.*/)?'
+        index += 2
+      } else {
+        source += '.*'
+        index += 1
+      }
+    } else if (char === '*') {
+      source += '[^/]*'
+    } else if (char === '?') {
+      source += '[^/]'
+    } else if (char === '[' && body.indexOf(']', index + 2) !== -1) {
+      const end = body.indexOf(']', index + 2)
+      source += `[${body.slice(index + 1, end).replace(/^!/, '^').replace(/[\\\]]/g, '\\$&')}]`
+      index = end
+    } else {
+      source += char.replace(/[.+^${}()|\\[\]]/g, '\\$&')
+    }
+  }
+  try {
+    return new RegExp(`^${source}$`).test(anchored ? path : basename(path))
+  } catch {
+    return true
+  }
+}

package/hooks/scan/checks/types.ts

@@ -50,6 +50,11 @@ export type CheckResult = {
   severity: Severity
   evidence: Evidence[]
   advice: string
+  /**
+   * What the evidence means, in plain words for a person: a headline, then a
+   * few lines. Shown before the evidence, which stays one step further in.
+   */
+  summary?: string[]
 }
 
 const RANK: Record<Status, number> = { info: 0, pass: 1, warn: 2, fail: 3 }
@@ -67,19 +72,30 @@ export function severityFor(status: Status): Severity {
   return status === 'fail' ? 'high' : status === 'warn' ? 'medium' : 'none'
 }
 
+/**
+ * At most `max` pieces of evidence, the worst first, and a line counting the
+ * rest. Every piece is judged before capping, so a late failure still counts.
+ */
+export function capEvidence(evidence: Evidence[], max: number, fallback: Status = 'warn'): Evidence[] {
+  if (evidence.length <= max) return evidence
+  const worstFirst = [...evidence].sort((a, b) => RANK[b.status ?? fallback] - RANK[a.status ?? fallback])
+  return [...worstFirst.slice(0, max), { file: '-', excerpt: `and ${evidence.length - max} more`, status: 'info' }]
+}
+
 /**
  * Builds a check's row from its evidence: the row takes the worst status any
  * piece of evidence carries (`fallback` when none does), and `pass` when
  * there is no evidence at all.
  */
 export function row(
-  base: { id: string; group: GroupId; title: string; advice: string },
+  base: { id: string; group: GroupId; title: string; advice: string; summary?: string[] },
   evidence: Evidence[],
   fallback: Status = 'warn',
   severity?: Severity,
 ): CheckResult {
   if (evidence.length === 0) {
-    return { ...base, status: 'pass', severity: 'none', evidence: [] }
+    const { summary: _unused, ...rest } = base
+    return { ...rest, status: 'pass', severity: 'none', evidence: [] }
   }
   const status = evidence.reduce<Status>((acc, item) => worse(acc, item.status ?? fallback), 'info')
   const worstFirst = [...evidence]

package/hooks/scan/checks/validator.ts

@@ -31,7 +31,7 @@ export async function runValidator(host: Host, root: string): Promise<ValidatorR
     const reason = result.stderr.trim().split('\n')[0] ?? ''
     return { ran: false, reason: reason === '' ? `exit code ${result.exitCode}` : reason.slice(0, 200) }
   }
-  const report = parseValidatorReport(parsed.value)
+  const report = relativeTo(root, parseValidatorReport(parsed.value))
   if (report.ran && parsed.value.success === false && report.errors.length === 0) {
     report.errors.push({ file: '-', message: `claude plugin validate failed (exit code ${result.exitCode})` })
   }
@@ -95,3 +95,17 @@ function splitList(text: string): string[] {
   if (current.trim() !== '') out.push(current.trim())
   return out
 }
+
+/**
+ * The report with the scanned folder's own path taken out of file names and
+ * messages: a remote scan's folder is a temporary one, and every other place
+ * in the report is relative to the candidate.
+ */
+function relativeTo(root: string, report: ValidatorReport): ValidatorReport {
+  if (!report.ran) return report
+  const roots = [root, `/private${root}`].map(path => path.replace(/\/+$/, ''))
+  const strip = (text: string): string =>
+    roots.reduce((out, path) => out.split(`${path}/`).join('').split(path).join('.'), text)
+  const fix = (item: ValidatorProblem): ValidatorProblem => ({ file: strip(item.file), message: strip(item.message) })
+  return { ...report, errors: report.errors.map(fix), warnings: report.warnings.map(fix) }
+}

package/hooks/scan/github.ts

@@ -0,0 +1,219 @@
+// What GitHub says about a repository the guard fetched from it: how old it
+// and its owner are, how many people work on it, and whether the scanned
+// commit is signed and part of the repository's own history. GitHub is the
+// host the code came from, so asking it reveals nothing new. Every answer is
+// information only, except a brand-new repository or account, and a commit
+// that is not on the default branch, which are warnings. A failed lookup is
+// noted and never fails the scan.
+
+import { row, type CheckResult, type Evidence, type Status } from './checks/types'
+import type { FetchResult, Host } from './host'
+import type { PinnedSource } from './remote'
+import { safeLine } from './safe-text'
+
+const API = 'https://api.github.com'
+const HEADERS = { Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': 'ai-install-guard' }
+const DAY = 24 * 60 * 60 * 1000
+/** Younger than this, a repository or an account is worth a warning. */
+const NEW_DAYS = 30
+
+type Json = Record<string, unknown>
+
+class LookupError extends Error {}
+
+function isJson(value: unknown): value is Json {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** owner/repo for a github.com source, or undefined for any other host. */
+export function githubRepo(url: string): { owner: string; repo: string } | undefined {
+  const match = /^https:\/\/github\.com\/([A-Za-z0-9-]{1,39})\/([A-Za-z0-9._-]{1,100}?)(?:\.git)?$/.exec(url)
+  return match === null ? undefined : { owner: match[1] as string, repo: match[2] as string }
+}
+
+async function api(host: Host, path: string): Promise<{ status: number; body: unknown; headers: Record<string, string> }> {
+  if (host.fetch === undefined) throw new LookupError('no network here')
+  let answer: FetchResult
+  try {
+    answer = await host.fetch(`${API}${path}`, { headers: HEADERS })
+  } catch (error) {
+    throw new LookupError(`could not reach GitHub: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if ((answer.status === 403 || answer.status === 429) && (answer.headers['x-ratelimit-remaining'] === '0' || answer.status === 429)) {
+    throw new LookupError("GitHub's limit for lookups without an account was reached; try again within the hour")
+  }
+  let body: unknown
+  try {
+    body = JSON.parse(answer.text)
+  } catch {
+    body = undefined
+  }
+  return { status: answer.status, body, headers: answer.headers }
+}
+
+function age(iso: unknown, now: number): number | undefined {
+  if (typeof iso !== 'string') return undefined
+  const time = Date.parse(iso)
+  return Number.isNaN(time) ? undefined : Math.max(0, Math.floor((now - time) / DAY))
+}
+
+function spoken(days: number): string {
+  if (days < 1) return 'today'
+  if (days < 60) return `${days} day${days === 1 ? '' : 's'} ago`
+  if (days < 730) return `${Math.round(days / 30)} months ago`
+  return `${Math.round(days / 365)} years ago`
+}
+
+function count(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined
+}
+
+/** How many contributors, from the last page number of a one-per-page listing. */
+async function contributors(host: Host, path: string): Promise<number | undefined> {
+  const answer = await api(host, `${path}/contributors?per_page=1&anon=1`)
+  if (answer.status === 204) return 0
+  if (answer.status !== 200) return undefined
+  const last = /[?&]page=(\d+)>;\s*rel="last"/.exec(answer.headers.link ?? '')
+  if (last !== null) return Number(last[1])
+  return Array.isArray(answer.body) ? answer.body.length : undefined
+}
+
+export async function githubProvenance(host: Host, source: PinnedSource, now = Date.now()): Promise<CheckResult[]> {
+  const repo = githubRepo(source.url)
+  if (repo === undefined || host.fetch === undefined) return []
+  const path = `/repos/${repo.owner}/${repo.repo}`
+  try {
+    return await lookups(host, path, source, now)
+  } catch (error) {
+    const reason = error instanceof LookupError ? error.message : `the lookup failed: ${error instanceof Error ? error.message : String(error)}`
+    return [
+      {
+        id: 'provenance.repository',
+        group: 'provenance',
+        title: 'Repository and its owner',
+        status: 'info',
+        severity: 'none',
+        evidence: [{ file: '-', excerpt: `not checked: ${safeLine(reason)}`, status: 'info' }],
+        advice: "The repository's history could not be read, so the verdict rests on the code alone.",
+        summary: [`Not checked: ${safeLine(reason)}`],
+      },
+    ]
+  }
+}
+
+async function lookups(host: Host, path: string, source: PinnedSource, now: number): Promise<CheckResult[]> {
+  const repoAnswer = await api(host, path)
+  if (repoAnswer.status === 404) throw new LookupError('GitHub does not show this repository')
+  if (repoAnswer.status !== 200 || !isJson(repoAnswer.body)) throw new LookupError(`GitHub answered ${repoAnswer.status}`)
+  const info = repoAnswer.body
+  const owner = isJson(info.owner) ? info.owner : {}
+  const login = typeof owner.login === 'string' ? owner.login : undefined
+  // After the repository itself, a request that fails is noted where it
+  // belongs and the rest still count: a late failure never hides a warning.
+  const notChecked: string[] = []
+  const attempt = async <T>(what: string, run: () => Promise<T>): Promise<T | undefined> => {
+    try {
+      return await run()
+    } catch (error) {
+      notChecked.push(`${what}: ${error instanceof LookupError ? error.message : error instanceof Error ? error.message : String(error)}`)
+      return undefined
+    }
+  }
+  const ownerAnswer = login === undefined ? undefined : await attempt('its owner', () => api(host, `/users/${encodeURIComponent(login)}`))
+  const ownerInfo = ownerAnswer !== undefined && ownerAnswer.status === 200 && isJson(ownerAnswer.body) ? ownerAnswer.body : {}
+  const people = await attempt('its contributors', () => contributors(host, path))
+
+  const repoDays = age(info.created_at, now)
+  const ownerDays = age(ownerInfo.created_at, now)
+  const pushedDays = age(info.pushed_at, now)
+  const stars = count(info.stargazers_count)
+  const forks = count(info.forks_count)
+  const who = `${typeof owner.type === 'string' && owner.type === 'Organization' ? 'organization' : 'account'} ${safeLine(login ?? 'unknown')}`
+
+  // The warning signs: an account made days ago, or a new repository with a
+  // single author that hardly anyone uses. A new repository from an
+  // established account, with others working on it, is only noted.
+  const newAccount = ownerDays !== undefined && ownerDays < NEW_DAYS
+  // Only facts GitHub gave count: a count it did not give is not taken as low.
+  const loneNewRepo = repoDays !== undefined && repoDays < NEW_DAYS && people !== undefined && people <= 1 && stars !== undefined && stars < 10
+  const evidence: Evidence[] = []
+  const note = (excerpt: string, status: Status = 'info') => evidence.push({ file: '-', excerpt, status })
+  if (repoDays !== undefined) note(`created ${spoken(repoDays)}${loneNewRepo ? ', with a single contributor and few stars' : ''}`, loneNewRepo ? 'warn' : 'info')
+  if (ownerDays !== undefined) note(`owned by the ${who}, created ${spoken(ownerDays)}`, newAccount ? 'warn' : 'info')
+  note(`${stars ?? '?'} stars, ${forks ?? '?'} forks, ${people ?? '?'} contributor${people === 1 ? '' : 's'}`)
+  if (pushedDays !== undefined) note(`last pushed ${spoken(pushedDays)}`)
+  if (info.archived === true) note('archived: it gets no more fixes')
+  for (const what of notChecked) note(`not checked, ${safeLine(what)}`)
+  if (info.fork === true) {
+    const parent = isJson(info.parent) && typeof info.parent.full_name === 'string' ? safeLine(info.parent.full_name) : 'another repository'
+    note(`a fork of ${parent}: compare it with the original`)
+  }
+
+  const young = [
+    loneNewRepo && repoDays !== undefined ? `the repository is ${spoken(repoDays).replace(' ago', ' old')}, with one contributor and few stars` : '',
+    newAccount && ownerDays !== undefined ? `its owner's account is ${spoken(ownerDays).replace(' ago', ' old')}` : '',
+  ].filter(text => text !== '')
+  const summary = [
+    young.length > 0
+      ? `New: ${young.join(' and ')}`
+      : `${repoDays === undefined ? 'A repository' : `Created ${spoken(repoDays)}`} by the ${who}${ownerDays === undefined ? '' : ` (on GitHub since ${spoken(ownerDays)})`}`,
+    `${stars ?? '?'} stars, ${forks ?? '?'} forks, ${people ?? '?'} contributor${people === 1 ? '' : 's'}${pushedDays === undefined ? '' : `; last pushed ${spoken(pushedDays)}`}`,
+  ]
+  // A part that could not be read is said in the summary too, not only below it.
+  if (notChecked.length > 0) summary.push(`Not checked: ${notChecked.map(safeLine).join('; ')}`)
+  const repository = row(
+    {
+      id: 'provenance.repository',
+      group: 'provenance',
+      title: 'Repository and its owner',
+      advice: 'A brand-new repository or account has no track record. Most are honest, but most malicious plugins are new too: look closer before you trust one.',
+      summary,
+    },
+    evidence,
+    'info',
+  )
+
+  // The scanned commit: signed, and part of the repository's own history.
+  const commitEvidence: Evidence[] = []
+  const commitTried = await attempt('the commit', () => api(host, `${path}/commits/${source.sha}`))
+  const commit = commitTried ?? { status: 0, body: undefined, headers: {} }
+  if (commitTried === undefined) {
+    commitEvidence.push({ file: '-', excerpt: `not checked: ${safeLine(notChecked.at(-1) ?? 'the request failed')}`, status: 'info' })
+  } else if (commit.status === 200 && isJson(commit.body) && isJson(commit.body.commit)) {
+    const verification = isJson(commit.body.commit.verification) ? commit.body.commit.verification : {}
+    const committer = isJson(commit.body.commit.committer) ? commit.body.commit.committer : {}
+    const committedDays = age(committer.date, now)
+    commitEvidence.push({
+      file: '-',
+      excerpt: verification.verified === true ? 'signed, and GitHub verified the signature' : 'not signed, or the signature could not be verified',
+      status: 'info',
+    })
+    if (committedDays !== undefined) commitEvidence.push({ file: '-', excerpt: `committed ${spoken(committedDays)}`, status: 'info' })
+  } else if (commit.status === 404 || commit.status === 422) {
+    commitEvidence.push({ file: '-', excerpt: 'GitHub does not show this commit in this repository', status: 'warn' })
+  } else if (commitTried !== undefined) {
+    commitEvidence.push({ file: '-', excerpt: `not checked: GitHub answered ${commit.status}`, status: 'info' })
+  }
+  // A commit named by id could come from a fork in the same network (an
+  // "impostor commit"); one reached through a branch or tag cannot.
+  const defaultBranch = typeof info.default_branch === 'string' ? info.default_branch : undefined
+  if (source.refKind === 'commit' && defaultBranch !== undefined && commit.status === 200) {
+    const compared = (await attempt('the default branch', () => api(host, `${path}/compare/${encodeURIComponent(defaultBranch)}...${source.sha}`))) ?? { status: 0, body: undefined, headers: {} }
+    const status = isJson(compared.body) && typeof compared.body.status === 'string' ? compared.body.status : undefined
+    if (status === 'behind' || status === 'identical') commitEvidence.push({ file: '-', excerpt: `part of the default branch ${safeLine(defaultBranch)}`, status: 'info' })
+    else if (status !== undefined) commitEvidence.push({ file: '-', excerpt: `not on the default branch ${safeLine(defaultBranch)}: it may come from another branch or from a fork`, status: 'warn' })
+    else commitEvidence.push({ file: '-', excerpt: `whether it is on the default branch was not checked: ${compared.status === 0 ? safeLine(notChecked.at(-1) ?? 'the request failed') : `GitHub answered ${compared.status}`}`, status: 'info' })
+  }
+  const commitRow = row(
+    {
+      id: 'provenance.commit',
+      group: 'provenance',
+      title: 'The scanned commit',
+      advice: "A commit named by its id can come from any fork of the repository, since GitHub serves them all from one place. Prefer one on the default branch or behind a release tag.",
+      summary: commitEvidence.length > 0 ? [commitEvidence.map(item => item.excerpt).join('; ').replace(/^./, char => char.toUpperCase())] : undefined,
+    },
+    commitEvidence,
+    'info',
+  )
+  return [repository, commitRow]
+}

package/hooks/scan/host.ts

@@ -32,7 +32,20 @@ export type RunOptions = {
   env?: Record<string, string>
 }
 
+/** An HTTP answer, the body read as text. */
+export type FetchResult = {
+  status: number
+  ok: boolean
+  /** Lower-cased names. */
+  headers: Record<string, string>
+  text: string
+}
+
+export type FetchInit = { method?: string; headers?: Record<string, string>; body?: string }
+
 export type Host = {
+  /** HTTPS requests, for repository metadata and the lookups you turn on. Absent where there is no network. */
+  fetch?: (url: string, init?: FetchInit) => Promise<FetchResult>
   list: (path: string) => Promise<HostEntry[]>
   stat: (path: string, options?: { resolve: boolean }) => Promise<HostStat>
   readBytes: (path: string) => Promise<Uint8Array>